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

package/README.md

@@ -68,66 +68,6 @@ 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、代码高亮、工具调用、提问卡片）+ 输入框 + 连接状态条 + 登录引导。
@@ -156,95 +96,6 @@ await replay.exitToAutonomous()                // 退出回放，之后真的运
 - `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）：
@@ -253,7 +104,7 @@ models.filter((m) => m.serviceModelId)
 <MarkdownContent content={markdownText} />
 ```
 
-传了 `sessionId` 才会把智能体产出文件的 `MEDIA:` 行折叠成下载卡片（下载要用它）。`ChatView` 内部已经传好，只有单独用 `MarkdownContent` 时需要自己给：
+传了 `sessionId` 才会把智能体产出文件的 `MEDIA:` 行折叠成以文件名为文本的下载链接（下载要用它）。`ChatView` 内部已经传好，只有单独用 `MarkdownContent` 时需要自己给：
 
 ```tsx
 <MarkdownContent sessionId={sessionId}>{markdownText}</MarkdownContent>
@@ -302,4 +153,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`、`useReplay`、`UseReplayResult`、`ReplayMismatch`、`ReplayBar`、`ReplayBarProps`、`ReplayMismatchPrompt`、`ReplayMismatchPromptProps`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`ToolCallRenderer`、`MarkdownContent`、`MarkdownContentProps`。
+本包自有声明：`BladeProvider`、`BladeProviderProps`、`useBladeClient`、`useAgentSession`、`UseAgentSessionOptions`、`UseAgentSessionResult`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`ToolCallRenderer`、`MarkdownContent`、`MarkdownContentProps`。

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/ChatView.d.ts

@@ -1,23 +1,43 @@
-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;
+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";
 }
 /**
- * 聊天界面。默认接 Blade 智能体会话，`mode="llm"` 时改接标准 OpenAI 对话接口。
- *
- * 这一层只做分流：两种模式各自是独立组件，已经确定要哪一种的可以直接用
- * `<AgentChat>` 或 `<LlmChat>`。
+ * 开箱即用的聊天界面：连接（或新建）一个会话，渲染消息流与输入框。
+ * 状态全部来自 useAgentSession，不依赖任何全局 store。
  */
 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 行折叠而来）。
  *
- * 整张卡片只有一个动作：下载。第一方界面点卡片是「在右侧预览」，那依赖 app 的 artifact
- * 面板，SDK 里没有这块，所以不摆预览入口也不写预览文案——UI 不能承诺不存在的能力。
+ * href 让 Vue/纯 HTML 宿主看到标准的「文件名→URL」语义；普通点击仍交给
+ * downloadFile，避免跨域时 download 属性被忽略，也确保使用点击时的最新 token。
  */
 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/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/embed/entry.d.ts

@@ -18,13 +18,15 @@ 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;
@@ -39,7 +41,6 @@ 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/index.d.ts

@@ -2,22 +2,9 @@ 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";