Agent Harness 到底是什么？从 Pi 和 DeepSeek Harness 讲起

✦内容摘要

Agent Harness 不是模型，而是让模型读文件、调用工具、执行命令并遵守权限的工作环境。本文从 Pi 和 DeepSeek Harness 讲起，用家用车与车队系统的类比讲清区别，并横向比较主流 Coding Agent，帮助新手按任务复杂度和安全需求做选择。

先弄懂模型、Agent 和 Harness，再谈工具怎么选。

如果你刚开始学 Agent，最容易卡住的通常不是代码，而是一串看起来很像的名字。

DeepSeek、GPT、Claude 是模型。Pi、DeepSeek Harness、Codex、Claude Code 又是什么？为什么同一个 DeepSeek 模型，放进不同工具里会有不同表现？

再往后看，还有 Tool、Skill、MCP、子 Agent、沙箱、上下文和工作流。每个词单独查都能找到解释，放在一起却很容易乱。

这些词现在都不用背。先弄清模型、Agent 和 Harness 三者的关系，后面的概念才有地方可放。

这篇从零开始，不要求你了解 AI 原理，也不要求你会写 Agent。最容易建立概念的办法，是先把大模型想成司机，把 Agent Harness 想成车。

沿着这个类比往下，只需要弄懂三个问题。

Pi 和 DeepSeek Harness 到底是什么
它们分别适合谁
如果两个都不合适，还有哪些工具值得选

先把最容易混淆的地方弄清楚

DeepSeek、GPT、Claude 是大模型。它们像司机，负责理解需求、判断下一步做什么。

Agent 处在更外一层。你给它一个目标，它会让模型判断下一步，调用工具得到结果，再把结果交给模型继续判断，直到任务完成、遇到风险或需要你确认。

一个最小的 Agent 工作过程，大概长这样。

你提出目标
  → 模型判断下一步
  → Harness 调用工具
  → 工具返回结果
  → 模型继续判断或结束任务

Pi、DeepSeek Harness、Codex、Claude Code 这一类东西，才是 Agent Harness。它们像车和工作环境，决定司机能看到什么、手边有什么工具、能去哪儿、哪些动作需要你同意、做过的事情怎么记录。

为了方便理解，可以把一套能真正干活的 Coding Agent 记成下面这样。

Coding Agent = 大模型 + Harness

Harness 通常负责组织
  读写文件和执行命令的工具
  项目上下文
  权限和安全规则
  会话与运行记录

Agent Harness 到底是什么？从 Pi 和 DeepSeek Harness 讲起 image 1

你让 AI 修一个 Java 空指针，模型负责判断哪里可能有问题。Harness 负责把 OrderService.java 交给模型，允许它搜索调用方、修改文件、执行 Maven，再把测试结果送回模型。

所以，同一个 DeepSeek 模型放进不同 Harness，表现可能不一样。模型没换，工作台、工具和规则换了。

这也解释了一个常见误会。DSH 功能更多，不等于它一定能写出更好的代码。最后的结果还要看模型能力、项目上下文、工具是否可靠，以及你有没有把需求讲清楚。

Pi 和 DSH 都是 Harness。它们从不同地方起步。Pi 从最小工具集起步，需要什么再增加什么。DSH 从插件化平台、任务编排和完整记录起步，开箱就准备了更多结构。

Pi 更像一辆简单的家用车

Pi 的官方定位很直接，它是一套极简的终端 Coding Harness。

默认情况下，它主要给模型四个工具。

read   读取文件
write  创建或覆盖文件
edit   修改文件
bash   执行命令

就这四个。

看着少，但日常写代码真的够用。读源码、搜索调用关系、改文件、运行 mvn test，几乎都能落到这四个动作上。

Pi 的舒服之处，是你很容易看懂它正在干什么。模型读了哪个文件，改了哪里，执行了什么命令，路径很短。出了问题，也比较容易定位。

它还支持很多模型。DeepSeek、OpenAI、Claude、Gemini、OpenRouter、一些云服务和本地模型都可以接。今天想用 DeepSeek，明天换 Claude，不需要连工作方式一起换掉。

需要更多能力时，可以用 TypeScript 写一个小扩展，也能安装现成的能力包。比如给 git push 加确认，禁止修改 application-prod.yml，或者增加一个专门跑 Maven 测试的命令。

代价也很清楚。

Pi 默认没有内建沙箱，也没有一套完整的权限审批系统。它启动在你的 Windows、macOS 或 Linux 账户下，就可能拥有这个账户能用的文件、进程、网络和凭证权限。扩展代码也有相近的权限。

所以 Pi 很轻，但安全边界要自己补。普通测试仓库问题不大，支付、结算、生产配置、私钥或线上脚本就不能裸跑。至少要有 Git、人工确认，最好再放进 Docker、虚拟机或其他隔离环境。

适合 Pi 的人通常有几种。

喜欢终端，希望工具简单透明
经常切换不同模型
主要做读代码、改文件、跑测试这类日常任务
想学习 Agent 最基本的工作循环
愿意自己补少量扩展和安全措施

Pi 的学习难度不算高。会用终端、会配 API Key，就能开始。想写扩展时，需要再学一点 TypeScript。

DeepSeek Harness 更像一家出租车公司的调度系统

DeepSeek Harness 常写成 DSH。它也能让模型读代码、改文件、执行命令，但它想解决的问题更大。

如果 Pi 是一辆车，DSH 更像一整套车队系统。里面有车辆、司机、任务调度、权限、行车记录、不同岗位和控制台。

DSH 的 Standard 模式开箱就带着文件工具、Shell、搜索、Web、Skills、计划、目标、子 Agent 和工作流。本地 Web UI 也已经准备好，小白不必先在终端里记一堆命令。

它还提供 Code、Minimal、Creator 等运行模式。你可以把 Minimal 当成精简测试车，只保留少量工具观察模型表现。Creator 更偏向检查运行时和开发自定义能力。

DSH 最有辨识度的地方，是「Everything is a Plugin」。模型接入、文件系统、Shell、工具、会话、沙箱、存储、Agent Loop、子 Agent 和 UI，都可以作为插件组合或替换。

这套思路对公司内部平台很有吸引力。平台开发者可以通过配置和插件，让不同团队使用不同模型，让不同项目采用不同权限，也可以把会话接入内部存储。工具调用和子 Agent 调度会进入追加式事件记录，为恢复、回放和审计提供基础。

这里说的是平台能力的基础，不是开箱即用的企业合规系统。多租户、内部身份、数据留存规则和审计报表，仍然要按公司的要求接入或开发。

听起来很强，学习成本也确实高。

普通用户打开 DSH Web UI，填好 DeepSeek API Key，选中工作区，就能开始。这一步甚至可能比 Pi 更容易。

一旦你要自己开发 DSH 插件，难度会突然上升。你要理解 Cordis、插件、事件和生命周期。对只想修几个 Java 文件的人，这些概念大多用不上。

还有一条不能藏起来。DeepSeek 官方目前把 DSH 标为 Developer Preview。它可以体验和研究，也可以做内部验证，但插件接口和配置仍可能发生破坏兼容的变化。现在就围绕它投入大量长期定制代码，后续维护成本很难判断。

DSH 的安全能力比默认 Pi 完整。它有 read-only、workspace-write、danger-full-access 等权限模式，也支持审批和一次性提权。

不过它的默认沙箱主要约束文件写入效果。网络访问、进程可见性和凭证隔离不能只靠这层沙箱。遇到不可信仓库或敏感项目，容器和虚拟机仍然有价值。

适合 DSH 的人也很好辨认。

明确想用 DeepSeek，又喜欢 Web UI
任务长，希望内置计划、目标和子 Agent
想查看完整执行轨迹
在做 Agent 评测、回放或实验
准备建设可插拔的内部 Agent 平台

Agent Harness 到底是什么？从 Pi 和 DeepSeek Harness 讲起 image 2

同一个 Java 任务，两边到底差在哪儿

假设需求只有一句。

修复 OrderService 的空指针，并运行 Maven 测试。

Pi 可能直接读取 OrderService，搜索调用方，修改代码，执行 mvn test，然后把结果告诉你。

DSH 可能先建立计划，再让一个子 Agent 搜索调用方，让另一个子 Agent 检查现有测试，主 Agent 汇总信息后修改代码并运行 Maven。整个过程会留下更完整的事件和轨迹。

两边最后可能改出一模一样的代码。

差别主要在过程。Pi 追求短路径，DSH 追求编排、替换和追踪。如果任务半小时就能做完，Pi 的直接会让人很舒服。如果任务要跑几个小时，还要多人查看过程、复盘某一步为什么出错，DSH 的记录和调度会更有用。

可以记住这个判断。

一项任务能不能完成，看模型和工具。很多任务怎样长期、稳定、可追踪地完成，才轮到平台能力发挥作用。

Agent Harness 到底是什么？从 Pi 和 DeepSeek Harness 讲起 image 3

为什么有人会觉得 DSH 更简单

这里有个很容易把人绕晕的地方。

从使用角度看，DSH 有 Web UI，填 Key、选目录、发任务，对没用过终端的人更直观。

从开发角度看，Pi 的结构小，写一个扩展就能加能力。DSH 要先理解完整插件体系，明显更难。

所以不能只问「谁更容易上手」。要问你准备做什么。

只是使用现成功能，DSH Standard 可能更容易。想研究 Agent 原理，Pi 更容易。想开发一个企业 Agent 平台，DSH 的学习成本更高，但它提供的结构也更多。

四个常见误会，最容易让选型跑偏

用 DeepSeek 模型，就必须用 DeepSeek Harness 吗

不需要。

DeepSeek 是模型，DSH 是 Harness。Pi、OpenCode、Aider 等工具也能接 DeepSeek API。使用 DSH 的理由应该是你需要它的 Web UI、计划、子 Agent、事件记录或插件平台，不该只是因为两边名字里都有 DeepSeek。

反过来也一样。DSH 虽然由 DeepSeek 推出，却不只支持 DeepSeek 模型。它还能连接 OpenAI、Anthropic 和一些兼容 OpenAI 协议的自定义网关。

先选模型还是先选 Harness，要看你最在意什么。模型能力和价格最重要，就先选模型。权限、工作流、审计和使用习惯更重要，就先选 Harness，再看它支持哪些模型。

Agent Harness 到底是什么？从 Pi 和 DeepSeek Harness 讲起 image 4

子 Agent 越多，任务做得越好吗

不一定。

一个子 Agent 搜代码，另一个检查测试，确实可以并行。但它们也会重复读取文件、消耗更多 Token，还可能给出互相冲突的判断。主 Agent 最后仍要整合结果。

修一个明确的空指针，单 Agent 沿着调用关系查下去往往更快。分析几个相互独立的模块，或者需要代码、安全、测试三个角度同时审查时，子 Agent 才更容易体现价值。

所以，DSH 内置子 Agent 是能力，不是每项任务都该开启的固定流程。Pi 默认不强调子 Agent，也不代表它只能完成小玩具。

Web UI 会比终端里的 Agent 更强吗

界面不会直接改变模型能力。

Web UI 的优势是直观。计划、轨迹、审批和多个会话可以放在页面上展示，新用户也更容易找到入口。终端的优势是快，离 Git、Maven、日志和脚本更近，熟悉命令行的人少切几次窗口就能完成工作。

真正影响结果的仍然是模型、工具、上下文和权限规则。喜欢页面就用页面，喜欢终端就用终端，不需要把操作习惯包装成技术高低。

DSH 功能更多，它算 Pi 的升级版吗

它们没有这种前后关系。

Pi 在主动保持小核心，让用户按需扩展。DSH 在主动建设一个可以替换组件、调度任务和回放过程的平台。一个把复杂性留到需要时再加，一个提前提供完整结构。

这像家用车和车队系统。车队系统的按钮更多，但你每天只开一辆车上下班时，多出来的调度能力不会自动帮你更早到公司。等你真的开始管理几十辆车，它们才会从负担变成工具。

两个都不选，还有哪些 Agent Harness

很多人研究完 Pi 和 DSH，最后发现自己真正需要的只是一个成熟的日常 Coding Agent。

这很正常。

Pi 把自由留给你，代价是有些能力要自己补。DSH 把平台结构准备好了，代价是更重、仍在预览。中间还有不少成熟工具。

下面这张表是为了选型方便做的简化归类，不是官方评分，也不比谁更聪明。

工具	可以把它想成	更适合什么需求
Pi	简单、可改装的家用车	终端、多模型、轻量任务、学习 Agent 循环
DeepSeek Harness	可插拔的车队调度平台	DeepSeek Web UI、子 Agent、审计、平台开发
OpenCode	配置齐全的多品牌车	多模型、代码导航、计划、子 Agent，又不想自己拼扩展
Codex	OpenAI 的完整工程车间	长任务、沙箱、审批、多 Agent、OpenAI 生态
Claude Code	Claude 的完整工程车间	Claude 模型、Hooks、子 Agent、企业策略
Gemini CLI	Google 的开源终端工具	Gemini、Google 搜索、低成本入门
Qwen Code	偏国内模型生态的全功能工具	Qwen、多协议、中文、IDE、桌面和多 Agent
Aider	你坐在旁边的结对程序员	明确控制文件范围、看 Git Diff、小步修改
Goose	连接外部工具的通用助手	桌面端、代码以外的文件和办公流程
OpenHands	带隔离运行环境的 Agent 平台	Docker、云端后台任务、远程沙箱、企业部署

不用一次记住十个名字，把它们收成四类就够了。

成熟的日常开发工具看 Codex、Claude Code、OpenCode。它们适合直接干活，不要求你先研究 Harness 架构
轻量和人工控制看 Pi、Aider。Pi 追求小核心，Aider 更强调明确文件范围和 Git 小步修改
平台和隔离运行看 DSH、OpenHands。DSH 偏插件和轨迹，OpenHands 偏 Docker、远程 Sandbox 和云端任务
特定生态和通用自动化看 Gemini CLI、Qwen Code、Goose。Goose 还能用 MCP 连接外部工具，把流程保存成可复用的 Recipe

小白怎么选，别先看功能数量

选 Agent Harness 时，最容易犯的错是看功能表。谁的勾最多，就觉得谁最好。

功能越多，模型需要理解的工具越多，你需要理解的配置也越多。用不到的能力不会自动变成价值，只会留在界面、上下文和维护工作里。

Agent Harness 到底是什么？从 Pi 和 DeepSeek Harness 讲起 image 5

这里还有一个很实用的办法。别一上来就让工具改整个项目，先给它同一项小任务。

比如选一个测试仓库，让几个候选工具都完成下面这些动作。

解释一个 Service 的调用流程
修复一个可复现的小问题
运行一条 Maven 测试命令
展示修改前后的 Diff
中途故意放一个需要审批的越界操作

你很快就能感觉到，哪个工具的节奏、权限和反馈方式更适合自己。产品页上的几十项能力，没有一次真实小任务直观。

Java、支付和对账项目要多看一层

普通示例项目里，Agent 改错了可以回滚。支付、结算、对账、权限和生产配置不一样，一条错误命令可能碰到真实数据或凭证。

这类项目别只比较模型回答得好不好，还要检查下面几件事。

能不能先用只读或 Plan 模式分析
写入是否限制在当前 Workspace
网络是否默认关闭或可控
危险命令是否需要单独批准
修改前后能不能清楚查看 Diff
SQL 是否默认只读
私钥、生产配置和凭证能否放在 Agent 不可读的位置
能否在 Docker、WSL 或虚拟机里运行

Pi 默认缺少内建沙箱，不能直接当安全边界。DSH 的权限和文件沙箱更完整，但也不是完整的网络、进程和凭证隔离。

Agent Harness 到底是什么？从 Pi 和 DeepSeek Harness 讲起 image 6

还有一件常被忽略的事。本地运行不代表代码只留在本机。只要使用 DeepSeek、OpenAI、Anthropic 或其他外部模型 API，Harness 仍可能把完成任务所需的代码和上下文发给对应服务。敏感代码能不能外发，要先看公司规则和供应商的数据政策。

最小启动命令

Pi 和 DSH 都需要先安装 Node.js。下面只有启动命令，不包含模型账号和费用。

想体验 Pi，可以先在一个测试仓库里安装并启动。

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi

启动后可以用 /login 登录支持的订阅服务，也可以按模型供应商的文档设置 API Key。

想体验 DSH 的 Web UI，可以运行下面这条命令。

npx @deepseek-ai/dsh web

浏览器打开后再配置模型 API Key，选择测试工作区。第一次别放生产仓库，也别把私钥和生产配置放进工作区。

读完真正该记住什么

如果只留四句话，我会留这些。

大模型是司机，Harness 是车和工作环境。换 Harness 不会直接让模型变聪明，但会改变它能看到什么、能做什么、怎样被约束。
Pi 适合轻量、透明、多模型和自己改装。它默认没有内建沙箱，敏感项目要额外隔离。
DeepSeek Harness 适合 Web UI、计划、子 Agent、事件回放和平台开发。它更重，也仍处于 Developer Preview。
只想提高日常开发效率，不必执着于 Pi 或 DSH。Codex、Claude Code、OpenCode 往往更省时间。

刚开始学 Agent，不用急着背插件名和架构图。先分清模型、Harness 和工具，再用一个小任务跑完读取代码、修改文件和执行测试的完整过程。先认车，再看零件，后面的概念自然会接上。

参考资料

Pi 官方文档[1]
Pi Security[2]
DeepSeek Harness 官方介绍[3]
DeepSeek Harness 架构文档[4]
DeepSeek Harness Sandbox[5]
OpenCode 官方文档[6]
Codex CLI 官方文档[7]
Claude Code 官方文档[8]
Gemini CLI 官方仓库[9]
Qwen Code 官方仓库[10]
Goose 官方文档[11]
Aider 官方文档[12]
OpenHands 官方文档[13]

断更一段时间，后续继续开始更新Agent技术😊

引用链接

[1] Pi 官方文档: https://pi.dev/docs/latest [2] Pi Security: https://pi.dev/docs/latest/security [3] DeepSeek Harness 官方介绍: https://deepseek.com/harness/en/ [4] DeepSeek Harness 架构文档: https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md [5] DeepSeek Harness Sandbox: https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/sandbox.md [6] OpenCode 官方文档: https://opencode.ai/docs/ [7] Codex CLI 官方文档: https://learn.chatgpt.com/docs/codex/cli [8] Claude Code 官方文档: https://code.claude.com/docs/en/overview [9] Gemini CLI 官方仓库: https://github.com/google-gemini/gemini-cli [10] Qwen Code 官方仓库: https://github.com/QwenLM/qwen-code [11] Goose 官方文档: https://block.github.io/goose/ [12] Aider 官方文档: https://aider.chat/docs/ [13] OpenHands 官方文档: https://docs.openhands.dev