2026-07-23 00:10:53 +08:00
|
|
|
# Agent Note: API extractor 报告
|
2026-07-15 23:25:06 -07:00
|
|
|
|
|
|
|
|
Status: proposed
|
|
|
|
|
|
2026-07-22 22:29:39 +08:00
|
|
|
[English](2026-06-11-api-extractor-reports.md) | 中文
|
|
|
|
|
|
2026-08-04 18:42:13 +08:00
|
|
|
> 从最初的「doc-sync（文档同步门禁）与 API 报告」Agent Note 中拆出（首次提出于 2026-06-11）。第 1 至第 2 部分（文档块类型检查、事件分类体系校验）已交付，见 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)。本文是被推迟的第 3 部分，作为独立提案保留。
|
2026-07-15 23:25:06 -07:00
|
|
|
|
|
|
|
|
## 问题
|
|
|
|
|
|
2026-07-22 03:07:36 -07:00
|
|
|
公开 API 的变更是不可见的：没有任何机制将「此次提交改变了公开接口」变为一个显式、可评审的事实。评审者阅读 diff 时可能遗漏某个导出类型新增了字段，或某个方法签名发生了变化。
|
2026-07-15 23:25:06 -07:00
|
|
|
|
|
|
|
|
## 提案
|
|
|
|
|
|
2026-08-04 17:36:14 +08:00
|
|
|
使用 api-extractor（或 `tsc --emitDeclarationOnly` 加一份规范化的公开 API 清单）为每个包生成一份签入仓库的 `etc/<pkg>.api.md`；CI 在重新生成结果与已签入报告不一致时失败。这样，每一次公开 API 变更都会成为评审者（或评审 agent（智能体））必须看到的一行 diff。
|
2026-07-15 23:25:06 -07:00
|
|
|
|
|
|
|
|
## 曾考虑的替代方案
|
|
|
|
|
|
2026-08-04 17:36:14 +08:00
|
|
|
**`tsc --emitDeclarationOnly` 加规范化的公开 API 清单**：如果 api-extractor 过于笨重，这是更轻量的机制；两者都能满足提案所需的「签入仓库、可 diff」的报告形态。
|
2026-07-15 23:25:06 -07:00
|
|
|
|
|
|
|
|
## 验收标准
|
|
|
|
|
|
2026-07-22 03:07:36 -07:00
|
|
|
- 每个包都有一份签入仓库的 `etc/<pkg>.api.md`；CI 在重新生成结果与已提交报告不一致时失败。
|
2026-07-15 23:25:06 -07:00
|
|
|
- 公开 API 变更（新增导出、字段放宽、签名变化）在评审中以报告 diff 行的形式可见。
|
|
|
|
|
|
|
|
|
|
## 风险
|
|
|
|
|
|
2026-07-22 03:07:36 -07:00
|
|
|
该依赖笨重且难以调教（这正是它被推迟的原因），且报告格式会随编译器升级而变动，增加一个维护面；在各包尚未发布的阶段，收益有限。
|
2026-07-15 23:25:06 -07:00
|
|
|
|
|
|
|
|
## 推迟原因
|
|
|
|
|
|
2026-07-22 03:07:36 -07:00
|
|
|
在 doc-sync 落地时被推迟：对于一个内部 monorepo，评审者已经能看到源码 diff，价值不高；且依赖笨重、难以调教。如果各包将来对外发布，再重新评估——届时一份稳定、可 diff 的公开接口报告才值得其维护成本。
|
