开发工具代码编辑器数据科学【免费下载链接】positronPositron, a next-generation data science IDE项目地址https://gitcode.com/gh_mirrors/po/positron点击查看免费下载导读本文以 phase10-plan.md 这份实现计划文档为主线完整拆解 PositronVS Code 系数据科学 IDEagentHost 平台层中客户端工具Client-provided Tools这一特性的设计决策与最终落地。你将掌握IAgent.setClientTools/IAgent.onClientToolCallComplete的完整调用链、JSON Schema → Zod 转换器、基于PendingRequestRegistry的延迟回调机制、工具集变更触发 yield-restart 的流程以及子代理subagent场景下的路由与并发去重策略——既可直接指导二次开发也可作为阅读 agentHost 源码 的路线图。1. 特性背景为什么需要客户端工具在 Positron 的 agentHost 架构中Claude Agent 会话由ClaudeAgent类托管并通过anthropic-ai/claude-agent-sdk下称 SDK与模型通信。SDK 默认只能使用内置工具Read / Write / Bash 等而工作台workbench侧的客户端——例如数据面板、连接器、自定义扩展——往往需要把自己的工具暴露给模型调用。Phase 10 的目标就是打通这条通道让工作台客户端通过IAgent.setClientTools(session, clientId, tools)注册自定义工具这些工具经 SDK 的Options.mcpServers走in-process MCP进程内 MCP路径暴露给 Claude模型调用工具后再由IAgent.onClientToolCallComplete(session, toolCallId, result)把结果回填给 SDK。文档明确指出这一行为与 Copilot Agent 已具备的能力对齐参见 copilotAgent.ts:943-954 的子代理路由参照。从最终状态看Phase 10 已全部落地计划文档标记为DONE1833 个 agentHost 测试通过E2E 验证了会话恢复resume后持久化的client__*MCP 工具往返可见于 Agents 窗口。2. 核心概念与协议层定义2.1 ToolDefinition客户端工具的统一描述客户端工具以ToolDefinition描述定义于 channels-session/state.ts:594-630name唯一工具标识title/description展示名与功能描述inputSchemaJSON Schematype: objectpropertiesrequired描述输入参数可选——客户端工具可以没有正式 SchemaoutputSchema输出结构定义annotations/_meta行为提示与附加元数据镜像 MCP 约定。计划文档强调inputSchema是窄化的 JSON Schema 子集仅object/properties/required这正是后面手写 JSON Schema → Zod 转换器而非引入第三方库的决策依据。2.2 工具调用结果ToolCallResult工作台完成工具调用后通过ToolCallResult定义于 channels-chat/state.ts:1251-1269返回结果字段包括success是否成功pastTenseMessage对工具行为的过去式描述content非结构化内容块数组镜像 MCPCallToolResult.contentstructuredContent结构化结果对象镜像 MCPstructuredContenterror失败时的错误信息。内容块类型由ToolResultContentType枚举channels-chat/state.ts:1466-1473区分text、embeddedResource、resource、fileEdit、terminal、subagent。其中embeddedResource携带 Base64 编码的data与contentType如image/png、application/pdf——这一形态与 MCP 的resource块存在 1:1 之外的结构差异是结果转换器的主要工作点详见第 6 节。3. 总体架构与设计决策3.1 状态归属挂在会话对象上而非新增旁路 Map计划文档记录了一个重要的委员会裁决council findingclientTools状态不以ClaudeClientToolRegistry按 sessionId 键控的 Map形式挂在ClaudeAgent上而是直接存放在已有的 per-session 对象上物化materialize前暂存于IClaudeProvisionalSession.clientTools物化后转移到ClaudeAgentSession的toolDiff模型上与model/permissionMode的转移模式一致。这样避免了在_provisionalSessions和_sessions之外引入第三张平行 per-session Map会话清理自动复用ClaudeSessionEntry.dispose()/ provisional 删除路径无需显式.clear(sessionId)。3.2 构造顺序先建协作者再建 MCP Servercouncil finding C1进程内 MCP server 的tool()处理器闭包会捕获会话的_pendingClientToolCalls延迟注册表与 bridgeClaudeToolUseIdBridge。为避免server 先建、session 后建、闭包捕获了错误实例的顺序陷阱ClaudeAgentSession的构造函数显式接收这两个协作者claudeAgentSession.ts:444-445它们在物化前就由 agent 侧构建完毕MCP server 的处理器闭包由此绑定到会话最终持有的同一批实例。3.3 一次只暴露一个 in-process MCP server协议层一个会话最多只有一个活跃客户端见 agentSideEffects.ts 的活跃客户端管理setClientTools(session, clientId, tools)是对该客户端工具片段的整体替换full replacement不支持多客户端合并。因此 Phase 10 只注册一个名为client的 in-process MCP server——常量CLAUDE_CLIENT_MCP_SERVER_NAME client定义于 claudeClientToolMcpServer.ts:85。3.4 与 Phase 11 的边界Query.setMcpServers运行时热替换外部 HTTP MCP server属于Phase 11Phase 10 只在启动时写Options.mcpServers计划文档还纠正了路线图的一处偏差生产扩展的_gateway字段是 VS CodeMcpGateway适配器暴露外部编辑器 MCP server与进程内工具createSdkMcpServer无关因此 Phase 10不做 gateway / idle timeout生命周期管理setClientCustomizations/reloadPlugins同样划归 Phase 11。4. 注册与调用完整调用链4.1 注册入口setClientTools工作台客户端通过IAgent.setClientTools(chat, clientId, tools)注册工具。在ClaudeAgent中注册经由活跃客户端句柄ClaudeActiveClientHandle转发getOrCreateActiveClient创建句柄时注入回调内部调用_findChatByUri(targetChat)?.setClientTools(client.clientId, tools)claudeAgent.ts:2465并记录日志。活跃客户端移除时removeActiveClient则调用target.removeClientTools(clientId)清空该客户端贡献的工具claudeAgent.ts:2484。会话侧的实现claudeAgentSession.ts:1355-1367是薄封装最终写入SessionClientToolsModelsetClientTools(clientId: string, tools: readonly ToolDefinition[]): void { this.toolDiff.model.setTools(clientId, tools); }多客户端语义SessionClientToolsModel内部用ActiveClientToolSet按clientId分别保存贡献对外暴露合并视图mergedclaudeSessionClientToolsModel.ts:28-59——按工具name去重、先插入的客户端胜出并可通过ownerOf(toolName)把工具调用路由回贡献方客户端。merged是IObservable且其equalsFn使用structuralToolsEqualname description inputSchema的结构化比较因此结构完全相同的重复提交不会触发下游订阅者claudeSessionClientToolsModel.ts:31-35。4.2 物化时注入 Options.mcpServers每次materialize/resume/ yield-restart 时agent 都会基于当前合并快照构建全新的Options.mcpServers经物化器写入 SDK 启动选项。预物化provisional阶段的注册会在第一次物化时生效——这是转移即物化transfer-at-materialize语义。一个值得注意的细节是 C6 裁决物化完成后转移的必须是构建 MCP server 时使用的同一快照而非重新读取provisional.clientTools因为setClientTools不经过会话序列器sequencer重新读取可能观察到更新的快照 Y而 SDK 实际以快照 X 启动。SessionClientToolsDiff.consume()的设计正是为此服务详见 5.2。4.3 模型调用MCP tool() handler 与 tool_use_id 的找回SDK 的tool()处理器签名是(args, extra: unknown)不直接携带tool_use_id——这是计划阶段经 SDK 源码sdk.mjs验证过的事实也是整个 Phase 10 最核心的风险点见第 8 节 Risks。落地后的实现claudeClientToolMcpServer.ts:36-60找到了一个更简洁的方案SDK 0.2.128 会在extra._meta[claudecode/toolUseId]命名空间键下携带原始tool_use_id由extractToolUseId提取const toolUseId extractToolUseId(extra); if (toolUseId undefined) { return { content: [{ type: text, text: ...SDK omitted tool_use_id... }], isError: true }; } return awaitResult(toolUseId);若未来 SDK 版本丢弃或改名该字段处理器返回错误结果而非死锁——降级路径显式可观测。awaitResult回调由调用方注入本实现中解析为会话持有的_pendingClientToolCalls上的延迟对象。每个工具经由sdk.tool(name, description, jsonSchemaToZodRawShape(inputSchema), handler)注册随后打包进createSdkMcpServer({ name: client, tools })。该工厂是纯工厂pure factory不加载 SDK、无 I/OSDK 的懒加载导出由IClaudeAgentSdkService注入测试时可用FakeClaudeAgentSdkService替换。4.4 结果回填onClientToolCallComplete工作台完成调用后ClaudeAgent.onClientToolCallCompleteclaudeAgent.ts:2495-2508执行若chat本身是已解析的目标会话直接调用addressed.completeClientToolCall(toolCallId, result)否则通过resolveSubagentChatParent(context)解析子代理的父会话并回填子代理场景见第 7 节miss 时静默——因为agentSideEffects会转发每一个ChatToolCallComplete信封包括 SDK 自有工具未知 id 是预期路径绝不能抛异常。会话侧completeClientToolCallclaudeAgentSession.ts:1384-1387先把协议结果经convertToolCallResult转换为 MCPCallToolResult再respond(toolCallId, converted)解开延迟对象。5. 变更检测工具集 Diff 与 yield-restart5.1 为什么需要重启Options.mcpServers只在启动时生效startup-onlyPhase 10不使用Query.setMcpServers那是 Phase 11 的运行时热替换。因此客户端工具集一旦变化必须走 Phase 9 已有的_rebindQuery(restart)yield-restart 机制让 SDK 以新工具集重启。5.2 SessionClientToolsDiffdirty bit 驱动的预检claudeSessionClientToolsModel.ts:73-127 的SessionClientToolsDiff是变更检测的核心构造时通过autorun订阅model.merged观察量与_lastAppliedTools做结构化比较不同则置 dirty bitconsume()读取当前合并快照、清 dirty bit 并把快照记为已应用markDirty()强制置位——用于consume之后的下游工作SDK 重建失败时让 SDK 仍停留在旧快照的会话在下一次 sendMessage 重试初始autorun回调被跳过_ignoreNextFire避免全新 diff 在没有任何setTools之前就误报 dirty。这段设计正是计划文档中 C6 不变量setTools 与在途构建竞争时通过 autorun 重翻 dirty bit下一次 sendMessage 检测到陈旧集合并再次触发 rebind与rebind 失败 dirty bit 缺口修复的落地。5.3 sendMessage 预检rebind-or-forward互斥在sendMessageClaudeAgentSession.send中预检条件claudeAgentSession.ts:1060-1069把工具集差异与自定义项差异、MCP 启动启停版本、挂起的恢复会话、附加工作目录、传输模式切换等并列if (this.toolDiff.hasDifference || this.clientCustomizationsDiff.hasDifferenceFrom(this._desiredClientPluginPaths()) || ... ) { await this._rebindForSyncedState(); } else { await pipeline.setPermissionMode(resolveCurrentPermissionMode(...)); }两个分支互斥走 rebind 分支时跳过setPermissionMode转发因为 rebind 路径中 rematerializer 已重读实时 permissionMode且_rebindQuery尾部经_replayCurrentConfig重放双向状态claudeSdkPipeline.ts:397——rebind 后再次setPermissionMode是冗余的还可能记录一次虚假的调用。整个预检块保持在会话序列器内保证并发 send 折叠为一次 rebind 两次有序发送。_rebindForSyncedStateclaudeAgentSession.ts:1126-1130先rejectAll(CancellationError)拒绝所有挂起的客户端工具调用再rebindForRestart()_rebindQuery(restart)的窄化公开包装避免泄露私有方法最后触发自定义项变更信号。6. 结果类型转换ToolCallResult → CallToolResultconvertToolCallResult(result, toolUseId)claudeClientToolResult.ts:35-46是导出的独立函数按协议 → MCP1:1 映射并做形状变换协议内容块MCP 目标说明text{ type: text, text }直接映射embeddedResource且contentType以image/开头{ type: image, data, mimeType }字段改名 重新打包embeddedResource非图片{ type: resource, resource: { uri, mimeType, blob } }合成临时 URI未知块类型字符串化文本块 warn 日志有界爆炸半径error/successfalseisError: true透传structuredContent原样透传镜像 MCP 字段关键形状变换C5 裁决协议EmbeddedResource { data, contentType }并不与 MCP{ type: resource, resource: { uri, mimeType, blob|text } }1:1 对应——MCP 的 zod schema 拒绝无 URI 的 resource 块而协议数据没有自带 URI。因此实现合成临时的、每次调用唯一的 URIclaude-client://toolUseId/indexclaudeClientToolResult.ts:18-18、78该 URI 对双方都是不透明的模型永远不会解引用它。toolUseId嵌入 URI 使并行工具调用的块保持消歧。未知块类型Resource / FileEdit / Terminal / Subagent 等协议自有形状降级为字符串化文本块并console.warn——一次坏调用不是一次崩溃。7. 子代理路由与并发去重7.1 子代理共享父会话的 MCP serverClaude SDK 在父会话的Query子进程内运行子代理不新建Query因此Options.mcpServers天然共享——子代理与父会话调用同一个in-process MCP server处理器侧代码无需感知子代理。当工作台以子代理 URI 回复onClientToolCallComplete时Phase 10 通过resolveSubagentChatParent(context)实现中基于parseSubagentSessionUri迭代的 while 循环语义走到根会话在根会话的注册表中找到挂起的延迟对象镜像 copilotAgent.ts:943-954。计划文档特别强调嵌套子代理子代理的子代理需要迭代解析单次解析只能处理深度 1。7.2 同名同参并发调用的去重策略计划文档最初设计了ClaudeToolUseIdBridge以(toolName, canonicalStringify(args))为键做流事件与处理器入口的 rendezvous内部按parent_tool_use_id维护 FIFO 队列、优先同父匹配canonicalStringify递归排序对象键以保证 SDK 流事件解析出的input与处理器收到的 args 不因键序差异而失配。落地后的实现claudeClientToolMcpServer.ts走了一条更直接的路既然extra._meta直接携带tool_use_id处理器无需再做基于参数的匹配直接以tool_use_id为键在PendingRequestRegistry上注册延迟。计划文档记载的跨父 FIFO 按到达顺序结算断言因此被合并/简化——因为 MCP 处理器的resolve调用没有父 id 输入SDKtool()签名无父引用而tool_use_id由工作台回显每个物理调用仍能拿到正确种类的结果。父 id 仍在noteToolUseEvent时捕获并存储在PendingEvent上为未来实现真正的同父优先预留数据模型。并行同名同参调用由tool_use_id天然区分FIFO 匹配保证安全。7.3 PendingRequestRegistry延迟对象注册表common/pendingRequestRegistry.ts 是 Phase 7 权限往返已使用的原语Phase 10 复用于客户端工具registerAndFire(key, fire)原子地先注册再触发回调——防止同步响应者在 fire 之后才注册导致死锁Phase 7 踩过的坑register(key)纯注册并返回 promise适用于响应来自另一条代码路径的场景MCP 处理器由 SDK 调用、完成经工作台往返重复注册旧延迟被CancellationError拒绝以免泄漏respond(key, value)解开延迟并返回是否命中rejectAll(error)Phase 10 新增对每个挂起延迟调用.error(error)并清空 Map——与既有的denyAll用值 resolve面向权限拒绝路径语义区分。不变量会话 dispose 或 rebind 时_pendingClientToolCalls.rejectAll(new CancellationError())必须先于 Query 交换执行防止旧 Query 上的挂起调用泄漏到新 Queryrebind 路径claudeAgentSession.ts:1126-1130与 dispose 路径共享这一拒绝逻辑。8. 风险与防护Risks 的落地验证计划文档列出的关键风险在实现中均有对应防护tool()处理器拿不到tool_use_id——最初设计用ClaudeToolUseIdBridge做流事件 rendezvous最终验证 SDK 0.2.128 在extra._meta[claudecode/toolUseId]提供该 idextractToolUseId提取 缺 id 时降级错误结果两种方案都避免了死锁rematerializer 闭包捕获过期数据——闭包必须每次 rebind 重读实时状态而非物化时快照一次实现中 rematerializer 闭包重建 mcpServers 时读取session.clientTools分层违规——agentHost 位于 platform 层只依赖anthropic-ai/claude-agent-sdk与modelcontextprotocol/sdk类型无src/vs/workbench/反向依赖zod 版本不匹配——SDK 的AnyZodRawShape兼容 zod 3 与 4仓库根为zod3.x无需处理但实现为jsonSchemaToZodRawShape参数化了ZodFactory而非静态导入 zodzod 非根依赖、渲染侧测试环境无法解析裸 specifier工厂随createSdkMcpServer/tool一起经SdkExports注入。9. 测试与验证矩阵计划文档Steps 10 Implementation Notes展示了完整的测试策略全部落地于 test/nodeJSON Schema → Zod 转换器claudeJsonSchemaToZod.test.ts5 例空/未定义、原始类型 required/optional、数组/嵌套对象/enum/oneOf/null、nullable/description/default、逐属性z.any()回退结果转换claudeClientToolResult.test.ts6 例text、error、图片嵌入资源、非图片嵌入资源合成 URI、未知块回退、structuredContent 透传MCP server 工厂claudeClientToolMcpServer.test.ts4 例server 名为client、handler 经 bridge/registry 挂起、inputSchema 经注入的工厂转换、缺 description 回退会话模型claudeSessionClientToolsModel.test.ts合并视图、ownerOf 路由、dirty bit 生命周期注册表扩展rejectAll以指定错误结算所有挂起延迟并清空注册表集成测试claudeAgent.test.ts8 例注册流入Options.mcpServers、物化后触发 yield-restart、等快照不重启、未知会话静默丢弃、mid-materialize 竞争钉住构建期快照、子代理 URI 走根、dispose 拒绝挂起调用、FakeQuery.setMcpServers保持NotModeled证明 Phase 10 从不调用Query.setMcpServers。验证命令来自计划文档 Verification 节./scripts/test.sh --run src/vs/platform/agentHost/test/node/clientTools/claudeJsonSchemaToZod.test.ts ./scripts/test.sh --run src/vs/platform/agentHost/test/node/clientTools/claudeClientToolMcpServer.test.ts ./scripts/test.sh --run src/vs/platform/agentHost/test/node/claudeAgent.test.ts npm run typecheck-client npm run valid-layers-checkE2E 验收场景用launch技能启动带--agents的 Code OSS → 新建 Claude 会话 → 经协议session/activeClientToolsChanged注册一个最小工具如name: echo、inputSchema: { type:object, properties:{ msg:{ type:string }}, required:[msg] }→ 提示词要求模型调用该工具 → 用code-oss-logs技能核对 agent-host 日志中的[Claude] setClientTools与Options.mcpServers写入记录并在 chat 面板看到工具调用卡片随后修改工具 schema 再发一条消息验证第二次startup日志证明 yield-restart 生效。10. 已知局限Accepted, Not Blocking计划文档坦诚记录了三个被接受的局限二次开发时应留意活跃客户端切换产生两次 rebind工作台先setClientTools(prev, [])再setClientTools(new, [tool])且用户在两动作之间发消息时会触发两次重启。合并需要跨动作感知因只在客户端切换时发生、成本可接受而搁置rebind 间隙到达的 steering 消息被丢弃resetForRebind后队列无父节点Phase 9 的 steering 注入假设队列父节点存活——跨特性交互问题文档化待处理恢复路径的快照更新在常见场景是 no-op子进程崩溃到恢复之间若无setClientTools写appliedClientToolSnapshot无害保留是为了工具在恢复等待期确实变化时的正确性。11. 从源码继续深入计划全貌phase10-plan.md、roadmap.md工具注册与结果回填的会话编排claudeAgent.tsgetOrCreateActiveClient/onClientToolCallComplete会话状态与 diff 预检claudeAgentSession.ts四个独立测试友好的纯函数/工厂clientTools 目录延迟原语pendingRequestRegistry.ts流映射与消息路由tool_use事件线程化parent_tool_use_idclaudeMapSessionEvents.ts、claudeSdkMessageRouter.tsCopilot 参照实现copilotAgent.ts:935-954。一句话总结Phase 10 用会话对象自持状态 启动期注入Options.mcpServers sendMessage 预检 diff 触发 yield-restart PendingRequestRegistry延迟结算四件套把工作台客户端工具完整接入了 Claude Agent 的 in-process MCP 通道并且用纯函数独立可测、SDK 懒加载注入、未知 id 静默、坏块降级文本四个原则把复杂度约束在了可测试、可演进的范围之内。赞分享开发工具代码编辑器数据科学【免费下载链接】positronPositron, a next-generation data science IDE项目地址https://gitcode.com/gh_mirrors/po/positron点击查看免费下载相关推荐ProxySQL MCP 配置端点的受约束 SQL 查询工具从实现计划到源码落地的完整剖析ProxySQL MCP 配置端点的受约束 SQL 查询工具从实现计划到源码落地的完整剖析 本篇技术指南以仓库内的实现计划文档 2026 05 04 conf后端数据库负载均衡VS Code Agent Host 中 Claude 工具调用富渲染的落地Phase 8.5 与 Copilot 对齐的设计与实现VS Code Agent Host 中 Claude 工具调用富渲染的落地Phase 8.5 与 Copilot 对齐的设计与实现 导读 在 Visual开发工具代码编辑器从 2.0 到 2.3mcp-use/client TypeScript MCP 客户端的关键演进与技术剖析从 2.0 到 2.3 mcp use/client TypeScript MCP 客户端的关键演进与技术剖析 mcp use/client 是 mcp后端MCP 服务MCP ClientsAI Agent人工智能上一篇告别繁琐文件传输croc让两台电脑秒传文件的秘密下一篇ScreenTimeLapse完整教程从安装到高级设置的10个实用技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考