从跑起来，
到读懂它。
DeepSeek Harness 是一个「一切皆插件」的开源 agent harness，跑在 Cordis 框架上。
这份指南带你从第一次启动 dsh，到顺着 turn flow 读懂插件化架构，
再到动手写第一个扩展、加入社区。路线图进度会保存在你的浏览器里，随时可以接着学。
# 三分钟跑起来（Node.js ^22.19 或 >=24）
$ git clone https://github.com/deepseek-ai/deepseek-harness.git
$ cd deepseek-harness && pnpm install && pnpm run build
$ pnpm dsh web # → http://127.0.0.1:3080
先建立心智模型
读这个仓库之前，先记住三句话。它们解释了几乎所有设计决策， 也是你在代码里反复遇到的三个模式。
一切皆插件
没有特权核心：模型适配器、工具注册表、会话日志、agent loop 本身都是插件，全部可在 cordis.yml 中替换。扩展 = 在树里挂一个新插件；注册 = 可逆的 effect，插件卸载时自动回收。
能力缝隙三角色
一个可替换能力 = Service Definition（接口）+ Service Provider（实现）+ Consumer（使用者）。shell / fs / llm / subagent 都是这个模式——换一个 provider，整个产品的能力随之切换。
模型可见即可日志重建
凡是进入模型请求的内容，必须能从 session 事件日志重建。只增的 SessionEvent 日志是全仓库的中心：fork、resume、transcript、telemetry 都从这条流派生。
主线剧情：一次 turn 的生命周期
一个 step 是一次模型请求加上它调用的工具；一个 turn 是零到多个 step。
下面这张交互式流程图来自 docs/architecture.md 的 Turn flow，
点击每个阶段看它在做什么——读代码时把调用链往这条主线上挂，就不会迷路。
五步学习路线
按顺序执行，每完成一步就勾掉它（进度存在本地浏览器）。 总计约 2–3 天的精读时间，之后你就可以独立探索了。
没有上下文的通读效率最低。先把系统跑起来，触发一次核心流程，再带着问题去读代码。
- 启动 Web UI，像普通用户一样玩一会儿
- 用 headless profile 跑一次无头任务
- 用
--dump-config看你机器实际启动的插件树——任何一行都能被你自己的 patch 替换
pnpm install && pnpm run build && pnpm dsh webpnpm dsh --profile headless "帮我总结这个仓库"dsh --profile web --dump-config先建词汇表，再看代码。这三篇是官方指定的入口，读完你就掌握了全仓库 80% 的关键概念。
docs/development.md— 开发指南：命令、目录布局、测试政策docs/cordis-primer.md— Cordis 入门（想更系统就看docs/cordis-tutorial/）；不懂 Cordis 读不懂这个仓库docs/architecture.md— 架构文档，改packages/前必读；里面的 Turn flow 图是整个系统的主线
不要按目录通读。按架构文档里的核心包表，沿 turn flow 的顺序读，每个子系统配 docs/subsystems/ 下的对应文档。
packages/core/session— 只增的 SessionEvent 日志，一切的源头packages/core/agent+core/agent-loop— Agent 接口与默认驱动packages/core/tools— 工具注册表与执行管线packages/core/system-prompt— prompt 段落与工具 schema 组装packages/llm/llm— 消息/流式词汇表与模型适配器缝隙
能给项目加一个真实可用的小功能，才算读懂了。docs/cookbook/ 就是为此准备的。
- 照
docs/cookbook/adding-a-tool.md加一个自己的 tool - 进阶：
adding-an-llm-adapter.md接一个自己的模型 - 系统学扩展点：
extension-cookbook.md、adding-a-package.md - 平台方向：
adding-a-remote-api.md（经ctx.remote给远程客户端开 Remote API）、adding-a-session-format-version.md（演进会话日志格式）
代码告诉你 what，决策记录告诉你 why 和「为什么不那样做」。这是这个仓库最特别的学习资源。
.agents/notes/implemented/— Agent Notes：按 architecture / process / testing 分类的设计决策记录docs/postmortem/— 真实故障的事后分析docs/glossary.md— 术语表，读代码卡壳时回来查
覆盖整条路线的 42 道面试式问答：先自己作答，再点击展开对照答案。
11 课 × 30 分钟：每课 20 分钟图解精读 + 10 分钟即时批改练习（单选 / 多选 / 问答），从会用、读懂、会改到维护者视角。
可复用的开源学习方法论
这八条方法从这个仓库提炼出来，放到任何一个成熟开源项目上都适用。
先跑后读
把项目跑起来、触发一次核心流程，再带着具体问题读代码。没有上下文的通读效率最低。
先建词汇表
每个成熟项目都有自己的术语（turn / step / seam / bundle / profile）。先读 glossary 和架构文档，把词汇和代码实体对上，之后读代码只是填细节。
追一条端到端主线
选一个核心场景（发一条消息到收到回复），顺着调用链追完。主线通了，分支都是挂上去的。
找「生成的地图」
机器生成的索引是定位代码的最快路径：module-graph、event-producer-consumer（每个事件谁生产谁消费）、tool-catalog、config-catalog。
把测试当行为规格读
snapshot / e2e 测试告诉你「系统对外应该长什么样」，比实现代码更稳定，也更能经得起重构。
读决策记录，不只是代码
代码是 what，ADR / Agent Notes / postmortem 是 why。判断一个项目值不值得深入，看它的决策记录质量就知道。
用一个小改动验证理解
能给项目加一个无关紧要但真实可用的小功能，才算读懂了。cookbook 类文档价值最高就是这个道理。
用 agent 辅助探索
架构文档自己就推荐这么做——让 AI 帮你定位、总结、画调用链，你负责提问和验证。
加入社区
社区入口分中英文两圈。想被社区认识，最快的方式不是提问，
而是用 cookbook 写一个小插件并挂到 dsh-plugin topic 上。
官方指定的反馈、bug 报告与讨论渠道，也是潜水观察「大家在关心什么」的最佳起点。
Discord ↗英文实时交流社区，适合问快速问题、跟踪日常迭代。
dsh-plugin topic ↗社区插件的集散地。刷这个 topic 看别人做的扩展；给自己的插件仓库加上它就能被发现。
企微群入群问卷 ↗中文圈主阵地：扫下方小助手二维码并填写问卷，小助手会邀请你加入企微群。
建议的参与节奏
- 先潜水两周：读 GitHub Discussions、Discord / 企微群，摸清大家在关心的问题
- 用
docs/cookbook/写一个自己的小插件 - 给插件仓库挂上
dsh-plugintopic 发布——这是被社区认识最快的方式 - 想从学习走向贡献时，读仓库根目录的
CONTRIBUTING.md
资源速查
仓库内的关键路径，按用途分组。点击任意路径即可复制。