@blade-hq/agent-client 2612.0.0-beta.4 → 2612.0.0-beta.6

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` 不一定和目标环境跑的版本一致。
@@ -697,3 +699,27 @@ chat.renderers = {
 - **消息**：`ChatMessage`、`MessageContent`、`MessageContentPart`、`TextContentPart`、`ImageUrlContentPart`、`FileContentPart`、`ToolCallInfo`、`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` 注册机制。知识库的 `kbIds` 选择行为保持不变。
+
+
+主题类型：`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` 保存引用编号、原文、插件包摘要及具体调用身份；历史查看直接使用该字段，插件停用或卸载后仍可核查当时内容。