DeepSeek Harness 的官方文档全在仓库的 docs/ 目录里：171 篇，而且97% 自带官方简体中文版（在英文文件同目录下加 .zh.md 后缀，例如 architecture.zh.md）。问题不在于没有文档，而在于没人告诉你先读哪几篇。这份导读把文档按两条阅读路径组织，并标出三个新手最常卡住的点。
阅读前的一个提醒：项目处于开发者预览期，官方在 README 与 SAFETY.md 里明示会有破坏性变更。任何第三方镜像站转载的文档都可能落后上游——读之前看一眼页面上的提交日期。
用户线：只想把 DSH 用起来
按这个顺序读四篇就够：
- README（en）——
npx @deepseek-ai/dsh web一键启动。 - SAFETY.md（en）——官方要求运行前先读的安全须知。
- 使用 Web UI（en）——界面与日常操作。
- 配置模型（en）——新手卡点 #1。凭证、provider、模型别名三个概念交织，配错的表现是「启动了但没反应」。配完模型再翻插件配置目录（仅英文），它是查配置项时的字典。
开发者线：要写插件或改源码
- 架构总纲（en）——万物皆插件的总体设计。
- Cordis 入门（en）——服务、事件、Fiber 的概念一网打尽。
- Cordis 教程 1–7 章（en）——动手教程，不需要 API key。第 2、3 章是新手卡点 #2：
inject依赖声明与 effect 清理。官方案故复盘 0001 就是一个export default丢掉inject导致的线上事故——读完教程第 3 章再读这篇复盘，理解会深很多。 - DSH 插件开发（en）系列 10 篇——从第一个插件到打包发布。
- Cookbook（en）11 篇——写工具、加设置卡片、接模型适配器的权威参考。
cordis.yml 组合与覆盖层机制是新手卡点 #3：读教程第 6 章（组合与热更新）加上开发环境搭建（仅英文）。
按需查阅的字典（不要顺序读）
docs/subsystems/ 下有 51 篇子系统详解——沙箱、审批、会话、Skills、Webhook、Slot……它们不是教程，是字典：用到哪个子系统查哪篇。两个导航型文档值得收藏：文档图谱索引（仅英文）与术语表（en）。
无中文版的 5 篇（截至 2026-09-17 核实）
docs/AGENTS.md（文档写作规范）、cordis-api/inherited.md，以及 i18n 目录下的 3 篇翻译治理内部文件。其余 166 篇都有官方中文。
关于第三方镜像与版本漂移
社区有镜像站把官方文档转载为多语言网页版（如 dshfind 的文档区，合规地标注了 MIT 出处）。需要知道的两点：其一，官方中文版本来就存在于仓库里，镜像的「中文」并非它自己翻译；其二，镜像钉在固定提交上——我们核实时其钉住的提交落后上游约一个月，缺少若干新增子系统篇目。查最新行为，永远以仓库为准。
FAQ
官方文档有中文版吗？
有，而且是一等公民机制：仓库里 1,646 个 .zh.md 文件，docs/ 下 97% 的文档有官方简体中文版，在英文文件路径的 .md 前加 .zh 即可访问。没有官方日语、韩语版本。
读文档时最应该先避开哪三个坑？
模型配置（providers 文档+配置目录一起读）、inject 依赖声明与 effect 清理（Cordis 教程第 2、3 章+事故复盘 0001）、cordis.yml 组合机制（教程第 6 章）。这三个点也是官方事故复盘和 Discussion 里出问题最多的地方。
文档和实际行为对不上怎么办？
项目周更，破坏性变更是常态。先看仓库的 release 记录与你读的文档提交日期，第三方镜像一律以仓库为准。