Bin-hy/dsh

DSH 深度拆解

DeepSeek Harness 深度剖析 · 源码级中文学习资料

在线阅读 → deepseek-docs.pages.dev

一句话介绍

一份源码级的 DeepSeek Harness 中文学习资料：从 Cordis 插件框架到 Agent Loop 状态机，从工具执行管道到多代理编排，把 219 个包的 monorepo 拆成 15 篇可读文章、12 个可迁移设计模式、28 道面试题。

DeepSeek Harness 是 DeepSeek 开源的生产级 Agent Harness（Claude Code / Codex CLI 同类产品的底层引擎）。它的设计哲学浓缩为一句话：

事件流 + 可逆副作用 = 全部控制流。
循环本身没有特权——策略以监听器身份挂在事件上，能力以提供方身份挂在服务 seam 上。

英文摘要：对 DeepSeek Harness 的源码级深度剖析，这是 DeepSeek 出品的基于插件的 agent harness。15 篇深度文章阐释了其事件溯源会话日志、turn/step 状态机、工具执行管道、沙箱（Landlock）、上下文工程（compaction/spill）、多代理编排（subagent/workflow/goal）、流式 LLM 层，以及基于插件的 Web GUI——包含真实的类型定义、代码路径、设计权衡，以及面向 agent 工程岗位的面试题。内容为中文。

✨ 为什么值得 Star

| | |
|---|---|
| 🧩 源码级证据 | 每一篇都标注 文件路径:行号，可直接回溯到 deepseek-harness 仓库对应代码 |
| 🏗️ 系统化拆解 | 15 篇文章覆盖从插件框架到 Web GUI 的完整架构，不是零散笔记 |
| ⚖️ 讲权衡，不讲名词 | 每个设计都回答"为什么这样设计 + 放弃了什么"，面试官最想听的正是这个 |
| 🎯 面向求职 | 12 个可迁移设计模式（每条带面试话术）+ 28 道高频题 + 扩展实战 |
| 🎨 在线可读 | VitePress 站点部署于 Cloudflare Pages，全文搜索 + 代码高亮 + 目录导航 |

📖 内容地图

导读（3 篇）

- 为什么研究 DSH — 项目定位与学习它的四个理由
- 核心概念速览 — Cordis、事件、seam、scope、turn/step 术语表
- 架构总览 — profile/bundle 组装、40+ 服务地图、轮次流程

深度拆解（8 篇）

| # | 章节 | 核心内容 |
|---|---|---|
| 01 | 核心循环：Agent Loop | turn/step 状态机、inbox 队列、waterfall 拦截、工具调度 barrier/滚动池 |
| 02 | 工具系统与执行管道 | 九段流水线、双轨策略（瀑布+单调守卫）、类型安全 schema DSL |
| 03 | 沙箱与权限 | Landlock 自限制 launcher、审批升级、权限预设 |
| 04 | 上下文工程 | prompt 组装、compaction（日志事件即锁）、spill、token 计量、技能系统 |
| 05 | 多代理编排 | subagent 六种 Provider、受限 JS workflow、jobs、goal 循环 |
| 06 | LLM 层与流式管道 | StreamChunk 协议、BlockAssembler、重试持久化、凭据只存引用 |
| 07 | Web GUI 与 API 层 | 插件化浏览器 Cordis、双 WS 流、增量折叠、Typert RPC |
| 08 | 持久化与工程化 | 219 包 monorepo、双 face 构建、vendored 框架修改日志 |

面试冲刺（2 篇）

- 设计模式手册 — 12 个可迁移模式：事件溯源日志、能力 seam、失败类型化、有界委托……
- 高频面试题 — 概念/源码/系统设计/场景四类共 28 题

实战（1 篇）

- 扩展 DSH：加一个工具 — 五步验证流程 + 技能编写 + 进阶路线图

🏗️ 架构全景图

flowchart TB
subgraph 组合平面["组合平面 · 静态"]
Profile["profile(web / headless)"] --> Bundle["bundle 层(dsh-base → dsh-web-app)"]
Bundle --> Patch["cordis.patch.yml+ --patch overlay"]
end

subgraph 运行平面["运行平面 · 动态"]
Driver["Agent Loop 驱动器(turn/step 状态机)"]
Driver -->|"agent/pre-step"| PreStep["拦截链(compaction / 技能 / 指令)"]
PreStep -->|"agent/request"| LLM["ctx.llm 流式管道"]
LLM -->|"assistant/chunk*"| Log["SessionEvent 日志(唯一真源)"]
Driver -->|"tools/pre→execute→post"| Tools["ctx.tools 执行管道"]
end

subgraph 能力平面["能力平面 · seam"]
Seam["Service Definition + Provider + Consumer"]
Seam --- S1["ctx.shell / ctx.subprocess"]
Seam --- S2["ctx.fs / ctx.sandbox"]
Seam --- S3["ctx.subagents / ctx.workflowEngine"]
Seam --- S4["ctx.llm / ctx.web / ctx.skills"]
end

Patch --> Driver
Tools --> Log
S1 & S2 & S3 & S4 --> Tools

🔬 Roadmap

深度拆解持续更新中。全部待深挖项整理在 research/backlog.md（56 条存疑项 → 12 个文章聚类）：

| 状态 | 计划 |
|---|---|
| ✅ 已发布 | 01~16 + 五篇补遗，共 26 篇；12 个主聚类全部消化 |
| 🔬 研究中 | 第二轮存疑项（消化过程中新发现的 20 条，见 backlog） |

🚀 快速开始

git clone https://github.com/Bin-hy/dsh.git
cd dsh
npm install
npm run dev        # http://localhost:5173/
npm run build      # 输出 docs/.vitepress/dist

☁️ 部署（Cloudflare Pages）

本站在 Cloudflare Pages 上部署（https://deepseek-docs.pages.dev）：

构建命令   npm run build
输出目录   docs/.vitepress/dist
环境变量   NODE_VERSION: 22

无需任何自定义配置——仓库 push 到 main 后 Pages 自动构建发布。

🗺️ 学习路线建议

第 1 天  导读 3 篇          —— 建立心智模型（Cordis、事件、seam）
第 2 天  核心循环 + 工具系统 —— 理解 Agent 的"心跳"
第 3 天  上下文 + 多代理编排 —— 理解 agent 的"记忆"与"协作"
第 4 天  LLM 层 + Web GUI   —— 理解数据如何流动
第 5 天  面试冲刺 + 实战扩展  —— 输出自己的理解

📚 研究底稿

research/ 目录保存了 6 份原始研究笔记（约 4,000 行），是博客文章的素材底稿：

research/
├── 01-core-loop.md       核心循环与运行时
├── 02-tools-sandbox.md   工具系统与沙箱
├── 03-context-skills.md  上下文工程与技能系统
├── 04-orchestration.md   多代理编排
├── 05-llm-streaming.md   LLM 层与流式管道
└── 06-web-gui.md         Web GUI 与 API 层

每份笔记都包含：概念地图、模块与文件地图、真实类型定义（带 文件:行号）、执行流程、设计权衡、面试要点与诚实标注的存疑项。

🤝 贡献

欢迎以任何形式贡献：

- 纠错：任何与源码不符的表述，直接提 Issue 或 PR
- 补全：研究笔记中的 50+ 条存疑项是现成的深挖清单（如 E2B 远程沙箱、ACP 进程外传输）
- 翻译：英文版的翻译贡献非常欢迎

📄 License

本仓库中原创内容（博客文章、研究笔记、代码）采用 MIT License 开源。

本项目是对 DeepSeek Harness 的独立学习笔记，非官方文档；DSH 本身遵循其自身的 MIT License，文中引用均以学习研究为目的。

🙏 致谢

感谢 DeepSeek 开源 DeepSeek Harness——它把 agent 工程的共识最佳实践以生产级质量落地，是绝佳的学习范本。

如果这份资料帮到了你，请点个 Star ⭐，让更多人看到它。