Bin-hy/dsh
源码级拆解 DeepSeek Harness · 面向 Agent 开发者的中文学习资料
安装Install
dsh plugin --profile web add github:Bin-hy/dsh把 Bin-hy/dsh 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
一句话介绍
一份源码级的 DeepSeek Harness 中文学习资料：从 Cordis 插件框架到 Agent Loop 状态机，从工具执行管道到多代理编排，把 219 个包的 monorepo 拆成 15 篇可读文章、12 个可迁移设计模式、28 道面试题。
DeepSeek Harness 是 DeepSeek 开源的生产级 Agent Harness（Claude Code / Codex CLI 同类产品的底层引擎）。它的设计哲学浓缩为一句话：
事件流 + 可逆副作用 = 全部控制流。
循环本身没有特权——策略以监听器身份挂在事件上，能力以提供方身份挂在服务 seam 上。
An English abstract: A source-level deep dive into DeepSeek Harness, the plugin-based agent harness from DeepSeek. 15 in-depth articles explain its event-sourced session log, turn/step state machine, tool execution pipeline, sandbox (Landlock), context engineering (compaction/spill), multi-agent orchestration (subagent/workflow/goal), streaming LLM layer, and plugin-based web GUI — with real type definitions, code paths, design tradeoffs, and interview questions for agent engineering roles. Content is in Chinese.
✨ 为什么值得 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 篇）
实战（1 篇）
- 扩展 DSH：加一个工具 — 五步验证流程 + 技能编写 + 进阶路线图
🏗️ 架构全景图
flowchart TB
subgraph 组合平面["组合平面 · 静态"]
Profile["profile<br/>(web / headless)"] --> Bundle["bundle 层<br/>(dsh-base → dsh-web-app)"]
Bundle --> Patch["cordis.patch.yml<br/>+ --patch overlay"]
end
subgraph 运行平面["运行平面 · 动态"]
Driver["Agent Loop 驱动器<br/>(turn/step 状态机)"]
Driver -->|"agent/pre-step"| PreStep["拦截链<br/>(compaction / 技能 / 指令)"]
PreStep -->|"agent/request"| LLM["ctx.llm 流式管道"]
LLM -->|"assistant/chunk*"| Log["SessionEvent 日志<br/>(唯一真源)"]
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 ⭐，让更多人看到它。
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …
-
nocobase/nocobase
NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything fr…