工程实践：构建、测试、CI gates 与开发纪律

dsh 仓库本身的工程化程度极高，对做 agent 工程化的人是很好的参考样本。

构建：Host/Client 双面

TypeScript 两个隔离 aggregate：tsconfig.host.json（packages/examples/tests/scripts/website）与 tsconfig.client.json（packages/client/*、apps/web）。原因：两侧都对 cordis Context 接口做同 key declaration merge，合成一个 ts.Program 会冲突。根 tsconfig 只是 solution root。
顺序：tsc -b host → tsdown --env.DSH_BUILD_FACE host → tsc -b client → tsdown client → build:web。Typert 只在 Host tsdown 阶段运行：严格分析 ts.Program，为每个业务包生成 typert.host.js 与 typert.remote-client.js——这是 Web 前端类型安全 RPC 的来源（@Remote 装饰器 → 生成的具体函数 ctx.remote.goals.create(...)，非 JS Proxy；运行时经 POST /api/<ns>/<method> 严格校验进出）。
静态分析/测试经 base paths 解析到 src（source plane）；消费 lib/ 的 gate 显式声明依赖（artifact plane）——两者绝不混用。

测试矩阵（vitest 六 config）

层	命令	分工
Unit	`pnpm test`	packages/examples 的 tests；每个 registry 必须有 HMR-safety 测试
Coverage	`test:coverage`	*per-file 100% on `packages///src`*；未覆盖行视为 dead code 该删；自定义 reporter 打印精确 `path:line:col`
Real-API e2e	`test:e2e`	真 key 打 live provider（DeepSeek + EXA/Perplexity smoke）；无 key self-skip
Snapshot	`test:snapshot`	keyless 期望输出：transport contracts、presentation、persisted logs；record/refresh/replay 三态
Web browser	`test:web`	Chromium（Playwright）replay 对比快照；Linux PR 必过 gate
Perf/Stress	`.perf.ts` / `.stress.ts`	opt-in，timeout 600s，不进 CI

测试政策要点：“We are DeepSeek — do not ration real-API tests”（inference is cheap；with-key 测试证明 agent 真的能工作）；prefer real implementation over mock；verify the world, not the self-report（e2e 断言外部重跑命令/重读文件，不信 agent 自述）；test the real entry path（built lib/bin.js 在 plain node 下跑，暴露 tsx 掩盖的问题）；非 trivial 的 model/protocol/人可见变更必须同 PR 加 keyless snapshot。

CI gates（scripts/run-gates.ts）

自研 in-process 有界并行 gate scheduler（依赖图验证：重复 id/未知依赖/环检测；失败下游标 skipped）。14 个 mode（ci-primary、ci-static、ci-coverage、ci-snapshot、ci-windows-* 等）。ci-primary 含：runtime-closure、package-invariants、typert-contracts、typecheck、oxlint lint、jscpd duplication、coverage（双 gate 分 worker 预算）、node-compat smokes、snapshot、module-graph、knip、build、publint、built-bin smoke（12 个 built-artifact e2e，证明包名 import 在 plain Node 能到 lib/）。doc-sync 叶子约 30 个：各类 catalog/graph 校验、export-jsdoc、md-links、mermaid、translation-pairing、doc-budgets、VitePress build……

15 个 GitHub workflow，最独特的是：PR 的 blocking windows job 在 hosted Linux 上用 Wine 跑 Windows Node；windows-native 在 windows-2025/self-hosted 独立报告。另有 issue 管理自动化（policy.mjs 本身有测试、进 gate，驱动 GitHub Project 状态流）。

AGENTS.md 核心纪律（面向 AI agent 贡献者）

Pre-release stance：“foundation over blast radius”——宁可自由 rename/repackage 并同步所有引用，不做兼容 shim。
命令纪律：只报告实际跑过的命令；绝不默认跑全套、不重复已通过的检查（CI 拥有穷尽覆盖）；test:coverage 才是 coverage gate。sandbox 挡住时用最窄 host escalation 原样重试并要求证据；绝不绕过真实测试失败。
Registrations are effects；Model-visible ⟺ logged；Plugins, not loop changes；seam 三角色完备；waterfall listener 必须调 next()；closed union switch 以 assertNever 收尾。
插件内禁止 hardcoded tunables（必须成 cordis.yml 可改的 validated Config）；misconfiguration fails loud。
跨边界 opaque id 用 branded type；信任 TypeScript at typed same-process boundaries（校验只放 parser/config/队列/model JSON/durable/worker/进程/wire 边界）。
非 trivial 变更必须同 PR 附 Agent Note（.agents/notes/，archived 冻结）；每个 module/export 有 JSDoc（verify-export-jsdoc 强制）；文档文风不用隐喻，contract/boundary 等词受限使用。
PR 纪律：刻意选择 history，独立变更分开；rewrite 用 --force-with-lease，禁裸 --force。
CLAUDE.md 是 AGENTS.md 的 symlink（三处）。TODO 三级：FIXME > TODO > XXX。

Defensive patterns（每条对应一个真实 bug class）

正交结果独立上报：一个进程可以同时 timed out AND exit 0——timedOut/signal/exitCode 各自独立，不嵌套分支。
公共契约两侧都遵守：多种结果表示先 normalize 再过公共 API。
Async state ≠ synchronous state：多个 follow-up/steer 可能共享一个 running 区间；own 一次 run 必须显式定义区间并处理”nothing to wait for”。
Dispose 必须到达 quiescence 而非只请求：kill → await 子进程退出；先关 listener 再 kill，让迟到 completion 保持沉默。
Dispatcher 包容 callback 异常：用户 listener 抛错不能 reject 所在 promise 或饿死后续 listener。
不给不可信输出 ambient env 或可预测路径：子进程 env scrubbed；temp/spill 用 0700 私有目录、随机名、'wx' 0600 独占创建防 symlink race。
Unlink link-shaped paths：symlink/junction 用 lstat + unlinkSync 删链接本体；recursive rmSync 只用于确知的真实目录。

其它工程细节

i18n 双语三兄弟：foo.md + foo.zh.md + foo.i18n.yaml（记录两侧确认一致时的 git blob hash）；结构镜像强制（标题/列表/表格/链接/代码块一一对应，verify-translation-pairing 机器校验）；专用 git merge driver dsh-translation-pairing fail closed。
verify- 脚本群约 35 个*：type-equiv（文档 ts type-equiv 代码块与源码声明逐符号一致）、doc-budgets（字数预算）、cordis-config、runtime-closure、node-next-types（built declarations 对临时 NodeNext 消费者验证）等。
lefthook：pre-commit 只跑快速检查（pairing/archived notes/staged oxlint/notices 重生成/vendor manifest guard）；刻意不跑测试/snapshot/build——CI 拥有穷尽覆盖。
postmortem/ 目录收录事故复盘并被 testing.md 引为 smoke test 价值依据；session fixture 必须 macOS/Linux 双平台 replay——“fix fixtures, not normalizers”。

Wiki AI

目录