DeepSeek/deepseek-harness
1
0
Fork 0
mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/master' into worktree/acp-automation-protocol

Browse Source 
# Conflicts:
#	.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
#	.agents/notes/implemented/architecture/2026-06-20-package-hierarchy.md
#	.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md
#	.agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.md
#	.agents/notes/implemented/feature/2026-06-14-acp-multi-session.md
#	.agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md
#	.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
#	.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
#	.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
#	.agents/notes/implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-surface.md
#	docs/architecture.i18n.yaml
#	docs/cookbook/extension-cookbook.i18n.yaml
#	docs/cookbook/extension-cookbook.md
#	docs/cookbook/extension-cookbook.zh.md
#	docs/core-data-structures/approval.md
#	docs/core-data-structures/user-interaction.md
#	docs/event-producer-consumer.md
#	docs/persistence-catalog.md
#	docs/testing.md
#	docs/tool-catalog.md
#	examples/acp-agent/tests/fixtures/live-mode-switching-2026-07-07.session.jsonl
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl
#	examples/acp-agent/tests/snapshots/permission-switching/session.jsonl
#	packages/goal/tool-goal/README.md
#	packages/ui/acp/README.md
#	packages/ui/acp/acp-feature-support.md
#	packages/ui/acp/src/index.ts
#	packages/ui/acp/tests/bridge.spec.ts
#	packages/ui/acp/tests/dispose.spec.ts
#	packages/ui/acp/tests/edges.spec.ts
#	packages/ui/acp/tests/turns.spec.ts
This commit is contained in:
Tianyi Cui
2026-07-24 23:43:10 +08:00
parent d01474d1d0 b97b1b4a3f
commit 440384fdb4
829 changed files with 23607 additions and 1815 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-11-doc-sync-enforcement.md: 375059312c312dff7b5ddcb95ea5b82ac8cd4d06
2026-06-11-doc-sync-enforcement.zh.md: 5c17263bdc2b4908a82237d1fc3b08f1f22a62d9

2
.agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-06-11-doc-sync-enforcement.zh.md)
## Problem
AGENTS.md promises that docs and code stay strictly in sync, but the promise was verified by eyeball. Review caught drift twice — a cookbook example contradicting the type policy, and a README citing the wrong `registerAdapter` call. Out-of-sync docs are worse than no docs, and this codebase is built primarily by agents that follow gates far more reliably than prose (mechanical quality gates). Two classes of doc drift are mechanically checkable: code blocks that no longer compile, and the event-taxonomy table that duplicates the `interface Events` declarations.

32
.agents/notes/implemented/process/2026-06-11-doc-sync-enforcement.zh.md Normal file
View File

@@ -0,0 +1,32 @@
# Agent Note: Doc-sync 强制
Status: implemented
[English](2026-06-11-doc-sync-enforcement.md) | 中文
## 问题
AGENTS.md 承诺文档与代码严格同步，但这一承诺此前仅靠人眼核查。评审曾两次发现漂移：一次是实操手册（cookbook）示例与类型策略矛盾，一次是 README 引用了错误的 `registerAdapter` 调用。失去同步的文档比没有文档更糟；而本代码库主要由 agent（智能体）构建，agent 遵守门禁远比遵守行文约定可靠（机械质量门禁）。有两类文档漂移可以被机械检查：不再能编译的代码块，以及与 `interface Events` 声明重复的事件分类体系表。
## 决策
两道门禁，沿用既有的 `scripts/` 风格（tsx ESM，每个脚本一项职责）：
1. **`doc-typecheck`** 从 `README.md`、`docs/**` 和 `packages/*/README.md` 中提取所有 ` ```ts ` 围栏代码块，写入一个继承根 `tsconfig.json` 的临时项目，然后用 `tsc -b` 编译。临时项目复用源码的 `paths` 映射和根 project references，因此文档示例能看到源码，而 vendor 代码仍在其自身的 tsconfig 设置下被检查。刻意作为草图的代码块可通过显式的 ` ```ts ignore-check ` 信息字符串来 opt-out；脚本会报告 opt-out 比例，超过一半即失败，防止该豁免机制悄然成为常态。
2. **`verify-event-taxonomy`** 从 `packages/*/src` 中的 `interface Events` 块和 `docs/architecture.md` 中的分类体系表分别提取事件名称，断言两个集合完全一致。只校验，不生成：表格保留手写的 Mode/Purpose 列，仅检查名称集合。（落地此门禁时发现了表格遗漏的三个事件：`tools/change`、`llm/adapter-change`、`system-prompt/change`。）**已被取代**：由[生成式 Cordis 目录](2026-06-20-generated-cordis-catalog.md)取代。此门禁及其 `architecture.md` 表格已退役，取而代之的是完全生成的 `docs/cordis-catalog/events.md` + `docs/cordis-catalog/services.md` 及其 `verify-cordis-catalog` 新鲜度门禁。本 Agent Note（agent 决策记录）中的其他门禁（`doc-typecheck` 以及下文修订中的 `verify-md-wrap`）不受影响。
两者都通过 package.json 中共享的 `doc-sync` 脚本运行；贡献者在相关文档变更中调用它，CI 则执行完整检查。[快速本地 Git 钩子](2026-07-22-fast-local-git-hooks.md)决策使这类按变更面选择的工作不进入 commit 和 push 钩子。
**修订（2026-06-17）：** 第三道门禁 **`verify-md-wrap`** 随后被纳入 `doc-sync`。它使用 `mdast-util-from-markdown` + GFM 解析范围内的每个 Markdown 文件（`README.md`、`docs/**`、`packages/*/README.md`，加上 `AGENTS.md` / `packages/AGENTS.md`），如果任何 `paragraph` 节点跨越多个源码行则失败，从而强制执行 docs/AGENTS.md 中「一个段落一个物理行」的写作规则。同样遵循只校验不生成的原则：它报告硬换行但从不重写，因此不会引入格式化噪音。`doc-sync` 现在包含三道门禁。
## 曾考虑的替代方案
- **API-extractor 基准报告**（[已推迟的提案](../../proposed/process/2026-06-11-api-extractor-reports.md)）：有意推迟。对于评审者已能直接看到源码 diff 的内部 monorepo 而言价值有限，且依赖重、配置繁琐。
- **从源码生成分类体系表**而非仅校验名称：否决，机制比问题本身更重；表格保留了手写的 Mode/Purpose 列，直到[生成式 Cordis 目录](2026-06-20-generated-cordis-catalog.md)完全取代了这项检查。
## 后果
- 可检查类别中的文档漂移会直接使 `doc-sync` 和 CI 失败，而不是等评审人发现。这是「机械门禁优于行文规范」原则的具体应用。
- 让文档代码片段可编译需要少量 stub import/`declare`；`ignore-check` 比例必须保持低位，否则门禁形同虚设（比例守卫强制执行此约束）。
- 分类体系检查仅限名称——Mode 或 Purpose 列的错误仍需人工评审。
- 如果包（package）未来对外发布，API 报告方案仍可重新考虑。

6
.agents/notes/implemented/process/2026-06-11-quality-gates.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-11-quality-gates.md: e1af110387936d644208dc1829fde4a4fdf8a3f9
2026-06-11-quality-gates.zh.md: a4e57b7a08ecf20babb33b55d8c94414df1b10b1

2
.agents/notes/implemented/process/2026-06-11-quality-gates.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-06-11-quality-gates.zh.md)
The hook/CI symmetry in this record is superseded by [Fast local Git hooks](2026-07-22-fast-local-git-hooks.md); CI remains the exhaustive enforcement path.
## Problem

30
.agents/notes/implemented/process/2026-06-11-quality-gates.zh.md Normal file
View File

@@ -0,0 +1,30 @@
# Agent Note: 以机械质量门禁取代行文约定
Status: implemented
[English](2026-06-11-quality-gates.md) | 中文
本记录中的钩子/CI 对称设计已由[快速本地 Git 钩子](2026-07-22-fast-local-git-hooks.md)取代；CI 仍是执行完整检查的路径。
## 问题
本代码库主要由 coding agent（智能体）开发。相比行文约定，agent 遵守强制门禁的可靠性远高得多；而当劳动由 agent 承担时，「工作量大」不构成成本论据。早期证据：未通过类型检查的测试被提交（vitest 不做类型检查），仅在评审中才被发现。
## 决策
每条可机械检查的 AGENTS.md 承诺都有一个以非零状态退出的命令。CI 执行完整集合，而 Git 钩子将延迟预算留给可低成本发现的本地缺陷：
- 最严格的 TypeScript 配置（`noUncheckedIndexedAccess`、`exactOptionalPropertyTypes` 等）；示例、测试和脚本通过根目录的 no-emit `tsconfig.json` 在 CI 中进行类型检查，而包（package）/vendor 代码保持在各自 project-reference 边界之后。
- ESLint strict-type-checked + @stylistic（作为强制执行的统一代码风格），包括文件内重复逻辑检查；vendor 代码排除在外。
- jscpd 检测包的生产 TypeScript 代码与仓库脚本中的跨文件克隆；窄范围的源码区间例外用于记录有意为之的并行实现。
- `packages/*/*/src` 下按文件 100% 覆盖率（v8）；不可达的防御性守卫使用 `/* v8 ignore */ ` 并注明理由，而非删除。
- knip（死代码/依赖）、publint（包的正确性）、workspace 约束（workspace 规则：private、cordis peer+dev、统一版本、ESM），以及对构建出的包声明文件进行 NodeNext 消费方类型检查。
- lefthook pre-commit 修复已暂存文件的 lint 问题、拒绝已暂存的空白问题并检查 vendor manifest；pre-push 运行增量类型检查。CI 在 Node 22.19/24/26 上运行完整矩阵，并对 Headless、TUI、ACP（Agent Client Protocol）、JSON-RPC、工作流和代码运行时入口路径执行已构建应用的冒烟测试。
## 后果
- 约定不会因 agent 更替而失效；可低成本发现的 commit/push 缺陷在本地失败，其余完整规则违规在 CI 中失败。
- 门禁本身也是需要维护的代码；配置变更与其他变更一样需要评审。
- 100% 覆盖率的压力可能催生无断言的测试——变异测试是计划中的对策（见[变异测试提案](../../proposed/testing/2026-06-11-mutation-testing.md)）。
<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->

6
.agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-11-tsdown-over-dumble.md: e8cdaeb1e3331ffb04de024acff5b0e6ca3e6366
2026-06-11-tsdown-over-dumble.zh.md: bb5feef585c1748f41d1b204313f1a4d8b357a17

2
.agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-06-11-tsdown-over-dumble.zh.md)
## Problem
The initial build used **dumble**, the cordiverse zero-config esbuild wrapper that upstream Cordis itself builds with — maximum alignment with the vendored packages' conventions (it reads each package.json and infers entries/formats from the `exports` field). But dumble is a liability as a load-bearing tool in this repo: v0.2.x, ~530 npm downloads/week, effectively one maintainer, and we were invoking it through a custom orchestration script (`scripts/build.ts`) because it has no workspace mode.

30
.agents/notes/implemented/process/2026-06-11-tsdown-over-dumble.zh.md Normal file
View File

@@ -0,0 +1,30 @@
# Agent Note: 使用 tsdown 替代 dumble 进行 JS 打包
Status: implemented
[English](2026-06-11-tsdown-over-dumble.md) | 中文
## 问题
最初的构建使用 **dumble**，即 cordiverse 的零配置 esbuild 包装层——上游 Cordis 自身也用它构建——与 vendor 包（package）的约定最大程度对齐（它读取每个 package.json 并从 `exports` 字段推断入口/格式）。但 dumble 作为本仓库的承重工具存在隐患：v0.2.x，每周约 530 次 npm 下载，实质上只有一位维护者，而且由于它没有 workspace 模式，我们不得不通过自定义编排脚本（`scripts/build.ts`）来调用它。
目前构建产物只在 `pnpm run build` + publint 中有意义（尚未发布任何包；开发/测试/演示通过 tsx 直接运行未打包的源码），因此切换成本现在最低，一旦包开始发布就只会更高。
## 决策
用 **tsdown**（基于 rolldown，每周约 250 万次下载，VoidZero 支持，活跃发布）替代 dumble：
- 根目录 `tsdown.config.ts`，配置 `workspace: ['vendor/*', 'packages/*/*']`（显式 glob 将打包范围限定在 vendor 的 Cordis 与 TypeScript 包目录树内；`workspace: true` 还会发现示例 manifest 和不需要打包的 workspace 成员）。
- 共享形状：入口为 `lib/types/index.js`，`outDir: 'lib'`，ESM，`platform: node`，`target: es2024`，`fixedExtension: false`（为 `"type": "module"` 包保留 `.js`），`dts: false`（声明归 tsc -b 所有），`clean: false`（lib/ 还保存 TSC 的 `lib/types` 中间树）。入口最初是 `src/index.ts`；[TSC 优先构建 Agent Note（agent 决策记录）](2026-06-17-ts-build-config.md)随后将 tsdown 改为打包 TSC 输出的 JS，使 TypeScript 转换行为统一由一个编译器提供。
- vendor/ 中有两个按包覆盖的配置（属于我们自己的修改，与重新生成的 tsconfig 类似；记录在 vendor/README.md 中）：schemastery（通过 `outExtensions` 输出双格式 `.mjs`/`.cjs`）、logger-console（两次单入口 pass，使共享基类被内联到每个入口而非生成哈希命名的分片，与上游发布形态一致）。
- `scripts/build.ts` 删除；`pnpm run build` = `tsc -b && tsdown`（根 solution 拥有 emit 图）。
## 曾考虑的替代方案
- **直接编写 esbuild 脚本**：最成熟的引擎，零包装层风险，但需要手动维护 tsdown workspace 模式自动提供的按包规格表。
- **pkgroll**：理念上最接近的直接替代品，但每周仅 78k 下载且基于 Rollup，维护前景严格弱于 tsdown。
- **保留 dumble**：与上游完美对齐，但巴士因子不可接受。
## 后果
运行时 bundle 输出仍沿用 dumble 时代的公开入口形状（`lib/index.js`，以及包特有的变体，例如 `schemastery` 的 `lib/index.mjs`/`lib/index.cjs` 与 `logger-console` 的 `lib/browser.js`）；根据 [TSC 优先构建 Agent Note](2026-06-17-ts-build-config.md)，声明现位于 `lib/types` 下。External 仍来自各包的 dependencies/peerDependencies。我们放弃了 dumble 的 exports 字段推断：采用非默认形状的新包需要逐包提供 `tsdown.config.ts`，不能只依赖 package.json 字段。未来如果 `tsc -b` 成为瓶颈，tsdown 也可以接管声明打包（isolatedDeclarations）；这需要另写一份 Agent Note。

6
.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-11-vendor-cordis-as-source.md: ae6f5438c5817c61a549d9edb2041d538fbcebe6
2026-06-11-vendor-cordis-as-source.zh.md: 8d6f0e39d53e1c85eaaa50c4c4bf1d9ef648d953

2
.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-06-11-vendor-cordis-as-source.zh.md)
## Problem
DeepSeek Harness SDK is built on the Cordis framework. Cordis core was at 4.0.0-rc.6 (a release candidate) when this repo started; the harness depends on framework internals (fiber lifecycle, effect disposal, waterfall dispatch) whose exact behavior matters to the agent loop's correctness guarantees.

27
.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.zh.md Normal file
View File

@@ -0,0 +1,27 @@
# Agent Note: 将 Cordis 以源码形式收录，而非作为 npm 依赖
Status: implemented
[English](2026-06-11-vendor-cordis-as-source.md) | 中文
## 问题
DeepSeek Harness SDK 构建于 Cordis 框架之上。本仓库启动时，Cordis core 处于 4.0.0-rc.6（一个候选发布版本）；harness 依赖框架内部实现（fiber 生命周期、dispose（资源释放）、waterfall（瀑布式事件）分发），其确切行为直接关系到 agent loop（智能体循环）的正确性保证。
## 决策
将所需的 Cordis 包（core、loader、include、group、timer、hmr、logger-console）与 cordiverse 基础库（cosmokit、schemastery）以源码形式复制到 `vendor/`，扁平化放置，保留其原始 npm 包名以实现透明的 workspace 解析。真正的第三方依赖（js-yaml、chokidar、@standard-schema/spec 等）仍从 npm 获取。
`vendor/README.md` 是 manifest（元数据清单）：记录每个包（package）的上游仓库 + commit SHA，以及一份详尽的本地修改日志。pre-commit 守卫（`scripts/check-vendor-manifest.sh`）会拒绝未在同一次提交中更新 manifest 的 vendor 源码变更。
## 曾考虑的替代方案
- **依赖 npm 包**：否决。core 处于候选发布阶段，harness 依赖框架内部实现（fiber 生命周期、dispose、waterfall 分发），agent loop 的正确性保证取决于这些行为的确切表现；上游 RC 版本升级可能在没有本地修复路径的情况下破坏它们。
- **递归收录所有传递依赖**：否决。真正的第三方依赖（js-yaml、chokidar、@standard-schema/spec 等）仍从 npm 获取；只有内部实现对我们有影响的框架层才需要自行持有。
## 后果
- harness 完全持有其框架层：可审计、可打补丁、版本锁定。上游 RC 无法影响我们，框架 bug 可以在仓库内直接修复。
- 上游同步是手动操作（流程记录在 manifest 中）。修改日志使 diff 范围始终可知。
- 收录的包保留上游代码风格；lint 与严格性门禁将其排除（它们的 tsconfig 在本地放宽了我们较新的编译器选项）。
- 从第一天起就有一个本地补丁：移除了 hmr 的 locale-YAML 导入（运行时 YAML 导入钩子未被收录）。

6
.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-16-pnpm-over-yarn.md: 9dee405f509897e2a173399e466d574c518fa9ab
2026-06-16-pnpm-over-yarn.zh.md: 3a5ff5e9b1fb0511a9191b2e3c35b61f00b705cd

2
.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-06-16-pnpm-over-yarn.zh.md)
## Problem
The repo shipped on **Yarn 4** with the `node-modules` linker — a deliberately conservative choice that behaves like npm's flat layout while giving us Yarn's workspaces and `yarn constraints`. It worked. But Yarn 4's Plug'n'Play heritage makes the `node-modules` linker the off-the-beaten-path mode, and the broader JS ecosystem — tooling defaults, CI actions, Corepack examples, contributor familiarity — increasingly centers on pnpm. For a repo that is built primarily by agents and read by occasional human contributors, "the package manager most tools and people expect" has real value: fewer surprises, better-trodden failure paths, more copy-pasteable answers.

43
.agents/notes/implemented/process/2026-06-16-pnpm-over-yarn.zh.md Normal file
View File

@@ -0,0 +1,43 @@
# Agent Note: 使用 pnpm 替代 Yarn 4 作为包管理器
Status: implemented
[English](2026-06-16-pnpm-over-yarn.md) | 中文
## 问题
本仓库最初使用 **Yarn 4** 搭配 `node-modules` 链接器启动。这是一个刻意保守的选择：行为类似 npm 的扁平布局，同时享有 Yarn 的 workspaces 和 `yarn constraints`。它能正常工作。但 Yarn 4 源自 Plug'n'Play 的血统，使得 `node-modules` 链接器成为非主流模式；而更广泛的 JS 生态——工具默认值、CI action、Corepack 示例、贡献者的熟悉度——正日益以 pnpm 为中心。对于一个主要由 agent（智能体）构建、偶尔有人类贡献者阅读的仓库而言，「大多数工具和人所期望的包管理器」具有实际价值：更少的意外、更成熟的故障路径、更多可直接复用的解答。
切换成本目前处于最低点。本仓库尚无任何包（package）发布（每个包都是 `private: true`）；开发/测试/演示全部通过 tsx **未构建**运行，因此包管理器只需做到：（a）解析并链接 `node_modules`，（b）运行 workspace 脚本，（c）强制执行 workspace 约束。唯一的 Yarn 特有资产是 `yarn.config.cjs`（`@yarnpkg/types` 约束引擎），体量小且可机械地重新表达。这与 [tsdown 决策](2026-06-11-tsdown-over-dumble.md)的逻辑一致：在爆炸半径尚小时，将承重工具换为生态更健康的选项。
## 决策
采用 **pnpm 11.7.0**，通过 `packageManager` 字段固定版本，经 Corepack 安装（与 Yarn 使用的机制相同）：
- **Workspaces** 从 `package.json` 的 `workspaces` 数组 + `.yarnrc.yml` 迁移到 `pnpm-workspace.yaml`（`vendor/*`、`packages/*`——同样的 glob；`examples/*` 保持非 workspace，与先前设置及 tsdown 的显式 glob 一致）。
- **严格符号链接链接器**（pnpm 默认）取代 Yarn 的提升式 `node-modules` 链接器。我们刻意**不**添加 `node-linker=hoisted` / `shamefully-hoist` 逃生口：pnpm 的非扁平 `node_modules` 会让幻影依赖（引用未声明的传递依赖）大声失败，这对于一个以机械门禁为核心质量保障的仓库（见[机械质量门禁](2026-06-11-quality-gates.md)）是一项*优势*。门禁套件（类型检查、lint、test、build、knip）是证明不存在此类幻影导入的安全网。
- **构建脚本白名单。** pnpm 10+ 不运行依赖的生命周期脚本，除非将其加入白名单。`pnpm-workspace.yaml` 携带一份显式的 `allowBuilds` 映射（`esbuild`、`lefthook`、`@google/genai`、`protobufjs`）——与本仓库对模型/工具输出已有的供应链加固姿态一致，现在也应用于安装时的代码执行。`peerDependencyRules.allowedVersions.typescript: '>=5 <7'` 消除仓库内 TypeScript 的良性 peer 范围警告。
- **约束变为包管理器无关。** `yarn.config.cjs`（导入 `@yarnpkg/types`，使用 `Yarn.workspaces()` / `workspace.set()`）被 `scripts/check-workspace-constraints.ts` 取代——一个纯 tsx 脚本，通过 `pnpm run constraints` 运行。它在相同的 `vendor` + `packages` 范围上强制执行完全相同的不变式：每个包 `private: true`；`@deepseek-ai/dsh-*` 包将 `cordis` 同时声明为对等依赖（peer dependency）和 dev 依赖且范围一致、使用根 `package.json` 的版本、设置 `type: module`；vendor 包仅检查 privacy。
- 所有 CI、lefthook 钩子、`package.json` 脚本和文档中的 `yarn …` 动词变为 `pnpm …` / `pnpm run …`。`yarn.lock` → `pnpm-lock.yaml`（lockfile v9）。`.gitignore` 将 `.yarn/` 换为 `.pnpm-store/`。vendor README（如 `vendor/cordis/README.md`）按 Vendoring Policy 保持其上游 `yarn` 示例不变。
## 曾考虑的替代方案
- **保留 Yarn 4**——零变动，但押注于使用率较低的链接器模式和一个绑定单一包管理器的约束引擎。
- **npm workspaces**——无处不在，但没有约束方案，monorepo 开发体验也较差。
- **pnpm 搭配提升式链接器**——迁移更平滑，但放弃了幻影依赖安全性，而这正是迁移的核心正确性理由。
## 后果
约束检查失去了 Yarn 的自动**修复**能力（`workspace.set()` 能原地改写 manifest）；tsx 脚本仅做检查，不通过时以非零退出码和消息退出。这是可接受的：CI 从未运行过 `--fix`，且需要手动编辑的情况很少。贡献者现在为 pnpm 而非 Yarn 运行 `corepack enable`；`pnpm exec lefthook install` 取代 `yarn lefthook install`（`postinstall` 钩子仍会运行 `lefthook install`）。
性能（迁移时在开发 NFS 文件系统上测量；单次运行样本，方差大——仅供方向性参考，非基准测试套件）：
| 场景 | Yarn 4 | pnpm 11 |
|---|---|---|
| 冷启动（空缓存/store，无 `node_modules`） | ~14 s | ~16 s |
| 热重链接（缓存/store 已热，`node_modules` 已删除） | ~12–14 s | ~15–22 s |
| 冻结，`node_modules` 存在（无操作重验证） | ~2–8 s | ~0.5–7 s |
在快速本地磁盘上，pnpm 的内容寻址 store 通常在冷/热安装中胜出，尤其在多个检出之间的**磁盘占用**方面优势明显（一个全局 store 通过硬链接接入每个 `node_modules`，而 Yarn 每个 worktree 复制约 279 MB——部分开发者经常为本仓库保持约 10 个或更多 worktree）。该去重优势在上述迁移时数据中**未能**体现，因为测试 store 和 `node_modules` 位于不同文件系统，硬链接失效；在单文件系统的开发机或 CI 缓存上则适用。诚实的总结：在我们的 NFS 开发文件系统上，安装速度在噪声范围内不分伯仲；迁移的理由是生态对齐、幻影依赖安全性和跨检出磁盘去重，而非原始安装时间的胜出。
所有质量门禁（constraints、类型检查、lint、doc-sync、达到 100% 的 test:coverage、构建、knip、publint 以及已构建应用的冒烟测试）均在 pnpm 下通过，证明更换 linker 没有引入幽灵依赖故障。

6
.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-17-ts-build-config.md: 1275a635242ea887c941db9dc0554fd33acd4102
2026-06-17-ts-build-config.zh.md: 7691118dd152874e2849f1ace686069c9ea3f61f

2
.agents/notes/implemented/process/2026-06-17-ts-build-config.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-06-17-ts-build-config.zh.md)
> Root project topology (which tsconfig owns which graph) has since moved to a solution root over two aggregate programs; see the [solution-root note](2026-07-22-tsconfig-solution-root-two-aggregates.md). The tsc-first pipeline decided here is unchanged.
## Problem

80
.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md Normal file
View File

@@ -0,0 +1,80 @@
# Agent Note: TSC 优先构建与编译器单一归属
Status: implemented
[English](2026-06-17-ts-build-config.md) | 中文
> 根项目拓扑（即哪个 tsconfig 拥有哪张图）后来改为由一个 solution 根文件统辖两个聚合 program；见[solution 根文件 Agent Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)。本文确定的 TSC 优先流水线保持不变。
## 问题
此前的 TypeScript 构建与类型检查配置存在以下问题：
- `build` 使用 `tsc` 将 `packages/<group>/<pkg>` 和 `vendor/*` 下的 `.ts` 转换为 `.d.ts` 文件，然后使用 `tsdown` 将 `.ts` 转换为打包后的 `.js` 文件。这导致两个工具各自执行 TypeScript 转换。
- `typecheck` 倾向于通过一个根目录的类型检查配置来校验包（package）、vendor 源码、示例、测试和脚本。
目标是让构建与类型检查使用一致的 tsconfig 边界和 TypeScript 解析/转换行为。构建应通过单一编译器和配置生成 `.js`、`.d.ts`、`.js.map` 和 `.d.ts.map`，使发布产物与类型校验保持一致。
验证过程中发现了若干具体的技术问题和可能的路径：
- `tsdown` 使用 `oxc` 进行 TypeScript 转换，其行为与 `tsc` 不同。
- `tsdown` 输出的打包 `.d.ts` 与 Cordis 内部的相对模块增强（module augmentation）结构冲突。
- tsc 的输出受 `allowImportingTsExtensions` 影响，因此需要确保生成的 `.js` 文件不会导入 `.ts` 文件，且生成的 `.d.ts` 文件保留 NodeNext/Node16 接受的显式相对说明符。为此，包内相对导入在 TypeScript 源码中使用显式 `.ts` 说明符，由 `rewriteRelativeImportExtensions` 在输出的 JS 中将其重写为 `.js`。
- `tsdown` 输出的打包 `.js` 与 `tsc -b` 逐文件输出的 `.js` 行为不同，例如装饰器转换行为。
- `vendor/*/src`、示例、测试和脚本无法全部以 plain-include 方式纳入一个根目录的严格程序。
- 在根目录严格配置下直接对 `vendor/*/src` 做类型检查，会触发大量不属于本项目所有权范围的类型错误。
- `packages/*/*` 对 `vendor` 的包依赖解析到 `vendor/*/lib`，以适应不同的 tsconfig 严格度。
## 决策
包内相对导入使用显式 `.ts` 说明符。
`pnpm run build` 是两阶段构建：
- 阶段 1：在根 solution 上执行 `tsc -b`，将逐模块的 `.js`、声明文件 `.d.ts`、JS sourcemap `.js.map` 和声明 sourcemap `.d.ts.map` 输出到各包的 `lib/types`。这是权威的 TypeScript 编译结果。发布时保留 `.d.ts` / `.d.ts.map`，忽略 `.js` / `.js.map`。
- 该图是从根 solution `tsconfig.json` 经两个聚合可达的 project-reference 图（[拓扑](2026-07-22-tsconfig-solution-root-two-aggregates.md)），用于校验并输出包/vendor 的构建结果。
- 阶段 2：打包器读取 `lib/types` 下输出的 JS，将打包后的运行时入口写为 `lib/index.js` 或 `lib/index.mjs`（沿用当前行为）。此阶段仅做打包，禁止读取 TypeScript 源码或输出声明文件。
`tsdown` 不再负责 TypeScript 编译或声明文件输出。
`pnpm run typecheck` 运行同一张 `tsc -b` 图。
- 两个聚合（`tsconfig.host.json`、`tsconfig.client.json`）以 `noEmit` 方式检查示例、测试和脚本，并通过 references 校验包/vendor 源码。
- 被引用的包/vendor 项目保持与构建相同的输出行为，因此类型检查会刷新它们的 `lib/types` 输出，而无需使用独立的 no-emit 图。项目特定的严格度变更放在各自的 `packages/*/*/tsconfig.json` 或 `vendor/*/tsconfig.json` 中。
- 两个 no-emit 聚合禁用 `rewriteRelativeImportExtensions`；它们不输出任何文件，且包含跨 project-reference 边界导入 helper 的测试。包/vendor 的 emit 项目保持重写开启。
命令编排结构如下：
```sh
pnpm run build:
tsc -b
tsdown
pnpm run verify-node-next-types:
tsx scripts/verify-node-next-types.ts
pnpm run typecheck:
tsc -b
```
`pnpm run demo:*` 仍通过 tsx 和根路径直接运行 `src`，无需编译步骤。
## 曾考虑的替代方案
- **继续使用 `tsdown`/oxc 作为 TypeScript 转换器**：oxc 的转换行为与 `tsc` 不同（装饰器转换有差异、打包 JS 与逐文件输出不同），且其打包 `.d.ts` 与 Cordis 内部的相对模块增强结构冲突。
- **用一个根目录严格程序覆盖包、vendor、示例、测试和脚本**：vendor 源码在根目录严格标志下会触发不属于本项目所有权范围的类型错误；带有逐项目严格度的 project references 才是可行的边界。
## 后果
构建职责更加清晰：
- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `tsx` 和 `vitest`）。
- `build` 命令驱动根 solution 图。`tsc -b` 负责可发布的逐模块 `.js` 和 `.d.ts` 输出，打包器仅负责 `lib/index.*`。
- `lib/types/*.d.ts` 和 `.d.ts.map` 是发布用的声明输出。
- `lib/types/*.d.ts` 使用显式 `.ts` 相对说明符，TypeScript 的 NodeNext/Node16 解析器会将其映射到同级的 `.d.ts` 文件。
- `lib/types/*.js` 仅作为打包器输入，禁止用作运行时入口或公开导入目标。
- `lib/index.*` 是发布用的运行时输出，由打包器（当前为 `tsdown`）生成。
- `pnpm run verify-node-next-types` 扫描构建出的声明文件，检查是否存在缺少文件扩展名的相对说明符，然后以 `moduleResolution: "NodeNext"` 对构建出的 `types`/`exports` 接口进行临时外部 ESM 消费方的类型检查，确保声明说明符的回归在发布前被捕获。
- `typecheck` 命令使用 `tsconfig.json`。示例、测试和脚本由根 no-emit 项目检查，包和 vendor 模块保持与 `build` 相同的输出行为。包和 vendor 源码始终处于 project-reference 边界之后。
Cordis 的 vendor 副本现在与上游多了一处类型结构差异。在上游同步时，该差异必须被重新应用或明确废弃。

6
.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-18-markdown-cross-link-lint.md: 2e3b0f1fcd03f244756b0030f2da758c516a2bbb
2026-06-18-markdown-cross-link-lint.zh.md: cfe973ae939eceb50d6381ecf35c80df508907c3

2
.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-06-18-markdown-cross-link-lint.zh.md)
## Problem
Docs in this repo link to each other by relative path — `[topic](../implemented/2026-…-….md)`, `[the cookbook](adding-a-tool.md)`, `[architecture.md](../../architecture.md)`. Nothing verified those targets exist. A rename or a move silently breaks every inbound link, and the break is invisible until a reader clicks it. [Doc-sync enforcement](2026-06-11-doc-sync-enforcement.md) already mechanized two classes of doc drift (uncompilable code blocks, a stale event-taxonomy table) and [verify-md-wrap](2026-06-11-doc-sync-enforcement.md) a third (hard-wrapped prose) — but a dead cross-link is a fourth, equally mechanical class that was still verified by eyeball.

33
.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md Normal file
View File

@@ -0,0 +1,33 @@
# Agent Note: Markdown 交叉链接有效性检查
Status: implemented
[English](2026-06-18-markdown-cross-link-lint.md) | 中文
## 问题
本仓库的文档通过相对路径互相链接：`[topic](../implemented/2026-…-….md)`、`[the cookbook](adding-a-tool.md)`、`[architecture.md](../../architecture.md)`。此前没有任何机制验证这些目标是否存在。重命名或移动文件会静默破坏所有指向它的链接，且在读者点击之前不可见。[Doc-sync 强制](2026-06-11-doc-sync-enforcement.md)已经将两类文档漂移机械化（无法编译的代码块、陈旧的事件分类表），[verify-md-wrap](2026-06-11-doc-sync-enforcement.md) 覆盖了第三类（硬换行的段落），但死链是第四类同样可机械检查、却仍靠肉眼验证的问题。
引入这道门禁的直接动因是 Agent Note（agent 决策记录）目录树重组：将 `docs/adr/` 与 `.agents/notes/` 统一到同一个 `.agents/notes/` 下，并设置 `proposed/`、`implemented/`、`rejected/` 子目录，需要手工重命名约 40 条文档间链接。只要有一处路径输入错误，就会在没有任何检查拦截的情况下交付断链。
## 决策
新增第四道 `doc-sync` 门禁 `verify-md-links`（`scripts/verify-md-links.ts`），风格与 `verify-md-wrap` 一致（tsx ESM、基于 AST、只验证不生成）：
- 使用 `mdast-util-from-markdown` + GFM 解析每个范围内的 Markdown 文件，遍历所有 `link`、`image` 和 `definition` 节点。
- 仅当目标是**相对路径**时才检查。跳过带协议的 URL（`https:`、`mailto:` 等）、协议相对路径（`//host`）、根绝对路径（`/path`，在检出目录中没有稳定基准）以及纯页内锚点（`#section`）。剥除 `#fragment`/`?query`，相对于链接所在文件的目录解析路径，并断言目标在磁盘上存在。
- 只报告、不改写；发现第一条死链即以非零状态退出。
检查范围与其他门禁一致，并额外包含 AGENTS.md 文件对以及 `.agents/skills/` 下仓库自有的 agent-skill（技能）Markdown（这些 skill 文件会交叉链接到 docs 目录树，因此本次重组也改写了其中的链接）：`README.md`、`docs/**/*.md`、`packages/*/README.md`、`AGENTS.md`、`packages/AGENTS.md`、`.agents/skills/**/*.md`。系统按真实路径去重（`CLAUDE.md` symlink 会解析到 AGENTS.md 文件）。该检查接入 `doc-sync`，因此相关文档变更与 CI 执行同一套断链检查。
本门禁检查的是*文件存在性*，而非锚点有效性：指向一个真实文件但带有 `#wrong-heading` 片段的链接仍会通过（文件可解析；片段被剥除）。
## 曾考虑的替代方案
**锚点级有效性检查**：更重且价值更低；实际造成问题的是文件级死链。这一范围裁剪是有意为之：作者在链接到某个锚点时自行验证 `#fragment`。
## 后果
- 造成交叉链接失效的重命名与移动会直接使 `doc-sync` 和 CI 失败，而不是等读者点击死链才暴露。由此，引入该门禁的 Agent Note 重组具备自校验能力：同一个 PR（Pull Request）在改写 40 条链接的同时，也添加了证明这些链接均未悬空的检查。
- `doc-sync` 链中多了一个快速 tsx 脚本；无新增依赖（mdast/GFM 技术栈已作为 `verify-md-wrap` 的 devDependencies 存在）。
- 该门禁强制执行的约定是：文档交叉引用必须使用可机械检查的相对链接，绝不能只写纯文本或编号。[docs/AGENTS.md](../../../../docs/AGENTS.md)记录了这项约定，使作者了解该门禁及其理由。

6
.agents/notes/implemented/process/2026-06-20-agent-note-classification.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-20-agent-note-classification.md: 094233ed108e35e390cdc66b419179249c2d9173
2026-06-20-agent-note-classification.zh.md: b424b07e051507a894c8f5961feb5fe24a9da3c6

2
.agents/notes/implemented/process/2026-06-20-agent-note-classification.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-06-20-agent-note-classification.zh.md)
## Problem
A lifecycle-only Agent Note tree — `proposed/` / `implemented/` / `rejected/` — does not record what *kind* of decision each file contains. A reader browsing one lifecycle cannot distinguish a new capability from a removal or a tooling-policy change without opening each file.

48
.agents/notes/implemented/process/2026-06-20-agent-note-classification.zh.md Normal file
View File

@@ -0,0 +1,48 @@
# Agent Note: 通过路径编码的子目录对 Agent Note 进行分类
Status: implemented
[English](2026-06-20-agent-note-classification.md) | 中文
## 问题
仅按生命周期组织的 Agent Note（agent 决策记录）目录树（`proposed/` / `implemented/` / `rejected/`）无法记录每个文件包含哪一*类*决策。读者浏览某个生命周期时，如果不逐一打开文件，就无法区分新功能、移除项或工具策略变更。
本仓库一贯的倾向是[机械质量门禁优于行文规范](2026-06-11-quality-gates.md)：不被机器检查的约定终将腐烂。因此这里的分类方案必须可强制执行，而非靠自觉的文件头。
## 决策
增加第二个维度，即 Agent Note 的**类别**，并将其编码在路径中：`{lifecycle}/{class}/yyyy-mm-dd-topic.md`。文件夹*就是*标签。文件位置声明其类别；封闭集合限定为「这些文件夹且仅限这些」；既有的 [verify-md-links](2026-06-18-markdown-cross-link-lint.md) 门禁已经保护移动文件所需的路径改写。
### 六个类别的封闭集合
| 类别 | 涵盖范围 |
|---|---|
| `feature` | 面向用户或模型的新功能。 |
| `bug-fix` | 修正缺陷或填补事后复盘暴露的空白。 |
| `simplification` | 移除代码、行为或对外表面积，不引入新功能。 |
| `architecture` | 关于**交付源码**的结构性决策——包（package）之间的关系、运行时词汇。 |
| `process` | **围绕**代码的工具、策略或工作流，而非运行时行为。 |
| `testing` | 测试基础设施与策略。 |
`architecture` 与 `process` 的分界是：**architecture** 关乎我们交付的源码；**process** 关乎源码周边的工具与工作流。本 Agent Note 本身属于 `process` 决策：它改变仓库的组织方式与门禁，而不是 harness 的运行时行为，因此位于 `implemented/process/` 下。
### 两道门禁
两者都是 `doc-sync`（文档同步门禁）的成员，风格与 `verify-md-wrap` 一致（tsx ESM，只校验不生成，首个违规即以非零退出码退出）：
- **`scripts/verify-agent-note-classification.ts`**：定义封闭的生命周期与类别集合。它断言生命周期文件夹下的每个文件都位于规范集合中的类别文件夹内（生命周期根目录下散落的 `.md` 或未知类别文件夹都会失败），并拒绝集中式 `INDEX.md`。规范集合位于 `scripts/agent-note-tree.ts` 中，[README](../../README.md)则以行文记录每个类别。
- **`scripts/verify-doc-refs.ts`**：检查引用文档的源码注释。Agent Note 路径不仅出现在 Markdown 中，也出现在 TypeScript 文档注释中（例如以仓库根为起点的 `.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md`）。`verify-md-links` 看不到这些引用，因此目录重组可能静默留下失效引用。该门禁扫描 `packages/**` 与 `examples/**` 下仓库自有的 `.ts` 文件（排除已构建的 `lib/` 与 `vendor/`），查找 `docs/….md` 和 `.agents/notes/….md` token，解析每个以仓库根为起点的路径并断言其存在。它要求使用 `.md` 扩展名，因此不处理无扩展名的行文。
## 曾考虑的替代方案
- **在每个文件中添加 `Classification:` 行文行**（紧邻 `Status:`），由门禁解析。可行，但它将路径已能承载的事实重复到文件中，且行内容可能与所在文件夹不一致。路径编码使标签与其存储合二为一，没有需要保持同步的东西。
- **设立 `refactor` 类别。** 与 `simplification` 几乎完全重叠；唯一有人试图用来区分的标准是「可观察行为是否改变？」，而 `simplification` 已经编码了这一点（它不改变）。一个类别即可，无需两个。
- **生成或手工维护的语料索引。** 不予采纳：生命周期/类别目录树才是权威结构；集中式清单会制造合并热点，却没有提供目录树导航或仓库搜索无法实现的发现能力。单独的[索引提案](../../rejected/process/2026-07-04-generate-agent-note-index-tables.md)记录了被放弃的生成形状。
## 后果
- 每份 Agent Note 都位于一个类别文件夹下。读者浏览单个文件夹，即可查看某个生命周期内的全部简化或测试决策。
- `doc-sync` 链中多了两个快速 tsx 脚本；无新依赖（mdast/GFM 栈已因 `verify-md-wrap`/`verify-md-links` 而存在）。
- 新增类别必须是显式决策：修改 `scripts/agent-note-tree.ts` 中的 `const` 与 [Classification 章节](../../README.md#classification)，而不是只用 `mkdir` 创建文件夹。门禁会拒绝未知文件夹，因此临时类别无法悄然混入。
- 源码注释中的文档引用同样受门禁约束：被 `.ts` 注释引用的文档一旦移动或重命名，`doc-sync` 与 CI 中的 `verify-doc-refs` 就会失败，从而堵住 `verify-md-links` 在结构上无法发现的一类漂移。

6
.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-20-core-data-structures-catalog.md: d7e9d3d9b14fe723e3396c8167fe714b7613e2b5
2026-06-20-core-data-structures-catalog.zh.md: 8d2f16a46216cba8df0539be0abd2f1ad840eec3

2
.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-06-20-core-data-structures-catalog.zh.md)
## Problem
A reader trying to understand the harness could find its *behavior* in [architecture.md](../../../../docs/architecture.md) (the service map, the session/turn/step lifecycle, the event taxonomy) but had no single place describing its *vocabulary* — the data structures that behavior moves around. The type shapes lived only in source, scattered across `packages/*/src/types.ts`, so understanding "what is a `Message`, a `SessionEvent`, a `StreamChunk`" meant reading the declarations directly. A prose catalog would help, but a catalog that paraphrases or paste-copies type definitions rots the instant a field changes — and an out-of-sync type doc is worse than none, because a reader trusts it.

60
.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md Normal file
View File

@@ -0,0 +1,60 @@
# Agent Note: 核心数据结构目录与 `ts type-equiv` 漂移门禁
Status: implemented
[English](2026-06-20-core-data-structures-catalog.md) | 中文
## 问题
试图理解 harness 的读者可以在 [architecture.md](../../../../docs/architecture.md) 中找到它的*行为*（服务图、会话/轮次/步骤生命周期、事件分类），却找不到一个统一描述其*词汇*的地方，也就是这些行为所传递的数据结构。类型形状只存在于源码中，散落在 `packages/*/src/types.ts` 各处，因此要理解“什么是 `Message`、`SessionEvent`、`StreamChunk`”，就必须直接阅读声明。文字目录会有所帮助，但复述或复制粘贴类型定义的目录会在字段发生变化时立即腐化，而不同步的类型文档比没有文档更糟，因为读者会信任它。
因此，这项工作有两个相互交织的问题：**这样的目录应包含什么**（范围问题——harness 有数十种跨包（package）边界的类型，把它们全部倾倒进来对谁都没有帮助），以及**如何避免粘贴的类型定义发生漂移**（持久性问题）。本 Agent Note（agent 决策记录）记下了这两项决策。与它配套的[生成式 Cordis 事件与服务目录](2026-06-20-generated-cordis-catalog.md)从*接线*维度形成补充：本文对数据结构编目，另一篇则对传递这些结构的事件和服务编目。
## 决策
新增的 `docs/core-data-structures/` 目录对这些词汇编目，并配有新的 `verify-type-equiv` 文档同步门禁，使每个粘贴的类型声明及其 JSDoc 与源码保持同步。
### 何为"核心"——主干与 seam 的分界线
范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算"核心"，那么"核心"就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，"核心"就意味着*中央主干*，bash 词汇归入子页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是子页面细节。*** 逐一验证如下：
- 一个数据结构是**核心**的，如果它流经 agent loop 主干——无论加载了哪些插件，循环在每个轮次都会持有、派生、流式输出或记录它（`Message`、`StreamChunk`、`SessionEvent`、`Agent` 句柄）——**或者**它是插件作者面对某条流水线时编写的唯一标志性类型（`ToolDefinition`）。
- `ToolDefinition` 是核心（它是每个工具作者编写的东西），**即使循环从不持有它**——对于这一个标志性类型，撰写重要性压过了严格的"流经主干"规则。但它的类型推导机制——`ValueSchemaSpec`、`ParameterSchemaSpec`、`InferValue` 与 `InferArgs`——是子页面细节。这就是主干与 seam 分界线的精确表述。
- `ToolSchema` 是核心（它是流经每个步骤的模型请求 `GenerateOptions` 的一个字段），即使它在概念上属于工具流水线——当*流经主干*与*概念归属*冲突时，前者胜出。
- 工具展示词汇（`ToolCallView`/`ToolResultView` 等）、`SessionPersistence` 持久性 seam 以及 bash 词汇是子页面。
`core.md` 是一份**自包含的主干文档**：它给出每个主干结构的确切类型定义，辅以最少的行文，并链接到子页面获取各 seam 的细节。子页面包括 `llm-streaming.md`、`session.md`、`persistence.md`（沿内存模型与持久性 seam 的分界线从会话页面拆出）、`tools.md` 和 `bash.md`。
### `ts type-equiv` 机制——既逐字又防漂移
持久性要求很具体：文档展示当前类型声明与原始 JSDoc 的**逐字**内容（让读者看到真实形状和源码契约，而非复述），**并且**以机械方式保证其与源码匹配。仓库已经会编译 ` ```ts ` 围栏块（`doc-typecheck`），但真正接受类型检查的块需要导入噪音，而且只能证明*可赋值性*——字段改名或 JSDoc 变化仍可能通过。因此：
- 完整的类型声明及其 JSDoc 会逐字粘贴到专用的 ` ```ts type-equiv ` 围栏中。简洁的 ` ```ts public-api ` 围栏承载与源码等价的类环境投影，用于实现体不应进入目录的类。`doc-typecheck` 会识别并跳过这两种围栏（裸声明无法独立编译），并且**将它们排除在 opt-out 比例之外**——它们是单独受检的类别，而不是未经检查的草图。
- 新增的 `scripts/verify-type-equiv.ts` 通过 TypeScript 解析器提取每个块，并断言其声明结构和每条 JSDoc 注释都与所声明的符号匹配，只忽略格式空白和非 JSDoc 注释。普通块保留完整声明。`public-api` 投影保留类的公共字段、构造函数、访问器和方法及其原始 JSDoc，同时移除实现体以及私有或受保护成员。之所以选择它而非编译式 `_Check` 断言，是因为目录所保留的是源码名称与文档一致性，而不是可赋值性。
- 来源信息存放在集中的 `scripts/type-equiv.manifest.json`（`{ doc, symbol, source }` 条目）中，**而非**行文中的指令注释。脚本强制执行 **1:1 对应**：每个 type-equiv 块恰好有一条 manifest 条目，反之亦然；因此一个块永远不会被静默漏检，一条条目也永远不会腐烂。
- 接入 `doc-sync`，因此相关文档变更会在本地运行它，CI 也会与其他文档检查一起运行它。
### 维护是作者的职责，门禁作为兜底
`verify-type-equiv` 能捕获已记录类型的*粘贴漂移*，但无法告诉你一个全新的核心类型没有被记录。因此 AGENTS.md 和 `dsh-code-review` skill（技能）已更新，要求在变更添加或重塑已记录类型时同步更新目录——门禁处理漂移，人处理新增表面。
## 曾考虑的替代方案
- **平铺罗列所有跨包词汇**：`BashExecRequest` 测试案例否决了它。如果 seam 词汇算"核心"，目录对谁都没帮助；分层的主干与 seam 结构胜出。
- **用编译式 `_Check` 可赋值性断言**代替源码匹配：否决。可赋值性不会保留名称或 JSDoc；同类型字段改名或契约注释变化仍会通过。
- **来源信息作为行文中的指令注释**：否决，改用集中 manifest；其强制的 1:1 对应确保一个块永远不会被静默漏检，一条条目也永远不会腐烂。
## 验证教训
主干与 seam 规则在采纳前经过了 `BashExecRequest`、工具 schema 与定义、schema DSL、展示类型以及会话/持久化拆分的逐一测试。
`verify-type-equiv` 必须扫描完整的 Markdown 范围，而不仅是清单点名的文档。否则，未列入清单的 `type-equiv` 块就会逃过所宣称的一一检查。因此，门禁会将此类块报告为孤儿。本 Agent Note 将这条失败关闭扫描规则，连同主干与 seam 的分界决策及逐字匹配决策一并记录；生成式 Cordis 目录在[其 Agent Note](2026-06-20-generated-cordis-catalog.md) 中有对称的设计记录。
## 后果
- 这些词汇现在有一个**无法悄然漂移**的唯一归属：源码中的字段或公共类成员发生变化后，`doc-sync` 和 CI 中的 `verify-type-equiv` 会持续失败，直至粘贴内容刷新。Cordis 服务方法仍由生成式服务目录负责，而不会在此重复。
- 主干与 seam 分界线是一个可复用的范围界定工具，而非一次性的：同一条「你编写/持有/接收的东西是核心；为其提供类型推导/渲染/持久化的机制是细节」规则，后来也被用于界定事件/服务目录的 harness 层与继承层分层。
- `ts type-equiv` 围栏是继 ` ```ts `（编译）和 ` ```ts ignore-check `（草稿）之后的第三种文档块类别。后续的姊妹门禁又增加了第四种 ` ```ts cordis-catalog `（生成签名），复用了相同的跳过并排除处理。
- 添加或重塑核心类型现在附带一项文档义务，作者必须履行（门禁无法检测缺失的*新*类型），由 `dsh-code-review` 检查清单兜底。

6
.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-20-generated-cordis-catalog.md: b5957cf06a9316447aae70183de462024bb24be3
2026-06-20-generated-cordis-catalog.zh.md: 35ed06c4a8e13245a37adaa4d5da7a842e97c0c7

2
.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-06-20-generated-cordis-catalog.zh.md)
## Problem
A plugin author needs two reference surfaces that no single document gave them: every cordis **event** they can listen to (with its exact signature and dispatch mode) and every `ctx.<key>` **service** they can call (with its exact interface). The pieces existed but were scattered — a hand-maintained event-taxonomy *table* in `docs/architecture.md` (names + prose Mode/Purpose, name-set-checked by `verify-event-taxonomy`), a Service-map table (8 rows of role prose), and the `interface Events` / `interface Context` declarations themselves. The taxonomy table also could not catch a brand-new *undocumented* event: a name-set verifier only checks the names that are already in the table on both sides.

41
.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.zh.md Normal file
View File

@@ -0,0 +1,41 @@
# Agent Note: 生成式 Cordis 事件与服务目录
Status: implemented
[English](2026-06-20-generated-cordis-catalog.md) | 中文
## 问题
插件作者需要两个参考面，而此前没有任何单一文档能提供：他们可以监听的每一个 Cordis **事件**（含精确签名与分发模式），以及他们可以调用的每一个 `ctx.<key>` **服务**（含精确接口）。相关信息虽然存在，但散落各处：`docs/architecture.md` 中一张手工维护的事件分类*表格*（名称 + 行文描述的 Mode/Purpose，由 `verify-event-taxonomy` 做名称集合校验）、一张服务映射表（8 行角色描述），以及 `interface Events` / `interface Context` 声明本身。分类表格还有一个盲区：它无法捕获全新的*未记录*事件——名称集合校验器只检查两侧已有的名称。
这是对[核心数据结构目录](../../../../docs/core-data-structures/core.md)（[其 Agent Note（agent 决策记录）](2026-06-20-core-data-structures-catalog.md)）在接线维度上的补充：前者对循环传递的*数据结构*编目（经验证的手工粘贴），本文则对传递它们的*事件和服务*编目。
## 决策
从源码生成目录，取代手工维护表格并校验子集的方式。
`scripts/gen-cordis-catalog.ts` 使用 TypeScript 编译器 API，根据声明和源码 JSDoc 分别生成事件与服务参考。事件包含分派模式及其原始成员 JSDoc；服务包含公共签名及各方法的原始 JSDoc。确定性的 `--write` 和 `--check` 模式使两个页面成为生成产物，并由 `doc-sync` 强制检查新鲜度。
纯生成在此处是正确的，因为代码库足够规范，AST 就是全部事实：每个事件/服务名称都是字符串字面量，可以往返映射到静态声明——不存在动态命名的事件，也不存在仅运行时的服务。因此生成的文档不可能出错，且从结构上消除了未记录事件的缺口（生成器枚举源码，而非校验手写子集）。
具体选择：
- **`@mode` 标签，交叉校验。** 每个 harness 事件的 JSDoc 携带一个显式的 `@mode emit|waterfall|parallel|serial` 标签；缺少标签时生成器直接报错。当签名形状具有决定性时——尾部参数为 `next: () => …` 在结构上即为 waterfall（瀑布式事件）——生成器断言标签与之一致，矛盾时直接报错。emit/parallel/serial 的区别在结构上不可见（`session/flush` 返回 `Promise<void> | void` 且无 `next`，有序的 `agent/pre-step` 检查点亦然），因此信任标签。编写规则见 [AGENTS.md](../../../../AGENTS.md)。
- **分层范围。** harness 层（8 个 `@deepseek-ai/dsh-*` 服务及其事件）从源码完整渲染。继承层（cordis-core 的 `ctx.on/emit/effect/provide/…` + `internal/*` 事件 + loader/hmr/timer）是插件同样可见的固定 vendor 源码；它从生成器中一张人工维护的表格简洁渲染（名称 + 一行描述 + 源码指针），而非遍历 vendor AST。原因是 cordis-core 的 `Context` 混合了真正的 ctx 成员与非服务字段（`root`、`baseUrl`、`logger`），且 vendor 接口面仅在有意的 vendor 同步时才变化。
- **指向数据结构目录的交叉链接。** 签名中由仓库拥有的每个类型名（`GenerateOptions`、`StreamChunk`、`ToolDefinition`……）都会通过人工维护的映射链接到其主要核心数据结构页面。AST 遍历采用失败关闭策略：每个参数、泛型约束/默认值和返回类型引用都必须已映射、是签名自身的类型参数、是点名的 TypeScript/Cordis 基础类型，或带有点名的例外及其非目录文档归属。违规会连同源码位置汇总报告，并点明相应的归属列表。该映射不会复用 `type-equiv.manifest.json`，因为后者记录 `…Map` 符号，而签名引用派生的联合类型名，并且会在多个页面列出某些符号。
- **专用围栏。** 签名块使用 ` ```ts cordis-catalog ` 信息字符串，并把原始事件或公共方法 JSDoc 直接放在其声明之前。`doc-typecheck` 会识别并跳过这些裸片段，将其排除在 opt-out 比例之外——与 `type-equiv` 块的处理相同。
本决策**取代** [doc-sync 强制](2026-06-11-doc-sync-enforcement.md)中事件分类的那一半：`verify-event-taxonomy` 及其 `docs/architecture.md` 表格退役（architecture.md 的标题保留，正文改为指向目录；服务映射的角色表格作为人工行文保留）。doc-typecheck、verify-md-wrap、verify-md-links 和 verify-type-equiv 不受影响。
## 曾考虑的替代方案
- **校验而非生成（退役的分类检查所做的事）**：*仅对本参考面*反转了这一策略。此处的数据可以机械地完整获取，因此生成严格强于对手工表格做名称集合校验（完整签名、不会漂移、能捕获未记录事件）。
- **遍历 vendor AST 以获取继承层**：否决，改用人工维护表格。cordis-core 的 `Context` 混合了真正的 ctx 成员与非服务字段，且固定的 vendor 接口面仅在有意同步时才变化。
- **复用 `type-equiv.manifest.json` 作为签名交叉链接映射**：否决，改用完整的人工维护常量和失败关闭覆盖。清单记录 `…Map` 符号，而签名引用派生的联合类型名，并且会在多个页面列出某些符号。显式映射让每个渲染目标和每个非目录例外都成为可评审的决策。
## 后果
- 目录不会发生漂移：提交文件未反映的源码变化会使 `doc-sync` 和 CI 中的 `verify-cordis-catalog` 失败。新事件缺少 `@mode` 标签、标签与其签名冲突，或签名类型未分类，都会直接使生成器失败。
- 事件与服务方法契约只有一个归属——声明处的 JSDoc。目录会在生成的签名块中重复该原始 JSDoc，并使用其描述部分作为条目正文，因此单薄的源码文档只会生成单薄的目录条目。
- 继承层是手工摘要，因此 vendor 同步若新增或重命名了 cordis-core 事件或 `ctx` 成员，需要同步编辑 `gen-cordis-catalog.ts` 中的人工维护表格。这是不遍历固定 vendor 源码的有意代价；它很少变化，且在生成器中有明确标注。
- `verify-event-taxonomy.ts` 被删除，`docs/architecture.md` 的事件表格也已移除；之前链接到特定表格行的人现在会落在生成目录上。

4
.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-02-bilingual-docs-and-pairing-gate.md: 3be1d5d8fd9dba20cfca34c79cb01d89fad8097a
2026-07-02-bilingual-docs-and-pairing-gate.zh.md: a8aa8812934e755fe0175c8f3f20d194e4d24b4a
2026-07-02-bilingual-docs-and-pairing-gate.md: 4bc02878a0ea3f998e411ecc2b064c1626eacf3c
2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 90a0c2f07f68b0fb4e26cd1c4b537a30a829b10f

6
.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
View File

@@ -13,8 +13,14 @@ This repo's README and docs tree are read by people and agents inside and outsid
- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).
- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.
- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: required pairs exist, every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical), excluded (generated or bilingual-by-construction) files stay unpaired, and date-named documents on or after the manifest's `requiredSince` cutoff have complete pairs. The `required` list in [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) is a ratchet: each merged translation batch adds its files, so coverage only grows.
- **The enforcement frontier advances in coherent review batches.** A related set enters `required` only when reviewers can evaluate it as a unit. The core frontier groups [architecture](../../../../docs/architecture.md), the [Cordis primer](../../../../docs/cordis-primer.md), [defensive patterns](../../../../docs/defensive-patterns.md), the [glossary](../../../../docs/glossary.md), and [testing](../../../../docs/testing.md) because their terminology, links, and contributor contracts inform one another; admitting only part would leave the enforced corpus internally inconsistent. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.
- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.
- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.
## Verification
The verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../scripts/translation-prompt.snapshot.ts) pins the rendered system message, five reviewed example pairs, source request, and consumed response. Together these checks make pair drift, publication drift, configuration misclassification, and model-visible prompt drift review-visible.
## Alternatives considered
- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this Agent Note: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.

6
.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
View File

@@ -13,8 +13,14 @@ Status: implemented
- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。
- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。
- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：required 的配对必须存在；任何已存在的配对必须完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）不得配对；凡文件名以日期开头且日期不早于 manifest（元数据清单）中 `requiredSince` 分界日期的文档，也必须有完整配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单只进不退：每个合并的翻译批次将自己的文件加入其中，覆盖面只增不减。
- **执行红线按连贯的评审批次推进。** 一组相关文档只有在评审者能够将其作为整体评估时，才进入 `required`。核心红线将[架构](../../../../docs/architecture.md)、[Cordis 入门](../../../../docs/cordis-primer.md)、[防御性模式](../../../../docs/defensive-patterns.md)、[术语表](../../../../docs/glossary.md)和[测试](../../../../docs/testing.md)归为一组，因为它们的术语、链接和贡献者契约相互关联；只纳入其中一部分会使受门禁约束的文档集合内部不一致。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。
- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。
- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。
## 验证
验证契约分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。
## 曾考虑的替代方案
- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。

6
.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-02-tool-schema-catalog.md: c8cc69df428f6eee0f66ed976865afe2a0702448
2026-07-02-tool-schema-catalog.zh.md: f08cb5b5312dd07f91037a4382bf5e416cae552d

2
.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-07-02-tool-schema-catalog.zh.md)
## Problem
The repository had no single reference for the names, descriptions, and JSON Schemas actually exposed to the model. Source declarations are scattered and runtime-composed, while the existing Cordis and data-structure catalogs cover wiring and vocabulary rather than tools.

55
.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md Normal file
View File

@@ -0,0 +1,55 @@
# Agent Note: 生成式工具 schema 目录（启动并采集）
Status: implemented
[English](2026-07-02-tool-schema-catalog.md) | 中文
## 问题
仓库此前没有一份统一的参考文档来记录实际暴露给模型的工具名称、描述与 JSON Schema。源码声明分散各处且在运行时组合，而既有的 Cordis 目录和数据结构目录覆盖的是接线与词汇，而非工具。
## 决策
目录通过**启动每个工具插件并读取其已注册 schema** 来生成，而不是解析源码。`scripts/gen-tool-catalog.ts` 在全新的 Cordis `Context` 上挂载每个已发布工具包（package）；该上下文还提供 `SystemPrompt`、`ToolRegistry` 以及插件 `apply` 所读取的注入 seam。生成器调用 `ctx.tools.schemas()`——也就是发送给模型的确切 `ToolSchema[]`——随后释放上下文，并为每个包渲染一个 `## <package>` 章节，每个工具附带一个 ` ```json ` `parameters` 块。它与 `gen-cordis-catalog` / `gen-module-graph` 的 CLI 形状一致：默认 `--write` 重新生成；提交副本陈旧时 `--check` 失败；输出具有确定性（按清单排序，工具按名称排序）。`verify-tool-catalog`（即 `--check`）在 `doc-sync` 内运行，因此相关文档变更和 CI 会执行同一项新鲜度检查。
### 为何启动而非解析（核心要点）
Cordis 目录是纯 TypeScript AST 遍历，因为每个事件/服务名都是字符串字面量，可以往返映射到静态声明——AST 即全部事实。**工具 schema 在静态层面不可知**，因此同样的技术会产出一份说谎的文档：
- `tool-todo` 写了 `enum: [...STATUSES]`——对一个运行时 `const` 的展开。AST 看到的是展开表达式，而非 `["pending","in_progress","completed"]`。
- 每条 description 都通过字符串**拼接**构建（`'…' + '…'`）。AST 看到的是拼接节点，而非模型实际读到的最终文本。
- `tool-subagent` 的工具名是 `config.toolName ?? 'subagent'`——加载时选定，并非字面量。
- MCP 插件可以通过 `ctx.tools.register()` 直接注册**原始 JSON Schema**，完全不经过 `defineTool`，因此结构化枚举 `defineTool(` 调用点会遗漏。
唯一准确的真源，是插件加载后注册表实际持有的 schema。启动插件是把[测试策略](../../../../docs/testing.md)中“验证现实，而非自我报告”的准则应用到文档生成器：读取已发布产物，而非重新推导一份。
### 恢复「不会静默遗漏」的保证
启动有一项 AST 遍历不存在的代价：没有源码声明集合可供枚举，新工具包可能被遗忘。一个**完整性守卫**恢复了这项保证——`assertManifestComplete` 对 `packages/` 下所有 `tool-*` 包进行 glob，若有任何一个不在生成器的启动 manifest 中则直接报错。新工具包在注册之前会导致生成器失败，进而导致 `doc-sync` 失败。这与 Cordis 生成器通过枚举源码免费获得的结构性属性相同，只是为基于启动的生成器重新实现了一遍。
### 手动维护的启动 manifest 是不可化约的策略
文件系统负责发现工具包清单，完整性守卫负责拒绝遗漏。`TOOL_PACKAGES` 仍然为每个包持有一份显式的启动配方，因为所需的 seam 实现和配置属于策略，不是能从目录布局或注入名称安全推断的事实。
### 范围
`packages/*/tool-*` 下已发布的产品工具包，每个都使用默认配置启动，包括 `dsh-tool-bash`（`bash`）、`dsh-tool-tasks`（`task_output`、`task_list`、`task_kill`）和 `dsh-tool-subagent`（`subagent`）。仅供示例使用的工具不在范围内。
目录的单位是包，而非每个配置化的工具实例。每个包以默认配置启动一次；加载时的别名（如 `subagent_fork`）会注明，但不枚举所有部署排列。部署清单是一个独立的、无界的接口。
### 使用普通 `json` 围栏
schema 块使用 ` ```json `，而非自定义的 `ts` 系围栏。`doc-typecheck` 只提取 `ts*` 围栏，因此 JSON 块对它不可见——无需 `BlockKind` 接线（不同于 Cordis 目录的 `ts cordis-catalog` 围栏，后者需要加入白名单以避免裸签名片段被编译）。
## 曾考虑的替代方案
- **纯 TypeScript AST 遍历，如 Cordis 目录**：工具 schema 在静态层面不可知（见上文核心要点）：运行时展开、字符串拼接、配置选定的名称，以及原始 `ctx.tools.register()` 注册，都会让 AST 推导出的文档说谎。
- **从各包的 inject 推断启动配方**：属于[发现包清单提案](../../proposed/process/2026-06-20-discover-package-inventory.md)所警告的「过度聪明」路径；配方保持为手写策略，清单由文件系统发现并由完整性守卫把关。
- **为 schema 块使用自定义 `ts` 系围栏**：不必要。普通 ` ```json ` 围栏对 `doc-typecheck` 不可见，无需 `BlockKind` 白名单。
## 后果
- 目录不会发生漂移：提交文件未反映的工具 schema 变化会使 `doc-sync` 和 CI 中的 `verify-tool-catalog` 失败。新增的 `tool-*` 包若未加入清单，会直接使完整性守卫失败。
- 工具描述文本有唯一归属——源码中 `defineTool` 的 `description`——生成的条目质量取决于它，与 Cordis 目录对事件 JSDoc 施加的强制力相同。
- 生成器导入并执行工作区包（这是仓库中第一个这样做的脚本；其他脚本只读文本）。它通过根 `tsconfig` 的 `paths` 映射在 `tsx` 下运行，使用与演示和测试相同的未构建源码路径，因此不需要构建步骤。
- 未来某个工具背后新增一个能力 seam，意味着 manifest 中需要新增一条配方条目（声明要挂载哪些 seam）。这正是上文指出的有意为之的手写成本；仅在新增工具包时才需变更。

6
.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-03-documentation-graph-atlas.md: 9a30b13f9db6ceb2715517230e349cbe083850ec
2026-07-03-documentation-graph-atlas.zh.md: 0734a2c659459f40ee81b9960f259681cb35891c

2
.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-07-03-documentation-graph-atlas.zh.md)
## Problem
The repo already had several high-trust documentation surfaces, each on a different axis: [module-graph.md](../../../../docs/module-graph.md) is generated from package `peerDependencies`, the generated [Cordis events](../../../../docs/cordis-catalog/events.md) and [services](../../../../docs/cordis-catalog/services.md) catalogs are generated from Cordis `Events` and `Context` declarations, [tool-catalog.md](../../../../docs/tool-catalog.md) is generated by booting shipped tool plugins, and [core-data-structures/](../../../../docs/core-data-structures/core.md) uses `ts type-equiv` blocks to keep pasted type definitions synchronized with source.

70
.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.zh.md Normal file
View File

@@ -0,0 +1,70 @@
# Agent Note: 面向维护者与 SDK 用户的文档关系图索引
Status: implemented
[English](2026-07-03-documentation-graph-atlas.md) | 中文
## 问题
仓库已经有若干高可信文档表面，各自覆盖不同维度：[module-graph.md](../../../../docs/module-graph.md) 根据包（package）的 `peerDependencies` 生成；生成式 [Cordis 事件](../../../../docs/cordis-catalog/events.md)和[服务](../../../../docs/cordis-catalog/services.md)目录根据 Cordis `Events` 和 `Context` 声明生成；[tool-catalog.md](../../../../docs/tool-catalog.md) 通过启动已发布工具插件生成；[core-data-structures/](../../../../docs/core-data-structures/core.md) 则使用 `ts type-equiv` 块使粘贴的类型定义与源码保持同步。
这些参考文档是准确的，但大多是目录式的。维护者仍需自行综合关系：哪些包构成一个能力 seam、哪个应用组装了具体的主干、哪些事件是持久的而哪些是实时的、钩子或策略插件在哪里可以拦截工作、以及哪个面向模型的工具依赖哪个服务。SDK 用户从另一个角度面临同样的问题：「我想要某种行为，应该安装或加载哪个包？应该扩展哪个事件/服务/工具？」
钩子子系统使事件的生产者/消费方拓扑与拦截点变得更加重要；文件系统 seam 使能力 seam、策略否决、工具呈现与 SDK 组装路径变得更加重要。如果关系图的范围仅限于一个小的 bash/todo/subagent 表面，它们会立即陈旧。
## 决策
新增生成式关系图文档，由聚焦的生成器产出并在 [docs/graph-atlas.md](../../../../docs/graph-atlas.md) 建立索引；作为 `doc-sync` 的一部分，通过 `pnpm run verify-doc-graphs` / 现有目录新鲜度检查进行验证。
该索引是既有目录之上的关系层。它不取代精确的参考文档，而是链接到它们并解释各部分如何组合在一起。
### 维护模式
每个关系图页面声明一种维护模式：
- **Generated（生成）**：所有节点和边均从源码发现；如果已提交的产物陈旧，`--check` 失败。
- **Hybrid generated（混合生成）**：源码发现清单，一个小型 manifest 对不可约的策略进行分类，完整性守卫在发现的条目未被分类时失败。
- **Curated（人工策划）**：图表解释设计意图、时序或归属；它由生成器输出以使关系图文档保持为可重新生成的整体，但内容是有意撰写的。
### 首批发布的索引
该索引链接十一种关系表面。包拓扑和工具包所提供的功能位于已经拥有这些事实的现有生成式目录中；其余聚焦图表由 `scripts/gen-doc-graphs.ts` 生成。
| 关系图 | 维护模式 | 真源 |
|---|---|---|
| [模块依赖图](../../../../docs/module-graph.md) | 生成式 | `packages/*/*/package.json` 的对等依赖（peer dependency）与包分组路径 |
| [工具 schema 目录与包映射](../../../../docs/tool-catalog.md) | 生成式 | 启动后采集的工具 schema，以及工具包服务/效应元数据 |
| [能力 seam 与核心服务](../../../../docs/capability-seams.md) | 混合生成式 | Cordis 服务声明，以及 `gen-doc-graphs.ts` 中的角色清单 |
| [tui-agent 应用组合](../../../../examples/tui-agent/composition.md) | 混合生成式 | `examples/tui-agent/cordis.yml` 插件列表，以及人工维护的应用/bundle 展开 |
| [headless-agent 应用组合](../../../../examples/headless-agent/composition.md) | 混合生成式 | `examples/headless-agent/cordis.yml` 插件列表，以及人工维护的应用/bundle 展开 |
| [cordis-agent 应用组合](../../../../examples/cordis-agent/composition.md) | 混合生成式 | `examples/cordis-agent/cordis.yml` 插件列表，以及人工维护的应用/bundle 展开 |
| [acp-agent 应用组合](../../../../examples/acp-agent/composition.md) | 混合生成式 | `examples/acp-agent/cordis.yml` 插件列表加人工策划的应用/bundle 展开 |
| [事件生产者/消费方矩阵](../../../../docs/event-producer-consumer.md) | 混合生成式 | Cordis 事件声明、经 AST 扫描的 `ctx.on/emit/parallel/serial/waterfall` 位置，以及显式动态分派覆盖 |
| [agent 轮次与步骤生命周期](../../../../docs/agent-lifecycle.md) | 人工维护 | architecture.md 循环生命周期、Cordis 目录链接，以及会话事件语义 |
| [工具执行管线](../../../../docs/tool-execution-pipeline.md) | 人工维护 | 工具管线语义与 `tools/execute` waterfall（瀑布式事件）|
| [ACP（Agent Client Protocol）快照回放](../../../../packages/ui/acp/snapshot-replay.md) | 人工策划 | 快照 harness 行为 |
### 为什么由生成器拥有文档
包拓扑留在 `gen-module-graph.ts`，工具-包能力映射留在 `gen-tool-catalog.ts`，因为这些生成器已经拥有权威事实和新鲜度门禁。`gen-doc-graphs.ts` 拥有其余关系页面和索引。代价是人工策划的图表需要在 TypeScript 字符串块中编辑，而非直接编辑 Markdown。对于首版来说这是可接受的，因为面向用户的产物仍然是纯 Markdown/Mermaid；未来如果撰写体验比可重新生成更重要，可以将人工策划的页面拆分出去。
### 完整性守卫
混合生成的页面在其 manifest 陈旧时必须显式报错：
- 模块图读取每个包的 `peerDependencies`，并按 `packages/<group>/<pkg>` 路径对包进行分组。
- 工具目录通过启动收集已发布的工具，并从同一份 manifest 渲染包/服务/副作用映射（其完整性守卫已在检查该 manifest）。
- 能力 seam 图导入 Cordis 服务收集器，断言每个发现的 harness `ctx.<key>` 都已在 `SERVICE_ROLES` 中分类，且每个已分类的 key 仍然存在。
- 事件生产者/消费方矩阵标记为 hybrid，因为 subagent 生命周期事件有意使用 `ctx.events.dispatch` 实现逐监听器隔离；这些动态边是显式覆盖而非无声遗漏。
- `verify-mermaid` 使用 Mermaid 自身的解析器解析仓库中每个 ` ```mermaid ` 围栏，因此语法错误在本地和 CI 的 `doc-sync` 阶段即被捕获，而非在 GitHub 渲染时才显示为损坏的图表。
## 曾考虑的替代方案
已提交的图表使用 Mermaid，因为 GitHub 在 Markdown 中原生渲染它且不引入新的文档构建依赖；密集的多对多数据（如事件生产者/消费方关系）改用 Markdown 表格。**PlantUML、托管图表服务和生成的 SVG** 曾被考虑，但在 Mermaid 成为瓶颈之前有意不采用。
## 后果
- 维护者获得了拓扑、seam、事件流、生命周期、应用组合与快照行为的可视化入口。
- SDK 用户获得了从用例到包组合的路径，而非仅有自底向上的包参考。
- `doc-sync` 现在包含 `verify-doc-graphs` 和 `verify-mermaid`，因此关系图漂移和 Mermaid 语法错误与其他文档新鲜度门禁一起被捕获。
- 未来的文件系统和钩子工作有了承载新复杂度的具体位置：文件系统应扩展能力文档和工具目录，钩子应扩展事件矩阵和工具执行流水线。

6
.agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-04-cordis-jsdoc-completeness-gate.md: c7c39986414437ce4d0d4c64f9e25f47485fdf5c
2026-07-04-cordis-jsdoc-completeness-gate.zh.md: f1e7ec824ebae119c1cb27ca4dd9f0d8330dde1a

2
.agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-07-04-cordis-jsdoc-completeness-gate.zh.md)
## Problem
The generated Cordis catalog enforced event dispatch modes but not complete service and event contracts. Methods could lack descriptions, and parameters or returns could be undocumented on the cross-plugin API surface where IDE guidance matters most.

41
.agents/notes/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.zh.md Normal file
View File

@@ -0,0 +1,41 @@
# Agent Note: 针对 Cordis 对外服务接口的 JSDoc 完整性门禁
Status: implemented
[English](2026-07-04-cordis-jsdoc-completeness-gate.md) | 中文
## 问题
生成的 Cordis 目录此前强制了事件分发模式，但未强制要求完整的服务与事件契约。方法可以缺少描述，参数或返回值可以在跨插件 API 接口上不写文档——而这恰恰是 IDE 引导最重要的地方。
AGENTS.md 中的规则（「每个导出都有解释语义的 JSDoc」）只能靠评审以行文形式检查；本仓库的既定偏好是将不变式编码为机械门禁。「Cordis 服务函数与事件」这一范围有精确的机器定义，只有目录生成器知道：事件是 `declare module 'cordis'` 内 `interface Events` 的成员，服务接口是每个 `interface Context` 键所指向的类的公开方法。ESLint 规则看不到这层映射；生成器在每次运行时计算它。
## 决策
扩展 `scripts/gen-cordis-catalog.ts`——复用同一次遍历和同一套 `@mode` 先例——对它编目的所有内容强制执行 JSDoc 完整性要求。`verify-cordis-catalog` 在 `doc-sync` 内运行，因此相关文档变更和 CI 会执行同一门禁，无需另行接线。
契约如下：
- **事件**需要描述性文字，以及为每个**载荷参数**提供非空的 `@param`。载荷参数是携带事件数据的签名参数；`this` 接收者注解和尾部的 waterfall（瀑布式事件） `next` 免检——`next` 是分发机制，其语义已由 `@mode waterfall` 标签（及其结构交叉检查）拥有，逐事件重述只是样板代码。为免检参数写文档是允许的；只有缺失才被检查。
- **服务类**需要类级 JSDoc，每个公开方法需要描述性文字、为每个参数提供非空的 `@param`，以及非空的 `@returns`——除非标注的返回类型是 `void`/`Promise<void>`（此时 `@returns` 可选——resolve 时机有时值得记录——但从不强制要求）。
- **陈旧标签报错**：`@param` 命名了一个不存在的参数即为违规，与 `@mode` 与签名矛盾的检查对称。标签描述必须非空；超出此范围的语义质量由评审负责。
- **遍历可检查的显式性**：门禁是纯 AST 遍历（不使用类型检查器），因此服务方法必须显式标注返回类型（推断的返回类型无法分类），接口参数必须是简单标识符（解构模式没有名称供 `@param` 匹配）。
- **违规聚合**为一条错误信息，列出所有违规项——修复时一次看到完整清单。此前快速失败的 `@mode` 检查也移入同一份聚合报告，消息文本不变。
生成器保留同一源码注释的两种视图：`parseJsDoc` 在第一个块标签处结束条目正文，而 `ts cordis-catalog` 签名块包含原始 JSDoc，并完整保留 `@param`、`@returns` 和 `@mode`。因此，读者可以看到完整的源码契约，而块标签文本不会泄漏到周围正文中。
`packages/core/agent/tests/gen-cordis-catalog.spec.ts` 中的负路径测试对合成 fixture（测试前置数据）运行 `collectEvents`/`collectServices`，验证每条守卫都会触发且免检规则成立。撰写规则写在根 [AGENTS.md](../../../../AGENTS.md) 的约定条目中，与 `@mode` 规则并列。
## 曾考虑的替代方案
- **ESLint 规则**：无法看到该范围的机器定义（哪些 `interface Events` 成员、哪些 `ctx.<key>` 类构成 Cordis 对外服务接口）；目录生成器在每次运行时恰好计算这层映射，因此门禁放在那里。
- **将每个方法展开为单独的正文小节**：否决。目录保留一个服务章节和一个签名块，以维持可扫读性；附着于每个声明的 JSDoc 则在原处保留完整的方法契约。
- **逃逸标签**：不设。该接口面小且经过策展（采纳时 12 个服务、57 个方法、27 个事件），要点在于检查不可豁免。
## 后果
- 新事件或服务方法不能带着未记录的参数或结果落地：生成器会拒绝重新生成，`verify-cordis-catalog` 也会使 `doc-sync` 和 CI 失败。采纳时发现的约 139 处缺口已在同一变更中补齐，因此门禁以绿色状态落地。
- 服务接口必须显式标注返回类型并使用标识符参数。两项约束在采纳时均未构成限制（所有方法已有标注；不存在解构的 seam 参数）；但二者现在是承重要求，违反时会被机械检测到。
- AGENTS.md 中通用的 JSDoc 规则（「一行能说清就用一行」）在此接口上获得了更严格的特例：仅当方法无参数且返回 void 时，一行摘要才足够。
- 为 `next` 或 `this` 写 `@param` 合法但不检查——这是有意的不对称：门禁强制载荷契约，拒绝要求样板代码。
- 每个生成的事件或方法片段都带有其原始 JSDoc，而正文摘要不含标签。因此，源码编辑会同时刷新可读索引和签名旁展示的确切契约。

6
.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-04-doc-tiers-and-budgets.md: 9993eda6b0c7f1f8e5908dbd85fcfb4e5c6b3d1d
2026-07-04-doc-tiers-and-budgets.zh.md: a40e7c2fe56ef86137bb7bb3ee8c818bdeed7eb9

2
.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-07-04-doc-tiers-and-budgets.zh.md)
## Problem
Standing docs accumulated repeated rules, retold incidents, duplicated package maps, and stale Agent Note summaries despite existing writing guidance. Because review alone did not prevent that growth, the repository needed a mechanical budget alongside its documentation taxonomy.

28
.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md Normal file
View File

@@ -0,0 +1,28 @@
# Agent Note: 文档分层、预算与上限门禁
Status: implemented
[English](2026-07-04-doc-tiers-and-budgets.md) | 中文
## 问题
尽管已有写作指导，常设文档仍不断累积重复规则、反复讲述的事件、重复的包（package）映射，以及陈旧的 Agent Note（agent 决策记录）摘要。仅靠评审无法阻止这种增长，因此仓库需要在文档分类之外再配一套机械预算。
## 决策
- **每项事实只归属一处的层级分类。**[docs/AGENTS.md](../../../../docs/AGENTS.md) 是文档标准：它为每种 Markdown 层级分配单一职责（常设指令、系统图、类型目录、决策记录、事件故事、操作指南、各包契约、生成式目录、工作流），禁止在事实归属层级之外重复陈述（应改为链接），并包含编写或评审任何文档时使用的赘余检查清单。
- **范围窄且严格的预算门禁。**[scripts/verify-doc-budgets.ts](../../../../scripts/verify-doc-budgets.ts) 接入 `doc-sync`：[scripts/doc-budgets.manifest.json](../../../../scripts/doc-budgets.manifest.json) 列出的每份文档都必须低于其字数上限（采用 `wc -w` 语义，统计整个文件）；预算内文件缺失也会使门禁失败，使重命名无法悄然遗落其预算。范围刻意只涵盖容易膨胀的常设文档——根目录和子树中的 `AGENTS.md` 文件、`architecture.md`、`packages/README.md`，以及它们将内容移入的常设策略文档（`docs/testing.md`、`docs/defensive-patterns.md`）。参考文档、Agent Note 和包 README 不设预算：只要每一行都是事实，长度在这些位置就是合理的；评审和赘余检查清单负责约束它们。
- **上限是只进不退的执行红线。** 上限设定为文档当前字数的至少 105%（留出工作余量，使日常措辞调整能通过，而真正的膨胀仍会触发门禁），并随着文档被精简到目标预算而同步下调、保持该余量（根 `AGENTS.md` ≤ 1,500 词；`architecture.md` ≤ 1,800；子树 `AGENTS.md` ≤ 600；`packages/README.md` ≤ 600）。推进机制与[翻译配对的 `required` 清单](2026-07-02-bilingual-docs-and-pairing-gate.md)相同。门禁变红时，修复方式是按分类体系迁移或压缩内容；只有在 PR（Pull Request）描述中给出明确理由时才允许提高上限，manifest（元数据清单）的 diff 本身即为可评审的动作。
- **精简的工作流 skill（技能），契约归文档。**[.agents/skills/dsh-doc-standards](../../../skills/dsh-doc-standards/SKILL.md) 承载放置/审计/红灯门禁工作流，并以文档标准为真源，与 [dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md) 和 i18n 契约之间的分工相同。
## 曾考虑的替代方案
- **仅靠 skill 和评审纪律，不设门禁**：否决。上述膨胀正是在现行规则和评审注意力已经存在的情况下发生的；一条没有机械后盾的行文规则在此处已被证明无法维持，而本仓库自身的[质量门禁立场](2026-06-11-quality-gates.md)认为值得保持的不变式就值得编码。
- **对所有文档层级全面设限**：否决。一刀切的上限恰好惩罚了那些正当的长文档（如特性矩阵或类型目录，每一行都是事实，例如 `packages/ui/acp/acp-feature-support.md`），并产生逐文件的例外变更，训练贡献者机械地批准提限。
- **将标准放在 skill 内部**：否决。契约归文档，工作流归 skill；如果标准被塞进 SKILL.md，那些不调用该 skill 而直接编辑文档的 agent（智能体）就看不到它，而 `docs/AGENTS.md` 已经作为子树指令被任何在 `docs/` 下工作的人加载。
## 后果
- 向受预算约束的文档添加内容现在需要置换：将新增内容迁移到其分类体系归属地并留下指针，或压缩现有行文来腾出空间。只增不减会导致 CI 失败。
- 精简到目标预算的重写以堆叠的后续 PR 落地，每次合并时同步下调 manifest 中的上限；在各自落地之前，文档冻结的上限仅阻止进一步膨胀。
- 字数是一个粗糙的代理指标，这是有意接受的：它无法判断质量，但它在内容被添加的那一刻强制触发迁移决策，而那正是作者拥有足够上下文来正确放置内容的时刻。

6
.agents/notes/implemented/process/2026-07-04-persistence-log-catalog.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-04-persistence-log-catalog.md: 1529f41b485c1bc8ca029c0a9264574fa7a886a0
2026-07-04-persistence-log-catalog.zh.md: f3f77bb66f8798d953fed16bc79cadadc35c036a

2
.agents/notes/implemented/process/2026-07-04-persistence-log-catalog.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-07-04-persistence-log-catalog.zh.md)
## Problem
`SessionEventMap` is the on-disk vocabulary, but its declarations are split across the owning session package and declaration merges. The generated persistence catalog is the single reference for every event, its complete payload declaration and source JSDoc, and the shared `SessionEvent` envelope; hand-maintained tables drift and are removed. These records are not Cordis events—observers receive them through the single `session/event` bus event—so the Cordis catalog cannot cover them. The generator discovers all declarations and the doc-sync freshness gate rejects omissions or stale output.

36
.agents/notes/implemented/process/2026-07-04-persistence-log-catalog.zh.md Normal file
View File

@@ -0,0 +1,36 @@
# Agent Note: 生成式持久化日志事件目录
Status: implemented
[English](2026-07-04-persistence-log-catalog.md) | 中文
## 问题
`SessionEventMap` 是磁盘格式的词汇，但其声明分散在所属的会话包（package）和声明合并中。生成式持久化目录是所有事件、各自完整 payload 声明与源码 JSDoc，以及共享 `SessionEvent` 信封的唯一参考；手工维护的表格会发生漂移，因此被移除。这些记录不是 Cordis 事件——观察者通过唯一的 `session/event` 总线事件接收它们——所以 Cordis 目录无法覆盖。生成器会发现所有声明，文档同步新鲜度门禁会拒绝遗漏或陈旧输出。
## 决策
从源码生成 `docs/persistence-catalog.md`，配合新鲜度门禁，作为第四个参考面：持久化会话日志可以包含的*记录*，与 Cordis 目录（接线）、核心数据结构（词汇）和工具目录（工具）互补。
`gen-persistence-catalog.ts` 使用 TypeScript AST 扫描每个所属及声明合并的 `SessionEventMap`。它从前置 JSDoc 开始渲染每个成员，直至完整的 payload 类型，保留嵌套属性注释且只移除其容器缩进；同时粘贴构成持久化信封的所属 `SessionEventType`、`SurfaceEventType`、`SurfaceOp` 和 `SessionEvent` 声明。派生的 surface 徽章、参考链接和源码位置仍位于声明块之外。文档同步新鲜度检查会拒绝目录尚未重新生成的词汇或信封变更。
具体选择：
- **强制保证 JSDoc 完整性。** 每个成员和渲染出的信封类型都必须带有描述正文，完整的源码 JSDoc 会在目录中保持附着于其声明。`@mode` 标签是硬错误：分派模式属于 Cordis 总线事件，持久化记录没有这种模式。所有违规会汇总为一条错误，列出每个违规项。
- **surface 徽章由派生得出，而非手工列举。** `SurfaceEventType`（产生 LLM（大语言模型）消息且可能携带 `surfaceOp` 的子集）从拥有方包中的 union 声明解析；如果 union 成员命名了一个未声明的事件，则为硬错误（否则陈旧的 union 成员会静默地不标注任何内容）。其余一律渲染为 **log-only**。
- **专用围栏。** 声明块使用 ` ```ts persistence-catalog ` 信息字符串，`doc-typecheck` 会识别并跳过这些块，将其排除在 opt-out 比例之外——处理方式与 `ts cordis-catalog` 相同（这些声明引用所属模块中的类型，无法独立编译）。
- **仓库范围。** 目录枚举本仓库中的包，与兄弟文档的 packages-only 范围一致；下游插件可以合并更多事件类型，它们在设计上不在目录范围内。遍历过程用硬错误保护自身假设：拥有方的顶层 `interface SessionEventMap` 必须是 `@deepseek-ai/dsh-session` 中唯一的导出声明（无关的、局部的或同名重复的接口不能被当作磁盘词汇编入目录）；任何声明不得携带 `extends`（继承的键会加入 `keyof SessionEventMap` 却没有对应的目录行）；每个成员必须是带有显式 payload 类型的属性签名（方法形式的成员会加入 `keyof` 却在静默遍历中被漏过）；跨声明的重复成员也会失败。
本方案取代了手工副本：session.md 的 `hook/*` 表格、精简版 README 的事件表格、hook-protocol README 的 payload 条目列表，以及会话 README 的名称列表现在链接到目录，而不再重述 payload（周围的语义说明文字保留原位）。hook-protocol 合并成员上的两个误加的 `@mode emit` 标签已被移除——新门禁将它们作为类别错误拒绝。
## 曾考虑的替代方案
- **基于启动的生成器（类似工具目录）**：日志词汇完全是静态的，AST 遍历无需启动任何东西即可读取全部真相。
- **保留手工副本**：手工副本只能检查作者已经写下的名称；目录落地时，会话 README 的合并说明已经漂移。
## 后果
- 目录不会发生漂移：提交文件未反映的词汇或信封变化会使 `doc-sync` 和 CI 中的 `verify-persistence-catalog` 失败，而没有 JSDoc 的新增合并事件会直接使生成器失败——插件不能再添加未记录的磁盘记录类型。
- 事件正文只有一个归属，即声明处的 JSDoc；目录会保留该 JSDoc 和所有嵌套字段注释，不会将其扁平化或复述。
- `SurfaceEventType` union 现在对文档具有结构性承载作用：重命名事件而不更新 union（或反过来）会导致生成器失败，而不仅仅是编译器失败。
- 徽章派生假设 union 始终是一组封闭的字符串字面量且只有一个拥有方；如果重构偏离了这一形状，必须在同一个变更中更新生成器。

6
.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-05-uniform-agent-note-format.md: 06082251c1b96c90ed470d84224662e00e29791b
2026-07-05-uniform-agent-note-format.zh.md: df6b0f4dfacf122f452807491680091827f69c25

2
.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-07-05-uniform-agent-note-format.zh.md)
## Problem
Agent Note paths encoded lifecycle and class, but file contents still mixed headings, status formats, ADR and proposal templates, and proposal-era sections in implemented records. Authors copied whichever neighbor they found, and lifecycle moves could skip the required rewrite because no gate enforced an in-file contract.

30
.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md Normal file
View File

@@ -0,0 +1,30 @@
# Agent Note: Agent Note 的统一受门禁约束的文件内格式
Status: implemented
[English](2026-07-05-uniform-agent-note-format.md) | 中文
## 问题
Agent Note（agent 决策记录）的路径编码了生命周期和类别，但文件内容仍混杂着不同标题、状态格式、ADR 与提案模板，以及已实现记录中的提案阶段章节。作者会复制随手找到的相邻文件，而生命周期迁移可能跳过必要的改写，因为没有门禁强制执行文件内契约。
## 决策
[README.md § 文件格式](../../README.md#the-file-format)是文件内契约——头部块（`# Agent Note: <title>`，加上无日期且与文件夹一致的 `Status:` 枚举，其中只有拒绝原因可作为额外内容）、各生命周期的正文骨架（所有文件均以 `Problem` 开篇；`proposed/` 使用 `Proposal`/`Acceptance criteria`/`Risks`；`implemented/` 使用现在时的 `Decision`/`Consequences`，并禁止提案阶段标题；`rejected/` 冻结提案形状）、强制的 `Alternatives considered` 章节，以及规范章节词汇；定制技术章节可在这些规范章节之间保持自由形式。`pnpm run verify-agent-note-format`（[scripts/verify-agent-note-format.ts](../../../../scripts/verify-agent-note-format.ts)）作为 `doc-sync` 的一部分强制执行每项机械规则，因此跳过改写的生命周期迁移现在会使 CI 失败，而不再依赖评审者记忆。
定义该格式的同一变更规范化了整个语料库——遵循预发布立场：不设过渡期，不容忍双格式。唯一受既有条款豁免的是内容，而非格式：替代方案只能记录、不能杜撰，因此若某份格式制定前的 Agent Note 无法从记录中还原替代方案，就会携带确切的 `agent-note-format: alternatives-not-recorded` 注释；门禁只对日期早于本文的文件接受该注释。
## 曾考虑的替代方案
- **完整的刚性模板**（每个生命周期使用固定章节顺序，重构每份 Agent Note 以适配）：否决。大型设计 Agent Note 包含八到十五个定制技术章节（包（package）拓扑、线协议、schema），它们是承载设计的内容，而非漂移；刚性顺序会迫使我们现在进行破坏性改写，并永远与模板较劲。
- **仅规范化头部**（H1 和 Status，正文不动）：否决。债务标记指出的是*正文*的体裁分裂，让 `Context`/`Decision` 与 `Problem`/`Proposal` 无限期并存什么也解决不了。
- **不设 Status 行**（文件夹已经表示状态；格式制定前最新的三份 Agent Note 及其中一份的中文对应文件省略了该行）：否决，保留文件的自描述性。通过门禁校验该行与文件夹一致，消除了原本促使我们删除它的漂移风险。
- **带日期的 Status**（`Status: implemented (accepted YYYY-MM-DD)`）：否决。接受日期属于叙述性历史，写作规则将其排除在文档之外；文件名承载首次提出日期，git 承载其余信息；门禁能检查日期格式，但永远无法检查其真实性。
- **裸 `# <title>` H1**：否决。文件脱离目录树单独阅读时，`Agent Note: ` 前缀能自描述其体裁，而格式门禁可防止它漂移。
- **以 `## What we give up` 作为已实现记录的结尾**（README 对 Agent Note 所记录内容的原有表述）：否决。它只点出成本，而诚实的后果章节也会记录取舍换来了什么。
- **只有约定没有门禁**（写下契约，靠评审强制执行）：否决。slop checklist 已经通过约定禁止在 `implemented/` 中使用 spec 语气，而十九个文件展示了仅靠约定在此处能达到什么效果。
- **独立的 `FORMAT.md` 契约文件**：否决。由一个入口同时承载布局、分类和格式，比维护两个契约文件更易发现和维护。
## 后果
现在每份 Agent Note 都需要稍多一些结构，而强制的 `Alternatives considered` 章节是有意设置的阻力：记录决策却不记录它胜过什么，会招致 Agent Note 本应防止的重新争论。无法还原替代方案的格式制定前 Agent Note 会永久保留既有条款注释——这是记录中诚实的缺口，而不是杜撰的理由。`doc-sync` 增加一道门禁；在生命周期文件夹之间移动 Agent Note 时，现在必须当场完成真正的工作（迁移本就应包含的正文改写），而不是推迟为无人跟踪的清理任务。三十九个债务标记已经消失，由它们一直等待的模板解决。

6
.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-06-export-surface-jsdoc-gate.md: 93d8a41fc2ffb235de5c56ffeb5569bc95249392
2026-07-06-export-surface-jsdoc-gate.zh.md: 64b4bcc620046f2c94a2ce3fbeb67e59ada888d4

2
.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-07-06-export-surface-jsdoc-gate.zh.md)
## Problem
The [cordis JSDoc completeness gate](2026-07-04-cordis-jsdoc-completeness-gate.md) made undocumented parameters and results impossible on the cordis surface — `interface Events` members and `ctx.<key>` service classes — but that surface is a fraction of what a plugin author imports. The AGENTS.md rule "every export (and non-obvious method) has a JSDoc explaining semantics" stayed prose-checkable only by review everywhere else, and nothing at all asked for `@param`/`@returns` on ordinary exported functions. A survey at adoption found 203 under-documented module-level exports across 34 packages: seam-adjacent helpers (`runBash`, `readForEdit`, `htmlToMarkdown`), format codecs, whole undocumented interfaces and type aliases — exactly the names an IDE consumer hovers.

45
.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.zh.md Normal file
View File

@@ -0,0 +1,45 @@
# Agent Note: 导出表面 JSDoc 门禁
Status: implemented
[English](2026-07-06-export-surface-jsdoc-gate.md) | 中文
## 问题
[Cordis JSDoc 完整性门禁](2026-07-04-cordis-jsdoc-completeness-gate.md)使得 Cordis 表面上的参数和返回值不可能缺少文档——`interface Events` 成员和 `ctx.<key>` 服务类——但这只是插件作者所导入内容的一小部分。AGENTS.md 中的规则「每个导出（以及非显而易见的方法）都必须有解释语义的 JSDoc」在其他地方只能靠评审以行文方式检查，而且没有任何机制要求普通导出函数带 `@param`/`@returns`。采纳时的一次调查发现 34 个包（package）中有 203 个文档不完整的模块级导出：seam 相关辅助函数（`runBash`、`readForEdit`、`htmlToMarkdown`）、格式编解码器、完全无文档的接口和类型别名——恰恰是 IDE 消费方悬停查看的那些名称。
## 决策
新增门禁 `scripts/verify-export-jsdoc.ts`（`pnpm run verify-export-jsdoc`，接入 `doc-sync`（文档同步门禁），与 `verify-cordis-catalog` 并列），遍历每个 `packages/<group>/<pkg>/src/` 目录树下的所有模块级导出名称。解析与检查辅助函数从 `gen-cordis-catalog.ts` 移入共享的 `scripts/jsdoc.ts`，使得「已文档化」在两个表面上含义一致：描述性文字在第一个块标签处截止、每个可检查参数需要非空 `@param`、非 void 且有显式标注的返回值需要非空 `@returns`、过时的 `@param` 报错，违规项汇总为一份报告。
按声明类型划分的契约：
- 每个导出名称都需要带有非空描述文字的 JSDoc。
- 函数类导出（函数声明；初始化器为函数或带有内联可调用标注的 const；非标识符的函数默认导出）遵循完整的函数契约，分类前会剥离包装表达式（括号、`as`/`satisfies` 类型断言、非空断言）。如果 const 声明器标注了一个具名类型（`export const f: Handler = …`），签名契约推迟到该类型自身的声明处，`@returns` 保持可选；内联的 `(x: T) => U` 标注或单调用签名字面量本身就是表面签名，适用完整契约；而混合了调用/构造签名与其他成员的字面量则直接拒绝（没有单一签名可供标签对照——请提取具名类型）。
- 导出类需要类级别的描述文字；公开方法（包括静态方法——可通过导出名称访问）遵循函数契约；公开属性和访问器需要描述文字（get/set 对由 getter 覆盖）。重载实现体免检——签名承载文档。
- 导出接口、类型别名和枚举需要声明级别的描述文字；成员级别的强制有意推迟（承载关键成员契约的 seam 服务类已在 Cordis 门禁之下）。
- 导出命名空间递归检查（在 ambient `declare` 命名空间内，每个成员隐式导出）；命名空间本身仅在不与同名的已文档化声明合并时才需要描述文字（Config-namespace 惯用法只需文档化插件一次）。
- `declare module`/`declare global` 体和 `export … from` 重导出语句被跳过：augmentation 不是包的导出，重导出的定义在其定义处检查。`export import X = N.member` 别名需要文档化自身——其目标可能是遍历不会访问的非导出命名空间成员——且门禁仅支持纯描述文字的目标类型：可调用、类或命名空间目标携带别名描述文字无法承载的签名/成员契约，门禁会拒绝并要求直接导出该声明。
- 其余情况按封闭原则失败：`export =` 直接拒绝；基类从未命名的参数即使作为绑定模式仍需 `@param`；dispatch 不识别的导出语句类型本身就是违规——没有任何导出形式能因遗漏而免检。
三类豁免避免门禁要求样板代码，精神与 Cordis 门禁的 `this`/`next` 豁免一致（为已豁免的名称编写文档是允许的；只有缺失才不被检查）：
- **继承成员。** 重写从其基类声明继承文档。新增的公开表面仍需文档：新增参数、将 protected 成员公开重写、或在 void 基类之上返回具体类型。继承查找和推断返回值分类是门禁唯一需要类型检查器的工作；其他检查使用 AST。
- **插件协议槽位。** 顶层的 `name`/`inject`/`reusable`/`Config` 常量和 `apply` 入口，以及插件类上的同名静态成员，属于框架协议：其形状由 Cordis 固定，模块文档注释加 `interface Config` 承载插件的真实语义。
- **构造函数**，与 Cordis 门禁一致：插件类由框架构造，类文档承载全部说明。
`collectExportJsdocViolations()` 返回违规列表（CLI（命令行界面）在非空时以 1 退出），因此 `packages/core/agent/tests/verify-export-jsdoc.spec.ts` 中的负路径测试直接断言发现项，通过 fixture（测试前置数据）包驱动每一种拒绝和每一种豁免。
## 曾考虑的替代方案
- **eslint-plugin-jsdoc**（`require-jsdoc`/`require-param`/`require-returns`）：覆盖了机械核心，但无法表达本仓库的契约。继承成员豁免需要跨包的类型解析，协议槽位和命名空间合并惯用法是 Cordis 特有的，而完整性语义（标签前描述文字、过时标签报错、汇总报告）已在 `scripts/jsdoc.ts` 中与 catalog 生成器共享。两套微妙不同的「已文档化」定义，正是本仓库「单一归属」规则所要防止的失败模式。
- **扩展 `gen-cordis-catalog.ts`**：catalog 生成器渲染一个精选表面并守卫其新鲜度；仓库级遍历没有 catalog 可渲染。共享辅助函数、保持遍历独立，使每个门禁的职责清晰可读。
- **强制接口/类型别名的成员文档**：推迟。这会使检查表面成倍增长，而这些成员大多是自描述的字段；承载关键成员契约的 seam 服务类已有门禁。如果评审中出现成员文档漂移再重新考虑。
## 后果
- 新导出不能在缺少文档的情况下落地：`verify-export-jsdoc` 会使 `doc-sync` 和 CI 失败。采纳时发现的 203 处缺口已在同一变更中补齐，因此门禁以绿色状态落地。
- 导出函数必须标注返回类型（采纳时已全面满足，现在成为门禁依赖），并在 `@param` 需要命名参数时使用标识符参数。
- seam 文档是权威的：实现从其继承链继承文档，值得保留在实现上的行为说明是补充，而非必需。
- 门禁构建一个 `ts.Program`（约 6 秒）——唯一需要类型解析的文档门禁；在已编译文档片段的 `doc-sync` 内可以接受。
- 协议槽位名称按约定保留在模块顶层；一个恰好命名为 `apply` 或 `Config` 的非协议导出将不被检查——已接受，记录于此。

6
.agents/notes/implemented/process/2026-07-06-generated-config-catalog.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-06-generated-config-catalog.md: f39f5138526d3278e839ee0053d5051bb8bc1c36
2026-07-06-generated-config-catalog.zh.md: 825046914dad8e1a7d87340a310b252f03cbecb9

2
.agents/notes/implemented/process/2026-07-06-generated-config-catalog.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-07-06-generated-config-catalog.zh.md)
## Problem
The repository had no source-backed reference for plugin configuration. Package READMEs documented fields inconsistently, did not enumerate which packages are loadable, and did not verify that runtime schemas agree with declared config types.

40
.agents/notes/implemented/process/2026-07-06-generated-config-catalog.zh.md Normal file
View File

@@ -0,0 +1,40 @@
# Agent Note: 生成式插件配置目录
Status: implemented
[English](2026-07-06-generated-config-catalog.md) | 中文
## 问题
仓库此前没有以源码为后盾的插件配置参考。各包（package）的 README 对字段的记录方式不一致，未列举哪些包可被加载，也未校验运行时 schema 与声明的配置类型是否一致。
## 决策
`scripts/gen-config-catalog.ts` 根据各插件声明的 config 类型和 JSDoc 生成 [docs/config-catalog.md](../../../../docs/config-catalog.md)，并包含注入要求、被引用类型的链接和源码位置。包内类型会以传递方式纳入；workspace 类型和外部类型则会链接或点名。确定性的 `--write` 和 `--check` 模式使提交页面成为生成产物。
此处采用纯 AST 生成是正确的，原因与事件/服务目录相同，而与工具目录不同：配置类型是静态声明，仓库中每个 schemastery schema 都是静态的 `z.object`/`z.intersect` 字面量，因此源码即全部真相——配置表面没有任何部分是运行时组合的。
具体选择：
- **配置类型是第二参数的类型。** catalog 记录的是 `apply(ctx, config)` / 服务构造函数 `(ctx, config)` 的声明参数类型——即 Cordis 实际传入的值——而非按命名约定定位的 `Config` 导出。这使得遍历是全量的：无论接口叫 `AcpConfig` 还是 `BasicCompactConfig`，无论类型声明在兄弟文件中，还是插件完全没有验证 schema，都能正常工作。
- **分类是全量的。** 每个 `packages/<group>/<pkg>` 条目都会被解析（镜像 Loader 的 `unwrapExports`：`exports.default ?? exports`），归入可配置插件、无配置插件、抽象 seam 类或库之一——各自渲染在独立小节中——无法归类的条目直接报错。新包不可能被悄悄遗漏。
- **逐字段 JSDoc 强制要求。** 粘贴的声明中每个属性（包括嵌套的类型字面量）都需要非空的 JSDoc 描述，否则生成失败。粘贴本身就是文档，因此这与 events catalog 通过 `@mode` 施加的强制函数相同：源码文档过于单薄时门禁报错，而非产出单薄的 catalog。
- **Schema 键与声明类型做比对。** 生成器通过局部和 workspace 类型解析嵌套的对象与数组路径。确定缺失的路径报错；无法枚举的外部或动态形状则跳过。比对有意设计为单向的，因为声明类型可能包含被排除在 loader 配置之外的运行时专用字段。
- **专用围栏。** 粘贴的声明使用 ` ```ts config-catalog ` 信息字符串，`doc-typecheck` 会跳过它（引用了导入类型的孤立声明无法独立编译），并将其排除在 opt-out 比例之外——与 `cordis-catalog` 和 `persistence-catalog` 围栏的处理方式相同。
- **单文件 `docs/config-catalog.md`**，而非一个单文件目录：该页面面向单一受众（`cordis.yml` 的编写者），只有一个维度，不同于 `cordis-catalog/`（其中包含两个并列页面）。
各包 README 中的 `## Config` 小节保留。重叠是有意接受的：README 是经过策划的逐包契约（在部署上下文中描述配置语义，连同限制与扩展点），catalog 则是穷举式的生成枚举。由于 catalog 是生成的，二者不一致时说明 README 有误，修复方式是编辑 README——catalog 不会漂移。
## 曾考虑的替代方案
- **合成式逐字段渲染**：为每个字段生成项目符号列表、表格或带注释的 YAML 片段，从解析的 JSDoc 加 schema 元数据组装。否决，改用逐字粘贴：接口连同其 JSDoc 本身就是以原始形式撰写的契约，合成渲染器会重新格式化它不拥有的行文，增加一个可能歪曲原意的渲染层。
- **运行时启动 + schema 内省（如工具目录所做的那样）**：否决。此处没有任何内容是运行时组合的，且 schema 本身对配置表面的文档化不足（以行文记录的默认值、运行时专用字段、完全没有 schema 的插件）。启动只会增加脆弱性而不增加真相。
- **双向 schema/接口等价检查**：否决，改用子集检查。声明类型合理地包含 schema 拒绝从配置接受的成员（运行时专用 seam）。
- **在同一变更中废除 README `## Config` 小节**：否决。保留可接受的重叠使逐包契约在原处可读，而清理工作需要先把每个 README 的额外事实折入字段 JSDoc——这是可分离的工作，catalog 不依赖它。
## 后果
- 目录不会发生漂移：提交文件未反映的源码变化会使 `doc-sync` 和 CI 中的 `verify-config-catalog` 失败。config 字段未记录、被引用类型名无法解析，或 schema 键未出现在 config 类型中，都会直接使生成器失败。
- 配置行文现在有了声明处的强制函数：编写新配置字段意味着编写其 JSDoc，而该 JSDoc 将逐字成为 catalog 条目。
- 生成器对无法静态遍历的形状直接报错——别名化的包内配置导入、非 `object`/`intersect` 组合构建的 schema、未列入的全局类型名。引入此类形状时必须同时教会生成器（否则该形状不能进入仓库），这正是设计意图：catalog 始终是全部真相。
- `gen-cordis-catalog.ts` 导出其 JSDoc/指针辅助函数与 `LINK_MAP` 供复用，因此两个 catalog 以相同方式交叉链接类型，新增一条 link-map 条目同时服务于两者。

6
.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-06-node-engine-floor.md: f1754ea7ca32452a04c6cd8a0599568f602e47dd
2026-07-06-node-engine-floor.zh.md: 9d376a639378d3a0b9b645aa36c1a5d320d1d147

2
.agents/notes/implemented/process/2026-07-06-node-engine-floor.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-07-06-node-engine-floor.zh.md)
## Problem
The Node 22 branch of the root `engines.node` range is a contract for the installed workspace, not only for the runtime APIs the harness source calls directly. It must be no lower than package `engines.node` declarations for dependencies the workspace installs on that branch; otherwise `pnpm install --engine-strict` fails at an advertised LTS version, and non-strict installs run outside a dependency's supported runtime.

39
.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md Normal file
View File

@@ -0,0 +1,39 @@
# Agent Note: 将 Node LTS 引擎下限提升至 22.19
Status: implemented
[English](2026-07-06-node-engine-floor.md) | 中文
## 问题
根 `engines.node` 范围中的 Node 22 分支是对已安装工作区的契约，而不仅仅是 harness 源码直接调用的运行时 API 的契约。它不得低于工作区在该分支上安装的依赖包（package）所声明的 `engines.node`；否则 `pnpm install --engine-strict` 会在一个已宣传的 LTS 版本上失败，而非严格模式的安装则会在依赖所支持的运行时范围之外运行。
## 决策
将 `engines.node` 设为 `^22.19.0 || >=24.0.0`，并在 keyless CI 兼容性矩阵中测试 `['22.19', 24, 26]`。每条矩阵分支都运行 TypeScript 类型检查加一次 keyless 的源码模式 worker 冒烟测试，因此引擎下限通过完整的源码类型检查和真实的未构建运行时路径两条路径得到验证。真实 API 的 e2e 工作流保持在 Node 24 上，因为它验证的是 API 集成而非运行时下限。
两个 Node 特性决定了源码运行时的门槛：
- **`node:sqlite`**：`packages/session-persistence/session-persistence-sqlite` 在顶层执行 `import { DatabaseSync } from 'node:sqlite'`。该模块在 **22.13**（LTS）和 **23.4**（Current）取消了 `--experimental-sqlite` 标志要求；在此之前，导入它会在加载时抛出异常。
- **原生 TypeScript 类型剥离**——构建模式的 `examples/headless-agent/tests/keyless-smoke.e2e.ts` 冒烟测试使用纯 `node`（无 tsx）启动 `dsh-cli-demo` 已发布的 `lib/bin.js`，并加载示例的 `.ts` 测试适配器（`cli-mock-llm.ts`）。类型剥离从 **22.18**（LTS）和 **23.6**（Current）起成为默认行为；更早版本需要 `--experimental-strip-types`。
这些源码特性在 22.x 线上于 **22.18** 全部就绪，但已安装的 Pi 适配器依赖将宣传的 LTS 下限进一步提高。`@deepseek-ai/dsh-llm-pi-ai` 依赖 `@earendil-works/pi-ai@0.79.3`，后者的包声明 `engines.node >=22.19.0`，因此 LTS 下限为 **22.19**。24.x 分支保持 `>=24.0.0`。该不相交范围完全排除了 Node 23：Node 23.0–23.5 至少还有一个源码特性需要标志，而 23 线是非 LTS/已 EOL 的，宣传 `>=23.6` 会增加一条已终止的发布线和一条 CI 分支，而没有任何部署应当使用它。
`@types/node` 继续固定在 22.x 线（`^22.20.0`），以匹配 LTS 支持线：使用 Node 23+/24+/25+ 的 API 会在所有机器和类型检查门禁中导致 `tsc` 失败，而不是编译通过、直到仅下限矩阵分支才能捕获的运行时错误才暴露。目前整个代码树在 Node 22 类型表面上类型检查全部通过，因此这一固定没有任何代价。
## 后果
- 宣传的 LTS 分支不再低于 Pi 适配器依赖的下限。
- CI 通过 Node 22.19 直接验证 Node 22 LTS 下限，Node 24 分支保持 `node: 24`，Node 26 用于下一个偶数线；每条分支都对源码图执行类型检查，并实际启动未构建的工作流 worker。
- built-bin 冒烟测试无需版本条件标志：在 22.19 上类型剥离已是默认行为，因此测试保持其文档所述的纯 `node lib/bin.js` 路径。
- 未来若依赖或源码 API 提高运行时下限，必须在同一变更中同步调整 `engines.node`、兼容性矩阵和本 Agent Note（agent 决策记录）。
## 曾考虑的替代方案
- **保持 `^22.18.0 || >=24.0.0`。** 否决：它宣传的 LTS 版本低于 Pi 适配器依赖的下限。`@earendil-works/pi-ai@0.79.3` 要求 `>=22.19.0`。
- **降级或固定 `@earendil-works/pi-ai` 以保留 22.18 的宣传范围。** 否决：当前 Pi 适配器依赖是预期工作区的一部分，且 22.19 仍在 Node 22 LTS 线内。
- **下限 `>=22.13`（`node:sqlite` 边界）加上在 22.13–22.17 的 built-bin 冒烟测试中使用 `--experimental-strip-types`。** 否决：它为一个狭窄范围增加了版本条件测试标志，并将实验性标志依赖包装为正式支持。Pi 适配器依赖已经要求更高的 LTS 下限。
- **开放式 `>=22.19`。** 否决：它宣传支持 Node 23.0–23.5，而在这些版本上 `node:sqlite`（直到 23.4）或类型剥离（直到 23.6）仍需标志。
- **包含 Node 23.6+（`^22.19.0 || >=23.6.0`）。** 否决：23.6+ 确实能无标志运行两个源码特性，但 Node 23 已 end-of-life；宣传一条已终止的发布线会增加一个范围项和一条 CI 分支，而没有任何部署应当使用该运行时。
- **矩阵 `[22, 24, 26]` 而非固定 `22.19`。** 否决：浮动的主版本号条目会随时间上漂，悄然不再验证所声明的 LTS 下限。
- **保持 `@types/node` 超前于运行时下限（`^25`）。** 否决：类型定义超前于运行时下限会让仅 Node 24/25 才有的 API 编译通过，仅在 22.x 上运行时才失败。将 `@types/node` 固定在 22.x 线上可将此类问题转化为所有环境下的编译错误。

6
.agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-06-parallel-github-ci-gates.md: 5c276f6a75936021369bc5ad9494c9aa6e4e3fc3
2026-07-06-parallel-github-ci-gates.zh.md: 7d98f842ef1d60a3a5b727f975cb1d93ea6f253c

2
.agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-07-06-parallel-github-ci-gates.zh.md)
## Problem
The keyless GitHub CI gates are mostly orthogonal: typecheck, lint, documentation freshness, coverage, snapshot replay, build, package-publication hygiene, demo smoke, and built-bin smoke fail for different reasons and do not need each other's runtime state. Running them as one ordered command chain makes the workflow wall clock equal the sum of those gates, while splitting every short leaf into its own GitHub job repeats checkout, Node setup, pnpm restore, and install work until orchestration overhead becomes the bottleneck.

50
.agents/notes/implemented/process/2026-07-06-parallel-github-ci-gates.zh.md Normal file
View File

@@ -0,0 +1,50 @@
# Agent Note: 并行 GitHub CI 门禁
Status: implemented
[English](2026-07-06-parallel-github-ci-gates.md) | 中文
## 问题
无密钥 GitHub CI 门禁大多相互正交：类型检查、lint、文档新鲜度、覆盖率、快照重放、构建、包（package）的发布卫生检查、demo 冒烟和已构建二进制冒烟会因不同原因失败，也不需要彼此的运行时状态。将它们作为一条有序命令链运行，会使工作流墙钟时间等于所有门禁耗时之和；而把每个短小叶子拆成独立 GitHub job，又会反复执行 checkout、Node 设置、pnpm 恢复和安装，直到编排开销成为瓶颈。
随着 workspace 增长，原有的宽车道拆分不再满足这一平衡。PR（Pull Request）#404 合并时，Linux 的静态、覆盖率、快照和产物 job 分别耗时 148、195、94 和 230 秒；Windows 的静态和产物 job 分别耗时 251 和 482 秒。每个包都调用一次包管理器打包，主导了两个产物验证器的耗时；覆盖率在仅运行源码的套件前无谓地重建输出；CPU 密集型门禁则在静态与覆盖率车道内争用资源。
产物边界仍然承载关键约束。`publint`、`verify-node-next-types`、已编译不变量加载和已构建二进制冒烟测试都需要生成的 `lib/` 输出。分片不能让这些消费方抢在构建前运行，也不能用源码执行取代它们对已发布产物的信号。
## 决策
下述生产拓扑已经成为历史，并由[基于证据采用更大的托管 runner](2026-07-22-evidence-based-larger-hosted-runners.md) 取代。更大 runner 的决策移除了其分片选择器和工作流 job；本文保留早期拓扑为何被实现的记录。
[CI](../../../../.github/workflows/ci.yml) 将非 Windows job 的一分钟和 Windows job 的三分钟视为观测所得的性能目标，而非取消截止时间。托管 runner 的波动应留下完整计时证据和有用的失败日志，而不是取消本来正确的门禁。[串行跨平台 CI 参考](2026-07-21-serial-cross-platform-ci-reference.md)会在 Linux、macOS 和 Windows 上独立运行完整、未分片的主 Node 聚合，使优化后的车道清单不会成为自身完整性的唯一判据。
在该拓扑中，[scripts/run-gates.ts](../../../../scripts/run-gates.ts) 是通用的有界调度器，GitHub 则为昂贵的门禁族提供显式分片名称。`scripts/static-shards.ts` 将静态门禁划分为基础、文档类型、API 契约、目录、正文、文档投影和文档构建等归属，并拒绝缺失或重复的门禁分配。Linux lint 使用互不重叠的 A-C、D-M、N-S、T-Z 包源码和包测试车道，Windows 则使用完整的包源码与包测试车道；两者都包含从 `.` 开始的仓库补集，使新增顶层目标无法消失在分片之间，并负责唯一一次跨文件重复检查。`scripts/coverage-shards.ts` 把每个 workspace 包恰好分配给一个源码覆盖率车道。目录过滤器保留尾部分隔符，因为 Vitest 位置过滤器按子字符串匹配，否则会纳入具有同名前缀的相邻项。每个覆盖率车道只包含其拥有的源码文件，重复运行穷尽式伴随拓扑测试，并且不先执行构建，因为从删除了所有生成式 `lib/` 的树开始，完整覆盖率套件仍可通过。
快照重放使用两个显式多文件车道，以及大型 ACP（Agent Client Protocol）文件的八个场景分区。`scripts/snapshot-shards.ts` 拥有该清单，其测试会发现快照配置允许的每个文件。每个快照 job 在其 Linux runner 准备 Bubblewrap 的同时安装依赖，随后构建已发布运行时，并且只运行分配给它的重放表面。该套件保留五个子进程的有界并发，因为重放的大部分时间都在等待子进程协议 I/O。fixture（测试前置数据）守卫仍会在每个分区中检查完整 ACP 场景表。
冷启动的独立文档类型检查会重建完整的项目引用图，因此专用文档类型车道只构建一次，再用这些声明检查 Markdown 块。Linux 文档车道使用 VitePress 的 MPA 构建，在观测所得的非 Windows 目标内保留页面渲染与死链接验证；单独的阻塞式 Windows 构建和生产站点车道保留已生成包与已发布站点检查，同时避免把两条关键路径放进同一个 job。
产物使用两个车道：一个元数据车道负责 `publint`、NodeNext 声明和已编译不变量加载，另一个负责已构建二进制冒烟。每个车道都会在其消费方之前自行构建。重复短时构建会消耗 runner 分钟数，但避免了上传/下载依赖，并使每个 job 的关键路径保持有界。
[scripts/publint-all.ts](../../../../scripts/publint-all.ts) 在进程内针对内存发布视图调用 publint 支持的 API；该视图由每份清单声明的文件和 npm 强制元数据文件构成。这样无需生成 103 次包管理器打包命令，也能保留 workspace 文件与已发布文件之间的区别。[scripts/verify-built-package-invariants.mjs](../../../../scripts/verify-built-package-invariants.mjs) 在真实包下暂存这些经过结构验证、由清单声明的 `lib/` 文件，再通过纯 Node 和 Cordis Loader 规范化导入已编译的自引用。若伴随项触及未声明的运行时分片，仍会失败。
兼容性车道会在每条声明支持的 Node 版本线上运行源码 worker 和 Zstandard 运行时冒烟。TypeScript 在专用的主 Node 24 车道中只检查一次源码图；在运行时兼容性 job 中重复同一编译器分析只会增加耗时，不会提供运行时特有信号。
工作流缓存 pnpm store，将每个不可变 ESLint 缓存的键绑定到其所属 lint 分片，为 Windows 测量保留原生 PowerShell，并保留一个聚合的 `all checks passed` 状态用于分支保护。Windows 复用三个穷尽式 lint 分区，并在共享 runner 设置后组合基础/目录/正文门禁与文档类型/API 契约门禁；只有调度方式与 Linux 分区不同。Windows 构建和生产站点验证继续阻塞，而更广泛的 Windows 静态、lint 和产物矩阵仍为观察性检查。
## 曾考虑的替代方案
- **保留宽车道**：最大限度减少工作流 YAML，但会保留观测到的数分钟反馈周期。
- **让每个叶子门禁分别成为 GitHub job**：最大化扇出，但短小的生成器和正文检查准备 runner 的时间会超过检查仓库的时间。
- **向产物消费方上传一次构建**：避免重复编译，但上传/下载和依赖调度会延长墙钟时间；干净构建足够短，可以在有界车道内重复。
- **在两个发布门禁中保留包管理器打包**：把清单选择委托给 pnpm，但会重复启动 200 多个包管理器进程。清单结构门禁加发布视图 fixture 使优化后的清单契约显式化，并会在存在磁盘上有但未发布的依赖时失败。
- **在覆盖率前保留构建**：提供源码套件已不再消费的生成输出；干净树覆盖率证明表明这只是纯粹的延迟。
- **在每个 Node 版本上执行类型检查**：重复编译器工作，而兼容性冒烟已经验证实际的 Node 特有加载与压缩行为。
## 后果
上述分片清单和矩阵 job 不属于当前仓库契约。取而代之的更大 runner 决策在单个进程中保留完整主清单，并以串行套件作为独立完整性判据。
优化后的发布验证器依赖由 `verify-package-invariants` 强制执行的清单 `files` 契约。如果发布规则超出该契约，结构门禁和两个暂存视图必须一起变化。
兼容性 job 不再声称 TypeScript 本身已在每个 Node 运行时下执行。它们证明 Node 22、24 和 26 上对运行时敏感的源码加载，而主运行时负责唯一一次源码图类型检查。

6
.agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-06-parallel-pre-push-gates.md: f2e8f0054e595be20a320ec7095f0fe674eb93c6
2026-07-06-parallel-pre-push-gates.zh.md: 03b8773e475a9d1c82cea830cae6806a1c016f01

2
.agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-07-06-parallel-pre-push-gates.zh.md)
The local-hook portion of this record is superseded by [Fast local Git hooks](2026-07-22-fast-local-git-hooks.md). The bounded gate scheduler and package-level `publint` parallelism remain in force for CI, `doc-sync`, and explicit local commands.
## Problem

33
.agents/notes/implemented/process/2026-07-06-parallel-pre-push-gates.zh.md Normal file
View File

@@ -0,0 +1,33 @@
# Agent Note: 并行 pre-push 门禁
Status: implemented
[English](2026-07-06-parallel-pre-push-gates.md) | 中文
本记录中的本地 hook 部分已由[快速本地 Git hook](2026-07-22-fast-local-git-hooks.md) 取代。有界门禁调度器和包（package）级 `publint` 并行机制仍用于 CI、`doc-sync` 和显式本地命令。
## 问题
文档同步等聚合 job 隐藏了很长的串行链，其成员只读且相互独立。在工作流 YAML 中重复这些叶子清单，会使未来脚本变更有多个位置可以发生漂移；而串行运行包发布检查，会使一道门禁的耗时与包数量成正比。
## 决策
[scripts/run-gates.ts](../../../../scripts/run-gates.ts) 拥有 CI、`doc-sync` 和选择启用的 `check:all` 命令所使用的有界调度器。它将具名模式展开为叶子门禁，遵守产物依赖，缓冲可归因的输出，并在调用方需要不同 worker 上限时接受 `DSH_GATE_CONCURRENCY`。
[scripts/publint-all.ts](../../../../scripts/publint-all.ts) 从 `packages/<group>/<pkg>` 发现包，并以根据 `availableParallelism()` 确定大小的 worker 池运行 `publint`。`DSH_PUBLINT_CONCURRENCY` 可以针对资源配置不同的本地机器和 CI runner 限制或提高 worker 数量。结果按包缓冲，并按确定性的包顺序打印，因此并行执行不会打乱各包的日志块。
各门禁的包脚本仍是临时本地运行所用的词汇。`hygiene` 继续作为聚合 `&&` 链，而 `doc-sync` 在调度器中拥有其成员列表（[通过门禁调度器运行 doc-sync](2026-07-21-doc-sync-through-gate-scheduler.md)）。
## 曾考虑的替代方案
- **保持聚合 job 串行**：执行更简单，但墙钟时间等于各独立检查之和，并重复启动命令包装器。
- **每个叶子门禁声明一个 CI job**：暴露最大工作流并行度，但会重复 checkout、设置和安装开销，并在 YAML 中复制调度器清单。
- **在 shell 脚本内后台运行子命令**：可以并行处理，但会失去各门禁计时、确定性的失败分组和直接的信号处理。
- **每个包声明一个 `publint` job**：暴露最大包级并行度，但会创建手工维护的包清单，包发生变化时就会漂移。
- **以无界并发运行 `publint`**：只有通过拿进程数、内存压力、包 tarball 创建和可读日志冒险，才能最大限度缩短小型仓库的耗时。
## 后果
由调度器支持的命令耗时取最慢依赖链，而非各独立门禁之和，并会报告主导耗时的门禁。代价是维护一个具有显式模式清单的定制调度器。
`publint-all.ts` 采用异步执行并缓冲命令输出，而不是实时继承 stdio。换来的是具有稳定输出顺序的包级并行，以及用于资源调节的单一环境变量。

6
.agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-10-readme-known-limitations-gate.md: 2ca1168d795692730d17b6ab23dd113e8be277e5
2026-07-10-readme-known-limitations-gate.zh.md: 4e42492f501cca1a45a90694acea4ca78e920780

2
.agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-07-10-readme-known-limitations-gate.zh.md)
## Problem
The [documentation standard](../../../../docs/AGENTS.md) assigns limitations to package READMEs. Without a shared shape, an omitted section cannot distinguish an audited absence from forgotten documentation, and variant headings prevent a repository-wide search.

29
.agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.zh.md Normal file
View File

@@ -0,0 +1,29 @@
# Agent Note: 每个包（package）README 中受门禁保护的 Known Limitations 章节
Status: implemented
[English](2026-07-10-readme-known-limitations-gate.md) | 中文
## 问题
[文档标准](../../../../docs/AGENTS.md)规定限制项归属包 README。没有共享形状时，缺少章节无法区分“经审计确认没有限制”与“忘记编写文档”，不同的标题还会妨碍全仓库搜索。
## 决策
`packages/<group>/<pkg>/package.json` 下的每份包清单都有一个同级 README，其中包含规范的 `## Known Limitations and Deferred Work` 章节。其项目符号记录由该包拥有的持久消费方缺口和不明显的维护者约束；普通清理仍留在源码 TODO 或所属 Agent Note（agent 决策记录）中。[`verify-package-readme-limitations` 门禁](../../../../scripts/verify-package-readme-limitations.ts)从清单推导包集合，拒绝缺失 README，并要求恰好一个规范 h2 且至少包含一个顶层项目符号。“Limitations”“Deferred”“What is NOT here”或“Non-goals”等近似标题都会失败。
如果一个包确实没有需要声明的限制事项，则将其列入 `NO_LIMITATIONS` 并省略该章节。新增限制事项时须移除该条目；重命名或移除条目会失败，因为每个条目都必须对应一个被扫描的包。
门禁检查存在性、形状和允许列表。按照文档与[正文](../../../skills/dsh-prose-standard/SKILL.md)标准进行的评审负责覆盖面和准确性。常设规则位于 [packages/AGENTS.md](../../../../packages/AGENTS.md)。
## 曾考虑的替代方案
- **自由格式标题**：无法统一搜索，仍需近似标题检测。
- **要求空章节或写 "None."**：样板文字可能在包新增限制事项后仍然残留；白名单使「确无限制」这一状态显式且可评审。
- **设置字数上限**：合理的限制事项数量因包而异，因此由评审管控这一不设预算的 README 层级。
## 后果
- 新建的包须声明符合条件的限制事项，或显式加入白名单；缺失、漂移或空的章节会在本地和 CI 的 `doc-sync` 中失败。
- 门禁为 `doc-sync` 新增一个无外部依赖的 TypeScript 脚本。
- 重命名受强制的标题需要同时修改脚本和所有包 README。

6
.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-12-package-model-experience-contract.md: 92a8e5a1a81d00dae085e4af89456896373058e6
2026-07-12-package-model-experience-contract.zh.md: 54b181738b8276c634f777ad3424191c8652baec

2
.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md
View File

@@ -2,6 +2,8 @@
Status: implemented
English | [中文](2026-07-12-package-model-experience-contract.zh.md)
## Problem
A package README can explain APIs and runtime mechanics without answering the questions that dominate an agent harness's behavior and cost: what from this package reaches a model request, under which conditions, how long those tokens remain, and whether later requests preserve a reusable KV-cache prefix. The omission is especially hard to audit in a plugin architecture. A consumer may turn a backend result into a tool message, a policy plugin may replace success with an error, compaction may remove old history, and an agent-scoped registration may change one agent's prompt or schemas while leaving every other agent unchanged. Reading only the nominally model-facing packages therefore misses real context effects, while reading source across every dependency is too expensive for routine review.

33
.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md Normal file
View File

@@ -0,0 +1,33 @@
# Agent Note: 包（package）的模型体验契约
Status: implemented
[English](2026-07-12-package-model-experience-contract.md) | 中文
## 问题
包 README 可以解释 API 和运行时机制，却不回答主导 agent harness（智能体框架）行为与成本的问题：该包的哪些内容会进入模型请求、在什么条件下进入、这些 token 会保留多久，以及后续请求是否会保留可复用的 KV cache 前缀。在插件架构中，这种遗漏尤其难以审计。消费方可能把后端结果转为工具消息，策略插件可能以错误取代成功结果，压缩可能移除旧历史，而 agent 范围的注册可能改变某个 agent 的提示词或 schema，却不影响其他 agent。因此，只阅读名义上面向模型的包会遗漏真实的上下文效应，而在每次常规评审中跨所有依赖阅读源码又成本过高。
## 决策
每个具有面向模型或邻近模型契约的 workspace 包 README 都以规范的[模型体验章节](../../../../docs/cookbook/adding-a-package.md#4-write-the-package-readme)收尾，位置紧邻 `## Known Limitations and Deferred Work` 之前；位于“无限制项”允许列表中的包则以模型体验本身结尾。经审计确认与模型无关的通用包通过 `NO_MODEL_EXPERIENCE_SECTION` 省略该章节。
具有直接、条件式、有上限、全生命周期、多表面或辅助模型效应的包，为每个上下文表面使用一个 H3。每个表面包含三个有序 H4 字段——`What the model sees`、`Token effect` 和 `KV Cache effect`——每个字段都以一个正文段落开头。cache 字段区分仅追加增长、稳定重复前缀、替换先前 token，以及独立模型请求；它点明由包拥有、且能在新内容追加前改变请求的每项配置、范围、生命周期、压缩或路由变化。“Does not invalidate”表示该包保留一个已经可复用的前缀，并非承诺提供方一定命中 cache 或保留某段时间。由包拥有的稳定文本按原文精确引用：系统提示词正文和其他长字面量在引入它们的字段下使用带标题的 H5 加 `markdown` 围栏，通常位于 `What the model sees`；短字面量则以内联形式保留，并点名插值占位符。工具 schema 表面链接生成式[工具目录](../../../../docs/tool-catalog.md)中带锚点的章节，并且只陈述组合或配置增量；仅运行时定义解释目录为何省略它们。依赖数据和由提供方拥有的文本采用摘要。agent 范围的可见性须显式说明；当范围可隐藏提示词与 schema 中的一者而不影响另一者时，两种表面保持分离。
没有模型上下文效应的包，或某条路径完全由另一个包渲染的包，使用验证器审计过的短格式：一句以 `None, as ` 或 `Indirectly, through ` 开头的句子，随后是一个 `KV Cache effect` H4 和一个正文段落。纯传输包和无密钥测试支持包若不创建任何进入模型的内容，就使用 none 格式。提供方后端即使会限制或过滤数据也使用 indirect 格式；具名子项拥有全部效应时，接线 bundle 也使用该格式。这些章节定位贡献并声明不会直接使 cache 失效，同时不重复陈述消费方。结构化章节同样只记录由包拥有的输入、变换和增量。
`verify-package-readme-model-experience` 发现包清单，并验证三种分类、规范末尾章节顺序、确切字段标题深度与顺序、非空字段段落、逐字块的 H5 归属、具体字面量证据，以及带锚点的工具目录链接。它在 `doc-sync` 和并行门禁 runner 中运行。评审仍负责覆盖面、链接相关性和事实准确性。
## 曾考虑的替代方案
- **只记录注册提示词或工具的包**：否决。后端、策略插件、适配器、持久化、作用域和压缩都会改变 token 的内容或生命周期，却不拥有面向模型的 schema。
- **从源码生成一份集中式上下文成本目录**：否决。AST 能找到注册点，但无法推断语义条件，如历史保留、输出截断、父子可见性或辅助模型边界。包 README 是实现本地的契约；集中副本会增加又一个漂移面。
- **要求给出精确 token 数**：否决。精确数量取决于所选模型的 tokenizer、适配器序列化方式、配置和运行时数据。稳定的契约是增长形状：每请求固定、每调用条件性、保留、替换、有上限或零直接影响。
- **使用表格**：否决。精确源码文本和条件式结果形状会使单元格密集而难以扫读。重复的小节在保留相同字段的同时，为每个上下文表面提供易读的纵向空间。
- **允许所有零影响包省略该章节**：否决。无约束的缺失在「经审计的零影响」和「忘记写文档」之间有歧义。省略仅限于在验证器中以理由命名的模型无关通用包；模型相邻的零影响包保留一句显式说明。
- **要求经审计的零效应包或简单间接包使用完整结构化格式**：否决。它会围绕一个事实重复标签。受门禁约束的句子加 cache 字段既保留显式覆盖，又没有多余仪式。
- **只有约定而无门禁**：否决。仓库级契约必须覆盖未来的每个包；评审者的记忆无法可靠地检测到遗漏的 README 章节。
## 后果
评审者可以从任何面向模型或邻近模型的包开始，看到它对对话模型、子模型和辅助调用的贡献，无需重建完整插件图。token 预算工作可以区分重复请求开销和依赖数据的历史，而 cache 敏感工作可以识别仅追加路径，以及最早由包引起的前缀变更。agent 范围变更有明确的文档检查点。每当模型可见行为发生变化时，包作者都要维护一个或多个紧凑的上下文表面块，或一种已分类的短格式；经审计的通用包不携带无关的模型样板。结构化字段不承诺由提供方给出的精确 token 数或 cache 命中；测量仍取决于具体模型、提供方和工作负载，而所记录的增长、可见性和前缀稳定性契约保持稳定。