🔥 sdk: 死代码大扫除第二批——宿主旁路的五整块子系统 + 死 API 面（PR#283 续篇，~2000 行）

[CavinHuang]

严重度: P2（维护性/安全面）

PR#283 以「sidecar 是唯一宿主」为准绳删除了内置 providers。同一准绳贯穿全 SDK review，发现五整块宿主旁路的子系统与死 API 面仍留守（合计 ~2000+ 行）。均已逐条验证调用链。

A. 五整块子系统

块	位置	规模	证据
SDK 内置 MCP 链	agent.ts:536-595,1527-1639 + mcp/client.ts 全文件	~500 行	sidecar 不传 mcpServers/plugins，syncMcpConnections 循环体永不进入；sidecar MCP 走自己的 pluginMcpManager。注：#326、mcp/client.ts:126 的 elicitation 协议缺陷（读 params.type 恒 undefined，实际判别字段是 mode）随本块删除一并消失
SDK 插件装配链	plugins/loader.ts loadPlugins 簇(:355-477,251-305) + agent.ts:745-776 装配点 + hooks.ts:212-246,308-379 shell-hook	~250 行	loadPlugins(cwd,[],[]) 恒 []；sidecar 有自己的 plugin-registry + plugin-hooks-bridge（后者注释明说复制了 SDK 私有 executeShellHook）
AgentTool 嵌套 QueryEngine	tools/agent-tool.ts:175-550 + BUILTIN_AGENTS(:58-69) + registerAgents(:44-53)	~400 行	sidecar 两入口均 {...AgentTool, call: 自定义} 整体替换；splitDeferredTools 唯一活调用点(:226)随之死
sdk-mcp-server + tool-helper 簇	两文件主体	~140 行	createSdkMcpServer 全仓零调用（仅 README）；tool()/sdkToolToToolDefinition 唯一消费者是 sdk-mcp-server
死 API 面	QueryController 15 个委托方法(query-controller.ts:104-182 + agent.ts:1230-1246)；Agent 方法群 ~300 行（resumeInterruptedRun/discardInterruptedRun——sidecar 用导出的 detectDanglingToolUses 自建、mcp 控制、rewindFiles、stopTask 等）；session.ts 8 个导出函数(~180 行，sidecar 注释明说删会话不经 SDK)；顶层 query() 函数	~600 行	宿主只把 agent.query() 返回值当 AsyncIterable 迭代，控制操作全部直连 agent 实例

B. utils 死模块与死函数

• utils/context.ts 全文件 187 行：engine.ts:295 if (config.systemPrompt) 早退 + sidecar 恒传 systemPrompt 且自有 context-assembler → git 注入/AGENT.md 发现整模块不可达；连带 clearContextCache 进程级 memoize 永不失效的潜伏缺陷一并消失
• getAutoCompactThreshold/AUTOCOMPACT_BUFFER_TOKENS/calculateAutoCompactThreshold：与活路径 shouldAutoCompact 同名概念两套算法（死函数多减 13k/30k/50k buffer），误导性强
• getTokenCountFromUsage、getCachedTokens、createAgentProgressTracker（连带 types.ts:780 AgentProgressUsage + SDKResultMessage.progressUsage 字段）、isAuthError/isRateLimitError/formatApiError 三件套、createUserMessage/createAssistantMessage/extractTextFromContent/createCompactBoundaryMessage/truncateText、createFileStateCache：全仓零生产调用
• CODEANY_* env 读取链（与 [P2][sdk/agent] PR#283 遗留：auth_status 每 run 恒报 Missing API key，凭据展示链与 apiType 嗅探全部失真 #383 相邻但独立为 env 回退链本身）

C. index.ts 导出面收敛

408 个命名导出中 282 个（69%）宿主零引用。大量「内部自用仅导出面死」可先做一轮再导出修剪；lumeFileUrl/downloadAndLocalizeImages（index.ts:536-548 注释声称 sidecar 需要）实际零引用。

注意事项

• 删 bash.ts startDirectShellTask 直连路径(~200 行, :338-539)时保留 durable 分支全部行为；测试为死代码钉行为的同步删（usage.test.ts:94-120、file-tools.test.ts:54-55、engine.test.ts:594-643）
• 与既有 issue 的交叉：[P2][sdk/mcp] SDK MCP server 与外部 MCP 工具名原样拼装，非法字符直通 provider API 致整轮 400 #326（sdk-mcp-server 工具名）、[P2][sdk/query-controller] async iterable 输入源抛错成为 unhandledRejection 崩进程；push-after-close 同理 #356（query-controller 输入源异常——push/close/next 是活路径须保留）、[P3][sdk/session] matchesDir 大小写敏感比较，Windows 盘符/路径大小写差异令 continue 找不到会话 #362（matchesDir 死路径内）、[P2][sdk/web] downloadAndLocalizeImages 无 AbortSignal 无数量上限，中断后仍顺序下载全部图片 #342（downloadAndLocalizeImages 若判死则转为删除）修复方式可能从「修 bug」变为「随本批删除」
• 分批建议：A 五块按序 5 个 PR，B/C 各 1 个 PR

---

来源: packages/sdk 全量 review 第二轮（2026-08-22，PR#283 后），发现已逐条代码实证。

[CavinHuang]

🔍 二次确认

结论：✅ 可删（带三处保留项修正）— 共 8 块（A 五块 + B 三组 + C），全部验证主体死代码成立，~2000 行量级属实

块名	主文件	引用验证结果
A1 SDK 内置 MCP 链	mcp/client.ts 全文件 + agent.ts syncMcpConnections/getConfiguredMcpServers/mcpLinks/MCP 控制四方法	零存活引用。sidecar 不传 mcpServers 有测试钉死（run.test.ts:682 断言 cfg?.mcpServers undefined），插件 MCP 走自有 plugin-mcp-bridge。connectMCPServer/closeAllConnections/MCPConnection 仅 agent.ts + index.ts 导出面引用
A2 插件装配链	plugins/loader.ts loadPlugins 簇(:251-305,:307-477) + agent.ts 装配点(:751/:1606) + hooks.ts shell 分支(:212-246)+executeShellHook(:308-379)	零存活引用。sidecar run.ts:614-616 注释明说不再走 SDK loadPlugins；cfg.hooks 类型只有 handler 函数形态（types.ts:1584），shell command hook 唯一来源是已死的 plugin.hooks。保留项①：同文件 buildCommandToolDefinition+executeSandboxedCommandTool+execCommandTool 是活的（sidecar runtime-bridge.ts:53 直接 import），不能整文件删
A3 AgentTool 嵌套 QueryEngine	tools/agent-tool.ts call 体(:175-557) + BUILTIN_AGENTS(:58-69) + registerAgents/clearAgents(:44-53)	call 体零存活引用：sidecar 两入口均 {...AgentTool, call: 自定义} 整体替换（run-tools.ts:338/:618）。splitDeferredTools 生产唯一调用点 ：226 随之死。保留项②：AgentTool 外壳（name/description/inputSchema/validateInput 等）必须保留——sidecar spread 依赖；subagent-output.ts / agent-tool-events.ts / process-job-registry.ts / worktree-tools.ts 四个辅助模块是活的（sidecar run-subagent.ts 直接 import 前两者），只删 agent-tool.ts 对它们的 import
A4 sdk-mcp-server + tool-helper	sdk-mcp-server.ts 全文件 + tool-helper.ts 全文件	零生产引用。createSdkMcpServer/tool/sdkToolToToolDefinition 仅 README + examples/11 + examples/web/feature-catalog 引用；isSdkServerConfig 仅被 A1 的死 MCP 链消费（须先删 A1）
A5 死 API 面	query-controller.ts 15 个委托方法 + Agent 方法群 + session.ts 部分 + 顶层 query()	宿主对 query 返回值仅 for await 迭代（run-loop.ts:94），控制操作全部直连 agent 实例（setMaxThinkingTokens×2/setModel/interrupt/getInitializationResult×11）。resumeInterruptedRun/discardInterruptedRun 零宿主调用（sidecar 自建 discardInterruptedRunForThread，用导出的 detectDanglingToolUses）；rewindFiles/stopTask/reloadPlugins/mcp 控制零宿主调用；顶层 query() 仅 examples 08-11 引用。修正③：session.ts 是 10 个导出中 6 个纯死（appendToSession/deleteSession/getSessionMessages/getSessionInfo/renameSession/tagSession，约 90 行 + 关联类型），非 8 个——saveSession/loadSession/listSessions/forkSession 被 agent.ts 内部持久化/resume 路径使用，删不得
B1 utils/context.ts	全文件 187 行	零可达路径。engine.ts:334 if (config.systemPrompt) 早退在 getSystemContext/getUserContext(:371/:382) 之前；sidecar 恒传 systemPrompt（run.ts 构造 options）。clearContextCache 仅 index.ts 导出面
B2 死函数群	tokens.ts/usage.ts/messages.ts/retry.ts/fileCache.ts 各若干	逐一验证：getTokenCountFromUsage/AUTOCOMPACT_BUFFER_TOKENS/getAutoCompactThreshold、getCachedTokens/calculateAutoCompactThreshold/createAgentProgressTracker（连带 types.ts:166 progressUsage 字段 + :780 AgentProgressUsage）、createUserMessage/createAssistantMessage/extractTextFromContent/createCompactBoundaryMessage/truncateText(messages.ts:346)、isAuthError/isRateLimitError/formatApiError、createFileStateCache —— 除 index.ts 导出面与各自 .test.ts 外全仓零引用；同文件的活导出（estimateTokens 家族/withRetry/isPromptTooLongError/FileStateCache 类等）不受影响
B3 CODEANY_* env 回退链	agent.ts:307-337,:379 + engine.ts:1017 + retry.ts:153	注意：链内 CODEANY_HOME 是活的——sidecar session-store.ts:138 主动设置该变量、session.ts:59 读取它定位会话目录，删链条时必须留下这一对；API key/model/baseURL/apiType 回退部分可删
C index.ts 导出面收敛	index.ts	方向证实且更甚：实测 436 个命名导出中宿主（apps/* + packages/shared）仅 import 123 个，313 个（72%）宿主零引用（issue 记 282/69%，计数口径差异不改结论）。lumeFileUrl/downloadAndLocalizeImages：死的只是 index.ts:549-550 再导出行——函数本体活（web-fetch.ts:391 调 downloadAndLocalizeImages、image-pipeline.ts:161 自用 lumeFileUrl），删导出不删函数

🛠️ 清理方案

• 顺序：A1 → A4（isSdkServerConfig 消费点先消失）→ A2 → A3 → A5 → B → C；与既有 issue 交叉按原注意事项处理（[P2][sdk/query-controller] async iterable 输入源抛错成为 unhandledRejection 崩进程；push-after-close 同理 #356 的 push/close/next 保留、[P3][sdk/session] matchesDir 大小写敏感比较，Windows 盘符/路径大小写差异令 continue 找不到会话 #362 matchesDir 随 session.ts 死块消失、[P2][sdk/web] downloadAndLocalizeImages 无 AbortSignal 无数量上限，中断后仍顺序下载全部图片 #342 downloadAndLocalizeImages 改判为「仅删再导出」）
• 同步删测试：usage.test.ts:94-120（calculateAutoCompactThreshold + createAgentProgressTracker 两段，已核实钉的是死函数）；plugins/loader.test.ts 中 loadPlugins describe 组（保留 buildCommandToolDefinition 组）；registry.test.ts:86 splitDelayedTools 适配器组；agent-resume.test.ts / agent-tool.parallel.test.ts 整体随方法删除。⚠️ 原 issue 所列 engine.test.ts:594-643 与 file-tools.test.ts:54-55 行号已漂移——现内容是 repeat-guard 等活行为测试，不可按行号删，执行时需按「钉 startDirectShellTask 直连路径」语义重新定位
• startDirectShellTask（bash.ts:338-539）：确认死——sidecar 恒传 artifactsRoot+sessionId（prepare-attempt.ts:103 → lume-runner.ts:424/:437），durable 分支恒走；删除后 Bash 工具隐含「必须有 artifactsRoot」前置
• examples/web：server.ts 的 MCP 控制/streamInput/rewindFiles/listSessions/getSessionInfo 路由 + feature-catalog 的 createSdkMcpServer demo 需随删或裁剪，属 demo 代码不构成阻塞

[CavinHuang]

🔧 认领第一批：A1 SDK 内置 MCP 链 + A4 sdk-mcp-server/tool-helper 簇（~640 行，按二次确认方案 A1 先行使 isSdkServerConfig 消费点消失后 A4 跟上）。B/A2/A3/A5/C 留给后续批次。

[CavinHuang]

第一批 A1+A4 已提 PR #444（-895 行）：SDK 内置 MCP 链 + sdk-mcp-server/tool-helper 簇 + 连带的 assembleToolPool。

[CavinHuang]

🔧 认领剩余全部批次：A2 → A3 → A5 → B1/B2/B3 → C（含 startDirectShellTask 死路径与同步测试清理，按二次确认方案与三处保留项执行）。

[CavinHuang]

📦 剩余批次已提 PR #497（含此前中断会话遗留的 A2/A3/A5/B1 三 commit 复用 + 本次续完的 A5/B3/B2/C，全批约 -3000 行）。

验证与取舍详见 PR 描述。要点：

• ✅ typecheck 6/6 包绿；sdk 697 pass/0 fail；shared 203 pass/0 fail
• ⏸️ startDirectShellTask 直连路径删除缓做：删除后 durable 前台路径在 bun test 下挂死（裸 bun 与生产正常），疑为 process-job worker 水合与测试运行器的交互问题，需独立 root-cause，本批不硬闯
• 🔍 顺带发现预存缺陷：sidecar plugin-hooks-bridge「非 JSON 输出」用例在纯 main 上同样失败（♻️ refactor(sidecar): 分层边界重划 + host ports 注入,agent-runtime 运行时依赖清零 (#289) #495 层叠重构带入），已另开 issue 跟进