AI-Chain
AI Agent DeepSeek Harness Agent Harness 开发者工具

DeepSeek Harness：用“一切皆插件”架构打造可替换的 AI Agent 工作台

分享:
DeepSeek Harness：用“一切皆插件”架构打造可替换的 AI Agent 工作台

先说结论：Agent 的核心不应该是无法替换的黑盒

许多 AI Agent 项目一开始都像一个函数：接收 prompt，调用模型，执行几个工具，再返回结果。随着需求增加，模型供应商、工具注册、session log、文件工作区、sandbox、权限审批和 Web UI 逐一加入，这个函数很快会变成难以替换的单体。

DeepSeek Harness（dsh）选择了另一条路：官方文档将它描述为“一切皆插件”的 agent harness。模型 adapter、tool registry、session log、agent loop，以及 Web 和 headless 执行模式，都以 plugin 形式组合。它的价值不只是模块化，而是让替换行为成为系统的一等能力：团队可以通过另一个 plugin 叠加、覆盖或卸载行为，而不必修改 privileged core。

但需要先说明，DeepSeek Harness 目前仍是 developer preview，官方明确警告会出现 breaking changes。因此它更适合研究可组合的 Agent 架构、建立内部原型和评估 plugin 边界，不适合直接作为稳定的生产平台。

它解决哪种问题？

如果团队只是想调用一次 LLM API，dsh 可能太重。它真正面向的是会持续变化的 Agent 工作流：切换模型供应商，在 Web 和 headless 执行中复用同一个 agent loop，独立替换工具和 approval policy，以及通过 profile 组合不同环境，而不是复制整个应用。

这些需求的共同点是组合方式在变化，而不只是 prompt 改了几个字。如果每次替换都要 fork 核心并修改多个依赖模块，维护成本会随着功能数量快速上升。

架构重点：Plugin、Cordis、Profile 与 Bundle

1. Plugin 是统一的组合单位

DeepSeek Harness 使用 Cordis 作为底层框架。根据架构文档，plugin 可以向共享 context 贡献 services、typed events 和可逆 effects；plugin 卸载时，注册也可以通过同一生命周期模型回收。安装和撤销能力因此遵循同一种组合模型。

系统没有必须直接 patch 的 privileged core。模型 adapter、工具注册、session log 和 agent loop 都是可替换组件。扩展点是挂载到 context 的 plugin，而不是隐藏在核心文件里的 hook。

2. Profile 描述可执行环境

Profile 是存储在 Harness home 中的命名组合，列出 bundles，保存 out-of-tree plugins，并保存用户自己的 cordis.patch.yml。项目提供 web 和 headless 作为 profile template。

可以把 profile 看作某种工作模式的配方：Web 需要浏览器界面和 server，headless 适合一次性或自动化任务。不同部署场景可以保留不同 profile，而不是把所有条件塞进一个全局配置文件。

3. Bundle 划定分发与覆盖边界

Bundle 是 Cordis 配置行及其挂载代码的分发格式。Bundles 按顺序应用，高层可以 patch 低层插入的内容。架构文档以 dsh-base、dsh-web-app 和 dsh-headless 为例：base 提供 model adapters、tools、persistence、sandbox、approval policy、settings、credentials 和 telemetry；web-app 加入浏览器应用；headless 加入无需 server 的 one-shot runner。

重点不在术语，而在明确的组合顺序。需要替换 approval policy 或工具集时，应该先判断在哪一层加入 patch，而不是直接修改基础 bundle。

实际上手：先启动 Web UI，再验证第一个任务

前置条件

官方 README 的最短路径是使用 npx，先安装 Node.js。若从源码开发，development guide 另外要求 Node.js 22.19+ 或 24+、启用 Corepack 的 pnpm，以及 Git 2.26+。要在 Web UI 执行真实模型任务，需要在 Settings 中配置 DeepSeek API key；不要把凭证写入命令或日志。

方式一：通过 npm 启动

npx @deepseek-ai/dsh web

默认 Web UI 地址是 http://127.0.0.1:3080。用浏览器打开后进入 Settings → Models 配置 provider，再点击 Choose workspace，加入启动 dsh 时所在的项目目录；选择 workspace 之前，session composer 会保持不可用。

第一个可验证任务可以使用官方指南中的示例：

Summarize this repository and identify its main packages.

这一步可以同时验证模型配置、workspace 访问以及 agent 读取和整理项目文件的能力。Web UI 会根据当前 permission policy，在需要 approval 的操作前请求确认。

方式二：从源码运行

先检查 Node.js、pnpm 和 Git 版本，再执行：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

首次安装会通过 postinstall 配置 worktree-local Lefthook hooks 和 dsh-translation-pairing merge driver。若 hook 缺失，可按 development guide 执行 node scripts/install-lefthook.mjs，再用 pnpm run typecheck 做首次检查。

走向可维护导入的实践顺序

先用 web profile 验证模型、workspace 和 approval 行为，再评估 headless；不要同时改模型 adapter、工具和权限。新工具优先考虑 plugin，既有设置则研究 bundle 顺序与 cordis.patch.yml。分别测试读文件、写文件、执行命令和多步骤任务，记录 approval 边界、拒绝后的恢复方式以及 session log 是否足够。

当 Web、headless 和自动化 job 需要不同权限时，为它们保留不同 profile 比堆叠运行时环境变量更容易审查。升级 developer preview 时，要一起版本管理 bundles、外部 plugins 和 patch，并重新运行 typecheck 与关键任务。

限制与风险

项目处于 developer preview 阶段并明确警告 breaking changes，因此 CLI、plugin API 和 profile 格式不能被视为长期稳定契约。Everything-is-a-plugin 提供了可替换性，同时也要求团队理解 Cordis context、生命周期、layer 顺序和 patch 行为；没有测试和版本锁定时，自由组合也可能变成调试负担。

Approval UI 不能替代威胁模型。workspace、shell、sandbox、credentials 和 telemetry 仍需要最小权限、隔离、审计和敏感数据控制。对于只需要一次 API 调用的服务，简单 SDK 或 tool-calling loop 可能更合适。

结论

DeepSeek Harness 值得关注的地方，不只是又提供了一个 Agent UI，而是把 model、tools、sessions、permissions 和 loop 放进同一套 plugin composition 模型。务实路径是先用 npx @deepseek-ai/dsh web 跑通最小任务，再从源码理解 profile／bundle，最后建立自己的 plugin 和 permission policy。把它当成可组合 Agent 架构的 developer preview 来学习和验证，比把它误认为稳定的全能平台更符合官方现况。

参考资料