Jotaro Space
DeepSeek Harness Testing、Docs、Agent Notes：这个仓库为什么校验这么重
JotaroRD
  2026-08-14 01:15:00   2026-09-04 18:20:23  

模块定位

DeepSeek Harness 是一个 pre-release 但工程约束很重的仓库。它的测试和文档系统不是装饰，而是维持插件化架构不散架的关键。

相关入口：

  • package.json scripts
  • scripts/run-gates.ts
  • docs/AGENTS.md
  • .agents/notes/README.md
  • docs/development.md
  • packages/test-support/*
  • vitest.*.config.ts

测试层次

常见命令：

1
2
3
4
5
6
7
8
pnpm run test
pnpm run test:coverage
pnpm run test:e2e
pnpm run test:snapshot
pnpm run typecheck
pnpm run lint
pnpm run hygiene
pnpm run doc-sync

这里 test:coverage 是 CI coverage gate。不是所有变更都要本地跑全套，但 PR 前要按变更面选择相关检查。

Snapshot 为什么重要

Agent 产品的输出和 transcript 是用户可见行为。只写单元测试不足以覆盖 assembled application transcript。因此非平凡模型/用户可见行为要加或更新 keyless snapshot。

这类 snapshot 不只是测函数返回值，而是测 assembled runtime 里用户真正看到什么。

TypeScript 架构约束

仓库有 Host 和 Client 两个 aggregate：

  • tsconfig.host.json
  • tsconfig.client.json

原因是两侧都会 declaration-merge Cordis Context，如果放进同一个 TS program 会冲突。构建顺序也围绕这个事实设计。

Docs Gate

pnpm run doc-sync 会跑大量文档相关 gate：

  • doc typecheck。
  • generated catalogs。
  • markdown wrap。
  • markdown links。
  • public repository links。
  • doc refs。
  • mermaid。
  • agent note classification。
  • agent note format。
  • translation pairing。
  • doc budgets。
  • documentation build。

这解释了为什么改一篇文档也不能随便写：这个仓库把文档当成可执行契约的一部分。

Agent Notes

每个非平凡变更都要有 Agent Note。Agent Note 记录“为什么这么决策、放弃了什么、后续维护成本是什么”。它不是 PR 描述，也不是实现日志。

生命周期：

  • proposed/
  • implemented/
  • rejected/
  • archived/

Implemented note 必须写当前事实，不写“以前/现在/后来”的变更故事。

双语文档

仓库要求中英文配对文档同步维护。一个 pair 包括：

  • foo.md
  • foo.zh.md
  • foo.i18n.yaml

配对校验会检查结构、链接目标、hash 记录。注意中文正文里的普通链接目标要和英文侧结构一致，不是所有链接都改成 .zh.md。

常见坑

第一，生成目录不能手改，要改生成源。

第二，README 改动通常需要中文 counterpart 和 i18n sidecar。

第三，Agent Note 不是计划清单，implemented note 要写已交付事实。

第四，文档里的 TypeScript fence 可能要参与 doc-typecheck。

继续读源码

  • docs/AGENTS.md
  • .agents/notes/README.md
  • docs/development.md
  • scripts/run-gates.ts
  • packages/test-support/README.md