@blade-hq/agent-react 2610.0.0-beta.17 → 2610.0.0-beta.19

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 下会直接报错。
 
 ## 快速开始
@@ -299,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 与接入文档。
@@ -307,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/display-utils.d.ts

@@ -9,6 +9,7 @@ export type ToolTone = "emerald" | "blue" | "amber" | "red";
 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/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";