@leaflow/sdk 0.1.3 → 0.2.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,23 @@ components:
         - width
         - height
       type: object
-    BindingView:
+    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:
         channelId:
@@ -59,7 +75,23 @@ components:
         - verifiedAt
         - createdAt
       type: object
-    ChannelView:
+    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:
         allowFrom:
@@ -86,7 +118,13 @@ components:
           format: date-time
           type: string
         webhookPath:
+          description: 回调路径，网关配置和排查时用
           type: string
+        webhookUrl:
+          description: 填到平台后台的回调地址。部署未声明公网入口时为 null
+          type:
+            - string
+            - "null"
       required:
         - id
         - platform
@@ -94,6 +132,7 @@ components:
         - status
         - senderPolicy
         - allowFrom
+        - webhookUrl
         - webhookPath
         - createdAt
         - updatedAt
@@ -109,7 +148,7 @@ components:
         - label
         - description
       type: object
-    ClaimCodeOutputBody:
+    ClaimCodeResponseBody:
       additionalProperties: false
       properties:
         code:
@@ -121,7 +160,7 @@ components:
         - code
         - expiresAt
       type: object
-    ContextView:
+    ContextResource:
       additionalProperties: false
       properties:
         compactAt:
@@ -151,7 +190,7 @@ components:
         - compactAt
         - warnAt
       type: object
-    CreateChannelInputBody:
+    CreateChannelRequestBody:
       additionalProperties: false
       properties:
         allowFrom:
@@ -179,7 +218,7 @@ components:
         - platform
         - name
       type: object
-    CreateThreadInputBody:
+    CreateThreadRequestBody:
       additionalProperties: false
       properties:
         approvalMode:
@@ -190,7 +229,7 @@ components:
             - yolo
           type: string
       type: object
-    DecideInputBody:
+    DecideRequestBody:
       additionalProperties: false
       properties:
         approved:
@@ -200,35 +239,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 +279,7 @@ components:
         - wait
         - turn
       type: object
-    EarlierView:
+    EarlierResource:
       additionalProperties: false
       properties:
         before:
@@ -295,7 +334,7 @@ components:
         - status
         - message
       type: object
-    ItemView:
+    ItemResource:
       additionalProperties: false
       properties:
         approval:
@@ -315,7 +354,7 @@ components:
           type: string
         attachments:
           items:
-            $ref: "#/components/schemas/AttachmentView"
+            $ref: "#/components/schemas/AttachmentResource"
           type:
             - array
             - "null"
@@ -334,7 +373,7 @@ components:
         id:
           type: string
         model:
-          description: 这一行是哪个模型产出的。人打的字上是 null
+          description: 产出这一条的模型。用户自己发的消息为 null
           type:
             - string
             - "null"
@@ -367,7 +406,7 @@ components:
             - string
             - "null"
         type:
-          description: 客户端按它 switch 出这一行的形状
+          description: 决定这一条包含哪些字段
           enum:
             - user_message
             - agent_message
@@ -385,87 +424,7 @@ components:
         - reverted
         - model
       type: object
-    ListBindingsOutputBody:
-      additionalProperties: false
-      properties:
-        bindings:
-          items:
-            $ref: "#/components/schemas/BindingView"
-          type:
-            - array
-            - "null"
-        total:
-          format: int64
-          type: integer
-      required:
-        - bindings
-        - total
-      type: object
-    ListChannelsOutputBody:
-      additionalProperties: false
-      properties:
-        channels:
-          items:
-            $ref: "#/components/schemas/ChannelView"
-          type:
-            - array
-            - "null"
-        total:
-          format: int64
-          type: integer
-      required:
-        - channels
-        - total
-      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 +449,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,7 +487,19 @@ 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:
         name:
@@ -524,11 +507,18 @@ components:
         resident:
           type: boolean
         webhookPath:
+          description: 回调路径模板，{channel} 处替换为通道 id
           type: string
+        webhookUrlTemplate:
+          description: 完整回调地址模板。部署未声明公网入口时为 null
+          type:
+            - string
+            - "null"
       required:
         - name
         - resident
         - webhookPath
+        - webhookUrlTemplate
       type: object
     Question:
       additionalProperties: false
@@ -551,7 +541,19 @@ components:
         - question
         - choices
       type: object
-    RevertInputBody:
+    RejectionListResponseBody:
+      additionalProperties: false
+      properties:
+        rejections:
+          items:
+            $ref: "#/components/schemas/Entry"
+          type:
+            - array
+            - "null"
+      required:
+        - rejections
+      type: object
+    RevertRequestBody:
       additionalProperties: false
       properties:
         ordinal:
@@ -561,7 +563,7 @@ components:
       required:
         - ordinal
       type: object
-    RevertOutputBody:
+    RevertedCountResponseBody:
       additionalProperties: false
       properties:
         reverted:
@@ -570,15 +572,7 @@ components:
       required:
         - reverted
       type: object
-    RotateSecretOutputBody:
-      additionalProperties: false
-      properties:
-        webhookSecret:
-          type: string
-      required:
-        - webhookSecret
-      type: object
-    SendMessageInputBody:
+    SendMessageRequestBody:
       additionalProperties: false
       properties:
         attachmentIds:
@@ -593,26 +587,30 @@ components:
       required:
         - text
       type: object
-    SendMessageOutputBody:
+    StreamResource:
       additionalProperties: false
       properties:
-        turnId:
+        path:
+          type: string
+        ticket:
           type: string
       required:
-        - turnId
+        - path
+        - ticket
       type: object
-    StreamView:
+    ThreadListResponseBody:
       additionalProperties: false
       properties:
-        ticket:
-          type: string
-        url:
-          type: string
+        threads:
+          items:
+            $ref: "#/components/schemas/ThreadSummaryResource"
+          type:
+            - array
+            - "null"
       required:
-        - url
-        - ticket
+        - threads
       type: object
-    ThreadSummaryView:
+    ThreadSummaryResource:
       additionalProperties: false
       properties:
         approvalMode:
@@ -649,7 +647,15 @@ components:
         - unread
         - approvalMode
       type: object
-    TurnView:
+    TurnIDResponseBody:
+      additionalProperties: false
+      properties:
+        turnId:
+          type: string
+      required:
+        - turnId
+      type: object
+    TurnResource:
       additionalProperties: false
       properties:
         approvalMode:
@@ -661,7 +667,7 @@ components:
       required:
         - approvalMode
       type: object
-    UpdateChannelInputBody:
+    UpdateChannelRequestBody:
       additionalProperties: false
       properties:
         credentials:
@@ -674,7 +680,7 @@ components:
           maxLength: 128
           type: string
       type: object
-    UpdateThreadInputBody:
+    UpdateThreadRequestBody:
       additionalProperties: false
       properties:
         approvalMode:
@@ -690,7 +696,7 @@ components:
         reasoningEffort:
           type: string
       type: object
-    UploadedView:
+    UploadedResource:
       additionalProperties: false
       properties:
         height:
@@ -706,7 +712,7 @@ components:
         - width
         - height
       type: object
-    VerifyCodeInputBody:
+    VerifyCodeRequestBody:
       additionalProperties: false
       properties:
         code:
@@ -714,7 +720,7 @@ components:
       required:
         - code
       type: object
-    WaitView:
+    WaitResource:
       additionalProperties: false
       properties:
         autoResolutionMs:
@@ -747,24 +753,40 @@ components:
         - kind
         - turnId
       type: object
+    WebhookSecretResponseBody:
+      additionalProperties: false
+      properties:
+        webhookSecret:
+          type: string
+      required:
+        - webhookSecret
+      type: object
 info:
   description: |-
-    助手对话及其接入面：线程、逐字稿、一次 turn 的执行与流式输出、工具调用与审批、追问、技能，以及通道、绑定和微信扫码登录。
+    控制台里的 AI 助手：对话、消息、工具调用与审批、附件，以及把助手接到微信、飞书、Telegram 等即时通讯平台上。
 
-    ## 认证
+    ## 一次对话
 
-    所有接口都要求 `Authorization: Bearer <项目令牌>`。项目令牌向 `POST /api/v1/projects/{projectId}/token` 换取，登录服务是 auth.leaflow.net。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 `project_id`。
+    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}`）。处理完成后助手自动继续。
 
-    令牌无效或过期返回 401，不是当前项目的成员返回 403。这两种都应重新换取令牌后重试；仍然失败说明这个账号在该项目里已没有权限。
+    发送图片分两步：先 `POST /v1/attachments` 上传拿到 id，发送消息时放进 `attachmentIds`。
 
-    ## 一次对话
+    ## 实时输出
+
+    ```
+    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
@@ -794,7 +816,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/UploadedView"
+                $ref: "#/components/schemas/UploadedResource"
           description: Created
         default:
           content:
@@ -871,7 +893,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListBindingsOutputBody"
+                $ref: "#/components/schemas/BindingListResponseBody"
           description: OK
         default:
           content:
@@ -955,7 +977,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListChannelsOutputBody"
+                $ref: "#/components/schemas/ChannelListResponseBody"
           description: OK
         default:
           content:
@@ -980,14 +1002,14 @@ paths:
         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:
@@ -1049,7 +1071,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ChannelView"
+                $ref: "#/components/schemas/ChannelResource"
           description: OK
         default:
           content:
@@ -1080,14 +1102,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:
@@ -1121,7 +1143,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ClaimCodeOutputBody"
+                $ref: "#/components/schemas/ClaimCodeResponseBody"
           description: Created
         default:
           content:
@@ -1164,7 +1186,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListRejectionsOutputBody"
+                $ref: "#/components/schemas/RejectionListResponseBody"
           description: OK
         default:
           content:
@@ -1198,7 +1220,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/RotateSecretOutputBody"
+                $ref: "#/components/schemas/WebhookSecretResponseBody"
           description: OK
         default:
           content:
@@ -1232,7 +1254,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/LoginView"
+                $ref: "#/components/schemas/LoginResource"
           description: Created
         default:
           content:
@@ -1245,7 +1267,7 @@ paths:
         - Onboarding
   /v1/models:
     get:
-      description: 返回本平台当前提供的模型及其上下文窗口、推理档位和支持的输入类型。用于填充对话设置里的模型选择。清单与项目无关，但仍需要有效的项目令牌。
+      description: 返回本平台当前提供的模型及其上下文窗口、推理档位和支持的输入类型。用于填充对话设置里的模型选择。
       operationId: list-models
       parameters:
         - description: Bearer + 项目令牌。一张项目令牌同时确定当前用户和当前项目，因此路径上不带 project_id
@@ -1260,7 +1282,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListModelsOutputBody"
+                $ref: "#/components/schemas/ModelListResponseBody"
           description: OK
         default:
           content:
@@ -1288,7 +1310,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListPlatformsOutputBody"
+                $ref: "#/components/schemas/PlatformListResponseBody"
           description: OK
         default:
           content:
@@ -1330,7 +1352,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListThreadsOutputBody"
+                $ref: "#/components/schemas/ThreadListResponseBody"
           description: OK
         default:
           content:
@@ -1355,14 +1377,14 @@ paths:
         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:
@@ -1395,7 +1417,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/DocumentView"
+                $ref: "#/components/schemas/DocumentResource"
           description: OK
         default:
           content:
@@ -1426,14 +1448,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:
@@ -1470,7 +1492,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/DecideInputBody"
+              $ref: "#/components/schemas/DecideRequestBody"
         required: true
       responses:
         "204":
@@ -1534,14 +1556,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:
@@ -1578,7 +1600,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/AnswerInputBody"
+              $ref: "#/components/schemas/AnswerRequestBody"
         required: true
       responses:
         "204":
@@ -1641,14 +1663,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:
@@ -1682,7 +1704,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/LoginView"
+                $ref: "#/components/schemas/LoginResource"
           description: OK
         default:
           content:
@@ -1715,14 +1737,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: