openapi: 3.1.0
info:
  title: "WeChat Cloud Capability API"
  version: 0.1.0
  description: "Cloud protocol capability API for personal WeChat accounts, media resources, Finder, workers, and object storage entitlements."
servers:
  -
    url: "https://weixin.uaisir.com"
    description: "WeChat cloud capability API root"
security:
  -
    bearerAuth:
[]
paths:
  "/api/capabilities/enterprise-wechat/v1/accounts/{accountId}/chatrooms":
    get:
      summary: "Reserved enterprise WeChat chatrooms query"
      operationId: listEnterpriseWechatChatrooms
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "501":
          description: "Reserved for enterprise WeChat capability surface."
      tags:
        - "Enterprise WeChat Reserved"
      description: "Reserved enterprise WeChat chatrooms query. Reserved enterprise WeChat capability endpoint. It keeps the API Fox and generated-client namespace stable before the independent enterprise WeChat implementation is enabled."
  "/api/capabilities/enterprise-wechat/v1/accounts/{accountId}/contacts":
    get:
      summary: "Reserved enterprise WeChat contacts query"
      operationId: listEnterpriseWechatContacts
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "501":
          description: "Reserved for enterprise WeChat capability surface."
      tags:
        - "Enterprise WeChat Reserved"
      description: "Reserved enterprise WeChat contacts query. Reserved enterprise WeChat capability endpoint. It keeps the API Fox and generated-client namespace stable before the independent enterprise WeChat implementation is enabled."
  "/api/capabilities/enterprise-wechat/v1/accounts/{accountId}/external-contacts":
    get:
      summary: "Reserved enterprise WeChat external contacts query"
      operationId: listEnterpriseWechatExternalContacts
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
        "501":
          description: "Reserved for enterprise WeChat capability surface."
      tags:
        - "Enterprise WeChat Reserved"
      description: "Reserved enterprise WeChat external contacts query. Reserved enterprise WeChat capability endpoint. It keeps the API Fox and generated-client namespace stable before the independent enterprise WeChat implementation is enabled."
  "/api/capabilities/personal-wechat/v1/accounts":
    get:
      summary: "List cloud-mounted WeChat accounts"
      operationId: listPersonalWechatAccounts
      responses:
        "200":
          description: "Account list."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    type: object
                    required:
                      - items
                    additionalProperties: false
                    properties:
                      items:
                        type: array
                        items:
                          "$ref": "#/components/schemas/PersonalWechatAccount"
              examples:
                default:
                  value:
                    data:
                      items:
                        -
                          accountId: wacct_example
                          internalInstanceId: wxinst_example
                          bindSessionId: bind_example
                          cloudKeyId: key_slot_example
                          protocolDeviceType: ipad
                          status: bound
                          online: true
                          nickname: "客服微信一号"
                          avatarUrl: ""
                          updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Accounts"
      description: "List cloud-mounted WeChat accounts. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
    post:
      summary: "Create pending WeChat account record"
      operationId: createPersonalWechatAccount
      responses:
        "200":
          description: "Pending account."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    "$ref": "#/components/schemas/PersonalWechatAccount"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_pending_example
                      displayName: "客服微信一号"
                      status: pending_bind
                      mode: cloud
                      runtime:
                        state: pending_bind
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Accounts"
      description: "Create pending WeChat account record. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/PersonalWechatAccountCreateRequest"
            examples:
              default:
                value:
                  displayName: "客服微信一号"
                  deviceId: macbook-pro-local
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/actions/validate":
    post:
      summary: "Validate an account action before execution"
      operationId: validateAction
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Action validation result."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatActionValidationResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      action: message.send_text
                      targetId: wxid_example
                      allowed: true
                      requiredCapability: action.execute
                      riskLevel: low
                      requiresProposal: false
                      reason: ""
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Tasks"
      description: "Validate an account action before execution. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/PersonalWechatActionValidateRequest"
            examples:
              default:
                value:
                  action: message.send_text
                  targetId: wxid_example
                  reason: manual-send
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/bind-sessions":
    post:
      summary: "Create cloud QR bind session"
      operationId: createBindSession
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Bind session."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatBindSessionResponse"
              examples:
                default:
                  value:
                    data:
                      bindSessionId: bind_example
                      accountId: wacct_example
                      internalInstanceId: wxinst_example
                      hostDeviceId: macbook-pro-local
                      cloudKeyId: key_slot_example
                      wechatKeyId: key_slot_example
                      protocolDeviceType: ipad
                      protocolDeviceProfileVersion: v1
                      allowedProtocolDeviceTypes:
                        - ipad
                      defaultProtocolDeviceType: ipad
                      allowProtocolDeviceSwitch: false
                      seatIndex: 1
                      seatId: seat_example
                      proxyRequired: false
                      proxyBypassed: false
                      proxyLease:
{}
                      entitlement:
{}
                      status: issued
                      lastEvent: created
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Accounts"
      description: "Create cloud QR bind session. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/PersonalWechatBindSessionCreateRequest"
            examples:
              default:
                value:
                  deviceId: macbook-pro-local
                  protocolDeviceType: ipad
                  localAccountCount: 0
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/capabilities":
    get:
      summary: "Get account capability directory"
      operationId: getAccountCapabilities
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Account capability directory."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatCapabilityDirectoryResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      mode: cloud
                      available:
                        - wechat.bind
                        - action.execute
                      unavailable:
[]
                      runtime:
                        status: available
                        health: online
                        workerId: worker-mac-1
                      storage:
                        objectStorageEnabled: true
                        storageAvailableBytes: 1073741824
                        maxFileSizeBytes: 104857600
                      notes:
                        - "公开能力 API 只返回产品层账号和脱敏状态，不返回 WeChat Key、登录态、代理凭证或原始协议响应。"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Accounts"
      description: "Get account capability directory. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/contacts":
    get:
      summary: "List contacts from cloud event cache"
      operationId: listContacts
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/query"
        -
          "$ref": "#/components/parameters/limit"
      responses:
        "200":
          description: "Contact list."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatContactPageResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      source: cloud_event_cache
                      syncRequired: true
                      cursor: 42
                      items:
                        -
                          accountId: wacct_example
                          contactId: wxid_example
                          targetId: wxid_example
                          userName: wxid_example
                          nickname: "张三"
                          remarkName: ""
                          alias: ""
                          avatarUrl: ""
                          latest:
                            previewText: "已脱敏消息预览"
                            messageType: text
                            updatedAt: "2026-07-05T00:00:00.000Z"
                            createdAt: "2026-07-05T00:00:00.000Z"
                          source: cloud_event_cache
                          syncRequired: true
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Contacts"
      description: "List contacts from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/contacts/details":
    post:
      summary: "Create contact details task"
      operationId: createContactDetailsTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Contact details task."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ProtocolGenericTaskResponse"
              examples:
                default:
                  value:
                    data:
                      taskId: contacts_details_example
                      type: contacts_details
                      accountId: wacct_example
                      status: queued
                      params:
                        query: "示例查询"
                        ids:
[]
                        limit: 50
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      completedAt: ""
                      source: cloud_task_queue
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Contacts"
      description: "Create contact details task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ProtocolGenericTaskRequest"
            examples:
              default:
                value:
                  query: "客户昵称"
                  limit: 50
                  reason: manual-sync
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/contacts/search":
    get:
      summary: "Search contacts from cloud event cache"
      operationId: searchContacts
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/query"
        -
          "$ref": "#/components/parameters/limit"
      responses:
        "200":
          description: "Contact search result."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatContactPageResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      source: cloud_event_cache
                      syncRequired: true
                      cursor: 42
                      items:
                        -
                          accountId: wacct_example
                          contactId: wxid_example
                          targetId: wxid_example
                          userName: wxid_example
                          nickname: "张三"
                          remarkName: ""
                          alias: ""
                          avatarUrl: ""
                          latest:
                            previewText: "已脱敏消息预览"
                            messageType: text
                            updatedAt: "2026-07-05T00:00:00.000Z"
                            createdAt: "2026-07-05T00:00:00.000Z"
                          source: cloud_event_cache
                          syncRequired: true
                      query: "张三"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Contacts"
      description: "Search contacts from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
    post:
      summary: "Create protocol contact search task"
      operationId: createContactSearchTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Contact search task."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ProtocolGenericTaskResponse"
              examples:
                default:
                  value:
                    data:
                      taskId: contacts_search_example
                      type: contacts_search
                      accountId: wacct_example
                      status: queued
                      params:
                        query: "示例查询"
                        ids:
[]
                        limit: 50
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      completedAt: ""
                      source: cloud_task_queue
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Contacts"
      description: "Create protocol contact search task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ProtocolGenericTaskRequest"
            examples:
              default:
                value:
                  query: "客户昵称"
                  limit: 50
                  reason: manual-sync
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/contacts/sync":
    post:
      summary: "Create contact sync task"
      operationId: createContactSyncTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Contact sync task."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ProtocolGenericTaskResponse"
              examples:
                default:
                  value:
                    data:
                      taskId: contacts_sync_example
                      type: contacts_sync
                      accountId: wacct_example
                      status: queued
                      params:
                        query: "示例查询"
                        ids:
[]
                        limit: 50
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      completedAt: ""
                      source: cloud_task_queue
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Contacts"
      description: "Create contact sync task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ProtocolGenericTaskRequest"
            examples:
              default:
                value:
                  query: "客户昵称"
                  limit: 50
                  reason: manual-sync
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/conversations":
    get:
      summary: "List conversations from cloud event cache"
      operationId: listConversations
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/query"
        -
          "$ref": "#/components/parameters/limit"
      responses:
        "200":
          description: "Conversation list."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatConversationPageResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      source: cloud_event_cache
                      syncRequired: true
                      cursor: 42
                      items:
                        -
                          targetId: wxid_example
                          displayName: "张三"
                          conversationType: contact
                          messageType: text
                          previewText: "已脱敏消息预览"
                          lastCursor: 42
                          updatedAt: "2026-07-05T00:00:00.000Z"
                          unreadCount: 0
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Conversations"
      description: "List conversations from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/conversations/{targetId}/messages":
    get:
      summary: "List normalized conversation messages"
      operationId: listConversationMessages
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/targetId"
        -
          "$ref": "#/components/parameters/cursor"
        -
          "$ref": "#/components/parameters/since"
        -
          "$ref": "#/components/parameters/limit"
      responses:
        "200":
          description: "Normalized conversation messages."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatMessagePageResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      targetId: wxid_example
                      conversationType: contact
                      source: cloud_event_cache
                      syncRequired: true
                      schemaVersion: wechat.protocol.normalized-messages.v1
                      cursor: 42
                      nextCursor: 42
                      hasMore: false
                      items:
                        -
                          eventId: evt_example
                          targetId: wxid_example
                          messageType: text
                          displayCategory: text
                          previewText: "已脱敏消息预览"
                          resource:
                            kind: ""
                            status: none
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Conversations"
      description: "List normalized conversation messages. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/events":
    get:
      summary: "Pull protocol events by cursor"
      operationId: listAccountEvents
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/cursor"
        -
          "$ref": "#/components/parameters/since"
        -
          "$ref": "#/components/parameters/limit"
      responses:
        "200":
          description: "Event page."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    type: object
                    required:
                      - events
                      - cursor
                    additionalProperties: false
                    properties:
                      events:
                        type: array
                        items:
                          "$ref": "#/components/schemas/ProtocolEvent"
                      cursor:
                        type: string
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      cursor: 42
                      nextCursor: 42
                      hasMore: false
                      items:
                        -
                          schemaVersion: wechat.protocol.event.v1
                          eventId: evt_example
                          eventType: message.created
                          accountId: wacct_example
                          internalInstanceId: wxinst_example
                          bindSessionId: bind_example
                          cloudKeyId: key_slot_example
                          runtimeShardId: shard-a
                          targetId: wxid_example
                          direction: inbound
                          msgType: 1
                          messageType: text
                          previewText: "已脱敏消息预览"
                          cursor: 42
                          source: live
                          aiEligible: true
                          receivedAt: "2026-07-05T00:00:00.000Z"
                          resource:
                            kind: ""
                            status: none
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Accounts"
      description: "Pull protocol events by cursor. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/finder/detail":
    post:
      summary: "Create or read Finder detail task/result"
      operationId: getFinderDetail
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Finder detail task or result."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    "$ref": "#/components/schemas/FinderDetailTask"
              examples:
                default:
                  value:
                    data:
                      taskId: finder_example
                      accountId: wacct_example
                      objectId: finder_object_example
                      status: queued
                      result:
{}
                      media:
                        -
                          resourceId: res_example
                          resourceType: finder_cover
                          objectKey: wechat/wacct_example/finder_cover.jpg
                          status: ready
                          mimeType: image/jpeg
                          sizeBytes: 102400
                          expiresAt: "2026-07-05T00:10:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Finder and SNS"
      description: "Create or read Finder detail task/result. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/FinderDetailRequest"
            examples:
              default:
                value:
                  objectId: finder_object_id
                  objectNonceId: finder_object_nonce
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/finder/detail-tasks/{taskId}":
    get:
      summary: "Get Finder detail task status"
      operationId: getFinderDetailTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/taskId"
      responses:
        "200":
          description: "Finder detail task."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    "$ref": "#/components/schemas/FinderDetailTask"
              examples:
                default:
                  value:
                    data:
                      taskId: finder_example
                      accountId: wacct_example
                      objectId: finder_object_example
                      status: succeeded
                      result:
{}
                      media:
                        -
                          resourceId: res_example
                          resourceType: finder_cover
                          objectKey: wechat/wacct_example/finder_cover.jpg
                          status: ready
                          mimeType: image/jpeg
                          sizeBytes: 102400
                          expiresAt: "2026-07-05T00:10:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Finder and SNS"
      description: "Get Finder detail task status. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/finder/search":
    post:
      summary: "Create Finder search task"
      operationId: createFinderSearchTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Finder search task."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ProtocolGenericTaskResponse"
              examples:
                default:
                  value:
                    data:
                      taskId: finder_search_example
                      type: finder_search
                      accountId: wacct_example
                      status: queued
                      params:
                        query: "示例查询"
                        ids:
[]
                        limit: 50
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      completedAt: ""
                      source: cloud_task_queue
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Finder and SNS"
      description: "Create Finder search task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ProtocolGenericTaskRequest"
            examples:
              default:
                value:
                  query: "客户昵称"
                  limit: 50
                  reason: manual-sync
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups":
    get:
      summary: "List groups from cloud event cache"
      operationId: listGroups
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/query"
        -
          "$ref": "#/components/parameters/limit"
      responses:
        "200":
          description: "Group list."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatGroupPageResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      source: cloud_event_cache
                      syncRequired: true
                      cursor: 42
                      items:
                        -
                          accountId: wacct_example
                          groupId: room_example@chatroom
                          targetId: room_example@chatroom
                          name: "客户群"
                          displayName: "客户群"
                          memberCount: 0
                          latest:
                            previewText: "已脱敏消息预览"
                            messageType: text
                            updatedAt: "2026-07-05T00:00:00.000Z"
                            createdAt: "2026-07-05T00:00:00.000Z"
                          source: cloud_event_cache
                          syncRequired: true
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Groups"
      description: "List groups from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups/{groupId}":
    get:
      summary: "Get group summary from cloud event cache"
      operationId: getGroup
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/groupId"
      responses:
        "200":
          description: "Group summary."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatGroupResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      groupId: room_example@chatroom
                      targetId: room_example@chatroom
                      name: "客户群"
                      displayName: "客户群"
                      memberCount: 0
                      latest:
                        previewText: "已脱敏消息预览"
                        messageType: text
                        updatedAt: "2026-07-05T00:00:00.000Z"
                        createdAt: "2026-07-05T00:00:00.000Z"
                      source: cloud_event_cache
                      syncRequired: true
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Groups"
      description: "Get group summary from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups/{groupId}/members":
    get:
      summary: "Read cached group members or protocol-required state"
      operationId: listGroupMembers
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/groupId"
      responses:
        "200":
          description: "Group members cache state."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatGroupProtocolRequiredResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      groupId: room_example@chatroom
                      source: cloud_task_queue_required
                      syncRequired: true
                      type: group_members
                      items:
[]
                      note: "群成员需要由协议 worker 执行 groups/details 或群成员同步后回写。"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Groups"
      description: "Read cached group members or protocol-required state. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups/{groupId}/qrcode":
    get:
      summary: "Read cached group QR code state"
      operationId: getGroupQrcode
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/groupId"
      responses:
        "200":
          description: "Group QR code cache state."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatGroupProtocolRequiredResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      groupId: room_example@chatroom
                      source: cloud_task_queue_required
                      syncRequired: true
                      type: group_qrcode
                      qrcode:
                        status: not_cached
                        expiresAt: ""
                      note: "群二维码需要由协议 worker 执行群二维码查询后回写，云端不会伪造二维码。"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Groups"
      description: "Read cached group QR code state. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups/details":
    post:
      summary: "Create group details task"
      operationId: createGroupDetailsTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Group details task."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ProtocolGenericTaskResponse"
              examples:
                default:
                  value:
                    data:
                      taskId: groups_details_example
                      type: groups_details
                      accountId: wacct_example
                      status: queued
                      params:
                        query: "示例查询"
                        ids:
[]
                        limit: 50
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      completedAt: ""
                      source: cloud_task_queue
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Groups"
      description: "Create group details task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ProtocolGenericTaskRequest"
            examples:
              default:
                value:
                  query: "客户昵称"
                  limit: 50
                  reason: manual-sync
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups/search":
    get:
      summary: "Search groups from cloud event cache"
      operationId: searchGroups
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/query"
        -
          "$ref": "#/components/parameters/limit"
      responses:
        "200":
          description: "Group search result."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatGroupPageResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      source: cloud_event_cache
                      syncRequired: true
                      cursor: 42
                      items:
                        -
                          accountId: wacct_example
                          groupId: room_example@chatroom
                          targetId: room_example@chatroom
                          name: "客户群"
                          displayName: "客户群"
                          memberCount: 0
                          latest:
                            previewText: "已脱敏消息预览"
                            messageType: text
                            updatedAt: "2026-07-05T00:00:00.000Z"
                            createdAt: "2026-07-05T00:00:00.000Z"
                          source: cloud_event_cache
                          syncRequired: true
                      query: "客户群"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Groups"
      description: "Search groups from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups/sync":
    post:
      summary: "Create group sync task"
      operationId: createGroupSyncTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Group sync task."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ProtocolGenericTaskResponse"
              examples:
                default:
                  value:
                    data:
                      taskId: groups_sync_example
                      type: groups_sync
                      accountId: wacct_example
                      status: queued
                      params:
                        query: "示例查询"
                        ids:
[]
                        limit: 50
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      completedAt: ""
                      source: cloud_task_queue
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Groups"
      description: "Create group sync task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ProtocolGenericTaskRequest"
            examples:
              default:
                value:
                  query: "客户昵称"
                  limit: 50
                  reason: manual-sync
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/labels":
    get:
      summary: "List contact labels"
      operationId: listContactLabels
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Contact label list."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatLabelPageResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      source: cloud_event_cache
                      syncRequired: true
                      items:
[]
                      note: "云端缓存暂未持久化联系人标签；调用 contacts/sync 后由协议 worker 回写。"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Contacts"
      description: "List contact labels. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/media/resources/{resourceId}":
    get:
      summary: "Get media resource status"
      operationId: getMediaResource
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/resourceId"
      responses:
        "200":
          description: "Media resource."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    "$ref": "#/components/schemas/MediaResource"
              examples:
                default:
                  value:
                    data:
                      resourceId: res_example
                      accountId: wacct_example
                      type: image
                      status: available
                      mimeType: image/jpeg
                      sizeBytes: 102400
                      objectStorage:
                        provider: cos
                        bucket: wechat-media-example
                        region: ap-guangzhou
                        objectKey: wechat/wacct_example/res_example.jpg
                        mimeType: image/jpeg
                        sizeBytes: 102400
                        checksum: sha256-example
                      errorCode: ""
                      errorMessage: ""
                      expiresAt: "2026-07-05T00:10:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Media"
      description: "Get media resource status. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/media/resources/{resourceId}/sign":
    post:
      summary: "Sign short-lived media URL"
      operationId: signMediaResource
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/resourceId"
      responses:
        "200":
          description: "Signed media resource."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    "$ref": "#/components/schemas/MediaResource"
              examples:
                default:
                  value:
                    data:
                      resourceId: res_example
                      accountId: wacct_example
                      type: image
                      status: available
                      mimeType: image/jpeg
                      sizeBytes: 102400
                      objectStorage:
                        provider: cos
                        bucket: wechat-media-example
                        region: ap-guangzhou
                        objectKey: wechat/wacct_example/res_example.jpg
                        mimeType: image/jpeg
                        sizeBytes: 102400
                        checksum: sha256-example
                      errorCode: ""
                      errorMessage: ""
                      expiresAt: "2026-07-05T00:10:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      signedUrl: "https://cos.example.invalid/signed/media-resource"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Media"
      description: "Sign short-lived media URL. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: false
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/EmptyJsonRequest"
            examples:
              default:
                value:
{}
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/media/resources/resolve":
    post:
      summary: "Register and resolve a WeChat media resource"
      operationId: resolveMediaResource
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Media resource record."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    "$ref": "#/components/schemas/MediaResource"
              examples:
                default:
                  value:
                    data:
                      resourceId: res_example
                      accountId: wacct_example
                      type: image
                      status: pending
                      mimeType: image/jpeg
                      sizeBytes: 102400
                      objectStorage:
                        provider: cos
                        bucket: wechat-media-example
                        region: ap-guangzhou
                        objectKey: wechat/wacct_example/res_example.jpg
                        mimeType: image/jpeg
                        sizeBytes: 102400
                        checksum: sha256-example
                      errorCode: ""
                      errorMessage: ""
                      expiresAt: "2026-07-05T00:10:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Media"
      description: "Register and resolve a WeChat media resource. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/MediaResourceRequest"
            examples:
              default:
                value:
                  type: image
                  mimeType: image/jpeg
                  sizeBytes: 102400
                  fileName: image.jpg
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/media/resources/sign":
    post:
      summary: "Sign short-lived media URLs in batch"
      operationId: signMediaResources
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Signed media resource list."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    type: object
                    required:
                      - items
                    additionalProperties: false
                    properties:
                      items:
                        type: array
                        items:
                          "$ref": "#/components/schemas/MediaResource"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      items:
                        -
                          resourceId: res_example
                          accountId: wacct_example
                          type: image
                          status: available
                          mimeType: image/jpeg
                          sizeBytes: 102400
                          objectStorage:
                            provider: cos
                            bucket: wechat-media-example
                            region: ap-guangzhou
                            objectKey: wechat/wacct_example/res_example.jpg
                            mimeType: image/jpeg
                            sizeBytes: 102400
                            checksum: sha256-example
                          errorCode: ""
                          errorMessage: ""
                          expiresAt: "2026-07-05T00:10:00.000Z"
                          updatedAt: "2026-07-05T00:00:00.000Z"
                          signedUrl: "https://cos.example.invalid/signed/media-resource"
                      failed:
[]
                      expiresAt: "2026-07-05T00:10:00.000Z"
                      source: cloud_object_storage_signer
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Media"
      description: "Sign short-lived media URLs in batch. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/MediaResourceBatchSignRequest"
            examples:
              default:
                value:
                  resourceIds:
                    - res_example
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/media/uploads":
    post:
      summary: "Create upload resource for outbound media"
      operationId: createMediaUpload
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Upload resource record."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/MediaResourceResponse"
              examples:
                default:
                  value:
                    data:
                      resourceId: res_example
                      accountId: wacct_example
                      type: upload_asset
                      status: pending
                      mimeType: image/jpeg
                      sizeBytes: 102400
                      objectStorage:
                        provider: cos
                        bucket: wechat-media-example
                        region: ap-guangzhou
                        objectKey: wechat/wacct_example/res_example.jpg
                        mimeType: image/jpeg
                        sizeBytes: 102400
                        checksum: sha256-example
                      errorCode: ""
                      errorMessage: ""
                      expiresAt: "2026-07-05T00:10:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Media"
      description: "Create upload resource for outbound media. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/MediaResourceRequest"
            examples:
              default:
                value:
                  type: image
                  mimeType: image/jpeg
                  sizeBytes: 102400
                  fileName: image.jpg
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/messages/history-sync":
    post:
      summary: "Create message history sync task"
      operationId: createMessageHistorySyncTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Message history sync task."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ProtocolGenericTaskResponse"
              examples:
                default:
                  value:
                    data:
                      taskId: history_sync_example
                      type: history_sync
                      accountId: wacct_example
                      status: queued
                      params:
                        query: "示例查询"
                        ids:
[]
                        limit: 50
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      completedAt: ""
                      source: cloud_task_queue
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Messaging"
      description: "Create message history sync task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ProtocolGenericTaskRequest"
            examples:
              default:
                value:
                  query: "客户昵称"
                  limit: 50
                  reason: manual-sync
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/messages/normalize":
    post:
      summary: "Normalize cached protocol messages"
      operationId: normalizeMessages
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Normalized messages."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    type: object
                    required:
                      - items
                    additionalProperties: false
                    properties:
                      items:
                        type: array
                        items:
                          "$ref": "#/components/schemas/NormalizedMessage"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      targetId: wxid_example
                      source: cloud_event_cache
                      syncRequired: true
                      schemaVersion: wechat.protocol.normalized-messages.v1
                      cursor: 42
                      nextCursor: 42
                      hasMore: false
                      items:
                        -
                          eventId: evt_example
                          targetId: wxid_example
                          messageType: text
                          displayCategory: text
                          previewText: "已脱敏消息预览"
                          resource:
                            kind: ""
                            status: none
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      requestBody:
        required: true
        description: "Message normalization request."
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/NormalizeMessagesRequest"
      tags:
        - "Personal WeChat Messaging"
      description: "Normalize cached protocol messages. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/messages/sync":
    post:
      summary: "Create message sync task"
      operationId: createMessageSyncTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Message sync task."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ProtocolGenericTaskResponse"
              examples:
                default:
                  value:
                    data:
                      taskId: message_sync_example
                      type: message_sync
                      accountId: wacct_example
                      status: queued
                      params:
                        query: "示例查询"
                        ids:
[]
                        limit: 50
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      completedAt: ""
                      source: cloud_task_queue
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Messaging"
      description: "Create message sync task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ProtocolGenericTaskRequest"
            examples:
              default:
                value:
                  query: "客户昵称"
                  limit: 50
                  reason: manual-sync
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/messages/text":
    post:
      summary: "Create text send task"
      operationId: createTextSendTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/idempotencyKey"
        -
          "$ref": "#/components/parameters/traceId"
      responses:
        "200":
          description: "Send task."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    "$ref": "#/components/schemas/SendTask"
              examples:
                default:
                  value:
                    data:
                      taskId: send_example
                      accountId: wacct_example
                      targetId: wxid_example
                      messageType: text
                      status: queued
                      clientActionId: act_example
                      proposalId: ""
                      dedupeKey: act_example
                      workerId: worker-mac-1
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      description: "Creates a text send task. Body supports targetId, content/text, clientActionId, proposalId, sourceMessageId, and traceId."
      requestBody:
        required: true
        description: "Text send request."
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/TextSendRequest"
      tags:
        - "Personal WeChat Messaging"
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/messages/types":
    get:
      summary: "Get normalized message type catalog"
      operationId: getMessageTypes
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Message type catalog."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatMessageTypeCatalogResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      schemaVersion: wechat.protocol.message-types.v1
                      messageTypes:
                        - text
                        - image
                        - voice
                        - video
                        - unknown
                      conversationTypes:
                        - contact
                        - group
                        - official
                        - system
                      displayCategories:
                        - text
                        - media
                        - link
                        - app
                        - system
                        - payment
                        - unknown
                      resourceStatuses:
                        - none
                        - pending
                        - ready
                        - failed
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Messaging"
      description: "Get normalized message type catalog. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/official-accounts":
    get:
      summary: "List official accounts from cloud event cache"
      operationId: listOfficialAccounts
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/query"
        -
          "$ref": "#/components/parameters/limit"
      responses:
        "200":
          description: "Official account list."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatOfficialAccountPageResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      source: cloud_event_cache
                      syncRequired: true
                      items:
                        -
                          officialId: gh_example
                          name: "示例公众号"
                          latest:
                            previewText: "已脱敏消息预览"
                            messageType: text
                            updatedAt: "2026-07-05T00:00:00.000Z"
                            createdAt: "2026-07-05T00:00:00.000Z"
                          unreadCount: 0
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Official Accounts"
      description: "List official accounts from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/official-accounts/{officialId}/messages":
    get:
      summary: "List official account messages"
      operationId: listOfficialAccountMessages
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/officialId"
        -
          "$ref": "#/components/parameters/cursor"
        -
          "$ref": "#/components/parameters/since"
        -
          "$ref": "#/components/parameters/limit"
      responses:
        "200":
          description: "Official account messages."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatMessagePageResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      targetId: gh_example
                      conversationType: official
                      source: cloud_event_cache
                      syncRequired: true
                      schemaVersion: wechat.protocol.normalized-messages.v1
                      cursor: 42
                      nextCursor: 42
                      hasMore: false
                      items:
                        -
                          eventId: evt_example
                          targetId: wxid_example
                          messageType: text
                          displayCategory: text
                          previewText: "已脱敏消息预览"
                          resource:
                            kind: ""
                            status: none
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Official Accounts"
      description: "List official account messages. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/official-accounts/hub":
    get:
      summary: "Get official account hub summary"
      operationId: getOfficialAccountHub
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/query"
        -
          "$ref": "#/components/parameters/limit"
      responses:
        "200":
          description: "Official account hub."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatOfficialHubResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      source: cloud_event_cache
                      syncRequired: true
                      totalCount: 1
                      unreadCount: 0
                      latest:
                        previewText: "已脱敏消息预览"
                        messageType: text
                        updatedAt: "2026-07-05T00:00:00.000Z"
                        createdAt: "2026-07-05T00:00:00.000Z"
                      items:
                        -
                          officialId: gh_example
                          name: "示例公众号"
                          latest:
                            previewText: "已脱敏消息预览"
                            messageType: text
                            updatedAt: "2026-07-05T00:00:00.000Z"
                            createdAt: "2026-07-05T00:00:00.000Z"
                          unreadCount: 0
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Official Accounts"
      description: "Get official account hub summary. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/online-status":
    get:
      summary: "Get account online status"
      operationId: getAccountOnlineStatus
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Account online status."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    "$ref": "#/components/schemas/RuntimeSummary"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      internalInstanceId: wxinst_example
                      bindSessionId: bind_example
                      cloudKeyId: key_slot_example
                      hostDeviceId: macbook-pro-local
                      protocolDeviceType: ipad
                      protocolDeviceProfileVersion: v1
                      status: online
                      bindStatus: bound
                      workerId: worker-mac-1
                      workerLeaseExpiresAt: "2026-07-05T00:10:00.000Z"
                      health:
                        status: online
                        workerId: worker-mac-1
                      recover:
{}
                      updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Accounts"
      description: "Get account online status. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/profile":
    get:
      summary: "Get cloud account profile summary"
      operationId: getAccountProfile
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Cloud account profile summary."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatProfileResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      displayName: "客服微信一号"
                      avatarUrl: ""
                      bindSessionId: bind_example
                      cloudKeyId: key_slot_example
                      protocolDeviceType: ipad
                      hostDeviceId: macbook-pro-local
                      mode: cloud
                      source: cloud_runtime_summary
                      syncRequired: true
                      runtime:
                        accountId: wacct_example
                        internalInstanceId: wxinst_example
                        bindSessionId: bind_example
                        cloudKeyId: key_slot_example
                        hostDeviceId: macbook-pro-local
                        protocolDeviceType: ipad
                        protocolDeviceProfileVersion: v1
                        status: online
                        bindStatus: bound
                        workerId: worker-mac-1
                        workerLeaseExpiresAt: "2026-07-05T00:10:00.000Z"
                        health:
                          status: online
                          workerId: worker-mac-1
                        recover:
{}
                        updatedAt: "2026-07-05T00:00:00.000Z"
                      latestEventAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Accounts"
      description: "Get cloud account profile summary. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/recipients/resolve":
    get:
      summary: "Resolve one recipient from cloud event cache"
      operationId: resolveRecipient
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Recipient candidates."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatRecipientResolveResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      source: cloud_event_cache
                      syncRequired: true
                      items:
                        -
                          query: "张三"
                          matches:
                            -
                              targetId: wxid_example
                              displayName: "张三"
                              conversationType: contact
                              confidence: 1
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Contacts"
      description: "Resolve one recipient from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
    post:
      summary: "Resolve recipient candidates in batch"
      operationId: resolveRecipients
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Recipient candidates."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatRecipientResolveResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      source: cloud_event_cache
                      syncRequired: true
                      items:
                        -
                          query: "张三"
                          matches:
                            -
                              targetId: wxid_example
                              displayName: "张三"
                              conversationType: contact
                              confidence: 1
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Contacts"
      description: "Resolve recipient candidates in batch. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/RecipientResolveRequest"
            examples:
              default:
                value:
                  queries:
                    - "张三"
                    - "客户群"
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/recover":
    post:
      summary: "Request protocol runtime recovery"
      operationId: recoverAccount
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Runtime state."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/RuntimeSummaryResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      internalInstanceId: wxinst_example
                      bindSessionId: bind_example
                      cloudKeyId: key_slot_example
                      hostDeviceId: macbook-pro-local
                      protocolDeviceType: ipad
                      protocolDeviceProfileVersion: v1
                      status: recovering
                      bindStatus: bound
                      workerId: worker-mac-1
                      workerLeaseExpiresAt: "2026-07-05T00:10:00.000Z"
                      health:
                        status: recovering
                        workerId: worker-mac-1
                      recover:
{}
                      updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Accounts"
      description: "Request protocol runtime recovery. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/RecoverRequest"
            examples:
              default:
                value:
                  reason: manual-recover
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/runtime-summary":
    get:
      summary: "Get account runtime summary"
      operationId: getAccountRuntimeSummary
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Account runtime summary."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    "$ref": "#/components/schemas/RuntimeSummary"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      internalInstanceId: wxinst_example
                      bindSessionId: bind_example
                      cloudKeyId: key_slot_example
                      hostDeviceId: macbook-pro-local
                      protocolDeviceType: ipad
                      protocolDeviceProfileVersion: v1
                      status: online
                      bindStatus: bound
                      workerId: worker-mac-1
                      workerLeaseExpiresAt: "2026-07-05T00:10:00.000Z"
                      health:
                        status: online
                        workerId: worker-mac-1
                      recover:
{}
                      updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Accounts"
      description: "Get account runtime summary. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/scopes":
    get:
      summary: "Get account scopes"
      operationId: getAccountScopes
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      responses:
        "200":
          description: "Account scope directory."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/PersonalWechatScopeDirectoryResponse"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      scopes:
                        -
                          scope: messages.send
                          capability: action.execute
                          description: "创建受控发送任务。"
                          enabled: true
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Accounts"
      description: "Get account scopes. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/send-tasks/{taskId}":
    get:
      summary: "Get text send task status"
      operationId: getSendTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/taskId"
      responses:
        "200":
          description: "Send task."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    "$ref": "#/components/schemas/SendTask"
              examples:
                default:
                  value:
                    data:
                      taskId: send_example
                      accountId: wacct_example
                      targetId: wxid_example
                      messageType: text
                      status: sent
                      clientActionId: act_example
                      proposalId: ""
                      dedupeKey: act_example
                      workerId: worker-mac-1
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Messaging"
      description: "Get text send task status. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/sns/timeline":
    get:
      summary: "Create SNS timeline query task"
      operationId: createSnsTimelineTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/cursor"
        -
          "$ref": "#/components/parameters/limit"
      responses:
        "200":
          description: "SNS timeline task."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ProtocolGenericTaskResponse"
              examples:
                default:
                  value:
                    data:
                      taskId: sns_timeline_example
                      type: sns_timeline
                      accountId: wacct_example
                      status: queued
                      params:
                        query: "示例查询"
                        ids:
[]
                        limit: 50
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      completedAt: ""
                      source: cloud_task_queue
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Finder and SNS"
      description: "Create SNS timeline query task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ProtocolGenericTaskRequest"
            examples:
              default:
                value:
                  query: "客户昵称"
                  limit: 50
                  reason: manual-sync
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/sns/user-page":
    get:
      summary: "Create SNS user page query task"
      operationId: createSnsUserPageTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/userName"
        -
          "$ref": "#/components/parameters/cursor"
        -
          "$ref": "#/components/parameters/limit"
      responses:
        "200":
          description: "SNS user page task."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ProtocolGenericTaskResponse"
              examples:
                default:
                  value:
                    data:
                      taskId: sns_user_page_example
                      type: sns_user_page
                      accountId: wacct_example
                      status: queued
                      params:
                        query: "示例查询"
                        ids:
[]
                        limit: 50
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      completedAt: ""
                      source: cloud_task_queue
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Finder and SNS"
      description: "Create SNS user page query task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ProtocolGenericTaskRequest"
            examples:
              default:
                value:
                  query: "客户昵称"
                  limit: 50
                  reason: manual-sync
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/tasks/{taskId}":
    get:
      summary: "Get unified task status"
      operationId: getTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/taskId"
      responses:
        "200":
          description: "Unified task."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/UnifiedProtocolTaskResponse"
              examples:
                default:
                  value:
                    data:
                      taskType: send
                      taskId: send_example
                      accountId: wacct_example
                      status: succeeded
                      rawStatus: succeeded
                      targetId: wxid_example
                      messageType: text
                      clientActionId: act_example
                      proposalId: ""
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      completedAt: "2026-07-05T00:00:01.000Z"
                      data:
                        taskId: send_example
                        accountId: wacct_example
                        targetId: wxid_example
                        messageType: text
                        status: sent
                        clientActionId: act_example
                        proposalId: ""
                        dedupeKey: act_example
                        workerId: worker-mac-1
                        errorCode: ""
                        errorMessage: ""
                        createdAt: "2026-07-05T00:00:00.000Z"
                        updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Tasks"
      description: "Get unified task status. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/tasks/{taskId}/cancel":
    post:
      summary: "Cancel a pending task"
      operationId: cancelTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/taskId"
      responses:
        "200":
          description: "Cancelled task status."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/UnifiedProtocolTaskResponse"
              examples:
                default:
                  value:
                    data:
                      taskType: send
                      taskId: send_example
                      accountId: wacct_example
                      status: cancelled
                      rawStatus: cancelled
                      targetId: wxid_example
                      messageType: text
                      clientActionId: act_example
                      proposalId: ""
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      completedAt: "2026-07-05T00:00:01.000Z"
                      data:
                        taskId: send_example
                        accountId: wacct_example
                        targetId: wxid_example
                        messageType: text
                        status: cancelled
                        clientActionId: act_example
                        proposalId: ""
                        dedupeKey: act_example
                        workerId: worker-mac-1
                        errorCode: ""
                        errorMessage: ""
                        createdAt: "2026-07-05T00:00:00.000Z"
                        updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Tasks"
      description: "Cancel a pending task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/TaskMutationRequest"
            examples:
              default:
                value:
                  reason: manual-operation
  "/api/capabilities/personal-wechat/v1/accounts/{accountId}/tasks/{taskId}/retry":
    post:
      summary: "Retry a failed or cancelled task"
      operationId: retryTask
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
        -
          "$ref": "#/components/parameters/taskId"
      responses:
        "200":
          description: "Retried task status."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/UnifiedProtocolTaskResponse"
              examples:
                default:
                  value:
                    data:
                      taskType: send
                      taskId: send_example
                      accountId: wacct_example
                      status: queued
                      rawStatus: queued
                      targetId: wxid_example
                      messageType: text
                      clientActionId: act_example
                      proposalId: ""
                      errorCode: ""
                      errorMessage: ""
                      createdAt: "2026-07-05T00:00:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
                      completedAt: "2026-07-05T00:00:01.000Z"
                      data:
                        taskId: send_example
                        accountId: wacct_example
                        targetId: wxid_example
                        messageType: text
                        status: queued
                        clientActionId: act_example
                        proposalId: ""
                        dedupeKey: act_example
                        workerId: worker-mac-1
                        errorCode: ""
                        errorMessage: ""
                        createdAt: "2026-07-05T00:00:00.000Z"
                        updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Tasks"
      description: "Retry a failed or cancelled task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/TaskMutationRequest"
            examples:
              default:
                value:
                  reason: manual-operation
  "/api/capabilities/personal-wechat/v1/storage/entitlement":
    get:
      summary: "Get object storage entitlement"
      operationId: getStorageEntitlement
      responses:
        "200":
          description: "Object storage entitlement."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    "$ref": "#/components/schemas/StorageEntitlement"
              examples:
                default:
                  value:
                    data:
                      objectStorageEnabled: true
                      storageQuotaBytes: 1073741824
                      storageUsedBytes: 1024
                      storageRetentionDays: 30
                      maxFileSizeBytes: 104857600
                      monthlyEgressQuotaBytes: 1073741824
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - "Personal WeChat Media"
      description: "Get object storage entitlement. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets."
  "/api/protocol/accounts/{accountId}/health":
    post:
      summary: "Worker updates account health"
      operationId: updateProtocolHealth
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      security:
        -
          protocolWorkerKey:
[]
      responses:
        "200":
          description: "Runtime state."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    "$ref": "#/components/schemas/RuntimeSummary"
              examples:
                default:
                  value:
                    data:
                      accountId: wacct_example
                      internalInstanceId: wxinst_example
                      bindSessionId: bind_example
                      cloudKeyId: key_slot_example
                      hostDeviceId: macbook-pro-local
                      protocolDeviceType: ipad
                      protocolDeviceProfileVersion: v1
                      status: online
                      bindStatus: bound
                      workerId: worker-mac-1
                      workerLeaseExpiresAt: "2026-07-05T00:10:00.000Z"
                      health:
                        status: online
                        workerId: worker-mac-1
                      recover:
{}
                      updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      x-internal: true
      tags:
        - "Protocol Workers"
      description: "Worker updates account health. Internal protocol worker endpoint for claim, health, or result writeback. It is marked x-internal, uses the protocol worker key, and is not part of the public capability SDK."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ProtocolHealthUpdateRequest"
            examples:
              default:
                value:
                  status: online
                  workerId: worker-mac-1
                  queueLagMs: 0
  "/api/protocol/accounts/{accountId}/media/resource-results":
    post:
      summary: "Worker writes media resource result"
      operationId: writeMediaResourceResult
      parameters:
        -
          "$ref": "#/components/parameters/accountId"
      security:
        -
          protocolWorkerKey:
[]
      responses:
        "200":
          description: "Media resource."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    "$ref": "#/components/schemas/MediaResource"
              examples:
                default:
                  value:
                    data:
                      resourceId: res_example
                      accountId: wacct_example
                      type: image
                      status: available
                      mimeType: image/jpeg
                      sizeBytes: 102400
                      objectStorage:
                        provider: cos
                        bucket: wechat-media-example
                        region: ap-guangzhou
                        objectKey: wechat/wacct_example/res_example.jpg
                        mimeType: image/jpeg
                        sizeBytes: 102400
                        checksum: sha256-example
                      errorCode: ""
                      errorMessage: ""
                      expiresAt: "2026-07-05T00:10:00.000Z"
                      updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      x-internal: true
      tags:
        - "Protocol Workers"
      description: "Worker writes media resource result. Internal protocol worker endpoint for claim, health, or result writeback. It is marked x-internal, uses the protocol worker key, and is not part of the public capability SDK."
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ProtocolMediaResourceResultRequest"
            examples:
              default:
                value:
                  resourceId: res_example
                  status: available
                  mimeType: image/jpeg
                  sizeBytes: 102400
                  objectStorage:
                    provider: cos
                    objectKey: wechat/account/resource.jpg
                    mimeType: image/jpeg
                    sizeBytes: 102400
  "/api/protocol/workers/claim":
    post:
      summary: "Worker claims assignments and tasks"
      operationId: claimProtocolWorker
      security:
        -
          protocolWorkerKey:
[]
      responses:
        "200":
          description: "Worker assignments."
          content:
            "application/json":
              schema:
                type: object
                required:
                  - data
                additionalProperties: false
                properties:
                  data:
                    type: object
                    required:
                      - worker
                      - assignments
                    additionalProperties: true
                    properties:
                      worker:
                        type: object
                        additionalProperties: true
                      assignments:
                        type: array
                        items:
                          "$ref": "#/components/schemas/ProtocolWorkerAssignment"
              examples:
                default:
                  value:
                    data:
                      assignments:
                        -
                          accountId: wacct_example
                          internalInstanceId: wxinst_example
                          bindSessionId: bind_example
                          cloudKeyId: key_slot_example
                          protocolDeviceType: ipad
                          hostDeviceId: macbook-pro-local
                          sendTasks:
                            -
                              taskId: send_example
                              accountId: wacct_example
                              targetId: wxid_example
                              messageType: text
                              status: queued
                              clientActionId: act_example
                              proposalId: ""
                              dedupeKey: act_example
                              workerId: worker-mac-1
                              errorCode: ""
                              errorMessage: ""
                              createdAt: "2026-07-05T00:00:00.000Z"
                              updatedAt: "2026-07-05T00:00:00.000Z"
                          finderDetailTasks:
                            -
                              taskId: finder_example
                              accountId: wacct_example
                              objectId: finder_object_example
                              status: queued
                              result:
{}
                              media:
                                -
                                  resourceId: res_example
                                  resourceType: finder_cover
                                  objectKey: wechat/wacct_example/finder_cover.jpg
                                  status: ready
                                  mimeType: image/jpeg
                                  sizeBytes: 102400
                                  expiresAt: "2026-07-05T00:10:00.000Z"
                          genericTasks:
                            -
                              taskId: contacts_sync_example
                              type: contacts_sync
                              accountId: wacct_example
                              status: queued
                              params:
                                query: "示例查询"
                                ids:
[]
                                limit: 50
                              errorCode: ""
                              errorMessage: ""
                              createdAt: "2026-07-05T00:00:00.000Z"
                              updatedAt: "2026-07-05T00:00:00.000Z"
                              completedAt: ""
                              source: cloud_task_queue
                          mediaResources:
                            -
                              resourceId: res_example
                              accountId: wacct_example
                              type: image
                              status: pending
                              mimeType: image/jpeg
                              sizeBytes: 102400
                              objectStorage:
                                provider: cos
                                bucket: wechat-media-example
                                region: ap-guangzhou
                                objectKey: wechat/wacct_example/res_example.jpg
                                mimeType: image/jpeg
                                sizeBytes: 102400
                                checksum: sha256-example
                              errorCode: ""
                              errorMessage: ""
                              expiresAt: "2026-07-05T00:10:00.000Z"
                              updatedAt: "2026-07-05T00:00:00.000Z"
                          localTaskPath: /api/wechat-bind-sessions/bind_example/local-task
                          health:
                            accountId: wacct_example
                            internalInstanceId: wxinst_example
                            bindSessionId: bind_example
                            cloudKeyId: key_slot_example
                            hostDeviceId: macbook-pro-local
                            protocolDeviceType: ipad
                            protocolDeviceProfileVersion: v1
                            status: online
                            bindStatus: bound
                            workerId: worker-mac-1
                            workerLeaseExpiresAt: "2026-07-05T00:10:00.000Z"
                            health:
                              status: online
                              workerId: worker-mac-1
                            recover:
{}
                            updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      x-internal: true
      requestBody:
        required: true
        description: "Worker claim request."
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ProtocolWorkerClaimRequest"
      tags:
        - "Protocol Workers"
      description: "Worker claims assignments and tasks. Internal protocol worker endpoint for claim, health, or result writeback. It is marked x-internal, uses the protocol worker key, and is not part of the public capability SDK."
  "/health":
    get:
      summary: "Cloud API health check"
      operationId: getHealth
      security:
[]
      responses:
        "200":
          description: "Health status."
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/HealthResponse"
              examples:
                default:
                  value:
                    ok: true
                    service: wechat-cloud-api
                    updatedAt: "2026-07-05T00:00:00.000Z"
        "400":
          "$ref": "#/components/responses/BadRequest"
        "401":
          "$ref": "#/components/responses/Unauthorized"
        "403":
          "$ref": "#/components/responses/Forbidden"
      tags:
        - Health
      description: "Cloud API health check. Public health probe for deployment readiness and load balancer checks. It returns only service status metadata and no tenant, account, or protocol data."
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    protocolWorkerKey:
      type: apiKey
      in: header
      name: X-Protocol-Worker-Key
  parameters:
    accountId:
      name: accountId
      in: path
      required: true
      schema:
        type: string
      description: "Product-level WeChat account ID. Access is limited by the caller token."
    resourceId:
      name: resourceId
      in: path
      required: true
      schema:
        type: string
      description: "Media resource ID."
    taskId:
      name: taskId
      in: path
      required: true
      schema:
        type: string
      description: "Unified task ID."
    targetId:
      name: targetId
      in: path
      required: true
      schema:
        type: string
      description: "Conversation target ID."
    officialId:
      name: officialId
      in: path
      required: true
      schema:
        type: string
      description: "Official account ID."
    groupId:
      name: groupId
      in: path
      required: true
      schema:
        type: string
      description: "Group chat ID."
    idempotencyKey:
      name: X-Idempotency-Key
      in: header
      required: false
      schema:
        type: string
      description: "Optional idempotency key for write actions. SDKs may generate it automatically."
    traceId:
      name: X-Trace-Id
      in: header
      required: false
      schema:
        type: string
      description: "Optional trace ID for API, worker, and audit correlation."
    query:
      name: query
      in: query
      required: false
      schema:
        type: string
      description: "Search text. The API also accepts q as a compatibility alias."
      example: "张三"
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 50
      description: "Maximum number of cached records or tasks to return."
      example: 50
    cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
      description: "Cloud event cursor or page cursor."
      example: 0
    since:
      name: since
      in: query
      required: false
      schema:
        type: string
      description: "Compatibility alias for cursor."
      example: 0
    userName:
      name: userName
      in: query
      required: false
      schema:
        type: string
      description: "Contact username or wxid surrogate for SNS user-page tasks."
      example: wxid_xxx
  schemas:
    ApiError:
      type: object
      required:
        - error
        - message
      additionalProperties: false
      properties:
        error:
          type: string
        message:
          type: string
        data:
          type: object
          additionalProperties: true
    HealthResponse:
      type: object
      required:
        - ok
        - service
        - updatedAt
      additionalProperties: false
      properties:
        ok:
          type: boolean
        service:
          type: string
        updatedAt:
          type: string
          format: date-time
    PersonalWechatAccount:
      type: object
      required:
        - accountId
        - status
      additionalProperties: false
      properties:
        accountId:
          type: string
        internalInstanceId:
          type: string
        bindSessionId:
          type: string
        cloudKeyId:
          type: string
        protocolDeviceType:
          type: string
          enum:
            - ipad
            - mac
            - win
            - harmony
            - car
            - watch
        status:
          type: string
        online:
          type: boolean
        nickname:
          type: string
        avatarUrl:
          type: string
        updatedAt:
          type: string
          format: date-time
    RuntimeSummary:
      type: object
      required:
        - accountId
        - status
        - online
      additionalProperties: false
      properties:
        accountId:
          type: string
        internalInstanceId:
          type: string
        bindSessionId:
          type: string
        cloudKeyId:
          type: string
        protocolDeviceType:
          type: string
        runtimeShardId:
          type: string
        status:
          type: string
        online:
          type: boolean
        lastSeenAt:
          type: string
          format: date-time
        recoverRequestedAt:
          type: string
          format: date-time
    ProtocolEvent:
      type: object
      required:
        - schemaVersion
        - eventId
        - eventType
        - accountId
        - targetId
        - messageType
        - cursor
      additionalProperties: false
      properties:
        schemaVersion:
          type: string
          enum:
            - wechat.protocol.event.v1
        eventId:
          type: string
        eventType:
          type: string
        accountId:
          type: string
        internalInstanceId:
          type: string
        bindSessionId:
          type: string
        cloudKeyId:
          type: string
        runtimeShardId:
          type: string
        targetId:
          type: string
        direction:
          type: string
          enum:
            - inbound
            - outbound
            - unknown
        msgType:
          type: integer
        messageType:
          type: string
        previewText:
          type: string
          description: "Redacted display preview. Raw chat body is not accepted as API input."
        cursor:
          type: string
        source:
          type: string
        aiEligible:
          type: boolean
        receivedAt:
          type: string
          format: date-time
        resource:
          "$ref": "#/components/schemas/MediaResourceRef"
    TextSendRequest:
      type: object
      required:
        - targetId
      additionalProperties: false
      properties:
        targetId:
          type: string
        content:
          type: string
          maxLength: 4000
          description: "Text to send. This is accepted only by the send task creation API."
        text:
          type: string
          maxLength: 4000
          deprecated: true
        atWxIDList:
          type: array
          items:
            type: string
          maxItems: 200
        clientActionId:
          type: string
        proposalId:
          type: string
        sourceMessageId:
          type: string
        traceId:
          type: string
    SendTask:
      type: object
      required:
        - taskId
        - accountId
        - targetId
        - status
      additionalProperties: false
      properties:
        taskId:
          type: string
        accountId:
          type: string
        targetId:
          type: string
        messageType:
          type: string
        status:
          type: string
          enum:
            - queued
            - leased
            - sending
            - sent
            - delivered
            - failed
            - cancelled
        clientActionId:
          type: string
        proposalId:
          type: string
        dedupeKey:
          type: string
        workerId:
          type: string
        errorCode:
          type: string
        errorMessage:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    NormalizeMessagesRequest:
      type: object
      required:
        - eventRefs
      additionalProperties: false
      properties:
        eventRefs:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 200
        cursor:
          type: string
      description: "Only accepts event references from cloud cache. Raw message body, XML, chat content, and contact detail fields are rejected."
    NormalizedMessage:
      type: object
      required:
        - eventId
        - messageType
        - targetId
      additionalProperties: false
      properties:
        eventId:
          type: string
        targetId:
          type: string
        messageType:
          type: string
        displayCategory:
          type: string
        previewText:
          type: string
        resource:
          "$ref": "#/components/schemas/MediaResourceRef"
    MediaResourceRef:
      type: object
      additionalProperties: false
      properties:
        resourceId:
          type: string
        resourceType:
          type: string
        objectKey:
          type: string
          description: "COS object key scoped by tenantId/userId/accountId."
        status:
          type: string
        mimeType:
          type: string
        sizeBytes:
          type: integer
        expiresAt:
          type: string
          format: date-time
    MediaResource:
      type: object
      required:
        - resourceId
        - accountId
        - status
      additionalProperties: false
      properties:
        resourceId:
          type: string
        accountId:
          type: string
        resourceType:
          type: string
        status:
          type: string
        objectKey:
          type: string
        signedUrl:
          type: string
          description: "Short-lived URL only; never includes urlToken/decodeKey."
        expiresAt:
          type: string
          format: date-time
        errorCode:
          type: string
        errorMessage:
          type: string
    FinderDetailTask:
      type: object
      required:
        - taskId
        - accountId
        - objectId
        - status
      additionalProperties: false
      properties:
        taskId:
          type: string
        accountId:
          type: string
        objectId:
          type: string
        status:
          type: string
        result:
          type: object
          additionalProperties: true
        media:
          type: array
          items:
            "$ref": "#/components/schemas/MediaResourceRef"
    StorageEntitlement:
      type: object
      required:
        - objectStorageEnabled
        - storageQuotaBytes
        - storageUsedBytes
      additionalProperties: false
      properties:
        objectStorageEnabled:
          type: boolean
        storageQuotaBytes:
          type: integer
        storageUsedBytes:
          type: integer
        storageRetentionDays:
          type: integer
        maxFileSizeBytes:
          type: integer
        monthlyEgressQuotaBytes:
          type: integer
    ProtocolWorkerClaimRequest:
      type: object
      required:
        - workerId
      additionalProperties: false
      properties:
        workerId:
          type: string
        runtimeShardId:
          type: string
        hostDeviceId:
          type: string
        capacity:
          type: integer
          minimum: 1
          maximum: 200
        version:
          type: string
    ProtocolWorkerAssignment:
      type: object
      required:
        - accountId
      additionalProperties: false
      properties:
        accountId:
          type: string
        internalInstanceId:
          type: string
        bindSessionId:
          type: string
        cloudKeyId:
          type: string
        sendTasks:
          type: array
          items:
            "$ref": "#/components/schemas/SendTask"
        finderDetailTasks:
          type: array
          items:
            "$ref": "#/components/schemas/FinderDetailTask"
        protocolDeviceType:
          type: string
        hostDeviceId:
          type: string
        localTaskPath:
          type: string
        health:
          "$ref": "#/components/schemas/RuntimeSummary"
        genericTasks:
          type: array
          items:
            type: object
            additionalProperties: true
        mediaResources:
          type: array
          items:
            "$ref": "#/components/schemas/MediaResource"
    DataEnvelope:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          type: object
          additionalProperties: true
    LatestPreview:
      type: object
      required:
        - previewText
        - messageType
        - updatedAt
      additionalProperties: false
      properties:
        previewText:
          type: string
          description: "Redacted display preview."
        messageType:
          type: string
          description: "Normalized message type."
        updatedAt:
          type: string
          description: "Latest cached update time."
        createdAt:
          type: string
          description: "Latest cached create time."
    PersonalWechatContact:
      type: object
      required:
        - accountId
        - contactId
        - targetId
        - nickname
        - source
        - syncRequired
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        contactId:
          type: string
          description: "Product-level contact ID."
        targetId:
          type: string
          description: "Conversation target ID."
        userName:
          type: string
          description: "Protocol username or wxid surrogate after redaction."
        nickname:
          type: string
          description: "Display nickname."
        remarkName:
          type: string
          description: "Remark name when available."
        alias:
          type: string
          description: "Alias when available."
        avatarUrl:
          type: string
          description: "Avatar URL when available."
        latest:
          "$ref": "#/components/schemas/LatestPreview"
        source:
          type: string
          description: "Data source, normally cloud_event_cache."
        syncRequired:
          type: boolean
          description: "Whether a protocol sync task is still required for fresher data."
    PersonalWechatContactPage:
      type: object
      required:
        - accountId
        - source
        - syncRequired
        - cursor
        - items
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        source:
          type: string
          description: "Data source, normally cloud_event_cache."
        syncRequired:
          type: boolean
          description: "Whether a protocol sync task is still required for fresher data."
        cursor:
          type: integer
          description: "Current cloud event cursor."
        items:
          type: array
          items:
            "$ref": "#/components/schemas/PersonalWechatContact"
        query:
          type: string
          description: "Search query when this page is produced by a search endpoint."
    PersonalWechatLabel:
      type: object
      required:
        - labelId
        - name
      additionalProperties: false
      properties:
        labelId:
          type: string
          description: "Label ID."
        name:
          type: string
          description: "Label name."
        count:
          type: integer
          description: "Cached contact count."
    PersonalWechatLabelPage:
      type: object
      required:
        - accountId
        - source
        - syncRequired
        - cursor
        - items
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        source:
          type: string
          description: "Data source, normally cloud_event_cache."
        syncRequired:
          type: boolean
          description: "Whether a protocol sync task is still required for fresher data."
        cursor:
          type: integer
          description: "Current cloud event cursor."
        items:
          type: array
          items:
            "$ref": "#/components/schemas/PersonalWechatLabel"
        note:
          type: string
          description: "Human-readable cache or sync note."
    PersonalWechatGroup:
      type: object
      required:
        - accountId
        - groupId
        - targetId
        - displayName
        - source
        - syncRequired
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        groupId:
          type: string
          description: "Group chat ID."
        targetId:
          type: string
          description: "Conversation target ID."
        name:
          type: string
          description: "Group name."
        displayName:
          type: string
          description: "Display group name."
        memberCount:
          type: integer
          description: "Cached member count."
        latest:
          "$ref": "#/components/schemas/LatestPreview"
        source:
          type: string
          description: "Data source, normally cloud_event_cache."
        syncRequired:
          type: boolean
          description: "Whether a protocol sync task is still required for fresher data."
    PersonalWechatGroupPage:
      type: object
      required:
        - accountId
        - source
        - syncRequired
        - cursor
        - items
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        source:
          type: string
          description: "Data source, normally cloud_event_cache."
        syncRequired:
          type: boolean
          description: "Whether a protocol sync task is still required for fresher data."
        cursor:
          type: integer
          description: "Current cloud event cursor."
        items:
          type: array
          items:
            "$ref": "#/components/schemas/PersonalWechatGroup"
        query:
          type: string
          description: "Search query when this page is produced by a search endpoint."
    PersonalWechatGroupProtocolRequired:
      type: object
      required:
        - accountId
        - groupId
        - source
        - syncRequired
        - type
        - note
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        groupId:
          type: string
          description: "Group chat ID."
        source:
          type: string
          description: "Data source, normally cloud_task_queue_required."
        syncRequired:
          type: boolean
          description: "Whether a protocol worker task is required."
        type:
          type: string
          description: "Required protocol query type."
        items:
          type: array
          description: "Cached group members. Empty until worker writeback."
          items:
            type: object
            required:
[]
            additionalProperties: true
            properties:
{}
        qrcode:
          type: object
          required:
            - status
            - expiresAt
          additionalProperties: false
          properties:
            status:
              type: string
              description: "Cached QR code status."
            expiresAt:
              type: string
              description: "QR code expiry time if cached."
        note:
          type: string
          description: "Human-readable sync requirement note."
    PersonalWechatConversation:
      type: object
      required:
        - targetId
        - displayName
        - conversationType
        - messageType
        - previewText
        - lastCursor
        - updatedAt
      additionalProperties: false
      properties:
        targetId:
          type: string
          description: "Conversation target ID."
        displayName:
          type: string
          description: "Display name inferred from cached events."
        conversationType:
          type: string
          description: "contact, group, official, or system."
        messageType:
          type: string
          description: "Latest normalized message type."
        previewText:
          type: string
          description: "Redacted latest message preview."
        lastCursor:
          type: integer
          description: "Latest protocol event cursor for this conversation."
        updatedAt:
          type: string
          description: "Latest event time."
        unreadCount:
          type: integer
          description: "Cached unread count."
    PersonalWechatConversationPage:
      type: object
      required:
        - accountId
        - source
        - syncRequired
        - cursor
        - items
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        source:
          type: string
          description: "Data source, normally cloud_event_cache."
        syncRequired:
          type: boolean
          description: "Whether a protocol sync task is still required for fresher data."
        cursor:
          type: integer
          description: "Current cloud event cursor."
        items:
          type: array
          items:
            "$ref": "#/components/schemas/PersonalWechatConversation"
    PersonalWechatMessagePage:
      type: object
      required:
        - accountId
        - targetId
        - conversationType
        - source
        - syncRequired
        - cursor
        - nextCursor
        - hasMore
        - items
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        targetId:
          type: string
          description: "Conversation target ID."
        conversationType:
          type: string
          description: "contact, group, official, or system."
        source:
          type: string
          description: "Data source, normally cloud_event_cache."
        syncRequired:
          type: boolean
          description: "Whether a protocol sync task is still required for fresher data."
        schemaVersion:
          type: string
          description: "Normalized message schema version."
        cursor:
          type: integer
          description: "Current cloud event cursor."
        nextCursor:
          type: integer
          description: "Cursor to use for the next page."
        hasMore:
          type: boolean
          description: "Whether more events are likely available."
        items:
          type: array
          items:
            "$ref": "#/components/schemas/NormalizedMessage"
    PersonalWechatOfficialAccount:
      type: object
      required:
        - officialId
        - name
        - latest
        - unreadCount
      additionalProperties: false
      properties:
        officialId:
          type: string
          description: "Official account ID."
        name:
          type: string
          description: "Official account display name."
        latest:
          "$ref": "#/components/schemas/LatestPreview"
        unreadCount:
          type: integer
          description: "Cached unread count."
    PersonalWechatOfficialAccountPage:
      type: object
      required:
        - accountId
        - source
        - syncRequired
        - items
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        source:
          type: string
          description: "Data source, normally cloud_event_cache."
        syncRequired:
          type: boolean
          description: "Whether a protocol sync task is still required for fresher data."
        items:
          type: array
          items:
            "$ref": "#/components/schemas/PersonalWechatOfficialAccount"
    PersonalWechatOfficialHub:
      type: object
      required:
        - accountId
        - source
        - syncRequired
        - totalCount
        - unreadCount
        - items
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        source:
          type: string
          description: "Data source, normally cloud_event_cache."
        syncRequired:
          type: boolean
          description: "Whether a protocol sync task is still required for fresher data."
        totalCount:
          type: integer
          description: "Official account count."
        unreadCount:
          type: integer
          description: "Cached unread count."
        latest:
          "$ref": "#/components/schemas/LatestPreview"
        items:
          type: array
          items:
            "$ref": "#/components/schemas/PersonalWechatOfficialAccount"
    PersonalWechatRecipientCandidate:
      type: object
      required:
        - targetId
        - displayName
        - conversationType
        - confidence
      additionalProperties: false
      properties:
        targetId:
          type: string
          description: "Resolved target ID."
        displayName:
          type: string
          description: "Resolved display name."
        conversationType:
          type: string
          description: "contact, group, official, or system."
        confidence:
          type: number
          description: "Heuristic match confidence."
    PersonalWechatRecipientResolution:
      type: object
      required:
        - query
        - matches
      additionalProperties: false
      properties:
        query:
          type: string
          description: "Original query string."
        matches:
          type: array
          items:
            "$ref": "#/components/schemas/PersonalWechatRecipientCandidate"
    PersonalWechatRecipientResolveResult:
      type: object
      required:
        - accountId
        - source
        - syncRequired
        - items
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        source:
          type: string
          description: "Data source, normally cloud_event_cache."
        syncRequired:
          type: boolean
          description: "Whether a protocol sync task is still required for fresher data."
        items:
          type: array
          items:
            "$ref": "#/components/schemas/PersonalWechatRecipientResolution"
    ProtocolGenericTaskParams:
      type: object
      required:
        - ids
        - limit
      additionalProperties: false
      properties:
        sinceCursor:
          type: string
          description: "Cursor used for sync-like protocol tasks."
        targetId:
          type: string
          description: "Target conversation ID."
        groupId:
          type: string
          description: "Group chat ID."
        userName:
          type: string
          description: "Contact username or wxid surrogate."
        query:
          type: string
          description: "Search query."
        ids:
          type: array
          description: "Explicit target IDs."
          items:
            type: string
        limit:
          type: integer
          description: "Requested result limit."
        reason:
          type: string
          description: "Redacted request reason."
    ProtocolGenericTask:
      type: object
      required:
        - taskId
        - type
        - accountId
        - status
        - params
        - createdAt
        - updatedAt
        - source
      additionalProperties: false
      properties:
        taskId:
          type: string
          description: "Protocol task ID."
        type:
          type: string
          description: "Generic task type."
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        status:
          type: string
          description: "queued, processing, succeeded, failed, or cancelled."
        params:
          "$ref": "#/components/schemas/ProtocolGenericTaskParams"
        errorCode:
          type: string
          description: "Failure code when available."
        errorMessage:
          type: string
          description: "Redacted failure message when available."
        createdAt:
          type: string
          description: "Creation time."
        updatedAt:
          type: string
          description: "Update time."
        completedAt:
          type: string
          description: "Completion time when available."
        source:
          type: string
          description: "Data source, normally cloud_task_queue."
    UnifiedProtocolTask:
      type: object
      required:
        - taskType
        - taskId
        - accountId
        - status
        - rawStatus
        - createdAt
        - updatedAt
        - data
      additionalProperties: false
      properties:
        taskType:
          type: string
          description: "Unified task type."
        taskId:
          type: string
          description: "Task ID."
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        status:
          type: string
          description: "Unified status."
        rawStatus:
          type: string
          description: "Underlying task status."
        targetId:
          type: string
          description: "Target conversation ID for send tasks."
        messageType:
          type: string
          description: "Message type for send tasks."
        resourceId:
          type: string
          description: "Media resource ID for media tasks."
        resourceType:
          type: string
          description: "Media resource type for media tasks."
        objectId:
          type: string
          description: "Finder object ID for Finder tasks."
        objectNonceId:
          type: string
          description: "Finder object nonce ID when available."
        finderUsername:
          type: string
          description: "Finder username when available."
        clientActionId:
          type: string
          description: "Client action ID for write tasks."
        proposalId:
          type: string
          description: "Proposal ID when a human/agent proposal exists."
        errorCode:
          type: string
          description: "Failure code when available."
        errorMessage:
          type: string
          description: "Redacted failure message when available."
        createdAt:
          type: string
          description: "Creation time."
        updatedAt:
          type: string
          description: "Update time."
        completedAt:
          type: string
          description: "Completion time when available."
        data:
          type: object
          required:
[]
          additionalProperties: true
          properties:
{}
    PersonalWechatBindSession:
      type: object
      required:
        - bindSessionId
        - accountId
        - internalInstanceId
        - cloudKeyId
        - protocolDeviceType
        - status
        - createdAt
      additionalProperties: false
      properties:
        bindSessionId:
          type: string
          description: "Cloud bind session ID."
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        internalInstanceId:
          type: string
          description: "Internal protocol runtime ID."
        hostDeviceId:
          type: string
          description: "Host device ID."
        cloudKeyId:
          type: string
          description: "Cloud key slot ID, not the raw WeChat key."
        wechatKeyId:
          type: string
          description: "Key slot ID kept for backward compatibility, not the raw WeChat key."
        protocolDeviceType:
          type: string
          description: "Protocol device profile type."
        protocolDeviceProfileVersion:
          type: string
          description: "Protocol device profile version."
        allowedProtocolDeviceTypes:
          type: array
          description: "Allowed protocol device profile types."
          items:
            type: string
        defaultProtocolDeviceType:
          type: string
          description: "Default protocol device profile type."
        allowProtocolDeviceSwitch:
          type: boolean
          description: "Whether the caller may switch protocol device profile."
        seatIndex:
          type: integer
          description: "Wechat seat index."
        seatId:
          type: string
          description: "Wechat seat ID."
        proxyRequired:
          type: boolean
          description: "Whether proxy is required."
        proxyBypassed:
          type: boolean
          description: "Whether proxy was bypassed."
        proxyLease:
          type: object
          required:
[]
          additionalProperties: true
          properties:
{}
        entitlement:
          type: object
          required:
[]
          additionalProperties: true
          properties:
{}
        status:
          type: string
          description: "Bind session status."
        lastEvent:
          type: string
          description: "Latest bind session event."
        createdAt:
          type: string
          description: "Creation time."
        updatedAt:
          type: string
          description: "Update time."
    PersonalWechatProfile:
      type: object
      required:
        - accountId
        - displayName
        - mode
        - source
        - syncRequired
        - runtime
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        displayName:
          type: string
          description: "Account display name."
        avatarUrl:
          type: string
          description: "Avatar URL when available."
        bindSessionId:
          type: string
          description: "Cloud bind session ID."
        cloudKeyId:
          type: string
          description: "Cloud key slot ID, not the raw WeChat key."
        protocolDeviceType:
          type: string
          description: "Protocol device profile type."
        hostDeviceId:
          type: string
          description: "Host device ID."
        mode:
          type: string
          description: "Runtime mode."
        source:
          type: string
          description: "Profile data source."
        syncRequired:
          type: boolean
          description: "Whether a protocol sync task is still required for fresher data."
        runtime:
          type: object
          required:
[]
          additionalProperties: true
          properties:
{}
        latestEventAt:
          type: string
          description: "Latest cached event time."
    PersonalWechatCapabilityDirectory:
      type: object
      required:
        - accountId
        - mode
        - available
        - unavailable
        - runtime
        - storage
        - notes
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        mode:
          type: string
          description: "Runtime mode."
        available:
          type: array
          description: "Available capability codes."
          items:
            type: string
        unavailable:
          type: array
          description: "Unavailable capability codes."
          items:
            type: string
        runtime:
          type: object
          required:
            - status
            - health
            - workerId
          additionalProperties: false
          properties:
            status:
              type: string
              description: "Runtime availability status."
            health:
              type: string
              description: "Worker health status."
            workerId:
              type: string
              description: "Worker ID when available."
        storage:
          type: object
          required:
            - objectStorageEnabled
            - storageAvailableBytes
            - maxFileSizeBytes
          additionalProperties: false
          properties:
            objectStorageEnabled:
              type: boolean
              description: "Whether object storage is enabled."
            storageAvailableBytes:
              type: integer
              description: "Remaining storage quota."
            maxFileSizeBytes:
              type: integer
              description: "Maximum upload size."
        notes:
          type: array
          description: "Human-readable boundary notes."
          items:
            type: string
    PersonalWechatScopeItem:
      type: object
      required:
        - scope
        - capability
        - description
        - enabled
      additionalProperties: false
      properties:
        scope:
          type: string
          description: "OAuth-like public scope name."
        capability:
          type: string
          description: "Internal capability code."
        description:
          type: string
          description: "Human-readable scope description."
        enabled:
          type: boolean
          description: "Whether this scope is currently enabled."
    PersonalWechatScopeDirectory:
      type: object
      required:
        - accountId
        - scopes
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        scopes:
          type: array
          items:
            "$ref": "#/components/schemas/PersonalWechatScopeItem"
    PersonalWechatActionValidation:
      type: object
      required:
        - accountId
        - action
        - targetId
        - allowed
        - requiredCapability
        - riskLevel
        - requiresProposal
        - reason
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        action:
          type: string
          description: "Action code to validate."
        targetId:
          type: string
          description: "Target conversation or resource ID."
        allowed:
          type: boolean
          description: "Whether the action may be executed."
        requiredCapability:
          type: string
          description: "Required capability code."
        riskLevel:
          type: string
          description: "low, medium, or high."
        requiresProposal:
          type: boolean
          description: "Whether a proposal or approval is required."
        reason:
          type: string
          description: "Redacted denial reason when not allowed."
    PersonalWechatMessageTypeCatalog:
      type: object
      required:
        - accountId
        - schemaVersion
        - messageTypes
        - conversationTypes
        - displayCategories
        - resourceStatuses
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        schemaVersion:
          type: string
          description: "Catalog schema version."
        messageTypes:
          type: array
          description: "Supported normalized message type codes."
          items:
            type: string
        conversationTypes:
          type: array
          description: "Supported conversation type codes."
          items:
            type: string
        displayCategories:
          type: array
          description: "Supported UI display category codes."
          items:
            type: string
        resourceStatuses:
          type: array
          description: "Supported media resource status codes."
          items:
            type: string
    ProtocolRuntimeState:
      type: object
      required:
        - accountId
        - internalInstanceId
        - bindSessionId
        - cloudKeyId
        - status
        - updatedAt
      additionalProperties: false
      properties:
        accountId:
          type: string
          description: "Product-level WeChat account ID."
        internalInstanceId:
          type: string
          description: "Internal protocol runtime ID."
        bindSessionId:
          type: string
          description: "Cloud bind session ID."
        cloudKeyId:
          type: string
          description: "Cloud key slot ID, not the raw WeChat key."
        hostDeviceId:
          type: string
          description: "Host device ID."
        protocolDeviceType:
          type: string
          description: "Protocol device profile type."
        protocolDeviceProfileVersion:
          type: string
          description: "Protocol device profile version."
        status:
          type: string
          description: "Runtime status."
        bindStatus:
          type: string
          description: "Bind session status."
        workerId:
          type: string
          description: "Worker ID when available."
        workerLeaseExpiresAt:
          type: string
          description: "Worker lease expiry time."
        health:
          type: object
          required:
[]
          additionalProperties: true
          properties:
{}
        recover:
          type: object
          required:
[]
          additionalProperties: true
          properties:
{}
        updatedAt:
          type: string
          description: "Update time."
    MediaResourceResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/MediaResource"
    RuntimeSummaryResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/ProtocolRuntimeState"
    PersonalWechatBindSessionResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatBindSession"
    PersonalWechatProfileResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatProfile"
    PersonalWechatCapabilityDirectoryResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatCapabilityDirectory"
    PersonalWechatScopeDirectoryResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatScopeDirectory"
    PersonalWechatActionValidationResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatActionValidation"
    PersonalWechatContactPageResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatContactPage"
    PersonalWechatLabelPageResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatLabelPage"
    PersonalWechatGroupPageResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatGroupPage"
    PersonalWechatGroupResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatGroup"
    PersonalWechatGroupProtocolRequiredResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatGroupProtocolRequired"
    PersonalWechatConversationPageResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatConversationPage"
    PersonalWechatMessagePageResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatMessagePage"
    PersonalWechatOfficialAccountPageResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatOfficialAccountPage"
    PersonalWechatOfficialHubResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatOfficialHub"
    PersonalWechatRecipientResolveResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatRecipientResolveResult"
    PersonalWechatMessageTypeCatalogResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/PersonalWechatMessageTypeCatalog"
    ProtocolGenericTaskResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/ProtocolGenericTask"
    UnifiedProtocolTaskResponse:
      type: object
      required:
        - data
      additionalProperties: false
      properties:
        data:
          "$ref": "#/components/schemas/UnifiedProtocolTask"
    EmptyJsonRequest:
      type: object
      required:
[]
      additionalProperties: false
      description: "Empty JSON request body for POST endpoints that currently use path parameters only."
      properties:
{}
    PersonalWechatAccountCreateRequest:
      type: object
      required:
[]
      additionalProperties: false
      description: "Create or update a pending personal WeChat cloud account record without raw protocol fields."
      properties:
        accountId:
          type: string
          description: "Optional client-provided product account ID."
        displayName:
          type: string
          description: "Display name for the pending cloud-mounted account."
        deviceId:
          type: string
          description: "Host device ID used only as client metadata."
    PersonalWechatBindSessionCreateRequest:
      type: object
      required:
[]
      additionalProperties: false
      description: "Create a cloud QR bind session. Raw WeChat Key, Data62, login state, and proxy credentials are forbidden."
      properties:
        deviceId:
          type: string
          description: "Host device ID used by the local sidecar."
        reconnectAccountId:
          type: string
          description: "Existing account ID when reconnecting an occupied WeChat seat."
        protocolDeviceType:
          type: string
          description: "Requested protocol device profile type, such as ipad or mac."
        localAccountCount:
          type: integer
          description: "Local account count used for single-seat guardrails."
    PersonalWechatActionValidateRequest:
      type: object
      required:
        - action
      additionalProperties: false
      description: "Pre-validate a personal WeChat action before execution."
      properties:
        action:
          type: string
          description: "Action code, for example message.send_text or task.retry."
        targetId:
          type: string
          description: "Target conversation, group, media, or task ID."
        reason:
          type: string
          description: "Redacted business reason."
    ProtocolGenericTaskRequest:
      type: object
      required:
[]
      additionalProperties: false
      description: "Generic protocol control task request. Private protocol fields, chat bodies, proxy credentials, and AI private data are forbidden."
      properties:
        sinceCursor:
          type: string
          description: "Cursor for sync-like tasks."
        cursor:
          type: string
          description: "Compatibility alias for sinceCursor."
        targetId:
          type: string
          description: "Target conversation ID."
        groupId:
          type: string
          description: "Group chat ID."
        userName:
          type: string
          description: "Contact username or wxid surrogate."
        query:
          type: string
          description: "Search query."
        ids:
          type: array
          description: "Explicit target IDs."
          items:
            type: string
        limit:
          type: integer
          description: "Requested result limit."
        reason:
          type: string
          description: "Redacted request reason."
    FinderDetailRequest:
      type: object
      required:
        - objectId
      additionalProperties: false
      description: "Create or read a Finder detail parsing task. Playback URLs, urlToken, decodeKey, comments, and raw protocol fields are forbidden."
      properties:
        objectId:
          type: string
          description: "Finder object ID."
        objectNonceId:
          type: string
          description: "Finder object nonce ID when available."
        finderUsername:
          type: string
          description: "Finder username when available."
        encryptedObjectId:
          type: string
          description: "Encrypted object ID when available."
        lastBuffer:
          type: string
          description: "Pagination or continuation buffer when provided by the protocol layer."
        traceId:
          type: string
          description: "Optional caller trace ID."
    MediaResourceRequest:
      type: object
      required:
        - type
        - sizeBytes
      additionalProperties: false
      description: "Register or create a media resource. Temporary WeChat URLs, urlToken, decodeKey, and proxy credentials are forbidden."
      properties:
        resourceId:
          type: string
          description: "Optional caller-provided media resource ID."
        type:
          type: string
          description: "Media resource type, such as image, video, voice, file, finder_cover, or upload_asset."
        resourceType:
          type: string
          description: "Compatibility alias for type."
        mimeType:
          type: string
          description: "MIME type."
        sizeBytes:
          type: integer
          description: "Resource size in bytes."
        fileName:
          type: string
          description: "Original file name used only for object-key derivation."
        objectKey:
          type: string
          description: "Optional COS object key scoped by tenant/user/account."
        messageId:
          type: string
          description: "Related message ID when resolving an inbound media resource."
        finderObjectId:
          type: string
          description: "Related Finder object ID."
        targetId:
          type: string
          description: "Related conversation target ID."
    MediaResourceBatchSignRequest:
      type: object
      required:
        - resourceIds
      additionalProperties: false
      description: "Sign multiple media resources with short-lived URLs. Raw object storage secrets are never accepted."
      properties:
        resourceIds:
          type: array
          description: "Media resource IDs to sign."
          items:
            type: string
    RecipientResolveRequest:
      type: object
      required:
[]
      additionalProperties: false
      description: "Resolve display text or IDs into sendable conversation targets."
      properties:
        query:
          type: string
          description: "Single recipient query."
        queries:
          type: array
          description: "Batch recipient queries."
          items:
            type: string
        targetId:
          type: string
          description: "Compatibility input used as a recipient query."
    RecoverRequest:
      type: object
      required:
[]
      additionalProperties: false
      description: "Request protocol runtime recovery without sending raw login state or protocol secrets."
      properties:
        reason:
          type: string
          description: "Redacted recovery reason."
        workerId:
          type: string
          description: "Preferred worker ID when manually targeting recovery."
    TaskMutationRequest:
      type: object
      required:
[]
      additionalProperties: false
      description: "Retry or cancel a queued task."
      properties:
        reason:
          type: string
          description: "Redacted retry or cancellation reason."
    ProtocolHealthUpdateRequest:
      type: object
      required:
        - status
      additionalProperties: false
      description: "Internal worker account health update. Proxy credentials and protocol secrets are forbidden."
      properties:
        status:
          type: string
          description: "Worker-reported account health status."
        workerId:
          type: string
          description: "Worker ID."
        runtimeShardId:
          type: string
          description: "Worker runtime shard ID."
        workerCursor:
          type: string
          description: "Worker event cursor."
        queueLagMs:
          type: integer
          description: "Queue lag in milliseconds."
        latencyMs:
          type: integer
          description: "Worker latency in milliseconds."
        reconnectCount:
          type: integer
          description: "Reconnect count."
        lastError:
          type: string
          description: "Redacted latest error."
    ObjectStorageResult:
      type: object
      required:
[]
      additionalProperties: false
      description: "Object storage writeback result without temporary WeChat URL secrets."
      properties:
        provider:
          type: string
          description: "Object storage provider, normally cos."
        bucket:
          type: string
          description: "Bucket name."
        region:
          type: string
          description: "Bucket region."
        objectKey:
          type: string
          description: "COS object key."
        mimeType:
          type: string
          description: "MIME type."
        sizeBytes:
          type: integer
          description: "Object size in bytes."
        checksum:
          type: string
          description: "Checksum when available."
    ProtocolMediaResourceResultRequest:
      type: object
      required:
        - resourceId
      additionalProperties: false
      description: "Internal worker media-resource writeback. Temporary URLs, urlToken, decodeKey, and raw protocol secrets are forbidden."
      properties:
        resourceId:
          type: string
          description: "Media resource ID."
        status:
          type: string
          description: "available, failed, pending, or uploading."
        mimeType:
          type: string
          description: "MIME type."
        sizeBytes:
          type: integer
          description: "Object size in bytes."
        objectStorage:
          "$ref": "#/components/schemas/ObjectStorageResult"
        checksum:
          type: string
          description: "Checksum when available."
        errorCode:
          type: string
          description: "Failure code when available."
        errorMessage:
          type: string
          description: "Redacted failure message when available."
  responses:
    BadRequest:
      description: "Invalid request."
      content:
        "application/json":
          schema:
            "$ref": "#/components/schemas/ApiError"
    Unauthorized:
      description: "Missing or invalid authentication."
      content:
        "application/json":
          schema:
            "$ref": "#/components/schemas/ApiError"
    Forbidden:
      description: "Capability or account access denied."
      content:
        "application/json":
          schema:
            "$ref": "#/components/schemas/ApiError"
tags:
  -
    name: Health
    description: "Readiness and deployment health probes."
  -
    name: "Personal WeChat Accounts"
    description: "Personal WeChat account creation, binding, profile, online state, runtime summary, and recovery."
  -
    name: "Personal WeChat Events"
    description: "Cursor-based personal WeChat protocol event reads with redacted payload boundaries."
  -
    name: "Personal WeChat Conversations"
    description: "Conversation and normalized message reads built from cloud-side event cache."
  -
    name: "Personal WeChat Messaging"
    description: "Message sync, message normalization, message type catalog, text send tasks, and send status reads."
  -
    name: "Personal WeChat Contacts"
    description: "Contacts, labels, contact search tasks, and recipient resolution."
  -
    name: "Personal WeChat Groups"
    description: "Group list, search, detail, member, QR code, and group sync tasks."
  -
    name: "Personal WeChat Official Accounts"
    description: "Official account list, hub, and official account message reads."
  -
    name: "Personal WeChat Media"
    description: "Object storage entitlement, media resource registration, upload, status, and short-lived signing."
  -
    name: "Personal WeChat Finder and SNS"
    description: "Finder search/detail tasks and SNS timeline or user-page tasks."
  -
    name: "Personal WeChat Tasks"
    description: "Unified task status, retry, cancellation, and action pre-validation."
  -
    name: "Enterprise WeChat Reserved"
    description: "Reserved enterprise WeChat capability namespace for future independent implementation."
  -
    name: "Protocol Workers"
    description: "Internal protocol worker claim, health, and result writeback endpoints."
