夜雨聆风技术文档治理的最高纪律：像控制代码单测一样控制文档坏链，像管理云资源配额一样给文档设定硬性字数预算。
一、现实痛点：技术文档的“中年危机”与信息熵增
在很多长期演进的开源项目与企业代码库中，技术文档往往会陷入不可逆的“中年危机”：
- 翻车场景一：文体严重混乱（Mixed Forms）
- 通俗类比
：就像新手刚进一家餐馆想看“今日推荐菜单”，服务员却直接递过来一本 500 页的《食品原料国家安全标准与猪肉冷链运输规范》。 - 现实映射
：在原本面向新手的「入门快速指南（Getting Started）」里，硬塞了几千字的底层并发锁实现机制与几十个边缘错误码字典，新手还没跑通 Demo 就已被劝退。 - 翻车场景二：复制粘贴泛滥，事实割裂（Doc Drift）
同一个架构原理或事件格式，在 10 几个 Markdown 文件里各复制了一份。代码重构后，开发者改了其中的 3 个，遗漏了另外 7 个，导致全仓文档自相矛盾、真假难辨。 - 翻车场景三：篇幅无限膨胀，成为信息垃圾场（Doc Slop）
没有字数约束，单篇文档随心所欲地膨胀到数万字，充斥着过期的讨论草稿与会议流水账，没人能通读，也没人敢维护。
DeepSeek Harness（DSH）确立了 dsh-doc-standards 技能：把文档当成代码一样进行静态编译检查，通过「文体双轨分治」、「单一事实来源」与「硬性字数预算门禁」，从根本上遏制文档熵增。
二、文档文体的两极分化：Tutorial vs Reference 双轨分治
DSH 严格禁止将“引导式教程”与“字典式手册”混写在同一篇文档中，确立了清晰的双轨分流模型：
┌─────────────────────────────────────────┐
│ 全仓技术文档体系 (Docs Hierarchy) │
└────────────────────┬────────────────────┘
│
┌────────────────────────────────┴────────────────────────────────┐
▼ ▼
┌─────────────────────────────────────────┐ ┌─────────────────────────────────────────┐
│ 1. 教程型文档 (Tutorials / Cookbooks) │ │ 2. 参考型文档 (References / Specs) │
├─────────────────────────────────────────┤ ├─────────────────────────────────────────┤
│ • 读者定位：明确初级/进阶水平 │ │ • 读者定位：面向精准查阅与配置速查 │
│ • 阅读模式：严格按时间时序单向推进 │ │ • 阅读模式：支持无序随机访问 (Random) │
│ • 终点目标：产出一个可观测的结果 (Demo) │ │ • 终点目标：给出穷尽的字段/错误类型字典 │
│ • 严禁行为：原地展开底层参数字典 │ │ • 引用规范：作为底层事实，被教程链接引用│
└─────────────────────────────────────────┘ └─────────────────────────────────────────┘
│ │
└────────────────────────────────┬────────────────────────────────┘
▼
┌─────────────────────────────────────────┐
│ 底部门禁：字数预算与坏链自动拦截 (CI) │
└─────────────────────────────────────────┘
教程型 vs 参考型核心对照表
| 核心受众 | ||
| 阅读路径 | 线性单向流（Step-by-step） | 随机点状查阅（Random Access） |
| 交付产物 | 一个可观测的成功状态 | 一套完备的客观事实 |
| 底层原理处置 | 严禁原地长篇大论 | 作为单一权威事实源 |
三、单一事实来源（Single Source of Truth / SSOT）
为了彻底根除“同一原理解释到处复制粘贴导致的事实漂移”，DSH 执行严苛的 一事一地（One Home Per Fact） 原则：
1. 唯一权威归宿
整个仓库中，关于某个核心机制、架构设计或配置项的完整命题，只能由一个权威 Markdown 文件承载。全仓其他所有提及该概念的地方，一律只能通过相对路径 Markdown 链接指向该权威文件。
2. 自动化坏链与跨文件锚点门禁（CI 强制拦截）
在 DSH 的预推检查中，集成了自动化文档验证工具：
# 1. 扫描全仓所有 Markdown 相对链接与 #heading-slug 锚点有效性
pnpm run verify-md-links
# 2. 扫描 TypeScript 源码注释中引用的 docs/*.md 路径是否真实存在
pnpm run verify-doc-refs
- 原子化重构
：一旦某个文档被重命名或章节标题修改，CI 会直接报出红灯并列出所有失效的相对链接与锚点，强制要求全仓所有引用必须在同一个 Commit 中原子修复！
四、文档字数预算门禁（verify-doc-budgets）
这是 DSH 在大型 Monorepo 治理中最具前瞻性的创新之一：给核心技术文档设定硬性「字数预算上限（Budget Ceiling）」。
# 检查全仓核心文档是否超过字数预算上限
pnpm run verify-doc-budgets
文档字数预算监控示例
AGENTS.md | ||||
docs/architecture.md | ||||
docs/testing.md | ||||
docs/defensive-patterns.md | 1,350 词 |
当字数预算超限时的「三级处置阶梯」：
[ CI 字数预算超限告警 (Over Budget) ]
│
▼
┌────────────────────────────────────────────────────────┐
│ 【优先级 1: 细节外迁 (Relocate)】 │
│ 将非核心的深入细节拆分到子模块文档中，使用链接引用 │
└─────────────────────────┬──────────────────────────────┘
│ (若无法外迁)
▼
┌────────────────────────────────────────────────────────┐
│ 【优先级 2: 语言凝练 (Condense)】 │
│ 应用 dsh-prose-standard 剔除空洞废话与流水账叙述 │
└─────────────────────────┬──────────────────────────────┘
│ (若已极度凝练仍超限)
▼
┌────────────────────────────────────────────────────────┐
│ 【优先级 3: 严格论证申请上调 (Raise Budget)】 │
│ 论证该文档确实承载了全新核心架构事实，方可修改配置上限│
└────────────────────────────────────────────────────────┘
- 优先级 1：细节外迁（Relocate）
—— 将过于深入的实现细节拆分到子文档，在主文档保留 1~2 句话总结并加链接； - 优先级 2：语言凝练（Condense）
—— 按照 dsh-prose-standard剔除形容词、历史过程叙述与无效修饰； - 优先级 3：严格论证后上调（Raise Budget）
—— 只有当确实合入了重大新子系统时，才允许在配置文件中提升该文档的预算数值。
五、工程启示与落地指南
- 像编译代码一样编译文档
将文档坏链（Broken Links）和失效锚点纳入 CI 门禁，杜绝“代码跑通了，文档全指空”的尴尬。 - 文体分离是抗击熵增的第一道防线
永远不要让教程变成手册，教程负责“带新手跑通”，手册负责“给老手查阅”。 - 给文档引入「资源配额」管理思维
通过设定字数预算，倒逼工程师和 AI 持续重构、凝练文字，防止文档沦为无法维护的信息垃圾场。 
💡 下期预告：
很多团队会写架构决策记录（ADR），但三年前过时的旧 ADR 该如何处理？直接修改历史决策会导致上下文丢失，放任不管又会误导新人。
下一篇我们将拆解dsh-archive-agent-notes，看 DeepSeek 如何用「状态机迁移」与「SHA-256 只增清单哈希密封」，让历史决策具备不可篡改的法律级存证效力！欢迎「关注」专栏并设为「星标」🌟，第一时间获取硬核工程深度解析！如果本文对你有启发，请点个「在看」与「赞」支持一下！