源码阅读路线图¶
DeepSeek Harness 代码库包含 50+ 个子包，直接逐个文件通读很容易迷失在细节中。本路线图为你规划了一条从核心到外围、从机制到生态的最优阅读路径。
路线总览¶
第 0 站 建立体感与运行环境 README + 跑起 dsh 实例 0.5h ⭐
第 1 站 Cordis 微内核与组合系统 Context 树、Service、Bundles 2.0h ⭐⭐⭐
第 2 站 Agent Loop 与事件系统 Turn/Step 循环与三大事件域 4.0h ⭐⭐⭐
第 3 站 LLM 抽象与工具执行流水线 流式词汇表、工具管道与沙箱 3.0h ⭐⭐⭐
第 4 站 多 Agent 编排与迭代飞轮 Subagent、Workflow 与 Ralph 3.5h ⭐⭐⭐
第 5 站 上下文工程与全栈架构 Compaction、Spill、Web 与 RPC 2.5h ⭐⭐
─────────────────────────────────────────────────────────────────────────────
总计精读时间：约 15.5 小时；速读路线（仅看 ⭐⭐⭐ 核心章节）：约 6 小时
分站详解¶
第 0 站：建立体感与环境准备（0.5h）¶
- 目标：理解仓库组织结构，体验 DSH 的核心交互。
- 重点文件：
README.zh.md：官方架构设计说明AGENTS.md：代码库守则与包结构划分- 运行命令：
pnpm dsh --profile web --dump-config查看当前机器加载的完整插件配置树。
第 1 站：Cordis 微内核与组合系统（2.0h，基础基石）¶
- 目标：搞清楚什么是"万物皆插件"，插件如何在 Context 树中挂载、注入依赖、并被声明式 YAML 覆盖。
- 对应章节：
- Cordis 微内核架构（⭐⭐⭐）
- Profile 与组合包机制（⭐⭐）
- 核心问题：
- 插件调用
ctx.inject(['sessions'], (ctx) => ...)时，Cordis 如何处理异步服务依赖与拓扑排序？ - 为什么 DSH 可以在不重启服务的情况下热卸载插件，且不会遗留任何内存泄漏和事件监听残留？
cordis.patch.yml如何对深层嵌套的插件配置实现无侵入式替换？
第 2 站：Agent Loop 与三大事件域（4.0h，全书心脏）¶
- 目标：深入理解 DSH 最核心的执行引擎，掌握从 User Message 到 LLM 思考，再到 Tool Call 的完整闭环。
- 对应章节：
- Agent Loop 状态机与驱动（⭐⭐⭐）
- 三大事件域深度解析（⭐⭐⭐）
- 会话日志与投影机制（⭐⭐⭐）
- 核心问题：
- Turn（轮次） 和 Step（步骤） 的严格定义是什么？
- 为什么说
agent/pre-step是一个 Waterfall 事件？它如何实现请求拒绝与消息重写？ - 为什么 DSH 坚持"模型可见即已记录"（What is visible to the model is logged）？
deriveMessages()如何从纯粹的事件流派生出 LLM 输入？
第 3 站：LLM 抽象与工具执行流水线（3.0h，行动能力）¶
- 目标：搞懂 DSH 如何对接各类大模型，以及工具如何安全、受控地在沙箱中执行。
- 对应章节：
- 统一 LLM 抽象与流式处理（⭐⭐）
- 工具流水线与系统提示词（⭐⭐⭐）
- 沙箱隔离与安全防御（⭐⭐⭐）
- 核心问题：
assistant/chunk流式事件如何与最终的assistant/message统一？- 一个工具调用（如
edit或bash）从模型输出到真实落盘，要经过哪些前置守卫（tools/pre-execute）与后置检查（tools/post-execute）？ - Fs Observation Policy 为什么要求 Agent 必须先
read文件才能edit/write？ - 三级沙箱（
read-only/workspace-write/danger-full-access）如何在 OS 层（Landlock / sandbox-exec）落地？
第 4 站：多 Agent 编排与迭代飞轮（3.5h，高阶进阶）¶
- 目标：掌握 DSH 领先业界的四大高级编排范式。
- 对应章节：
- Subagent 子智能体体系（⭐⭐⭐）
- Workflow 声明式脚本引擎（⭐⭐⭐）
- Ralph 迭代飞轮与 Goal 系统（⭐⭐⭐）
- 核心问题：
subagent（独立干净上下文）与subagent_fork（继承父会话上下文）在底层实现上有何区别？- 为什么 DSH 放弃了庞大的 JSON 配置图，转而让 Agent 直接写纯 JavaScript 脚本来驱动
workflow？ pipeline()为什么采用无屏障流转？parallel()与pipeline()的边界在哪？- Ralph 循环如何通过"Fresh-Agent 隔离 + 共享工作区持久记忆 + 结构化报告跨轮传递"解决长程任务中的上下文污染（Context Bleed）难题？
第 5 站：上下文工程与全栈架构（2.5h，工程落地）¶
- 目标：了解生产级 Agent 必备的上下文管理与全栈 Web 架构。
- 对应章节：
- 上下文压缩与 Spill 外溢（⭐⭐）
- MCP / ACP / LSP 扩展协议（⭐⭐）
- 全栈 Web 与 Typert RPC（⭐⭐）
- 核心问题：
- 当工具输出超过阈值时，
spill机制如何将大输出自动截流到磁盘文件并生成安全引用标记？ - Typert 如何自动生成强类型的端到端 RPC 接口？
- Client 端的插件系统如何实现与 Vite / HMR 的无缝热重载？
推荐阅读法则¶
- 核心概念先行：务必先理解 Cordis 的
Context和Service，否则看后面的包会感到"到处找不到直接的 new 或函数调用"。 - 抓主干弃细枝：
- 优先读各包的
src/index.ts（Service 声明与事件注册） - 深入读核心逻辑实现类（如
agent.ts、runner.ts、pipeline.ts） - 忽略辅助工具库和类型声明映射文件
- 善用断言与测试用例：
DSH 代码库单元测试非常完善（
packages/*/test/），阅读测试用例是理解复杂时序逻辑的最快路径。