跳转至

DeepSeek Harness (DSH) 源码伴读指南

欢迎来到 DeepSeek Harness（简称 DSH） 的中文源码伴读指南。

DeepSeek Harness 是由 DeepSeek 团队研发的新一代生产级 Coding Agent 架构基座。它的核心哲学是 "Everything is a Plugin"（万物皆插件） 与 "What is visible to the model is logged"（模型可见即已记录）。

本指南旨在帮助工程师、架构师和 AI 研究者，从零顺通 DSH 的数十个模块、微内核插件系统、核心 Agent 循环、多智能体编排以及沙箱安全体系。

什么是 DeepSeek Harness？

在开源社区中，大部分 AI Agent 框架（如 AutoGPT、BabyAGI、早期 LangChain）通常采用"单体黑盒循环"或"重型流程编排图"。而 DSH 走了一条截然不同的架构路线：基于 Cordis 框架构建纯粹的微内核插件系统。

在 DSH 中： - 没有特权内核：无论是 LLM 适配器、工具注册表、提示词生成器、会话存储，还是 Agent Loop 循环驱动器本身，全部都是平等的 Cordis 插件（Plugin）。 - 完全可替换与可组合：你可以通过一行配置将默认的 Agent Loop 替换为自定义的状态机驱动器，也可以任意插拔沙箱策略或工具。 - 纯事件溯源（Event Sourcing）：会话日志是唯一真理。模型所见的一切历史记录均从结构化会话事件流中确定性投影得出。 - 工业级多智能体编排：原生支持 subagent（独立子任务与继承式子任务）、workflow（基于 Worker 线程的 JavaScript 声明式流水线编排）以及 ralph（Fresh-Agent 零上下文污染自主迭代飞轮）。 - 三层纵深安全沙箱：内置 OS 原生沙箱（Linux Landlock / macOS sandbox-exec）、文件系统前置观察策略（Fs Observation Policy）与用户交互审批流。

DSH 整体架构全景图

┌─────────────────────────────────────────────────────────────────────────────┐
│                          Applications & Interfaces                          │
│   ┌─────────────────────┐   ┌─────────────────────┐   ┌─────────────────┐   │
│   │     apps/web        │   │      apps/cli       │   │  packages/acp   │   │
│   │ (React + Vite Web)  │   │  (Terminal Runner)  │   │  (Agent Client) │   │
│   └──────────┬──────────┘   └──────────┬──────────┘   └────────┬────────┘   │
└──────────────┼─────────────────────────┼───────────────────────┼────────────┘
               │ Typert RPC (Type-safe)  │                       │
┌──────────────▼─────────────────────────▼───────────────────────▼────────────┐
│                             API & Gateway Layer                             │
│       packages/api/gateway  •  packages/api/remotes  •  packages/sdk        │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
┌──────────────────────────────────────▼──────────────────────────────────────┐
│                    Cordis Microkernel & Context Tree                        │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                            ctx: Context                               │  │
│  │   ├── ctx.sessions      (SessionStore / Append-Only Event Log)        │  │
│  │   ├── ctx.tools         (Scoped ToolRegistry & Execution Pipeline)    │  │
│  │   ├── ctx.agents        (Active Agent Registry & Lifecycle)           │  │
│  │   ├── ctx.agentLoop     (ReactLoop Driver Engine)                     │  │
│  │   ├── ctx.systemPrompt  (Dynamic Prompt Assembler)                    │  │
│  │   ├── ctx.llm           (Multi-Provider LLM Streaming Runtime)        │  │
│  │   ├── ctx.sandbox       (Process Confinement & Permission Manager)    │  │
│  │   ├── ctx.subagents     (Multi-Agent Delegation Registry)             │  │
│  │   └── ctx.workflowEngine(Worker-Thread Orchestration Engine)          │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
┌──────────────────────────────────────▼──────────────────────────────────────┐
│                       Profiles & Bundle Compositions                        │
│   ┌───────────────────┐    ┌────────────────────┐    ┌──────────────────┐   │
│   │     dsh-base      │ ──►│    dsh-web-app     │ ──►│   dsh-headless   │   │
│   │ (Core, Tools, LLM)│    │  (Browser GUI)     │    │ (One-shot CLI)   │   │
│   └───────────────────┘    └────────────────────┘    └──────────────────┘   │
│   Overlay System: cordis.yml -> cordis.patch.yml -> CLI --patch overrides   │
└─────────────────────────────────────────────────────────────────────────────┘

DSH 与主流 Coding Agent 架构对比

架构维度 pi-mono (pi.foril.site) Claude Code / OpenCode DeepSeek Harness (DSH)
内核模型 单向分层单体 (coding-agent → agent → ai) 单体 CLI / 模块化服务 Cordis 微内核（万物皆插件，无特权内核）
扩展机制 事件发射 + 扩展注册表 扩展钩子 (Hooks) 上下文依赖注入 + 声明式 YAML 补丁覆盖 (cordis.patch.yml)
会话历史 数组内存模型，定期摘要 消息数组 + SQLite 严格事件溯源（Event Sourcing），投影生成模型输入
多 Agent 支持 无（仅单 Agent 会话） 简单子进程派生 四重编排：Subagent (独立/继承) + Workflow 脚本 + Ralph 飞轮 + Goal
安全与沙箱 无内置沙箱（依赖外部容器隔离） 基础权限提示 OS 级原生沙箱 (Landlock/sandbox-exec) + Fs 观察守卫 + 动态提权
工具管道 简单函数调用 中间件管道 三阶段拦截：pre-execute → execute → post-execute
前端体系 终端 TUI（差分渲染） 终端 CLI / Web React 现代 Web GUI + Client 插件 HMR 热重载 + Typert RPC

怎么用好这份伴读指南

  1. 对照本地源码阅读： 建议在本地打开克隆的源码目录 /Users/foril/projects/deepseek-harness。指南中所有 packages/xxx/src/yyy.ts:行号 的引用都可以直接在源码中定位。
  2. 按路线图步步推进： 阅读顺序已按认知难度经过严格编排：先搞懂 Cordis 微内核概念，再攻克 Agent Loop 核心循环，继而探索工具沙箱与多 Agent 编排体系。
  3. 带着核心问题阅读： 每个章节开头均列出了"核心问题"和"核心文件速查表（⭐ 评级）"。
  4. 章末自测反馈： 每章末尾配有自测题与设计思考，用于检验是否真正掌握了该模块的精髓。

本地源码参考版本：v0.1.0-rc.8（克隆于 /Users/foril/projects/deepseek-harness）。