@blade-hq/agent-client 2612.0.0-beta.1 → 2612.0.0-beta.11

package/README.md

@@ -12,6 +12,8 @@ Blade Agent 的框架无关客户端。浏览器和 Node.js 都能用；用 Vue
 npm install @blade-hq/agent-client
 ```
 
+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` 不一定和目标环境跑的版本一致。
@@ -158,6 +160,35 @@ const index = await client.sessions.getSessionTurnIndex(id) // SessionTurnIndex
 const first = index.items[0] // SessionTurnIndexItem
 ```
 
+创建会话时可以绑定 Streamable HTTP MCP 来源；BA 会在创建成功前读取并保存工具列表，
+来源此时必须可访问且接受创建请求中的 Bearer 凭据。之后沿用已发现的工具目录，
+刷新来源时更新目录。默认 `exposure: "lazy"` 通过 `plugin_list`、`plugin_inspect`、
+`plugin_run` 发现和调用工具；`exposure: "eager"` 会将 `include_tools` 允许的工具和完整
+参数 schema 直接加入执行模式的模型工具列表，无需先 inspect。`eager_tools` 可在 lazy
+来源中选出直接暴露的工具，也可指定 eager 来源中的优先工具。主运行和子智能体使用相同
+策略，计划模式不加载。直接工具的名称为 `mcp_<来源>__<工具>_<hash>`，调用仍经 Go MCP
+dispatcher。会话 MCP 的可用工具名称按来源注入 `plugin_catalog`，lazy 工具完整 schema
+仍由 `plugin_inspect` 按需读取。每个运行最多直接加载 32 个工具、64 KiB 完整工具定义；
+超预算的工具仍可通过
+`plugin_inspect/plugin_run` 使用。
+Bearer 凭据只在创建或轮换时提交，查询不会返回它：
+
+```ts
+const sessionToken = "由适配器签发的会话令牌"
+const { session_id } = await client.sessions.createSessionWithRequest({
+  intent: "飞书对话",
+  mcp_sources: [{
+    id: "feishu",
+    url: "https://adapter.example.com/mcp",
+    bearer_token: sessionToken,
+    eager_tools: ["send_files"],
+  }],
+})
+```
+
+工具集合由创建请求确定，后续 `session.send()` 沿用它。查询来源和轮换凭据的 REST 接口见 Swagger；轮换时传入 `null` 可撤销某来源凭据。
+`skip_confirmations: true` 会让该会话的普通轮次直接执行工具，适合由接入方自行承接交互的渠道会话。
+
 `SessionTurnsQuery` 的 `before` 与 `fromEntryId` 互斥；定位命中不了当前分支时服务端返回
 404 / 409，而不是空窗口。目录的 `entryId` 与 `/turns` 的 `turn_id` 同源，可直接当 `before` 游标。
 
@@ -669,10 +700,34 @@ chat.renderers = {
 - **声明式会话**：`SessionDefinition`、`SolutionDefinition`、`SkillDefinition`、`SkillFile`、`SessionConfig`、`TextFile`、`SessionSetupError`、`SessionSetupStage`
 - **会话消息队列**：`SessionQueueSnapshot`、`QueuedMessage`、`QueuedMessageStatus`、`QueueOperationResult`
 - **页面协作**：`CommandHandler`、`BladeChatMountRenderers`、`MountRenderer`、`MountRendererObject`、`MountResult`、`MountHandle`
-- **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`PaginatedSessionsResult`、`SessionInfo`、`SessionStatus`、`SessionDetail`、`DEFAULT_REPLAY_SPEED`、`ReplaySpeed`、`ReplayState`、`SessionTurnsPage`、`SessionTurnsQuery`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`AppCliDefinition`、`AppCliAttachment`
+- **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`McpSourceConfig`、`PaginatedSessionsResult`、`SessionInfo`、`SessionStatus`、`SessionDetail`、`DEFAULT_REPLAY_SPEED`、`ReplaySpeed`、`ReplayState`、`SessionTurnsPage`、`SessionTurnsQuery`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`AppCliDefinition`、`AppCliAttachment`
 - **模型目录**：`ModelsResource`、`ModelCatalog`、`ModelOption`
 - **远程电脑**：`ComputersResource`、`SessionComputer`、`AccountComputer`
 - **Headless**：`HeadlessResource`、`RunOptions`、`RunResult`、`RunTrace`
-- **消息**：`ChatMessage`、`MessageContent`、`MessageContentPart`、`TextContentPart`、`ImageUrlContentPart`、`FileContentPart`、`ToolCallInfo`、`MemoryRefInfo`、`getTextContent`、`getImageParts`、`getFileParts`、`contentPreview`、`groupMessagesByLoop`、`chatErrorForDisplay`、`transformSlashCommand`、`SkillMentionAvailability`、`userFacingErrorText`
+- **消息**：`ChatMessage`、`MessageContent`、`MessageContentPart`、`TextContentPart`、`ImageUrlContentPart`、`FileContentPart`、`ToolCallInfo`、`WorkflowStepInfo`(固定流程运行时每步的留档，挂在 `workflow:run` 的 `ToolCallInfo.workflow_steps` 上)、`MemoryRefInfo`、`getTextContent`、`getImageParts`、`getFileParts`、`contentPreview`、`groupMessagesByLoop`、`chatErrorForDisplay`、`transformSlashCommand`、`SkillMentionAvailability`、`userFacingErrorText`
 
 会话列表和详情的 `SessionInfo.initiator` 表示首次发起来源：`ui` 为界面，`sdk` 为 SDK；旧会话缺少可靠记录时为 `unknown`，尚未发起会话时为 `null` 或未提供。它不等同于后台运行标记 `is_headless`，后续继续会话不会改变来源。
+
+## 主题协作与资产引用
+
+`client.chatGroups` 保持既有资源名称和 `/api/chat-groups` 路径，界面称为“主题”。
+列表新增 `role`（`owner` / `editor` / `viewer`）和 `member_count`；`session_count` 仅表示当前用户自己的会话数。
+
+- `listMembers` / `addMembers` / `updateMember` / `removeMember` 管理成员。只有所有者可以邀请、改角色或移除他人；普通成员可移除自己以退出。
+- `listTasks` / `createTask` / `updateTask` / `deleteTask` 管理任务。`createTask` 的 `start_agent: true` 由服务端创建提交者的私人会话并开始处理。启动失败时任务仍保留，接口返回错误，不应盲目重建任务。
+- `listAssets` / `readAsset` / `uploadAsset` / `createAssetFolder` / `deleteAsset` 访问平台资产；`submitSessionAsset` 将当前用户的沙盒会话文件复制到资产。所有请求仍由服务端鉴权。
+- `session.send(text, { topicAssetRefs: [{ topic_id, path }] })` 为本条消息选择资产；省略时不继承上一条选择。服务端重新解析元数据，通过 Context 提供拉取指引，不自动读取正文。
+- `ChatMessage.topic_asset_refs` 是实时与历史一致的展示引用，不能当作访问许可。主题成员不会因此获得其他成员的会话读取权；任务的 `session_id` 只返回给该会话所有者。
+
+资产引用目前是专用字段，不依赖通用 `context_refs` 注册机制。
+
+
+主题类型：`ChatGroup`、`ChatGroupRole`、`ChatGroupMember`、`ChatGroupTask`、`CreateChatGroupTask`、`UpdateChatGroupTask`、`ChatGroupAsset`、`ChatGroupAssetList`、`TopicAssetRef`。`normalizeTopicAssetRefs` 仅规范化展示引用并去重，不代替服务端鉴权。
+
+### 插件条目选择
+
+`PluginRef` 保存 `{ provider: "plugin", plugin, server, id, label }`，`normalizePluginRefs(value)` 按插件、服务和条目 id 去重。label 只用于展示，条目权限和全文由服务端按当前账号重新读取。
+
+`session.send(text, { refs })` 选择本轮条目；不传 refs 继承上一轮选择，`refs: []` 清除，新的数组替换。AskUser 和暂停续跑沿用本轮冻结内容，下一条新消息才重新读取。流式消息和历史消息都保留 `message.refs`。
+
+`ToolEvidence` 是工具调用的原文快照类型。`ToolCallInfo.evidence` 保存引用编号、原文、插件包摘要及具体调用身份；历史查看直接使用该字段，插件停用或卸载后仍可核查当时内容。