9.2 KiB
DeepSeek Harness 文档体系参考
资料来源:本地源码快照 ~/workspace/research/deepseek-harness,远端为 deepseek-ai/deepseek-harness。本次查看的 HEAD 为 528c682e061696f5a160f363f236ecbf53cbd006(2026-08-21);以下结论描述该快照,不代表上游当前状态。
一句话结论
DeepSeek Harness 将文档视为源码的一部分:Markdown 写在所属模块,网站只是投影;每条事实只能有一个权威归属;英中两份内容与一致性记录必须同时提交;文档链接、示例类型、生成内容、翻译结构、站点和篇幅都进入自动检查。
这套体系很适合多包、多人和 Agent 高频改动的仓库,但 PLoop 在第一轮不应全量复制。我们应先借鉴“单一归属、文档与代码同改、可执行校验、面向用户文档与内部设计分层”,而不为内部中文设计记录引入全仓双语三件套和数十个专项脚本。
1. 文档不是一个目录,而是按职责分层
它以 docs/AGENTS.md 规定“one home per fact”(每个事实只有一个归属),并明确下列文档层:
| 层 | 在 DeepSeek Harness 中的归属 | 作用 | PLoop 可借鉴点 |
|---|---|---|---|
| 全局操作约束 | 根 AGENTS.md |
每次 Agent/开发会话都需要的短规则 | 保持短小,只链接到细则 |
| 架构地图 | docs/architecture.md |
系统组成、主循环、扩展点与阅读顺序 | PLoop 的整体架构图只放一个所有者 |
| 子系统参考 | docs/subsystems/ |
逐子系统定义、语义和生成 API | 将 Dataset、SUT、Run、Trace、Score 等契约按领域拥有者记录 |
| 决策记录 | .agents/notes/ |
为什么这样设计、取舍及必需验证 | PLoop 现有 docs/decisions/ 承担这个角色;保持“决策”与“当前设计”分离 |
| 操作手册 | docs/cookbook/ |
有编号验证步骤的 how-to | 将导入数据、接入 RAG、重评等可操作流程放入 docs/guides/ |
| 产品文档 | docs/user/ |
对外发布的用户/开发者指南 | 未来平台上线时从内部设计中筛选稳定的用户路径 |
| 模块契约 | 各 package README.md |
配置、限制、扩展点与使用体验 | 后续 backend/、frontend/、pkg/ 形成稳定边界后,为各边界补充 README |
| 事故/历史 | docs/postmortem/ |
以证据为中心的事故叙事 | 仅在真实运行事故出现时添加,避免把日常设计讨论写成历史叙事 |
这并非按文件类型分目录,而是按读者问题分配所有权:架构文档不重复字段定义,操作指南不重复设计取舍,决策文档不成为当前行为的第二份规范。上层用链接指向下层事实所有者,避免多份文档悄悄漂移。
2. 源文档与文档站分离:站点是投影
Markdown 保留在业务归属目录,而 website/docs.ts 是一份发布清单:它将指定源文件映射到中文根路由和英文 /en/ 路由,并定义导航标签、侧栏分组、顺序和页面大纲。VitePress 配置以 website/.generated 作为可丢弃的站点输入;scripts/project-doc-site.ts 负责投影、重写站内链接、保留回 GitHub 的编辑入口,并输出每页的原始 Markdown 副本和 llms.txt。
这个设计避免了两套内容:源文件仍由代码/子系统拥有,网站只负责呈现。站点发布面也不是“把整个 docs/ 暴露出去”:发布清单选择了用户指南、开发教程、架构、子系统参考、部分生成 catalog 和 cookbook;内部决策、维护规范、事故记录等仍留在仓库。
对 PLoop 的含义是:第一轮继续以仓库内 README.md + docs/ 为唯一知识源。等 M4–M6 有稳定的操作者流程和需要对外浏览的用户文档时,再增加 website/ 与“源文档 → 路由”的显式清单;不要复制一份 Markdown 到站点目录。
3. 双语不是翻译习惯,而是可验证的提交契约
DeepSeek Harness 的有效文档通常包含同目录的三件套:foo.md(英文)、foo.zh.md(中文)、foo.i18n.yaml(上次人工确认两者语义一致时的两个 Git blob hash)。中文和英文同等权威;两边标题、列表、表格、代码块与内部链接结构必须镜像,并互相提供语言切换链接。
verify-translation-pairing.ts 检查三件套完整性、记录的内容 hash、链接语言、Markdown 结构和生成区约束。它刻意只证明“这对文件被重新确认过且结构一致”,不假装能判断译文质量;术语和人工审查仍是必需环节。该快照的 docs/ 下有 219 篇 Markdown,其中 107 篇 .zh.md 与 107 个 .i18n.yaml 侧车文件,说明这一机制已在较大文档面上运行。
PLoop 的当前设计、TODO 与决策主要服务中文团队,因此不采用“所有内部文档强制英中三件套”。建议的边界是:
- 内部设计、计划、决策:保持中文单源,正常 Markdown 链接校验即可。
- 将来公开的网站页面、开放的 RAG adapter 协议、OpenAPI 对外说明:若承诺双语,再在该发布子树采用成对文件和 CI 检查。
- 数据集原文、gold 和自动生成的 API schema:将源数据/生成器视为权威,不手抄翻译副本;中文说明单独标明派生关系和版本。
这样保留其“翻译必须可追踪”的价值,不把第一轮的文档维护成本扩大三倍。
4. 文档质量门是独立的 doc-sync
scripts/run-gates.ts 定义 doc-sync 门,并行运行文档相关检查;package.json 将它暴露为 pnpm run doc-sync。关键检查可分成四类:
| 类别 | 代表检查 | 防止的问题 | PLoop 首轮建议 |
|---|---|---|---|
| 可访问性 | Markdown 链接/锚点、VitePress build、站点投影测试 | 文档移动后链接失效、发布页不可构建 | M0a 加入相对链接检查;有文档站后加入站点 build |
| 代码一致性 | TS 文档示例类型检查、类型等价检查、生成 catalog/图谱 freshness | 文档中的 API 示例和代码分离 | 首轮仅对 OpenAPI/JSON Schema 示例做契约测试;前端/后端稳定后再考虑语言级示例编译 |
| 结构与归属 | 文档引用、包路径、README 约束、Markdown 单行段落、字数预算 | 重复事实、失控膨胀、目录改名后漂移 | 执行“一个事实一个所有者”和链接检查;暂不设硬性字数线,规模变大后才设置 |
| 双语与生成内容 | 翻译配对、翻译提示词、生成区、目录/工具/配置 catalog | 半份翻译、手改生成物、清单过期 | 仅在未来对外双语子树启用;不要在 M0 复制全套 |
其很值得采用的原则是:代码契约改变时,拥有该契约的文档必须同一变更更新;生成清单从源码生成,而不是手写第二份表;异常、决策和当前说明各自有固定落点。它不值得直接照搬的部分是对 TypeScript monorepo、Cordis 生成 API 和全仓双语的深度定制。
5. 对 PLoop 的落地建议
| 时机 | 建议动作 | 目的 |
|---|---|---|
| M0a | 在统一 make check 中保留 Markdown 相对链接审计;根 README 和 docs/README.md 继续作为入口/分类导航 |
最小成本防链接漂移 |
| 已落实(D-016 / W-M0a-03) | 新增简短 docs/AGENTS.md:分类、单一事实归属、代码/契约同改、决策/设计/指南的边界;并以 make check-docs 自动检查相对链接与锚点 |
让 Agent 和开发者以同一规则新增文档 |
| M1–M4 | 在每个领域包/API 路由旁维护最小 README 或 ADR 链接;将 API schema、数据库迁移、样例 JSON 的权威来源固定为代码或 schema | 降低 DDD 文档与实现的重复 |
| M5–M7 | 为 MultiHop-RAG 的导入、执行、Trace 和 regrade 写可验证的操作指南;文档中的命令以实际 CI/Compose 流程验证 | 让评测结果可由新成员复跑 |
| 对外发布前 | 评估 VitePress/同类站点;采用显式页面清单投影,不复制 Markdown;只为发布面引入双语配对策略 | 将内部知识与对外产品文档解耦 |