dsh-doc

DeepSeek Harness 文档

概要

DeepSeek Harness 文档规范：让每个页面都可搜索、便于新手阅读，并且足够准确，能供 Agent 和维护者使用；同时确保文档网站是经过测试的仓库 Markdown 投影。首先遵循仓库中的 AGENTS.md 文件并执行各项检查，然后按此工作流处理与类型映射的元数据、渐进式细节、逐行对齐的双语页面、语料库审计和网站发布。每条事实只设一个归属方：源码、测试、生成的目录、软件包 README、指南、Agent Notes 和临时文档各自保留其对应类型的事实。session-persistence-jsonl 的 README 双语版本是格式参考示例。

目录

• 工作流
• 事实核查流程：测试，而非臆测
• 类型系统和模板
• 文风规则
• 质量标准
• 审计语料库
• 字数预算
• 网站发布
• 详细参考
• 验证
• 开发者备注

工作流

针对每个指定范围，按以下顺序执行。常见读者路径应简洁，但不要仅为减少字数而删除失败情况、归属方、限制或其他必需约定。

1. 阅读根目录和更具体位置的 AGENTS.md、文档规范、目标页面、其源码/测试、导航归属方以及双语记录。
2. 根据页面的主要用途和读者进行分类：产品快速入门、用户任务指南、贡献者教程、架构概述、软件包/子系统参考、生成的参考文档、Agent 指令、决策记录或临时文档。
3. 将页面放在最接近其归属方的位置。软件包约定应放在软件包代码旁；跨软件包学习、用户、开发者、架构、讨论和有有效期的临时材料应放在 docs/ 中。
4. 在编写细节前，明确读者的起始状态、可观察结果、可能的失败情况、恢复路径，以及后续有用的深入内容。
5. 添加或修订 YAML 元数据——为文档指定映射到相应用途模板的 kind——然后依次编写 Summary、Table of Contents、面向用户的内容、面向开发者的内容、可选的 Further Exploration 和最后的 Dev Note，文档类型允许时遵循此顺序。
6. 在同一轮中更新双语对应版本。保持标题、列表、表格、代码、链接、frontmatter 布局和物理行数对齐。
7. 对照代码、测试、生成器、软件包元数据或当前决策归属方核实每项陈述；并按下方的事实核查流程运行页面中说明的操作。更新归属方后，再更新任何衍生材料。
8. 先运行针对性检查，再运行 pnpm run test:docs、pnpm run doc-sync、pnpm run lint 和 git diff --check；重新通读完整差异，先检查正确性，再检查简洁性和与仓库的契合度。

事实核查流程：测试，不要臆测

文档说明产品如今的行为，而操作声明唯一可接受的证据就是实际运行过。本流程适用于每份新文档，以及每个声称操作、命令、默认值、错误或平台差异的新段落，必须严格遵循。

1. 编写安装说明前，先对主题进行分类。 查阅事实，不要看文件夹名称：检查 package.json 中是否声明了 dsh.bundle.patch，并检查入口文件中的插件形态（导出 apply 或默认导出服务即为插件；纯模块 API 则为库）。Bundle 使用 dsh plugin --profile <name> add <package> 安装，且只有这种包类型会通过该命令激活 profile 层；插件以 cordis.yml 条目挂载；库只是依赖，本身没有安装方式。具有特殊状态的包（库、Bundle）应使用各自的 README 模板，绝不要套用不适用的插件 README 安装说明。
2. 针对当前检出版本运行每项声明的操作。 按文档所示的方式，准确执行每条 CLI 命令、配置片段，以及每个 profile 或补丁示例；只记录实际观察到的内容，包括准确输出、警告和失败模式。如果某项声明依赖于你无法获取的密钥或网络，请说明这一点，并指出负责验证的人员，而不要直接断言其行为。
3. 删除无法复现的内容。 绝不要凭记忆、类比或相邻包 README 中的信息，沿用命令、字段、默认值或行为。如果某项声明无法复现，应修正声明，而不是测试。
4. 根据最新的 master 检查旧文档。 修改现有页面前，先执行 git fetch origin，并将相关部分与 origin/master 对比；配对 sidecar 会恢复任一侧最后确认的文本。master 上过时的说法依然是错误的：应根据代码修正，而非沿用旧文案。
5. 每次编辑后重新记录配对。 每次配对编辑都要重新运行 pnpm run verify-translation-pairing --write <pair>，以确保 sidecar 跟踪已确认的配对。

kind 系统与模板

kind front matter 字段会准确选择一个 README 模板。元数据参考中的每种 kind 都对应 templates/ 中的一个模板文件，且每个模板都只对应一种 kind；文档检查会根据相同的机械事实推导预期 kind。

• package-group → templates/package-group.md：分组映射（packages/README.md、packages/<group>/README.md）——介绍这一系列，映射其直接包含的包，并链接由包维护的详情。
• package-reference → templates/package-reference.md：Cordis 插件或服务包——挂载配置、配置表、折叠的实现内容、模型体验和已知限制，均采用 gate 规定的形式。
• package-library → templates/package-library.md：没有插件接口的包——使用者入口点、不包含配置文件安装路径、不包含挂载配置。
• package-bundle → templates/package-bundle.md：声明 dsh.bundle.patch 的包——经过验证的 dsh plugin 安装路径、层语义、补丁文档。
• persistence-change → templates/persistence-change.md：docs/persistence-changes/ 中的带日期记录——确认检测到的类型转换，并列出每个根节点的前置类型和生成后的架构。
• persistence-release → templates/persistence-release.md：docs/persistence-changes/releases/ 中固定的标签——比较重建的历史类型，但不声称已确认兼容性。
• persistence-format → templates/persistence-format.md：docs/persistence-changes/historical-formats/ 中的历史 Session 格式检查点，包含完整架构；当前写入器使用现有目录。
• upgrade-guide → templates/upgrade-guide.md：docs/upgrade-guide/v<version>/<item>/guide.md 及其中文对应文件——针对一种外部可感知的破坏性变更提供迁移步骤，由 dsh-create-upgrade-guide 负责维护。

开始编写前先打开模板，并遵循其骨架和规则；模板会说明 kind 的含义、页面结构，以及每个章节必须通过的事实检查。新增 kind 时，必须同时提供独立的模板文件、明确记录的仓库定位或指定的负责人，以及一项将文档映射到该 kind 的专项检查。

语气规则

这些规则决定一个章节可以写什么。它们适用于所有面向用户的人工撰写页面，对软件包 README 尤其重要。

• 摘要说明主题能做什么。 开篇的 Summary 和面向用户的章节应描述用户或 Agent 可以用主题做什么——包括结果、收益、适用场景和主要成本——而不是描述其角色、类型或内部身份。在软件包摘要中，“它是什么”仅指读者可见的功能，而不是它在 Cordis 中的角色、注册项或内部组件。除非读者会在配置、命令或公共 API 中直接使用，否则省略源代码标识符。“该 seam 会注册 ctx.x，并追加 x/event 记录”是在叙述身份；“你可以为每条消息保存一条备注，并且重启后仍会保留”才是在说明它能做什么。
• 开发者章节应解释，而不是罗列。 折叠的实现内容应涵盖整体设计理念、架构和概略的数据流——足以让读者理解软件包的工作方式——并链接到代码以了解精确细节。折叠内容中不得包含完整 API 目录、详尽的列清单、事件载荷枚举或对 JSDoc 的复述。
• Dev Note 是唯一允许杂乱的区域。 不完整的想法、草稿、尚未确定的方向、测量产物和工作假设只能放在最后的 Dev Note 中，并明确标注为非权威内容。其他所有章节都必须使用经过润色、反映当前状态的文字。
• 只写当前状态。 普通文档描述当前代码库。专门的 persistence-change、persistence-release 和 persistence-format 记录保留历史类型证据；版本发布对比和格式检查点描述已观察到的历史，不得声称兼容性。upgrade-guide 描述从其版本目录对应的发布版本升级到下一个版本的变化。Agent Notes 和事后复盘保留各自的历史范围。
• 使用受控的技术英语。 每个句子都应有明确的执行者，并且只包含一个主要动作，以免歧义影响行为。每个概念使用同一个术语，优先使用直接的动词，拆分层叠的指令和条件，并保留情态含义和例外情况。遵循页面风格参考中非认证、受 ASD-STE100 启发的规范。精确性需要时，不要强行缩短句子。

质量标准

评审时请使用以下定义。每个章节都应先用一段简短文字说明内容方向，再进入小节或详尽细节。

• 简明： 常见路径只包含实现目标所需的信息；完整细节可通过一个直接链接或深入一层获取。
• 直观： 前置条件先于依赖它们的概念，下一步操作一目了然，标题使用读者会搜索的术语。
• 友好： 读者能识别成功状态，在操作前了解风险，从常见失败中恢复，并自行决定是否继续深入。
• 准确： 每项持久有效的声明都有明确的责任方，其验证方式与风险相称。
• 便于 Agent 阅读： 元数据、稳定的标题、锚点、术语、责任归属以及当前状态／提议状态，有助于在不加载整个文档集的情况下进行定向检索。
• 对新手完整： 没有代码库背景的专业工程师，也能通过 3 到 5 个互相链接的页面还原相关架构或功能。

不要对详尽参考资料统一施加字数限制。应衡量入口路径长度、查询一项内容时需要浏览的无关材料、最大章节规模、标题数量和页面大小；当检索成本较高时，按现有领域责任方拆分。

审查文档集合

阅读（不要重新总结）负责维护以下内容的契约：docs/AGENTS.md，了解层级、教程／参考文档形式、分类、篇幅预算和赘述检查清单；.agents/notes/README.md，了解 Agent Note 生命周期；docs/i18n/README.md，了解双语配对规则；以及 root AGENTS.md，了解长期指令。审查和编辑时排除 .agents/notes/archived/——已归档的笔记是冻结的历史记录。

对范围内的每份面向读者的文档（不包括 Agent Notes），按照标准的编写顺序处理：定位文档并说明其主题；确定允许的细节层级，将更深入的说明移至负责维护该内容的下级文档，并添加链接；根据预期用途而非路径，将文档归类为教程或参考文档；对于教程，按照前置知识和难度排列概念；拆分篇幅较长的混合形式文档。随后检查位置限制：配对文档每次编辑都需要更新对应文档并使用 --write 重新录制；生成的目录绝不可手动编辑；移动操作必须是原子性的，并在同一变更中修复所有指向该内容的链接。

完成结构检查后，按赘述检查清单排查，先用成本最低的方法。使用 dsh-trim-cot-leakage 检查推理过程记录泄漏；搜索独特短语，查找重复规则；用权威维护源替换手写目录和状态清单；从已实现的 Agent Notes 中删除迁移计划和将来时的规范文本。使用 pnpm run verify-doc-budgets --list 和字数扫描测量超出预算的文档；如果删减文本会改变承诺的行为，而非仅改变说明，先提出行为变更（遵循 dsh-find-simplifications）。保留每条承载关键约束的规则，最好用一到三行说明，并链接到其理由；不要为了迁移可有可无的推理而新建说明文档。

字数预算

pnpm run verify-doc-budgets 会将长期维护的文档与 scripts/doc-budgets.manifest.json 中的上限进行比较；若检查未通过，请遵循 docs/AGENTS.md 中按顺序执行的迁移、精简、提高上限策略。上限是护栏，不是精简目标：字数达到或低于目标时，至少保留 5% 的余量；只有确实需要空间时才提高上限，并在 PR 中说明清单差异的理由。

网站发布

网站是经过测试的投影，而非第二份副本：website/docs.ts 是显式公开许可清单，将规范的 docs/ 源文件映射到路由树；scripts/project-doc-site.ts 会将其改写到可丢弃的 website/.generated/ 树中；VitePress 则构建该树。仓库中的 Markdown 始终是唯一可编辑的内容源；翻译始终作为同级配对文件（foo.md、foo.zh.md、foo.i18n.yaml），绝不使用区域设置目录。只在规范源文件中编辑已发布页面；新增页面时添加一条清单记录；移动或移除页面时，须原子性地更新源文件、清单记录和所有指向该页面的链接；绝不编辑 website/.generated/、website/.cache/ 或 website/.dist/。有意设置每个 DocsPage 字段，并遵循投影器的链接规则；字段、侧边栏集合和预览命令详见 references/website-sync.md。将内容同步到构建中并不等于发布：部署仍是单独且明确请求的步骤。

详细参考

仅加载任务所需的参考文档。每篇参考文档都可从此文件直接访问，因此技能没有深层参考链。

• 元数据、链接和双语配对：README 前置元数据、kind 系统及其推导方式、描述语义、仓库路径、行对齐和 sidecar 记录。
• 页面结构与层级：强制章节顺序、章节摘要、从用户到开发者的内容进阶、文档树中的位置、小型规则文件、Further Exploration 和 Dev Note 的归属。
• 页面风格：简短摘要、----- 章节分隔符、可折叠内容章节和强调用法规范。
• 审查标准：新手测试、证据核查、软件包 README 审查、参考示例和验证命令。
• 网站发布：清单字段、投影器链接规则、预览与验证，以及部署分离。

templates/ 中的模板为每种 kind 提供一个可用骨架；开始撰写前，请打开文档 kind 对应的模板。

使用 dsh-prose-standard 检查句子级契约覆盖情况并进行编辑判断。session-persistence-jsonl README 配对文件（英文、中文）是参考示例：可搜索的 YAML、Summary 和目录、从用户到开发者的内容进阶（含可折叠的开发者章节）、Further Exploration、规范的 Model Experience 和 Known Limitations 章节，以及最后的 Dev Note。

验证

验证受影响的格式，而不仅仅是 Markdown 语法。对于强有力的承诺，应准备一个有效的专门测试样例，以及一个能证明顶层门禁可以失败的无效样例。

• README 元数据：解析 YAML，将 kind 映射到对应模板和文档规范；拒绝 name、audience、未受规范管理的 tags 和 README 局部的 i18n 元数据；并拒绝缺失描述或广告式描述。
• 双语页面：验证结构、精确行数、术语、链接一致性和 sidecar 记录。
• 教程：测试文档中说明的入口路径，或明确指定人工验证负责人。
• 生成的参考文档：运行确定性的时效性检查，并报告检索大小指标。
• 软件包 README：运行 Summary 门禁，将每篇英文 Summary 限制在 100 个按 wc -w 风格统计的单词以内；若未通过，则引导回到此技能和对应的 kind 模板；运行 model-experience 和 limitation 检查，然后在行为声明发生变化时运行针对软件包的测试；合并相关声明前，重新运行 README 要求执行的每条命令。
• Skills：运行仓库的 skill 调用元数据检查。

运行 pnpm run test:docs，快速全面检查文档（配对、换行、链接、README 门禁、预算、skill 元数据、Agent Note 门禁），然后再完整运行 pnpm run doc-sync。

Dev Note

无。