分析基于代码库 deepseek-ai/deepseek-harness（版本 0.1.0-rc.5，MIT 协议） 仓库地址：https://github.com/deepseek-ai/deepseek-harness

一、项目介绍

DeepSeek Harness（简称 dsh）是由 DeepSeek AI 开发并开源的 Agent 运行时框架（agent harness）。它是一个"用来构建 AI 智能体（Agent）的基础设施层"：负责把大语言模型（LLM）、工具调用、文件系统、进程执行、多智能体协作、会话持久化、沙箱安全等能力编排成一个可运行、可扩展的完整 Agent 系统。

它的核心设计理念只有一句话：

一切皆插件（Everything is a plugin）。

整个产品——包括模型适配器、工具注册表、会话日志、甚至 agent loop（智能体主循环）本身——都是插件，运行在由开源社区框架 Cordis 支撑的插件树之上。不存在一个"需要打补丁的特权内核"：任何能力都可以从配置文件层面整体替换。

基本事实

项目说明
名称DeepSeek Harness（dsh）
开发者DeepSeek AI
许可证MIT
语言TypeScript（主体）、Rust（Landlock 沙箱）、Python（SDK）
运行时Node.js ≥ 22.19
包管理pnpm workspace monorepo（约 50 个包）
状态Developer preview（快速迭代，存在破坏性变更）
启动方式npx @deepseek-ai/dsh web，默认 Web UI 地址 http://127.0.0.1:3080
界面形态Web GUI（React）、Headless 一次性运行、TUI、Python SDK、ACP 协议接入

设计哲学：为什么"一切皆插件"？

传统 Agent 框架往往有一个"内核 + 扩展点"的结构：内核代码不可替换，只能在预留的钩子上做文章。DeepSeek Harness 反其道而行——它把框架自身也写成插件：

  • 没有特权内核可打补丁，扩展方式就是"在别的插件旁边挂一个插件"；
  • 所有注册都是可逆副作用（reversible effects），插件卸载时注册自动撤销；
  • 服务之间通过 ctx.（如 ctx.llm、ctx.tools、ctx.sessions）按接口寻找，而不是直接 import 具体实现；
  • 依赖关系通过 inject 声明，加载顺序由"服务依赖"自动推导，而非手写启动序列。

二、文件结构分析

顶层布局

deepseek-harness/
├── apps/          # 可交付应用
│   ├── cli/       # 命令行入口（`pnpm dsh web` 的 bin.ts）
│   └── web/       # Web 前端（Vite + React，浏览器 GUI）
├── packages/      # 约 50 个核心包（按领域分组的 monorepo）
├── native/        # 原生代码（landlock-run：Linux 沙箱启动器，Rust）
├── python/        # Python SDK 与运行时（uv + hatch 构建）
├── vendor/        # 内置的 Cordis 生态（cordis、cosmokit、loader 等）
├── docs/          # 双语文档（英/中），含架构、子系统、教程、复盘
├── website/       # 文档站点（VitePress）
├── scripts/       # 构建/校验/发布脚本
├── examples/      # 示例（含 ACP Agent 示例）
├── assets/        # 资源文件
├── patches/       # 依赖补丁
├── .github/       # CI、issue 管理
├── package.json   # 根包（pnpm workspace 定义 + 全部脚本）
├── pnpm-workspace.yaml
├── tsconfig*.json # 多套 TS 工程（host/client 两面）
├── vitest*.config.ts  # 单元 / e2e / 快照 / Web / 性能 / 压测 六套测试配置
├── tsdown.config.ts   # 构建器
└── BENCHMARK.md / AGENTS.md / CLAUDE.md / CONTRIBUTING*.md

packages/ —— 按领域拆分的核心包

packages/
├── core/         # 循环核心
│   ├── agent/           # Agent 接口、活跃注册表、agent/* 事件
│   ├── agent-loop/      # 默认驱动器（turn/step 主循环）
│   ├── agent-default-model/  # 默认模型选择
│   ├── agent-tool-presentation/
│   ├── scope/           # 按 agent 隔离的注册原语
│   ├── session/         # 仅追加的 SessionEvent 日志
│   ├── system-prompt/   # 提示词片段 + 工具 schema 组装
│   └── tools/           # 作用域化工具注册表 + 把关执行流水线
├── llm/          # llm/：消息/流式词汇表与适配器 seam（ctx.llm）
├── bundle/       # 分发层：base / web-app / headless 三种组合包
├── boot/         # app-boot：profile 与 bundle 的装配机制
├── fs/           # 文件系统 seam（FsTarget、read/write/edit 结果）
├── shell/ subprocess/ terminal/   # 执行能力 seam
├── sandbox/ guard/ approval/      # 安全与审批
├── subagent/ workflow/ goal/ jobs/# 多智能体与任务编排
├── session-query/ compaction/ persistence/ storage/  # 会话数据
├── mcp/ acp/ lsp/ api/            # 协议接入
├── e2b/          # E2B 远程沙箱 POC（fs-e2b、subprocess-e2b）
├── web/ host/ client/ typert/     # 前端/宿主/客户端通信（Typert RPC）
├── skill/ schedule/ plan/ todo/ feedback/ interaction/  # 功能插件
└── test-support/ examples/ util/  # 支撑包

每个包自带 README.md（中英双语）和文档，docs/subsystems/ 下约 50 个页面逐一对应。

vendor/ —— 内置的 Cordis 生态

DeepSeek Harness 把 Cordis 框架全家桶直接 vendored 进仓库，保证版本锁定与可审计：

vendor/
├── cordis/        # 核心插件框架（ctx、事件、effect）
├── cosmokit/      # 工具库
├── loader/        # 配置加载器
├── include/       # !!js 表达式解析
├── schemastery/   # 配置 schema 驱动表单
├── hmr/           # 热重载
├── group/ timer/ logger-console/

docs/ —— 罕见的工程化文档体系

  • architecture.md（含中文版）：架构总纲、轮次流程图、扩展点映射表；
  • subsystems/*：约 50 个子系统页，每页含 生成的 Cordis API 参考（由源码 AST 生成并做漂移校验）；
  • cordis-tutorial/：7 讲 Cordis 上手教程；
  • cookbook/：扩展实操手册（加包、加工具、加 LLM 适配器、加 Chat 节点）；
  • tool-catalog.md / config-catalog.md / event-producer-consumer.md / graph-atlas.md：生成式目录，由脚本从真实运行时读取；
  • postmortem/：故障复盘文档；
  • 所有文档均维护中英双语，并有 verify-* 脚本保证链接、引用、mermaid 图不失效。

三、使用的工具与技术栈

语言与运行时

工具用途
TypeScript 6全栈主体语言，严格模式，host/client 双面工程
Node.js 22/24运行时
Rustnative/landlock-run：Linux Landlock 沙箱启动器
Python + uv/hatchpython/sdk（Python SDK）与 sdk-runtime

构建与工程化

工具用途
pnpm 11 workspacesmonorepo 包管理（workspace:^ 内部依赖）
tsc project references类型检查与编译（host/client 两套 tsbuildinfo）
tsdown库构建（按 DSH_BUILD_FACE 区分 host/client 产物）
ViteWeb 前端构建（apps/web）
tsx直接运行 TS 脚本（构建、校验、迁移）
lefthookgit hooks
knip / publint / jscpd / oxlint死代码检测 / 包发布检查 / 重复代码 / 快速 lint

测试体系（六套 Vitest 配置）

  • vitest.config.ts：单元测试；
  • vitest.e2e.config.ts：端到端（含 Playwright 驱动真实浏览器）；
  • vitest.snapshot.config.ts：快照（可 record / refresh / replay 三种模式）；
  • vitest.web.config.ts：Web 前端测试；
  • vitest.web.perf.config.ts：性能（complex-history.perf.ts 等）；
  • vitest.web-stress.config.ts：压力测试。

关键基础设施

组件角色
Cordis插件框架（事件、服务、可逆副作用）
JSONL + SQLite会话持久化双后端
@vscode/ripgrepglob/grep 工具的打包二进制（无需宿主安装 rg）
LandlockLinux 原生进程沙箱（自限制后 exec）
E2B远程 Linux 沙箱 POC（云端执行世界）
PlaywrightWeb e2e 测试
Mermaid文档图表

协议支持

  • MCP（Model Context Protocol）：packages/mcp/mcp-client，接入外部 MCP 工具；
  • ACP（Agent Client Protocol）：packages/acp/acp，把 dsh 的 Agent 能力暴露给其他客户端（IDE 等）；
  • LSP：packages/lsp，语言服务器协议导航能力。

模型可用的工具集（20+ 个 shipped 工具包）

ask_user_question、run_code、exit_plan_mode、bash/pwsh、终端六件套（terminal_open/send/read/...）、read/write/edit/read_image、glob/grep、web_search/web_fetch、lsp、subagent/subagent_fork、send_message/list_agents/interrupt_agent、workflow、ralph、create_goal/get_goal/update_goal、todo_write、job_kill/job_list/job_output、session_event_read/search/trace、skill、schedule_*、str_replace_editor、自指涉的 cordis_define/inspect/run/stop 等。

四、优势与创新点

1. "一切皆插件"：无特权内核的极端可扩展性

这是最根本的创新。模型适配器、工具注册表、会话日志、agent loop 全部是插件，全部可从配置替换。对比传统框架的"内核 + 钩子"，dsh 的扩展是组合式的：挂载一个插件 = 扩展产品，卸载插件 = 注册副作用自动撤销。dsh --profile web --dump-config 能打印出你机器上真实启动的整棵配置树，任何一行都可以用你自己的 patch 覆盖——这是可观测性与可定制性的极致统一。

2. Profile + Bundle 的分层组装模型

运行中的 dsh 是由多个层叠"补丁"组合出来的插件树：每个 bundle 按顺序应用 → profile 的 cordis.patch.yml → home 级 → --patch 覆盖。web 和 headless 作为模板交付。这有点像"操作系统发行版"的哲学：三层预置 + 一层用户覆盖，让"给产品换脑"变成改一行 YAML。

3. 能力 Seam（接缝）设计：一次替换、全局生效

每个可替换能力由三个角色构成：Service Definition（接口）/ Service Provider（实现）/ Consumer（消费者，通常是模型工具）。文件系统与进程提供方共享同一个"执行世界"，所以把 ctx.fs 和 ctx.subprocess 指向远程沙箱（如 E2B），Bash、PTY、LSP 就跟着一起搬过去，无需为每个消费方写 provider 分支。subagent 提供方同样千变万化——从新建子 agent 到把一轮委派给另一个产品（ACP）——都藏在同一个接口后面。

4. 会话日志作为唯一事实来源："模型可见即已记录"

这是数据完整性上非常严格的创新：任何到达模型请求的内容都必须能从会话日志重建，并由运行时不变量（runtime invariant）断言。deriveMessages() 从仅追加的 SessionEvent 日志投影模型历史；fork、resume、transcript、遥测、持久化全部派生自同一事件流。原始 assistant/chunk 事件保留回放与 UI 保真。这一不变量把"会话可复现"从口号变成了可测试的工程约束。

5. 三级事件体系 + 四种派发模式

  • 持久会话事件（turn/*、step/*、user/message、tool/*）：事实必须存活；
  • 实时 Agent 事件（agent/*）：观察/拦截飞行中的工作；
  • 能力事件（fs/*、tools/*、telemetry/*）：在不 import 主循环的前提下附加策略与适配器。

事件派发支持 emit（观察）/ waterfall（环绕中间件，可短路）/ parallel（并行）/ serial（有序决策）四种模式，是 Cordis 论文《A Programming Paradigm for Spatiotemporal Composability》所描述的时空可组合性的工程落地。

6. 安全沙箱：从内核级到云端的纵深防御

  • Landlock：Linux 上自研的"自限制后 exec"启动器（Rust 编写），进程在启动前先约束自己的文件系统权限；
  • 审批系统：ApprovalRequest/ApprovalOutcome，每次敏感操作按会话策略征求用户批准；
  • 权限预设（permission-presets）：按会话动态解析策略；
  • 凭据引用：配置里只存 CredentialRef（引用）而不是值，逐操作解析，UI 只暴露 CredentialInfo；
  • fail-closed：无法判定时默认拒绝。

7. 原生多智能体与任务编排

subagent seam 支持可续跑的后台子代理（subagent / subagent_fork）、结构化子代理控制（send_message/list_agents/interrupt_agent）、workflow（脚本化多阶段编排，阶段间无屏障流水线）、ralph（每轮全新 agent 的迭代循环）、goal 工具（跨轮次持久目标，可暂停/恢复/标记阻塞）。后台任务由统一的 ctx.jobs 运行时管理，job_* 三件套统一读写。这套体系让"agent 编排 agent"成为一等公民。

8. 自我指涉（Self-referential）：用 dsh 开发 dsh

工具集中甚至有 cordis_define / cordis_run / cordis_stop / cordis_inspect_*——运行时在 vm 沙箱里动态定义并运行 Cordis 插件包，动态包还能注册新的模型可见工具。加上 AGENTS.md、CLAUDE.md、.agents/notes/ 中沉淀的 3800+ 篇 agent 工作笔记，这个项目是"dogfooding"（吃自己的狗粮）的极致案例：它既是 Agent 运行时，也是用 Agent 开发的 Agent 运行时。

9. 生成式目录 + 漂移校验的工程质量

项目用脚本从真实运行时生成工具目录（tool-catalog 会真的 boot 每个工具插件读取 ctx.tools.schemas()）、配置目录、事件生产消费映射、模块图、持久化目录，并由 verify-* 系列脚本在 CI 中做漂移检查。再加上六套测试矩阵（单元/e2e/快照/Web/性能/压测）与 Windows/Linux 双平台门禁（甚至用 Wine 跑 Windows 门禁），文档与代码的同步是被自动化强制的，而不是靠自觉。

10. 开放生态与可接入性

  • MIT 协议，dsh-plugin GitHub topic 鼓励第三方插件；
  • 支持 MCP（接入外部工具）、ACP（被 IDE 等客户端接入）、LSP；
  • Web GUI / Headless / TUI / Python SDK 四种形态；
  • 完整的中英双语文档体系（每个文档都有 *.zh.md，且有翻译校验脚本保证成对）。

五、局限与定位

需要客观指出：项目处于 developer preview 阶段（0.1.0-rc.5），官方明确声明存在破坏性变更；框架较重（Node.js monorepo、Cordis 抽象层），学习曲线陡峭——架构文档明确要求先读完 Cordis primer 与 7 讲教程才能改 packages/；沙箱生态仍在演进（E2B 是 POC，Landlock 仅 Linux）。它更适合以 DeepSeek 模型为基座、需要深度定制与多智能体编排的团队作为基础设施，而非追求开箱即用的轻量用户。

六、总结

DeepSeek Harness 的独特之处，在于它把"可扩展性"从特性提升为架构公理：没有内核、没有特权、一切可替换、一切可观察、一切可复现。加上会话日志不变量、三级事件体系、能力接缝、原生多智能体编排与严格的工程质量门禁，它代表了当前开源 Agent 运行时中"重架构、高组合性"路线的前沿实践。对于想深入理解 Agent 系统如何被"拼装"出来的开发者，这是一个极佳的学习与二次开发蓝本。

相关链接：

个人观点，仅供参考，如有不对之处，请多包涵，欢迎指出。本文由AI协助完成！