Files

T

ZiyaZhang 19606bc331 docs: generate THIRD_PARTY_NOTICES.md and gate it in doc-sync

Replace the hand-written inventory with scripts/gen-third-party-notices.ts,
verified fresh by a doc-sync leaf gate. Tier by declaring workspace area
rather than manifest section, so test-support runtime declarations stay
dev-only and every mountable plugin's dependencies are disclosed as
runtime; list the pnpm-patched packages; point the Python closure at
uv.lock. Re-record the translation-prompt snapshot the README link
invalidated.

2026-07-30 07:27:13 -07:00

5.6 KiB

Raw Blame History

Agent Note: Generated third-party notices

Status: implemented

English | 中文

Problem

本仓库开源需要披露所依赖的第三方软件及各自的许可证。这份披露必须完整，必须随依赖变化保持为真，还必须给出读者用得上的信息：哪些包最终会进到用户机器上，哪些只用于构建和测试。

手写清单无法长期满足其中任何一条。约一百行从各清单文件推导出来的包名与许可证标识，只要有依赖新增、移除或换用许可证就会悄悄失真，而 doc-sync 不会察觉。

Decision

THIRD_PARTY_NOTICES.md 由 scripts/gen-third-party-notices.ts 依据各工作区清单、vendor/README.md、pyproject.toml 与 pnpm-workspace.yaml 生成。pnpm run verify-third-party-notices 以 --check 运行生成器，作为 doc-sync 的叶子门禁；依赖变了却没重新生成，会像目录过期一样直接失败。根 README 双语两侧都从「许可证」一节链到该文件。

文件只披露直接依赖。完整的 npm 闭包连同锁定版本已记录在 pnpm-lock.yaml（pnpm licenses list 可渲染），Python 闭包记录在 python/sdk/uv.lock；再用散文誊一遍只会得到一份更差的副本。

分层依据是声明方所在区域，而非清单字段名。 只要 DEV_ONLY_AREAS 之外的任一清单——即根清单、packages/support/、packages/client/test-runtime/、website/、examples/、native/ 之外——在 dependencies 或 optionalDependencies 里点名某个包，它就是运行时依赖。单看字段名在两个方向上都会出错：测试支撑包把 vitest 写在 dependencies 里却并不交付它；而 bin/dsh 启动器 exec 经过的 tsx，根本没有任何清单把它声明为运行时依赖，只能由生成器显式标记。

运行时层刻意覆盖所有可挂载的插件，而不止 CLI、Web UI 与 Python 运行时默认加载的那些。scripts/install.sh 安装的就是仓库本身，用户的 cordis.yml 可以挂载任何插件包；@modelcontextprotocol/sdk 与 OpenTelemetry 系列即使没有任何默认装配引入，也会触达真实用户。对法务披露而言，披露不足才是代价更高的那个方向。

许可证与仓库地址取自已安装的 pnpm store，因此生成器要求工作树已安装依赖；某个包两处都解析不到时直接失败，而不是留下空单元格。OVERRIDES 收录已发布清单答不上来的包：用 Rust 构建、发布时省略 license 字段的 npm 可执行包，以及 modelcontextprotocol/servers 系列——该仓库正处在 MIT 向 Apache-2.0 的重新许可过程中，实际条款按贡献逐条而定。被源码收编的包会与 vendor/README.md 交叉核对，出现非 MIT 即报错；pnpm-workspace.yaml 的 patchedDependencies 列在运行时表格之后，因为 pnpm 在安装期就会打上这些补丁——交付产物携带的是改动过的 @earendil-works/pi-tui 与 node-pty，补丁文件本身就是改动的完整记录。

Testing

scripts/gen-third-party-notices.spec.ts 用夹具清单钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 dependencies 条目，以及没有任何应用挂载的插件包。它同时钉住被收编包的表格解析器能读出已提交的清单表，且表格形态一变就解析为空——正是这一点让生成器直接失败，而不是产出一个空章节。

Alternatives considered

保留手写文件，发版时人工过一遍。 用肉眼审阅上百行推导数据，恰恰是生成器能做对的活；而且在两次发版之间，文件自称「列出全部直接依赖」这句话无人验证。

列出完整传递闭包。 闭包有数千个包，锁文件里已带精确版本，铺开只会淹没读者真正要评估的直接依赖。文件转而指向锁文件与 pnpm licenses list。

按清单字段分层（dependencies 与 devDependencies）。 机械上最省事，但在真实数据上两个方向都会出错，理由见上文分层段落。

只按已交付装配的可达性分层（apps/* 加 python/sdk-runtime）。这样得到的运行时层更紧凑，但会把 MCP 客户端与 OpenTelemetry 导出器判为仅开发用途——而运行已安装仓库的用户完全可以挂载它们。这会低估披露，对法务通告来说错在了更危险的一侧。

把披露文件做成双语对。 其他根文档都是成对的，但这份文件是上游包名、SPDX 标识与网址构成的表格，可翻译的只有寥寥几段章节导语。scripts/translation-pairing.ts 的发现范围限定在 README*、.agents/notes/**、docs/** 与 python/**，根目录下的非 README 文件在构造上就不属于双语语料；双语入口由 README 对承担。

Consequences

此后增删依赖都需要运行 pnpm run gen-third-party-notices 并提交结果，否则 doc-sync 失败。这正是预期成本——披露不可能再悄悄过期。

生成器需要已安装的工作树，因此比纯源码生成器更重；发布元数据不可用的新包需要补一条 OVERRIDES，而不是默默渲染出空白许可证。这两类失败都会明确报错并指出补救方式。

分层规则是编码在一个常量里的政策。若新增了不参与交付的工作区区域——第二层测试基础设施、另一个站点——就要同步扩展 DEV_ONLY_AREAS，否则其依赖会被当作运行时依赖披露出去。

5.6 KiB Raw Blame History Unescape Escape