3.1 dsh-doc：文档结构化与评审

它是什么

dsh-doc 的官方描述是：创建、重构、评审、审计或迁移 DeepSeek Harness 文档。

它是 dsh 团队写文档的主力技能，也是这批技能里体量最大的一份：SKILL.md 约 18418 字节，另带 4 个 references 与 9 个 templates。作为参照，同批技能里体量最小的 agent-experience 只有 70 字节——一个技能可以短到只是一句话，也可以像 dsh-doc 这样自带一整套文档方法论。

注意描述里的五个动词：创建、重构、评审、审计、迁移。它管的不是“写新文档”这一个动作，而是文档的整个生命周期——老文档要重构，写完要评审，定期要审计，结构变化要迁移。这也是它体量大的根本原因：覆盖的场景多，每个场景都要有规矩。

这批技能全部住在 dsh 仓库的 .agents/skills/ 目录，对应六层发现优先级里的 project-agents 层（rank 200）。项目根目录取包含 .git 的最近祖先目录，所以团队成员克隆仓库后自动获得同一套文档规范，不需要每人各自安装、各自维护版本。

它能火不是没有原因：文档工作最难的从来不是“写”，而是结构、层级、元数据、双语同步这些看不见的东西。模型生成文字的速度早就不是瓶颈，瓶颈是生成的文字有没有结构、能不能被检索、双语之间对不对得上——这些恰好都是技能能固定的部分。

九个模板：文档类型决定结构

官方记录 templates 目录共 9 个模板，覆盖包文档、持久化文档与升级指南三大场景。下表逐个说明其中八个的名称与对应文档类型——名字本身就说明了用途：

模板 对应文档类型 固定下来的内容
package-bundle.md 组合包文档 组合包的组成与装配说明
package-group.md 包组文档 一组相关包的总览与导航
package-library.md 库文档 面向使用者的 API 说明
package-reference.md 参考包文档 字段、配置项等查阅型内容
persistence-change.md 持久化变更记录 一次存储相关变更的记录格式
persistence-format.md 持久化格式说明 数据落盘的格式与约束
persistence-release.md 持久化发布说明 发布涉及存储层时的说明
upgrade-guide.md 升级指南 破坏性变更的迁移步骤

已记录名称的八个分属三条线：package 系四个，管包类文档怎么写；persistence 系三个，把存储相关文档拆得最细——变更、格式、发布各管一段，因为持久化改动直接影响老数据能不能被新版本读出，混在一篇里写必丢信息；upgrade-guide 一个，专治破坏性变更。

九个模板对应九种文档类型。这意味着“该写什么、按什么顺序写、每节放什么”是被固定下来的，不靠作者临时发挥。写库文档的人不会漏掉 API 说明，写升级指南的人不会被漏掉迁移步骤——模板先行的价值就在于此。

四个 references 的分工

参考文件 分管领域 为什么单独拆出
metadata-links-i18n.md 元数据、链接与国际化 标题、描述、kind 字段和跨语言链接是高频出错点，值得独立规则
review.md 评审要点 文档写完要走一轮评审，不是写完就发布
structure-hierarchy.md 结构与层级 目录怎么组织、父子页面怎么分层
style.md 文风 文字质量标准，与 dsh-prose-standard 同源

主指令负责流程与判断，四个 references 各管一个专项。这种“主文件 + 专项参考”的结构本身就是技能组织的范式：SKILL.md 保持可读，细节按需加载，改规则时也知道该改哪一份。

其中 metadata-links-i18n.md 的存在特别值得抄。元数据和链接的问题有个共同点：不出在正文里。正文写错了评审时能看出来，标题写错、kind 标错、双语链接指错语言版本，评审时根本想不起来查。把它单独拆成一份参考，等于给这类隐形问题一个固定的检查入口。

大技能为什么不会拖慢会话

有人看到 18418 字节就担心：每次会话都背着这么一大篇？不会。skill 的官方定位是可选的指令而非会话事件：模型可调用的会话目录只使用 name 与 description，从不使用正文；正文要等模型判断任务相关、主动调用 skill 工具，或用户输入 /技能名 时，才完整加载。宿主也不会根据文件扩展名把 references 和 templates 一股脑塞进上下文。

所以技能可以放心做得深——入口必须小，内容可以厚。写 description 时把“什么时候该用我”说清楚，比堆正文更重要。

什么时候会触发它

场景 技能做什么
新建一个包，要写它的文档 按对应模板起手，该有的节一节不缺
老文档结构混乱，要重构 先过结构层级的规则，再动内容
改了存储格式 走持久化三件套：变更记录、格式说明、发布说明
发布了破坏性变更 按升级指南模板列迁移步骤，不靠用户自己猜
定期巡检 拿元数据与链接的规则审计存量文档

对个人作者的启发是：写文档前先花十秒选模板。这十秒省的是写完发现结构不对、推倒重来的半小时。

值得你抄走的三条方法

第一条：文档类型决定模板。 不要用一套结构写所有文档。参考包、库、组合包的读者预期完全不同：查参考的人要精确字段，读库文档的人要能照着跑的示例。模板先行能避免“写着写着跑偏”。落地做法很简单：建一个 templates/ 目录，每类文档一个文件，新建文档时先复制模板再填内容。

第二条：元数据与链接单独成篇。 元数据（标题、描述、kind 字段）决定文档能否被正确检索和索引，跨语言链接决定双语站点不出现断链。这两类问题不出在正文里，最容易被忽略，所以值得独立规则、独立检查。落地做法：写一份元数据检查清单，每次发布前逐项过。

第三条：评审是独立环节。 review.md 单独存在，意味着文档流程里有明确的一环是“写完先评再发”。把评审从写作里拆出来，写的人敢收尾，看的人有据可查。落地做法：文档类改动也走评审流程，清单照 review.md 的思路列，哪怕只有五条。

你要不要装

你的情况 建议
维护技术文档站 / 知识库 强烈建议，直接改造使用
团队有文档规范 建议，用来把规范变成可执行清单
只是偶尔写个 README 不必，杀鸡用牛刀

判断标准很简单：你一年写超过十篇需要他人阅读的文档，就值得装；低于这个数，模板带来的收益抵不过维护成本。

怎么改造成你的版本

# 取过来（路径按你的克隆位置调整）
cp -r /path/to/dsh/.agents/skills/dsh-doc ~/.dsh/skills/my-doc

放 ~/.dsh/skills/ 属于用户层（rank 400），对所有项目生效；只想给单个项目用，就放进项目的 .agents/skills/（rank 200），随仓库走，队友克隆即得。

然后改三处：

  1. description 里的“DeepSeek Harness 文档”换成你的项目名——description 是模型唯一必读字段，决定技能能否被选中。改写时保留原来的动词结构： text 改前：创建、重构、评审、审计或迁移 DeepSeek Harness 文档 改后：创建、重构、评审、审计或迁移 XX 项目的技术文档
  2. 删掉你不需要的模板，保留三五个最常用的；模板越少，作者越容易选对；
  3. references/structure-hierarchy.md 里换上你的目录约定。

改完验证一下：新起一个会话，让它“按规范写一份 XX 文档”，看它是否主动调用你的技能；也可以直接输入 /my-doc 强制加载，检查清单和模板是否按预期工作。

小结

  • dsh-doc 是 dsh 团队的文档主力技能：主指令约 18418 字节 + 4 份参考 + 9 个模板。
  • 核心方法：文档类型决定模板、元数据与链接独立规则、评审独立成环节。
  • 技能入口小、内容厚，靠渐进加载不拖慢会话。
  • 维护文档站的人强烈建议改造使用；偶尔写 README 不必。

延伸阅读