# DeepSeek Harness 文档体系参考 资料来源:本地源码快照 [`~/workspace/research/deepseek-harness`](/Users/pptg/workspace/research/deepseek-harness/README.md),远端为 [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)。本次查看的 `HEAD` 为 `528c682e061696f5a160f363f236ecbf53cbd006`(2026-08-21);以下结论描述该快照,不代表上游当前状态。 ## 一句话结论 DeepSeek Harness 将文档视为源码的一部分:Markdown 写在所属模块,网站只是投影;每条事实只能有一个权威归属;英中两份内容与一致性记录必须同时提交;文档链接、示例类型、生成内容、翻译结构、站点和篇幅都进入自动检查。 这套体系很适合多包、多人和 Agent 高频改动的仓库,但 PLoop 在第一轮不应全量复制。我们应先借鉴“单一归属、文档与代码同改、可执行校验、面向用户文档与内部设计分层”,而不为内部中文设计记录引入全仓双语三件套和数十个专项脚本。 ## 1. 文档不是一个目录,而是按职责分层 它以 [`docs/AGENTS.md`](/Users/pptg/workspace/research/deepseek-harness/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`](/Users/pptg/workspace/research/deepseek-harness/website/docs.ts) 是一份发布清单:它将指定源文件映射到中文根路由和英文 `/en/` 路由,并定义导航标签、侧栏分组、顺序和页面大纲。VitePress 配置以 `website/.generated` 作为可丢弃的站点输入;[`scripts/project-doc-site.ts`](/Users/pptg/workspace/research/deepseek-harness/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`](/Users/pptg/workspace/research/deepseek-harness/scripts/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`](/Users/pptg/workspace/research/deepseek-harness/scripts/run-gates.ts) 定义 `doc-sync` 门,并行运行文档相关检查;[`package.json`](/Users/pptg/workspace/research/deepseek-harness/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](../decisions/decisions.md#d-016文档按单一事实归属维护内部中文单源发布面按需双语) 采用最小文档治理,并在 [W-M0a-03](../plan/work-items/W-M0a-03-toolchain-and-quality-gates.md) 落地 `check-docs`。全仓双语配对和文档站仍未采用。