开源项目第194期：deepseek-harness — DeepSeek 出品的 AI Agent 开发框架，万物皆插件

引言

名字里有"harness"，但和 EleutherAI 的 lm-evaluation-harness（模型评测框架）没有任何关系。

这是第 194 篇 。今天的项目是 deepseek-harness ------ DeepSeek AI 出品的 Agent 开发框架，核心设计理念是"万物皆插件"（Everything is a Plugin）。

一句话描述：把 AI Agent 的每一个能力组件做成可替换插件，然后给了四种截然不同的运行模式，其中 PTC 模式直接颠覆了标准工具调用的执行逻辑。

137,100 Stars，13,800 Forks。MIT 许可，TypeScript 为主，Node.js 运行时。Developer Preview 阶段，API 可能有破坏性变更。

你会学到什么

• "Harness"在这里是什么意思（不是 benchmark，是约束层）
• Cordis"万物皆插件"架构的核心思路
• PTC 模式：模型写 TypeScript 程序，而不是逐步调用工具
• 四种运行模式的差异和适用场景
• Append-only 会话日志和轨迹溯源机制
• 一行命令启动完整 Agent 开发环境

前提知识

• 了解 AI Agent 和工具调用（tool calling）的基本概念
• 熟悉 TypeScript/Node.js 基础
• 了解插件系统的一般设计思路会更有帮助

---

背景：Harness 是什么意思

"Harness"在工程语境里不是"评测工具"，而是约束层（constraint layer）------把一个系统包裹起来，给它提供结构化的边界和能力。

把马套上挽具（harness），不是限制它，而是让它的力量可以被精确引导。deepseek-harness 对 AI Agent 做的就是这件事：用插件约束层定义 Agent 能做什么、怎么做、留下什么记录。

现有的 Agent 框架通常把工具、内存、规划、子 Agent 硬编码在一起------某个能力改了，其他部分可能跟着崩。deepseek-harness 的解法：内核（kernel）只管插件的注册、依赖、生命周期，什么能力都是插件。换掉工具插件不影响规划插件；换掉模型后端不影响 UI 插件。

---

Cordis 架构："万物皆插件"

deepseek-harness 的底层是 Cordis 框架 ------ 一个专门为可插拔应用设计的 TypeScript 框架，Cordis 团队发表过一篇关于"时空可组合性"编程范式的论文。

Cordis 的核心约束：内核本身不包含任何业务逻辑，只负责：

• 插件注册和卸载
• 插件间依赖声明和解析
• 插件生命周期管理（加载、就绪、卸载）
• 服务的提供和消费

deepseek-harness 的每个能力都是这样构建的：

组件	插件形态
文件编辑工具	@dsh/plugin-str-replace-editor
Shell 执行	@dsh/plugin-bash
向量检索	@dsh/plugin-retrieval
规划器	@dsh/plugin-planning
目标追踪	@dsh/plugin-goals
子 Agent 调度	@dsh/plugin-subagents
工作流编排	@dsh/plugin-workflows
Web UI	@dsh/plugin-web-ui
模型后端	@dsh/plugin-model-openai 等

换掉模型后端：把 plugin-model-openai 替换成 plugin-model-anthropic，其他插件不受影响。关闭子 Agent 功能：卸载 plugin-subagents，不需要修改任何其他代码。

社区插件通过 GitHub Topic dsh-plugin 标记，可以直接搜索发现。

---

四种运行模式

这是 deepseek-harness 最值得关注的设计。不同场景需要的 Agent 能力集完全不同，框架提供四种预设模式，而不是一套"通用"配置。

Standard 模式

完整工具链：文件编辑、持久化 Shell、向量检索、技能库、规划器、目标追踪、子 Agent 调度、工作流编排。

适合：实际工程任务，需要完整 Agent 能力的场景。

npx @deepseek-ai/dsh web           # Web UI，默认 Standard 模式
npx @deepseek-ai/dsh               # CLI 模式

PTC 模式：程序化工具组合

PTC 全称 Program That Calls，是 deepseek-harness 最有特色的执行模式。

标准工具调用的流程：

Agent 调用 tool_A → 等待结果 → 调用 tool_B → 等待结果 → 调用 tool_C ...

每一步都要等模型决策，顺序执行，没有控制流。

PTC 模式的流程：

Agent 写一段 TypeScript 程序 → 程序组合调用 tool_A、tool_B、tool_C → 一次执行完

这个 TypeScript 程序可以用完整的编程构造：

• if/else：根据中间结果做条件分支
• for/while：循环处理多个文件或数据项
• try/catch：处理工具调用错误
• 并行调用：Promise.all([toolA(), toolB()]) 同时执行多个操作

// PTC 模式下，模型生成的程序示例
async function analyzeProject() {
  const files = await listFiles({ pattern: "src/**/*.ts" });
  
  const analyses = await Promise.all(
    files.map(f => readFile({ path: f }))
  );
  
  const hasTests = files.some(f => f.includes(".test."));
  if (!hasTests) {
    await createFile({
      path: "src/__tests__/basic.test.ts",
      content: generateTestTemplate(analyses)
    });
  }
  
  return summarize(analyses);
}

对于需要多步骤、有条件分支、可以并行的任务，PTC 模式比逐步工具调用效率高得多，也更容易推理整体执行逻辑。

Minimal 模式

只保留持久化 bash 和 str_replace_editor，去掉所有其他插件。

设计目的是 benchmark：在最干净的环境里测量模型的基础能力，不被复杂工具栈污染结果。SWE-bench 这类代码评测通常用这个模式。

Creative 模式

支持运行时插件检查和内存中插件试验------加载一个新插件，观察它的行为，不满意就卸载，不需要重启进程。

适合：开发新插件、调试插件交互、构建自定义 Agent 预设。

---

完整轨迹溯源

这是 deepseek-harness 在工程可靠性上的核心投入。

所有会话日志采用 Append-only 格式，记录每一步：

• 系统提示（system prompt）的完整内容
• 模型的思维链（Chain of Thought）
• 每个工具调用：函数名、参数、返回值
• 子 Agent 调度：哪个父 Agent 启动了哪个子 Agent，传了什么上下文
• 每次上下文注入：从哪个插件注入了什么信息

日志格式是 Append-only，每个事件追加到末尾，不修改历史记录。这让以下操作成为可能：

# 从某个中间步骤恢复会话
dsh resume --session <id> --from-step 15

# 从某一步 fork 出新的执行分支
dsh fork --session <id> --at-step 10

# 重放整个会话（用于调试或验证）
dsh replay --session <id>

# 查看某一步的完整上下文来源
dsh trajectory --session <id> --step 8

Trajectory 视图可以按来源拆解：某个结论来自哪个工具调用的返回值，哪个插件注入的上下文，模型在哪一步做了什么决策。

对于需要复现 bug 的场景，这个机制几乎是必须的：普通 Agent 运行失败后，你能看到最终结果，但中间发生了什么需要靠猜。deepseek-harness 的完整日志让你可以精确定位到"第 12 步，bash 工具返回了非零退出码，模型在第 13 步做了一个错误的假设"。

---

快速上手

一行启动 Web UI

npx @deepseek-ai/dsh web
# → Web UI 启动在 http://localhost:3080

不需要提前安装，npx 自动拉取。

CLI 模式

npx @deepseek-ai/dsh "帮我分析这个 TypeScript 项目的依赖关系"

配置模型后端

# 使用 DeepSeek 模型
export DEEPSEEK_API_KEY=your_key
npx @deepseek-ai/dsh web --model deepseek-coder

# 使用 OpenAI 兼容接口
export OPENAI_API_KEY=your_key
npx @deepseek-ai/dsh web --model gpt-4o

选择运行模式

npx @deepseek-ai/dsh web --mode ptc       # PTC 程序化模式
npx @deepseek-ai/dsh web --mode minimal   # Minimal benchmark 模式
npx @deepseek-ai/dsh web --mode creative  # Creative 插件试验模式

安装自定义插件

# 安装社区插件
pnpm add @dsh-community/plugin-github-tools

# 在配置中注册
# dsh.config.ts
export default {
  plugins: [
    require('@dsh-community/plugin-github-tools')
  ]
}

---

架构对比

维度	deepseek-harness	LangChain	OpenHands	gstack
架构核心	Cordis 插件内核	链式调用抽象	Docker 沙箱隔离	23 个角色命令集
执行模型	Standard / PTC / Minimal / Creative	单一工具调用链	工具调用 + 代码执行	专家角色分工
可替换性	每个能力都是插件	有限，部分硬编码	工具可配置	命令可组合
溯源机制	Append-only 日志，完整轨迹	基础日志	事件日志	无
benchmark 支持	Minimal 模式内置	需外部配置	支持 SWE-bench	无
主要语言	TypeScript	Python	Python	TypeScript
安装方式	npx @deepseek-ai/dsh web	pip install	Docker	git clone
Stars	137.1k	~100k+	~55k	~128k

---

主要使用场景

代码任务：Standard 模式，使用完整工具链。文件编辑、Shell 执行、向量检索、子 Agent 并行处理不同模块。

模型评测：Minimal 模式，干净环境，只保留 bash + 编辑器，测 SWE-bench 或自定义代码 benchmark。

多步骤数据处理：PTC 模式，模型写一段处理程序，批量处理文件、并行 API 调用、条件分支，比逐步工具调用效率高一个量级。

插件开发：Creative 模式，运行时加载新插件、观察行为、热卸载，不需要每次重启进程调试。

Agent 行为调试：任何模式都可以，Trajectory 视图追溯某个错误决策的完整上下文来源。

---

项目地址与资源

• GitHub : deepseek-ai/deepseek-harness
• 官网 : deepseek.com/harness
• 社区插件 : GitHub 搜索 Topic dsh-plugin
• Cordis 框架 : github.com/cordiverse/...
• 开发团队: DeepSeek AI，杭州

---

总结

deepseek-harness 做的不是"更好的 Agent"，而是"更好的 Agent 开发环境"。

Cordis 的万物皆插件约束，解决了 Agent 框架里的一个常见工程问题：能力组件耦合在一起，改一个影响一片。当每个能力都是独立插件时，替换、测试、组合都变得清晰。

PTC 模式是另一个值得单独讨论的设计决策。标准工具调用是"一步一步走"，PTC 是"先写好计划，再一次执行"。对于有条件分支和并行操作的任务，后者在效率和可调试性上都更优。

完整轨迹溯源让 Agent 从黑盒变成可检查的系统------每个决策步骤有记录，每条记录有来源，每次失败都能精确复现。

137,100 Stars 在 Developer Preview 阶段，说明 DeepSeek 在 Agent 开发工具这个方向的时机判断是准确的：模型能力足够了，缺的是让 Agent 可靠运行、可以被调试的工程基础设施。

---

探索 PrimeSkills ------ 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。