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

78 lines
9.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`。全仓双语配对和文档站仍未采用。