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

package/README.md

@@ -6,6 +6,8 @@ Blade Agent 的 React 绑定：`BladeProvider` + `useAgentSession` + 开箱即
 pnpm add @blade-hq/agent-client @blade-hq/agent-react
 ```
 
+TypeScript 消费者需要开发依赖 `@types/node`：底层 arktype 的声明使用 Node `buffer.File` 类型。若显式配置 `compilerOptions.types`，需包含 `node`；这是类型检查环境要求，浏览器运行时不因此依赖 Node。React 使用者还需对应版本的 `@types/react` / `@types/react-dom`。
+
 默认装到的是当前长期支持版（LTS），厂内离线交付按它开发。要跟两周一发的公网版本，改用 `@next`。
 
 最稳妥的做法是先读目标 Server 的 `GET /api/version`，按返回的版本号在 `package.json` 里钉死——NPM 的 `latest` 不一定和目标环境跑的版本一致。
@@ -471,3 +473,23 @@ blade-chat::part(input-toolbar) { gap: 12px; }
 完整签名见 [public-api.md](./public-api.md)。本包公开声明：`BladeProvider`、`BladeProviderProps`、`BladeHost`、`HostAttachment`、`HostCatalogItem`、`useBladeClient`、`useAgentSession`、`UseAgentSessionOptions`、`UseAgentSessionResult`、`useReplay`、`UseReplayResult`、`ReplayMismatch`、`ReplayBar`、`ReplayBarProps`、`ReplayMismatchPrompt`、`ReplayMismatchPromptProps`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`UserMessageRendererProps`、`AssistantTextRendererProps`、`AskUserQuestionRendererProps`、`AskUserQuestionData`、`PlanUpdateRendererProps`、`PlanUpdateData`、`PlanStepStatus`、`ToolCallRenderer`、`ToolRendererProps`、`FollowupInteractionEvent`、`LlmChatHandle`、`LlmChatOptions`、`ChatCompletionTool`、`LlmToolCall`、`MarkdownContent`、`MarkdownContentProps`。
 
 `@blade-hq/agent-client` 不再从本包转出，`BladeClient`、`AgentSession` 等直接从 `@blade-hq/agent-client` import。
+
+## 主题资产 @
+
+主题资产候选通过当前主题的资产列表获取，使用专用 `TopicAssetMention` 药丸；没有关联主题时不展示候选。首页与会话输入框复用候选查询、引用序列化和展示结构。
+
+`useReferenceCandidates(getScope, { plugins, topics, files })` 在富输入子入口提供固定三组候选的并发查询、短等待与迟到刷新；作用域为 client、鉴权身份、session、topic，菜单使用 query 返回数组绑定 observe，退出时 cancel。宿主继续提供原有数据适配，控制器不执行工具或改写发送协议。
+
+`queueTopicAssetReference(sessionId, { topic_id, path })`（`@blade-hq/agent-react/rich-input`）可在导航到当前用户的同主题会话前预填引用。发送只携带引用身份，元数据和权限由服务端重新判断；本轮续跑保留引用，下一条消息默认不继承。
+
+会话文件树可通过宿主提供的提交动作显示“提交到资产”；只读或未关联主题时不显示写入口，服务端仍会独立检查权限。
+
+文件提交共享组件：`TopicAssetSubmitDialog`（属性 `TopicAssetSubmitDialogProps`）提供目录选择和提交说明；`useTopicAssetSubmissionAccess` 查询当前会话的主题及写权限。二者用于宿主文件树接入，不能替代服务端鉴权。
+
+### 选择插件条目
+
+ChatView 和 `<blade-chat>` 的默认轻量输入支持 @ 搜索插件条目，候选显示中文插件名和图标。选中条目在输入框上方显示，可点 × 移除；发送后保留选择，刷新后恢复最近用户消息的选择。富输入使用同样的候选接口与 PluginRef 身份。自动读取失败时模型会收到明确失败说明。
+
+### 应用资料展示
+
+共享聊天视图展示消息级 `context_attachments`：气泡只显示正文，资料标签可展开查看纯文本详情，`data` 中的内部 JSON 与 ID 不显示。`ChatSendOptions.contextAttachments` 可沿共享发送入口传入 SDK；可靠后台发送使用 `AgentSession.prepareSend` / `sendPrepared`。文件读取使用当前 `BladeProvider` 的 `BladeClient` 和资料指定的会话权限，失效或没有来源的文件显示「文件不可用」。内置 Web、扩展和嵌入视图使用相同实现。

package/dist/chat/AssistantTurnBlock.d.ts

@@ -38,7 +38,7 @@ export declare function formatExecutionDuration(durationMs: number): string;
 export declare function getExecutionDurationMs({ messages, isStreaming, now, }: {
     messages: ChatMessage[];
     isStreaming: boolean;
-    now?: number;
+    now?: number | null;
 }): number;
 declare function AssistantTurnBlockBase({ sessionId, messages: rawMessages, isStreaming, isReasoningRevealing, askAnswers, onAnswer, sessionStatus, level, forceExpanded, customization, }: Props): import("react/jsx-runtime").JSX.Element;
 export declare const AssistantTurnBlock: import("react").MemoExoticComponent<typeof AssistantTurnBlockBase>;

package/dist/chat/ChatLoadingIndicator.d.ts

@@ -0,0 +1,7 @@
+export declare function isPreparingReply(messages: readonly {
+    role: string;
+    kind?: string;
+}[]): boolean;
+export declare function ChatLoadingIndicator({ preparing }: {
+    preparing?: boolean;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/chat/ChatPanel.d.ts

@@ -38,8 +38,6 @@ export interface ChatPanelProps extends ChatViewCustomization {
     /** 宿主是否接住了「创建后台任务」；见输入框上的说明。 */
     canCreateBoardTask?: boolean;
     canShareSession?: boolean;
-    onResyncSkills?: () => void;
-    isResyncingSkills?: boolean;
     /** 打开技能页；由宿主导航。 */
     onOpenSkills?: () => void;
     inputLabel?: string;
@@ -61,4 +59,4 @@ export interface ChatPanelProps extends ChatViewCustomization {
  * 聊天面板：消息流 + 队列 + 输入框。数据只来自 SessionSourceProvider 提供的会话实例与 props；
  * 内置 Web、浏览器插件与 SDK 的 ChatView / `<blade-chat>` 渲染的都是它。
  */
-export declare function ChatPanel({ sessionId, theme, mode: providedMode, onToggleMode, banner, header, footer, emptyState, errorMessage: externalError, onExitReplay, placeholder, onFollowupInteraction, renderAttachments, onBeforeSend, onCommand, canCreateBoardTask, canShareSession, onResyncSkills, isResyncingSkills, onOpenSkills, inputLabel, onDoubleEscape, composerHint, composerBanner, scrollToStartKey, scrollToEntryKey, initialDraft, initialDraftKey, renderMode: requestedRenderMode, renderComposerStats, classNames, components, renderers, }: ChatPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatPanel({ sessionId, theme, mode: providedMode, onToggleMode, banner, header, footer, emptyState, errorMessage: externalError, onExitReplay, placeholder, onFollowupInteraction, renderAttachments, onBeforeSend, onCommand, canCreateBoardTask, canShareSession, onOpenSkills, inputLabel, onDoubleEscape, composerHint, composerBanner, scrollToStartKey, scrollToEntryKey, initialDraft, initialDraftKey, renderMode: requestedRenderMode, renderComposerStats, classNames, components, renderers, }: ChatPanelProps): import("react/jsx-runtime").JSX.Element;

package/dist/chat/ContextAttachmentPills.d.ts

@@ -0,0 +1,4 @@
+import type { ContextAttachment } from "@blade-hq/agent-client";
+export declare function ContextAttachmentPills({ attachments }: {
+    attachments?: ContextAttachment[];
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/chat/LightComposer.d.ts

@@ -1,6 +1,6 @@
 import type { ComposerProps } from "./customization";
 /**
- * 轻输入（SDK 与 `<blade-chat>` 的默认输入框）：纯文本 textarea，不带富文本编辑、提及、`/` 菜单、
+ * 轻输入（SDK 与 `<blade-chat>` 的默认输入框）：textarea 和通用插件条目选择，不带富文本编辑、`/` 菜单、
  * 语音与模型选择。`AgentSession.attach()` / `insertText()`（页面协作、跟进建议、MCP 应用消息）
  * 都落进这里的文本。
  */

package/dist/chat/LiteMessageList.d.ts

@@ -12,7 +12,7 @@ type TextRow = {
     failed?: boolean;
     /** 本轮（含子智能体循环）真实检索到的引用证据，只有 assistant 文本行才有——
      * 跟 AssistantTurnBlock.tsx 的 turnToolCalls/citations 同一套算法，不然轻量
-     * 模式下 kb_search 的 [n] 角标只能停在纯文本，点不开、也 hover 不出来源。 */
+     * 模式下 插件引用的 [n] 角标只能停在纯文本，点不开、也 hover 不出来源。 */
     citations?: Record<number, CitationEntry>;
 };
 type MemoryRefsRow = {

package/dist/chat/MessageList.d.ts

@@ -5,6 +5,7 @@ import type { ResultFeedback } from "@blade-hq/agent-client/internal";
 import type { AskUserAnswerData } from "./AskUserQuestionBlock";
 import type { ChatViewCustomization } from "./customization";
 export { shouldAppendPendingAssistantTurn } from "./message-list-blocks";
+export declare function isReasoningRevealingForMessage(message: ChatMessage | undefined, isRevealing: boolean, isStopping?: boolean): boolean;
 export interface MessageListProps {
     sessionId: string;
     messages: ChatMessage[];

package/dist/chat/WorkflowRunBlock.d.ts

@@ -1,13 +1,29 @@
+import type { WorkflowRunEntry } from "@blade-hq/agent-client";
 import type { ToolCallInfo } from "@blade-hq/agent-client/internal";
 interface Props {
     /** 触发这次运行的 workflow:run 工具调用。 */
     toolCall: ToolCallInfo;
     sessionId: string;
 }
+type StepGroup = {
+    key: string;
+    desc: string;
+    stepId: string;
+    stepKind: string;
+    /** 落史的终态(刷新重建时有);实时运行中没有,由运行状态推断。 */
+    status?: string;
+    logs: string[];
+};
+/** 事件流 → 步骤分组:每个 step 事件开一张卡。log 行带所属步骤 id 时归到那一步
+ * (并行分支的输出不按宣告顺序到达,按位置归会挂错卡);旧记录没有 id 才归到上一步。 */
+export declare function groupWorkflowEntries(entries: readonly WorkflowRunEntry[]): {
+    prelude: string[];
+    groups: StepGroup[];
+};
 /**
- * 「工作流运行」块:一次 workflow:run 的执行呈现——每个步骤一张卡顺序铺开
- * (agent 步骤=完整子智能体卡,命令/条件步骤=描述+输出的小卡),头部可整体折叠。
- * 渲染在触发它的回合内部(思考折叠区之后、总结之前),随回合持久。
+ * 「固定流程」块:一次 workflow:run(跑某个技能的 flows/*.yaml)的执行呈现——每个步骤
+ * 一张卡顺序铺开(agent 步骤=完整子智能体卡,命令/条件步骤=描述+输出的小卡),头部可整体折叠。
+ * 渲染在触发它的回合的「执行过程」折叠区里,和普通技能的工具调用同一个位置。
  */
 export declare function WorkflowRunBlock({ toolCall, sessionId }: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/chat/ai-elements/reasoning.d.ts

@@ -1,4 +1,4 @@
-import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@blade-hq/ui/components/collapsible";
+import type * as CollapsiblePrimitive from "@radix-ui/react-collapsible";
 import type { ComponentProps } from "react";
 interface ReasoningContextValue {
     isStreaming: boolean;
@@ -7,7 +7,7 @@ interface ReasoningContextValue {
     duration: number | undefined;
 }
 export declare const useReasoning: () => ReasoningContextValue;
-export type ReasoningProps = ComponentProps<typeof Collapsible> & {
+export type ReasoningProps = ComponentProps<typeof CollapsiblePrimitive.Root> & {
     isStreaming?: boolean;
     open?: boolean;
     defaultOpen?: boolean;
@@ -15,11 +15,11 @@ export type ReasoningProps = ComponentProps<typeof Collapsible> & {
     duration?: number;
 };
 export declare const Reasoning: import("react").MemoExoticComponent<({ className, isStreaming, open, defaultOpen, onOpenChange, duration: durationProp, children, ...props }: ReasoningProps) => import("react/jsx-runtime").JSX.Element>;
-export type ReasoningTriggerProps = ComponentProps<typeof CollapsibleTrigger> & {
+export type ReasoningTriggerProps = ComponentProps<typeof CollapsiblePrimitive.Trigger> & {
     wordCount: number;
 };
 export declare const ReasoningTrigger: import("react").MemoExoticComponent<({ className, children, wordCount, ...props }: ReasoningTriggerProps) => import("react/jsx-runtime").JSX.Element>;
-export type ReasoningContentProps = ComponentProps<typeof CollapsibleContent> & {
+export type ReasoningContentProps = ComponentProps<typeof CollapsiblePrimitive.Content> & {
     children: string;
 };
 export declare const ReasoningContent: import("react").MemoExoticComponent<({ className, children, ...props }: ReasoningContentProps) => import("react/jsx-runtime").JSX.Element>;

package/dist/chat/customization.d.ts

@@ -30,7 +30,7 @@ export type ChatViewClassNames = Partial<{
     skillStatusBarInner: string;
 }>;
 /** 输入框提交时的附加项（模型、推理档位、知识库等由富输入给出）。 */
-export interface ChatSendOptions extends Pick<ChatSendExtras, "thinkingOverride" | "reasoningLevel" | "kbIds" | "queueWhenRunning"> {
+export interface ChatSendOptions extends Pick<ChatSendExtras, "thinkingOverride" | "reasoningLevel" | "refs" | "contextAttachments" | "topicAssetRefs" | "queueWhenRunning"> {
     /** 附件实际上传到的会话（首页新建会话时由输入框给出）。 */
     targetSessionId?: string;
     /** 本条消息用的模型；null 表示沿用会话已保存的模型。 */
@@ -69,8 +69,6 @@ export interface ComposerProps {
     SkillStatusBarComponent?: ComponentType<SkillStatusBarComponentProps>;
     skillStatusBarClassName?: string;
     skillStatusBarInnerClassName?: string;
-    onResyncSkills?: () => void;
-    isResyncingSkills?: boolean;
     onOpenSkills?: () => void;
     inputLabel?: string;
     placeholderText?: string;
@@ -182,8 +180,6 @@ export interface ToolRendererProps {
 }
 export interface SkillStatusBarComponentProps {
     sessionId: string;
-    onResync?: () => void;
-    isResyncing?: boolean;
     vertical?: boolean;
     className?: string;
     innerClassName?: string;

package/dist/chat/index.d.ts

@@ -85,16 +85,13 @@ export { ENTRY_SCROLL_MARGIN_PX, calculateStickyAwareMargin, normalizeScrollEntr
 export { BashRenderer } from "./tool-renderers/BashRenderer";
 export { FileEditRenderer } from "./tool-renderers/FileEditRenderer";
 export { FileReadRenderer } from "./tool-renderers/FileReadRenderer";
-export { KbSearchRenderer } from "./tool-renderers/KbSearchRenderer";
 export { SearchRenderer } from "./tool-renderers/SearchRenderer";
 export { SubmitResultRenderer } from "./tool-renderers/SubmitResultRenderer";
-export { parseKbSearchResult, formatKbSearchLabel } from "./tool-renderers/kb-search-result";
-export type { KbSearchHit, KbSearchResult } from "./tool-renderers/kb-search-result";
 export { getRenderer } from "./tool-renderers/registry";
 export { getResultText, getResultImages, parseJsonValue, isPlainObject, getStringValue, getNumberValue, getBooleanValue, extractErrorMessage, getFileName, getCodeLanguage, formatBytes, CodePreview } from "./tool-renderers/shared";
 export { shouldFollowWritePreview, scrollWritePreviewToLatest } from "./tool-renderers/write-preview-scroll";
 export { skillDisplayName } from "./lib/skill-name";
-export { type ConnectorComputerSectionProps, type InputConnection, type InputDataState, type InputKnowledgeBase, type InputModelCatalog, type InputModelOption, type InputModelPreferences, type InputSessionSkill, type InputSkillStats, type RichInputServices, parseModelReasoningLevels, RichInputServicesProvider, useRichInputServices, } from "./runtime/input-services";
+export { type ConnectorComputerSectionProps, type InputConnection, type InputDataState, type InputModelCatalog, type InputModelOption, type InputModelPreferences, type InputSessionSkill, type InputSkillStats, type RichInputServices, parseModelReasoningLevels, RichInputServicesProvider, useRichInputServices, } from "./runtime/input-services";
 export { backgroundTaskDismissals, useDismissedBackgroundTasks } from "./runtime/background-task-dismissals";
 export { visibleSkillIds, visibleSkills } from "./lib/skill-visibility";
 export { resetInputCaches } from "./runtime/input-cache-reset";

package/dist/chat/lib/citations.d.ts

@@ -1,30 +1,13 @@
 import type { ToolCallInfo } from "@blade-hq/agent-client/internal";
-/** 一条可点击引用的完整证据：从 kb_search 工具结果的 hit 原样带过来。 */
+/** 一条可点击引用的原文，来自保存的插件快照。 */
 export interface CitationEntry {
     n: number;
-    kbName: string;
     title: string;
-    path: string;
-    page: number | null;
-    heading: string | null;
     text: string;
     previewUrl: string | null;
+    snapshot?: boolean;
+    toolCallId?: string;
+    itemId?: string;
 }
-/**
- * 从一轮里的工具调用抽取可引用证据。规则：
- * - 只认成功完成的 kb_search 调用（其余工具、失败/进行中的调用都不构成可引用证据）。
- * - 汇总本轮全部 kb_search 调用的命中，不只看最后一次。后端（见
- *   `knowledge_base.py build_search_tool_output` 的 `start_index`、
- *   `EngineSkillMixin.allocate_kb_citation_range`）保证本轮内多次 kb_search
- *   调用的编号连续递增、不重叠、不归零，所以回答里的每个 `[n]` 在这一轮里
- *   本该全局唯一，直接汇总即可，不用再靠"只用最后一次"去猜模型引用的是哪次。
- * - 但前端不信任协议 100% 不出错：万一后端真出现同一个编号在不同调用间指向
- *   不同证据的异常情况，这里依然按"冲突就剔除"处理——发现冲突直接从返回的
- *   map 里删掉这个编号，而不是用后来者覆盖前者，避免一旦协议出岔子就退回到
- *   "看起来能点、点开却是错的文档"这个原始 bug。正常情况下这段防御代码不会
- *   被触发。
- *
- * 返回的 map 只包含真的有证据支撑、且没有歧义的编号——`[n]` 是否可点全靠这个
- * map 里有没有对应的 key，不额外维护一个"允许列表"，避免两处状态不同步。
- */
+/** Collect saved plugin sources; conflicting numbers remain unclickable. */
 export declare function buildCitationsFromToolCalls(toolCalls: ToolCallInfo[] | null | undefined): Record<number, CitationEntry>;

package/dist/chat/markdown/MarkdownContent.d.ts

@@ -1,12 +1,15 @@
 import { type MarkdownRendererProps } from "../../components/markdown";
 import { normalizeAdjacentUrlFormatting } from "./text";
+import { type ComponentPropsWithRef } from "react";
 import type { CitationEntry } from "../lib/citations";
 export { normalizeAdjacentUrlFormatting };
+type PreProps = ComponentPropsWithRef<"pre">;
 export declare function resolveCollapsedContent({ dataKeyAttribute, dataRawAttribute, children, }: {
     dataKeyAttribute?: string;
     dataRawAttribute?: string;
     children?: unknown;
 }): string;
+export declare function CodeBlockPre({ children, ...props }: PreProps): import("react/jsx-runtime").JSX.Element;
 export declare function collapseInlineToolCalls(children: string): string;
 /** `[n]` 形式的引用角标，只有在 `citations` 里能查到 n 对应的证据时才替换成可交互标签
  * `<blade-citation-ref data-n="n">`；查不到就原样留作纯文本——不给用户一个点了却没有

package/dist/chat/runtime/actions.d.ts

@@ -9,7 +9,9 @@ export interface ChatSendExtras {
     model?: string;
     thinkingOverride?: boolean;
     reasoningLevel?: string;
-    kbIds?: number[];
+    contextAttachments?: SendOptions["contextAttachments"];
+    refs?: SendOptions["refs"];
+    topicAssetRefs?: SendOptions["topicAssetRefs"];
     whatif?: SendOptions["whatif"];
     replayDecision?: SendOptions["replayDecision"];
     /**

package/dist/chat/runtime/composer-channels.d.ts

@@ -1,3 +1,4 @@
+import { type TopicAssetRef } from "@blade-hq/agent-client";
 export interface PendingContextSignal {
     id: string;
     label: string;
@@ -13,6 +14,7 @@ export interface SendRequestSignal {
     id: string;
 }
 export interface ComposerChannelsState {
+    topicAssetReferences: Record<string, TopicAssetRef[]>;
     pendingContexts: Record<string, PendingContextSignal[]>;
     draftAppends: Record<string, DraftAppendSignal[]>;
     sendRequests: Record<string, SendRequestSignal[]>;
@@ -21,6 +23,8 @@ export interface ComposerChannelsState {
 }
 export declare const composerChannels: {
     getState: () => ComposerChannelsState;
+    addTopicAssetReference(sessionId: string, ref: TopicAssetRef): void;
+    consumeTopicAssetReferences: (sessionId: string) => TopicAssetRef[];
     subscribe(listener: () => void): () => void;
     addPendingContext(sessionId: string, context: Omit<PendingContextSignal, "id">): void;
     removePendingContext(sessionId: string, contextId: string): void;

package/dist/chat/runtime/input-cache-reset.d.ts

@@ -4,5 +4,5 @@
  * `resetInputCaches`。放在 internal 入口，宿主调用它不必引入富输入。
  */
 import type { BladeClient } from "@blade-hq/agent-client";
-export declare function onInputCachesReset(client: BladeClient, reset: () => void): void;
+export declare function onInputCachesReset(client: BladeClient, reset: () => void): () => void;
 export declare function resetInputCaches(client: BladeClient): void;

package/dist/chat/runtime/input-history-storage.d.ts

@@ -0,0 +1,2 @@
+export declare function getInputHistoryGeneration(): number;
+export declare function resetInputHistoryStorage(): void;

package/dist/chat/runtime/input-services.d.ts

@@ -38,11 +38,6 @@ export interface InputModelPreferences {
 }
 /** 偏好里存的是 JSON 字符串（模型 id → 档位）；坏数据当作没有。 */
 export declare function parseModelReasoningLevels(value: string | null | undefined): Record<string, string>;
-export interface InputKnowledgeBase {
-    id: number;
-    name: string;
-    description?: string | null;
-}
 export interface InputSessionSkill {
     skill_id: string;
     display_name?: string | null;
@@ -80,7 +75,6 @@ export interface RichInputServices {
     useModelCatalog?: () => InputModelCatalog;
     useModelPreferences?: () => InputModelPreferences;
     /** 知识库清单（`@` 菜单打开时才调用）。 */
-    useKnowledgeBaseLoader?: () => () => Promise<InputKnowledgeBase[]>;
     /** 语音是否可用（部署可以关掉）；默认不可用，不显示麦克风。 */
     voiceEnabled?: boolean;
     /** 语音的 AudioWorklet 脚本地址。 */