@blade-hq/agent-react 2610.0.0-beta.7 → 2610.0.0-beta.71

package/README.md

@@ -6,6 +6,10 @@ Blade Agent 的 React 绑定：`BladeProvider` + `useAgentSession` + 开箱即
 pnpm add @blade-hq/agent-client @blade-hq/agent-react
 ```
 
+默认装到的是当前长期支持版（LTS），厂内离线交付按它开发。要跟两周一发的公网版本，改用 `@next`。
+
+最稳妥的做法是先读目标 Server 的 `GET /api/version`，按返回的版本号在 `package.json` 里钉死——NPM 的 `latest` 不一定和目标环境跑的版本一致。
+
 > 注意两个包都要装：`agent-client` 是运行时依赖，只装 `agent-react` 在 pnpm 下会直接报错。
 
 ## 快速开始
@@ -28,7 +32,6 @@ export function App() {
 
 - 不传 `sessionId` 自动创建新会话；未登录时 `ChatView` 自己渲染登录按钮（弹窗授权，见 agent-client 的 `client.auth.login()`）。
 - 同一 `BladeProvider` 下可以放多个 `ChatView`，各自独立会话、互不干扰。
-- 宿主只需要完成态消息时，可在 `BladeClient` 构造参数中传 `streamTokens: false`，不订阅逐 token 增量。
 
 ## BladeProvider
 
@@ -54,6 +57,7 @@ const client = useBladeClient() // 当前 Provider 的 BladeClient
 const { session, state, error } = useAgentSession(sessionId, {
   createOptions,        // 不传 sessionId 时的建会话配置（UseAgentSessionOptions）
   onSessionCreated: (id) => saveSomewhere(id),
+  onSessionConnected: (session) => session.on("toolResult", handleResult),
 })
 
 state?.messages     // ChatMessage[]，直接渲染
@@ -67,8 +71,29 @@ await session?.send("你好")
 
 - 优先级：`sessionId`（连接既有会话）> `createOptions`（按配置新建）> 默认新建。
 - 自动创建只发生一次（含 React StrictMode 双跑）；创建出的 id 通过 `onSessionCreated` 交还，重挂载时把它作为 `sessionId` 传回即可复用会话。
+- 必须覆盖连接窗口内事件时，用 `onSessionConnected` 在历史加载和房间订阅开始前完成订阅，并返回取消订阅函数。
 - 同一 `sessionId` 的多次调用复用同一 `AgentSession` 实例（引用计数）；卸载后延迟释放，路由抖动不会断连。
 
+## SessionMemoryToggle
+
+把当前会话是否使用记忆放进宿主自己的会话设置面板：
+
+```tsx
+const [memoryEnabled, setMemoryEnabled] = useState(session.memory_enabled !== false)
+
+<SessionMemoryToggle
+  sessionId={session.id}
+  enabled={memoryEnabled}
+  onSaved={(_sessionId, enabled) => setMemoryEnabled(enabled)}
+  onError={(error) => toast.error(String(error))}
+/>
+```
+
+组件默认使用 `BladeProvider` 的 client；已有独立 client 装配层的宿主也可以显式传
+`client={client}`。同一 client、同一会话的多个开关共享保存锁，即使切换会话或同时存在多个
+设置入口，也不会并发提交相互覆盖。服务端确认后的权威值通过 `onSaved` 返回。
+全部属性见 `SessionMemoryToggleProps`。
+
 ## useReplay
 
 会话回放（演示 / 彩排）：拿一个已经聊完的会话当素材，重现当时的回复和工具调用，
@@ -133,6 +158,9 @@ await replay.exitToAutonomous()                // 退出回放，之后真的运
 
 完整聊天界面：消息列表（Markdown、代码高亮、工具调用、提问卡片）+ 输入框 + 连接状态条 + 登录引导。
 
+`ChatView` 固定使用普通展示模式。产品内置 Web 的精简/开发者模式不属于 SDK 公共能力，
+因此没有 `renderMode` 等切换属性。
+
 ```tsx
 <ChatView
   sessionId={id}                       // 可选；不传自动建会话
@@ -150,11 +178,24 @@ await replay.exitToAutonomous()                // 退出回放，之后真的运
 
 全部 props 见 `ChatViewProps`。样式说明：
 
-`onFollowupInteraction` 使用 `FollowupInteractionEvent`，覆盖下一步建议展示/采纳、成果展示/打开/下载以及结果评分。SDK 不内置 PostHog 等分析厂商；宿主回调抛错也不会中断用户点击或下载。
+智能体调用 `update_plan` 新增或更新任务时，`ChatView` 会在输入框上方自动展开最新任务进度，
+5 秒后平滑收起；连续更新会重新计时，用户手动展开或收起后以用户选择为准。自建聊天布局可直接
+使用 `CurrentPlanPanel` / `PlanUpdateBlock`，或用 `getPlanUpdateDisplayState`、
+`parsePlanUpdate` 和 `pickCurrentPlanStep` 复用同一套判定。
+
+`ChatView` 的普通展示模式不显示只供诊断的项目说明、可用能力和当前工作环境。需要自建诊断界面时，可直接使用独立的 `ContextCard`，属性见 `ContextCardProps`；状态到文案的映射来自 agent-client 的 `getContextDisplayState`，不需要接入方重复判断。一次输入通常会同时注入十几项上下文，把渲染序列里连续的几项用 `ContextGroupCard`（属性见 `ContextGroupCardProps`）折成一行更合适；哪几项算一组由 agent-client 的 `groupAdjacentContextRuns` 判定，折叠行文案来自 `getContextGroupDisplayState` / `ContextGroupDisplayState`。底层数据类型为 `ContextProjectionData` / `ContextProjectionFields`，展示结果为 `ContextDisplayState`，并保留 `ContextAction`、`ContextSourceInfo` 和 `contextProjectionData` 给 headless 消费方。
+
+记忆引用提示可通过 `MemoryRefsHint` 展示，`collectMemoryRefs` 用于从一轮消息中聚合引用，保证宿主自定义消息布局与 SDK 默认界面保持一致。
+
+MCP App 卡片（`tool_ui` block）在默认消息流里自动渲染，无需配置；自建消息布局时可用 `ToolUiCardView` 渲染单个卡片，并传入 `sessionId` 启用共享 AppBridge。卡片的实例、内容解析与终态（archived 留档不重放）判定来自 agent-client 的共享层（`collectInlineToolUiCards` / `resolveToolUiCardContent` 等）。preview 卡片不进消息流，由 `toolPreview` 事件推给宿主自建面板。
+
+`onFollowupInteraction` 使用 `FollowupInteractionEvent`，覆盖下一步建议展示/采纳、成果展示/打开/下载以及结果评分。SDK 不内置分析服务；宿主回调抛错也不会中断用户点击或下载。
+文件成果以文件名为文本的标准下载链接展示；Vue / 纯 HTML 使用的 `<blade-chat>` 与 `ChatView` 行为一致。
 
 - 必须引入一份样式，按宿主有没有 Tailwind 二选一：
-  - **`style.full.css`**（默认选它）：布局兜底 + 编译好的 Tailwind 产物，自包含，宿主没装 Tailwind 也是完整视觉。
-  - **`style.css`**：只有 `.blade-chat-*` 布局兜底。宿主自己装了 Tailwind、且 `content` 配了扫描 `node_modules/@blade-hq/agent-react` 时用它，可以少一份重复 CSS。选错不会报错，只是工具块、思考块内部会退化成没有布局的裸 HTML。
+  - **`style.full.css`**（默认选它）：CSS 变量、容器查询、Markdown 排版等兜底 + 编译好的 Tailwind 产物，自包含，宿主没装 Tailwind 也是完整视觉。
+  - **`style.css`**：只有兜底那部分（Tailwind 类表达不了的规则）。宿主自己装了 Tailwind、且 `content` 配了扫描 `node_modules/@blade-hq/agent-react` 时用它，可以少一份重复 CSS。选错不会报错，只是布局、配色、工具块和思考块会退化成裸 HTML——组件的视觉本来就只定义一次，都在它的 Tailwind 类上。
+  - 两份都用同一套层序 `@layer properties, theme, base, components, utilities, blade-chat-overrides;`（在 `src/scoped-preflight.css` 里声明一次；`properties` 是 Tailwind 的 `--tw-*` 初始值层，必须排在最前）。兜底规则在 `components` 层；Tailwind 工具类在 `utilities` 层；SDK 里那几条**必须压过自己工具类**的规则（窄容器里放宽用户消息、移动端聚焦不缩放、Markdown 与代码块排版）在最后一层 `blade-chat-overrides`（名字带 SDK 前缀，避免宿主已有的同名层把全局层序定到别处）——放进 `components` 会被同元素的工具类盖掉，等于没写。**宿主写的普通 CSS 不分层，按层序赢过这里所有层，与加载顺序无关，也不需要 `!important`**：这是「接入方覆盖必胜」的实现方式，改 `src/style.css` 时不要把规则挪出这两层。
   - 两份都不含 Tailwind preflight 这类全局 reset，引入后不会影响宿主页面自己的排版；组件需要的那点重置限定在 `.blade-chat` 子树内（见 `src/scoped-preflight.css`）。Shadow DOM 版（`<blade-chat>`）不受此限，它注入的是带 preflight 的完整产物。
 - 颜色走 CSS 变量，可整体换肤；深色页面要在根元素上写 `data-theme="dark"`，否则拿到的是默认的浅色变量。
 - `renderers.toolCall` 返回 `null` 时回落到默认工具卡片。
@@ -170,6 +211,9 @@ Blade。这时把 `ChatView` 切到 `mode="llm"`，或者直接用下层的 `Llm
 <ChatView mode="llm" llm={{ baseURL: "/api/llm", model }} />   // 切成纯 LLM
 <LlmChat baseURL="/api/llm" model={model} />                   // 或者直接用（LlmChatProps）
 <AgentChat sessionId={id} />                                   // 智能体那侧同样可以直接用（AgentChatProps）
+
+`AgentChat` 还支持 `sessionPluginControls(sessionId)` 插槽，宿主可复用
+`@blade-hq/agent-client` 的会话插件状态与激活控制。
 ```
 
 **协议就是 OpenAI 的**：`POST {baseURL}/chat/completions`，`stream: true`，读
@@ -261,6 +305,43 @@ models.filter((m) => m.serviceModelId)
 <MarkdownContent sessionId={sessionId}>{markdownText}</MarkdownContent>
 ```
 
+`normalizeAdjacentUrlFormatting` 可在复用其他 Markdown 渲染器前，保护紧贴行内格式标记的 URL。
+
+## Canonical 引用消息
+
+`ChatView` 会自动识别 ship-attack 会话中的 `[引用]` / `[用户输入]` canonical
+消息，并按原顺序展示引用来源、快照和用户输入。自建消息列表时可用
+`parseWhatIfPrompt` 解析同一格式，再交给 `WhatIfUserBubble` 渲染；
+`onQuoteClick` 可接入宿主的步骤跳转。
+
+```tsx
+const parsed = parseWhatIfPrompt(messageText)
+return parsed ? (
+  <WhatIfUserBubble parsed={parsed} onQuoteClick={jumpToStep} />
+) : null
+```
+
+## isAgentComputerCommand / isAgentComputerToolCall / classifyAgentComputerLaunchOutcome
+
+判断智能体是否在沙盒里启动了通用 GUI 应用镜像（`computer launch`）——后端 blade-agent 通过 `computer` CLI 驱动一块虚拟屏幕运行任意 GUI 软件，这些函数用于自行接入方判断要不要展示对应的实时画面入口（比如自建一个类似「电脑镜像」的标签页）。当前 SDK 侧还没有内置这块 UI，只导出判定规则，避免各接入方重新猜一遍匹配逻辑。
+
+`isAgentComputerCommand`/`isAgentComputerToolCall` 只回答"这条命令是不是一次 launch 尝试"，不回答"这次 launch 最终成不成功"——待处理、已失败的 launch 也会命中。要判断真实结果（比如决定要不要展示画面入口），用 `classifyAgentComputerLaunchOutcome`：它会解析工具调用的 `status`/`result`，返回 `"pending" | "succeeded" | "failed" | "unknown"`。`"unknown"` 表示 `status` 已经是终态但 `result` 字段本身缺失（常见于会话整理/compaction 之后的历史投影，归档时不会重新序列化完整 result），跟"result 回来了、里面确实没有成功标记"的 `"failed"` 是两种不同性质的证据——接入方要按自己的场景决定怎么处理（展示类场景可以偏宽松，当作足够展示；自动跳转/替用户做决定的场景应该偏保守，当作跟 `"failed"` 一样处理）。
+
+```ts
+import {
+  isAgentComputerCommand,
+  isAgentComputerToolCall,
+  classifyAgentComputerLaunchOutcome,
+} from "@blade-hq/agent-react"
+
+isAgentComputerCommand("computer launch --exec /opt/apps/foo/bar") // true
+isAgentComputerCommand("computer status") // false（只认 launch，不认查询类子命令）
+
+isAgentComputerToolCall(toolCall.arguments) // 工具调用的 JSON 参数版本
+
+classifyAgentComputerLaunchOutcome(toolCall) // "pending" | "succeeded" | "failed" | "unknown"
+```
+
 ## 选择模型
 
 SDK 的 ChatView / `<blade-chat>` 不内置模型选择器（默认用后端配置的模型）。指定模型有两种方式：
@@ -277,15 +358,28 @@ SDK 的 ChatView / `<blade-chat>` 不内置模型选择器（默认用后端配
 
 1. **深浅主题**：`<ChatView theme="dark" />` / `<blade-chat theme="dark">` 切内置深色，不传或 `"light"` 为浅色。宿主已经在祖先元素上写了 `data-theme="dark"` 时不用传，`ChatView` 会跟着变。`<blade-chat>` 渲染在 Shadow DOM 内，页面上的 `data-theme` 对它无效，只认 `theme` 属性。
 
-2. **CSS 变量换肤**（React 与 `<blade-chat>` 通用）：所有颜色走 `--primary`、`--background`、`--muted` 等变量（完整清单见 style.css 开头）。页面直接覆盖即可穿透 Shadow DOM：
+2. **CSS 变量换肤**（React 与 `<blade-chat>` 通用）：所有颜色走 `--primary`、`--background`、`--muted` 等变量（完整清单见下面的「CSS 变量清单」，默认值在 style.css 开头）。页面直接覆盖即可穿透 Shadow DOM：
 
 ```css
 blade-chat { --primary: 262 83% 58%; height: 640px; }
 ```
 
-3. **classNames props**（React）：`ChatView` 的 `classNames` 把自定义 class（含你自己构建的 Tailwind 工具类）挂到根节点、消息区、输入区等关键节点上，见 `ChatViewClassNames`。
+3. **classNames props**（React）：`ChatView` 的 `classNames` 把自定义 class（含你自己构建的 Tailwind 工具类）挂到各个区块上，见 `ChatViewClassNames`。SDK 内部用 `cn`（clsx + tailwind-merge）拼接，你传的类在最后一个参数，所以 `classNames={{ chatInput: "p-0" }}` 会直接盖掉组件内部的 `py-3`，与 CSS 加载顺序无关：
+
+```tsx
+<ChatView
+  sessionId={id}
+  classNames={{
+    root: "h-[640px] rounded-2xl border",
+    userBubble: "bg-sky-100 text-sky-900",
+    assistantText: "text-[15px] leading-7",
+    chatInput: "px-2",
+    inputInner: "bg-white shadow-sm",
+  }}
+/>
+```
 
-4. **内嵌 `<style>`（纯 HTML / Vue）**：`<blade-chat>` 的直接 `<style>` 子元素会被注入 Shadow DOM、排在内置样式之后，可用 `.blade-chat-*` 类名做任意深度定制：
+4. **内嵌 `<style>` 与 `::part`（纯 HTML / Vue）**：`<blade-chat>` 的直接 `<style>` 子元素会被注入 Shadow DOM、排在内置样式之后，可用 `.blade-chat-*` 类名做任意深度定制；每个主要区块同时带一个与锚点同名的 `part`（`blade-chat-user-bubble` → `part="user-bubble"`），页面外层用 `::part()` 也能选到它：
 
 ```html
 <blade-chat base-url="...">
@@ -296,12 +390,218 @@ blade-chat { --primary: 262 83% 58%; height: 640px; }
 </blade-chat>
 ```
 
+```css
+blade-chat::part(user-bubble) { background: #eef2ff; }
+blade-chat::part(input-toolbar) { gap: 12px; }
+```
+
+### classNames 覆盖哪些区块
+
+区块与锚点一一对应（键名 = 锚点名去掉 `blade-chat-` 前缀）：
+
+| `classNames` 键 | 锚点 | 落点 |
+| --- | --- | --- |
+| `root` | `.blade-chat` | 聊天根容器 |
+| `banner` | `.blade-chat-banner` | 连接状态条 |
+| `errorBar` | `.blade-chat-error-bar` | 顶部出错条 |
+| `messageList` | `.blade-chat-messages` | 消息区 |
+| `messagesScroll` | `.blade-chat-messages-scroll` | 消息区滚动内容（内边距） |
+| `messagesContent` | `.blade-chat-messages-content` | 消息内容列（居中、最大宽度） |
+| `empty` | `.blade-chat-empty` | 空状态 |
+| `scrollToBottom` | `.blade-chat-scroll-bottom` | 「滚动到底部」按钮 |
+| `userMessage` | `.blade-chat-user-row` | 用户消息行 |
+| `userBubble` | `.blade-chat-user-bubble` | 用户气泡 |
+| `fileCard` | `.blade-chat-file-card` | 消息里的文件附件 |
+| `errorMessage` | `.blade-chat-error-row` | 消息流里的出错块 |
+| `assistantTurn` | `.blade-chat-assistant-turn` | 一轮助手回复 |
+| `thinking` | `.blade-chat-thinking` | 思考过程 |
+| `assistantText` | `.blade-chat-assistant-text` | 助手正文 |
+| `memoryRefs` | `.blade-chat-memory-refs` | 记忆引用 |
+| `toolRow` | `.blade-chat-tool-row` | 执行过程里的工具行（智能体模式下工具调用都走这条路径） |
+| `agentLoop` | `.blade-chat-agent-loop` | 子智能体行 |
+| `askCard` | `.blade-chat-ask-card` | 提问卡 |
+| `askOption` | `.blade-chat-ask-option` | 提问卡的每个选项 |
+| `planPanel` | `.blade-chat-plan` | 输入框上方的计划面板 |
+| `queuePanel` | `.blade-chat-queue` | 会话队列面板 |
+| `followup` | `.blade-chat-followup` | 本轮小结与跟进区 |
+| `followupAction` | `.blade-chat-followup-action` | 跟进建议按钮 |
+| `chatInput` | `.blade-chat-input` | 输入区外层 |
+| `inputInner` | `.blade-chat-input-inner` | 输入框卡片（边框、圆角、底色） |
+| `textarea` | `.blade-chat-textarea` | 输入框 |
+| `inputToolbar` | `.blade-chat-input-toolbar` | 输入框右侧按钮组 |
+
+同一批锚点也是普通 CSS 的抓手：锚点只负责「可被选中」，视觉规则不在它身上，所以对你的锚点写 `.blade-chat-user-bubble { ... }` 不会被 SDK 的样式盖掉（SDK 的规则都在 `@layer components` / `@layer blade-chat-overrides`，Tailwind 工具类在 `@layer utilities`，你的样式不分层，按 CSS 层序本来就赢）。
+
+### 锚点清单
+
+每个可见区块的根元素都固定带一个 `blade-chat-*` 类，构成公开契约（`src/style.css` 顶部的登记块是唯一来源，构建会校验它和组件源码、三份 CSS 产物一致）：
+
+| 区块 | 锚点 |
+| --- | --- |
+| 聊天根容器 | `.blade-chat` |
+| 登录引导 / 连接状态条 / 出错条 / 回放条 | `.blade-chat-login`、`.blade-chat-banner`、`.blade-chat-error-bar`、`.blade-chat-replay-bar` |
+| 消息区 | `.blade-chat-messages`、`.blade-chat-messages-scroll`、`.blade-chat-messages-content`、`.blade-chat-empty`、`.blade-chat-scroll-bottom`、`.blade-chat-scroll-bottom-label` |
+| 用户消息 | `.blade-chat-user-row`、`.blade-chat-user-col`、`.blade-chat-user-bubble`、`.blade-chat-file-card`（+ `-icon` / `-name`） |
+| 助手回复 | `.blade-chat-assistant-turn`、`.blade-chat-assistant-text`、`.blade-chat-thinking`、`.blade-chat-memory-refs`、`.blade-chat-render-error` |
+| 工具调用 | `.blade-chat-tool-row`（执行过程里的工具行）、`.blade-chat-agent-loop`（子智能体行） |
+| 提问卡 | `.blade-chat-ask-card`、`.blade-chat-ask-option` |
+| 计划与队列 | `.blade-chat-plan`、`.blade-chat-plan-block`、`.blade-chat-queue`、`.blade-chat-queue-item`、`.blade-chat-queue-notice` |
+| 跟进区 | `.blade-chat-followup`、`.blade-chat-followup-action` |
+| 输入区 | `.blade-chat-input`、`.blade-chat-input-inner`、`.blade-chat-textarea`、`.blade-chat-input-toolbar` |
+| 上下文卡片 | `.blade-chat-context-card`、`.blade-chat-context-summary`、`.blade-chat-context-icon`、`.blade-chat-context-copy`、`.blade-chat-context-title`、`.blade-chat-context-status`、`.blade-chat-context-chevron`、`.blade-chat-context-detail`、`.blade-chat-context-group-items` |
+| Markdown 与代码块 | `.blade-chat-markdown`、`.blade-chat-prose`、`.blade-chat-codeblock`、`.blade-chat-codeblock-header`、`.blade-chat-codeblock-body` |
+| 其他 | `.blade-chat-host`（`<blade-chat>` 内的挂载点）、`.blade-chat-advanced`、`.blade-chat-mcp-app`、`.blade-chat-error-row`、`.blade-chat-error-block` |
+
+### part 清单（`<blade-chat>` 的 Shadow DOM 专用）
+
+Shadow DOM 把上面的类名挡在页面之外，所以**主要区块**额外带一个与锚点同名的 `part`（去掉 `blade-chat-` 前缀；根容器的锚点是 `blade-chat`，约定用 `root`），页面外层用 `::part()` 选：
+
+```css
+blade-chat::part(user-bubble) { background: #eef2ff; }
+blade-chat::part(input-toolbar) { gap: 12px; }
+```
+
+清单（`src` 里每一处 `part` 都由构建校验，必须能对回锚点清单）：
+
+| 分组 | part |
+| --- | --- |
+| 容器与状态 | `root`、`banner`、`error-bar`、`replay-bar`、`mcp-app` |
+| 消息区 | `messages`、`messages-scroll`、`messages-content`、`empty`、`scroll-bottom` |
+| 用户消息 | `user-row`、`user-bubble`、`file-card`、`error-row` |
+| 助手回复 | `assistant-turn`、`assistant-text`、`thinking`、`memory-refs` |
+| 工具与提问 | `tool-row`、`agent-loop`、`ask-card`、`ask-option` |
+| 计划与队列 | `plan`、`plan-block`、`queue` |
+| 跟进区 | `followup`、`followup-action` |
+| 输入区 | `input`、`input-inner`、`textarea`、`input-toolbar` |
+
+外围区块（`.blade-chat-context-*`、`.blade-chat-codeblock-*` 等）只有类名锚点，React 下可以直接选；`<blade-chat>` 下要改它们得用第 4 层的内嵌 `<style>`（那段样式就注入在 Shadow DOM 里）。
+
+### CSS 变量清单
+
+颜色是 `hsl()` 的三个分量（形如 `223 100% 54%`），几何是长度值。宿主盖掉这些变量即可整体换肤（React 下写在 `.blade-chat` 或祖先元素上；`<blade-chat>` 下写在元素上，变量能穿透 Shadow DOM）：
+
+| 分组 | 变量 |
+| --- | --- |
+| 基础色 | `--background`、`--foreground`、`--card`、`--card-foreground`、`--popover`、`--popover-foreground` |
+| 语义色 | `--primary`、`--primary-foreground`、`--muted`、`--muted-foreground`、`--accent`、`--accent-foreground`、`--destructive`、`--border`、`--ring` |
+| 用户消息专用 | `--user-msg-bg`、`--user-msg-fg`、`--user-msg-border` |
+| 布局（SDK 按容器宽度推导） | `--blade-chat-gutter`（消息区与输入区的左右留白）、`--blade-chat-turn-gap`（轮次间距）。两个变量声明在 `.blade-chat` 上，**设在祖先元素上不生效**（元素上的声明永远赢过继承值）。React 下直接对 `.blade-chat` 写规则，或用 `classNames.root` 传一个设该变量的工具类（如 `"[--blade-chat-gutter:2rem]"`）；`<blade-chat>` 下用第 4 层的内嵌 `<style>` |
+| 布局（接入方按需覆盖） | `--blade-chat-queue-gutter`（队列面板左右留白，默认跟随 gutter）、`--blade-chat-pin-spacer`（消息顶置的底部补白，组件自己写）、`--blade-chat-input-top-border`（输入区上边框，组件自己写） |
+
+深色主题的变量挂在 `[data-theme="dark"]` 上，由 `theme` prop / 属性落到聊天根节点，整棵子树继承。
+
+上面这些是**会改变 SDK 组件外观**的变量。另外随主题一起声明的还有 `--radius`、`--input`、`--destructive-foreground`：`agent-react` 的默认组件不消费它们（圆角走 Tailwind 自己的 `--radius-*`），宿主在聊天容器里自绘 UI 时可以直接用，改动它们不会影响 SDK 自带的界面。
+
+### 区块级渲染器（renderers）
+
+`classNames` 换不掉整个区块时用 `renderers`：每个渲染器拿到一个描述该区块的对象，返回 `ReactNode`；返回 `null` 走 SDK 默认渲染。
+
+```tsx
+<ChatView
+  sessionId={id}
+  renderers={{
+    toolCall: (toolCall) => <MyToolCard toolCall={toolCall} />,
+    userMessage: ({ message }) => <MyBubble message={message} />,
+    assistantText: ({ message, streaming, compact }) => (compact ? null : <MyMarkdown text={message.content} />),
+    askUserQuestion: ({ data, answered, onAnswer }) => <MyQuestions data={data} answered={answered} onAnswer={onAnswer} />,
+    planUpdate: ({ plan, running }) => <MyPlanSteps plan={plan} running={running} />,
+  }}
+/>
+```
+
+- `toolCall`：`(toolCall: ToolCallInfo) => ReactNode | null`，见 `ToolCallRenderer`。
+- `userMessage`：`UserMessageRendererProps`——只替换用户消息气泡，消息行（`.blade-chat-user-row`）与图片/文件附件仍由 SDK 渲染；消息顶置依赖那个行容器，替换掉它新消息就不会被顶到视口顶部。
+- `assistantText`：`AssistantTextRendererProps`——只替换助手正文，思考块、工具卡、附件照旧。
+- `askUserQuestion`：`AskUserQuestionRendererProps`——`data` 是 `AskUserQuestionData`，`onAnswer` 与默认卡片同一个回调契约；照常作答才算完成这次提问。**提问工具优先走这个渲染器**，只有没配它时才回落到 `toolCall`（避免 `toolCall` 先拿到提问、而它没有作答回调）。
+- `planUpdate`：`PlanUpdateRendererProps`——`plan` 是最近一次成功 `update_plan` 的解析结果；还没有解析出计划时渲染器不会被调用，回落到默认面板的「正在更新任务进度…」。
+
+## 自定义消息列表滚动
+
+`ChatView`、`AgentChat` 和 `LlmChat` 已经处理好用户发言顶置，不用额外配置。自建消息列表时可用 `useMessagePin` 复用同一套触发、补白、视口 resize 和手动滚动接管逻辑；调用方只需提供滚动容器、目标消息与 spacer 的读写函数。完整参数见 [public-api.md](./public-api.md#usemessagepin-function)。
+
+## 打字机式显示节流
+
+`ChatView`、`AgentChat` 和 `LlmChat` 已经内置这套节流，不用额外配置。服务端到达速率天然不均匀（一次推 5 个字、一次推 20 个字），直接原样渲染会显得忽快忽慢；`useTypewriterReveal(targetText, isLive, resetKey)` 按估算到达速度、留一个很小的固定滞后量匀速播放，返回 `{ displayedText, isRevealing, flushNow }`——自建消息列表时可以直接复用。`isLive` 传 `false`（历史加载 / 回放）时永远整段直接显示；`resetKey`（比如消息的 `entry_id`）变化时播放状态从头开始；`flushNow()` 用于用户点了停止时立即整段显示已到达内容。完整参数见 [public-api.md](./public-api.md#usetypewriterreveal-function)。
+
+## 长会话历史导航（useTurnNavigation / TurnNavRail）
+
+`AgentChat` 已经内置这条轨道，不用额外配置：右侧刻度轨列出**整条会话**的用户发言（目录来自服务端
+`/turn-index`，所以窗口外的旧发言也点得到），点已加载的发言直接滚动并短暂高亮，点窗口外的发言发
+一次定位请求（服务端返回「从它到最新」的窗口）后滚动到目标。
+
+自建聊天界面时用 `useTurnNavigation` 复用同一套时序（滚动 / 加载态 / 高亮）：宿主提供
+`TurnNavigationSource`（目录怎么来、定位怎么发、刷新信号）与 `getLoadedEntryElement` /
+`revealEntry` / `beforeSeek` 三个列表侧回调（合起来就是 `TurnNavigationOptions`），返回
+`TurnNavigationResult`（`items`、`loadingEntryId`、
+`error`、`failedEntryId`、`activeEntryId`、`selectEntry`）。`TurnNavRail` 是配套的刻度轨组件
+（`TurnNavRailProps`），样式与交互可直接用或照抄；定位高亮的类名是 `TURN_NAV_HIGHLIGHT_CLASS`。
+目录刷新信号用 `latestUserSpeechEntryId(turns)` 计算——只认最新一条用户发言，往前翻页补进的更早
+发言不该作废正在进行的定位；没有目录接口的会话（静态历史 / 分享页）用 `turnNavItemsFromMessages`
+把已加载的窗口转成兜底条目。
+
 ## 纯静态 HTML / Vue？
 
 不需要本包——用后端托管的单文件产物 `<script src=".../sdk/blade-agent.js">` + `<blade-chat>` 自定义元素，行为与 `ChatView` 一致；详见 agent-client README 与接入文档。
 
+## 附录：连接器与插件选择
+
+- **连接器面板**：`ConnectorPanel`、`ConnectorPanelProps`、`PluginConnectorList`、`PluginConnectorListProps`、`ConfiguringPlugin`
+- **插件行与触发器**：`PluginConnectorItem`、`PluginConnectorSelection`、`selectionFromItem`、`triggerSummary`、`TriggerSummary`、`TRIGGER_ICON_LIMIT`、`mergeConnectorItems`、`catalogToConnectorItems`、`filterConnectorItems`
+- **触发器上的头像堆叠**：`PluginTriggerStack`、`PluginTriggerStackProps`（前三枚插件头像 + `+N`，宿主自己画触发器时用它，不要另写一份折叠）
+- **启用时序**：`useSessionPluginActivation`、`UseSessionPluginActivationResult`
+
 ## 附录：re-export 自 @blade-hq/agent-client
 
 为方便单包引入，本包 re-export 了 agent-client 的全部公开声明（`BladeClient`、`AgentSession`、`SessionState`、协议类型等），文档一律见 [agent-client 的 README](../agent-client/README.md)。完整签名见 [public-api.md](./public-api.md)。
 
-本包自有声明：`BladeProvider`、`BladeProviderProps`、`useBladeClient`、`useAgentSession`、`UseAgentSessionOptions`、`UseAgentSessionResult`、`useReplay`、`UseReplayResult`、`ReplayMismatch`、`ReplayBar`、`ReplayBarProps`、`ReplayMismatchPrompt`、`ReplayMismatchPromptProps`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`FollowupInteractionEvent`、`ToolCallRenderer`、`MarkdownContent`、`MarkdownContentProps`。
+本包自有声明：`BladeProvider`、`BladeProviderProps`、`useBladeClient`、`useAgentSession`、`UseAgentSessionOptions`、`UseAgentSessionResult`、`useMessagePin`、`UseMessagePinOptions`、`useTypewriterReveal`、`UseTypewriterRevealResult`、`useReplay`、`UseReplayResult`、`ReplayMismatch`、`ReplayBar`、`ReplayBarProps`、`ReplayMismatchPrompt`、`ReplayMismatchPromptProps`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`FollowupInteractionEvent`、`ToolCallRenderer`、`CurrentPlanPanel`、`PlanUpdateBlock`、`PlanUpdateData`、`PlanUpdateDisplayState`、`PlanStepStatus`、`getPlanUpdateDisplayState`、`isPlanUpdateTool`、`parsePlanUpdate`、`pickCurrentPlanStep`、`PLAN_AUTO_COLLAPSE_MS`、`MarkdownContent`、`MarkdownContentProps`、`parseWhatIfPrompt`、`ParsedWhatIfPrompt`、`WhatIfQuote`、`WhatIfUserBubble`、`WhatIfUserBubbleProps`、`SessionQueuePanel`、`SessionQueuePanelProps`、`isQueuePanelVisible`。
+
+## 会话消息队列
+
+智能体会话的等待消息由服务端持久化，`ChatView` / `AgentChat` 已在输入框上方渲染队列区域（空队列不占位，条目数超过三条可折叠）。输入框不再有「直接插入 / 排队执行」开关：会话空闲时提交直接开始处理，运行中提交默认入队；暂停时在面板上显示原因和「继续执行」。面板数据来自 `useAgentSession` 状态里的 `queue`（`SessionQueueSnapshot`），可编辑/删除/立即补充的判定来自 agent-client 的 `canEditQueuedMessage` / `canCancelQueuedMessage` / `canDeliverQueuedMessage`，文案用 `queuedMessageStatusLabel` / `queuePauseReasonLabel`。
+
+自建布局可直接使用 `<SessionQueuePanel>`，属性类型为 `SessionQueuePanelProps`：传 `snapshot`、`canDeliver`、可选的 `pendingItemId`（提交中的条目禁用操作）与 `notice`（冲突/失败说明），以及 `onResume` / `onCancel` / `onEdit` / `onMove` / `onReorder` / `onDeliver` 回调。上移/下移与拖动排序最终都提交当前 pending 条目的完整 id 顺序。冲突时队列由服务端快照刷新，`ChatView` 会把未保存的正文放回输入框，不会静默丢掉用户编辑的内容。
+
+面板比输入框窄一圈、贴在它上方，所以宽度必须跟输入框一致：用可选属性 `contentWidthClassName` 传入输入框内层的宽度类（不传则按本包输入框的 `max-w-[748px]`）。左右内边距同理——默认值对应本包输入框的 `--blade-chat-gutter`；如果你给输入框根节点换了左右 padding（例如改成 `px-10`），必须用 `rootClassName` 在面板根节点重设 `--blade-chat-queue-gutter` 成同一个值，否则面板会跟输入框错开一圈、在两者相接的缝上露出来。
+
+输入框的 `mergesWithPanelAbove` 为 true 时上两角改直角，跟面板拼成一条完整轮廓；否则输入框的上角圆弧会从较窄的面板两侧露出来，形成两个尖角。**这个值要取面板上报的状态，不要在宿主侧用 `isQueuePanelVisible` 复算**：面板有本地编辑态（编辑到一半、那条等待消息被服务端拿走时仍要留在原地保住草稿，见 `detachedEdit`），这时 snapshot 里没有条目、宿主复算会得到 false，输入框就会在面板还显示着的时候把上角恢复成圆角。用 `onVisibleChange` 拿到面板的真实占位状态，再传给输入框或 `ChatSurface` 的 `queuePanelVisible`。本包的 `AgentChat` 已按这条接好，自建布局照做即可。
+
+拼轮廓的前提是两者**真的相邻**。中间夹着别的内容时（本包的 MCP 暂存内容、内置 Web 的 `composerBanner`），面板下两角与输入框上两角都要圆起来——直角是"被对方接住"的表示，露出直角却中间空着一块，看起来像被削掉一角。面板的 `mergesWithInputBelow` 与输入框的 `mergesWithPanelAbove` 要取同一个判据；`ChatSurface` 会用 context 把这一位传给面板，自建布局直接传即可。
+
+`PollingBackoff` 从 agent-client 重导出，供自定义只读轮询计算退避时间；它不发送或重放请求。用法见 [agent-client 轮询说明](../agent-client/README.md#只读轮询退避)。
+
+### 会话插件
+
+默认 `AgentChat` / 智能体模式 `ChatView` 自带会话插件选择器，展开时查询 BH，选择按当前会话保存。准备失败会保留勾选并提供重试。独立嵌入可使用 `<SessionPluginSelector client={client} sessionId={id} />`；`sessionPluginControls` 可覆盖默认控件。组件参数类型为 `SessionPluginSelectorProps`。
+
+列表项用插件声明的业务名称与随包本地图标展示（`sessionPluginLabel(plugin)` 与 `<SessionPluginIcon client={client} sessionId={id} plugin={plugin} />`，两者都可单独复用，参数类型为 `SessionPluginLabelProps` / `SessionPluginIconProps`）；没有声明或图标不可用时回退技术 ID 与通用占位。授权、缓存、调用一律仍用 `plugin.name`。
+
+插件的账号、token 等配置由包内 JSON Schema 声明，选择器就地提供填写入口：首次激活缺配置的插件会直接弹出表单（`<SessionPluginConfigDialog client={client} sessionId={id} plugin={plugin} />`），已配置的插件在行内提供「配置」按钮。表单本体是 `<SessionPluginConfigForm>`，参数与提交类型为 `SessionPluginConfigFormProps` / `SessionPluginConfigDraft`，也可单独嵌入；`SessionPluginConfigDialogProps` 是对话框的参数类型。
+
+表单只呈现它确定能呈现的 JSON Schema 构造（字符串/数值/布尔/null、对象与数组、枚举、`properties` 内的 `writeOnly`，以及用同一字段的 `const` 固定的 `oneOf` 分支）；遇到无法安全呈现的写法直接说明原因，不降级成手写 JSON、不静默丢字段。`writeOnly` 字段永不回显：留空表示保持不变，输入表示修改，显式「清除」才会删除。
+### 连接器面板
+
+首页与对话输入框共用同一个连接器面板：`<ConnectorPanel client={client} sessionId={id} />`，
+参数类型为 `ConnectorPanelProps`。面板本身只管插件分区，电脑与外部账号由宿主通过
+`renderComputerSection` / `renderExternalAccounts` / `renderFooterActions` 注入——那些入口
+要跳宿主自己的路由，SDK 不硬编码内部路径。`sessionId` 传 `null` 表示"首页"：此时开关只记录
+本次输入的待选（`PluginConnectorSelection`、`onPendingPluginsChange`），不激活任何东西、
+不建会话、不启沙盒；`pendingDisabledReason` 用于说明该模式下为什么用不了待选。
+
+插件行的渲染交给 `<PluginConnectorList>`（`PluginConnectorListProps`），它只负责样式与排版：
+"该显示成什么"全部来自 `PluginConnectorItem`、`mergeConnectorItems`、`catalogToConnectorItems`、
+`filterConnectorItems`，判定不各写一份。`sessionPluginLabel` 决定
+一行读起来是什么名字。
+
+启用时序由 `useSessionPluginActivation` 收口（返回值类型 `UseSessionPluginActivationResult`）：
+**先准备配置、再提交激活**。缺必填配置时开关不落到已启用、立刻弹表单，保存由服务端确认配置
+完整才提交；取消、校验失败、读取失败都保持关闭，不会先写 `active=true` 再补偿。慢准备/慢激活
+期间开关仍可点，语义是取消这次意图而不是再排一次队。配置弹窗由 `ConfiguringPlugin` 描述。
+
+触发器要在不打开面板时就能显示"选了哪几个、几个"：用 `selectionFromItem` 把一行转成
+`PluginConnectorSelection`，再用 `triggerSummary` 折成 `TriggerSummary`（最多 `TRIGGER_ICON_LIMIT`
+个图标，其余折成数量；没有图标 token 的项不占图标位但仍计数）。
+
+### MCP Apps
+
+`McpAppCard` 使用官方 AppBridge 渲染归档卡片，内置 Web 消费同一组件。在 `BladeProvider` 下传入会话 ID 与来源 ID，也可直接提供 `BladeClient`。`McpAppMessage` 表示 App 提供的文本；`McpAppMessageContext` 将其交给当前对话的待发送区。用户可在 `ChatView` 查看、移除并确认发送。`update-model-context` 会把 App 提交的当前状态经 `sessions.updateMcpAppContext` 存为会话上下文：只落库、不追加聊天、不启动 agent turn，正在运行的一轮保持启动时版本，下一个新的运行才读取；冲突（409）时重读最新 revision 后重提同一份状态一次。

package/dist/chunk-G3PMV62Z.js

@@ -0,0 +1,36 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+export {
+  __commonJS,
+  __export,
+  __toESM
+};
+//# sourceMappingURL=chunk-G3PMV62Z.js.map

package/dist/{chunk-ZXXLY4RM.js → chunk-IA6J2NTB.js}

@@ -1,32 +1,8 @@
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
-};
-var __export = (target, all5) => {
-  for (var name2 in all5)
-    __defProp(target, name2, { get: all5[name2], enumerable: true });
-};
-var __copyProps = (to2, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to2, key) && key !== except)
-        __defProp(to2, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to2;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
+import {
+  __commonJS,
+  __export,
+  __toESM
+} from "./chunk-G3PMV62Z.js";
 
 // ../../node_modules/.pnpm/inline-style-parser@0.2.7/node_modules/inline-style-parser/cjs/index.js
 var require_cjs = __commonJS({
@@ -27409,7 +27385,7 @@ var Se2 = createContext({ code: "" });
 var de2 = () => useContext(Se2);
 var ot = ({ language: e }) => jsx("div", { className: "flex h-8 items-center text-muted-foreground text-xs", "data-language": e, "data-streamdown": "code-block-header", children: jsx("span", { className: "ml-1 font-mono lowercase", children: e }) });
 var cn2 = /\n+$/;
-var dn2 = lazy(() => import("./highlighted-body-B3W2YXNL-YD7FAP6V.js").then((e) => ({ default: e.HighlightedCodeBlockBody })));
+var dn2 = lazy(() => import("./highlighted-body-B3W2YXNL-YF4GVJGP.js").then((e) => ({ default: e.HighlightedCodeBlockBody })));
 var rt2 = ({ code: e, language: t, className: o, children: n, isIncomplete: s2 = false, ...r2 }) => {
   let i = useMemo(() => e.replace(cn2, ""), [e]), c = useMemo(() => ({ bg: "transparent", fg: "inherit", tokens: i.split(`
 `).map((a2) => [{ content: a2, color: "inherit", bgColor: "transparent", htmlStyle: {}, offset: 0 }]) }), [i]);
@@ -27756,7 +27732,7 @@ var Dt = ({ children: e, className: t, onDownload: o, onError: n }) => {
   }, []), jsxs("div", { className: "relative", ref: i, children: [jsx("button", { className: f2("cursor-pointer p-1 text-muted-foreground transition-all hover:text-foreground disabled:cursor-not-allowed disabled:opacity-50", t), disabled: c, onClick: () => r2(!s2), title: "Download table", type: "button", children: e != null ? e : jsx(Z3, { size: 14 }) }), s2 ? jsxs("div", { className: "absolute top-full right-0 z-10 mt-1 min-w-[120px] overflow-hidden rounded-md border border-border bg-background shadow-lg", children: [jsx("button", { className: "w-full px-3 py-2 text-left text-sm transition-colors hover:bg-muted/40", onClick: () => a2("csv"), title: "Download table as CSV", type: "button", children: "CSV" }), jsx("button", { className: "w-full px-3 py-2 text-left text-sm transition-colors hover:bg-muted/40", onClick: () => a2("markdown"), title: "Download table as Markdown", type: "button", children: "Markdown" })] }) : null] });
 };
 var Vt = ({ children: e, className: t, showControls: o, ...n }) => jsxs("div", { className: "my-4 flex flex-col gap-2 rounded-lg border border-border bg-sidebar p-2", "data-streamdown": "table-wrapper", children: [o ? jsxs("div", { className: "flex items-center justify-end gap-1", children: [jsx(Ht, {}), jsx(Dt, {})] }) : null, jsx("div", { className: "border-collapse overflow-x-auto overscroll-y-auto rounded-md border border-border bg-background", children: jsx("table", { className: f2("w-full divide-y divide-border", t), "data-streamdown": "table", ...n, children: e }) })] });
-var Jn = lazy(() => import("./mermaid-3ZIDBTTL-N7YKJ3SM.js").then((e) => ({ default: e.Mermaid })));
+var Jn = lazy(() => import("./mermaid-3ZIDBTTL-QL4YGD6I.js").then((e) => ({ default: e.Mermaid })));
 var Kn2 = /language-([^\s]+)/;
 function ke2(e, t) {
   if (!(e != null && e.position || t != null && t.position)) return true;
@@ -28246,10 +28222,11 @@ var Nt = ({ chart: e, className: t, config: o, fullscreen: n = false, showContro
 
 export {
   clsx,
+  twMerge,
   Qe2 as Qe,
   Ks,
   R2 as R,
   _r,
   Nt
 };
-//# sourceMappingURL=chunk-ZXXLY4RM.js.map
+//# sourceMappingURL=chunk-IA6J2NTB.js.map