@blade-hq/agent-react 2608.0.5 → 2608.0.7-beta.0

package/README.md

@@ -28,6 +28,7 @@ export function App() {
 
 - 不传 `sessionId` 自动创建新会话；未登录时 `ChatView` 自己渲染登录按钮（弹窗授权，见 agent-client 的 `client.auth.login()`）。
 - 同一 `BladeProvider` 下可以放多个 `ChatView`，各自独立会话、互不干扰。
+- 宿主只需要完成态消息时，可在 `BladeClient` 构造参数中传 `streamTokens: false`，不订阅逐 token 增量。
 
 ## BladeProvider
 
@@ -68,6 +69,66 @@ await session?.send("你好")
 - 自动创建只发生一次（含 React StrictMode 双跑）；创建出的 id 通过 `onSessionCreated` 交还，重挂载时把它作为 `sessionId` 传回即可复用会话。
 - 同一 `sessionId` 的多次调用复用同一 `AgentSession` 实例（引用计数）；卸载后延迟释放，路由抖动不会断连。
 
+## useReplay
+
+会话回放（演示 / 彩排）：拿一个已经聊完的会话当素材，重现当时的回复和工具调用，
+**完全不调用模型**。
+
+**进入回放是"派生一个新会话"，不是把当前会话切模式**：`startReplay()` 返回的是新会话
+的 id，拿它去渲染（`<ChatView sessionId={newId} />` 或自己 `connect`）才进入回放。源会话
+原样不动。连上之后也不会自动播——用户照着源会话的问题问，才逐句重现。
+
+同一个 hook 覆盖两种身份——传进去的会话既可能是准备被回放的**源会话**，也可能是**回放中**的会话：
+
+```tsx
+// —— 源会话页面：提供"开始回放"入口 ——
+const { session: sourceSession } = useAgentSession(sourceId)
+const source = useReplay(sourceSession)
+
+source.canReplay        // false 时 source.unsupportedReason 可直接展示
+const replayId = await source.startReplay(5)   // 返回**新建的**回放会话 id，路由过去
+
+// —— 回放会话页面：状态与控制 ——
+const { session: replaySession } = useAgentSession(replayId)
+const replay = useReplay(replaySession)
+
+replay.isReplay         // 是不是在回放
+replay.speed            // 当前倍速
+replay.canControl       // 改回放是 owner 专属；分享出去的只读会话为 false
+replay.mismatch         // 输入和录制对不上时的待决策项
+await replay.setSpeed(2)
+await replay.exitToAutonomous()                // 退出回放，之后真的运行
+```
+
+配套两个组件，直接接上 `useReplay()` 的返回值即可：
+
+```tsx
+<ReplayBar
+  isReplay={replay.isReplay}
+  speed={replay.speed}
+  canControl={replay.canControl}
+  onSpeedChange={(s) => void replay.setSpeed(s)}
+  onExit={() => void replay.exitToAutonomous()}
+/>
+<ReplayMismatchPrompt mismatch={replay.mismatch} />
+```
+
+返回值见 `UseReplayResult`，冲突项见 `ReplayMismatch`，组件属性见 `ReplayBarProps` /
+`ReplayMismatchPromptProps`。
+
+只读身份（分享链接打开的会话）仍然会显示「回放模式」——这是会话事实，藏起来会让分享出去的
+回放看着像真实运行；但倍速和退出会被禁用，因为服务端的 `PATCH` 是 owner 专属。
+
+**`ChatView` 已经自带这一整套**——用它打开回放会话，状态条、倍速、退出、冲突卡片都在，
+不用自己接。下面这些 API 是给自建 UI 用的。
+
+**注册即接管**：底层的 `replayMismatch` 只交给最先注册的处理器。调用 `useReplay()`（或用
+`ChatView`）就意味着由它接管冲突；两者都不用则维持 SDK 默认行为——静默转为真实运行。
+
+回放状态本身住在 `SessionState.replay` 里，本 hook 只是它的 React 绑定。非 React 宿主
+（Vue、Svelte、自建 UI）直接订阅快照即可，不需要这个包，用法见
+[agent-client 的会话回放章节](../agent-client/README.md#会话回放演示--彩排)。
+
 ## ChatView
 
 完整聊天界面：消息列表（Markdown、代码高亮、工具调用、提问卡片）+ 输入框 + 连接状态条 + 登录引导。
@@ -79,6 +140,7 @@ await session?.send("你好")
   onSessionCreated={(id) => ...}       // 自动创建的会话 id 交还调用方
   onSessionReady={(session) => ...}    // 会话实例就绪（页面协作高级用法）
   commands={{ "map.highlight": (data) => map.highlight(data) }}  // 智能体 → 页面指令
+  onFollowupInteraction={(event) => analytics.capture(event.type, event)} // 厂商无关交互回调
   placeholder="输入消息..."
   classNames={{ root: "...", banner: "...", messages: "...", input: "..." }}  // ChatViewClassNames
   renderers={{ toolCall: (info) => <MyToolCard info={info} /> }}              // ChatViewRenderers
@@ -88,6 +150,9 @@ await session?.send("你好")
 
 全部 props 见 `ChatViewProps`。样式说明：
 
+`onFollowupInteraction` 使用 `FollowupInteractionEvent`，覆盖下一步建议展示/采纳、成果展示/打开/下载以及结果评分。SDK 不内置 PostHog 等分析厂商；宿主回调抛错也不会中断用户点击或下载。
+文件成果以文件名为文本的标准下载链接展示；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。
@@ -96,6 +161,95 @@ await session?.send("你好")
 - `renderers.toolCall` 返回 `null` 时回落到默认工具卡片。
 - **内边距按容器宽度伸缩**，嵌进窄侧栏（300–400px）时会自动收窄，不看浏览器视口。代价是聊天容器需要有确定宽度——放在 flex/grid 里被拉伸，或显式给宽度都可以；放进 `width: fit-content`、`inline-flex` 这类由内容决定宽度的父容器会塌缩。
 
+## 纯 LLM 模式（不建会话）
+
+有些应用只要「一问一答」——分类、改写、总结，不需要智能体、不需要会话、也不需要用户登录
+Blade。这时把 `ChatView` 切到 `mode="llm"`，或者直接用下层的 `LlmChat`，界面完全一样：
+
+```tsx
+<ChatView />                                                  // 默认：智能体模式，行为不变
+<ChatView mode="llm" llm={{ baseURL: "/api/llm", model }} />   // 切成纯 LLM
+<LlmChat baseURL="/api/llm" model={model} />                   // 或者直接用（LlmChatProps）
+<AgentChat sessionId={id} />                                   // 智能体那侧同样可以直接用（AgentChatProps）
+```
+
+**协议就是 OpenAI 的**：`POST {baseURL}/chat/completions`，`stream: true`，读
+`choices[0].delta`。任何 OpenAI 兼容实现（Blade 网关、vLLM、Ollama、OpenAI 本身、你自己的
+透传代理）都能直接接，不用为这个组件专门写后端。
+
+**密钥默认不进浏览器**：把 `baseURL` 指向自己后端的一个路径，后端补上 `Authorization` 再原样
+转发即可（协议是标准的，这个代理就是纯转发）。确实要前端直连时才传 `apiKey`——只适合受控内网、
+演示，或密钥本身就属于当前用户的场景。
+
+**模型服务地址和模型名别写死**，用 `client.models.list()` 拿，各部署端口不一样：
+
+```tsx
+const { baseUrl, defaultServiceModel, models } = await client.models.list()
+
+// 后端透传（推荐）：baseURL 指向自己的路径，模型名仍然要用 defaultServiceModel
+<ChatView mode="llm" llm={{ baseURL: "/api/llm", model: defaultServiceModel }} />
+
+// 浏览器直连：仅当 baseUrl 对浏览器也可达时
+<ChatView mode="llm" llm={{ baseURL: baseUrl, model: defaultServiceModel, apiKey }} />
+
+// 让用户选模型时，过滤掉不在这个服务上的
+models.filter((m) => m.serviceModelId)
+```
+
+**模型名要用 `defaultServiceModel` / `serviceModelId`，不是 `default` / `id`。** 后者是平台内部
+标识，平台接了多个模型服务时形如 `provider-xxx::deepseek-v4-flash`，发给模型服务只会得到
+「模型不存在」。`baseUrl` 同理是服务端视角的地址，平台常配成 `http://127.0.0.1:30000/v1`，
+那是给自己后端转发用的，不能直接丢给浏览器。
+
+**工具调用走 OpenAI 标准的多轮流程**，不需要任何私有扩展：声明 `tools`，在 `onToolCall`
+（收到 `LlmToolCall`）里执行——通常就是调你自己应用的同源接口——返回值会作为
+`role: "tool"` 消息回喂给模型，直到它给出最终回答或达到 `maxToolRounds`（默认 4）。
+每一轮工具调用都会渲染成和智能体模式一样的工具卡片。
+
+```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()
+  }}
+  onReady={(handle) => setChat(handle)}   // LlmChatHandle：insertText / send / reset
+/>
+```
+
+### 让用户自己改模型服务地址
+
+传 `advanced` 就在输入框上方多一行「高级设置」（默认收起），用户可以改模型服务地址和模型名；
+改过之后会显示「已自定义」，也能一键恢复默认。不传就一个节点都不渲染。
+
+```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 }} />
+```
+
+`LlmAdvancedSettings` 可细调：`baseURL` / `model` 各自能不能改（默认都能）、`apiKey` 要不要
+出现（**默认不出现**，打开意味着密钥存在浏览器里，只适合受控场景）、`storage` 是记住选择
+（`local`，默认）还是只在本次有效（`memory`）、`storageKey` 自定义存储键。用户改了会回调
+`onOverrideChange`（`LlmOverride`），宿主想自己也记一份时用。
+
+其余可选项见 `LlmChatOptions`：`headers`、`historyTurns`（默认 12 轮）、`temperature`、
+`extraBody`、`fetchImpl`。只要状态机、界面自己写的，用 `useLlmChat`（返回
+`UseLlmChatResult`：`messages` / `isStreaming` / `error` / `send` / `stop` / `reset`）。
+
+纯 LLM 模式不做会话持久化、文件上传、提问卡片、记忆和检查点——那些是智能体协议的能力，
+需要就用默认模式。
+
 ## MarkdownContent
 
 单独渲染一段智能体消息 Markdown（含代码复制按钮、XSS 消毒；HTML 经 sanitize 白名单处理，不接受任意 raw HTML）：
@@ -104,8 +258,6 @@ await session?.send("你好")
 <MarkdownContent content={markdownText} />
 ```
 
-传了 `sessionId` 才会把智能体产出文件的 `MEDIA:` 行折叠成下载卡片（下载要用它）。`ChatView` 内部已经传好，只有单独用 `MarkdownContent` 时需要自己给：
-
 ```tsx
 <MarkdownContent sessionId={sessionId}>{markdownText}</MarkdownContent>
 ```
@@ -153,4 +305,4 @@ blade-chat { --primary: 262 83% 58%; height: 640px; }
 
 为方便单包引入，本包 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`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`ToolCallRenderer`、`MarkdownContent`、`MarkdownContentProps`。
+本包自有声明：`BladeProvider`、`BladeProviderProps`、`useBladeClient`、`useAgentSession`、`UseAgentSessionOptions`、`UseAgentSessionResult`、`useReplay`、`UseReplayResult`、`ReplayMismatch`、`ReplayBar`、`ReplayBarProps`、`ReplayMismatchPrompt`、`ReplayMismatchPromptProps`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`FollowupInteractionEvent`、`ToolCallRenderer`、`MarkdownContent`、`MarkdownContentProps`。

package/dist/components/AgentChat.d.ts

@@ -0,0 +1,21 @@
+import type { AgentSession, CreateSessionRequest } from "@blade-hq/agent-client";
+import { type ChatPresentationProps } from "./ChatSurface";
+import type { FollowupInteractionEvent } from "./PostChatFollowupBlock";
+export interface AgentChatProps extends ChatPresentationProps {
+    /** follow-up、成果和评分交互；SDK 不绑定任何分析厂商。 */
+    onFollowupInteraction?: (event: FollowupInteractionEvent) => void;
+    /** 连接既有会话；不传则按 createOptions 自动新建。 */
+    sessionId?: string;
+    createOptions?: CreateSessionRequest;
+    /** 自动创建出的 sessionId 通过此回调交还调用方持有。 */
+    onSessionCreated?: (sessionId: string) => void;
+    /** 会话连接完成后回调（页面协作场景拿 AgentSession 实例用）。 */
+    onSessionReady?: (session: AgentSession) => void;
+    /** 智能体下发给宿主页面的指令处理器（action → handler）。 */
+    commands?: Record<string, (data: unknown) => void>;
+}
+/**
+ * 智能体模式的聊天界面：连接（或新建）一个 Blade 会话，渲染消息流与输入框。
+ * 状态全部来自 useAgentSession，不依赖任何全局 store。
+ */
+export declare function AgentChat(props: AgentChatProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/AssistantTurnBlock.d.ts

@@ -7,7 +7,7 @@ interface Props {
     onAnswer?: (answer: string, toolCallId: string, answerData: AskUserAnswerData) => void;
     sessionStatus?: string;
     toolCallRenderer?: ToolCallRenderer;
-    /** 传给 Markdown 渲染，用于把 MEDIA 行折叠成文件下载卡片。 */
+    /** 会话 id；传给 Markdown 渲染的统一上下文。 */
     sessionId?: string;
 }
 /**

package/dist/components/ChatSurface.d.ts

@@ -0,0 +1,68 @@
+import type { AskUserAnswerData, ChatMessage, ConnectionStatus, PostChatFollowup } from "@blade-hq/agent-client";
+import type { ReactNode } from "react";
+import type { ToolCallRenderer } from "./ToolCallBlock";
+import type { FollowupInteractionEvent } from "./PostChatFollowupBlock";
+import type { ResultFeedback } from "@blade-hq/agent-client";
+export interface ChatViewClassNames {
+    root?: string;
+    banner?: string;
+    messageList?: string;
+    chatInput?: string;
+}
+export interface ChatViewRenderers {
+    /** 自定义工具调用渲染；返回 null 走默认渲染。 */
+    toolCall?: ToolCallRenderer;
+}
+export interface ChatViewSlots {
+    /** 消息列表上方的自定义区域。 */
+    header?: ReactNode;
+    /** 无消息时的空状态。 */
+    emptyState?: ReactNode;
+    /** 输入框下方的自定义区域。 */
+    footer?: ReactNode;
+}
+/** 两种模式共用的外观属性。 */
+export interface ChatPresentationProps {
+    classNames?: ChatViewClassNames;
+    renderers?: ChatViewRenderers;
+    slots?: ChatViewSlots;
+    placeholder?: string;
+    /** 配色主题，默认浅色。宿主已经在祖先元素上写了 data-theme 时不用传。 */
+    theme?: "light" | "dark";
+}
+/** 主题落到聊天根节点上：深色变量挂在 [data-theme="dark"] 上，由它继承给整棵子树。 */
+export declare function themeAttr(theme: ChatPresentationProps["theme"]): "dark" | undefined;
+interface ChatSurfaceProps extends ChatPresentationProps {
+    /** follow-up、成果和评分交互；SDK 不绑定任何分析厂商。 */
+    onFollowupInteraction?: (event: FollowupInteractionEvent) => void;
+    connection: ConnectionStatus;
+    errorMessage: string | null;
+    messages: ChatMessage[];
+    postChatFollowup?: PostChatFollowup | null;
+    isStreaming: boolean;
+    isStopping: boolean;
+    inputText: string;
+    onInputChange: (value: string) => void;
+    onSuggestion?: (value: string) => void;
+    onSend: (text: string) => Promise<boolean>;
+    onStop: () => void;
+    sessionStatus?: string;
+    askAnswers?: Record<string, AskUserAnswerData>;
+    onAnswer?: (answer: string, toolCallId: string, answerData: AskUserAnswerData) => void;
+    sessionId?: string;
+    isViewer?: boolean;
+    resultFeedbackByEntry?: ReadonlyMap<string, ResultFeedback>;
+    onResultFeedbackSaved?: (feedback: ResultFeedback) => void;
+    /** 输入框上方的内部区域（纯 LLM 模式的高级设置用）。不传时不渲染任何节点。 */
+    beforeInput?: ReactNode;
+    /** 连接状态条下方的横幅（回放模式条用）。不传时不渲染任何节点。 */
+    banner?: ReactNode;
+}
+/**
+ * 消息流 + 输入框：智能体模式与纯 LLM 模式共用同一套外观，差别只在谁喂数据。
+ *
+ * 这里的 DOM 结构受 tests/chat-view-compat.test.tsx 的快照保护——接入方拿
+ * .blade-chat-* 类名写了自己的样式，结构一动他们的页面就歪。
+ */
+export declare function ChatSurface({ theme, classNames, renderers, slots, placeholder, connection, errorMessage, messages, postChatFollowup, isStreaming, isStopping, inputText, onInputChange, onSuggestion, onSend, onStop, sessionStatus, askAnswers, onAnswer, sessionId, isViewer, resultFeedbackByEntry, onResultFeedbackSaved, onFollowupInteraction, beforeInput, banner, }: ChatSurfaceProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ChatView.d.ts

@@ -1,43 +1,24 @@
-import type { AgentSession, CreateSessionRequest } from "@blade-hq/agent-client";
-import { type ReactNode } from "react";
-import type { ToolCallRenderer } from "./ToolCallBlock";
-export interface ChatViewClassNames {
-    root?: string;
-    banner?: string;
-    messageList?: string;
-    chatInput?: string;
-}
-export interface ChatViewRenderers {
-    /** 自定义工具调用渲染；返回 null 走默认渲染。 */
-    toolCall?: ToolCallRenderer;
-}
-export interface ChatViewSlots {
-    /** 消息列表上方的自定义区域。 */
-    header?: ReactNode;
-    /** 无消息时的空状态。 */
-    emptyState?: ReactNode;
-    /** 输入框下方的自定义区域。 */
-    footer?: ReactNode;
-}
-export interface ChatViewProps {
-    /** 连接既有会话；不传则按 createOptions 自动新建。 */
-    sessionId?: string;
-    createOptions?: CreateSessionRequest;
-    /** 自动创建出的 sessionId 通过此回调交还调用方持有。 */
-    onSessionCreated?: (sessionId: string) => void;
-    /** 会话连接完成后回调（页面协作场景拿 AgentSession 实例用）。 */
-    onSessionReady?: (session: AgentSession) => void;
-    /** 智能体下发给宿主页面的指令处理器（action → handler）。 */
-    commands?: Record<string, (data: unknown) => void>;
-    classNames?: ChatViewClassNames;
-    renderers?: ChatViewRenderers;
-    slots?: ChatViewSlots;
-    placeholder?: string;
-    /** 配色主题，默认浅色。宿主已经在祖先元素上写了 data-theme 时不用传。 */
-    theme?: "light" | "dark";
+import { type AgentChatProps } from "./AgentChat";
+import { type LlmChatHandle } from "./LlmChat";
+import type { LlmAdvancedSettings, LlmOverride } from "./LlmAdvancedSettings";
+import type { LlmChatOptions } from "../hooks/use-llm-chat";
+export type { ChatViewClassNames, ChatViewRenderers, ChatViewSlots, } from "./ChatSurface";
+export type { FollowupInteractionEvent } from "./PostChatFollowupBlock";
+export interface ChatViewProps extends AgentChatProps {
+    /** 挂哪个下层组件。默认 `agent`——不传就是接 Blade 智能体会话的原有行为。 */
+    mode?: "agent" | "llm";
+    /** `mode="llm"` 时的模型服务配置；`advanced` 打开输入框上方的「高级设置」。 */
+    llm?: LlmChatOptions & {
+        advanced?: boolean | LlmAdvancedSettings;
+        onOverrideChange?: (override: LlmOverride) => void;
+    };
+    /** `mode="llm"` 时拿到操作句柄；智能体模式请用 `onSessionReady`。 */
+    onLlmReady?: (handle: LlmChatHandle) => void;
 }
 /**
- * 开箱即用的聊天界面：连接（或新建）一个会话，渲染消息流与输入框。
- * 状态全部来自 useAgentSession，不依赖任何全局 store。
+ * 聊天界面。默认接 Blade 智能体会话，`mode="llm"` 时改接标准 OpenAI 对话接口。
+ *
+ * 这一层只做分流：两种模式各自是独立组件，已经确定要哪一种的可以直接用
+ * `<AgentChat>` 或 `<LlmChat>`。
  */
 export declare function ChatView(props: ChatViewProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ConnectionBanner.d.ts

@@ -3,6 +3,6 @@ interface Props {
     connection: ConnectionStatus;
     className?: string;
 }
-/** 连接状态提示条：数据来自 SessionState.connection，正常连接时不渲染。 */
+/** 连接状态提示条：短暂断线静默，超过容错时间后再逐级提示。 */
 export declare function ConnectionBanner({ connection, className }: Props): import("react/jsx-runtime").JSX.Element | null;
 export {};

package/dist/components/LlmAdvancedSettings.d.ts

@@ -0,0 +1,40 @@
+/** 纯 LLM 模式的高级设置：让用户自己改模型服务地址。 */
+export interface LlmAdvancedSettings {
+    /** 允许改模型服务地址，默认允许。 */
+    baseURL?: boolean;
+    /** 允许改模型名，默认允许。 */
+    model?: boolean;
+    /**
+     * 允许在界面上填密钥，默认**不允许**。
+     * 打开意味着密钥存在浏览器里，只适合受控内网、演示，或密钥本身就属于当前用户的场景。
+     */
+    apiKey?: boolean;
+    /** 覆盖值存哪：`local` 记住用户的选择（默认），`memory` 只在本次会话有效。 */
+    storage?: "local" | "memory";
+    /** localStorage 的键，默认按组件拿到的 baseURL 生成。 */
+    storageKey?: string;
+}
+export interface LlmOverride {
+    baseURL?: string;
+    model?: string;
+    apiKey?: string;
+}
+export declare function normalizeAdvanced(value: boolean | LlmAdvancedSettings | undefined): Required<Pick<LlmAdvancedSettings, "baseURL" | "model" | "apiKey" | "storage">> | null;
+export declare function readOverride(settings: boolean | LlmAdvancedSettings | undefined, baseURL: string): LlmOverride;
+declare function writeOverride(settings: boolean | LlmAdvancedSettings | undefined, baseURL: string, override: LlmOverride): void;
+interface Props {
+    settings: boolean | LlmAdvancedSettings;
+    /** 组件拿到的默认值，用来做占位提示与"恢复默认" */
+    defaults: {
+        baseURL: string;
+        model: string;
+    };
+    override: LlmOverride;
+    onChange: (next: LlmOverride) => void;
+}
+/**
+ * 输入框上方的一行「高级设置」：默认收起，展开后可以改模型服务地址与模型。
+ * 只有调用方显式打开才渲染——不传 advanced 时这里一个节点都不会出现。
+ */
+export declare function LlmAdvancedSettingsBar({ settings, defaults, override, onChange }: Props): import("react/jsx-runtime").JSX.Element | null;
+export { writeOverride };

package/dist/components/LlmChat.d.ts

@@ -0,0 +1,29 @@
+import { type LlmChatOptions } from "../hooks/use-llm-chat";
+import { type ChatPresentationProps } from "./ChatSurface";
+import { type LlmAdvancedSettings, type LlmOverride } from "./LlmAdvancedSettings";
+/** 纯 LLM 模式的操作句柄，对应智能体模式的 session.insertText() / send()。 */
+export interface LlmChatHandle {
+    /** 把文本放进输入框交给用户确认，不直接发出去。 */
+    insertText: (text: string) => void;
+    send: (text: string) => Promise<boolean>;
+    /** 清空这段对话。 */
+    reset: () => void;
+}
+export interface LlmChatProps extends LlmChatOptions, ChatPresentationProps {
+    /** 拿到操作句柄：业务界面把选中的数据塞进输入框，或直接发一句。 */
+    onReady?: (handle: LlmChatHandle) => void;
+    /**
+     * 打开输入框上方的「高级设置」，让用户自己改模型服务地址（默认还能改模型名）。
+     * 不传就一个节点都不渲染。传 `true` 用默认配置，或用对象细调。
+     */
+    advanced?: boolean | LlmAdvancedSettings;
+    /** 用户改了覆盖值时回调，方便宿主自己也记一份。 */
+    onOverrideChange?: (override: LlmOverride) => void;
+}
+/**
+ * 纯 LLM 模式的聊天界面：不建会话、不连实时通道、也不要求登录 Blade，
+ * 只按 **OpenAI Chat Completions** 标准协议跟模型服务一问一答。
+ *
+ * 默认形态是把 `baseURL` 指向自己后端的透传路径，由后端补密钥再转发，浏览器不持有密钥。
+ */
+export declare function LlmChat({ classNames, renderers, slots, placeholder, theme, onReady, advanced, onOverrideChange, ...options }: LlmChatProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/MarkdownContent.d.ts

@@ -3,14 +3,11 @@ export interface MarkdownContentProps {
     className?: string;
     /** 流式渲染传 "streaming"，历史静态内容默认 "static"。 */
     mode?: "streaming" | "static";
-    /**
-     * 会话 id。传了才会把 `MEDIA:` 行折叠成文件下载卡片——下载要用它。
-     * 不要给用户消息传：用户自己在输入框打一行 `MEDIA:` 不该被当成平台产物。
-     */
+    /** 会话 id；保留给聊天组件统一透传上下文。 */
     sessionId?: string;
 }
 /**
- * SDK 版 Markdown 渲染：附带代码块复制按钮、智能体产出文件的下载卡片；
- * 相比第一方版本去掉了 mermaid、外链确认弹窗与文件预览。
+ * SDK 版 Markdown 渲染：附带代码块复制按钮；相比第一方版本去掉了
+ * mermaid、外链确认弹窗与文件预览。
  */
 export declare function MarkdownContent({ children, className, mode, sessionId }: MarkdownContentProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/MessageList.d.ts

@@ -1,8 +1,11 @@
-import type { AskUserAnswerData, ChatMessage } from "@blade-hq/agent-client";
+import type { AskUserAnswerData, ChatMessage, PostChatFollowup, ResultFeedback } from "@blade-hq/agent-client";
 import { type ReactNode } from "react";
+import { type FollowupInteractionEvent } from "./PostChatFollowupBlock";
 import type { ToolCallRenderer } from "./ToolCallBlock";
 interface Props {
     messages: ChatMessage[];
+    postChatFollowup?: PostChatFollowup | null;
+    onSuggestion?: (value: string) => void;
     isStreaming: boolean;
     sessionStatus?: string;
     askAnswers?: Record<string, AskUserAnswerData>;
@@ -10,12 +13,16 @@ interface Props {
     toolCallRenderer?: ToolCallRenderer;
     emptyState?: ReactNode;
     className?: string;
-    /** 传给助手消息的 Markdown 渲染，用于把 MEDIA 行折叠成文件下载卡片。 */
+    /** 会话 id；传给助手消息的统一上下文。 */
     sessionId?: string;
+    isViewer?: boolean;
+    onFollowupInteraction?: (event: FollowupInteractionEvent) => void;
+    resultFeedbackByEntry?: ReadonlyMap<string, ResultFeedback>;
+    onResultFeedbackSaved?: (feedback: ResultFeedback) => void;
 }
 /**
  * 消息列表：use-stick-to-bottom 自动滚动 + 按轮次分组渲染。
  * 相比第一方版本去掉了轮次导航栏、吸顶状态条与规划摘要卡片。
  */
-export declare function MessageList({ messages, isStreaming, sessionStatus, askAnswers, onAnswer, toolCallRenderer, emptyState, className, sessionId, }: Props): import("react/jsx-runtime").JSX.Element;
+export declare function MessageList({ messages, postChatFollowup, onSuggestion, isStreaming, sessionStatus, askAnswers, onAnswer, toolCallRenderer, emptyState, className, sessionId, isViewer, onFollowupInteraction, resultFeedbackByEntry, onResultFeedbackSaved, }: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/PostChatFollowupBlock.d.ts

@@ -0,0 +1,59 @@
+import type { FinalArtifact, PostChatFollowup, ResultFeedback as SavedResultFeedback, ResultFeedbackReason } from "@blade-hq/agent-client";
+export type FollowupInteractionEvent = {
+    type: "suggestions_shown";
+    sessionId?: string;
+    assistantEntryId: string;
+    count: number;
+} | {
+    type: "suggestion_adopted";
+    sessionId?: string;
+    assistantEntryId: string;
+    suggestionIndex: number;
+} | {
+    type: "artifact_shown";
+    sessionId?: string;
+    assistantEntryId: string;
+    artifactIndex: number;
+    artifactKind: FinalArtifact["kind"];
+} | {
+    type: "artifact_opened";
+    sessionId?: string;
+    assistantEntryId: string;
+    artifactIndex: number;
+    artifactKind: FinalArtifact["kind"];
+} | {
+    type: "artifact_download_started";
+    sessionId?: string;
+    assistantEntryId: string;
+    artifactIndex: number;
+    artifactKind: "file";
+} | {
+    type: "artifact_download_succeeded";
+    sessionId?: string;
+    assistantEntryId: string;
+    artifactIndex: number;
+    artifactKind: "file";
+} | {
+    type: "result_feedback_shown";
+    sessionId?: string;
+    assistantEntryId: string;
+} | {
+    type: "result_feedback_submitted";
+    sessionId?: string;
+    assistantEntryId: string;
+    helpful: boolean;
+    reason: ResultFeedbackReason | null;
+    updatedAt: string;
+};
+export declare function HistoricalResultFeedback({ feedback }: {
+    feedback: SavedResultFeedback;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function PostChatFollowupBlock({ followup, sessionId, onSuggestion, isViewer, onInteraction, savedFeedback, onFeedbackSaved, }: {
+    followup: PostChatFollowup;
+    sessionId?: string;
+    onSuggestion?: (value: string) => void;
+    isViewer?: boolean;
+    onInteraction?: (event: FollowupInteractionEvent) => void;
+    savedFeedback?: SavedResultFeedback;
+    onFeedbackSaved?: (feedback: SavedResultFeedback) => void;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/ReplayBar.d.ts

@@ -0,0 +1,13 @@
+import type { ReplaySpeed } from "@blade-hq/agent-client";
+export interface ReplayBarProps {
+    /** 非回放会话传 false 时整条不渲染。 */
+    isReplay: boolean;
+    speed: ReplaySpeed;
+    onSpeedChange: (speed: ReplaySpeed) => void;
+    onExit: () => void;
+    /** 传 useReplay().canControl。只读身份下仍然显示"在回放"，但操作按钮禁用。 */
+    canControl?: boolean;
+    className?: string;
+}
+/** 回放会话的顶部状态条：说明当前在回放、切换倍速、随时退出回放。 */
+export declare function ReplayBar({ isReplay, speed, onSpeedChange, onExit, canControl, className, }: ReplayBarProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/ReplayMismatchPrompt.d.ts

@@ -0,0 +1,8 @@
+import type { ReplayMismatch } from "../hooks/use-replay";
+export interface ReplayMismatchPromptProps {
+    /** 来自 useReplay().mismatch；为 null 时不渲染。 */
+    mismatch: ReplayMismatch | null;
+    className?: string;
+}
+/** 回放中输入和录制内容对不上时的选择卡：按录制继续，还是从这里真跑。 */
+export declare function ReplayMismatchPrompt({ mismatch, className }: ReplayMismatchPromptProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/embed/entry.d.ts

@@ -24,6 +24,8 @@ declare const BladeAgent: {
     SessionHub: typeof agentClient.SessionHub;
     SessionSetupError: typeof agentClient.SessionSetupError;
     createInitialSessionState: typeof agentClient.createInitialSessionState;
+    reconcileOptimisticUserTurns: typeof agentClient.reconcileOptimisticUserTurns;
+    toReplaySnapshot: typeof agentClient.toReplaySnapshot;
     connectEmbedded: typeof agentClient.connectEmbedded;
     isCommandEnvelope: typeof agentClient.isCommandEnvelope;
     isInboundEnvelope: typeof agentClient.isInboundEnvelope;
@@ -38,6 +40,8 @@ declare const BladeAgent: {
     isHiddenInternalMessage: typeof agentClient.isHiddenInternalMessage;
     normalizeMessageContent: typeof agentClient.normalizeMessageContent;
     transformSlashCommand: typeof agentClient.transformSlashCommand;
+    latestPostChatFollowup: typeof agentClient.latestPostChatFollowup;
+    DEFAULT_REPLAY_SPEED: agentClient.ReplaySpeed;
     SessionInfo: import("arktype/internal/variants/object.ts").ObjectType<{
         id: string;
         intent: string;
@@ -82,6 +86,7 @@ declare const BladeAgent: {
         number: string;
     }, {}>;
     TaskStatus: import("arktype/internal/variants/string.ts").StringType<"done" | "failed" | "in_progress" | "pending" | "skipped", {}>;
+    acceptedPostChatFollowupCompletesLatestRun: typeof agentClient.acceptedPostChatFollowupCompletesLatestRun;
     ClientProjectionBuilder: typeof agentClient.ClientProjectionBuilder;
     createSocket: typeof agentClient.createSocket;
     getChat: typeof getChat;