super-agent-sdk 1.0.7 → 1.0.9

package/README.md

@@ -24,10 +24,10 @@ Super Agent Web SDK —— 为 `super-agent-service` 提供的一站式浏览器
 
 `super-agent-sdk` 提供两个入口：
 
-| 入口                      | 说明                                                       | 依赖       |
-| ------------------------- | ---------------------------------------------------------- | ---------- |
-| `super-agent-sdk`        | 纯 JS API 调用层，封装鉴权、SSE 流式解析、会话与消息接口   | 无 UI 依赖 |
-| `super-agent-sdk/widget` | 可嵌入式 React 聊天组件 | React 18+  |
+| 入口                     | 说明                                                     | 依赖       |
+| ------------------------ | -------------------------------------------------------- | ---------- |
+| `super-agent-sdk`        | 纯 JS API 调用层，封装鉴权、SSE 流式解析、会话与消息接口 | 无 UI 依赖 |
+| `super-agent-sdk/widget` | 可嵌入式 React 聊天组件                                  | React 18+  |
 
 核心能力：
 
@@ -83,11 +83,11 @@ function createSuperAgent(config: SDKConfig): SuperAgentSDK;
 
 ```ts
 export interface SDKConfig {
-  botId: number;          // Bot ID（必填）
-  tokenGateway: string;   // Token 网关前缀（必填，不带 host），如 "/api/gateway"；token URL = {origin}{tokenGateway}/v1/token
-  baseUrl?: string;       // 业务接口前缀（可选，默认 "/api/agent/runtime/v1"），不带 host
-  appId?: string;         // 可选，不传则从 token 接口响应自动获取
-  token?: string;         // 可选，不传则自动调 token 接口获取
+  botId: number; // Bot ID（必填）
+  tokenGateway: string; // Token 网关前缀（必填，不带 host），如 "/api/gateway"；token URL = {origin}{tokenGateway}/v1/token
+  baseUrl?: string; // 业务接口前缀（可选，默认 "/api/agent/runtime/v1"），不带 host
+  appId?: string; // 可选，不传则从 token 接口响应自动获取
+  token?: string; // 可选，不传则自动调 token 接口获取
 }
 ```
 
@@ -131,6 +131,7 @@ ready
 
 ```ts
 export interface SuperAgentSDK {
+  readonly botId: number; // 当前 Bot ID
   createSession(): Promise<string>;
   chat(options: ChatOptions): AbortController;
   listConversations(
@@ -141,9 +142,19 @@ export interface SuperAgentSDK {
   getMessages(sessionId: string): Promise<UIMessage[]>;
   getToken(): Promise<string>;
   setToken(token: string): void;
-  feedback(messageId: string, type: "like" | "dislike", options?: { reason?: number; remark?: string }): Promise<void>;
+  feedback(
+    messageId: string,
+    type: "like" | "dislike",
+    options?: { reason?: number; remark?: string },
+  ): Promise<void>;
   cancelFeedback(messageId: string): Promise<void>;
-  respondInterrupt(interruptId: string, sessionId: string, response: InterruptResponse): Promise<void>;
+  respondInterrupt(
+    interruptId: string,
+    sessionId: string,
+    response: InterruptResponse,
+    onMessage?: (event: ChatEvent) => void,
+    onError?: (error: Error) => void,
+  ): Promise<void>;
   listSkills(): Promise<SkillInfo[]>;
   stopGeneration(sessionId: string): Promise<void>;
 }
@@ -175,7 +186,11 @@ export interface ChatOptions {
   stream?: boolean; // 默认 true
   onMessage?: (event: ChatEvent) => void;
   onError?: (error: Error) => void;
-  onDone?: (result: { sessionId: string; content: string }) => void;
+  onDone?: (result: {
+    sessionId: string;
+    content: string;
+    messageId?: string;
+  }) => void; // messageId：后端在 done 事件返回的消息标识（存在时 SDK Widget 用其启用消息反馈，若返回可据此判断该消息可 feedback）
   signal?: AbortSignal;
 }
 ```
@@ -303,41 +318,74 @@ sdk.setToken("<TOKEN>");
 
 消息反馈（赞/踩）。调用 `sdk.feedback()` 发送 `POST /chat/messages/{messageId}/feedback`；调用 `sdk.cancelFeedback()` 发送 `DELETE` 取消反馈。
 
+> **messageId 说明**：即消息历史返回的表主键 `id`（数字），不是 `messageId`（UUID）。纯 API 模式从 `getMessages()` 结果取 `UIMessage.id`。
+
 ```ts
+const messages = await sdk.getMessages(sessionId);
+const aiMsg = messages.findLast((m) => m.role === "assistant");
+
 // 点赞
-await sdk.feedback("msg_123", "like");
+await sdk.feedback(aiMsg.id, "like");
 
 // 踩（可附原因 + 备注）
-await sdk.feedback("msg_123", "dislike", {
-  reason: 1,  // 1=事实错误 2=逻辑问题 3=不相关 4=信息过时 5=冗长啰嗦 6=难以理解
+await sdk.feedback(aiMsg.id, "dislike", {
+  reason: 1, // 1=事实错误 2=逻辑问题 3=不相关 4=信息过时 5=冗长啰嗦 6=难以理解
   remark: "时间描述有误",
 });
 
 // 取消反馈
-await sdk.cancelFeedback("msg_123");
+await sdk.cancelFeedback(aiMsg.id);
 ```
 
 组件内置的点赞/踩按钮已自动调用 `feedback()`/`cancelFeedback()`：
+
 - 点击已选中的按钮 → 取消（DELETE）
 - 点击另一个按钮 → 切换（POST）
 - 点踩时弹出原因选择面板（可选填原因 + 备注后提交）
+- 流式渲染期间消息尚无后端 ID（临时占位），此时点击反馈 SDK 会自动拉取一次历史消息解析真实 ID 再发送，业务方无感知
+
+### 5.10 respondInterrupt()
+
+响应中断事件（Human-in-the-Loop），后端继续推送后续 SSE 事件：
+
+```ts
+sdk.respondInterrupt(
+  interruptId: string,
+  sessionId: string,
+  response: InterruptResponse,
+  onMessage?: (event: ChatEvent) => void,
+  onError?: (error: Error) => void
+): Promise<void>
+```
+
+Widget 内置中断卡片会自动调用此方法，纯 API 模式需手动处理（详见 [12. Human-in-the-Loop](#12-human-in-the-loop)）。
+
+### 5.11 listSkills()
 
-### 5.10 后端接口对照
+获取当前 Bot 绑定的技能列表（用于 `/` 斜杠命令选择技能）：
+
+```ts
+const skills: SkillInfo[] = await sdk.listSkills();
+// [{ code: "web-searcher", name: "web-searcher", displayName: "网页搜索", description: "..." }]
+```
+
+### 5.12 后端接口对照
 
 SDK 方法 → 后端接口的完整映射：
 
 > 除 `getToken()` 外，其余接口请求均携带 `X-App-Id` 与 `X-Token` 请求头进行鉴权。
 
-| 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`/`stop` 事件含 `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`                               |
-| `stopGeneration()`    | `POST /chat/stop`         | `{ sessionId }`                         | `{ stopped: "pending", sessionId }`             |
-| `listSkills()`        | `GET /chat/bots/{botId}/skills` | —                                 | `[{ code, name, displayName, description }]`    |
+| 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`/`stop` 事件含 `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`                                          |
+| `respondInterrupt()`  | `POST /chat/interrupt/{interruptId}/respond` | `{ sessionId, action, value? }`         | SSE 流（后续事件）                              |
+| `stopGeneration()`    | `POST /chat/stop`                            | `{ sessionId }`                         | `{ stopped: "pending", sessionId }`             |
+| `listSkills()`        | `GET /chat/bots/{botId}/skills`              | —                                       | `[{ code, name, displayName, description }]`    |
 
 ---
 
@@ -363,7 +411,26 @@ export interface MountOptions {
   suggestedPrompts?: string[];
   title?: string; // 标题，默认 "AI Assistant"
   sidebarDefaultOpen?: boolean; // fullpage 模式：侧边栏初始展开（默认 true）
-  avatar?: AvatarConfig; // 自定义头像
+  avatar?: AvatarConfig; // 自定义头像（AI 消息始终有内置默认头像；用户头像未配置则不显示）
+  artifactPreview?: boolean; // 产物预览总开关（html/pdf/docx 预览 + 下载 + 全屏），默认 false
+  capabilities?: CapabilityItem[]; // floating 首页：能力清单（icon + 标签 + 描述）
+  quickLinks?: QuickLinkItem[]; // floating 首页：快速入口
+  logo?: string; // floating 首页居中 Logo（URL），默认 SDK 内置 Logo
+  triggerLogo?: string; // floating 触发按钮 Logo（URL），默认 SDK 内置 Logo
+  showTimestamp?: boolean; // 显示消息时间戳，默认 false 不显示
+}
+
+export interface CapabilityItem {
+  icon?: string; // 图标 URL
+  label: string; // 能力名称
+  desc?: string; // 能力描述（超长自动省略）
+}
+
+export interface QuickLinkItem {
+  icon?: string; // 图标 URL
+  label: string; // 入口名称
+  prompt?: string; // 点击后发送的消息
+  onClick?: () => void; // 自定义点击行为（优先于 prompt）
 }
 
 export interface WidgetInstance {
@@ -398,16 +465,38 @@ widget.destroy(); // 卸载并移除 DOM
 
 > 挂载后默认是收起状态，需调用 `widget.open()` 展开。
 
+### 6.2 源码接入（monorepo alias）注意事项
+
+Widget 内部使用 **Tailwind CSS**（utility 全部限定在 `[data-super-agent-widget]` 宿主选择器内、禁用 preflight，不影响宿主页样式）。分发包（`dist`）已内联全部样式；内置图片资产（Logo/图标/头像等）走 CDN 绝对路径（`src/widget/assets/index.ts` 的 `BASE_URL`），**npm 引入无需任何配置**（需能访问 CDN）。
+
+若宿主工程通过 vite alias 直接引用 SDK **源码**（如本仓库 frontend 的做法），则 SDK 的样式会由宿主自己的 PostCSS/Tailwind 管线处理，需要满足：
+
+1. 宿主 `tailwind.config` 的 `content` 包含 SDK 源码路径，否则 widget 的 utility 类不会生成：
+
+```ts
+// frontend/tailwind.config.ts
+export default {
+  content: [
+    './index.html',
+    './src/**/*.{js,jsx,ts,tsx}',
+    '../sdk/src/**/*.{ts,tsx}', // SDK 源码
+  ],
+  // ...
+};
+```
+
+2. 无需在宿主 config 中镜像 SDK 的 `important: '[data-super-agent-widget]'`（那会把宿主自己的 utility 也锁进 widget 容器内）；宿主管线生成的 utility 为普通类，widget DOM 照常命中，动画/自定义类由 SDK 自带的 `tailwind.css`（运行时注入）保证。
+
 ---
 
 ## 7. 展示模式
 
 通过 `mode` 切换两种展示模式：
 
-| 模式               | 说明                                           |
-| ------------------ | ---------------------------------------------- |
-| `floating`（默认） | 右下角悬浮气泡，点击展开弹窗面板               |
-| `fullpage`         | 整页布局，DeepSeek 风格左侧会话栏 + 右侧聊天区 |
+| 模式               | 说明                                                       |
+| ------------------ | ---------------------------------------------------------- |
+| `floating`（默认） | 右下角 Logo 触发按钮 + 可拖拽/拉伸/最大化的浮窗聊天窗口     |
+| `fullpage`         | 整页布局，左侧会话栏（hr-for-help 风格）+ 右侧聊天区        |
 
 ```ts
 mount("#chat-root", { sdk, mode: "fullpage" });
@@ -419,6 +508,21 @@ mount("#chat-root", { sdk, mode: "fullpage" });
 mount("#chat-root", { sdk, mode: "fullpage", sidebarDefaultOpen: false });
 ```
 
+### 7.1 浮窗模式（floating）交互
+
+浮窗窗口对齐 hr-for-help 设计，开箱具备以下交互能力：
+
+- **标题栏拖拽**：按住顶部导航栏移动窗口（视口内钳制，按钮区域不触发）
+- **左右拉伸调宽**：窗口左右两侧 6px 手柄拖拽，宽度范围 360 ~ 800 px，拖超过 800 自动进入大窗
+- **大窗/小窗切换**：header 右侧「大窗」按钮切换；大窗为底部弹出的近全屏 overlay（内容区 800px 居中），回小窗时宽度重置为默认值
+- **内容自适应高度**：聊天内容增长时窗口自动变高（默认 648px，上限 95% 视口，超出后消息区滚动），回到首页恢复默认高度
+- **内嵌会话侧边栏**：header「历史记录」按钮开合；小窗展开时窗口自动加宽 200px；大窗模式自动展开（220px），大窗/小窗各自记住用户偏好
+- **关闭即还原**：关闭窗口后几何状态（位置/宽度/大窗态/高度）全部重置
+
+浮窗消息展示对齐 hr-for-help：AI 头像独占一行（无背景色，生成中切换动效头像）、气泡白底描边、用户气泡浅蓝右对齐；`fullpage` 模式保持横排头像 + 经典气泡，两者互不影响。
+
+首页（无消息时）包含：居中 Logo（浮动动画）+ 流光渐变标题 + 能力清单 + 建议词 chips + 快速入口，内容通过 `capabilities` / `suggestedPrompts` / `quickLinks` / `logo` 配置（见 6.1；icon 可复用 `super-agent-sdk/widget` 导出的内置 `ASSETS`）。
+
 ---
 
 ## 8. 定制化
@@ -433,8 +537,8 @@ export interface ThemeConfig {
   backgroundColor?: string; // 默认 #ffffff
   fontFamily?: string; // 默认 system-ui, -apple-system, sans-serif
   borderRadius?: number; // 默认 16 (px)
-  panelWidth?: number; // 默认 380 (px)
-  panelHeight?: number; // 默认 520 (px)
+  panelWidth?: number; // floating 初始宽度，默认 400 (px)
+  panelHeight?: number; // floating 初始高度，默认 648 (px)
   zIndex?: number; // 默认 9999
 }
 ```
@@ -447,8 +551,8 @@ export interface ThemeConfig {
 | `--sa-bg`           | `#ffffff`                              | `backgroundColor` |
 | `--sa-font`         | `system-ui, -apple-system, sans-serif` | `fontFamily`      |
 | `--sa-radius`       | `16px`                                 | `borderRadius`    |
-| `--sa-panel-width`  | `380px`                                | `panelWidth`      |
-| `--sa-panel-height` | `520px`                                | `panelHeight`     |
+| `--sa-panel-width`  | `400px`                                | `panelWidth`      |
+| `--sa-panel-height` | `648px`                                | `panelHeight`     |
 | `--sa-z-index`      | `9999`                                 | `zIndex`          |
 
 ```ts
@@ -468,12 +572,12 @@ mount("#chat-root", {
 
 ### 8.2 头像定制
 
-通过 `avatar` 配置助手与用户的头像，支持 URL、emoji 或文本（以 `http`、`/`、`data:` 开头视为图片 URL，否则作为 emoji/文本渲染）：
+通过 `avatar` 配置助手与用户的头像，支持图片 URL、emoji 或文本。以 `http(s)://`、`data:`、`blob:`、`/`、`./`、`../`、`//` 开头的字符串渲染为图片，其余作为 emoji/文本展示（无背景色）：
 
 ```ts
 export interface AvatarConfig {
-  assistant?: string; // URL、emoji 或文本
-  user?: string;
+  assistant?: string; // 图片 URL、emoji 或文本；默认 SDK 内置头像（生成中显示动效头像）
+  user?: string; // 图片 URL、emoji 或文本；未配置则不显示用户头像
 }
 ```
 
@@ -481,7 +585,7 @@ export interface AvatarConfig {
 mount("#chat-root", {
   sdk,
   avatar: {
-    assistant: "🤖",
+    assistant: "🤖", // 配置后覆盖内置默认头像
     user: "https://cdn.example.com/user-avatar.png",
   },
 });
@@ -504,24 +608,25 @@ export interface Slots {
   ToolCallPart?: ComponentType<ToolCallPartProps>;
   ToolResultPart?: ComponentType<ToolResultPartProps>;
   ErrorPart?: ComponentType<ErrorPartProps>;
+  InterruptCard?: ComponentType<InterruptCardProps>;
   WelcomeScreen?: ComponentType<WelcomeScreenProps>;
 }
 ```
 
-| 插槽             | Props 接口            | 说明                                        |
-| ---------------- | --------------------- | ------------------------------------------- |
-| `Trigger`        | `TriggerProps`        | 悬浮触发按钮                                |
-| `Header`         | `HeaderProps`         | 面板标题栏                                  |
-| `Message`        | `MessageProps`        | 单条消息容器（完整自定义消息渲染）          |
-| `Composer`       | `ComposerProps`       | 输入框 / 发送栏                             |
-| `ActionBar`      | `ActionBarProps`      | 消息操作栏（复制 / 重试 / 反馈）            |
-| `ThreadList`     | `ThreadListProps`     | 会话列表（浮窗模式覆盖层 / 全屏模式侧边栏） |
-| `ThinkingPart`   | `ThinkingPartProps`   | 思考过程块                                  |
-| `TextPart`       | `TextPartProps`       | 文本块                                      |
-| `ToolCallPart`   | `ToolCallPartProps`   | 工具调用卡片                                |
-| `ToolResultPart` | `ToolResultPartProps` | 工具返回卡片                                |
-| `ErrorPart`      | `ErrorPartProps`      | 错误提示块                                  |
-| `WelcomeScreen`  | `WelcomeScreenProps`  | 空会话欢迎页                                |
+| 插槽             | Props 接口            | 说明                                                                                               |
+| ---------------- | --------------------- | -------------------------------------------------------------------------------------------------- |
+| `Trigger`        | `TriggerProps`        | 悬浮触发按钮                                                                                       |
+| `Header`         | `HeaderProps`         | 面板标题栏                                                                                         |
+| `Message`        | `MessageProps`        | 单条消息容器（完整自定义消息渲染）                                                                 |
+| `Composer`       | `ComposerProps`       | 输入框 / 发送栏                                                                                    |
+| `ActionBar`      | `ActionBarProps`      | 消息操作栏（复制 / 重试 / 反馈）                                                                   |
+| `ThreadList`     | `ThreadListProps`     | 会话列表（浮窗模式覆盖层 / 全屏模式侧边栏）                                                        |
+| `ThinkingPart`   | `ThinkingPartProps`   | 思考过程块                                                                                         |
+| `TextPart`       | `TextPartProps`       | 文本块                                                                                             |
+| `ToolCallPart`   | `ToolCallPartProps`   | 工具调用卡片（可折叠 + 展开后复制参数）                                                            |
+| `ToolResultPart` | `ToolResultPartProps` | 工具返回卡片（pre 滚动 + 复制；`renderMode==="html"` 时 DOMPurify 清洗后直接渲染，最高 60vh 滚动） |
+| `ErrorPart`      | `ErrorPartProps`      | 错误提示块                                                                                         |
+| `WelcomeScreen`  | `WelcomeScreenProps`  | 空会话欢迎页                                                                                       |
 
 #### Trigger
 
@@ -530,6 +635,7 @@ export interface TriggerProps {
   isOpen: boolean;
   onClick: () => void;
   unreadCount?: number;
+  triggerLogo?: string; // 触发按钮 Logo（URL）
 }
 ```
 
@@ -549,11 +655,21 @@ function MyTrigger({ isOpen, onClick, unreadCount }: TriggerProps) {
 
 #### Header
 
+floating 与 fullpage 模式均支持替换；`onToggleThreadList` 在 floating 下切换内嵌会话侧边栏、在 fullpage 下切换左侧边栏；开启 `artifactPreview` 后额外提供产物入口字段。
+
+> 注：fullpage 内置 Header 只有标题与产物入口（无关闭按钮）；需要关闭入口时通过自定义 Header 的 `onClose` 自行渲染。floating 内置 Header 含历史/回首页/大窗/关闭按钮。
+
 ```ts
 export interface HeaderProps {
   title: string;
   onClose: () => void;
   onToggleThreadList: () => void;
+  isMaximized?: boolean;        // floating：大窗状态
+  onToggleMaximize?: () => void; // floating：大窗/小窗切换
+  showHome?: boolean;           // floating：聊天态显示回到首页
+  onHome?: () => void;          // floating：回到首页（新会话）
+  artifactCount?: number;       // 会话产物数量（artifactPreview 开启时提供）
+  onToggleArtifactDrawer?: () => void; // 打开/关闭产物预览抽屉
 }
 ```
 
@@ -697,8 +813,12 @@ function MyComposer({ status, onSend, onStop }: ComposerProps) {
 export interface ActionBarProps {
   message: UIMessage;
   onCopy: () => void;
-  onRegenerate: () => void;
-  onFeedback?: (messageId: string, feedback: "like" | "dislike") => void;
+  onRegenerate?: () => void;
+  onFeedback?: (
+    messageId: string,
+    feedback: "like" | "dislike",
+    options?: { reason?: number; remark?: string },
+  ) => void;
 }
 ```
 
@@ -720,9 +840,9 @@ function MyActionBar({
 }
 ```
 
-#### ThreadList（浮窗模式覆盖层 + 全屏模式侧边栏）
+#### ThreadList（浮窗内嵌会话侧边栏 + 全屏模式侧边栏）
 
-在 `floating` 模式下作为覆盖层渲染；在 `fullpage` 模式下作为侧边栏渲染。
+在 `floating` 模式下作为窗口内嵌侧边栏渲染（小窗 200px / 大窗 220px，随「历史记录」按钮开合）；在 `fullpage` 模式下作为左侧侧边栏渲染（220px，可收起为图标栏）。
 
 ```ts
 export interface ThreadListProps {
@@ -797,6 +917,10 @@ export interface ToolResultPartProps {
   toolName: string;
   toolCallId: string;
   content: string;
+  artifacts?: Artifact[];
+  renderMode?: string;
+  html?: string;
+  artifactPreview?: boolean;
 }
 export interface ErrorPartProps {
   content: string;
@@ -1113,7 +1237,7 @@ await sdk.deleteConversation(items[0].sessionId);
 - **新建**：点击「新会话」清空当前消息，下次发送时自动调用 `createSession()` 创建新会话。
 - **重命名**：`fullpage` 侧边栏或自定义 `ThreadList` 中调用 `renameConversation`。
 - **删除**：悬停会话项后点击删除按钮。
-- **本地持久化**：最近一次活跃会话写入 `localStorage`，键为 `sa_active_conversation`。
+- **本地持久化**：最近一次活跃会话写入 `localStorage`，键为 `sa_active_conversation_{botId}`（按 Bot 隔离，切换 Bot 后互不串扰）。
 
 ---
 
@@ -1136,7 +1260,7 @@ const controller = sdk.chat({
   message: "...",
   stream: true,
   onMessage: (event) => {
-    if (event.type === 'stop') {
+    if (event.type === "stop") {
       // 用户主动停止，event.content 为已生成的半截回复全文
       console.log("已停止，半截回复：", event.content);
     }
@@ -1185,7 +1309,7 @@ ac.abort();
 
 页面刷新或组件重新挂载时，会话状态自动恢复：
 
-1. 挂载时从 `localStorage` 读取上次活跃会话 ID（键 `sa_active_conversation`）。
+1. 挂载时从 `localStorage` 读取上次活跃会话 ID（键 `sa_active_conversation_{botId}`）。
 2. 若该会话仍在列表中，自动调用 `getMessages` 拉取历史消息并渲染。
 3. 若存储的会话已不存在（被删除），则自动清空并回退到「新会话」。
 
@@ -1218,17 +1342,27 @@ export type MessagePart =
       toolName: string;
       toolCallId: string;
       content: string;
+      artifacts?: Artifact[];
+      renderMode?: string;
+      html?: string;
     }
-  | { type: "error"; content: string };
-```
-
-| type          | 字段                                | 说明                            |
-| ------------- | ----------------------------------- | ------------------------------- |
-| `text`        | `content`                           | 文本 / Markdown 内容            |
-| `thinking`    | `content`                           | 思考过程（reasoning）           |
-| `tool_call`   | `toolName`, `toolCallId`, `args`    | 工具调用，`args` 为 JSON 字符串 |
-| `tool_result` | `toolName`, `toolCallId`, `content` | 工具返回结果                    |
-| `error`       | `content`                           | 错误信息                        |
+  | { type: "error"; content: string }
+  | {
+      type: "interrupt";
+      interrupt: InterruptEvent;
+      resolved?: boolean;
+      response?: InterruptResponse;
+    };
+```
+
+| type          | 字段                                                                      | 说明                            |
+| ------------- | ------------------------------------------------------------------------- | ------------------------------- |
+| `text`        | `content`                                                                 | 文本 / Markdown 内容            |
+| `thinking`    | `content`                                                                 | 思考过程（reasoning）           |
+| `tool_call`   | `toolName`, `toolCallId`, `args`                                          | 工具调用，`args` 为 JSON 字符串 |
+| `tool_result` | `toolName`, `toolCallId`, `content`, `artifacts?`, `renderMode?`, `html?` | 工具返回结果                    |
+| `error`       | `content`                                                                 | 错误信息                        |
+| `interrupt`   | `interrupt`, `resolved?`, `response?`                                     | 中断交互卡片（HITL）            |
 
 ### 11.3 ChatEvent（流式事件）
 
@@ -1242,12 +1376,18 @@ export interface ChatEvent {
     | "tool_result"
     | "done"
     | "stop"
-    | "error";
+    | "error"
+    | "interrupt";
   content: string;
   toolName?: string;
   toolCallId?: string;
   args?: string; // JSON.stringify 后的字符串
   sessionId?: string;
+  messageId?: string; // done 事件携带后端消息标识（后端返回时该消息可反馈/feedback）
+  interrupt?: InterruptEvent; // interrupt 事件携带中断详情
+  artifacts?: Artifact[]; // tool_result 事件携带的结构化产物
+  renderMode?: string; // "html" 时工具结果为富文本
+  html?: string; // renderMode==="html" 时的 HTML 内容
 }
 ```
 
@@ -1283,7 +1423,7 @@ Agent 执行中
 ### 12.3 响应中断
 
 ```ts
-await sdk.respondInterrupt(interruptId, {
+await sdk.respondInterrupt(interruptId, sessionId, {
   action: "confirm",
 });
 ```
@@ -1303,7 +1443,7 @@ mount("#chat", { sdk }).open();
 mount("#chat", {
   sdk,
   slots: {
-    InterruptCard: MyInterruptCard,   // 自定义全部类型
+    InterruptCard: MyInterruptCard, // 自定义全部类型
   },
 });
 ```
@@ -1318,7 +1458,7 @@ sdk.chat({
     if (e.type === "interrupt" && e.interrupt) {
       // 自定义 UI 处理
       const ok = window.confirm(e.interrupt.content);
-      sdk.respondInterrupt(e.interrupt.interruptId, {
+      sdk.respondInterrupt(e.interrupt.interruptId, sessionId, {
         action: ok ? "confirm" : "cancel",
       });
     }
@@ -1328,23 +1468,25 @@ sdk.chat({
 
 ### 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 | 交互     | 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 }` |
+
+> `form` 的字段定义见 `FormField`（`types.ts`）：`type` 支持 `text` / `number` / `password` / `textarea` / `select` / `multiSelect` / `date`；`options` 支持字符串数组或 `{ value, label }` 数组。已回答的历史 interrupt 以禁用态回显用户答案。
 
 > 每个 `interruptType` 的完整字段定义见 [API 文档](./API.md) 与 [HITL 设计文档](../docs/superpowers/specs/2026-08-18-human-in-the-loop-design.md)。
 
@@ -1404,6 +1546,10 @@ interface UseChatReturn {
   stop: () => void;
   regenerate: () => void;
   setMessages: (messages: UIMessage[]) => void;
+  respondToInterrupt: (
+    interruptId: string,
+    response: InterruptResponse,
+  ) => void;
 }
 ```
 
@@ -1415,15 +1561,18 @@ export function useConversations(
 interface UseConversationsOptions {
   sdk: SuperAgentSDK;
   onConversationChange?: (sessionId: string) => void;
+  enabled?: boolean; // 默认 true，false 时不自动加载
 }
 
 interface UseConversationsReturn {
   conversations: Conversation[];
   activeConversationId: string | null;
   loading: boolean;
+  hasMore: boolean;
   loadConversations: () => Promise<void>;
+  loadMore: () => Promise<void>;
   switchConversation: (sessionId: string) => Promise<UIMessage[]>;
-  newConversation: () => void;
+  newConversation: () => Promise<void>;
   deleteConversation: (sessionId: string) => Promise<void>;
   renameConversation: (sessionId: string, title: string) => Promise<void>;
   setActiveConversationId: (id: string | null) => void;