# Agent Note: API extractor 报告

Status: proposed

[English](2026-06-11-api-extractor-reports.md) | 中文

> 文档块类型检查与事件分类体系两部分已交付（[doc-sync（文档同步门禁）强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)）；剩余的 API 报告部分作为独立提案被推迟。

## 问题

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

## 提案

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

## 曾考虑的替代方案

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

## 验收标准

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

## 风险

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

## 推迟原因

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