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

package/README.md

@@ -68,6 +68,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、代码高亮、工具调用、提问卡片）+ 输入框 + 连接状态条 + 登录引导。
@@ -96,6 +156,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,7 +253,7 @@ await session?.send("你好")
 <MarkdownContent content={markdownText} />
 ```
 
-传了 `sessionId` 才会把智能体产出文件的 `MEDIA:` 行折叠成以文件名为文本的下载链接（下载要用它）。`ChatView` 内部已经传好，只有单独用 `MarkdownContent` 时需要自己给：
+传了 `sessionId` 才会把智能体产出文件的 `MEDIA:` 行折叠成下载卡片（下载要用它）。`ChatView` 内部已经传好，只有单独用 `MarkdownContent` 时需要自己给：
 
 ```tsx
 <MarkdownContent sessionId={sessionId}>{markdownText}</MarkdownContent>
@@ -153,4 +302,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`、`ToolCallRenderer`、`MarkdownContent`、`MarkdownContentProps`。

package/dist/components/AgentChat.d.ts

@@ -0,0 +1,18 @@
+import type { AgentSession, CreateSessionRequest } from "@blade-hq/agent-client";
+import { type ChatPresentationProps } from "./ChatSurface";
+export interface AgentChatProps extends ChatPresentationProps {
+    /** 连接既有会话；不传则按 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 行折叠成文件下载链接。 */
+    /** 传给 Markdown 渲染，用于把 MEDIA 行折叠成文件下载卡片。 */
     sessionId?: string;
 }
 /**

package/dist/components/ChatSurface.d.ts

@@ -0,0 +1,59 @@
+import type { AskUserAnswerData, ChatMessage, ConnectionStatus } 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 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 {
+    connection: ConnectionStatus;
+    errorMessage: string | null;
+    messages: ChatMessage[];
+    isStreaming: boolean;
+    isStopping: boolean;
+    inputText: string;
+    onInputChange: (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;
+    /** 输入框上方的内部区域（纯 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, isStreaming, isStopping, inputText, onInputChange, onSend, onStop, sessionStatus, askAnswers, onAnswer, sessionId, beforeInput, banner, }: ChatSurfaceProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ChatView.d.ts

@@ -1,43 +1,23 @@
-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 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/FileCard.d.ts

@@ -8,9 +8,9 @@ export type FileCardProps = ComponentPropsWithRef<"span"> & ExtraProps & {
     sessionId?: string;
 };
 /**
- * 智能体产出文件的下载链接（由 MEDIA 行折叠而来）。
+ * 智能体产出文件的下载卡片（由 MEDIA 行折叠而来）。
  *
- * href 让 Vue/纯 HTML 宿主看到标准的「文件名→URL」语义；普通点击仍交给
- * downloadFile，避免跨域时 download 属性被忽略，也确保使用点击时的最新 token。
+ * 整张卡片只有一个动作：下载。第一方界面点卡片是「在右侧预览」，那依赖 app 的 artifact
+ * 面板，SDK 里没有这块，所以不摆预览入口也不写预览文案——UI 不能承诺不存在的能力。
  */
 export declare function FileCard({ node, "data-path": pathAttribute, "data-name": nameAttribute, dataPath, dataName, sessionId, children, className, ...props }: FileCardProps): import("react/jsx-runtime").JSX.Element;

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

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

package/dist/components/MessageList.d.ts

@@ -10,7 +10,7 @@ interface Props {
     toolCallRenderer?: ToolCallRenderer;
     emptyState?: ReactNode;
     className?: string;
-    /** 传给助手消息的 Markdown 渲染，用于把 MEDIA 行折叠成文件下载链接。 */
+    /** 传给助手消息的 Markdown 渲染，用于把 MEDIA 行折叠成文件下载卡片。 */
     sessionId?: string;
 }
 /**

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

@@ -18,15 +18,13 @@ declare function getChat(element: Element | null): Promise<AgentSession>;
 declare const BladeAgent: {
     BladeClient: typeof agentClient.BladeClient;
     BladeApiError: typeof agentClient.BladeApiError;
-    EMPTY_PLATFORM_ENDPOINTS: agentClient.PlatformEndpoints;
-    loadPlatformEndpoints: typeof agentClient.loadPlatformEndpoints;
-    resolveServiceUrl: typeof agentClient.resolveServiceUrl;
     SDK_NAME: "agent-client";
     SDK_VERSION: string;
     AgentSession: typeof AgentSession;
     SessionHub: typeof agentClient.SessionHub;
     SessionSetupError: typeof agentClient.SessionSetupError;
     createInitialSessionState: typeof agentClient.createInitialSessionState;
+    toReplaySnapshot: typeof agentClient.toReplaySnapshot;
     connectEmbedded: typeof agentClient.connectEmbedded;
     isCommandEnvelope: typeof agentClient.isCommandEnvelope;
     isInboundEnvelope: typeof agentClient.isInboundEnvelope;
@@ -41,6 +39,7 @@ declare const BladeAgent: {
     isHiddenInternalMessage: typeof agentClient.isHiddenInternalMessage;
     normalizeMessageContent: typeof agentClient.normalizeMessageContent;
     transformSlashCommand: typeof agentClient.transformSlashCommand;
+    DEFAULT_REPLAY_SPEED: agentClient.ReplaySpeed;
     SessionInfo: import("arktype/internal/variants/object.ts").ObjectType<{
         id: string;
         intent: string;

package/dist/hooks/use-llm-chat.d.ts

@@ -0,0 +1,57 @@
+import type { ChatMessage } from "@blade-hq/agent-client";
+/** OpenAI 标准的工具声明，原样发给模型服务。 */
+export interface ChatCompletionTool {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+export interface LlmToolCall {
+    id: string;
+    name: string;
+    /** 模型生成的 JSON 字符串，是不可信输入，用之前自己校验。 */
+    arguments: string;
+}
+export interface LlmChatOptions {
+    /** OpenAI 兼容根地址，如 `/api/llm`（自己后端的透传路径）或 `http://host:30000/v1`。 */
+    baseURL: string;
+    model: string;
+    /**
+     * 直连模型服务时才需要。默认形态是让 `baseURL` 指向自己的后端，由后端补密钥转发，
+     * 浏览器不持有密钥。
+     */
+    apiKey?: string;
+    headers?: Record<string, string>;
+    /** 系统提示词，合成到消息最前面。 */
+    system?: string;
+    /** 每次带上最近多少轮，默认 12。越长越贵，也越容易超上下文。 */
+    historyTurns?: number;
+    temperature?: number;
+    /** 透传给模型服务的额外字段。 */
+    extraBody?: Record<string, unknown>;
+    tools?: ChatCompletionTool[];
+    /** 执行模型请求的工具，返回值会被序列化后回喂给模型。 */
+    onToolCall?: (call: LlmToolCall) => Promise<unknown>;
+    /** 工具最多来回几轮，默认 4，防止模型绕圈烧 token。 */
+    maxToolRounds?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface UseLlmChatResult {
+    messages: ChatMessage[];
+    isStreaming: boolean;
+    /** 出错原因；下一次发送会清掉。 */
+    error: string | null;
+    send: (text: string) => Promise<boolean>;
+    stop: () => void;
+    reset: () => void;
+}
+/**
+ * 纯 LLM 对话的状态机，协议就是 **OpenAI Chat Completions**——任何兼容实现都能直接接，
+ * 不需要为这个组件专门写后端。
+ *
+ * 工具调用走 OpenAI 标准的多轮流程：模型返回 tool_calls → 调 onToolCall 执行 →
+ * 结果作为 role:"tool" 消息回喂 → 再请求一次。
+ */
+export declare function useLlmChat(options: LlmChatOptions): UseLlmChatResult;

package/dist/hooks/use-replay.d.ts

@@ -0,0 +1,50 @@
+import type { AgentSession, ReplaySpeed } from "@blade-hq/agent-client";
+/** 回放中用户说的话和录制内容对不上，需要当场决定往哪走。 */
+export interface ReplayMismatch {
+    /** 用户这次实际发出的内容。 */
+    actualMessage: string;
+    /** 源会话里录制的下一句。 */
+    expectedMessage: string;
+    /** keep_replay：按录制内容继续；continue_replay：从这里转为真实运行。 */
+    resolve: (decision: "keep_replay" | "continue_replay") => void;
+}
+export interface UseReplayResult {
+    /** 当前会话是不是正在回放（转自主运行后为 false）。 */
+    isReplay: boolean;
+    /** 当前播放倍速，非回放会话固定为 1。 */
+    speed: ReplaySpeed;
+    setSpeed: (speed: ReplaySpeed) => Promise<void>;
+    /** 退出回放，之后的对话交给真实模型运行。 */
+    exitToAutonomous: () => Promise<void>;
+    /** 待决策的输入冲突；处理完自动清空。 */
+    mismatch: ReplayMismatch | null;
+    /** 能不能改回放（改回放是 owner 专属）。只读身份下仍然显示"在回放"，但不能操作。 */
+    canControl: boolean;
+    /** 当前会话能否作为回放来源（并行子智能体等场景不支持）。 */
+    canReplay: boolean;
+    /** canReplay 为 false 时的原因，可直接展示。 */
+    unsupportedReason: string | null;
+    /** 从当前会话派生一个回放会话，返回新会话 id。 */
+    startReplay: (speed?: ReplaySpeed) => Promise<string>;
+    isStarting: boolean;
+    /** 最近一次回放操作失败的原因。 */
+    error: Error | null;
+}
+/**
+ * 会话回放（演示 / 彩排模式）。
+ *
+ * 回放会话不会自动播放：用户照常发消息，只要这句和源会话录制的下一句意图一致，
+ * 服务端就按倍速重放当时的回复和工具调用，完全不调用模型；对不上就抛出
+ * `mismatch` 交给界面决定。
+ *
+ * 同一个 hook 覆盖两种身份——传入的会话既可能是回放会话（isReplay / setSpeed /
+ * exitToAutonomous / mismatch），也可能是准备被回放的源会话（canReplay /
+ * startReplay）。
+ *
+ * 回放状态本身住在 `SessionState.replay` 里（非 React 宿主直接订阅它即可），
+ * 这里只做 React 绑定：订阅快照 + 接管冲突 + 拉一次 preview。
+ *
+ * **注册即接管**：底层的 `replayMismatch` 只交给最先注册的处理器。调用本 hook
+ * 就意味着由它接管冲突；不调用则维持 SDK 默认行为——直接转为真实运行。
+ */
+export declare function useReplay(session: AgentSession | null): UseReplayResult;

package/dist/index.d.ts

@@ -2,9 +2,22 @@ export { BladeProvider, useBladeClient } from "./context";
 export type { BladeProviderProps } from "./context";
 export { useAgentSession } from "./hooks/use-agent-session";
 export type { UseAgentSessionOptions, UseAgentSessionResult } from "./hooks/use-agent-session";
+export { useReplay } from "./hooks/use-replay";
+export type { ReplayMismatch, UseReplayResult } from "./hooks/use-replay";
+export { useLlmChat } from "./hooks/use-llm-chat";
+export type { ChatCompletionTool, LlmChatOptions, LlmToolCall, UseLlmChatResult, } from "./hooks/use-llm-chat";
 export { ChatView } from "./components/ChatView";
 export type { ChatViewClassNames, ChatViewProps, ChatViewRenderers, ChatViewSlots, } from "./components/ChatView";
+export { AgentChat } from "./components/AgentChat";
+export type { AgentChatProps } from "./components/AgentChat";
+export { LlmChat } from "./components/LlmChat";
+export type { LlmChatHandle, LlmChatProps } from "./components/LlmChat";
+export type { LlmAdvancedSettings, LlmOverride } from "./components/LlmAdvancedSettings";
 export { MarkdownContent } from "./components/MarkdownContent";
 export type { MarkdownContentProps } from "./components/MarkdownContent";
+export { ReplayBar } from "./components/ReplayBar";
+export type { ReplayBarProps } from "./components/ReplayBar";
+export { ReplayMismatchPrompt } from "./components/ReplayMismatchPrompt";
+export type { ReplayMismatchPromptProps } from "./components/ReplayMismatchPrompt";
 export type { ToolCallRenderer } from "./components/ToolCallBlock";
 export * from "@blade-hq/agent-client";