@blade-hq/agent-react 2610.0.0-beta.53 → 2610.0.0-beta.55

package/README.md

@@ -384,6 +384,12 @@ blade-chat { --primary: 262 83% 58%; height: 640px; }
 
 不需要本包——用后端托管的单文件产物 `<script src=".../sdk/blade-agent.js">` + `<blade-chat>` 自定义元素，行为与 `ChatView` 一致；详见 agent-client README 与接入文档。
 
+## 附录：连接器与插件选择
+
+- **连接器面板**：`ConnectorPanel`、`ConnectorPanelProps`、`PluginConnectorList`、`PluginConnectorListProps`、`ConfiguringPlugin`
+- **插件行与触发器**：`PluginConnectorItem`、`PluginConnectorSelection`、`selectionFromItem`、`triggerSummary`、`TriggerSummary`、`TRIGGER_ICON_LIMIT`、`mergeConnectorItems`、`catalogToConnectorItems`、`filterConnectorItems`、`pluginConnectorSummary`
+- **启用时序**：`useSessionPluginActivation`、`UseSessionPluginActivationResult`
+
 ## 附录：re-export 自 @blade-hq/agent-client
 
 为方便单包引入，本包 re-export 了 agent-client 的全部公开声明（`BladeClient`、`AgentSession`、`SessionState`、协议类型等），文档一律见 [agent-client 的 README](../agent-client/README.md)。完整签名见 [public-api.md](./public-api.md)。
@@ -407,6 +413,29 @@ blade-chat { --primary: 262 83% 58%; height: 640px; }
 插件的账号、token 等配置由包内 JSON Schema 声明，选择器就地提供填写入口：首次激活缺配置的插件会直接弹出表单（`<SessionPluginConfigDialog client={client} sessionId={id} plugin={plugin} />`），已配置的插件在行内提供「配置」按钮。表单本体是 `<SessionPluginConfigForm>`，参数与提交类型为 `SessionPluginConfigFormProps` / `SessionPluginConfigDraft`，也可单独嵌入；`SessionPluginConfigDialogProps` 是对话框的参数类型。
 
 表单只呈现它确定能呈现的 JSON Schema 构造（字符串/数值/布尔/null、对象与数组、枚举、`properties` 内的 `writeOnly`，以及用同一字段的 `const` 固定的 `oneOf` 分支）；遇到无法安全呈现的写法直接说明原因，不降级成手写 JSON、不静默丢字段。`writeOnly` 字段永不回显：留空表示保持不变，输入表示修改，显式「清除」才会删除。
+### 连接器面板
+
+首页与对话输入框共用同一个连接器面板：`<ConnectorPanel client={client} sessionId={id} />`，
+参数类型为 `ConnectorPanelProps`。面板本身只管插件分区，电脑与外部账号由宿主通过
+`renderComputerSection` / `renderExternalAccounts` / `renderFooterActions` 注入——那些入口
+要跳宿主自己的路由，SDK 不硬编码内部路径。`sessionId` 传 `null` 表示"首页"：此时开关只记录
+本次输入的待选（`PluginConnectorSelection`、`onPendingPluginsChange`），不激活任何东西、
+不建会话、不启沙盒；`pendingDisabledReason` 用于说明该模式下为什么用不了待选。
+
+插件行的渲染交给 `<PluginConnectorList>`（`PluginConnectorListProps`），它只负责样式与排版：
+"该显示成什么"全部来自 `PluginConnectorItem`、`mergeConnectorItems`、`catalogToConnectorItems`、
+`filterConnectorItems` 与 `pluginConnectorSummary`，判定不各写一份。`sessionPluginLabel` 决定
+一行读起来是什么名字。
+
+启用时序由 `useSessionPluginActivation` 收口（返回值类型 `UseSessionPluginActivationResult`）：
+**先准备配置、再提交激活**。缺必填配置时开关不落到已启用、立刻弹表单，保存由服务端确认配置
+完整才提交；取消、校验失败、读取失败都保持关闭，不会先写 `active=true` 再补偿。慢准备/慢激活
+期间开关仍可点，语义是取消这次意图而不是再排一次队。配置弹窗由 `ConfiguringPlugin` 描述。
+
+触发器要在不打开面板时就能显示"选了哪几个、几个"：用 `selectionFromItem` 把一行转成
+`PluginConnectorSelection`，再用 `triggerSummary` 折成 `TriggerSummary`（最多 `TRIGGER_ICON_LIMIT`
+个图标，其余折成数量；没有图标 token 的项不占图标位但仍计数）。
+
 ### MCP Apps
 
 `McpAppCard` 使用官方 AppBridge 渲染归档卡片，内置 Web 消费同一组件。在 `BladeProvider` 下传入会话 ID 与来源 ID，也可直接提供 `BladeClient`。`McpAppMessage` 表示 App 提供的文本；`McpAppMessageContext` 将其交给当前对话的待发送区。用户可在 `ChatView` 查看、移除并确认发送。`update-model-context` 会把 App 提交的当前状态经 `sessions.updateMcpAppContext` 存为会话上下文：只落库、不追加聊天、不启动 agent turn，正在运行的一轮保持启动时版本，下一个新的运行才读取；冲突（409）时重读最新 revision 后重提同一份状态一次。

package/dist/components/ConnectorPanel.d.ts

@@ -0,0 +1,41 @@
+import type { BladeClient, SessionPluginActivation } from "@blade-hq/agent-client";
+import { type ReactNode } from "react";
+import { type PluginConnectorItem } from "./plugin-connector";
+import { type PluginConnectorSelection } from "./connector-panel-types";
+export interface ConnectorPanelProps {
+    client: BladeClient;
+    /**
+     * `null` 表示首页：插件开关只记下本次输入的待选，不激活任何东西、不建会话、
+     * 不启动沙盒或 MCP。待选项随首条消息一起交给宿主处理。
+     */
+    sessionId: string | null;
+    /** 首页待选插件；`sessionId` 为 null 时使用。 */
+    pendingPlugins?: PluginConnectorSelection[];
+    onPendingPluginsChange?: (next: PluginConnectorSelection[]) => void;
+    /** 首页候选开关不可用时的说明（例如软件工厂模式会先建项目再启动）。 */
+    pendingDisabledReason?: string | null;
+    /** 会话内插件启用/停用结果；宿主据此刷新技能统计。 */
+    onPluginsChanged?: (plugin: SessionPluginActivation) => void;
+    /**
+     * 当前已选（首页待选 / 会话内已启用）的插件，按行原样报给宿主。
+     *
+     * 触发器要在不打开面板时就能显示「选了哪几个、几个」，它自己拿不到这份状态，
+     * 所以由面板单向汇报；面板未挂载时宿主保留上一次的结果。
+     */
+    onSelectedChange?: (items: PluginConnectorItem[]) => void;
+    /** 宿主注入：电脑分区。参数是搜索词，宿主自己决定怎么过滤。 */
+    renderComputerSection?: (query: string) => ReactNode;
+    /** 宿主注入：外部账号分区（飞书 / GitHub 等固定连接入口）。 */
+    renderExternalAccounts?: (query: string) => ReactNode;
+    /** 宿主注入：底部操作（添加连接器 / 管理连接器）。 */
+    renderFooterActions?: () => ReactNode;
+    className?: string;
+}
+/**
+ * 统一连接器面板：顶部搜索、按「电脑 / 插件 / 外部账号」分区、底部添加与管理。
+ *
+ * 插件分区是这一层唯一的共享实现：首页和会话用同一个列表、同一套启用判定，
+ * 判定不各写一份。电脑与外部账号由宿主注入——那些入口需要宿主的路由与 CLI
+ * 引导，SDK 不硬编码内部路径，也不替第三方决定跳到哪里。
+ */
+export declare function ConnectorPanel({ client, sessionId, pendingPlugins, onPendingPluginsChange, pendingDisabledReason, onPluginsChanged, onSelectedChange, renderComputerSection, renderExternalAccounts, renderFooterActions, className, }: ConnectorPanelProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/PluginConnectorList.d.ts

@@ -0,0 +1,47 @@
+import type { BladeClient, SessionPluginConfigState } from "@blade-hq/agent-client";
+import type { PluginConnectorItem } from "./plugin-connector";
+export interface ConfiguringPlugin {
+    name: string;
+    /**
+     * 这次打开表单是不是「为了启用它」。
+     *
+     * 只有用户在开关上表达了启用意图时才为 true：已经跑起来的插件再保存配置
+     * 不应该顺手重启 / 重新激活（见 SessionPluginSelector 的历史约定）。
+     */
+    pendingActivation: boolean;
+}
+export interface PluginConnectorListProps {
+    client: BladeClient;
+    /** 会话内插件用会话接口取图标；首页候选（null）用账号级目录。 */
+    sessionId: string | null;
+    items: PluginConnectorItem[];
+    /** 正在提交意图的行；开关转圈，但仍然可点（点是取消）。 */
+    inFlight: Record<string, true>;
+    /** 有启用/停用请求在飞，会写服务端的行先锁住次要操作。 */
+    busy: boolean;
+    /** 上一次操作失败，给出重试入口。 */
+    mutationError: boolean;
+    onToggle: (item: PluginConnectorItem, next: boolean) => void;
+    onRetry: (item: PluginConnectorItem) => void;
+    onEditConfig: (item: PluginConnectorItem) => void;
+    configuring: ConfiguringPlugin | null;
+    onConfigSaved: (state: SessionPluginConfigState) => void;
+    onConfigClose: () => void;
+    /** 开关不可用时说明原因，而不是静默禁用。 */
+    disabledReason?: string | null;
+    /**
+     * 列表本身不可用（读取失败 / 搜索无结果）时的说明；有值时不再叠加「还没装插件」，
+     * 否则会把一次故障或一次没搜到说成「你这个账号没装东西」。
+     */
+    unavailableText?: string | null;
+    emptyText: string;
+    /** 首页待选模式：开关的语义是"待选"，不是"已经启用"。 */
+    draft?: boolean;
+}
+/**
+ * 连接器面板里的插件列表。
+ *
+ * 首页与会话共用同一份渲染：开关是开关，候选是候选，行的存在与状态无关——
+ * 没启用、没图标也要显示名称和占位，不隐藏整行。
+ */
+export declare function PluginConnectorList({ client, sessionId, items, inFlight, busy, mutationError, onToggle, onRetry, onEditConfig, configuring, onConfigSaved, onConfigClose, disabledReason, unavailableText, emptyText, draft, }: PluginConnectorListProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/SessionPluginIcon.d.ts

@@ -1,7 +1,11 @@
 import type { BladeClient, SessionPlugin } from "@blade-hq/agent-client";
 export interface SessionPluginIconProps {
     client: BladeClient;
-    sessionId: string;
+    /**
+     * 会话内已准备的包。传 `null` 时改用账号级目录图标（`/api/plugins/{name}/icon`），
+     * 这样首页这种还没有会话的地方也能显示包内图标。
+     */
+    sessionId: string | null;
     plugin: Pick<SessionPlugin, "name" | "icon">;
     className?: string;
 }

package/dist/components/connector-panel-types.d.ts

@@ -0,0 +1,35 @@
+import type { PluginConnectorItem } from "./plugin-connector";
+/**
+ * 首页选中的一个待选插件。
+ *
+ * 带上展示名和图标是为了两件事：后续的配置弹窗与失败提示能一直用业务名（只传技术
+ * ID 的话，用户在面板里看到「示例登录」、在弹窗标题里看到 `demo-login`，等于要他认
+ * 两遍），以及不用打开面板就能在触发器上看到自己选了什么。
+ *
+ * 技术 ID 仍是路径、授权、缓存与调用的权威。
+ */
+export interface PluginConnectorSelection {
+    name: string;
+    displayName: string | null;
+    icon: string | null;
+    iconSource: PluginConnectorItem["iconSource"];
+}
+/** 面板一行 → 待选条目。 */
+export declare function selectionFromItem(item: PluginConnectorItem): PluginConnectorSelection;
+/** 触发器上最多直接显示几个插件图标，其余折成数量。 */
+export declare const TRIGGER_ICON_LIMIT = 3;
+/** 触发器要显示的内容：要么是若干图标加一个数量，要么是一个通用图标。 */
+export interface TriggerSummary {
+    icons: Array<Pick<PluginConnectorSelection, "name" | "icon" | "iconSource">>;
+    /** 超出 TRIGGER_ICON_LIMIT 的数量；0 表示不显示角标。 */
+    overflow: number;
+    /** 已选/已启用的总数，用于无障碍标签与提示。 */
+    total: number;
+}
+/**
+ * 把一份插件列表折成触发器上的显示内容。
+ *
+ * 图标 token 为空的项不占图标位——占位图标连成一排只会让人误以为自己选了三个
+ * 不同的东西；它们仍计入数量。
+ */
+export declare function triggerSummary(items: Array<Pick<PluginConnectorSelection, "name" | "icon" | "iconSource">>): TriggerSummary;

package/dist/components/plugin-connector.d.ts

@@ -0,0 +1,41 @@
+import type { PluginCatalogEntry, SessionPlugin, SessionPluginConfigSummary } from "@blade-hq/agent-client";
+/**
+ * 连接器面板里的一行插件。
+ *
+ * 展示字段（名称、图标）和启用状态分开表达：目录接口在没有会话时也能给出名称与
+ * 图标，而「这次会话是否启用」只有会话接口知道。首页候选行恒为 `active: false`，
+ * 因为它只是待选，不代表已经激活。
+ */
+export interface PluginConnectorItem {
+    name: string;
+    display_name: string | null;
+    /** 图标 token；null 时显示统一占位，不隐藏整行。 */
+    icon: string | null;
+    /** 图标从哪个接口取：账号级目录，还是会话内已准备的包。 */
+    iconSource: "account" | "session";
+    installed: boolean | null;
+    /** 会话里已提交的选择；首页候选恒为 false。 */
+    active: boolean;
+    status: string;
+    reason?: string | null;
+    config?: SessionPluginConfigSummary;
+    projected: boolean;
+}
+/** 首页候选：只有账号级目录，没有会话状态。 */
+export declare function catalogToConnectorItems(catalog: PluginCatalogEntry[]): PluginConnectorItem[];
+/**
+ * 会话列表叠加账号目录。
+ *
+ * 目录可用时展示字段以目录为准（包可能还没准备，会话列表拿不到名称和图标），
+ * 目录不可用时退回会话行自己的字段，这样已选插件仍然可以取消。
+ */
+export declare function mergeConnectorItems(sessionPlugins: SessionPlugin[], catalog: PluginCatalogEntry[] | null): PluginConnectorItem[];
+/**
+ * 一行的配置说明文案；权威状态来自配置接口。
+ *
+ * `unchecked` 刻意没有文案：列表没有读过用户的 Home，说任何话都是噪音，
+ * 入口是开关本身。
+ */
+export declare function pluginConnectorSummary(state: string | undefined): string | null;
+/** 按名称和显示名做本地过滤；空查询返回全部。 */
+export declare function filterConnectorItems(items: PluginConnectorItem[], query: string): PluginConnectorItem[];

package/dist/components/use-session-plugin-activation.d.ts

@@ -0,0 +1,40 @@
+import type { BladeClient, SessionPluginActivation, SessionPluginConfigState } from "@blade-hq/agent-client";
+import type { ConfiguringPlugin } from "./PluginConnectorList";
+import { type PluginConnectorItem } from "./plugin-connector";
+export interface UseSessionPluginActivationResult {
+    items: PluginConnectorItem[];
+    loading: boolean;
+    /** 插件列表本身读不到（Hub 不可用等），已有选择仍然可取消。 */
+    listError: boolean;
+    /** 某次启用/停用/准备失败了。 */
+    mutationError: boolean;
+    /** 正在为哪些插件提交意图；对应的开关在转圈，但仍然可点（点是取消）。 */
+    inFlight: Record<string, true>;
+    busy: boolean;
+    configuring: ConfiguringPlugin | null;
+    reload: () => void;
+    toggle: (item: PluginConnectorItem, next: boolean) => void;
+    retry: (item: PluginConnectorItem) => void;
+    editConfig: (item: PluginConnectorItem) => void;
+    onConfigSaved: (state: SessionPluginConfigState) => void;
+    onConfigClose: () => void;
+}
+/**
+ * 会话内插件启用的唯一实现。
+ *
+ * 顺序是「先准备配置，再提交 activation」：缺配置时开关不落到已启用、立刻弹表单，
+ * 保存成功才提交；取消、校验失败、配置读取失败都不提交。绝不先持久化 active=true
+ * 再靠补偿关掉——那样用户下次刷新会看到一个从没被成功打开的插件。
+ *
+ * 停用仍然直接提交：在服务端它只是取消一条数据库选择，不准备包、不连 MCP。但如果
+ * 这次「启用」只是还在准备、压根没提交过 activation，取消就只是放弃本地意图。
+ *
+ * 所有异步响应都按 (lifetime, mutation) 校验：迟到的准备或激活结果不会把已经取消 /
+ * 已经切走会话的插件重新打开；反过来，旧响应发现服务端落库顺序与用户最新意图不同时，
+ * 会重新提交最新意图。
+ */
+export declare function useSessionPluginActivation({ client, sessionId, onChange, }: {
+    client: BladeClient;
+    sessionId: string;
+    onChange?: (plugin: SessionPluginActivation) => void;
+}): UseSessionPluginActivationResult;

package/dist/embed/entry.d.ts

@@ -52,7 +52,8 @@ declare const BladeAgent: {
     computerState: typeof agentClient.computerState;
     sortComputers: typeof agentClient.sortComputers;
     ModelsResource: typeof agentClient.ModelsResource;
-    ChatProjectsResource: typeof agentClient.ChatProjectsResource;
+    ChatGroupsResource: typeof agentClient.ChatGroupsResource;
+    PluginsResource: typeof agentClient.PluginsResource;
     hasChatRunEvent: typeof agentClient.hasChatRunEvent;
     buildMessageContent: typeof agentClient.buildMessageContent;
     chatErrorForDisplay: typeof agentClient.chatErrorForDisplay;
@@ -113,7 +114,7 @@ declare const BladeAgent: {
         workspace_path?: string | null | undefined;
         ba_version?: string | null | undefined;
         sandbox_version?: string | null | undefined;
-        chat_project_id?: string | null | undefined;
+        chat_group_id?: string | null | undefined;
         match?: unknown;
     }, {}>;
     SessionStatus: import("arktype/internal/variants/string.ts").StringType<"completed" | "created" | "failed" | "interrupted" | "running" | "waiting_for_input", {}>;

package/dist/index.d.ts

@@ -10,6 +10,16 @@ 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";
+export { ConnectorPanel } from "./components/ConnectorPanel";
+export type { ConnectorPanelProps } from "./components/ConnectorPanel";
+export { PluginConnectorList } from "./components/PluginConnectorList";
+export type { ConfiguringPlugin, PluginConnectorListProps } from "./components/PluginConnectorList";
+export { useSessionPluginActivation } from "./components/use-session-plugin-activation";
+export type { UseSessionPluginActivationResult } from "./components/use-session-plugin-activation";
+export { catalogToConnectorItems, filterConnectorItems, mergeConnectorItems, pluginConnectorSummary, } from "./components/plugin-connector";
+export type { PluginConnectorItem } from "./components/plugin-connector";
+export { selectionFromItem, triggerSummary, TRIGGER_ICON_LIMIT } from "./components/connector-panel-types";
+export type { PluginConnectorSelection, TriggerSummary, } from "./components/connector-panel-types";
 export { SessionPluginSelector } from "./components/SessionPluginSelector";
 export type { SessionPluginSelectorProps } from "./components/SessionPluginSelector";
 export { SessionPluginIcon, sessionPluginLabel } from "./components/SessionPluginIcon";