ploop/docs/reference/deepseek-harness-docs-reference.md
2026-08-31 15:27:34 +08:00

9.2 KiB
Raw Permalink Blame History

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 与决策主要服务中文团队,因此不采用“所有内部文档强制英中三件套”。建议的边界是:

  1. 内部设计、计划、决策:保持中文单源,正常 Markdown 链接校验即可。
  2. 将来公开的网站页面、开放的 RAG adapter 协议、OpenAPI 对外说明:若承诺双语,再在该发布子树采用成对文件和 CI 检查。
  3. 数据集原文、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;只为发布面引入双语配对策略 将内部知识与对外产品文档解耦

6. 本次没有做的事

  • 没有从 GitHub 重新克隆:本地已有完整源码目录,因此不会覆盖或重复拉取。
  • 没有执行其 doc-sync:该门会构建整个 TypeScript monorepo,且本次目标是审阅结构与机制;以上结论来自源码、脚本和配置的静态核查,不是一次上游 CI 成功声明。
  • 初次调研时没有直接将上述做法变更为 PLoop 约束;后续已通过 D-016 采用最小文档治理,并在 W-M0a-03 落地 check-docs。全仓双语配对和文档站仍未采用。