deepseek-harness/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.zh.md

Agent Note: API extractor 报告

Status: proposed

English | 中文

从最初的「doc-sync（文档同步门禁）与 API 报告」Agent Note（agent 决策记录）中拆出（首次提出于 2026-06-11）。第 1 至第 2 部分（文档块类型检查、事件分类体系校验）已交付，见 doc-sync 强制。本文是被推迟的第 3 部分，作为独立提案保留。

问题

公开 API 的变更是不可见的：没有任何机制将「此次提交改变了公开接口」变为一个显式、可评审的事实。评审者阅读 diff 时可能遗漏某个导出类型新增了字段，或某个方法签名发生了变化。

提案

使用 api-extractor（或 tsc --emitDeclarationOnly 加一份规范化的公开接口导出）为每个包（package）生成一份签入仓库的 etc/<pkg>.api.md；CI 在重新生成结果与已签入报告不一致时失败。这样，每一次公开 API 变更都会成为评审者（或评审 agent（智能体））必须看到的一行 diff。

曾考虑的替代方案

tsc --emitDeclarationOnly 加规范化的公开接口导出：如果 api-extractor 过于笨重，这是更轻量的机制；两者都能满足提案所需的「签入仓库、可 diff」的报告形态。

验收标准

• 每个包都有一份签入仓库的 etc/<pkg>.api.md；CI 在重新生成结果与已提交报告不一致时失败。
• 公开 API 变更（新增导出、字段放宽、签名变化）在评审中以报告 diff 行的形式可见。

风险

该依赖笨重且难以调教（这正是它被推迟的原因），且报告格式会随编译器升级而变动，增加一个维护面；在各包尚未发布的阶段，收益有限。

推迟原因

在 doc-sync 落地时被推迟：对于一个内部 monorepo，评审者已经能看到源码 diff，价值不高；且依赖笨重、难以调教。如果各包将来对外发布，再重新评估——届时一份稳定、可 diff 的公开接口报告才值得其维护成本。