@leaflow/sdk 0.1.3 → 0.3.0

package/openapi/assistant.yaml

@@ -1,6 +1,6 @@
 components:
   schemas:
-    AnswerInputBody:
+    AnswerRequestBody:
       additionalProperties: false
       properties:
         answers:
@@ -11,7 +11,7 @@ components:
       required:
         - answers
       type: object
-    AttachmentView:
+    AttachmentResource:
       additionalProperties: false
       properties:
         height:
@@ -27,7 +27,7 @@ components:
         - width
         - height
       type: object
-    BindingView:
+    BindingResource:
       additionalProperties: false
       properties:
         channelId:
@@ -59,7 +59,7 @@ components:
         - verifiedAt
         - createdAt
       type: object
-    ChannelView:
+    ChannelResource:
       additionalProperties: false
       properties:
         allowFrom:
@@ -86,7 +86,13 @@ components:
           format: date-time
           type: string
         webhookPath:
+          description: 回调路径，网关配置和排查时用
           type: string
+        webhookUrl:
+          description: 填到平台后台的回调地址。部署未声明公网入口时为 null
+          type:
+            - string
+            - "null"
       required:
         - id
         - platform
@@ -94,6 +100,7 @@ components:
         - status
         - senderPolicy
         - allowFrom
+        - webhookUrl
         - webhookPath
         - createdAt
         - updatedAt
@@ -109,7 +116,7 @@ components:
         - label
         - description
       type: object
-    ClaimCodeOutputBody:
+    ClaimCodeResponseBody:
       additionalProperties: false
       properties:
         code:
@@ -121,7 +128,7 @@ components:
         - code
         - expiresAt
       type: object
-    ContextView:
+    ContextResource:
       additionalProperties: false
       properties:
         compactAt:
@@ -151,7 +158,7 @@ components:
         - compactAt
         - warnAt
       type: object
-    CreateChannelInputBody:
+    CreateChannelRequestBody:
       additionalProperties: false
       properties:
         allowFrom:
@@ -179,7 +186,7 @@ components:
         - platform
         - name
       type: object
-    CreateThreadInputBody:
+    CreateThreadRequestBody:
       additionalProperties: false
       properties:
         approvalMode:
@@ -190,7 +197,27 @@ components:
             - yolo
           type: string
       type: object
-    DecideInputBody:
+    CredentialFieldResource:
+      additionalProperties: false
+      properties:
+        help:
+          type: string
+        key:
+          type: string
+        label:
+          type: string
+        required:
+          type: boolean
+        secret:
+          type: boolean
+      required:
+        - key
+        - label
+        - required
+        - secret
+        - help
+      type: object
+    DecideRequestBody:
       additionalProperties: false
       properties:
         approved:
@@ -200,35 +227,35 @@ components:
       required:
         - approved
       type: object
-    DocumentView:
+    DocumentResource:
       additionalProperties: false
       properties:
         context:
-          $ref: "#/components/schemas/ContextView"
+          $ref: "#/components/schemas/ContextResource"
         cursor:
           type:
             - string
             - "null"
         earlier:
-          $ref: "#/components/schemas/EarlierView"
+          $ref: "#/components/schemas/EarlierResource"
         items:
           items:
-            $ref: "#/components/schemas/ItemView"
+            $ref: "#/components/schemas/ItemResource"
           type:
             - array
             - "null"
         status:
           type: string
         stream:
-          $ref: "#/components/schemas/StreamView"
+          $ref: "#/components/schemas/StreamResource"
         turn:
-          $ref: "#/components/schemas/TurnView"
+          $ref: "#/components/schemas/TurnResource"
         turnId:
           type:
             - string
             - "null"
         wait:
-          $ref: "#/components/schemas/WaitView"
+          $ref: "#/components/schemas/WaitResource"
       required:
         - turnId
         - stream
@@ -240,7 +267,7 @@ components:
         - wait
         - turn
       type: object
-    EarlierView:
+    EarlierResource:
       additionalProperties: false
       properties:
         before:
@@ -252,31 +279,20 @@ components:
         - before
         - foldedAbove
       type: object
-    Entry:
+    EarlierResponseBody:
       additionalProperties: false
       properties:
-        at:
-          format: date-time
-          type: string
-        peer_id:
-          type: string
-        peer_name:
-          type: string
-        peer_username:
-          type: string
-        platform:
-          type: string
-        text_length:
-          format: int64
-          type: integer
-        verdict:
-          type: string
+        earlier:
+          $ref: "#/components/schemas/EarlierResource"
+        items:
+          items:
+            $ref: "#/components/schemas/ItemResource"
+          type:
+            - array
+            - "null"
       required:
-        - peer_id
-        - platform
-        - verdict
-        - text_length
-        - at
+        - items
+        - earlier
       type: object
     Error:
       additionalProperties: false
@@ -295,7 +311,7 @@ components:
         - status
         - message
       type: object
-    ItemView:
+    ItemResource:
       additionalProperties: false
       properties:
         approval:
@@ -315,7 +331,7 @@ components:
           type: string
         attachments:
           items:
-            $ref: "#/components/schemas/AttachmentView"
+            $ref: "#/components/schemas/AttachmentResource"
           type:
             - array
             - "null"
@@ -334,7 +350,7 @@ components:
         id:
           type: string
         model:
-          description: 这一行是哪个模型产出的。人打的字上是 null
+          description: 产出这一条的模型。用户自己发的消息为 null
           type:
             - string
             - "null"
@@ -367,7 +383,7 @@ components:
             - string
             - "null"
         type:
-          description: 客户端按它 switch 出这一行的形状
+          description: 决定这一条包含哪些字段
           enum:
             - user_message
             - agent_message
@@ -385,87 +401,59 @@ components:
         - reverted
         - model
       type: object
-    ListBindingsOutputBody:
+    LengthAwarePageBindingResource:
       additionalProperties: false
       properties:
-        bindings:
+        items:
+          description: 这一页的内容
           items:
-            $ref: "#/components/schemas/BindingView"
-          type:
-            - array
-            - "null"
+            $ref: "#/components/schemas/BindingResource"
+          type: array
+        limit:
+          description: 这一页最多几条，回显请求里的值
+          format: int64
+          type: integer
+        offset:
+          description: 跳过了多少条，回显请求里的值
+          format: int64
+          type: integer
         total:
+          description: 命中的总条数，不只是这一页
           format: int64
           type: integer
       required:
-        - bindings
+        - items
         - total
+        - limit
+        - offset
       type: object
-    ListChannelsOutputBody:
+    LengthAwarePageChannelResource:
       additionalProperties: false
       properties:
-        channels:
+        items:
+          description: 这一页的内容
           items:
-            $ref: "#/components/schemas/ChannelView"
-          type:
-            - array
-            - "null"
+            $ref: "#/components/schemas/ChannelResource"
+          type: array
+        limit:
+          description: 这一页最多几条，回显请求里的值
+          format: int64
+          type: integer
+        offset:
+          description: 跳过了多少条，回显请求里的值
+          format: int64
+          type: integer
         total:
+          description: 命中的总条数，不只是这一页
           format: int64
           type: integer
       required:
-        - channels
+        - items
         - total
+        - limit
+        - offset
       type: object
-    ListModelsOutputBody:
-      additionalProperties: false
-      properties:
-        models:
-          items:
-            $ref: "#/components/schemas/ModelView"
-          type:
-            - array
-            - "null"
-      required:
-        - models
-      type: object
-    ListPlatformsOutputBody:
-      additionalProperties: false
-      properties:
-        platforms:
-          items:
-            $ref: "#/components/schemas/PlatformView"
-          type:
-            - array
-            - "null"
-      required:
-        - platforms
-      type: object
-    ListRejectionsOutputBody:
-      additionalProperties: false
-      properties:
-        rejections:
-          items:
-            $ref: "#/components/schemas/Entry"
-          type:
-            - array
-            - "null"
-      required:
-        - rejections
-      type: object
-    ListThreadsOutputBody:
-      additionalProperties: false
-      properties:
-        threads:
-          items:
-            $ref: "#/components/schemas/ThreadSummaryView"
-          type:
-            - array
-            - "null"
-      required:
-        - threads
-      type: object
-    LoginView:
+    LoginResource:
       additionalProperties: false
       properties:
         expiresAt:
@@ -490,7 +478,19 @@ components:
         - reason
         - expiresAt
       type: object
-    ModelView:
+    ModelListResponseBody:
+      additionalProperties: false
+      properties:
+        models:
+          items:
+            $ref: "#/components/schemas/ModelResource"
+          type:
+            - array
+            - "null"
+      required:
+        - models
+      type: object
+    ModelResource:
       additionalProperties: false
       properties:
         contextWindow:
@@ -516,19 +516,65 @@ components:
         - reasoningTiers
         - inputModalities
       type: object
-    PlatformView:
+    PlatformListResponseBody:
+      additionalProperties: false
+      properties:
+        platforms:
+          items:
+            $ref: "#/components/schemas/PlatformResource"
+          type:
+            - array
+            - "null"
+      required:
+        - platforms
+      type: object
+    PlatformResource:
       additionalProperties: false
       properties:
+        credentialFields:
+          items:
+            $ref: "#/components/schemas/CredentialFieldResource"
+          type:
+            - array
+            - "null"
         name:
           type: string
         resident:
           type: boolean
+        secretSource:
+          enum:
+            - generated
+            - supplied
+            - none
+          type: string
+        setupChallenge:
+          enum:
+            - none
+            - webhook
+            - scan
+          type: string
+        setupMethod:
+          enum:
+            - credentials
+            - scan
+          type: string
         webhookPath:
+          description: 回调路径模板，{channel} 处替换为通道 id
           type: string
+        webhookUrlTemplate:
+          description: 完整回调地址模板。部署未声明公网入口时为 null
+          type:
+            - string
+            - "null"
       required:
         - name
         - resident
+        - setupMethod
+        - setupChallenge
+        - secretSource
+        - credentialFields
         - webhookPath
+        - webhookUrlTemplate
       type: object
     Question:
       additionalProperties: false
@@ -551,7 +597,47 @@ components:
         - question
         - choices
       type: object
-    RevertInputBody:
+    RejectionListResponseBody:
+      additionalProperties: false
+      properties:
+        rejections:
+          items:
+            $ref: "#/components/schemas/RejectionResource"
+          type:
+            - array
+            - "null"
+      required:
+        - rejections
+      type: object
+    RejectionResource:
+      additionalProperties: false
+      properties:
+        at:
+          format: date-time
+          type: string
+        peerId:
+          type: string
+        peerName:
+          type: string
+        peerUsername:
+          type: string
+        platform:
+          type: string
+        textLength:
+          format: int64
+          type: integer
+        verdict:
+          type: string
+      required:
+        - peerId
+        - peerName
+        - peerUsername
+        - platform
+        - verdict
+        - textLength
+        - at
+      type: object
+    RevertRequestBody:
       additionalProperties: false
       properties:
         ordinal:
@@ -561,7 +647,7 @@ components:
       required:
         - ordinal
       type: object
-    RevertOutputBody:
+    RevertedCountResponseBody:
       additionalProperties: false
       properties:
         reverted:
@@ -570,15 +656,14 @@ components:
       required:
         - reverted
       type: object
-    RotateSecretOutputBody:
+    RotateSecretRequestBody:
       additionalProperties: false
       properties:
         webhookSecret:
+          description: 平台生成密钥的平台（secretSource=supplied）必须传新的那把；我们生成的（generated）不能传
           type: string
-      required:
-        - webhookSecret
       type: object
-    SendMessageInputBody:
+    SendMessageRequestBody:
       additionalProperties: false
       properties:
         attachmentIds:
@@ -593,26 +678,61 @@ components:
       required:
         - text
       type: object
-    SendMessageOutputBody:
+    SenderCheckResource:
       additionalProperties: false
       properties:
-        turnId:
+        allowFrom:
+          items:
+            type: string
+          type:
+            - array
+            - "null"
+        allowed:
+          type: boolean
+        bindingId:
+          type:
+            - string
+            - "null"
+        senderPolicy:
+          type: string
+        verdict:
+          enum:
+            - ALLOWED_BY_BINDING
+            - ALLOWED_BY_ALLOW_FROM
+            - ALLOWED_BY_POLICY
+            - REJECTED_NOT_ALLOWED
           type: string
       required:
-        - turnId
+        - allowed
+        - verdict
+        - senderPolicy
+        - allowFrom
+        - bindingId
       type: object
-    StreamView:
+    StreamResource:
       additionalProperties: false
       properties:
-        ticket:
+        path:
           type: string
-        url:
+        ticket:
           type: string
       required:
-        - url
+        - path
         - ticket
       type: object
-    ThreadSummaryView:
+    ThreadListResponseBody:
+      additionalProperties: false
+      properties:
+        threads:
+          items:
+            $ref: "#/components/schemas/ThreadSummaryResource"
+          type:
+            - array
+            - "null"
+      required:
+        - threads
+      type: object
+    ThreadSummaryResource:
       additionalProperties: false
       properties:
         approvalMode:
@@ -649,7 +769,15 @@ components:
         - unread
         - approvalMode
       type: object
-    TurnView:
+    TurnIDResponseBody:
+      additionalProperties: false
+      properties:
+        turnId:
+          type: string
+      required:
+        - turnId
+      type: object
+    TurnResource:
       additionalProperties: false
       properties:
         approvalMode:
@@ -661,20 +789,34 @@ components:
       required:
         - approvalMode
       type: object
-    UpdateChannelInputBody:
+    UpdateChannelRequestBody:
       additionalProperties: false
       properties:
+        allowFrom:
+          description: 放行名单。仅在同时传了 senderPolicy 时生效
+          items:
+            type: string
+          type:
+            - array
+            - "null"
         credentials:
           additionalProperties:
             type: string
+          description: 整份替换而不是逐键合并。不传表示不动
           type: object
         enabled:
           type: boolean
         name:
           maxLength: 128
           type: string
+        senderPolicy:
+          description: 传了才会连同 allowFrom 一起替换
+          enum:
+            - BOUND_ONLY
+            - OPEN
+          type: string
       type: object
-    UpdateThreadInputBody:
+    UpdateThreadRequestBody:
       additionalProperties: false
       properties:
         approvalMode:
@@ -690,7 +832,7 @@ components:
         reasoningEffort:
           type: string
       type: object
-    UploadedView:
+    UploadedResource:
       additionalProperties: false
       properties:
         height:
@@ -706,7 +848,7 @@ components:
         - width
         - height
       type: object
-    VerifyCodeInputBody:
+    VerifyCodeRequestBody:
       additionalProperties: false
       properties:
         code:
@@ -714,7 +856,7 @@ components:
       required:
         - code
       type: object
-    WaitView:
+    WaitResource:
       additionalProperties: false
       properties:
         autoResolutionMs:
@@ -747,24 +889,46 @@ components:
         - kind
         - turnId
       type: object
+    WebhookSecretResponseBody:
+      additionalProperties: false
+      properties:
+        webhookSecret:
+          type: string
+      required:
+        - webhookSecret
+      type: object
+  securitySchemes:
+    bearerAuth:
+      bearerFormat: JWT
+      description: 项目令牌。先在 auth.leaflow.net 登录拿到账号令牌，再用它向 IAM 换取项目令牌（POST /api/v1/projects/{projectId}/token）——一张项目令牌同时说明当前用户和当前项目。
+      scheme: bearer
+      type: http
 info:
   description: |-
-    助手对话及其接入面：线程、逐字稿、一次 turn 的执行与流式输出、工具调用与审批、追问、技能，以及通道、绑定和微信扫码登录。
+    控制台里的 AI 助手：对话、消息、工具调用与审批、附件，以及把助手接到微信、飞书、Telegram 等即时通讯平台上。
+
+    ## 一次对话
 
-    ## 认证
+    1. `POST /v1/threads` 创建对话；
+    2. `POST /v1/threads/{thread}/messages` 发送消息，立即返回 `turnId`，助手的执行在后台进行；
+    3. `GET /v1/threads/{thread}` 取回对话文档用于渲染，并按其中的 `stream` 连上实时输出；
+    4. 助手需要用户参与时，文档中的 `wait` 会说明是哪一种：审批一批工具调用（`POST /v1/threads/{thread}/approvals/{batch}`），或回答几个问题（`POST /v1/threads/{thread}/questions/{item}`）。处理完成后助手自动继续。
 
-    所有接口都要求 `Authorization: Bearer <项目令牌>`。项目令牌向 `POST /api/v1/projects/{projectId}/token` 换取，登录服务是 auth.leaflow.net。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 `project_id`。
+    发送图片分两步：先 `POST /v1/attachments` 上传拿到 id，发送消息时放进 `attachmentIds`。
 
-    令牌无效或过期返回 401，不是当前项目的成员返回 403。这两种都应重新换取令牌后重试；仍然失败说明这个账号在该项目里已没有权限。
+    ## 实时输出
 
-    ## 一次对话
+    ```
+    GET /v1/turns/{turn}/stream?ticket=<ticket>&cursor=<cursor>
+    ```
 
-    1. `POST /v1/threads` 创建线程；
-    2. `POST /v1/threads/{thread}/messages` 发送消息。它立即返回 `turnId`，不等待执行完成——一次 turn 可能持续数十分钟；
-    3. `GET /v1/threads/{thread}` 取回线程文档。文档中的 `stream` 给出实时输出的地址和入场票据；流推送的是对该文档的增量编辑，客户端渲染逻辑只有一套；
-    4. turn 需要人工介入时，文档中的 `wait` 说明介入类型：批准一批工具调用（`POST /v1/threads/{thread}/approvals/{batch}`），或回答提出的问题（`POST /v1/threads/{thread}/questions/{item}`）。
+    这是一条 Server-Sent Events 流，因此不在下方的接口列表中。
 
-    图片分两步发送：先 `POST /v1/attachments` 取得附件 id，再在发送消息时放进 `attachmentIds`。
+    - `path` 与 `ticket` 都取自对话文档的 `stream`。`path` 是相对路径，按取回文档的地址解析；
+    - `cursor` 是起始位置，取自对话文档的 `cursor`。不传则从可用范围的开头开始；
+    - 推送的每一条都是对那份对话文档的一次增量编辑，套用同一套渲染逻辑即可；
+    - 连接有生存期，到时会正常关闭。使用 `EventSource` 时浏览器会自动携带 `Last-Event-ID` 重连并从断点续传，无需额外处理；
+    - 三种结束事件：`done` 本次 turn 完成（附带最终状态）、`paused` 助手在等待用户处理（重新取回对话文档读 `wait`）、`stalled` 执行已中断且不会恢复，不要重连。
   title: Leaflow Assistant 用户 API
   version: 1.0.0
 openapi: 3.1.0
@@ -773,14 +937,6 @@ paths:
     post:
       description: 请求体直接是文件字节，不使用 multipart 封装，一次上传一个文件。类型由内容判定，与 Content-Type 无关。返回的 id 在发送消息时放进 attachmentIds；从未被任何消息引用的附件会被定期清除。
       operationId: upload-attachment
-      parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
       requestBody:
         content:
           application/octet-stream:
@@ -794,7 +950,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/UploadedView"
+                $ref: "#/components/schemas/UploadedResource"
           description: Created
         default:
           content:
@@ -810,13 +966,6 @@ paths:
       description: 按附件 id 取回原始字节，可直接作为 <img> 的地址使用。响应带长期缓存头，附件内容不会变化。附件不存在或不属于当前用户时返回 404。
       operationId: download-attachment
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: attachment
           required: true
@@ -836,29 +985,28 @@ paths:
         - Attachment
   /v1/bindings:
     get:
+      description: 接入面那张表按通道列出各自绑了谁时用 channelId 过滤。
       operationId: list-bindings
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
-        - explode: false
+        - description: 这一页最多返回多少条
+          explode: false
           in: query
           name: limit
           schema:
             default: 50
+            description: 这一页最多返回多少条
             format: int64
-            maximum: 100
-            minimum: 0
+            maximum: 200
+            minimum: 1
             type: integer
-        - explode: false
+        - description: 跳过多少条。要翻得更深请改用游标翻页的接口
+          explode: false
           in: query
           name: offset
           schema:
+            description: 跳过多少条。要翻得更深请改用游标翻页的接口
             format: int64
+            maximum: 10000
             minimum: 0
             type: integer
         - explode: false
@@ -866,12 +1014,25 @@ paths:
           name: platform
           schema:
             type: string
+        - explode: false
+          in: query
+          name: channelId
+          schema:
+            format: uuid
+            type: string
+        - description: 仅返回处于活跃状态的绑定
+          explode: false
+          in: query
+          name: active
+          schema:
+            description: 仅返回处于活跃状态的绑定
+            type: boolean
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListBindingsOutputBody"
+                $ref: "#/components/schemas/LengthAwarePageBindingResource"
           description: OK
         default:
           content:
@@ -886,13 +1047,6 @@ paths:
     delete:
       operationId: delete-binding
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: binding
           required: true
@@ -911,31 +1065,54 @@ paths:
       summary: 解除绑定
       tags:
         - Onboarding
-  /v1/channels:
     get:
-      operationId: list-channels
+      operationId: get-binding
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
+        - in: path
+          name: binding
           required: true
           schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
+            format: uuid
             type: string
-        - explode: false
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BindingResource"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 查看绑定
+      tags:
+        - Onboarding
+  /v1/channels:
+    get:
+      operationId: list-channels
+      parameters:
+        - description: 这一页最多返回多少条
+          explode: false
           in: query
           name: limit
           schema:
             default: 50
+            description: 这一页最多返回多少条
             format: int64
-            maximum: 100
-            minimum: 0
+            maximum: 200
+            minimum: 1
             type: integer
-        - explode: false
+        - description: 跳过多少条。要翻得更深请改用游标翻页的接口
+          explode: false
           in: query
           name: offset
           schema:
+            description: 跳过多少条。要翻得更深请改用游标翻页的接口
             format: int64
+            maximum: 10000
             minimum: 0
             type: integer
         - explode: false
@@ -955,7 +1132,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListChannelsOutputBody"
+                $ref: "#/components/schemas/LengthAwarePageChannelResource"
           description: OK
         default:
           content:
@@ -968,26 +1145,18 @@ paths:
         - Onboarding
     post:
       operationId: create-channel
-      parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
       requestBody:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/CreateChannelInputBody"
+              $ref: "#/components/schemas/CreateChannelRequestBody"
         required: true
       responses:
         "201":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ChannelView"
+                $ref: "#/components/schemas/ChannelResource"
           description: Created
         default:
           content:
@@ -1003,13 +1172,6 @@ paths:
       description: 删除后该通道不再接收入站消息，其上的绑定一并失效。项目处于停服或清理状态时本接口仍然可用。
       operationId: delete-channel
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: channel
           required: true
@@ -1031,13 +1193,6 @@ paths:
     get:
       operationId: get-channel
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: channel
           required: true
@@ -1049,7 +1204,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ChannelView"
+                $ref: "#/components/schemas/ChannelResource"
           description: OK
         default:
           content:
@@ -1061,15 +1216,9 @@ paths:
       tags:
         - Onboarding
     patch:
+      description: 只修改传了的字段。senderPolicy 与 allowFrom 是一对，由 senderPolicy 决定是否替换；改动对常驻连接要等连接重建后才生效，回调型平台立即生效。
       operationId: update-channel
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: channel
           required: true
@@ -1080,14 +1229,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/UpdateChannelInputBody"
+              $ref: "#/components/schemas/UpdateChannelRequestBody"
         required: true
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ChannelView"
+                $ref: "#/components/schemas/ChannelResource"
           description: OK
         default:
           content:
@@ -1103,13 +1252,6 @@ paths:
       description: 生成一个一次性认领码交给待绑定的人，他在该平台上用自己的账号把这个码发给助手即完成绑定。绑定只能由本人以这种方式建立，不能直接指定平台账号。认领码有有效期，过期后需重新签发。
       operationId: create-claim-code
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: channel
           required: true
@@ -1121,7 +1263,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ClaimCodeOutputBody"
+                $ref: "#/components/schemas/ClaimCodeResponseBody"
           description: Created
         default:
           content:
@@ -1137,13 +1279,6 @@ paths:
       description: 排查「发了消息但助手没有响应」时使用。按时间倒序返回最近被这条通道拒绝的入站消息及其拒绝原因，最常见的原因是发送方尚未绑定。
       operationId: list-channel-rejections
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: channel
           required: true
@@ -1164,7 +1299,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListRejectionsOutputBody"
+                $ref: "#/components/schemas/RejectionListResponseBody"
           description: OK
         default:
           content:
@@ -1177,28 +1312,68 @@ paths:
         - Onboarding
   /v1/channels/{channel}/secret:
     post:
-      description: 生成新的回调密钥并立即使旧密钥失效。新密钥仅在本次响应中返回，之后无法再次取回，请先在平台侧完成配置。
+      description: 换一把新的回调密钥，旧的立即失效，通道降回待平台确认状态。密钥归谁定由平台决定，见 list-platforms 的 secretSource：generated 的平台不要传请求体，新密钥仅在本次响应中返回、之后无法再次取回；supplied 的平台必须把平台后台那把新密钥传进来。
       operationId: rotate-channel-secret
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
+        - in: path
+          name: channel
           required: true
           schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
+            format: uuid
             type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RotateSecretRequestBody"
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WebhookSecretResponseBody"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 轮换回调密钥
+      tags:
+        - Onboarding
+  /v1/channels/{channel}/sender-check:
+    get:
+      description: 改完发件人策略之后用来自查，不发送任何消息、也不改变任何状态：它走的是和真实入站完全相同的那份判定，并说明结论由哪一条规则得出。无法推演认领码那一条——是否是认领码取决于对方发来的内容。
+      operationId: check-sender
+      parameters:
         - in: path
           name: channel
           required: true
           schema:
             format: uuid
             type: string
+        - description: 平台上那个人的 id，和绑定、被拒记录里的是同一个值
+          explode: false
+          in: query
+          name: peerId
+          required: true
+          schema:
+            description: 平台上那个人的 id，和绑定、被拒记录里的是同一个值
+            type: string
+        - description: 仅 Telegram 这类有用户名的平台填得出来，不带 @。留空即当作没有用户名
+          explode: false
+          in: query
+          name: username
+          schema:
+            description: 仅 Telegram 这类有用户名的平台填得出来，不带 @。留空即当作没有用户名
+            type: string
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/RotateSecretOutputBody"
+                $ref: "#/components/schemas/SenderCheckResource"
           description: OK
         default:
           content:
@@ -1206,7 +1381,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 轮换回调密钥
+      summary: 推演一个发件人会不会被放行
       tags:
         - Onboarding
   /v1/channels/{channel}/weixin-logins:
@@ -1214,13 +1389,6 @@ paths:
       description: 微信个人号通道需要本人扫码登录后才能收发消息。本接口返回二维码，之后轮询 `GET /v1/weixin-logins/{login}` 获取进度；状态提示需要验证码时，调用 `POST /v1/weixin-logins/{login}/verify-code` 补交。
       operationId: begin-weixin-login
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: channel
           required: true
@@ -1232,7 +1400,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/LoginView"
+                $ref: "#/components/schemas/LoginResource"
           description: Created
         default:
           content:
@@ -1245,22 +1413,14 @@ paths:
         - Onboarding
   /v1/models:
     get:
-      description: 返回本平台当前提供的模型及其上下文窗口、推理档位和支持的输入类型。用于填充对话设置里的模型选择。清单与项目无关，但仍需要有效的项目令牌。
+      description: 返回本平台当前提供的模型及其上下文窗口、推理档位和支持的输入类型。用于填充对话设置里的模型选择。
       operationId: list-models
-      parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListModelsOutputBody"
+                $ref: "#/components/schemas/ModelListResponseBody"
           description: OK
         default:
           content:
@@ -1273,22 +1433,14 @@ paths:
         - Thread
   /v1/platforms:
     get:
-      description: 返回本平台当前支持接入的即时通讯平台，以及各自建通道时需要提供的凭据字段。用于填充新建通道表单。
+      description: 返回本平台当前支持接入的即时通讯平台，以及各自建通道时要走的流程和要填的凭据字段。新建通道表单完全由这份响应驱动：setupMethod 决定展示录入表单还是扫码流程，credentialFields 是要填的字段，secretSource 决定要不要有回调密钥那一栏。
       operationId: list-platforms
-      parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListPlatformsOutputBody"
+                $ref: "#/components/schemas/PlatformListResponseBody"
           description: OK
         default:
           content:
@@ -1301,21 +1453,23 @@ paths:
         - Onboarding
   /v1/threads:
     get:
+      description: 按最近活动排序，只返回当前账号在当前项目里的对话。archived 是一个二选一的开关而不是「包含归档」：归档的对话不出现在默认列表里，要看它们就把这个参数打开。
       operationId: list-threads
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
+        - description: 按标题搜索，大小写不敏感。留空则返回最近的对话
+          explode: false
+          in: query
+          name: q
           schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
+            description: 按标题搜索，大小写不敏感。留空则返回最近的对话
+            maxLength: 100
             type: string
-        - description: 仅返回已归档的对话
+        - description: 为真时**只**返回已归档的对话，否则只返回未归档的
           explode: false
           in: query
           name: archived
           schema:
-            description: 仅返回已归档的对话
+            description: 为真时**只**返回已归档的对话，否则只返回未归档的
             type: boolean
         - explode: false
           in: query
@@ -1330,7 +1484,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListThreadsOutputBody"
+                $ref: "#/components/schemas/ThreadListResponseBody"
           description: OK
         default:
           content:
@@ -1343,26 +1497,18 @@ paths:
         - Thread
     post:
       operationId: create-thread
-      parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
       requestBody:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/CreateThreadInputBody"
+              $ref: "#/components/schemas/CreateThreadRequestBody"
         required: true
       responses:
         "201":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ThreadSummaryView"
+                $ref: "#/components/schemas/ThreadSummaryResource"
           description: Created
         default:
           content:
@@ -1378,13 +1524,6 @@ paths:
       description: 对话的完整当前状态，用于首屏渲染。文档中的 stream 给出实时输出地址和入场票据，流推送的是对这份文档的增量编辑，可直接套用同一套渲染逻辑。
       operationId: get-thread
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: thread
           required: true
@@ -1395,7 +1534,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/DocumentView"
+                $ref: "#/components/schemas/DocumentResource"
           description: OK
         default:
           content:
@@ -1410,13 +1549,6 @@ paths:
       description: 可修改模型、推理档位、审批模式和归档状态。改动从下一次 turn 起生效，正在执行的 turn 沿用它启动时的设置。reasoningEffort 仅在同时提供 model 时生效。
       operationId: update-thread
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: thread
           required: true
@@ -1426,14 +1558,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/UpdateThreadInputBody"
+              $ref: "#/components/schemas/UpdateThreadRequestBody"
         required: true
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ThreadSummaryView"
+                $ref: "#/components/schemas/ThreadSummaryResource"
           description: OK
         default:
           content:
@@ -1449,13 +1581,6 @@ paths:
       description: 批次 id 来自对话文档的 wait 字段。本接口是幂等的：重复提交同一批次不会改变已经生效的决定，也不会报错。批次不属于该对话时返回 404。
       operationId: decide-approval
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: thread
           required: true
@@ -1470,7 +1595,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/DecideInputBody"
+              $ref: "#/components/schemas/DecideRequestBody"
         required: true
       responses:
         "204":
@@ -1484,18 +1609,47 @@ paths:
       summary: 批准或拒绝一批工具调用
       tags:
         - Thread
+  /v1/threads/{thread}/earlier:
+    get:
+      description: 首屏只给对话最新的那一段，再往上的内容用本接口按需取回，一次一段。before 用文档里的 earlier.before，响应里的 earlier 是再往上那一段的游标，为 null 表示已经到顶。返回的条目和文档里的 items 是同一种形状，顺序也一样（由旧到新），直接接在现有内容前面即可。
+      operationId: list-earlier-items
+      parameters:
+        - in: path
+          name: thread
+          required: true
+          schema:
+            type: string
+        - description: 来自文档里的 earlier.before，取这个序号之前的条目
+          explode: false
+          in: query
+          name: before
+          required: true
+          schema:
+            description: 来自文档里的 earlier.before，取这个序号之前的条目
+            format: int64
+            minimum: 0
+            type: integer
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EarlierResponseBody"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 取回更早的对话内容
+      tags:
+        - Thread
   /v1/threads/{thread}/interrupt:
     post:
       description: 对没有正在执行的 turn 的对话调用同样返回 204，不视为错误——用户点击停止与 turn 自然结束之间存在竞争，两种结果一致。项目处于停服或清理状态时本接口仍然可用。
       operationId: interrupt-thread
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: thread
           required: true
@@ -1518,13 +1672,6 @@ paths:
       description: 立即返回 turnId，不等待执行完成——一次 turn 可能持续数十分钟。执行进度通过对话文档中 stream 指向的实时流获取，不在本响应里。
       operationId: send-message
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: thread
           required: true
@@ -1534,14 +1681,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/SendMessageInputBody"
+              $ref: "#/components/schemas/SendMessageRequestBody"
         required: true
       responses:
         "202":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/SendMessageOutputBody"
+                $ref: "#/components/schemas/TurnIDResponseBody"
           description: Accepted
         default:
           content:
@@ -1557,13 +1704,6 @@ paths:
       description: 问题 id 来自对话文档的 wait 字段。已被回答过的问题同样返回 204——可能是另一个页面提交在先，也可能是自动应答窗口已到期，两种情况下 turn 都已带着答案继续执行。
       operationId: answer-question
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: thread
           required: true
@@ -1578,7 +1718,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/AnswerInputBody"
+              $ref: "#/components/schemas/AnswerRequestBody"
         required: true
       responses:
         "204":
@@ -1596,13 +1736,6 @@ paths:
     post:
       operationId: mark-thread-read
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: thread
           required: true
@@ -1625,13 +1758,6 @@ paths:
       description: 撤回 ordinal 及其之后的全部条目。被撤回的条目仍留在逐字稿中并标记 reverted，序号不会重排。返回实际撤回的条目数。
       operationId: revert-thread
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: thread
           required: true
@@ -1641,14 +1767,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/RevertInputBody"
+              $ref: "#/components/schemas/RevertRequestBody"
         required: true
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/RevertOutputBody"
+                $ref: "#/components/schemas/RevertedCountResponseBody"
           description: OK
         default:
           content:
@@ -1664,13 +1790,6 @@ paths:
       description: 轮询本接口直到状态变为成功或失败。状态提示需要验证码时，调用补交验证码接口。
       operationId: get-weixin-login
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: login
           required: true
@@ -1682,7 +1801,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/LoginView"
+                $ref: "#/components/schemas/LoginResource"
           description: OK
         default:
           content:
@@ -1698,13 +1817,6 @@ paths:
       description: 微信在扫码后要求短信或设备验证码时使用。验证码由登录发起人在自己手机上获取。
       operationId: submit-weixin-verify-code
       parameters:
-        - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
-            type: string
         - in: path
           name: login
           required: true
@@ -1715,14 +1827,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/VerifyCodeInputBody"
+              $ref: "#/components/schemas/VerifyCodeRequestBody"
         required: true
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/LoginView"
+                $ref: "#/components/schemas/LoginResource"
           description: OK
         default:
           content:
@@ -1733,4 +1845,6 @@ paths:
       summary: 补交登录验证码
       tags:
         - Onboarding
+security:
+  - bearerAuth: []