@blade-hq/agent-react 2610.0.0-beta.2 → 2610.0.0-beta.21

package/README.md

@@ -6,6 +6,10 @@ Blade Agent 的 React 绑定：`BladeProvider` + `useAgentSession` + 开箱即
 pnpm add @blade-hq/agent-client @blade-hq/agent-react
 ```
 
+默认装到的是当前长期支持版（LTS），厂内离线交付按它开发。要跟两周一发的公网版本，改用 `@next`。
+
+最稳妥的做法是先读目标 Server 的 `GET /api/version`，按返回的版本号在 `package.json` 里钉死——NPM 的 `latest` 不一定和目标环境跑的版本一致。
+
 > 注意两个包都要装：`agent-client` 是运行时依赖，只装 `agent-react` 在 pnpm 下会直接报错。
 
 ## 快速开始
@@ -150,7 +154,10 @@ await replay.exitToAutonomous()                // 退出回放，之后真的运
 
 全部 props 见 `ChatViewProps`。样式说明：
 
+`ChatView` 会把项目说明、可用能力和当前工作环境显示为默认折叠的业务卡片。自建消息列表可直接使用 `ContextCard`，属性见 `ContextCardProps`；状态到文案的映射来自 agent-client 的 `getContextDisplayState`，不需要接入方重复判断。底层数据类型为 `ContextProjectionData` / `ContextProjectionFields`，展示结果为 `ContextDisplayState`，并保留 `ContextAction`、`ContextSourceInfo` 和 `contextProjectionData` 给 headless 消费方。
+
 `onFollowupInteraction` 使用 `FollowupInteractionEvent`，覆盖下一步建议展示/采纳、成果展示/打开/下载以及结果评分。SDK 不内置 PostHog 等分析厂商；宿主回调抛错也不会中断用户点击或下载。
+文件成果以文件名为文本的标准下载链接展示；Vue / 纯 HTML 使用的 `<blade-chat>` 与 `ChatView` 行为一致。
 
 - 必须引入一份样式，按宿主有没有 Tailwind 二选一：
   - **`style.full.css`**（默认选它）：布局兜底 + 编译好的 Tailwind 产物，自包含，宿主没装 Tailwind 也是完整视觉。
@@ -296,6 +303,10 @@ blade-chat { --primary: 262 83% 58%; height: 640px; }
 </blade-chat>
 ```
 
+## 自定义消息列表滚动
+
+`ChatView`、`AgentChat` 和 `LlmChat` 已经处理好用户发言顶置，不用额外配置。自建消息列表时可用 `useMessagePin` 复用同一套触发、补白、视口 resize 和手动滚动接管逻辑；调用方只需提供滚动容器、目标消息与 spacer 的读写函数。完整参数见 [public-api.md](./public-api.md#usemessagepin-function)。
+
 ## 纯静态 HTML / Vue？
 
 不需要本包——用后端托管的单文件产物 `<script src=".../sdk/blade-agent.js">` + `<blade-chat>` 自定义元素，行为与 `ChatView` 一致；详见 agent-client README 与接入文档。
@@ -304,4 +315,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`、`FollowupInteractionEvent`、`ToolCallRenderer`、`MarkdownContent`、`MarkdownContentProps`。
+本包自有声明：`BladeProvider`、`BladeProviderProps`、`useBladeClient`、`useAgentSession`、`UseAgentSessionOptions`、`UseAgentSessionResult`、`useMessagePin`、`UseMessagePinOptions`、`useReplay`、`UseReplayResult`、`ReplayMismatch`、`ReplayBar`、`ReplayBarProps`、`ReplayMismatchPrompt`、`ReplayMismatchPromptProps`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`FollowupInteractionEvent`、`ToolCallRenderer`、`MarkdownContent`、`MarkdownContentProps`。

package/dist/components/AgentLoopBlock.d.ts

@@ -2,9 +2,6 @@ import type { ToolCallInfo } from "@blade-hq/agent-client";
 interface Props {
     toolCall: ToolCallInfo;
 }
-/**
- * 子智能体（fork Agent）状态块的 SDK 简化版：只展示描述、状态与最终结果，
- * 不再嵌套渲染子循环的完整消息流（那是第一方界面的能力）。
- */
+/** SDK 没有第一方子循环消息流，只保留轻量意图行和可展开的最终结果。 */
 export declare function AgentLoopBlock({ toolCall }: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/AssistantTurnBlock.d.ts

@@ -10,9 +10,17 @@ interface Props {
     /** 会话 id；传给 Markdown 渲染的统一上下文。 */
     sessionId?: string;
 }
-/**
- * 一轮助手回复：按消息顺序渲染 thinking 折叠块、正文 Markdown 与工具调用。
- * 相比第一方版本去掉了紧凑/详细模式切换、文件交付卡片与内联资源 iframe。
- */
+export type TurnDisplayMode = "compact" | "detail";
+export declare function resolveTurnDisplayMode({ isStreaming: _isStreaming, displayMode, }: {
+    isStreaming: boolean;
+    displayMode: TurnDisplayMode;
+}): TurnDisplayMode;
+export declare function formatExecutionDuration(durationMs: number): string;
+export declare function getExecutionDurationMs({ messages, isStreaming, now, }: {
+    messages: ChatMessage[];
+    isStreaming: boolean;
+    now?: number;
+}): number;
+/** 一轮助手回复：执行过程默认折叠，最终正文始终显示在摘要下方。 */
 export declare function AssistantTurnBlock({ messages, isStreaming, askAnswers, onAnswer, sessionStatus, toolCallRenderer, sessionId, }: Props): import("react/jsx-runtime").JSX.Element;
 export {};

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

@@ -0,0 +1,7 @@
+import { type ContextProjectionData } from "@blade-hq/agent-client";
+export interface ContextCardProps {
+    context: ContextProjectionData;
+    className?: string;
+}
+/** Business-facing Context summary. Native details keeps every card collapsed by default. */
+export declare function ContextCard({ context, className }: ContextCardProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/display-utils.d.ts

@@ -1,7 +1,15 @@
 import type { ToolCallInfo } from "@blade-hq/agent-client";
 export type ToolTone = "emerald" | "blue" | "amber" | "red";
+/**
+ * 技能入口文件的所在目录就是技能名（`.agent/skills/<技能名>/SKILL.md`）。
+ * 只显示 "SKILL.md" 用户看不出读的是哪个技能。
+ *
+ * 改这里必须同步 apps/web/src/agent/components/chat/display-utils.ts 的同名函数。
+ */
+export declare function getSkillNameFromFilePath(filePath: string | null | undefined): string | null;
 /** 归一化工具名：去掉命名空间前缀并映射到别名表（如 "fork:Agent" → "Agent"）。 */
 export declare function formatToolName(name: string): string;
+export declare function extractToolFilePath(toolCall: ToolCallInfo): string | null;
 /**
  * 返回工具调用的中文展示标签：优先取参数里的 description，
  * 其次取后端下发的 display_name / 系统工具中文名。

package/dist/embed/entry.d.ts

@@ -18,12 +18,16 @@ 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;
+    reconcileOptimisticUserTurns: typeof agentClient.reconcileOptimisticUserTurns;
     toReplaySnapshot: typeof agentClient.toReplaySnapshot;
     connectEmbedded: typeof agentClient.connectEmbedded;
     isCommandEnvelope: typeof agentClient.isCommandEnvelope;
@@ -39,6 +43,8 @@ declare const BladeAgent: {
     isHiddenInternalMessage: typeof agentClient.isHiddenInternalMessage;
     normalizeMessageContent: typeof agentClient.normalizeMessageContent;
     transformSlashCommand: typeof agentClient.transformSlashCommand;
+    contextProjectionData: typeof agentClient.contextProjectionData;
+    getContextDisplayState: typeof agentClient.getContextDisplayState;
     latestPostChatFollowup: typeof agentClient.latestPostChatFollowup;
     DEFAULT_REPLAY_SPEED: agentClient.ReplaySpeed;
     SessionInfo: import("arktype/internal/variants/object.ts").ObjectType<{

package/dist/hooks/use-message-pin.d.ts

@@ -0,0 +1,22 @@
+export interface UseMessagePinOptions {
+    targetKey: string | null;
+    pinTarget: boolean;
+    layoutKey?: string;
+    getScrollElement: () => HTMLElement | null;
+    getContentElement?: () => HTMLElement | null;
+    getTargetElement: () => HTMLElement | null;
+    getTargetScrollTop?: (scroll: HTMLElement) => number | null;
+    getSpacerHeight: () => number;
+    setSpacerHeight: (height: number) => void;
+    stopAutoScroll: () => void;
+    scrollToBottom: () => void;
+    margin?: number;
+}
+/**
+ * 用户发言顶置的共享状态机。SDK 和内置轻量列表只提供 DOM/虚拟列表适配器，
+ * 触发、调度、resize、手动接管和跟随交还的决策只在这里维护。
+ */
+export declare function useMessagePin({ targetKey, pinTarget, layoutKey, getScrollElement, getContentElement, getTargetElement, getTargetScrollTop, getSpacerHeight, setSpacerHeight, stopAutoScroll, scrollToBottom, margin, }: UseMessagePinOptions): {
+    release: () => void;
+    isActive: () => boolean;
+};

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export type { UseAgentSessionOptions, UseAgentSessionResult } from "./hooks/use-
 export { useReplay } from "./hooks/use-replay";
 export type { ReplayMismatch, UseReplayResult } from "./hooks/use-replay";
 export { useLlmChat } from "./hooks/use-llm-chat";
+export { useMessagePin } from "./hooks/use-message-pin";
+export type { UseMessagePinOptions } from "./hooks/use-message-pin";
 export type { ChatCompletionTool, LlmChatOptions, LlmToolCall, UseLlmChatResult, } from "./hooks/use-llm-chat";
 export { ChatView } from "./components/ChatView";
 export type { ChatViewClassNames, ChatViewProps, ChatViewRenderers, ChatViewSlots, FollowupInteractionEvent, } from "./components/ChatView";
@@ -20,4 +22,6 @@ export type { ReplayBarProps } from "./components/ReplayBar";
 export { ReplayMismatchPrompt } from "./components/ReplayMismatchPrompt";
 export type { ReplayMismatchPromptProps } from "./components/ReplayMismatchPrompt";
 export type { ToolCallRenderer } from "./components/ToolCallBlock";
+export { ContextCard } from "./components/ContextCard";
+export type { ContextCardProps } from "./components/ContextCard";
 export * from "@blade-hq/agent-client";