super-agent-sdk 1.0.0

package/README.md

@@ -0,0 +1,1316 @@
+# @super-agent/sdk
+
+Super Agent Web SDK —— 为 `super-agent-service` 提供的一站式浏览器端集成方案：既包含纯 JS 的 API 调用层（鉴权、SSE 流式解析、会话与消息接口），也包含开箱即用的嵌入式 React 聊天组件。
+
+## 目录
+
+1. [概述](#1-概述)
+2. [安装](#2-安装)
+3. [快速开始](#3-快速开始)
+4. [SDK 初始化](#4-sdk-初始化)
+5. [API 参考](#5-api-参考)
+6. [聊天组件](#6-聊天组件)
+7. [展示模式](#7-展示模式)
+8. [定制化](#8-定制化)
+9. [会话管理](#9-会话管理)
+10. [中断恢复](#10-中断恢复)
+11. [消息类型](#11-消息类型)
+12. [高级用法](#12-高级用法)
+
+---
+
+## 1. 概述
+
+`@super-agent/sdk` 提供两个入口：
+
+| 入口                      | 说明                                                       | 依赖       |
+| ------------------------- | ---------------------------------------------------------- | ---------- |
+| `@super-agent/sdk`        | 纯 JS API 调用层，封装鉴权、SSE 流式解析、会话与消息接口   | 无 UI 依赖 |
+| `@super-agent/sdk/widget` | 可嵌入式 React 聊天组件 | React 18+  |
+
+核心能力：
+
+- **纯 API 模式**：`createSuperAgent()` 返回轻量 SDK 实例，提供流式聊天、会话列表、历史消息、Token 刷新等能力。
+- **嵌入式组件**：`mount()` 挂载 React 聊天组件。
+- **两种展示模式**：`floating`（右下角气泡 + 弹窗面板）与 `fullpage`（整页 DeepSeek 风格布局）。
+- **会话持久化**：自动加载会话列表、`localStorage` 记住最近会话、刷新后自动恢复。
+
+---
+
+## 2. 安装
+
+```bash
+pnpm add @super-agent/sdk
+```
+
+纯 API 模式无需任何额外依赖。若使用聊天组件（widget），需同时安装 React：
+
+```bash
+pnpm add react react-dom
+```
+
+> `react` / `react-dom` 以 `peerDependencies`（可选）声明，版本要求 `>=18.0.0`。
+
+---
+
+## 3. 快速开始
+
+最简 5 行接入：
+
+```typescript
+import { createSuperAgent } from "@super-agent/sdk";
+import { mount } from "@super-agent/sdk/widget";
+
+const sdk = createSuperAgent({ baseUrl: "/api/v1", botId: 1 });
+// Token 自动获取，无需手动设置
+const widget = mount("#chat", { sdk });
+widget.open();
+```
+
+挂载完成后，页面右下角出现聊天气泡，点击展开面板即可开始对话。
+
+---
+
+## 4. SDK 初始化
+
+```ts
+function createSuperAgent(config: SDKConfig): SuperAgentSDK;
+```
+
+```ts
+export interface SDKConfig {
+  baseUrl: string; // e.g. "https://agent.example.com/api/v1"
+  botId: number; // bot ID
+}
+```
+
+只需提供 `baseUrl` 与 `botId` 即可。SDK 不要求在创建时传入 `appId` / `token`——组件挂载后会自动调用 `sdk.getToken()` 获取凭证并内部保存，无需手动设置。
+
+```ts
+const sdk = createSuperAgent({
+  baseUrl: "https://agent.example.com/api/v1",
+  botId: 1,
+});
+```
+
+凭证获取流程：
+
+```
+createSuperAgent({ baseUrl, botId })
+        ↓
+Widget 挂载时自动调用 sdk.getToken()
+        ↓
+POST /token { botId }
+        ↓
+后端返回 { app_id, token }
+        ↓
+SDK 内部自动保存凭证
+        ↓
+ready
+```
+
+出于安全考虑，`app_key` 应永远留在后端，浏览器端只持有短时有效的 Token。
+
+---
+
+## 5. API 参考
+
+> **字段命名映射**：后端接口返回的是 snake_case 字段，SDK 内部统一转换为 camelCase 后对外暴露。
+>
+> - 后端返回 `thread_id`（snake_case）→ SDK 内部映射为 `sessionId`
+> - 后端返回 `bot_id` → SDK 映射为 `botId`
+> - SDK 所有公开 API 均使用 camelCase（`sessionId`、`botId`）
+> - SDK 发起请求时同样使用 camelCase（如 `{ botId, sessionId, message }`）
+
+### 5.1 SDK 实例
+
+```ts
+export interface SuperAgentSDK {
+  createSession(): Promise<string>;
+  chat(options: ChatOptions): AbortController;
+  listConversations(
+    params?: ListConversationsParams,
+  ): Promise<ListConversationsResult>;
+  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;
+}
+```
+
+### 5.2 createSession()
+
+创建新会话，返回 `sessionId`。聊天前必须先创建会话。
+
+- SDK 调用 `POST /chat/sessions`，请求体为 `{ botId }`
+- 后端返回 `{ session_id: "..." }`
+- SDK 解析后返回 `sessionId` 字符串
+
+```ts
+const sessionId = await sdk.createSession();
+```
+
+### 5.3 chat()
+
+流式聊天。**`sessionId` 为必填**，必须先调用 `createSession()` 获取。返回 `AbortController`，可随时中断。
+
+- SDK 发送 `POST /chat`，请求体为 `{ botId, sessionId, message, stream }`
+- 后端 SSE 在 `done` 事件中返回 `session_id` → SDK 暴露为 `sessionId`
+
+```ts
+export interface ChatOptions {
+  sessionId: string; // 必填 — 先调用 createSession()
+  message: string;
+  stream?: boolean; // 默认 true
+  onMessage?: (event: ChatEvent) => void;
+  onError?: (error: Error) => void;
+  onDone?: (result: { sessionId: string; content: string }) => void;
+  signal?: AbortSignal;
+}
+```
+
+```ts
+const sessionId = await sdk.createSession();
+
+const controller = sdk.chat({
+  sessionId,
+  message: "帮我写一段排序算法",
+  stream: true, // 默认 true
+  onMessage: (event) => {
+    switch (event.type) {
+      case "thinking":
+        console.log("[思考]", event.content);
+        break;
+      case "ai":
+        process.stdout.write(event.content); // 增量输出
+        break;
+      case "tool_call":
+        console.log("[调用工具]", event.toolName, event.args);
+        break;
+      case "tool_result":
+        console.log("[工具结果]", event.content);
+        break;
+    }
+  },
+  onDone: ({ sessionId, content }) => {
+    console.log("\n完成，sessionId =", sessionId);
+  },
+  onError: (error) => {
+    console.error("出错：", error.message);
+  },
+});
+
+// 取消：controller.abort();
+```
+
+`stream: false` 时走非流式接口，`onDone` 收到完整回复：
+
+```ts
+sdk.chat({
+  sessionId,
+  message: "你好",
+  stream: false,
+  onDone: ({ sessionId, content }) => console.log("完整回复：", content),
+  onError: (error) => console.error(error),
+});
+```
+
+### 5.4 listConversations()
+
+```ts
+export interface ListConversationsParams {
+  page?: number; // 默认 1
+  size?: number; // 默认 20
+}
+
+export interface ListConversationsResult {
+  items: Conversation[];
+  total: number;
+}
+
+export interface Conversation {
+  sessionId: string;
+  botId: number;
+  title: string | null;
+  createTime: string;
+  updateTime: string;
+}
+```
+
+```ts
+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 }`
+
+### 5.5 getMessages()
+
+拉取会话历史消息，已转换为 UI 结构：
+
+```ts
+const messages: UIMessage[] = await sdk.getMessages(sessionId);
+```
+
+### 5.6 renameConversation() / deleteConversation()
+
+```ts
+await sdk.renameConversation(sessionId, "关于部署的讨论");
+await sdk.deleteConversation(sessionId);
+```
+
+### 5.7 getToken()
+
+```typescript
+sdk.getToken(): Promise<{ appId: string; token: string }>
+```
+
+自动获取并保存访问凭证：
+
+- SDK 调用 `POST /token`，请求体为 `{ botId }`（无需鉴权头）
+- 后端返回 `{ app_id, token }`
+- SDK 自动将凭证保存在内部
+- Widget 在挂载时自动调用此方法 —— 通常无需手动调用
+
+```ts
+const { appId, token } = await sdk.getToken();
+```
+
+### 5.8 setToken()
+
+```typescript
+sdk.setToken(appId: string, token: string): void
+```
+
+手动设置凭证（用于凭证由外部获取、或测试等场景）。正常情况下无需调用，Widget 挂载时会自动通过 `getToken()` 获取凭证。
+
+```ts
+sdk.setToken("<APP_ID>", "<TOKEN>");
+```
+
+### 5.9 feedback() / onFeedback
+
+点赞 / 踩：调用 `sdk.feedback()`，SDK 会回调你注册的 `sdk.onFeedback`。
+
+```ts
+sdk.onFeedback = (messageId, type) => {
+  // type: 'like' | 'dislike'
+  console.log(`Feedback: ${type} on message ${messageId}`);
+  // 上报到自己的业务后端
+};
+
+sdk.feedback("msg_123", "like");
+```
+
+组件内置的点赞 / 踩按钮也会经过 `sdk.feedback()`，因此只需注册一次 `onFeedback` 即可统一接收所有反馈。
+
+### 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 }` |
+
+字段命名转换规则：
+
+| 后端（snake_case） | SDK（camelCase） |
+| ------------------ | ---------------- |
+| `thread_id`        | `sessionId`      |
+| `bot_id`           | `botId`          |
+| `create_time`      | `createTime`     |
+| `update_time`      | `updateTime`     |
+
+---
+
+## 6. 聊天组件
+
+组件通过 `mount()` 从 `@super-agent/sdk/widget` 导入。
+
+### 6.1 mount()
+
+```ts
+export function mount(
+  target: string | HTMLElement,
+  options: MountOptions,
+): WidgetInstance;
+
+export interface MountOptions {
+  sdk: SuperAgentSDK;
+  mode?: WidgetMode; // 默认 'floating'
+  theme?: ThemeConfig;
+  slots?: Slots;
+  hooks?: EventHooks;
+  welcomeMessage?: string;
+  suggestedPrompts?: string[];
+  title?: string; // 标题，默认 "AI Assistant"
+  sidebarDefaultOpen?: boolean; // fullpage 模式：侧边栏初始展开（默认 true）
+  avatar?: AvatarConfig; // 自定义头像
+}
+
+export interface WidgetInstance {
+  open(): void;
+  close(): void;
+  destroy(): void;
+}
+```
+
+```ts
+import { createSuperAgent } from "@super-agent/sdk";
+import { mount } from "@super-agent/sdk/widget";
+
+const sdk = createSuperAgent({ baseUrl: "/api/v1", botId: 1 });
+
+const widget = mount("#chat-root", {
+  sdk,
+  mode: "floating",
+  title: "AI 助手",
+  welcomeMessage: "你好！有什么可以帮你的？",
+  suggestedPrompts: ["帮我写周报", "解释一下这段代码"],
+  theme: { primaryColor: "#6366f1" },
+});
+
+widget.open(); // 展开面板
+widget.close(); // 收起面板
+widget.destroy(); // 卸载并移除 DOM
+```
+
+> 挂载后默认是收起状态，需调用 `widget.open()` 展开。
+
+---
+
+## 7. 展示模式
+
+通过 `mode` 切换两种展示模式：
+
+| 模式               | 说明                                           |
+| ------------------ | ---------------------------------------------- |
+| `floating`（默认） | 右下角悬浮气泡，点击展开弹窗面板               |
+| `fullpage`         | 整页布局，DeepSeek 风格左侧会话栏 + 右侧聊天区 |
+
+```ts
+mount("#chat-root", { sdk, mode: "fullpage" });
+```
+
+`fullpage` 模式下，可通过 `sidebarDefaultOpen` 控制侧边栏初始展开状态：
+
+```ts
+mount("#chat-root", { sdk, mode: "fullpage", sidebarDefaultOpen: false });
+```
+
+---
+
+## 8. 定制化
+
+### 8.1 主题定制
+
+通过 `ThemeConfig` 定制外观，组件内部将其转换为 CSS 变量。
+
+```ts
+export interface ThemeConfig {
+  primaryColor?: string; // 默认 #6366f1
+  backgroundColor?: string; // 默认 #ffffff
+  fontFamily?: string; // 默认 system-ui, -apple-system, sans-serif
+  borderRadius?: number; // 默认 16 (px)
+  panelWidth?: number; // 默认 380 (px)
+  panelHeight?: number; // 默认 520 (px)
+  zIndex?: number; // 默认 9999
+}
+```
+
+对应的 CSS 变量：
+
+| 变量                | 默认值                                 | 对应字段          |
+| ------------------- | -------------------------------------- | ----------------- |
+| `--sa-primary`      | `#6366f1`                              | `primaryColor`    |
+| `--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-z-index`      | `9999`                                 | `zIndex`          |
+
+```ts
+mount("#chat-root", {
+  sdk,
+  theme: {
+    primaryColor: "#10b981",
+    backgroundColor: "#f9fafb",
+    fontFamily: "'PingFang SC', 'Microsoft YaHei', sans-serif",
+    borderRadius: 12,
+    panelWidth: 400,
+    panelHeight: 600,
+    zIndex: 10000,
+  },
+});
+```
+
+### 8.2 头像定制
+
+通过 `avatar` 配置助手与用户的头像，支持 URL、emoji 或文本（以 `http`、`/`、`data:` 开头视为图片 URL，否则作为 emoji/文本渲染）：
+
+```ts
+export interface AvatarConfig {
+  assistant?: string; // URL、emoji 或文本
+  user?: string;
+}
+```
+
+```ts
+mount("#chat-root", {
+  sdk,
+  avatar: {
+    assistant: "🤖",
+    user: "https://cdn.example.com/user-avatar.png",
+  },
+});
+```
+
+### 8.3 组件插槽（Slots）
+
+通过 `slots` 替换内置子组件。所有插槽 Props 均从 `@super-agent/sdk/widget` 导出。
+
+```ts
+export interface Slots {
+  Trigger?: ComponentType<TriggerProps>;
+  Header?: ComponentType<HeaderProps>;
+  Message?: ComponentType<MessageProps>;
+  Composer?: ComponentType<ComposerProps>;
+  ActionBar?: ComponentType<ActionBarProps>;
+  ThreadList?: ComponentType<ThreadListProps>;
+  ThinkingPart?: ComponentType<ThinkingPartProps>;
+  TextPart?: ComponentType<TextPartProps>;
+  ToolCallPart?: ComponentType<ToolCallPartProps>;
+  ToolResultPart?: ComponentType<ToolResultPartProps>;
+  ErrorPart?: ComponentType<ErrorPartProps>;
+  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`  | 空会话欢迎页                                |
+
+#### Trigger
+
+```ts
+export interface TriggerProps {
+  isOpen: boolean;
+  onClick: () => void;
+  unreadCount?: number;
+}
+```
+
+```tsx
+function MyTrigger({ isOpen, onClick, unreadCount }: TriggerProps) {
+  return (
+    <button
+      onClick={onClick}
+      style={{ position: "fixed", right: 24, bottom: 24 }}
+    >
+      {isOpen ? "关闭" : "聊天"}
+      {unreadCount ? <span>{unreadCount}</span> : null}
+    </button>
+  );
+}
+```
+
+#### Header
+
+```ts
+export interface HeaderProps {
+  title: string;
+  onClose: () => void;
+  onToggleThreadList: () => void;
+}
+```
+
+```tsx
+function MyHeader({ title, onClose, onToggleThreadList }: HeaderProps) {
+  return (
+    <div
+      style={{
+        display: "flex",
+        alignItems: "center",
+        padding: 12,
+        background: "#111",
+      }}
+    >
+      <span style={{ flex: 1, color: "#fff", fontWeight: 600 }}>{title}</span>
+      <button onClick={onToggleThreadList}>历史</button>
+      <button onClick={onClose}>关闭</button>
+    </div>
+  );
+}
+```
+
+#### Message（重点：完整自定义消息渲染）
+
+替换后接管整条消息的渲染，可完全自定义布局。`slots` 会透传进来，方便复用内置/自定义的 Part 组件。
+
+```ts
+export interface MessageProps {
+  message: UIMessage;
+  isStreaming: boolean;
+  isLast: boolean;
+  avatar?: AvatarConfig;
+  slots: Slots;
+  onCopy: () => void;
+  onRegenerate: () => void;
+  onFeedback?: (messageId: string, feedback: "like" | "dislike") => void;
+}
+```
+
+```tsx
+function MyMessage({
+  message,
+  isStreaming,
+  isLast,
+  avatar,
+  slots,
+  onCopy,
+  onRegenerate,
+  onFeedback,
+}: MessageProps) {
+  const isUser = message.role === "user";
+  return (
+    <div
+      style={{
+        display: "flex",
+        gap: 12,
+        justifyContent: isUser ? "flex-end" : "flex-start",
+      }}
+    >
+      {!isUser && <div>{avatar?.assistant ?? "A"}</div>}
+      <div style={{ maxWidth: "75%" }}>
+        {message.parts.map((part, idx) => {
+          switch (part.type) {
+            case "text":
+              return <div key={idx}>{part.content}</div>;
+            case "thinking":
+              return (
+                <div key={idx} style={{ fontStyle: "italic" }}>
+                  {part.content}
+                </div>
+              );
+            case "tool_call":
+              return <div key={idx}>[调用 {part.toolName}]</div>;
+            case "tool_result":
+              return <div key={idx}>[结果] {part.content}</div>;
+            case "error":
+              return (
+                <div key={idx} style={{ color: "red" }}>
+                  {part.content}
+                </div>
+              );
+          }
+        })}
+        {isStreaming && isLast && !isUser && <span>|</span>}
+        {!isUser && !isStreaming && (
+          <slots.ActionBar
+            message={message}
+            onCopy={onCopy}
+            onRegenerate={onRegenerate}
+            onFeedback={onFeedback}
+          />
+        )}
+      </div>
+      {isUser && <div>{avatar?.user ?? "U"}</div>}
+    </div>
+  );
+}
+```
+
+#### Composer
+
+```ts
+export interface ComposerProps {
+  status: ChatStatus;
+  onSend: (content: string) => void;
+  onStop: () => void;
+}
+```
+
+```tsx
+function MyComposer({ status, onSend, onStop }: ComposerProps) {
+  const [value, setValue] = useState("");
+  const streaming = status === "streaming";
+  return (
+    <div style={{ display: "flex", gap: 8, padding: 12 }}>
+      <input
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        style={{ flex: 1 }}
+      />
+      {streaming ? (
+        <button onClick={onStop}>停止</button>
+      ) : (
+        <button
+          onClick={() => {
+            onSend(value);
+            setValue("");
+          }}
+        >
+          发送
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+#### ActionBar（含 onFeedback）
+
+```ts
+export interface ActionBarProps {
+  message: UIMessage;
+  onCopy: () => void;
+  onRegenerate: () => void;
+  onFeedback?: (messageId: string, feedback: "like" | "dislike") => void;
+}
+```
+
+```tsx
+function MyActionBar({
+  message,
+  onCopy,
+  onRegenerate,
+  onFeedback,
+}: ActionBarProps) {
+  return (
+    <div style={{ display: "flex", gap: 8 }}>
+      <button onClick={onCopy}>复制</button>
+      <button onClick={onRegenerate}>重新生成</button>
+      <button onClick={() => onFeedback?.(message.id, "like")}>👍</button>
+      <button onClick={() => onFeedback?.(message.id, "dislike")}>👎</button>
+    </div>
+  );
+}
+```
+
+#### ThreadList（浮窗模式覆盖层 + 全屏模式侧边栏）
+
+在 `floating` 模式下作为覆盖层渲染；在 `fullpage` 模式下作为侧边栏渲染。
+
+```ts
+export interface ThreadListProps {
+  conversations: Conversation[];
+  activeSessionId: string | null;
+  onSwitch: (sessionId: string) => void;
+  onNew: () => void;
+  onDelete: (sessionId: string) => void;
+  onRename: (sessionId: string, title: string) => void;
+}
+```
+
+```tsx
+function MyThreadList({
+  conversations,
+  activeSessionId,
+  onSwitch,
+  onNew,
+  onDelete,
+  onRename,
+}: ThreadListProps) {
+  return (
+    <div>
+      <button onClick={onNew}>+ 新会话</button>
+      {conversations.map((conv) => (
+        <div
+          key={conv.sessionId}
+          onClick={() => onSwitch(conv.sessionId)}
+          style={{ fontWeight: conv.sessionId === activeSessionId ? 700 : 400 }}
+        >
+          {conv.title || "新会话"}
+          <button
+            onClick={(e) => {
+              e.stopPropagation();
+              onRename(conv.sessionId, prompt("新标题") || "");
+            }}
+          >
+            改
+          </button>
+          <button
+            onClick={(e) => {
+              e.stopPropagation();
+              onDelete(conv.sessionId);
+            }}
+          >
+            删
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+#### ThinkingPart / TextPart / ToolCallPart / ToolResultPart / ErrorPart
+
+```ts
+export interface ThinkingPartProps {
+  content: string;
+}
+export interface TextPartProps {
+  content: string;
+}
+export interface ToolCallPartProps {
+  toolName: string;
+  toolCallId: string;
+  args: string;
+}
+export interface ToolResultPartProps {
+  toolName: string;
+  toolCallId: string;
+  content: string;
+}
+export interface ErrorPartProps {
+  content: string;
+  onRetry?: () => void;
+}
+```
+
+```tsx
+function MyThinkingPart({ content }: ThinkingPartProps) {
+  return (
+    <div style={{ borderLeft: "3px solid #a855f7", padding: 6 }}>{content}</div>
+  );
+}
+
+function MyTextPart({ content }: TextPartProps) {
+  return <div style={{ whiteSpace: "pre-wrap" }}>{content}</div>;
+}
+
+function MyToolCallPart({ toolName, args }: ToolCallPartProps) {
+  return (
+    <div style={{ border: "1px solid #f59e0b" }}>
+      [调用 {toolName}] {args}
+    </div>
+  );
+}
+
+function MyToolResultPart({ toolName, content }: ToolResultPartProps) {
+  return (
+    <div style={{ background: "#ecfdf5" }}>
+      [{toolName} 结果] {content}
+    </div>
+  );
+}
+
+function MyErrorPart({ content, onRetry }: ErrorPartProps) {
+  return (
+    <div style={{ color: "red" }}>
+      {content}
+      {onRetry && <button onClick={onRetry}>重试</button>}
+    </div>
+  );
+}
+```
+
+### 8.4 事件钩子（EventHooks）
+
+通过 `hooks` 监听组件生命周期与交互事件：
+
+```ts
+export interface EventHooks {
+  onOpen?: () => void;
+  onClose?: () => void;
+  onMessageSend?: (message: string) => void;
+  onStreamStart?: (sessionId: string) => void;
+  onStreamEnd?: (sessionId: string) => void;
+  onError?: (error: Error) => void;
+  onConversationChange?: (sessionId: string) => void;
+}
+```
+
+```ts
+mount("#chat-root", {
+  sdk,
+  hooks: {
+    onOpen: () => console.log("面板已打开"),
+    onClose: () => console.log("面板已关闭"),
+    onMessageSend: (message) => console.log("用户发送：", message),
+    onStreamStart: (sessionId) =>
+      console.log("开始流式输出，会话：", sessionId),
+    onStreamEnd: (sessionId) => console.log("输出结束，会话：", sessionId),
+    onError: (error) => console.error("发生错误：", error.message),
+    onConversationChange: (sessionId) => console.log("切换会话：", sessionId),
+  },
+});
+```
+
+> 点赞 / 踩的反馈回调不在 `hooks` 中，而是在 `sdk.onFeedback`（见 [5.9](#59-feedback--onfeedback)）。
+
+### 8.5 定制示例
+
+完整的自定义 `Header` + `Message` + `ActionBar` + `WelcomeScreen`：
+
+```tsx
+import React, { useState } from "react";
+import { createSuperAgent } from "@super-agent/sdk";
+import { mount, Icon } from "@super-agent/sdk/widget";
+import type {
+  HeaderProps,
+  MessageProps,
+  ActionBarProps,
+  WelcomeScreenProps,
+} from "@super-agent/sdk/widget";
+
+const sdk = createSuperAgent({ baseUrl: "/api/v1", botId: 1 });
+sdk.setToken("demo_app", "demo_token");
+
+function CustomHeader({ title, onClose, onToggleThreadList }: HeaderProps) {
+  return (
+    <div
+      style={{
+        display: "flex",
+        alignItems: "center",
+        padding: "12px 16px",
+        background: "#0f172a",
+        color: "#fff",
+      }}
+    >
+      <Icon name="bot" size={18} color="#fff" />
+      <span style={{ flex: 1, marginLeft: 10, fontWeight: 700 }}>{title}</span>
+      <button onClick={onToggleThreadList}>
+        <Icon name="menu" size={16} />
+      </button>
+      <button onClick={onClose}>
+        <Icon name="x" size={16} />
+      </button>
+    </div>
+  );
+}
+
+function CustomMessage({
+  message,
+  isStreaming,
+  isLast,
+  avatar,
+  slots,
+  onCopy,
+  onRegenerate,
+  onFeedback,
+}: MessageProps) {
+  const isUser = message.role === "user";
+  return (
+    <div
+      style={{
+        display: "flex",
+        gap: 12,
+        justifyContent: isUser ? "flex-end" : "flex-start",
+        padding: "4px 0",
+      }}
+    >
+      {!isUser && (
+        <div
+          style={{
+            width: 36,
+            height: 36,
+            borderRadius: 12,
+            background: "#6366f1",
+          }}
+        >
+          {avatar?.assistant || "A"}
+        </div>
+      )}
+      <div style={{ maxWidth: "75%" }}>
+        {message.parts.map((part, idx) => {
+          switch (part.type) {
+            case "text":
+              return (
+                <div key={idx} style={{ whiteSpace: "pre-wrap" }}>
+                  {part.content}
+                </div>
+              );
+            case "thinking":
+              return (
+                <div
+                  key={idx}
+                  style={{ fontStyle: "italic", color: "#7c3aed" }}
+                >
+                  {part.content}
+                </div>
+              );
+            case "tool_call":
+              return <div key={idx}>[调用 {part.toolName}]</div>;
+            case "tool_result":
+              return <div key={idx}>[结果] {part.content}</div>;
+            case "error":
+              return (
+                <div key={idx} style={{ color: "#b91c1c" }}>
+                  {part.content}
+                </div>
+              );
+          }
+        })}
+        {isStreaming && isLast && !isUser && <span>|</span>}
+        {!isUser && !isStreaming && message.parts.length > 0 && (
+          <slots.ActionBar
+            message={message}
+            onCopy={onCopy}
+            onRegenerate={onRegenerate}
+            onFeedback={onFeedback}
+          />
+        )}
+      </div>
+      {isUser && (
+        <div
+          style={{
+            width: 36,
+            height: 36,
+            borderRadius: 12,
+            background: "#475569",
+          }}
+        >
+          {avatar?.user || "U"}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function CustomActionBar({
+  message,
+  onCopy,
+  onRegenerate,
+  onFeedback,
+}: ActionBarProps) {
+  const [liked, setLiked] = useState<"like" | "dislike" | null>(null);
+  return (
+    <div style={{ display: "flex", gap: 8, marginTop: 6 }}>
+      <button onClick={onCopy}>复制</button>
+      <button onClick={onRegenerate}>重新生成</button>
+      <button
+        onClick={() => {
+          const v = liked === "like" ? null : "like";
+          setLiked(v);
+          if (v) onFeedback?.(message.id, v);
+        }}
+        style={{ color: liked === "like" ? "#6366f1" : "#9ca3af" }}
+      >
+        👍
+      </button>
+      <button
+        onClick={() => {
+          const v = liked === "dislike" ? null : "dislike";
+          setLiked(v);
+          if (v) onFeedback?.(message.id, v);
+        }}
+        style={{ color: liked === "dislike" ? "#6366f1" : "#9ca3af" }}
+      >
+        👎
+      </button>
+    </div>
+  );
+}
+
+function CustomWelcomeScreen({
+  message,
+  suggestedPrompts,
+  onPromptClick,
+}: WelcomeScreenProps) {
+  return (
+    <div
+      style={{
+        flex: 1,
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "center",
+      }}
+    >
+      <Icon name="sparkles" size={32} color="#6366f1" />
+      <p>{message || "有什么可以帮你的？"}</p>
+      {suggestedPrompts?.map((prompt) => (
+        <button key={prompt} onClick={() => onPromptClick(prompt)}>
+          {prompt}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+mount("#chat-root", {
+  sdk,
+  mode: "fullpage",
+  title: "AI 助手",
+  welcomeMessage: "你好！我是 AI 助手",
+  suggestedPrompts: ["查询订单", "写一段代码"],
+  slots: {
+    Header: CustomHeader,
+    Message: CustomMessage,
+    ActionBar: CustomActionBar,
+    WelcomeScreen: CustomWelcomeScreen,
+  },
+}).open();
+```
+
+---
+
+## 9. 会话管理
+
+### 9.1 SDK 层面
+
+| 方法                 | 签名                                            | 说明                                 |
+| -------------------- | ----------------------------------------------- | ------------------------------------ |
+| `createSession`      | `() => Promise<string>`                         | 创建新会话，返回 `sessionId`         |
+| `listConversations`  | `(params?) => Promise<ListConversationsResult>` | 获取会话列表（分页）                 |
+| `renameConversation` | `(sessionId, title) => Promise<void>`           | 重命名会话                           |
+| `deleteConversation` | `(sessionId) => Promise<void>`                  | 删除会话                             |
+| `getMessages`        | `(sessionId) => Promise<UIMessage[]>`           | 获取会话历史消息（已转换为 UI 结构） |
+
+```ts
+const sessionId = await sdk.createSession();
+const { items, total } = await sdk.listConversations({ page: 1, size: 20 });
+const messages = await sdk.getMessages(items[0].sessionId);
+await sdk.renameConversation(items[0].sessionId, "新标题");
+await sdk.deleteConversation(items[0].sessionId);
+```
+
+### 9.2 组件内置能力
+
+- **自动加载**：挂载后自动调用 `listConversations` 拉取会话列表。
+- **切换**：点击会话项加载该会话历史消息并展示。
+- **新建**：点击「新会话」清空当前消息，下次发送时自动调用 `createSession()` 创建新会话。
+- **重命名**：`fullpage` 侧边栏或自定义 `ThreadList` 中调用 `renameConversation`。
+- **删除**：悬停会话项后点击删除按钮。
+- **本地持久化**：最近一次活跃会话写入 `localStorage`，键为 `sa_active_conversation`。
+
+---
+
+## 10. 中断恢复
+
+### 10.1 中断请求
+
+`chat()` 返回 `AbortController`，可随时中断：
+
+```ts
+const controller = sdk.chat({
+  sessionId,
+  message: "...",
+  stream: true,
+  onDone,
+});
+controller.abort();
+```
+
+也可在 `ChatOptions.signal` 传入外部 `AbortSignal`，SDK 会将其与内部信号合并，任一触发即中断：
+
+```ts
+const ac = new AbortController();
+sdk.chat({ sessionId, message: "...", signal: ac.signal });
+ac.abort();
+```
+
+### 10.2 会话恢复
+
+页面刷新或组件重新挂载时，会话状态自动恢复：
+
+1. 挂载时从 `localStorage` 读取上次活跃会话 ID（键 `sa_active_conversation`）。
+2. 若该会话仍在列表中，自动调用 `getMessages` 拉取历史消息并渲染。
+3. 若存储的会话已不存在（被删除），则自动清空并回退到「新会话」。
+
+整个过程对用户透明，无需额外配置。
+
+---
+
+## 11. 消息类型
+
+### 11.1 UIMessage
+
+```ts
+export interface UIMessage {
+  id: string;
+  role: "user" | "assistant";
+  parts: MessagePart[];
+  timestamp: number;
+}
+```
+
+### 11.2 MessagePart
+
+```ts
+export type MessagePart =
+  | { type: "text"; content: string }
+  | { type: "thinking"; content: string }
+  | { type: "tool_call"; toolName: string; toolCallId: string; args: string }
+  | {
+      type: "tool_result";
+      toolName: string;
+      toolCallId: string;
+      content: 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`                           | 错误信息                        |
+
+### 11.3 ChatEvent（流式事件）
+
+```ts
+export interface ChatEvent {
+  type:
+    | "user"
+    | "thinking"
+    | "ai"
+    | "tool_call"
+    | "tool_result"
+    | "done"
+    | "error";
+  content: string;
+  toolName?: string;
+  toolCallId?: string;
+  args?: string; // JSON.stringify 后的字符串
+  sessionId?: string;
+}
+```
+
+---
+
+## 12. 高级用法
+
+### 12.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 sessionId = await sdk.createSession();
+
+let full = "";
+sdk.chat({
+  sessionId,
+  message: "你好",
+  onMessage: (e) => {
+    if (e.type === "ai") full += e.content;
+  },
+  onDone: ({ sessionId, content }) => console.log(sessionId, content),
+  onError: (err) => console.error(err),
+});
+```
+
+### 12.2 使用 Hooks
+
+从 `@super-agent/sdk/widget` 导出 `useChat`、`useConversations`，可在自己的 React 应用中复用：
+
+```ts
+export function useChat(options: UseChatOptions): UseChatReturn;
+
+interface UseChatOptions {
+  sdk: SuperAgentSDK;
+  sessionId: string | null;
+  onSessionCreated?: (sessionId: string) => void;
+  onStreamStart?: (sessionId: string) => void;
+  onStreamEnd?: (sessionId: string) => void;
+  onError?: (error: Error) => void;
+  onMessageSend?: (message: string) => void;
+}
+
+interface UseChatReturn {
+  messages: UIMessage[];
+  status: ChatStatus;
+  error: Error | null;
+  sendMessage: (content: string) => void;
+  stop: () => void;
+  regenerate: () => void;
+  setMessages: (messages: UIMessage[]) => void;
+}
+```
+
+```ts
+export function useConversations(
+  options: UseConversationsOptions,
+): UseConversationsReturn;
+
+interface UseConversationsOptions {
+  sdk: SuperAgentSDK;
+  onConversationChange?: (sessionId: string) => void;
+}
+
+interface UseConversationsReturn {
+  conversations: Conversation[];
+  activeConversationId: string | null;
+  loading: boolean;
+  loadConversations: () => Promise<void>;
+  switchConversation: (sessionId: string) => Promise<UIMessage[]>;
+  newConversation: () => void;
+  deleteConversation: (sessionId: string) => Promise<void>;
+  renameConversation: (sessionId: string, title: string) => Promise<void>;
+  setActiveConversationId: (id: string | null) => void;
+}
+```
+
+```tsx
+function MyChat({ sdk }: { sdk: SuperAgentSDK }) {
+  const conv = useConversations({ sdk });
+  const chat = useChat({ sdk, sessionId: conv.activeConversationId });
+
+  return (
+    <div>
+      {chat.messages.map((m) => (
+        <div key={m.id}>
+          {m.role}:{" "}
+          {m.parts.map((p) => (p.type === "text" ? p.content : "")).join("")}
+        </div>
+      ))}
+      <button onClick={() => chat.sendMessage("你好")}>发送</button>
+    </div>
+  );
+}
+```
+
+> `useChat` 在 `sessionId` 为空时会自动调用 `sdk.createSession()` 创建新会话，无需手动处理。
+
+### 12.3 Token 续期
+
+请求返回 `401` 时，SDK 会自动重新调用 `POST /token` 获取新凭证并重试（并发请求合并为一次刷新），无需手动处理。
+
+### 12.4 取消请求
+
+`chat()` 返回 `AbortController`；或传入外部 `AbortSignal`（SDK 会合并内部信号，任一触发即中断）：
+
+```ts
+const controller = sdk.chat({
+  sessionId,
+  message: "...",
+  stream: true,
+  onDone,
+});
+// 稍后取消
+controller.abort();
+```
+
+```ts
+const ac = new AbortController();
+sdk.chat({ sessionId, message: "...", signal: ac.signal });
+ac.abort();
+```