npm - @blade-hq/agent-react - Versions diffs - 2612.0.0-beta.0 → 2612.0.0-beta.10 - Mend

@blade-hq/agent-react 2612.0.0-beta.0 → 2612.0.0-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1286) hide show

package/README.md CHANGED Viewed

@@ -6,6 +6,8 @@ Blade Agent 的 React 绑定：`BladeProvider` + `useAgentSession` + 开箱即
 pnpm add @blade-hq/agent-client @blade-hq/agent-react
 ```
+TypeScript 消费者需要开发依赖 `@types/node`：底层 arktype 的声明使用 Node `buffer.File` 类型。若显式配置 `compilerOptions.types`，需包含 `node`；这是类型检查环境要求，浏览器运行时不因此依赖 Node。React 使用者还需对应版本的 `@types/react` / `@types/react-dom`。
 默认装到的是当前长期支持版（LTS），厂内离线交付按它开发。要跟两周一发的公网版本，改用 `@next`。
 最稳妥的做法是先读目标 Server 的 `GET /api/version`，按返回的版本号在 `package.json` 里钉死——NPM 的 `latest` 不一定和目标环境跑的版本一致。
@@ -43,6 +45,23 @@ export function App() {
 Props 见 `BladeProviderProps`；在 Provider 外调用本包任何 hook 都会抛错。
+### 宿主动作（host）
+聊天界面里有些动作只有宿主知道怎么做：在工作区打开文件、打开预览、跳到另一个会话或项目、上传附件、列出可提及的技能和知识库。把它们作为 `host` 传进来（类型 `BladeHost`，附件与清单条目见 `HostAttachment`、`HostCatalogItem`）：
+```tsx
+const host: BladeHost = {
+  openSession: (sessionId) => navigate(`/chat/${sessionId}`),
+  openWorkspaceFile: ({ sessionId, path }) => openFile(sessionId, path),
+}
+<BladeProvider client={client} host={host}>{children}</BladeProvider>
+```
+每个动作都可选：**没提供的动作，对应的按钮和菜单项不显示**。`host` 请传稳定引用（模块常量或 `useMemo`）。
+> 当前版本的 `ChatView` 还没有调用这些动作，传入后界面暂时没有变化；聊天组件与内置 Web 统一后（#3061）会接入。
 ## useBladeClient
 ```tsx
@@ -74,26 +93,6 @@ await session?.send("你好")
 - 必须覆盖连接窗口内事件时，用 `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
 会话回放（演示 / 彩排）：拿一个已经聊完的会话当素材，重现当时的回复和工具调用，
@@ -179,43 +178,28 @@ await replay.exitToAutonomous()                // 退出回放，之后真的运
 全部 props 见 `ChatViewProps`。样式说明：
 智能体调用 `update_plan` 新增或更新任务时，`ChatView` 会在输入框上方自动展开最新任务进度，
-5 秒后平滑收起；连续更新会重新计时，用户手动展开或收起后以用户选择为准。自建聊天布局可直接
-使用 `CurrentPlanPanel` / `PlanUpdateBlock`，或用 `getPlanUpdateDisplayState`、
-`parsePlanUpdate` 和 `pickCurrentPlanStep` 复用同一套判定。
-后台任务自动唤醒会话时，`ChatView` 显示简短的 `BackgroundWakeNotice`，说明助手为何继续处理。卡片由明确的后台来源标记生成，流式和历史加载一致；自定义消息列表可以复用该组件及 agent-client 的 `isBackgroundWakeMessage`，无需解析内部提示文本。
-`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` 事件推给宿主自建面板。 文件引用卡片（`resource-file`）只带 `sourcePath`，`ToolUiCardView` 在 `BladeProvider` 下由父页面带鉴权读取当前文件，再放入无令牌、无同源权限的 iframe 渲染；同一路径的新卡片不会自动重载当前页面，用户点击卡片上方的“刷新”按钮才重新读取。自建面板也应按路径去重、首次打开时读取，并保留用户操作中的页面直到手动刷新。
+5 秒后平滑收起；连续更新会重新计时，用户手动展开或收起后以用户选择为准。
 `onFollowupInteraction` 使用 `FollowupInteractionEvent`，覆盖下一步建议展示/采纳、成果展示/打开/下载以及结果评分。SDK 不内置分析服务；宿主回调抛错也不会中断用户点击或下载。
 文件成果以文件名为文本的标准下载链接展示；Vue / 纯 HTML 使用的 `<blade-chat>` 与 `ChatView` 行为一致。
 - 必须引入一份样式，按宿主有没有 Tailwind 二选一：
   - **`style.full.css`**（默认选它）：CSS 变量、容器查询、Markdown 排版等兜底 + 编译好的 Tailwind 产物，自包含，宿主没装 Tailwind 也是完整视觉。
-  - **`style.css`**：只有兜底那部分（Tailwind 类表达不了的规则）。宿主自己装了 Tailwind、且 `content` 配了扫描 `node_modules/@blade-hq/agent-react` 时用它，可以少一份重复 CSS。选错不会报错，只是布局、配色、工具块和思考块会退化成裸 HTML——组件的视觉本来就只定义一次，都在它的 Tailwind 类上。
+  - **`style.css`**：只有兜底那部分（Tailwind 类表达不了的规则），**不含主题变量**。宿主自己装了 Tailwind、且 `content` 配了扫描 `node_modules/@blade-hq/agent-react` 时用它，可以少一份重复 CSS；主题变量（下面「CSS 变量清单」）与 `bg-popover` 这类语义色工具类要由宿主自己提供。选错不会报错，只是布局、配色、工具块和思考块会退化成裸 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"`，否则拿到的是默认的浅色变量。
+- 颜色走 CSS 变量，可整体换肤；深色页面要在聊天根节点或它的祖先元素上写 `data-theme="dark"`（或给 `ChatView` 传 `theme="dark"`），否则拿到的是默认的浅色变量。
 - `renderers.toolCall` 返回 `null` 时回落到默认工具卡片。
 - **内边距按容器宽度伸缩**，嵌进窄侧栏（300–400px）时会自动收窄，不看浏览器视口。代价是聊天容器需要有确定宽度——放在 flex/grid 里被拉伸，或显式给宽度都可以；放进 `width: fit-content`、`inline-flex` 这类由内容决定宽度的父容器会塌缩。
 ## 纯 LLM 模式（不建会话）
 有些应用只要「一问一答」——分类、改写、总结，不需要智能体、不需要会话、也不需要用户登录
-Blade。这时把 `ChatView` 切到 `mode="llm"`，或者直接用下层的 `LlmChat`，界面完全一样：
+Blade。这时把 `ChatView` 切到 `mode="llm"`，界面完全一样：
 ```tsx
 <ChatView />                                                  // 默认：智能体模式，行为不变
 <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`，读
@@ -252,23 +236,26 @@ models.filter((m) => m.serviceModelId)
 每一轮工具调用都会渲染成和智能体模式一样的工具卡片。
 ```tsx
-<LlmChat
-  baseURL="/api/llm"
-  model={model}
-  system="你是订单助手"
-  tools={[{ type: "function", function: { name: "query_orders", parameters: schema } }]}  // ChatCompletionTool
-  onToolCall={async ({ name, arguments: args }) => {
-    if (name !== "query_orders") throw new Error(`没有这个函数：${name}`)
-    // 参数是模型生成的不可信输入：先校验类型，再用 URLSearchParams 拼，
-    // 直接塞进查询串的话，一个 `李航&limit=all` 就能多带出参数
-    const { owner } = JSON.parse(args || "{}")
-    if (typeof owner !== "string") throw new Error("owner 必须是字符串")
-    const query = new URLSearchParams({ owner })
-    const resp = await fetch(`/api/orders?${query}`)
-    if (!resp.ok) throw new Error(`订单接口返回 ${resp.status}`)
-    return resp.json()
+<ChatView
+  mode="llm"
+  llm={{
+    baseURL: "/api/llm",
+    model,
+    system: "你是订单助手",
+    tools: [{ type: "function", function: { name: "query_orders", parameters: schema } }], // ChatCompletionTool
+    onToolCall: async ({ name, arguments: args }) => {
+      if (name !== "query_orders") throw new Error(`没有这个函数：${name}`)
+      // 参数是模型生成的不可信输入：先校验类型，再用 URLSearchParams 拼，
+      // 直接塞进查询串的话，一个 `李航&limit=all` 就能多带出参数
+      const { owner } = JSON.parse(args || "{}")
+      if (typeof owner !== "string") throw new Error("owner 必须是字符串")
+      const query = new URLSearchParams({ owner })
+      const resp = await fetch(`/api/orders?${query}`)
+      if (!resp.ok) throw new Error(`订单接口返回 ${resp.status}`)
+      return resp.json()
+    },
   }}
-  onReady={(handle) => setChat(handle)}   // LlmChatHandle：insertText / send / reset
+  onLlmReady={(handle) => setChat(handle)}   // LlmChatHandle：insertText / send / reset
 />
 ```
@@ -278,19 +265,17 @@ models.filter((m) => m.serviceModelId)
 改过之后会显示「已自定义」，也能一键恢复默认。不传就一个节点都不渲染。
 ```tsx
-<LlmChat baseURL="/api/llm" model={model} advanced />
-<LlmChat baseURL="/api/llm" model={model} advanced={{ apiKey: true, storage: "memory" }} />
 <ChatView mode="llm" llm={{ baseURL: "/api/llm", model, advanced: true }} />
+<ChatView mode="llm" llm={{ baseURL: "/api/llm", model, advanced: { apiKey: true, storage: "memory" } }} />
 ```
-`LlmAdvancedSettings` 可细调：`baseURL` / `model` 各自能不能改（默认都能）、`apiKey` 要不要
+`advanced` 对象可细调：`baseURL` / `model` 各自能不能改（默认都能）、`apiKey` 要不要
 出现（**默认不出现**，打开意味着密钥存在浏览器里，只适合受控场景）、`storage` 是记住选择
 （`local`，默认）还是只在本次有效（`memory`）、`storageKey` 自定义存储键。用户改了会回调
-`onOverrideChange`（`LlmOverride`），宿主想自己也记一份时用。
+`llm.onOverrideChange`，宿主想自己也记一份时用。
 其余可选项见 `LlmChatOptions`：`headers`、`historyTurns`（默认 12 轮）、`temperature`、
-`extraBody`、`fetchImpl`。只要状态机、界面自己写的，用 `useLlmChat`（返回
-`UseLlmChatResult`：`messages` / `isStreaming` / `error` / `send` / `stop` / `reset`）。
+`extraBody`、`fetchImpl`。
 纯 LLM 模式不做会话持久化、文件上传、提问卡片、记忆和检查点——那些是智能体协议的能力，
 需要就用默认模式。
@@ -300,48 +285,13 @@ models.filter((m) => m.serviceModelId)
 单独渲染一段智能体消息 Markdown（含代码复制按钮、XSS 消毒；HTML 经 sanitize 白名单处理，不接受任意 raw HTML）：
 ```tsx
-<MarkdownContent content={markdownText} />
-```
-```tsx
-<MarkdownContent sessionId={sessionId}>{markdownText}</MarkdownContent>
+<MarkdownContent>{markdownText}</MarkdownContent>
 ```
-`normalizeAdjacentUrlFormatting` 可在复用其他 Markdown 渲染器前，保护紧贴行内格式标记的 URL。
-## Canonical 引用消息
-`ChatView` 会自动识别 ship-attack 会话中的 `[引用]` / `[用户输入]` canonical
-消息，并按原顺序展示引用来源、快照和用户输入。自建消息列表时可用
-`parseWhatIfPrompt` 解析同一格式，再交给 `WhatIfUserBubble` 渲染；
-`onQuoteClick` 可接入宿主的步骤跳转。
+传 `sessionId` 时，正文里相对路径的图片按该会话工作区里的文件解析：
 ```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"
+<MarkdownContent sessionId={sessionId}>{markdownText}</MarkdownContent>
 ```
 ## 选择模型
@@ -360,23 +310,23 @@ 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` 等变量（完整清单见下面的「CSS 变量清单」，默认值在 style.css 开头）。页面直接覆盖即可穿透 Shadow DOM：
+2. **CSS 变量换肤**（React 与 `<blade-chat>` 通用）：所有颜色走 `--primary`、`--background`、`--muted` 等变量（完整清单见下面的「CSS 变量清单」，默认值随 `style.full.css` 与 `blade-agent.js` 一起提供，和内置 Web 是同一套取值）。页面直接覆盖即可穿透 Shadow DOM：
 ```css
 blade-chat { --primary: 262 83% 58%; height: 640px; }
 ```
-3. **classNames props**（React）：`ChatView` 的 `classNames` 把自定义 class（含你自己构建的 Tailwind 工具类）挂到各个区块上，见 `ChatViewClassNames`。SDK 内部用 `cn`（clsx + tailwind-merge）拼接，你传的类在最后一个参数，所以 `classNames={{ chatInput: "p-0" }}` 会直接盖掉组件内部的 `py-3`，与 CSS 加载顺序无关：
+3. **classNames props**（React）：`ChatView` 的 `classNames` 把自定义 class（含你自己构建的 Tailwind 工具类）挂到各个区块上，见 `ChatViewClassNames`。SDK 内部用 `cn`（clsx + tailwind-merge）拼接，你传的类在最后一个参数，所以 `classNames={{ chatInputRoot: "p-0" }}` 会直接盖掉组件内部的内边距，与 CSS 加载顺序无关：
 ```tsx
 <ChatView
   sessionId={id}
   classNames={{
     root: "h-[640px] rounded-2xl border",
-    userBubble: "bg-sky-100 text-sky-900",
+    userMessage: "[&_.blade-chat-user-bubble]:bg-sky-100",
     assistantText: "text-[15px] leading-7",
-    chatInput: "px-2",
-    inputInner: "bg-white shadow-sm",
+    chatInputRoot: "px-2",
+    chatInputInner: "max-w-4xl",
   }}
 />
 ```
@@ -399,38 +349,26 @@ 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` | 输入框右侧按钮组 |
+`classNames` 是便利功能，键名跟随组件结构，不冻结；需要稳定抓手时用下面的锚点类名或 `part`。
+| `classNames` 键 | 落点（锚点） |
+| --- | --- |
+| `root` | 聊天根容器（`.blade-chat`） |
+| `viewerBanner` | 查看分享会话时的只读提示条 |
+| `messageListRoot` | 消息区（`.blade-chat-messages`） |
+| `messageListViewport` | 消息区滚动内容，管内边距（`.blade-chat-messages-scroll`） |
+| `messageListContent` | 消息内容列，管居中与最大宽度（`.blade-chat-messages-content`） |
+| `messageListInner` | 内容列里逐轮排列的容器，管轮次间距 |
+| `emptyState` | 空状态（`.blade-chat-empty`） |
+| `userMessage` | 用户消息行（`.blade-chat-user-row`） |
+| `errorMessage` | 消息流里的出错块（`.blade-chat-error-row`） |
+| `assistantTurn` | 一轮助手回复（`.blade-chat-assistant-turn`） |
+| `assistantText` | 助手正文（`.blade-chat-assistant-text`） |
+| `toolCall` | 执行过程里的工具行与子智能体行（`.blade-chat-tool-row`、`.blade-chat-agent-loop`） |
+| `chatInputRoot` | 输入区外层（`.blade-chat-input`） |
+| `chatInputInner` | 输入框、计划面板与队列面板共用的内容宽度 |
+| `queuePanelRoot` | 会话队列面板（`.blade-chat-queue`）；改输入区左右内边距时在这里同步 `--blade-chat-queue-gutter` |
+| `skillStatusBarRoot`、`skillStatusBarInner` | 富输入菜单里的技能状态条（第一方内置 Web 用） |
 同一批锚点也是普通 CSS 的抓手：锚点只负责「可被选中」，视觉规则不在它身上，所以对你的锚点写 `.blade-chat-user-bubble { ... }` 不会被 SDK 的样式盖掉（SDK 的规则都在 `@layer components` / `@layer blade-chat-overrides`，Tailwind 工具类在 `@layer utilities`，你的样式不分层，按 CSS 层序本来就赢）。
@@ -443,7 +381,7 @@ blade-chat::part(input-toolbar) { gap: 12px; }
 | 聊天根容器 | `.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-user-row`、`.blade-chat-user-col`、`.blade-chat-user-bubble`、`.blade-chat-file-card` |
 | 助手回复 | `.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` |
@@ -451,8 +389,8 @@ blade-chat::part(input-toolbar) { gap: 12px; }
 | 跟进区 | `.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` |
+| Markdown 与代码块 | `.blade-chat-markdown`、`.blade-chat-prose`、`.blade-chat-table-wrapper`、`.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` |
 ### part 清单（`<blade-chat>` 的 Shadow DOM 专用）
@@ -480,7 +418,7 @@ blade-chat::part(input-toolbar) { gap: 12px; }
 ### CSS 变量清单
-颜色是 `hsl()` 的三个分量（形如 `223 100% 54%`），几何是长度值。宿主盖掉这些变量即可整体换肤（React 下写在 `.blade-chat` 或祖先元素上；`<blade-chat>` 下写在元素上，变量能穿透 Shadow DOM）：
+颜色是 `hsl()` 的三个分量（形如 `223 100% 54%`），几何是长度值。宿主盖掉这些变量即可整体换肤（React 下写在 `.blade-chat` 上——默认值就声明在这一层，写在祖先元素上会被盖掉；聊天区之外的 SDK 内容（Portal 到 body 的浮层、单独使用的组件）取 `:root` 上的值，宿主没声明时用零优先级的默认值；`<blade-chat>` 下写在元素上，变量能穿透 Shadow DOM，深浅主题下都生效）：
 | 分组 | 变量 |
 | --- | --- |
@@ -490,9 +428,9 @@ blade-chat::part(input-toolbar) { gap: 12px; }
 | 布局（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 / 属性落到聊天根节点，整棵子树继承。
+深色主题的变量：`<blade-chat>` 挂在 `:host([theme="dark"])` 上（只声明在宿主元素这一层，所以元素上的覆盖在深色下同样生效）；React 下挂在带 `data-theme="dark"` 的 `.blade-chat` 或其祖先之内的 `.blade-chat` 上。
-上面这些是**会改变 SDK 组件外观**的变量。另外随主题一起声明的还有 `--radius`、`--input`、`--destructive-foreground`：`agent-react` 的默认组件不消费它们（圆角走 Tailwind 自己的 `--radius-*`），宿主在聊天容器里自绘 UI 时可以直接用，改动它们不会影响 SDK 自带的界面。
+上面这些是**会改变 SDK 组件外观**的变量。另外随主题一起声明的还有 `--radius`、`--input`、`--destructive-foreground`：它们不在冻结的变量清单里。`--radius` 决定 Tailwind 圆角尺度（`rounded-md` 等由它推导）；`--input`、`--destructive-foreground` 供宿主在聊天容器里自绘 UI 时直接用。
 ### 区块级渲染器（renderers）
@@ -512,132 +450,42 @@ blade-chat::part(input-toolbar) { gap: 12px; }
 ```
 - `toolCall`：`(toolCall: ToolCallInfo) => ReactNode | null`，见 `ToolCallRenderer`。
+- `tool`：按工具名替换工具行展开后的详情，形如 `{ my_tool: MyToolDetail }`；组件拿到 `ToolRendererProps`（`toolCall`、`sessionId`），工具行本身（名称、状态、耗时）仍由 SDK 渲染。
 - `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`、`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`、`MarkdownRenderer`、`MarkdownRendererProps`、`MarkdownComponents`、`AllowedTags`、`DEFAULT_ALLOWED_TAGS`、`CodeBlockOverrides`、`LinkSafetyConfig`、`RawHtmlPlugin`、`parseWhatIfPrompt`、`ParsedWhatIfPrompt`、`WhatIfQuote`、`WhatIfUserBubble`、`WhatIfUserBubbleProps`、`SessionQueuePanel`、`SessionQueuePanelProps`、`isQueuePanelVisible`、`ExternalAnchor`、`stripSystemReminders`。
-## 会话消息队列
-智能体会话的等待消息由服务端持久化，`ChatView` / `AgentChat` 已在输入框上方渲染队列区域（空队列不占位，条目数超过三条可折叠）。输入框不再有「直接插入 / 排队执行」开关：会话空闲时提交直接开始处理，运行中提交默认入队；暂停时在面板上显示原因和「继续执行」。面板数据来自 `useAgentSession` 状态里的 `queue`（`SessionQueueSnapshot`），可编辑/删除/立即补充的判定来自 agent-client 的 `canEditQueuedMessage` / `canCancelQueuedMessage` / `canDeliverQueuedMessage`，文案用 `queuedMessageStatusLabel` / `queuePauseReasonLabel`。
+不需要本包——用后端托管的单文件产物 `<script src=".../sdk/blade-agent.js">` + `<blade-chat>` 自定义元素，行为与 `ChatView` 一致。Vue 项目用 `@blade-hq/agent-vue` 的 `<BladeChat>` 组件；区块定制用挂载式渲染器（`<blade-chat>` 元素的 `renderers` 属性），详见 agent-client README「`<blade-chat>` 的挂载式渲染器」。
-自建布局可直接使用 `<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` 成同一个值，否则面板会跟输入框错开一圈、在两者相接的缝上露出来。
+- `@blade-hq/agent-react/internal`：内置 Web 与浏览器插件用的聊天内部块、判定逻辑和连接器组件。
+- `@blade-hq/agent-react/rich-input`：富输入（Tiptap 编辑器、提及、`/` 菜单、语音、模型选择）。
+- `@blade-hq/agent-react/chat.css`：聊天正文的 Markdown 排版与动画，给自己编译 Tailwind 的第一方宿主（内置 Web、浏览器插件）引入；`style.full.css` 与 `blade-agent.js` 已经包含它。
-输入框的 `mergesWithPanelAbove` 为 true 时上两角改直角，跟面板拼成一条完整轮廓；否则输入框的上角圆弧会从较窄的面板两侧露出来，形成两个尖角。**这个值要取面板上报的状态，不要在宿主侧用 `isQueuePanelVisible` 复算**：面板有本地编辑态（编辑到一半、那条等待消息被服务端拿走时仍要留在原地保住草稿，见 `detachedEdit`），这时 snapshot 里没有条目、宿主复算会得到 false，输入框就会在面板还显示着的时候把上角恢复成圆角。用 `onVisibleChange` 拿到面板的真实占位状态，再传给输入框或 `ChatSurface` 的 `queuePanelVisible`。本包的 `AgentChat` 已按这条接好，自建布局照做即可。
+三者都随包发布，但**不属于公开面**：不写进本文档与 `public-api.md`，版本之间可以随时改动或删除。
-拼轮廓的前提是两者**真的相邻**。中间夹着别的内容时（本包的 MCP 暂存内容、内置 Web 的 `composerBanner`），面板下两角与输入框上两角都要圆起来——直角是"被对方接住"的表示，露出直角却中间空着一块，看起来像被削掉一角。面板的 `mergesWithInputBelow` 与输入框的 `mergesWithPanelAbove` 要取同一个判据；`ChatSurface` 会用 context 把这一位传给面板，自建布局直接传即可。
+## 附录：公开声明
-`PollingBackoff` 从 agent-client 重导出，供自定义只读轮询计算退避时间；它不发送或重放请求。用法见 [agent-client 轮询说明](../agent-client/README.md#只读轮询退避)。
+完整签名见 [public-api.md](./public-api.md)。本包公开声明：`BladeProvider`、`BladeProviderProps`、`BladeHost`、`HostAttachment`、`HostCatalogItem`、`useBladeClient`、`useAgentSession`、`UseAgentSessionOptions`、`UseAgentSessionResult`、`useReplay`、`UseReplayResult`、`ReplayMismatch`、`ReplayBar`、`ReplayBarProps`、`ReplayMismatchPrompt`、`ReplayMismatchPromptProps`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`UserMessageRendererProps`、`AssistantTextRendererProps`、`AskUserQuestionRendererProps`、`AskUserQuestionData`、`PlanUpdateRendererProps`、`PlanUpdateData`、`PlanStepStatus`、`ToolCallRenderer`、`ToolRendererProps`、`FollowupInteractionEvent`、`LlmChatHandle`、`LlmChatOptions`、`ChatCompletionTool`、`LlmToolCall`、`MarkdownContent`、`MarkdownContentProps`。
-### 会话插件
+`@blade-hq/agent-client` 不再从本包转出，`BladeClient`、`AgentSession` 等直接从 `@blade-hq/agent-client` import。
-默认 `AgentChat` / 智能体模式 `ChatView` 自带会话插件选择器，展开时查询 BH，选择按当前会话保存。准备失败会保留勾选并提供重试。独立嵌入可使用 `<SessionPluginSelector client={client} sessionId={id} />`；`sessionPluginControls` 可覆盖默认控件。组件参数类型为 `SessionPluginSelectorProps`。
+## 主题资产 @
-列表项用插件声明的业务名称与随包本地图标展示（`sessionPluginLabel(plugin)` 与 `<SessionPluginIcon client={client} sessionId={id} plugin={plugin} />`，两者都可单独复用，参数类型为 `SessionPluginLabelProps` / `SessionPluginIconProps`）；没有声明或图标不可用时回退技术 ID 与通用占位。授权、缓存、调用一律仍用 `plugin.name`。
+主题资产候选通过当前主题的资产列表获取，使用专用 `TopicAssetMention` 药丸；没有关联主题时不展示候选。首页与会话输入框复用候选查询、引用序列化和展示结构。
-插件的账号、token 等配置由包内 JSON Schema 声明，选择器就地提供填写入口：首次激活缺配置的插件会直接弹出表单（`<SessionPluginConfigDialog client={client} sessionId={id} plugin={plugin} />`），已配置的插件在行内提供「配置」按钮。表单本体是 `<SessionPluginConfigForm>`，参数与提交类型为 `SessionPluginConfigFormProps` / `SessionPluginConfigDraft`，也可单独嵌入；`SessionPluginConfigDialogProps` 是对话框的参数类型。
+`useReferenceCandidates(getScope, { plugins, topics, files })` 在富输入子入口提供固定三组候选的并发查询、短等待与迟到刷新；作用域为 client、鉴权身份、session、topic，菜单使用 query 返回数组绑定 observe，退出时 cancel。宿主继续提供原有数据适配，控制器不执行工具或改写发送协议。
-表单只呈现它确定能呈现的 JSON Schema 构造（字符串/数值/布尔/null、对象与数组、枚举、`properties` 内的 `writeOnly`，以及用同一字段的 `const` 固定的 `oneOf` 分支）；遇到无法安全呈现的写法直接说明原因，不降级成手写 JSON、不静默丢字段。`writeOnly` 字段永不回显：留空表示保持不变，输入表示修改，显式「清除」才会删除。
-### 连接器面板
+`queueTopicAssetReference(sessionId, { topic_id, path })`（`@blade-hq/agent-react/rich-input`）可在导航到当前用户的同主题会话前预填引用。发送只携带引用身份，元数据和权限由服务端重新判断；本轮续跑保留引用，下一条消息默认不继承。
-首页与对话输入框共用同一个连接器面板：`<ConnectorPanel client={client} sessionId={id} />`，
-参数类型为 `ConnectorPanelProps`。面板本身只管插件分区，电脑与外部账号由宿主通过
-`renderComputerSection` / `renderExternalAccounts` / `renderFooterActions` 注入——那些入口
-要跳宿主自己的路由，SDK 不硬编码内部路径。`sessionId` 传 `null` 表示"首页"：此时开关只记录
-本次输入的待选（`PluginConnectorSelection`、`onPendingPluginsChange`），不激活任何东西、
-不建会话、不启沙盒；`pendingDisabledReason` 用于说明该模式下为什么用不了待选。
+会话文件树可通过宿主提供的提交动作显示“提交到资产”；只读或未关联主题时不显示写入口，服务端仍会独立检查权限。
-插件行的渲染交给 `<PluginConnectorList>`（`PluginConnectorListProps`），它只负责样式与排版：
-"该显示成什么"全部来自 `PluginConnectorItem`、`mergeConnectorItems`、`catalogToConnectorItems`、
-`filterConnectorItems`，判定不各写一份。`sessionPluginLabel` 决定
-一行读起来是什么名字。
+文件提交共享组件：`TopicAssetSubmitDialog`（属性 `TopicAssetSubmitDialogProps`）提供目录选择和提交说明；`useTopicAssetSubmissionAccess` 查询当前会话的主题及写权限。二者用于宿主文件树接入，不能替代服务端鉴权。
-启用时序由 `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 后重提同一份状态一次。
-### 子智能体卡片
-`AgentTaskCard` 提供共享的可折叠子智能体卡片，`AgentTaskCardProps` 接受任务 `title`、`status`、最新动作 `activity` 和详情 `children`。`AgentTaskStatus` 包含 `running`、`waiting_input`、`completed`、`failed`、`cancelled`；进入 `waiting_input` 时自动展开，提示图标持续轻缓闪动，并遵守系统减少动态效果设置。回答表单由宿主通过 `children` 提供，回答后应更新状态以停止提示。
-### 对话分支选择器
-`SessionBranchPicker`（属性类型 `SessionBranchPickerProps`）提供与内置 Web 共用的 Git 风格对话树、消息预览、切换中禁用和错误提示，可放进宿主的弹窗或侧栏。`tree` 使用 `client.sessions.getSessionCheckpoints(sessionId)` 的返回值；`disabled` 应来自该会话的运行状态或只读权限，不能仅依据当前标签页是否收到流式消息。
-```tsx
-<SessionBranchPicker
-  tree={checkpoints}
-  disabled={isRunning || readOnly}
-  onCheckout={async (checkpointId, position) => {
-    const result = await client.sessions.checkoutSession(
-      sessionId, checkpointId, position, "conversation",
-    )
-    await refreshConversation()
-    setDraft(result.position === "before" ? result.content : "")
-    setCheckpoints(await client.sessions.getSessionCheckpoints(sessionId))
-  }}
-/>
-```
-示例中的刷新消息、设置草稿与保存检查点状态由宿主实现。消息圆点回到发送前（`before`），虚线圆点切到分支末尾（`turn_end`）。宿主弹窗应明确说明：这些操作只修改对话记录，不修改、删除或恢复工作目录中的文件；请求使用 `conversation` 模式，不使用文件恢复模式。
-### 会话图片
-`MessageImage` 是聊天组件共用的图片组件，属性类型为 `MessageImageProps`。它支持原生 `<img>` 属性，并从 `BladeProvider` 获取客户端；也可显式传入 `client`。会话资源使用带鉴权的独立请求，公开分享图片使用分享令牌授权，在接近可视区域时加载预览，卸载后回收对象 URL。传入 `original` 可用于原图预览。普通外部图片 URL 仍直接由浏览器加载。
-```tsx
-<MessageImage src={imageUrl} alt="附件图片" width={width} height={height} />
-```
+ChatView 和 `<blade-chat>` 的默认轻量输入支持 @ 搜索插件条目，候选显示中文插件名和图标。选中条目在输入框上方显示，可点 × 移除；发送后保留选择，刷新后恢复最近用户消息的选择。富输入使用同样的候选接口与 PluginRef 身份。自动读取失败时模型会收到明确失败说明。

package/dist/chat/AgentLoopBlock.d.ts ADDED Viewed

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+import type { ToolCallInfo } from "@blade-hq/agent-client/internal";
+interface Props {
+    toolCall: ToolCallInfo;
+    sessionId: string;
+    reasoning?: string;
+    hideAskUserQuestions?: boolean;
+    /** 初始展开(工作流步骤卡默认摊开,老 #1841 体验);等待回答仍强制展开。 */
+    defaultExpanded?: boolean;
+    /** 自定义卡头描述渲染(工作流用它把 {{ref}} 画成引用胶囊)。 */
+    renderDescription?: (description: string) => ReactNode;
+}
+export declare function AgentLoopBlock({ toolCall, sessionId, reasoning, hideAskUserQuestions, defaultExpanded, renderDescription, }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/{components → chat}/AskUserQuestionBlock.d.ts RENAMED Viewed

@@ -1,4 +1,5 @@
 import type { AskUserAnswerData } from "@blade-hq/agent-client";
+export type { AskUserAnswerData };
 interface OptionItem {
     label: string;
     description: string;
@@ -23,20 +24,15 @@ interface Props {
     sessionStatus: string;
     answerData?: AskUserAnswerData | undefined;
     onAnswer?: (answer: string, toolCallId: string, answerData: AskUserAnswerData) => void;
-    className?: string;
-    optionClassName?: string;
 }
-/** 提问选项卡片：单选/多选 + 自定义输入，回答通过 onAnswer 回调交还 ChatView。 */
-export declare function AskUserQuestionBlock({ data, answered, toolCallId, sessionStatus, answerData, onAnswer, className, optionClassName, }: Props): import("react/jsx-runtime").JSX.Element;
-/** 解析 AskUserQuestion 的工具结果/参数，容错 LLM 把 questions 输出为字符串的情况。 */
+export declare function AskUserQuestionBlock({ data, answered, toolCallId, sessionStatus, answerData, onAnswer, }: Props): import("react/jsx-runtime").JSX.Element;
 export declare function parseAskUserQuestion(toolResult: string | null | undefined): AskUserQuestionData | null;
 export interface AskUserQuestionError {
     message: string;
     detail: string | null;
 }
 /**
- * Keep this parser synchronized with apps/web/AskUserQuestionBlock.tsx.
+ * Keep this parser synchronized with agent-react/AskUserQuestionBlock.tsx.
  * The built-in Web cannot import agent-react, and this is not a public SDK protocol API.
  */
 export declare function parseAskUserQuestionError(toolResult: string | null | undefined): AskUserQuestionError | null;
-export {};