DeepSeek Harness 项目详解（一）：整体架构与模块地图

DeepSeek Harness（命令名 dsh）解决的是：怎样把一个会调用工具的大模型，组织成可交互、可恢复、可扩展的编程 Agent 系统。 模型产生文本或工具调用，Harness 负责输入排队、上下文构造、实际执行、权限检查、状态记录和界面反馈。

它的核心设计是“一切皆插件”：模型适配器、文件工具、审批、持久化、Web UI，甚至默认 Agent 循环本身，都通过 Cordis 组合起来。理解项目时，应同时看清两个方面：一次任务怎样流动，以及每项能力由谁提供、谁消费。

阅读范围与版本

本系列检查的是本机 deepseek-harness 源码快照，时间为 2026-09-16。

这里的“219 个包”不包含 vendor、apps、native、website 和 Python 分发包，也不表示启动后会同时加载 219 个包。本文介绍本地版本，未将它等同于远端最新版本。本次进行源码与配置静态核验，没有调用真实模型 API，也没有替项目执行完整测试套件。

系列导航

按“全景 → 主链 → 能力 → 产品与目录”阅读最容易建立完整认识。

图中省略部分中间适配器，以展示模块关系；精确行为以正文和固定版本的源码链接为准。

1. 整体架构

图 1：上层入口共享 Agent 服务；工具经统一流水线调用能力。Cordis 管理这些插件的服务依赖与生命周期。非会话 Storage 和 Session Event Log 分别保存不同性质的数据。

把这张图展开，可以得到五个相互配合的部分。

1. 应用入口：Web UI 接收人的输入，Headless 执行一次任务，SDK/ACP 接收其他程序的请求。
2. Agent 主干：管理活跃 Agent 和 Inbox，组装请求，驱动模型与工具交替执行。
3. 能力插件：实现文件、Shell、终端、搜索、LSP、MCP、子 Agent 等操作。
4. 状态与策略：保存会话事件，限制执行权限，管理上下文、目标、审批和恢复。
5. 产品界面与工程支持：把事件投影到浏览器，提供配置编辑、构建、测试与发布基础设施。

这些是便于理解的职责分类，并非五个各自独立的进程。例如 JSONL 持久化和 Web Host 通常运行在 Harness 的 Node.js 进程里；Python SDK 则在另一个进程中通过 stdio 与它通信。

2. Cordis 为什么是项目的基础

2.1 Context：获取服务的入口

插件通常通过 ctx 使用能力，例如：

ctx.agents          创建、查找、恢复活跃 Agent
ctx.sessions        维护内存中的 Session 事件流
ctx.systemPrompt    组装提示词片段和工具定义
ctx.tools           注册与执行工具
ctx.llm             选择模型适配器并处理流式响应
ctx.fs              文件系统能力
ctx.subprocess      子进程与 PTY 基础能力

其中 ctx.agents 定义公开接口，agent-loop 提供默认实现。UI 和扩展插件可以依赖前者，不需要知道默认循环的内部类。这为替换驱动器保留了空间。

2.2 Plugin：把功能与清理放在同一个生命周期

一个插件可以注册服务、工具、提示词片段或事件监听器。注册通过 ctx.effect()、ctx.on() 等机制绑定到插件生命周期；卸载插件时，相应资源需要撤销。

这直接影响实际行为：重新加载插件不能留下重复的工具、旧监听器或无人管理的进程。subprocess、Agent 工厂和后台任务因此都有明确的停止、等待结束和清理逻辑。

2.3 Event：插件参与运行流程的位置

session/event 是“日志已追加”的通知，和被记录的 tool/result 事件不是同一层概念。部分运行事件采用 waterfall：监听器调用 next() 才会继续传给后续监听器；没有调用可能意味着它接管或终止了这条处理链。

2.4 Scope：不同 Agent 看见不同能力

工具和提示词可以按作用域注册。当前 preset 实现的查找关系是：

Agent 自身作用域 → Preset 的常驻作用域 → 全局作用域
                  越近的同名贡献优先

当前实现中，同一个 preset 在一个进程里只挂载一次，多个会话通过作用域父链加入该组合；插件内部仍需按 Session/Agent 区分状态。不能把它理解成“每创建一个会话，就复制并启动一整棵 preset 插件树”。

服务的 Cordis isolate realm 与上述注册作用域也不是同一个概念：前者隔离服务实例，后者控制某个 Agent 可见的贡献。两者配合，避免一个 preset 的服务意外成为全局单例。

依据：架构文档、当前 preset 实现。

3. 看懂一个能力模块：定义、实现、消费方

项目常用 capability seam 表示“可替换能力的接口及其实现关系”。以执行命令为例：

因此，“模型看见的 Bash 工具”和“执行 Bash 的后端”属于不同职责。换用沙箱后端时，通常不需要重写工具的模型接口。

同样的分工出现在 llm、fs、subprocess、web、lsp、subagent、compaction 和 session-persistence。但不是每组包都必须拆成三层：Todo 只是某个会话的一份列表，没有必要凭空创造多个后端接口。

4. 仓库顶层目录

deepseek-harness/
├── apps/cli/       dsh 命令、profile 启动与内置 agent presets
├── apps/web/       浏览器应用的 Vite 入口
├── packages/       49 个模块组、219 个可组合包
├── vendor/         固定版本的 Cordis 等框架源码
├── python/         Python SDK、配套运行时分发与开发说明
├── native/         Landlock 原生启动器及平台分发
├── examples/       可运行的 cordis.yml 示例与回放用例
├── docs/           架构、子系统、用户指南和生成的目录
├── website/        VitePress 文档站
└── scripts/        构建、类型图、文档目录、质量与发布门禁

packages/examples 提供可复用的示例组合包；根目录 examples/ 放加载这些组合的可运行配置，两者层次不同。apps/web 也不是所有 UI 代码的所在地，大部分功能在 packages/client。

5. 49 个模块组的完整地图

以下按职责归类，括号数字是实际包数。第四篇逐包列出 219 个包的职责。

6. 用一个任务串起所有层

假设用户输入：“修复这个项目的登录错误，运行测试，然后说明改动。”下面是解释性示例，并非本次实际执行记录。

1. Web UI 把输入发送给 Host，Host 找到对应 Workspace、Session 和 Agent。
2. 输入以带标识的消息进入 Inbox；Agent 循环准备新轮次。
3. system-prompt 组装工具与提示词；agent-instructions 提供工作区指令，历史从 Session 日志派生。
4. LLM 适配器发送请求，把响应转换成统一的流式块。
5. 模型要求 grep、read 或 lsp；工具注册表检查策略，消费具体能力服务。
6. 修改文件前，文件观察策略检查读过的版本，沙箱检查允许写入的位置；需要人工决定时进入审批流程。
7. bash 通过 Shell 和 Subprocess 运行测试；长任务可能由 Jobs 管理。
8. 每步的消息和工具结果进入日志，再成为下一次请求的历史。上下文过大时，压缩插件参与下一次请求准备。
9. 模型给出结果；没有进一步工具工作或输入时关闭轮次。
10. UI 消费事件和投影，展示回复、工具卡片、状态及产物；持久化插件负责相应落盘。

如果用户只要求查看代码，并不需要启动所有这些模块；图和示例用于解释它们怎样协作。

7. 当前版本最值得注意的边界

这些边界来自对应实现和包说明，详细出处在后续各篇。尤其不要把旧概览里“每会话挂载 preset”“步骤后压缩”等简化说法直接当成当前函数调用顺序。

8. 推荐的源码阅读路线

固定版本入口：源码树、包目录、CLI 入口。这些链接由本地已读取文件与提交号建立，不代表另外核验了远端运行状态。