@leaflow/sdk 0.2.0 → 0.4.0

package/openapi/assistant.yaml

@@ -27,22 +27,6 @@ components:
         - width
         - height
       type: object
-    BindingListResponseBody:
-      additionalProperties: false
-      properties:
-        bindings:
-          items:
-            $ref: "#/components/schemas/BindingResource"
-          type:
-            - array
-            - "null"
-        total:
-          format: int64
-          type: integer
-      required:
-        - bindings
-        - total
-      type: object
     BindingResource:
       additionalProperties: false
       properties:
@@ -75,22 +59,6 @@ components:
         - verifiedAt
         - createdAt
       type: object
-    ChannelListResponseBody:
-      additionalProperties: false
-      properties:
-        channels:
-          items:
-            $ref: "#/components/schemas/ChannelResource"
-          type:
-            - array
-            - "null"
-        total:
-          format: int64
-          type: integer
-      required:
-        - channels
-        - total
-      type: object
     ChannelResource:
       additionalProperties: false
       properties:
@@ -229,6 +197,26 @@ components:
             - yolo
           type: string
       type: object
+    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:
@@ -291,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
@@ -424,6 +401,58 @@ components:
         - reverted
         - model
       type: object
+    LengthAwarePageBindingResource:
+      additionalProperties: false
+      properties:
+        items:
+          description: 这一页的内容
+          items:
+            $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:
+        - items
+        - total
+        - limit
+        - offset
+      type: object
+    LengthAwarePageChannelResource:
+      additionalProperties: false
+      properties:
+        items:
+          description: 这一页的内容
+          items:
+            $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:
+        - items
+        - total
+        - limit
+        - offset
+      type: object
     LoginResource:
       additionalProperties: false
       properties:
@@ -502,10 +531,33 @@ components:
     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
@@ -517,6 +569,10 @@ components:
       required:
         - name
         - resident
+        - setupMethod
+        - setupChallenge
+        - secretSource
+        - credentialFields
         - webhookPath
         - webhookUrlTemplate
       type: object
@@ -546,13 +602,41 @@ components:
       properties:
         rejections:
           items:
-            $ref: "#/components/schemas/Entry"
+            $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:
@@ -572,6 +656,13 @@ components:
       required:
         - reverted
       type: object
+    RotateSecretRequestBody:
+      additionalProperties: false
+      properties:
+        webhookSecret:
+          description: 平台生成密钥的平台（secretSource=supplied）必须传新的那把；我们生成的（generated）不能传
+          type: string
+      type: object
     SendMessageRequestBody:
       additionalProperties: false
       properties:
@@ -587,6 +678,37 @@ components:
       required:
         - text
       type: object
+    SenderCheckResource:
+      additionalProperties: false
+      properties:
+        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:
+        - allowed
+        - verdict
+        - senderPolicy
+        - allowFrom
+        - bindingId
+      type: object
     StreamResource:
       additionalProperties: false
       properties:
@@ -670,15 +792,29 @@ components:
     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
     UpdateThreadRequestBody:
       additionalProperties: false
@@ -761,6 +897,12 @@ components:
       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: |-
     控制台里的 AI 助手：对话、消息、工具调用与审批、附件，以及把助手接到微信、飞书、Telegram 等即时通讯平台上。
@@ -795,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:
@@ -832,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
@@ -858,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
@@ -888,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/BindingListResponseBody"
+                $ref: "#/components/schemas/LengthAwarePageBindingResource"
           description: OK
         default:
           content:
@@ -908,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
@@ -933,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
@@ -977,7 +1132,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ChannelListResponseBody"
+                $ref: "#/components/schemas/LengthAwarePageChannelResource"
           description: OK
         default:
           content:
@@ -990,14 +1145,6 @@ 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:
@@ -1025,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
@@ -1053,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
@@ -1083,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
@@ -1125,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
@@ -1159,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
@@ -1199,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/WebhookSecretResponseBody"
+                $ref: "#/components/schemas/SenderCheckResource"
           description: OK
         default:
           content:
@@ -1228,7 +1381,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 轮换回调密钥
+      summary: 推演一个发件人会不会被放行
       tags:
         - Onboarding
   /v1/channels/{channel}/weixin-logins:
@@ -1236,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
@@ -1269,14 +1415,6 @@ paths:
     get:
       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:
@@ -1295,16 +1433,8 @@ 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:
@@ -1323,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
@@ -1365,14 +1497,6 @@ 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:
@@ -1400,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
@@ -1432,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
@@ -1471,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
@@ -1506,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
@@ -1540,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
@@ -1579,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
@@ -1618,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
@@ -1647,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
@@ -1686,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
@@ -1720,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
@@ -1755,4 +1845,6 @@ paths:
       summary: 补交登录验证码
       tags:
         - Onboarding
+security:
+  - bearerAuth: []