@blade-hq/agent-react 2610.0.0-beta.89 → 2610.0.0-beta.90

package/README.md

@@ -183,11 +183,13 @@ await replay.exitToAutonomous()                // 退出回放，之后真的运
 使用 `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` 事件推给宿主自建面板。
+MCP App 卡片（`tool_ui` block）在默认消息流里自动渲染，无需配置；自建消息布局时可用 `ToolUiCardView` 渲染单个卡片，并传入 `sessionId` 启用共享 AppBridge。卡片的实例、内容解析与终态（archived 留档不重放）判定来自 agent-client 的共享层（`collectInlineToolUiCards` / `resolveToolUiCardContent` 等）。preview 卡片不进消息流，由 `toolPreview` 事件推给宿主自建面板。 文件引用卡片（`resource-file`）只带 `sourcePath`，`ToolUiCardView` 在 `BladeProvider` 下由父页面带鉴权读取当前文件，再放入无令牌、无同源权限的 iframe 渲染；同一路径的新卡片不会自动重载当前页面，用户点击卡片上方的“刷新”按钮才重新读取。自建面板也应按路径去重、首次打开时读取，并保留用户操作中的页面直到手动刷新。
 
 `onFollowupInteraction` 使用 `FollowupInteractionEvent`，覆盖下一步建议展示/采纳、成果展示/打开/下载以及结果评分。SDK 不内置分析服务；宿主回调抛错也不会中断用户点击或下载。
 文件成果以文件名为文本的标准下载链接展示；Vue / 纯 HTML 使用的 `<blade-chat>` 与 `ChatView` 行为一致。
@@ -611,6 +613,27 @@ blade-chat::part(input-toolbar) { gap: 12px; }
 
 `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 仍直接由浏览器加载。

package/dist/components/BackgroundWakeNotice.d.ts

@@ -0,0 +1,2 @@
+/** Shared by the SDK, built-in chat and developer message view. */
+export declare function BackgroundWakeNotice(): import("react/jsx-runtime").JSX.Element;

package/dist/components/SessionBranchPicker.d.ts

@@ -0,0 +1,11 @@
+import type { BladeClient } from "@blade-hq/agent-client";
+type CheckpointTree = Awaited<ReturnType<BladeClient["sessions"]["getSessionCheckpoints"]>>;
+export interface SessionBranchPickerProps {
+    tree: CheckpointTree;
+    /** Disable changes while this session is running or read-only. */
+    disabled?: boolean;
+    /** Restore only the conversation; the host owns history refresh and composer drafts. */
+    onCheckout: (checkpointId: string, position: "before" | "turn_end") => Promise<void>;
+}
+export declare function SessionBranchPicker({ tree, disabled, onCheckout, }: SessionBranchPickerProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/markdown/parse.d.ts

@@ -1,7 +1,7 @@
 import type { Root } from "mdast";
 /**
- * Markdown 字符串 -> mdast 语法树，启用 GFM（表格、任务列表、删除线、脚注、
- * 自动链接）。不做增量缓存——那是 `incremental.ts` 的职责，这里只是纯函数
+ * Markdown 字符串 -> mdast 语法树，启用 GFM（表格、任务列表、脚注、
+ * 自动链接），禁用删除线，波浪号保留为原文。不做增量缓存——那是 `incremental.ts` 的职责，这里只是纯函数
  * 封装，方便增量解析对"整篇重新解析"和"只解析一段尾部"复用同一套扩展配置。
  *
  * `cjkFriendlyExtension` 覆盖了 CommonMark 默认的强调符号（`**`/`_`）

package/dist/embed/entry.d.ts

@@ -67,6 +67,7 @@ declare const BladeAgent: {
     getTextContent: typeof agentClient.getTextContent;
     groupMessagesByLoop: typeof agentClient.groupMessagesByLoop;
     isHiddenInternalMessage: typeof agentClient.isHiddenInternalMessage;
+    isBackgroundWakeMessage: typeof agentClient.isBackgroundWakeMessage;
     normalizeMessageContent: typeof agentClient.normalizeMessageContent;
     transformSlashCommand: typeof agentClient.transformSlashCommand;
     contextProjectionData: typeof agentClient.contextProjectionData;

package/dist/index.d.ts

@@ -73,4 +73,7 @@ export type { AgentComputerLaunchOutcome } from "./lib/agent-computer-command";
 export * from "@blade-hq/agent-client";
 export { AgentTaskCard } from "./components/AgentTaskCard";
 export type { AgentTaskCardProps, AgentTaskStatus } from "./components/AgentTaskCard";
+export { SessionBranchPicker } from "./components/SessionBranchPicker";
+export type { SessionBranchPickerProps } from "./components/SessionBranchPicker";
 export { MessageImage, type MessageImageProps } from "./components/MessageImage";
+export { BackgroundWakeNotice } from "./components/BackgroundWakeNotice";