div-anthropic D3: 评估 claude-agent-sdk / sandbox-runtime / mcpb 三个 Anthropic/MCP 依赖的解耦可行性

[dahai80]

背景

feat/div-anthropic 分支 Phase 5 完成了 @anthropic-ai/sdk 错误层解耦 (commits 93bf783→8a31408,编译后二进制 0 处 SDK 错误类引用)。但 fusion-code 的 package.json 还依赖另外三个 Anthropic/MCP 运行时包,原始 Phase 6 计划提到要为它们评估解耦:

"@anthropic-ai/claude-agent-sdk": "^0.2.87",   // print.ts:132 — 纯 import type (编译期擦除)
"@anthropic-ai/sandbox-runtime": "^0.0.44",     // 沙箱执行
"@anthropic-ai/mcpb": "^2.1.2",                 // MCP 插件桥

逐包审计

1. @anthropic-ai/claude-agent-sdk — 仅类型,可立即降级

• src/cli/print.ts:132 import type { PermissionMode } from "@anthropic-ai/claude-agent-sdk" — 编译期擦除,build 后无运行时引用。
• src/services/mcp/client.ts:501 仅是注释里的 issue 链接,非代码。
• 结论: 移到 devDependencies 即可,不影响运行时。可与 div-anthropic D2: package.json 移除/降级 SDK 依赖 (受 #63 阻塞) #64 D2 合并处理。

2. @anthropic-ai/sandbox-runtime — 运行时沙箱

• src/utils/sandbox/sandbox-adapter.ts 等引用。
• 需评估: 沙箱执行是否可改用本地原生方案 (如 fusion-cli 的 Rust 沙箱),还是 Anthropic sandbox-runtime 提供不可替代能力。
• 跨仓约束: sandbox-runtime 是上游包,不能改其源码;解耦=找替代或自实现等价层。

3. @anthropic-ai/mcpb — MCP 插件桥

• src/utils/plugins/mcpbHandler.ts、src/utils/plugins/mcpPluginIntegration.ts、src/Tool.ts 等多处引用。
• 需评估: mcpb 提供的 MCP 插件打包/分发能力是否可由 @modelcontextprotocol/sdk (已在依赖) 直接覆盖,还是 mcpb 有独有功能。

待办

本 issue 是评估/追踪性质,非立即实现。每个包需单独决策:

• claude-agent-sdk: 确认纯类型 → 合并入 div-anthropic D2: package.json 移除/降级 SDK 依赖 (受 #63 阻塞) #64 D2 降级 devDeps
• sandbox-runtime: 评估替代方案或标记为接受的运行时依赖
• mcpb: 评估能否仅用 @modelcontextprotocol/sdk 覆盖,或标记为接受

关联

• div-anthropic D1: client.ts 云 provider 解耦 — 决定 seam 是否覆盖 bedrock/vertex/foundry 签名 #63 D1 (client.ts 云 provider)
• div-anthropic D2: package.json 移除/降级 SDK 依赖 (受 #63 阻塞) #64 D2 (package.json SDK 移除)
• 本 issue 是 div-anthropic 的范围扩展评估,不阻塞 D1/D2。

[dahai80]

调查结论：#65 — claude-agent-sdk / sandbox-runtime / mcpb 解耦可行性

逐个包调查源码与 fusion-code 内用法，结论如下。

---

1. @anthropic-ai/claude-agent-sdk — ✅ 可立即解耦（移到 devDependencies）

现状：package.json:32 "^0.2.87"，但 fusion-code 内仅 1 处引用，且为 import type：

• src/cli/print.ts:132 — import type { PermissionMode } from "@anthropic-ai/claude-agent-sdk"
• src/services/mcp/client.ts:501 — 只是注释里的 issue 链接，无实际引用

验证：

• import type 在 Bun build（DCE）下被擦除，不进入运行时。
• 该包 main: "sdk.mjs" 确实有运行时代码，但 fusion-code 从未做值导入，所以运行时从不加载它。

建议：将 @anthropic-ai/claude-agent-sdk 从 dependencies 移到 devDependencies（仅 typecheck 需要）。二进制体积零影响，运行时零影响。低风险，可立即做。

---

2. @anthropic-ai/sandbox-runtime — ⚠️ 不建议解耦（高耦合、安全核心、无替代）

现状：package.json:35 "^0.0.44"，src/utils/sandbox/sandbox-adapter.ts 深度包装它，被 11 处引用（main.tsx、BashTool/*、PowerShellTool、WebSearchTool、networkDomainCheck 等）。

依赖关系：

• sandbox-adapter.ts 值导入 SandboxManager、SandboxViolationStore、SandboxRuntimeConfigSchema 等 10+ 符号，不是 type-only。
• SandboxManager 内部按平台 spawn：macOS → sandbox-exec（系统自带），Linux → bwrap + socat 代理 + seccomp filter。这是一整套 OS 级沙箱，不是纯 JS。
• 包带 vendor/seccomp/（预编译 seccomp BPF 工具）、bin: srt（CLI）。

为何不建议解耦：

1. 无替代。它是 Claude Code 官方沙箱运行时，封装了 sandbox-exec/bwrap 的 profile 生成、违规存储、网络代理。重写 = 重新实现一套安全沙箱，违背 Rule 2（Simplicity First）与跨仓库规则（安全逻辑属上游）。
2. 安全敏感。沙箱出错 = 权限泄漏。自己重写风险高于收益。
3. 它本就不是 @anthropic-ai/sdk 的一部分。div-anthropic 的目标是去 SDK 依赖，sandbox-runtime 是独立包，与 LLM SDK 无耦合，不在本次解耦范围。
4. 构建侧：它不在 externals，被编译进二进制（strings fusion-code-dev | grep sandbox-runtime 命中），但它是纯 JS + spawn 系统命令，无 native addon，编译无问题。

建议：保留。如未来要瘦身，方向是"按需加载"（仅在启用沙箱时 await import），而非移除依赖。

---

3. @anthropic-ai/mcpb — 🟡 可部分优化，但暂不移除依赖

现状：package.json:34 "^2.1.2"，src/utils/plugins/mcpbHandler.ts 内仅 1 处值引用，且已是懒加载：

• mcpbHandler.ts:422 — const { getMcpConfigForManifest } = await import("@anthropic-ai/mcpb")（唯一运行时引用）
• 其余对 mcpb 的引用都是本地的 McpbManifestAny 类型别名（注释说明 zod 推断问题，没用包导出的类型）

构建侧：scripts/build.ts:122 已把 @anthropic-ai/mcpb 列入 externals → 不编译进二进制，运行时按需 import（需 mcpb 已安装）。这已是正确做法。

mcpb vs @modelcontextprotocol/sdk：

• 二者不重叠。@modelcontextprotocol/sdk 是 MCP 协议传输层（fusion-code 在 Tool.ts、mcp/client.ts、10+ 处用它跑 MCP server/client）。
• mcpb 是 MCPB 打包格式（.mcpb/.dxt 扩展）的解析器：解 zip、读 manifest、把用户配置灌进 server config。它依赖 zod（~700KB，懒加载注释里已说明为何 lazy）。
• fusion-code 用 @modelcontextprotocol/sdk 跑 MCP，用 mcpb 加载 MCPB 格式插件。功能正交，不能互替。

为何暂不移除依赖：

• 唯一引用已是懒加载 + externals，运行时开销为零（不装插件就不加载）。
• 移除依赖 = 丢失 MCPB 插件支持，是功能倒退。
• 若要进一步瘦身，可考虑把 mcpb 也做成 optionalDependencies（仅启用插件系统时需要），但当前 externals + lazy import 已达到同等效果。

建议：保留，现状最优。可选的后续优化：标注 optionalDependencies，让不需要插件的用户 bun install --no-optional 跳过。

---

汇总

包	引用方式	运行时加载	解耦可行性	建议
claude-agent-sdk	import type 仅 1 处	否（DCE 擦除）	✅ 高	移到 devDependencies，立即做
sandbox-runtime	值导入 10+ 符号，11 处引用	是（编译进二进制）	❌ 低	保留，安全核心无替代
mcpb	懒加载 1 处 + externals	否（按需）	🟡 中	保留，可降级 optionalDependencies

落地优先级

1. 立即：claude-agent-sdk → devDependencies（零风险，可随 PR feat(div-anthropic): LLM 接缝 + 错误层脱离 @anthropic-ai/sdk (Phase 1-6) #66 一起做）。
2. 可选：mcpb → optionalDependencies（低风险，文档说明插件系统依赖）。
3. 不做：sandbox-runtime 解耦（高风险、无收益、越出 div-anthropic 范围）。

本评估为只读调查，不改 fusion-code 代码；落地动作（第 1 项）待 PR #66 测试合并后单独提交。

[dahai80]

PR #66 已合并到 main (ed892e1)。本 issue (#65) 为后续评估: claude-agent-sdk 可移至 devDependencies (零风险项) + sandbox-runtime 评估。作为独立后续任务保留。