♻️ sdk: 简化批——token 估算口径矛盾、四份 writeFileAtomic、registry 双轨、@ts-nocheck 摘除

[CavinHuang]

严重度: P3（质量）

全量 review 发现的重复实现与口径矛盾收敛清单：

口径矛盾（优先）

1. estimateToolSchemaTokens 漏算 inputSchema：engine.ts:521-526 只算 (description+name)/4，同仓 tool-search.ts:34 的 getDeferredToolTokenCount 是 name+description+JSON.stringify(inputSchema)。30+ 工具 schema 可达上万 token——无 provider 锚点时 toolSchemaTokens 系统性偏低。且 estimateToolSchemaTokens 与 getContextUsage 内联(:2145-2148)还有一份重复实现
2. usage.ts:124 createAgentProgressTracker 混用绝对/累计语义（inputTokens 取快照、outputTokens 累加）——当前在死代码清单（🔥 sdk: 死代码大扫除第二批——宿主旁路的五整块子系统 + 死 API 面（PR#283 续篇，~2000 行） #388），若保留须统一口径

重复实现收敛

3. writeFileAtomic 四份拷贝：edit.ts:201 / write.ts:147 / notebook-edit.ts:245 / lsp-tool.ts:1115（仅后缀不同）→ 抽 utils 一处
4. skills/registry.ts 双轨：全局单例函数组(:79-251) 与 SkillRegistry 类(:11-76) 平行维护两套注册/别名/归一化逻辑 ~150 行
5. commandToolFromManifest(loader.ts:251-305) 复刻 buildCommandToolDefinition(:112-181) ~55 行且缺 sandbox 分支（在 🔥 sdk: 死代码大扫除第二批——宿主旁路的五整块子系统 + 死 API 面（PR#283 续篇，~2000 行） #388 死代码块内，随删）
6. validateManifest(manifest.ts:420) 与 normalized.ts:135 逐字相同
7. sliceSessionMessages 两份逐字符相同（agent.ts:135 / session.ts:293）
8. retry 错误分类三元链在流式/非流式两条路径重复（engine.ts:1243-1251 vs 1273-1281）
9. truncateText 双份（messages.ts:346 零调用 + mcp/manager.ts:382 私有版）
10. 内容块联合类型三套平行定义（types.ts:6-20 与 providers/types.ts:62-67 字段几乎逐一对齐），normalizeMessagesForAPI/fixToolResultPairing 全程 any 消解了收益

@ts-nocheck 摘除

11. web/scrapers/*.ts 74/74 文件首行 @ts-nocheck（~11k 行绕过 typecheck；🐛 fix: packages review 批次 #232-#246(实修 12 项,#233-#235 已修随附关闭) #273 摘过 SDK 其他文件，scraper 层遗留）

其他

12. types.ts(1718 行) 与 types/ 目录（仅 3 个第三方 ambient 声明）名字撞车易误导；types.ts 本体混杂十个域 + class AbortError，建议按域拆分
13. SDKMessage 联合成员导出面不齐：SDKRunAbortedMessage/SDKLspDiagnosticsMessage/SDKMemorySavedMessage 等实际发出的类型未导出，sidecar 只能 Extract 取形状——要么补导出要么立规则
14. stopReason: ...|string（providers/types.ts:85）等 | string 吸收字面量致 narrowing 失效

---

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

[CavinHuang]

🔍 二次确认

结论：✅ 可做（14 项逐一验证成立，其中第 3 项实际比 issue 多一份拷贝、第 11 项为 75 个文件）— 收敛点均已定位

#	项	验证结果
1	estimateToolSchemaTokens 漏算 inputSchema	✅ 证实，且同口径重复实为三处：engine.ts:563-568（estimateToolSchemaTokens）、:2289-2292（getContextUsage 内联 toolTokens）、:2393/:2399 明细分解——全是 (name.length+description.length)/4，均不含 inputSchema。全口径唯一实现在 tool-search.ts:33-35 getDeferredToolTokenCount（name+description+JSON.stringify(inputSchema)），宿主 context-controller 也依赖该口径链路
2	createAgentProgressTracker 混用绝对/累计语义	✅ 证实（usage.ts:124-141：inputTokens 取快照、outputTokens 累加）。已核实零生产引用（仅 usage.test.ts + index.ts 导出面），随 #388 B2 删除即本项自然消解，无需统一口径
3	writeFileAtomic 四份拷贝	✅ 证实且漏计一份，实为五份：edit.ts:201 / write.ts:147 / notebook-edit.ts:245 / lsp-tool.ts:1115 之外还有 utils/file-checkpoints.ts:274。前四份中 edit/write/notebook-edit 三份逐字节相同（Uint8Array），lsp-tool 为 string+'utf8'+.lsp.tmp 后缀变体，file-checkpoints 多一个 mkdir(recursive) 前置。收敛落点：utils 抽单一实现（Uint8Array | string 入参 + encoding/mkdir 选项）
4	skills/registry.ts 双轨	✅ 证实：SkillRegistry 类(:11-76) 与全局单例函数组(:107-209) 平行维护注册/归一化/别名/前缀剥离逻辑 ~150 行。注意两轨当前都是活的：bundled skills 模块加载时 registerSkill 进单例，agent.ts:291 再 new SkillRegistry(getAllSkills()) 播种实例；engine.ts:2293 与 agent-tool.ts:208 还有单例 fallback 读路径。属重构收敛而非单纯删除
5	commandToolFromManifest 复刻 buildCommandToolDefinition	✅ 证实（loader.ts:251-305 vs :112-181，前者缺 sandbox 分支）。commandToolFromManifest 唯一消费者是 loadPlugins→normalizeManifestTools，已在 #388 A2 死代码块内，随删即收敛，保留 buildCommandToolDefinition（sidecar runtime-bridge 在用）
6	validateManifest 与 normalized.ts:135 相同	✅ 证实：manifest.ts:420-423 inferDefaults(parseManifest(raw)) 与 normalized.ts:135 逐字同构；且 validateManifest 自身零生产调用（仅 index.ts:260 导出 + manifest.test.ts）。直接删 validateManifest 即完成收敛，无需改 normalized.ts
7	sliceSessionMessages 两份	✅ 证实近似逐字相同（agent.ts:135-143 多一个 !upToMessageId 守卫，session.ts:293-300 必传参数）。两处均在活路径（resume / forkSession），抽 utils 合一即可
8	retry 错误分类三元链两份	✅ 证实：engine.ts:1295-1303（流式 chunk.retry_state，取 chunk.errorStatus）与 :1325-1333（非流式 withRetry 回调，取 retry.error.status）的 429/400/401|403/5xx|529 分类链逐字相同，产出同为 api_retry 事件。抽 classifyRetryError(status) 一处
9	truncateText 双份	✅ 证实：messages.ts:346 零调用（随 #388 B2 删），mcp/manager.ts:382 私有版在 :418 存活使用。随 #388 删除零调用份即收敛
10	内容块联合类型三套平行	✅ 证实：types.ts:6-20（ToolResultContentBlock/ContentBlockParam/ContentBlock）与 providers/types.ts:62-67 NormalizedContentBlock 字段几乎一对一对齐，NormalizedResponseBlock(:94-97) ≈ ContentBlock(text/tool_use/thinking)；normalizeMessagesForAPI/fixToolResultPairing 以 any 桥接使差异不可见。属类型收敛重构，需 typecheck 全绿兜底
11	web/scrapers @ts-nocheck	✅ 证实且略多于 issue 所记：75 个文件首行 // @ts-nocheck（issue 记 74），目录共 80 文件 15935 行，仅 compat/index/index.test/types/utils 五个基建文件无标记；全仓其余位置零 @ts-nocheck
12	types.ts 与 types/ 目录撞车	✅ 证实：types.ts 现 1730 行混杂十个域 + class AbortError；types/ 目录仅 bun.d.ts/sql-js.d.ts/turndown-plugin-gfm.d.ts 三个第三方 ambient 声明
13	SDKMessage 联合成员导出不齐	✅ 证实：SDKRunAbortedMessage/SDKLspDiagnosticsMessage/SDKMemorySavedMessage 定义于 types.ts 且属于联合成员，但 index.ts 未导出；sidecar run-background.ts:127 注释明说「未从 index 导出，经 Extract 取型」——宿主被迫用 Extract 是现行证据
14	stopReason: ... | string 吸收字面量	✅ 证实：providers/types.ts:85 'end_turn' | 'max_tokens' | 'tool_use' | string，narrowing 失效成立

🛠️ 清理方案

• 优先级：1/8 先做（行为可观测：contextUsage 口径修正 + 重试事件分类统一）；3/6/7/9 机械收敛低风险；2/5/9 直接挂靠 🔥 sdk: 死代码大扫除第二批——宿主旁路的五整块子系统 + 死 API 面（PR#283 续篇，~2000 行） #388 对应块随删，不单独开 PR
• 口径基准：第 1 项以 tool-search.ts getDeferredToolTokenCount 为唯一口径源（含 inputSchema），estimateToolSchemaTokens/getContextUsage 内联改调它；skill 条目 (:2297) 的 name+description 口径保持独立不受影响
• 第 4 项方向：SkillRegistry 类定为唯一实现；全局函数组退化为共享单例门面（bundled skills 注册路径不能断），hasSkill/unregisterSkill 零生产调用可径直删
• 第 11 项建议分批：75 个文件一次摘除会暴露大量隐式 any 错误，按 scraper 分组小批摘除并逐批跑 bun run typecheck（SDK 包级）
• 第 12 项拆分：types.ts 按域拆出后 types/ 目录建议同步更名（如 typings/ 或 ambient.d.ts 归并）以消除撞车

[CavinHuang]

认领，基于最新 main 逐项核实后处理（清单写于 #283/#444/#456/#465/#467/#469 大改前，先对现状再动手）。

[CavinHuang]

逐条对账当前 main（PR#444/#456/#465/#467/#469 合入后）：

已解决（随其他 PR 落地）

• 1️⃣ estimateToolSchemaTokens 漏算：♻️ fix(sdk): engine 收敛批——惰性 token 估算/stableSerialize 单源/双循环合并/低危积压六项 #467 已删，getDeferredToolTokenCount（含 inputSchema）成单源
• 6️⃣ validateManifest 重复：已重构为 parseManifest+inferDefaults 薄组合，整函数逐字复制不复存在
• 8️⃣ retry 错误分类双路径：♻️ fix(sdk): engine 收敛批——惰性 token 估算/stableSerialize 单源/双循环合并/低危积压六项 #467 双循环合并已消
• 10 内容块三套定义：🏗️ refactor(shared,sdk): 协议消息类型下沉单源，解除 shared↔sdk 包级循环依赖 #469 协议类型下沉 @lume/shared 后大半消除；providers/types.ts 的 NormalizedContentBlock 是适配层内部表示，保留
• 11 scrapers @ts-nocheck：整个 web/scrapers 目录已移除，moot

本批修复（即将推 PR）

• 3️⃣ writeFileAtomic：edit/write/lsp-tool 三份已被死代码批清掉；剩余 session.ts/notebook-edit.ts/file-checkpoints.ts 三份全部收敛到 utils/fs-atomic 单源
• 4️⃣ registry 双轨：函数组改为委托单例 SkillRegistry 实例（class register 返回被替换者以保留 overwrite warn），删 ~90 行平行状态与逻辑
• 7️⃣ sliceSessionMessages：单源化到 session.ts，agent.ts 改 import
• 13 SDKMessage 导出面：补齐 SDKContextCompactionProgressMessage / SDKMemorySavedMessage / SDKRunAbortedMessage 三个缺失导出

裁定不修/移交

• 2️⃣ createAgentProgressTracker 口径矛盾 → 🔥 sdk: 死代码大扫除第二批——宿主旁路的五整块子系统 + 死 API 面（PR#283 续篇，~2000 行） #388 死代码清单管辖（若保留须统一）
• 5️⃣ commandToolFromManifest → 在 🔥 sdk: 死代码大扫除第二批——宿主旁路的五整块子系统 + 死 API 面（PR#283 续篇，~2000 行） #388 死代码块内，随删
• 9️⃣ messages.ts truncateText 全仓零调用（sidecar/web 均为本地小实现）→ 死 API 面，建议随 🔥 sdk: 死代码大扫除第二批——宿主旁路的五整块子系统 + 死 API 面（PR#283 续篇，~2000 行） #388 删除并摘 index 再导出
• 12 types.ts 拆分：🏗️ refactor(shared,sdk): 协议消息类型下沉单源，解除 shared↔sdk 包级循环依赖 #469 下沉后已从 1718 行降到 919 行且协议域已迁出，剩余拆分收益低扰动高，defer
• 14 stopReason | string：不可收窄——🔥 移除 SDK 内置 LLM providers，统一宿主注入契约 #283 之后 provider 为宿主注入纯契约，SDK 无法枚举宿主返回的 stop reason 集合；| string 是宿主透传通道而非疏漏

[CavinHuang]

项 11 摘除评估数据（随 PR#481 留档）

• sdk 包配置下全摘 @ts-nocheck：typecheck 零错误；做了阴性对照（注入一处类型错误 tsc 正确报 1 错），确认非假绿。
• sidecar 视角：sidecar 以 noUncheckedIndexedAccess 编译 sdk 源码时暴露 222 处错误 / 45+ 文件（github.ts 38、maven.ts 30、gitlab.ts 12 等）。
• 修复量估算：500–900 行，超出单批阈值 → 本批已原样还原，未纳入 PR#481。
• 建议修向：scrapers 目录统一索引访问守卫（如封装安全索引 helper）后按文件分批摘除，可拆独立 issue 跟进。