super-agent-sdk 1.0.3 → 1.0.5

package/README.md

@@ -15,7 +15,8 @@ Super Agent Web SDK —— 为 `super-agent-service` 提供的一站式浏览器
 9. [会话管理](#9-会话管理)
 10. [中断恢复](#10-中断恢复)
 11. [消息类型](#11-消息类型)
-12. [高级用法](#12-高级用法)
+12. [Human-in-the-Loop](#12-human-in-the-loop)
+13. [高级用法](#13-高级用法)
 
 ---
 
@@ -61,7 +62,11 @@ pnpm add react react-dom
 import { createSuperAgent } from "super-agent-sdk";
 import { mount } from "super-agent-sdk/widget";
 
-const sdk = createSuperAgent({ baseUrl: "/api/v1", botId: 1 });
+const sdk = createSuperAgent({
+  baseUrl: "/api/v1",
+  botId: 1,
+  appId: "your_app_id",
+});
 // Token 自动获取，无需手动设置
 const widget = mount("#chat", { sdk });
 widget.open();
@@ -81,46 +86,46 @@ function createSuperAgent(config: SDKConfig): SuperAgentSDK;
 export interface SDKConfig {
   baseUrl: string; // e.g. "https://agent.example.com/api/v1"
   botId: number; // bot ID
+  appId: string; // 应用密钥，用于换取 token
 }
 ```
 
-只需提供 `baseUrl` 与 `botId` 即可。SDK 不要求在创建时传入 `appId` / `token`——组件挂载后会自动调用 `sdk.getToken()` 获取凭证并内部保存，无需手动设置。
+只需提供 `baseUrl`、`botId` 与 `appId` 即可。SDK 不要求在创建时传入 `token`——组件挂载后会自动调用 `sdk.getToken()` 获取 token 并内部保存，无需手动设置。
 
 ```ts
 const sdk = createSuperAgent({
   baseUrl: "https://agent.example.com/api/v1",
   botId: 1,
+  appId: "your_app_id",
 });
 ```
 
 凭证获取流程：
 
 ```
-createSuperAgent({ baseUrl, botId })
+createSuperAgent({ baseUrl, botId, appId })
         ↓
 Widget 挂载时自动调用 sdk.getToken()
         ↓
-POST /token { botId }
+POST /api/token（无参数）
         ↓
-后端返回 { app_id, token }
+后端返回 { token }
         ↓
-SDK 内部自动保存凭证
+SDK 内部自动保存 token
         ↓
 ready
 ```
 
-出于安全考虑，`app_key` 应永远留在后端，浏览器端只持有短时有效的 Token。
+`appId` 用于换取访问 token，浏览器端后续请求只持有短时有效的 token。
 
 ---
 
 ## 5. API 参考
 
-> **字段命名映射**：后端接口返回的是 snake_case 字段，SDK 内部统一转换为 camelCase 后对外暴露。
+> **字段命名**：后端接口返回 camelCase 字段，SDK 直接使用，无需转换。
 >
-> - 后端返回 `thread_id`（snake_case）→ SDK 内部映射为 `sessionId`
-> - 后端返回 `bot_id` → SDK 映射为 `botId`
-> - SDK 所有公开 API 均使用 camelCase（`sessionId`、`botId`）
-> - SDK 发起请求时同样使用 camelCase（如 `{ botId, sessionId, message }`）
+> - 后端返回 `sessionId`、`botId`、`createTime`、`updateTime`
+> - SDK 所有公开 API 均使用 camelCase
 
 ### 5.1 SDK 实例
 
@@ -134,10 +139,10 @@ export interface SuperAgentSDK {
   renameConversation(sessionId: string, title: string): Promise<void>;
   deleteConversation(sessionId: string): Promise<void>;
   getMessages(sessionId: string): Promise<UIMessage[]>;
-  getToken(): Promise<{ appId: string; token: string }>;
-  setToken(appId: string, token: string): void;
-  feedback(messageId: string, type: "like" | "dislike"): void;
-  onFeedback?: (messageId: string, type: "like" | "dislike") => void;
+  getToken(): Promise<string>;
+  setToken(token: string): void;
+  feedback(messageId: string, type: "like" | "dislike", options?: { reason?: number; remark?: string }): Promise<void>;
+  cancelFeedback(messageId: string): Promise<void>;
 }
 ```
 
@@ -146,8 +151,8 @@ export interface SuperAgentSDK {
 创建新会话，返回 `sessionId`。聊天前必须先创建会话。
 
 - SDK 调用 `POST /chat/sessions`，请求体为 `{ botId }`
-- 后端返回 `{ session_id: "..." }`
-- SDK 解析后返回 `sessionId` 字符串
+- 后端返回 `{ sessionId: "..." }`
+- SDK 直接返回 `sessionId` 字符串
 
 ```ts
 const sessionId = await sdk.createSession();
@@ -158,7 +163,7 @@ const sessionId = await sdk.createSession();
 流式聊天。**`sessionId` 为必填**，必须先调用 `createSession()` 获取。返回 `AbortController`，可随时中断。
 
 - SDK 发送 `POST /chat`，请求体为 `{ botId, sessionId, message, stream }`
-- 后端 SSE 在 `done` 事件中返回 `session_id` → SDK 暴露为 `sessionId`
+- 后端 SSE 在 `done` 事件中返回 `sessionId`
 
 ```ts
 export interface ChatOptions {
@@ -245,8 +250,7 @@ const { items, total } = await sdk.listConversations({ page: 1, size: 20 });
 ```
 
 - SDK 调用 `GET /chat/conversations?botId=1&page=1&size=20`
-- 后端返回的每一项使用 `thread_id`、`bot_id`、`create_time`、`update_time` 字段
-- SDK 将其映射为 `Conversation { sessionId, botId, title, createTime, updateTime }`
+- 后端返回的每一项为 `{ sessionId, botId, title, createTime, updateTime }`
 
 ### 5.5 getMessages()
 
@@ -266,67 +270,69 @@ await sdk.deleteConversation(sessionId);
 ### 5.7 getToken()
 
 ```typescript
-sdk.getToken(): Promise<{ appId: string; token: string }>
+sdk.getToken(): Promise<string>
 ```
 
-自动获取并保存访问凭证：
+自动获取并保存访问 token：
 
-- SDK 调用 `POST /token`，请求体为 `{ botId }`（无需鉴权头）
-- 后端返回 `{ app_id, token }`
-- SDK 自动将凭证保存在内部
+- SDK 调用 `POST /api/token`（固定路径，不拼接 `baseUrl`），无需请求参数
+- 后端返回 `{ token }`
+- SDK 自动将 token 保存在内部
 - Widget 在挂载时自动调用此方法 —— 通常无需手动调用
 
 ```ts
-const { appId, token } = await sdk.getToken();
+const token = await sdk.getToken();
 ```
 
 ### 5.8 setToken()
 
 ```typescript
-sdk.setToken(appId: string, token: string): void
+sdk.setToken(token: string): void
 ```
 
-手动设置凭证（用于凭证由外部获取、或测试等场景）。正常情况下无需调用，Widget 挂载时会自动通过 `getToken()` 获取凭证。
+手动设置 token（用于 token 由外部获取、或测试等场景）。正常情况下无需调用，Widget 挂载时会自动通过 `getToken()` 获取 token。
 
 ```ts
-sdk.setToken("<APP_ID>", "<TOKEN>");
+sdk.setToken("<TOKEN>");
 ```
 
-### 5.9 feedback() / onFeedback
+### 5.9 feedback() / cancelFeedback()
 
-点赞 / 踩：调用 `sdk.feedback()`，SDK 会回调你注册的 `sdk.onFeedback`。
+消息反馈（赞/踩）。调用 `sdk.feedback()` 发送 `POST /chat/messages/{messageId}/feedback`；调用 `sdk.cancelFeedback()` 发送 `DELETE` 取消反馈。
 
 ```ts
-sdk.onFeedback = (messageId, type) => {
-  // type: 'like' | 'dislike'
-  console.log(`Feedback: ${type} on message ${messageId}`);
-  // 上报到自己的业务后端
-};
+// 点赞
+await sdk.feedback("msg_123", "like");
 
-sdk.feedback("msg_123", "like");
+// 踩（可附原因 + 备注）
+await sdk.feedback("msg_123", "dislike", {
+  reason: 1,  // 1=事实错误 2=逻辑问题 3=不相关 4=信息过时 5=冗长啰嗦 6=难以理解
+  remark: "时间描述有误",
+});
+
+// 取消反馈
+await sdk.cancelFeedback("msg_123");
 ```
 
-组件内置的点赞 / 踩按钮也会经过 `sdk.feedback()`，因此只需注册一次 `onFeedback` 即可统一接收所有反馈。
+组件内置的点赞/踩按钮已自动调用 `feedback()`/`cancelFeedback()`：
+- 点击已选中的按钮 → 取消（DELETE）
+- 点击另一个按钮 → 切换（POST）
+- 点踩时弹出原因选择面板（可选填原因 + 备注后提交）
 
 ### 5.10 后端接口对照
 
 SDK 方法 → 后端接口的完整映射：
 
-| SDK 方法              | HTTP 请求                 | 请求体（camelCase）                     | 后端返回（snake_case）                              | SDK 返回                                                           |
-| --------------------- | ------------------------- | --------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------ |
-| `getToken()`          | `POST /token`             | `{ botId }`                             | `{ app_id, token }`                                 | `{ appId, token }`                                                 |
-| `createSession()`     | `POST /chat/sessions`     | `{ botId }`                             | `{ session_id }`                                    | `sessionId` 字符串                                                 |
-| `chat()`              | `POST /chat`              | `{ botId, sessionId, message, stream }` | SSE 流，`done` 事件含 `session_id`                  | `onDone` 中暴露 `sessionId`                                        |
-| `listConversations()` | `GET /chat/conversations` | 查询参数 `botId`、`page`、`size`        | `{ thread_id, bot_id, create_time, update_time }[]` | `Conversation { sessionId, botId, title, createTime, updateTime }` |
-
-字段命名转换规则：
+> 除 `getToken()` 外，其余接口请求均携带 `X-App-Id` 与 `X-Token` 请求头进行鉴权。
 
-| 后端（snake_case） | SDK（camelCase） |
-| ------------------ | ---------------- |
-| `thread_id`        | `sessionId`      |
-| `bot_id`           | `botId`          |
-| `create_time`      | `createTime`     |
-| `update_time`      | `updateTime`     |
+| SDK 方法              | HTTP 请求                 | 请求体                                  | 后端返回                                        |
+| --------------------- | ------------------------- | --------------------------------------- | ----------------------------------------------- |
+| `getToken()`          | `POST {gateway}/v1/token` | `{ botId }`                             | `{ token, appId }`                              |
+| `createSession()`     | `POST /chat/sessions`     | `{ botId }`                             | `{ sessionId }`                                 |
+| `chat()`              | `POST /chat`              | `{ botId, sessionId, message, stream }` | SSE 流，`done` 事件含 `sessionId`               |
+| `listConversations()` | `GET /chat/conversations` | 查询参数 `botId`、`page`、`size`        | `{ items: [{ sessionId, botId, ... }], total }` |
+| `feedback()`          | `POST /chat/messages/{messageId}/feedback` | `{ type, reason?, remark? }` | `null`                               |
+| `cancelFeedback()`    | `DELETE /chat/messages/{messageId}/feedback` | 无 body                     | `null`                               |
 
 ---
 
@@ -366,7 +372,11 @@ export interface WidgetInstance {
 import { createSuperAgent } from "super-agent-sdk";
 import { mount } from "super-agent-sdk/widget";
 
-const sdk = createSuperAgent({ baseUrl: "/api/v1", botId: 1 });
+const sdk = createSuperAgent({
+  baseUrl: "/api/v1",
+  botId: 1,
+  appId: "your_app_id",
+});
 
 const widget = mount("#chat-root", {
   sdk,
@@ -874,8 +884,12 @@ import type {
   WelcomeScreenProps,
 } from "super-agent-sdk/widget";
 
-const sdk = createSuperAgent({ baseUrl: "/api/v1", botId: 1 });
-sdk.setToken("demo_app", "demo_token");
+const sdk = createSuperAgent({
+  baseUrl: "/api/v1",
+  botId: 1,
+  appId: "your_app_id",
+});
+sdk.setToken("demo_token");
 
 function CustomHeader({ title, onClose, onToggleThreadList }: HeaderProps) {
   return (
@@ -1192,17 +1206,118 @@ export interface ChatEvent {
 
 ---
 
-## 12. 高级用法
+## 12. Human-in-the-Loop
+
+Agent 执行中需要人类介入时（确认敏感操作、选择方案、补充信息、审核内容等），SDK 提供统一的中断交互机制。
+
+### 12.1 核心流程
+
+```
+Agent 执行中
+  → 后端发送 SSE interrupt 事件
+  → SDK 渲染中断交互卡片（按 interruptType 分发）
+  → 用户完成操作
+  → SDK 调用 respondInterrupt() 回传响应
+  → Agent 基于响应继续执行
+```
+
+### 12.2 interrupt 事件
+
+```json
+{
+  "type": "interrupt",
+  "interruptId": "int_001",
+  "interruptType": "confirm",
+  "content": "即将执行转账 ¥500，确认执行？",
+  "options": ["确认", "取消"]
+}
+```
+
+### 12.3 响应中断
+
+```ts
+await sdk.respondInterrupt(interruptId, {
+  action: "confirm",
+});
+```
+
+### 12.4 Widget 自动处理
+
+Widget 内置中断卡片渲染，收到 `interrupt` 事件后自动展示对应交互卡片，用户操作后自动回传，无需业务方处理：
+
+```ts
+mount("#chat", { sdk }).open();
+// 遇到 interrupt 时：自动渲染卡片 → 用户点击 → 自动 respondInterrupt → Agent 继续
+```
+
+也可通过插槽自定义中断卡片：
+
+```ts
+mount("#chat", {
+  sdk,
+  slots: {
+    InterruptCard: MyInterruptCard,   // 自定义全部类型
+  },
+});
+```
+
+### 12.5 纯 API 模式手动处理
+
+```ts
+sdk.chat({
+  sessionId,
+  message: "帮我转账 ¥500",
+  onMessage: (e) => {
+    if (e.type === "interrupt" && e.interrupt) {
+      // 自定义 UI 处理
+      const ok = window.confirm(e.interrupt.content);
+      sdk.respondInterrupt(e.interrupt.interruptId, {
+        action: ok ? "confirm" : "cancel",
+      });
+    }
+  },
+});
+```
+
+### 12.6 interruptType 一览
+
+| interruptType | 交互 | action | value 示例 |
+|---------------|------|--------|-----------|
+| `confirm` | 二次确认 | `confirm` / `cancel` | — |
+| `select` | 单选 | `select` | `"flight_a"` |
+| `multiSelect` | 多选 | `submit` | `["name", "phone"]` |
+| `input` | 文本输入 | `submit` | `"123456"` |
+| `form` | 表单 | `submit` | `{ name: "张三" }` |
+| `review` | 内容审阅 | `approve` / `reject` | 修改后内容 |
+| `approve` | 审批流 | `approve` / `reject` | 驳回原因 |
+| `upload` | 文件上传 | `submit` | `{ fileId, fileName }` |
+| `image` | 图片选择 | `select` / `reject` | 图片索引 |
+| `auth` | 授权请求 | `authorized` / `skip` | — |
+| `captcha` | 人机验证 | `verified` | `"captcha_token"` |
+| `decision` | 流程分支 | `decide` | `"retry"` 等 |
+| `rating` | 评分 | `rate` | `4` |
+| `date` | 日期选择 | `submit` | `"2026-08-21T14:00:00"` |
+| `location` | 位置选择 | `submit` | `{ address, lat, lng }` |
+
+> 每个 `interruptType` 的完整字段定义见 [API 文档](./API.md) 与 [HITL 设计文档](../docs/superpowers/specs/2026-08-18-human-in-the-loop-design.md)。
+
+---
+
+## 13. 高级用法
 
-### 12.1 纯 API 模式（不用 Widget）
+### 13.1 纯 API 模式（不用 Widget）
 
 不挂载组件，仅使用 API 层构建自己的 UI：
 
 ```ts
 import { createSuperAgent } from "super-agent-sdk";
 
-const sdk = createSuperAgent({ baseUrl: "/api/v1", botId: 1 });
-sdk.setToken("<APP_ID>", "<TOKEN>");
+const sdk = createSuperAgent({
+  baseUrl: "/api/v1",
+  botId: 1,
+  appId: "your_app_id",
+});
+sdk.setToken("<TOKEN>");
 
 const sessionId = await sdk.createSession();
 
@@ -1218,7 +1333,7 @@ sdk.chat({
 });
 ```
 
-### 12.2 使用 Hooks
+### 13.2 使用 Hooks
 
 从 `super-agent-sdk/widget` 导出 `useChat`、`useConversations`，可在自己的 React 应用中复用：
 
@@ -1290,11 +1405,11 @@ function MyChat({ sdk }: { sdk: SuperAgentSDK }) {
 
 > `useChat` 在 `sessionId` 为空时会自动调用 `sdk.createSession()` 创建新会话，无需手动处理。
 
-### 12.3 Token 续期
+### 13.3 Token 续期
 
-请求返回 `401` 时，SDK 会自动重新调用 `POST /token` 获取新凭证并重试（并发请求合并为一次刷新），无需手动处理。
+请求返回 `401` 时，SDK 自动重新调用 `POST /api/token` 获取新 token。
 
-### 12.4 取消请求
+### 13.4 取消请求
 
 `chat()` 返回 `AbortController`；或传入外部 `AbortSignal`（SDK 会合并内部信号，任一触发即中断）：
 

package/dist/index.cjs

@@ -1,5 +1,5 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function h(s){if(Array.isArray(s))return s.map(e=>h(e));if(s&&typeof s=="object"&&s.constructor===Object){const e={};for(const[r,t]of Object.entries(s)){const o=r.replace(/_([a-z])/g,(n,a)=>a.toUpperCase());e[o]=h(t)}return e}return s}class g{constructor(e){this.refreshing=null,this.baseUrl=e.baseUrl.replace(/\/$/,""),this.appId=e.appId??"",this.token=e.token??"",this.botId=e.botId}getBotId(){return this.botId}setToken(e,r){this.appId=e,this.token=r}async postPublic(e,r){const t=`${this.baseUrl}${e}`,o=await fetch(t,{method:"POST",headers:{"Content-Type":"application/json"},body:r?JSON.stringify(r):void 0});if(!o.ok)throw new Error(`HTTP ${o.status}: ${o.statusText}`);const n=await o.json();if(n.code!=="200")throw new Error(n.message||`API error: ${n.code}`);return h(n.data)}headers(e){return{"Content-Type":"application/json","X-App-Id":this.appId,"X-Token":this.token,...e}}async handleTokenRefresh(){if(this.refreshing)return await this.refreshing,!0;try{return this.refreshing=(async()=>{const e=await this.postPublic("/token",{botId:this.botId});this.appId=e.appId,this.token=e.token})(),await this.refreshing,!0}catch{return!1}finally{this.refreshing=null}}async request(e,r,t){if((!this.appId||!this.token)&&!await this.handleTokenRefresh())throw new Error("SDK token not available: POST /token failed");let o=`${this.baseUrl}${r}`;if(t!=null&&t.params){const c=new URLSearchParams;for(const[l,d]of Object.entries(t.params))d!=null&&c.set(l,String(d));const i=c.toString();i&&(o+=`?${i}`)}const n=await fetch(o,{method:e,headers:this.headers(),body:t!=null&&t.body?JSON.stringify(t.body):void 0});if(n.status===401&&!(t!=null&&t.retry)&&await this.handleTokenRefresh())return this.request(e,r,{...t,retry:!0});if(!n.ok)throw new Error(`HTTP ${n.status}: ${n.statusText}`);const a=await n.json();if(a.code!=="200")throw new Error(a.message||`API error: ${a.code}`);return h(a.data)}get(e,r){return this.request("GET",e,{params:r})}post(e,r){return this.request("POST",e,{body:r})}patch(e,r){return this.request("PATCH",e,{body:r})}del(e){return this.request("DELETE",e)}async streamPost(e,r,t){if((!this.appId||!this.token)&&!await this.handleTokenRefresh())throw new Error("SDK token not available: POST /token failed");const o=`${this.baseUrl}${e}`,n=await fetch(o,{method:"POST",headers:this.headers(),body:JSON.stringify(r),signal:t});return n.status===401&&await this.handleTokenRefresh()?fetch(o,{method:"POST",headers:this.headers(),body:JSON.stringify(r),signal:t}):n}}function f(s){const e=s.split(`
-`).map(t=>t.trim()).filter(t=>t.startsWith("data:")).map(t=>t.slice(5).trim());if(!e.length)return null;let r;try{r=JSON.parse(e.join(`
-`))}catch{return null}switch(r.type){case"user":return{type:"user",content:r.content??""};case"thinking":return{type:"thinking",content:r.content??""};case"ai":return{type:"ai",content:r.content??""};case"tool_call":return{type:"tool_call",content:r.name??"",toolName:r.name,toolCallId:r.id,args:typeof r.args=="string"?r.args:JSON.stringify(r.args??{})};case"tool_result":return{type:"tool_result",content:r.output??"",toolName:r.name,toolCallId:r.id};case"done":return{type:"done",content:r.content??"",sessionId:r.sessionId??r.session_id??""};case"error":return{type:"error",content:r.message??"Unknown error"};default:return null}}async function y(s,e,r){if(!s.body){r(new Error("Response body is null"));return}const t=s.body.getReader(),o=new TextDecoder;let n="";try{for(;;){const{value:a,done:c}=await t.read();if(c)break;n+=o.decode(a,{stream:!0});let i;for(;(i=n.indexOf(`
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function f(a){if(Array.isArray(a))return a.map(e=>f(e));if(a&&typeof a=="object"&&a.constructor===Object){const e={};for(const[t,n]of Object.entries(a)){const o=t.replace(/_([a-z])/g,(r,s)=>s.toUpperCase());e[o]=f(n)}return e}return a}const w="/api/agent/runtime/v1";class I{constructor(e){this.refreshing=null;const t=e.baseUrl??w;this.baseUrl=t.replace(/\/$/,""),this.tokenGateway=e.tokenGateway.replace(/\/$/,""),this.appId=e.appId??"",this.token=e.token??"",this.botId=e.botId,this.isAbsoluteUrl=/^https?:\/\//.test(this.baseUrl),this.isAbsoluteGateway=/^https?:\/\//.test(this.tokenGateway)}getBotId(){return this.botId}getAppKey(){return this.appId}setToken(e){this.token=e}getOrigin(){return typeof window<"u"?window.location.origin:""}async fetchToken(){const t=`${this.isAbsoluteGateway?this.tokenGateway:`${this.getOrigin()}${this.tokenGateway}`}/v1/token`,n=await fetch(t,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({botId:this.botId})});if(!n.ok)throw new Error(`HTTP ${n.status}: ${n.statusText}`);const o=await n.json();if(o.code!=="200")throw new Error(o.message||`API error: ${o.code}`);const r=f(o.data);return this.token=r.token,r.appId&&!this.appId&&(this.appId=r.appId),r.token}headers(e){return{"Content-Type":"application/json","X-App-Id":this.appId,"X-Token":this.token,...e}}async handleTokenRefresh(){if(this.refreshing)return await this.refreshing,!0;try{return this.refreshing=(async()=>{await this.fetchToken()})(),await this.refreshing,!0}catch{return!1}finally{this.refreshing=null}}async request(e,t,n){if(!this.token&&!await this.handleTokenRefresh())throw new Error("SDK token not available: POST /token failed");let o=this.isAbsoluteUrl?`${this.baseUrl}${t}`:`${this.getOrigin()}${this.baseUrl}${t}`;if(n!=null&&n.params){const i=new URLSearchParams;for(const[l,d]of Object.entries(n.params))d!=null&&i.set(l,String(d));const c=i.toString();c&&(o+=`?${c}`)}const r=await fetch(o,{method:e,headers:this.headers(),body:n!=null&&n.body?JSON.stringify(n.body):void 0});if(r.status===401&&!(n!=null&&n.retry)&&await this.handleTokenRefresh())return this.request(e,t,{...n,retry:!0});if(!r.ok)throw new Error(`HTTP ${r.status}: ${r.statusText}`);const s=await r.json();if(s.code!=="200")throw new Error(s.message||`API error: ${s.code}`);return f(s.data)}get(e,t){return this.request("GET",e,{params:t})}post(e,t){return this.request("POST",e,{body:t})}patch(e,t){return this.request("PATCH",e,{body:t})}del(e){return this.request("DELETE",e)}async streamPost(e,t,n){if(!this.token&&!await this.handleTokenRefresh())throw new Error("SDK token not available: POST /token failed");const o=this.isAbsoluteUrl?`${this.baseUrl}${e}`:`${this.getOrigin()}${this.baseUrl}${e}`,r=await fetch(o,{method:"POST",headers:this.headers(),body:JSON.stringify(t),signal:n});return r.status===401&&await this.handleTokenRefresh()?fetch(o,{method:"POST",headers:this.headers(),body:JSON.stringify(t),signal:n}):r}}function y(a){const e=a.split(`
+`).map(n=>n.trim()).filter(n=>n.startsWith("data:")).map(n=>n.slice(5).trim());if(!e.length)return null;let t;try{t=JSON.parse(e.join(`
+`))}catch{return null}switch(t.type){case"user":return{type:"user",content:t.content??""};case"thinking":return{type:"thinking",content:t.content??""};case"ai":return{type:"ai",content:t.content??""};case"tool_call":return{type:"tool_call",content:t.name??"",toolName:t.name,toolCallId:t.id,args:typeof t.args=="string"?t.args:JSON.stringify(t.args??{})};case"tool_result":return{type:"tool_result",content:t.output??"",toolName:t.name,toolCallId:t.id,artifacts:Array.isArray(t.artifacts)?t.artifacts:void 0,renderMode:t.render_mode??t.renderMode,html:t.html};case"done":return{type:"done",content:t.content??"",sessionId:t.sessionId??t.session_id??"",messageId:t.messageId??t.message_id};case"error":return{type:"error",content:t.message??"Unknown error"};case"interrupt":return{type:"interrupt",content:t.content??"",interrupt:{interruptId:t.interruptId??t.interrupt_id??"",interruptType:t.interruptType??t.interrupt_type??"confirm",content:t.content??"",options:t.options,placeholder:t.placeholder,inputType:t.inputType??t.input_type,maxLength:t.maxLength??t.max_length,required:t.required,fields:t.fields,metadata:t.metadata}};default:return null}}async function m(a,e,t){if(!a.body){t(new Error("Response body is null"));return}const n=a.body.getReader(),o=new TextDecoder;let r="";try{for(;;){const{value:s,done:i}=await n.read();if(i)break;r+=o.decode(s,{stream:!0});let c;for(;(c=r.indexOf(`
 
-`))!==-1;){const l=n.slice(0,i);n=n.slice(i+2);const d=f(l);d&&e(d)}}if(n.trim()){const a=f(n);a&&e(a)}}catch(a){(a==null?void 0:a.name)!=="AbortError"&&r(a instanceof Error?a:new Error(String(a)))}finally{try{t.releaseLock()}catch{}}}function m(s,e){const r=new AbortController,t=e.signal?I(e.signal,r.signal):r.signal,o={botId:s.getBotId(),message:e.message,sessionId:e.sessionId,stream:e.stream!==!1};return o.stream?s.streamPost("/chat",o,t).then(n=>{var a;if(!n.ok){(a=e.onError)==null||a.call(e,new Error(`HTTP ${n.status}`));return}return y(n,c=>{var i,l,d,u;c.type==="done"&&c.sessionId?(i=e.onDone)==null||i.call(e,{sessionId:c.sessionId,content:c.content}):c.type==="done"?(l=e.onDone)==null||l.call(e,{sessionId:"",content:c.content}):c.type==="error"?(d=e.onError)==null||d.call(e,new Error(c.content)):(u=e.onMessage)==null||u.call(e,c)},c=>{var i;return(i=e.onError)==null?void 0:i.call(e,c)})}).catch(n=>{var a;(n==null?void 0:n.name)!=="AbortError"&&((a=e.onError)==null||a.call(e,n instanceof Error?n:new Error(String(n))))}):s.post("/chat",o).then(n=>{var a;(a=e.onDone)==null||a.call(e,{sessionId:n.sessionId,content:n.content??""})}).catch(n=>{var a;(a=e.onError)==null||a.call(e,n instanceof Error?n:new Error(String(n)))}),r}function I(s,e){const r=new AbortController,t=()=>r.abort();return s.addEventListener("abort",t,{once:!0}),e.addEventListener("abort",t,{once:!0}),(s.aborted||e.aborted)&&r.abort(),r.signal}async function b(s){return(await s.post("/chat/sessions",{botId:s.getBotId()})).sessionId}function w(s){return{sessionId:s.threadId??s.sessionId,botId:s.botId,title:s.title,createTime:s.createTime,updateTime:s.updateTime}}async function k(s,e){const r=await s.get("/chat/conversations",{botId:s.getBotId(),page:(e==null?void 0:e.page)??1,size:(e==null?void 0:e.size)??20});return{...r,items:r.items.map(w)}}async function T(s,e,r){await s.patch(`/chat/conversations/${e}`,{title:r})}async function S(s,e){await s.del(`/chat/conversations/${e}`)}async function E(s,e){const r=await s.get(`/chat/conversations/${e}/messages`);return C(r)}function C(s){const e=[],r=[...s].sort((t,o)=>(t.seq??0)-(o.seq??0));for(const t of r){const o=t.role;if(o==="system")continue;const n=t.messageId??`msg_${t.id}`,a=new Date(t.createTime??"").getTime()||Date.now();if(o==="human")e.push({id:n,role:"user",parts:[{type:"text",content:t.content??""}],timestamp:a});else if(o==="ai"){const c=[];t.reasoning&&c.push({type:"thinking",content:t.reasoning}),t.content&&c.push({type:"text",content:t.content});const i=t.toolCalls;if(i&&Array.isArray(i))for(const l of i){let d;try{d=typeof l.args=="string"?l.args:JSON.stringify(l.args??{})}catch{d=String(l.args??"{}")}c.push({type:"tool_call",toolName:l.name??"",toolCallId:l.id??"",args:d})}e.push({id:n,role:"assistant",parts:c,timestamp:a})}else o==="tool"&&e.push({id:n,role:"assistant",parts:[{type:"tool_result",toolName:t.toolName??"",toolCallId:t.toolCallId??"",content:t.content??""}],timestamp:a})}return e}function P(s){const e=new g(s),r={getToken:async()=>{const t=await e.postPublic("/token",{botId:e.getBotId()});return e.setToken(t.appId,t.token),t},createSession:()=>b(e),chat:t=>m(e,t),listConversations:t=>k(e,t),renameConversation:(t,o)=>T(e,t,o),deleteConversation:t=>S(e,t),getMessages:t=>E(e,t),setToken:(t,o)=>e.setToken(t,o),feedback:(t,o)=>{var n;(n=r.onFeedback)==null||n.call(r,t,o)}};return r}exports.createSuperAgent=P;
+`))!==-1;){const l=r.slice(0,c);r=r.slice(c+2);const d=y(l);d&&e(d)}}if(r.trim()){const s=y(r);s&&e(s)}}catch(s){(s==null?void 0:s.name)!=="AbortError"&&t(s instanceof Error?s:new Error(String(s)))}finally{try{n.releaseLock()}catch{}}}function k(a,e){const t=new AbortController,n=e.signal?b(e.signal,t.signal):t.signal,o={botId:a.getBotId(),message:e.message,sessionId:e.sessionId,stream:e.stream!==!1};return o.stream?a.streamPost("/chat",o,n).then(r=>{var s;if(!r.ok){(s=e.onError)==null||s.call(e,new Error(`HTTP ${r.status}`));return}return m(r,i=>{var c,l,d,h;i.type==="done"&&i.sessionId?(c=e.onDone)==null||c.call(e,{sessionId:i.sessionId,content:i.content,messageId:i.messageId}):i.type==="done"?(l=e.onDone)==null||l.call(e,{sessionId:"",content:i.content,messageId:i.messageId}):i.type==="error"?(d=e.onError)==null||d.call(e,new Error(i.content)):(h=e.onMessage)==null||h.call(e,i)},i=>{var c;return(c=e.onError)==null?void 0:c.call(e,i)})}).catch(r=>{var s;(r==null?void 0:r.name)!=="AbortError"&&((s=e.onError)==null||s.call(e,r instanceof Error?r:new Error(String(r))))}):a.post("/chat",o).then(r=>{var s;(s=e.onDone)==null||s.call(e,{sessionId:r.sessionId,content:r.content??""})}).catch(r=>{var s;(s=e.onError)==null||s.call(e,r instanceof Error?r:new Error(String(r)))}),t}function b(a,e){const t=new AbortController,n=()=>t.abort();return a.addEventListener("abort",n,{once:!0}),e.addEventListener("abort",n,{once:!0}),(a.aborted||e.aborted)&&t.abort(),t.signal}async function T(a){return(await a.post("/chat/sessions",{botId:a.getBotId()})).sessionId}function S(a){return{sessionId:a.threadId??a.sessionId,botId:a.botId,title:a.title,createTime:a.createTime,updateTime:a.updateTime}}async function p(a,e){const t=await a.get("/chat/conversations",{botId:a.getBotId(),page:(e==null?void 0:e.page)??1,size:(e==null?void 0:e.size)??20});return{...t,items:t.items.map(S)}}async function $(a,e,t){await a.patch(`/chat/conversations/${e}`,{title:t})}async function A(a,e){await a.del(`/chat/conversations/${e}`)}async function C(a,e){const t=await a.get(`/chat/conversations/${e}/messages`);return O(t)}function O(a){var n,o,r;const e=[],t=[...a].sort((s,i)=>(s.seq??0)-(i.seq??0));for(const s of t){const i=s.role;if(i==="system")continue;const c=s.messageId??`msg_${s.id}`,l=new Date(s.createTime??"").getTime()||Date.now();if(i==="human")e.push({id:c,role:"user",parts:[{type:"text",content:s.content??""}],timestamp:l});else if(i==="ai"){const d=[];s.reasoning&&d.push({type:"thinking",content:s.reasoning}),s.content&&d.push({type:"text",content:s.content});const h=s.toolCalls;if(h&&Array.isArray(h))for(const u of h){let g;try{g=typeof u.args=="string"?u.args:JSON.stringify(u.args??{})}catch{g=String(u.args??"{}")}d.push({type:"tool_call",toolName:u.name??"",toolCallId:u.id??"",args:g})}e.push({id:c,role:"assistant",parts:d,timestamp:l})}else if(i==="tool"){const d=Array.isArray(s.artifacts)?s.artifacts:void 0;e.push({id:c,role:"assistant",parts:[{type:"tool_result",toolName:s.toolName??"",toolCallId:s.toolCallId??"",content:s.content??"",artifacts:d,renderMode:((n=s.metadata)==null?void 0:n.renderMode)??((o=s.metadata)==null?void 0:o.render_mode),html:(r=s.metadata)==null?void 0:r.html}],timestamp:l})}}return e}async function _(a,e,t,n,o,r){const s=await a.streamPost(`/chat/interrupt/${e}/respond`,{sessionId:t,action:n.action,value:n.value});if(!s.ok){const i=new Error(`HTTP ${s.status}`);throw r==null||r(i),i}o&&await m(s,i=>{i.type==="error"?r==null||r(new Error(i.content)):o(i)},i=>r==null?void 0:r(i))}function v(a){const e=new I(a);return{getToken:()=>e.fetchToken(),createSession:()=>T(e),chat:n=>k(e,n),listConversations:n=>p(e,n),renameConversation:(n,o)=>$(e,n,o),deleteConversation:n=>A(e,n),getMessages:n=>C(e,n),respondInterrupt:(n,o,r,s,i)=>_(e,n,o,r,s,i),setToken:n=>e.setToken(n),feedback:async(n,o,r)=>{const s={type:o};o==="dislike"&&((r==null?void 0:r.reason)!=null&&(s.reason=r.reason),r!=null&&r.remark&&(s.remark=r.remark)),await e.post(`/chat/messages/${n}/feedback`,s)},cancelFeedback:async n=>{await e.del(`/chat/messages/${n}/feedback`)}}}exports.createSuperAgent=v;

package/dist/index.d.ts

@@ -1,10 +1,31 @@
+/** 通用产物（INTERFACE 约定：type + data，适配 table/chart/file/text/image/html/custom） */
+export declare interface Artifact {
+    type: string;
+    data: Record<string, any>;
+}
+
+export declare interface ArtifactFile {
+    id: string;
+    type: "html" | "pdf" | "docx" | string;
+    filename: string;
+    url: string;
+    mime?: string;
+    size?: number;
+    summary?: string;
+}
+
 export declare interface ChatEvent {
-    type: "user" | "thinking" | "ai" | "tool_call" | "tool_result" | "done" | "error";
+    type: "user" | "thinking" | "ai" | "tool_call" | "tool_result" | "done" | "error" | "interrupt";
     content: string;
     toolName?: string;
     toolCallId?: string;
     args?: string;
     sessionId?: string;
+    messageId?: string;
+    interrupt?: InterruptEvent;
+    artifacts?: Artifact[];
+    renderMode?: string;
+    html?: string;
 }
 
 export declare interface ChatOptions {
@@ -16,6 +37,7 @@ export declare interface ChatOptions {
     onDone?: (result: {
         sessionId: string;
         content: string;
+        messageId?: string;
     }) => void;
     signal?: AbortSignal;
 }
@@ -30,6 +52,44 @@ export declare interface Conversation {
 
 export declare function createSuperAgent(config: SDKConfig): SuperAgentSDK;
 
+export declare interface FormField {
+    name: string;
+    label: string;
+    type: 'text' | 'number' | 'password' | 'textarea' | 'select' | 'date';
+    required?: boolean;
+    placeholder?: string;
+    defaultValue?: any;
+    options?: string[];
+}
+
+export declare interface InterruptEvent {
+    interruptId: string;
+    interruptType: InterruptType;
+    content: string;
+    options?: (string | InterruptOption)[];
+    placeholder?: string;
+    inputType?: 'text' | 'number' | 'password' | 'textarea';
+    maxLength?: number;
+    required?: boolean;
+    fields?: FormField[];
+    metadata?: Record<string, any>;
+}
+
+export declare interface InterruptOption {
+    value: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    danger?: boolean;
+}
+
+export declare interface InterruptResponse {
+    action: string;
+    value?: any;
+}
+
+export declare type InterruptType = 'confirm' | 'select' | 'multiSelect' | 'input' | 'form' | 'approve';
+
 export declare interface ListConversationsParams {
     page?: number;
     size?: number;
@@ -56,24 +116,30 @@ export declare type MessagePart = {
     toolName: string;
     toolCallId: string;
     content: string;
+    artifacts?: Artifact[];
+    renderMode?: string;
+    html?: string;
 } | {
     type: "error";
     content: string;
+} | {
+    type: "interrupt";
+    interrupt: InterruptEvent;
+    resolved?: boolean;
+    response?: InterruptResponse;
 };
 
 export declare interface SDKConfig {
-    baseUrl: string;
     botId: number;
+    tokenGateway: string;
+    baseUrl?: string;
     appId?: string;
     token?: string;
 }
 
 export declare interface SuperAgentSDK {
-    /** 获取 token（调用 POST /token），自动设置内部凭证 */
-    getToken(): Promise<{
-        appId: string;
-        token: string;
-    }>;
+    /** 获取 token（调用 POST {tokenGateway}/v1/token），自动设置内部凭证 */
+    getToken(): Promise<string>;
     /** 创建新会话，返回 sessionId */
     createSession(): Promise<string>;
     chat(options: ChatOptions): AbortController;
@@ -81,9 +147,16 @@ export declare interface SuperAgentSDK {
     renameConversation(sessionId: string, title: string): Promise<void>;
     deleteConversation(sessionId: string): Promise<void>;
     getMessages(sessionId: string): Promise<UIMessage[]>;
-    setToken(appId: string, token: string): void;
-    feedback(sessionId: string, type: "like" | "dislike"): void;
-    onFeedback?: (sessionId: string, type: "like" | "dislike") => void;
+    /** 响应中断事件（返回 SSE 流，后端继续推送后续事件） */
+    respondInterrupt(interruptId: string, sessionId: string, response: InterruptResponse, onMessage?: (event: ChatEvent) => void, onError?: (error: Error) => void): Promise<void>;
+    setToken(token: string): void;
+    /** 消息反馈（赞/踩），POST /chat/messages/{messageId}/feedback */
+    feedback(messageId: string, type: "like" | "dislike", options?: {
+        reason?: number;
+        remark?: string;
+    }): Promise<void>;
+    /** 取消消息反馈，DELETE /chat/messages/{messageId}/feedback */
+    cancelFeedback(messageId: string): Promise<void>;
 }
 
 export declare interface UIMessage {