打破传统固化架构：DeepSeek Harness 全插件化 AI Agent 框架实测解析

打破传统固化架构：DeepSeek Harness 全插件化 AI Agent 框架实测解析

阅读路线建议：想快速了解全插件化架构 → 直接看【一、二】；想上手接入 → 跳转【五】；想看我的主观评价 → 跳转【七】。

---

前言：打破传统固化架构的开源尝试

当前主流的 AI 编程工具大多被厂商闭源锁定 ——Claude Code、Codex、Cursor 各有优势，但架构上存在共性：核心逻辑固化，开发者只能在划定边界内使用，很难深度改造底层能力。 你只能 “用” 它，不能 “改” 它。

8 月 13 日，DeepSeek Harness 正式推出开发者预览版并以 MIT 协议开源，同日 DeepSeek-V4-Pro 正式版同步上线。本文聚焦这款全新开源 Agent 框架，我第一时间翻源码、跑 demo、看社区讨论，越看越觉得有意思。它走了一条和所有现有工具都不同的路：一切皆插件。不是 “支持插件”，而是 “整个产品就是由插件拼起来的”。这种从框架底层贯彻的可修改、可扩展的开源精神，正是它最打动我的地方。

这篇文章我从一个开发者的视角，聊聊 DeepSeek Harness 的设计思路、上手体验以及我的个人评价。

---

一、DeepSeek Harness 是什么

DeepSeek Harness 是 DeepSeek AI 开源的 Agent 运行框架，代号 dsh。它基于 Cordis 插件架构，连 Agent 的驱动循环本身都是插件，可以替换。

用大白话讲就是：Claude Code 和 Cursor 是"成品软件"，你装好就用；DeepSeek Harness 是"乐高积木"，每个零件都可以换，你想怎么搭就怎么搭。

它目前处于开发者预览阶段（Developer Preview），官方明确声明"THERE WILL BE COMPATIBILITY-BREAKING CHANGES"——正处于持续快速迭代中，存在兼容性破坏性变更，目前仅适合开发体验与生态探索。不过社区活跃度很高，后续迭代值得关注。

---

二、最大亮点：一切皆插件

2.1 这句话不是口号

我翻完源码以后，最大的感受是："一切皆插件"不是营销话术，是真的做到了。

看看这些核心组件在 DeepSeek Harness 里是怎么实现的：

组件	传统 Agent 框架的做法	DeepSeek Harness 的做法
模型适配器	写死支持某几个模型	注册到 ctx.llm，插拔式切换
工具注册表	内置工具，加新工具要改源码	注册到 ctx.tools，安装即生效
Agent 循环	硬编码在框架里	注册到 ctx.agentLoop，可整体替换
文件系统	直接调 Node.js fs	注册到 ctx.fs，可切到远程沙箱
Shell 执行	直接 spawn 子进程	注册到 ctx.shell，可换执行后端
UI 界面	框架自带，动不了	就是一个插件，想换就换

关键点：传统框架的"插件"是给你加功能的，核心你动不了。DeepSeek Harness 的插件体系是——连核心都可以换。你甚至能用自己写的插件替换掉官方的 Agent 驱动循环，重写 AI 与工具的整个交互流程。

打个比方：传统框架像一个精装修的房子——墙纸、地板、灯具都是定好的，你只能往里添家具；Harness 像一个毛坯房，每面墙、每根管线都可以重新布置，按你的需求来。传统框架让你"使用"，Harness 让你"建造"。

2.2 架构长什么样

整个 dsh 启动后，是一个从配置文件按序组合出来的插件树。根据源码 docs/architecture.md，启动层级叠加顺序为：Bundle 列表（按序）→ Profile 级 patch → 全局 Home 级 patch → --patch 命令行覆盖。后一层可以覆盖前一层的任意配置项。

也就是说，dsh 启动时按以下顺序加载配置：

1. Bundle 层：dsh-base（模型适配器、工具注册表、会话日志、沙箱/权限策略）+ dsh-web-app（Web UI 层）
2. Profile 级 patch：当前 Profile 的 cordis.patch.yml
3. Home 级 patch：全局 ~/.dsh/ 下的补丁
4. 命令行覆盖：--patch 参数指定的临时覆盖

2.3 底层靠什么：Cordis 框架

"一切皆插件"能做到，靠的是底层一个叫 Cordis 的框架。它的核心设计理念是时空可组合性（Spatiotemporal Composability），背后有一篇正式的学术论文（《A Programming Paradigm for Spatiotemporal Composability》）。

拆开来看就两个维度：

1. 时间可组合（可逆效应）：插件注册的任何东西——工具、监听器、适配器——在插件卸载时都会被完全回滚，不会残留。这保证了插件的加载和卸载是"干净"的，不会污染系统状态
2. 空间可组合（依赖注入）：每个插件声明自己需要什么服务（inject: ['tools']），框架自动等依赖就绪再加载。所有交互通过类型事件完成，插件可以在任意节点监听、拦截、改写

这套机制让整个系统像一个"插件插槽矩阵"——每个位置都是可替换的，替换后自动生效，卸载后自动恢复。这种"先有理论，再有实现"的做法，在开源项目里并不多见。

---

三、Agent 是怎么跑起来的

3.1 Turn 和 Step

DeepSeek Harness 对 Agent 的交互做了清晰的抽象。一个 Step 是一次模型请求加上它调用的工具；一个 Turn 包含零个或多个 Step。

简化后的流程：

turn/start
  → 拿到用户输入
  → 组装提示词 + 工具列表
  → agent/pre-step（插件可以在这里拦截/改写输入）
  → step/start
     → 发请求给模型
     → 模型返回 → 可能调用工具
     → 工具执行前 pre-execute → 执行 → post-execute
     → step/end
  → agent/turn-stopping
turn/end

关键设计：这个流程里每一个箭头都是一个事件，插件可以挂在任意事件上做拦截。 比如你想在每次工具执行前加个权限检查，只需要监听 tools/pre-execute 事件，不需要改框架代码。

3.2 会话日志：事件溯源

另一个让我觉得设计很干净的点是会话日志。它采用事件溯源模式——所有操作记录为 SessionEvent，只追加不修改。模型看到的上下文、对话回放、会话恢复、Fork 分支，全部从这份日志派生。

这带来一个好处：模型可见的内容一定在日志里，运行时有断言检查。 不会出现"AI 参考了某个你没看到的信息"这种黑盒情况。

---

四、安装与快速上手

4.1 环境要求

依赖	版本	说明
Node.js	22.19+ / 24+	CI 也覆盖 26，但 22.19+ 和 24+ 为稳定支持
pnpm	11.7.0	仓库锁定了版本，需启用 Corepack
Git	2.26+	源码构建需要

4.2 最快启动方式

# 一行命令启动 Web UI
npx @deepseek-ai/dsh web

启动后访问 http://127.0.0.1:3080，就能看到 Web 界面了。如果要从源码构建：

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

---

五、接入 DeepSeek 与设置详解

启动后，Web UI 左侧是设置栏，右侧是会话区。几个关键设置值得展开说说——有些和 Codex、Trae 等工具类似，我快速带过；有些是 Harness 独有的，我重点讲。

5.1 模型配置

打开 Settings → Models，DeepSeek 卡片里直接输入 API Key，保存即可。Key 保存后只显示脱敏描述符，无法再查看原文，实际存储在 $DSH_HOME/.credentials.yaml 中。
除了内置的 DeepSeek，还支持添加其他 Provider（Anthropic、OpenAI 等）和自定义 Provider。自定义 Provider 支持任意 OpenAI 兼容接口——输入 Provider ID、Base URL、API 协议和 Key，就可以接入 DeepSeek Plus 或其他兼容模型。模型变更不需要重启服务器，下次请求生效。

选好模型后，点击 Choose workspace 添加项目目录，选中即可开始会话。整个过程三步，比 Claude Code 设环境变量再加载 .env 直观很多。

5.2 权限预设：Harness 独有的安全设计

这是 Harness 比较有特色的一个设置，Codex、Trae 里没有直接对应的概念。

Settings → Permissions 里有两个预设：

预设	沙箱模式	审批策略	含义
workspace-write（默认）	工作区可写	危险操作需确认	日常开发推荐，安全与效率平衡
danger-full-access	全系统可写	从不询问	相当于关闭所有安全限制

预设不是单独的功能开关——它把沙箱模式和审批策略两个独立的维度打包成一个选项，切换预设时两个维度同时变化。你也可以手动分别调整，这时会显示为 custom（自定义）。

默认的 workspace-write 适合大多数场景：AI 能修改工作区内的文件，但执行危险命令或访问工作区外的目录时会弹窗确认。如果对 AI 足够信任，切到 danger-full-access 则完全放开。

5.3 插件与 Agent 预设管理

这两个和 Codex、Trae 的插件/Agent 管理类似，简单说：

• 插件管理：在 Settings 中可以看到已加载的插件列表，通过 cordis.patch.yml 或 cordis.yml 注册新插件。框架自动处理加载、卸载、资源释放，开发者只需专注功能实现
• Agent 预设：可以创建不同能力的 Agent 配置（比如只读分析 Agent、全功能开发 Agent），每个 Agent 可以有独立的工具集和权限策略

5.4 配置文件一览

Claude Code 用户最熟悉的就是项目根目录的 CLAUDE.md——放项目规范和代码风格。Harness 的配置体系分散在几个文件中，理解它们的关系有助于后续深度使用：

文件	位置	作用
settings.yaml	$DSH_HOME/settings.yaml	全局设置：模型、Provider、自定义端点
.credentials.yaml	$DSH_HOME/.credentials.yaml	API Key 加密存储
cordis.yml	插件/项目目录	插件注册和配置
cordis.patch.yml	Profile 目录	用户自定义补丁，覆盖默认配置

举例：如果你想接入 DeepSeek Plus 或其他兼容接口，在 settings.yaml 中配置自定义 Provider：

llm-pi-ai:
  providers:
    my-deepseek-plus:
      apiKeyEnv: DEEPSEEK_API_KEY
      api: openai-completions
      baseURL: https://api.deepseek.com/v1
      models:
        - id: deepseek-chat
        - id: deepseek-v4-flash

Claude Code 的配置是"环境变量 + CLAUDE.md + Plugin 市场"三个独立体系；Harness 是"统一的 Cordis 插件树"，所有东西都在同一个配置体系中通过 patch 叠加。灵活度更高，但上手门槛也更高。

5.5 初次使用的感受

配置好后，我开了第一个会话：

“帮我分析一下这个项目的整体结构，列出主要模块”

Agent 自动读取文件、分析结构、输出摘要，整体体验和 Claude Code 类似。几个使用感受：

顺手的地方：模型在界面下拉框里直接切换，不用改环境变量重启；不同项目选不同工作区，互不干扰；Key 脱敏存储，比 .env 明文安全。

需要适应的地方：Web UI 交互习惯和终端不同，习惯了 claude -p 单次命令模式的话这里没有直接等价物；权限审批弹窗在 Web 界面里，不如终端里按 Y/n 快；目前没有完整的 CLI 交互体验。

---

六、插件开发与社区生态

DeepSeek Harness 的插件开发门槛不高。一个最小工具插件长这样（基于源码 docs/cookbook/adding-a-tool.md）：

import { readFile } from 'node:fs/promises'
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'my-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'read_file',
    description: 'Read a file from disk.',
    parameters: {
      path: { type: 'string', required: true, description: 'Absolute path' },
    },
    async execute(args, exec) {
      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
    },
  }))
}

几个让我觉得体验不错的设计细节：

• 参数验证自动完成：defineTool 根据你声明的 schema 自动校验模型传过来的参数，不用手写校验逻辑
• 注册即生效，卸载即清理：工具 Schema 自动注入到系统提示词里，模型直接能看到；插件卸载时工具自动注销，框架帮你处理加载、卸载、资源释放全流程
• 权限拦截只需一个事件：想加权限控制？监听 tools/pre-execute，返回 { kind: 'deny' } 就行

社区方面，虽然是刚开源，插件已经冒出来了。由于 UI 本身就是一个可替换的插件，有人直接把整个界面改造成了完全不同的风格，外观可以自由发挥。插件发现方式很简单：在 GitHub 仓库加 dsh-plugin 标签就能搜到。目前没有集中的插件市场，但以这个活跃度来看，只是时间问题。

---

七、我的看法

设计层面：架构理念超前

DeepSeek Harness 最打动我的不是它当下的功能，而是它的设计理念。

“一切皆插件"不只是一个技术决策，它背后是一种对开源精神的彻底贯彻。传统开源项目是"源码开放，你可以改”，但改核心代码的成本很高——要理解架构、要处理耦合、要跟着上游 rebase。Harness 的做法是：不需要改核心代码，你只需要写一个插件，挂上去就行。 框架本身就给你留好了所有替换接口。

安全层面：为 AI 执行代码做的防护

AI 执行代码存在天然的安全风险——它可能误删文件、执行危险命令、访问不该访问的目录。Harness 在安全方面做了几层防护：

• 访问范围隔离：不同插件之间的代码相互隔离，一个插件出问题不会影响其他插件
• 多层权限管控：工具执行前可以经过多层权限检查，每一层都可以拒绝
• 操作全程留痕：所有操作记录在会话日志中，可以精确追溯到什么时间做了什么操作，甚至能进入子进程查看细节

这在实际使用中很有价值——当 AI 执行了你不期望的操作，你可以快速定位到是哪一步出了问题，而不是对着黑盒猜。

生态层面：插件市场是必然趋势

以目前社区的活跃度来看，插件市场是迟早的事。参考文档里提到了几个方向：

• 想要一个能操作数据库的插件？安装就行
• 想要一个能调用特定 AI 模型的插件？安装就行
• 不喜欢某个原生功能？替换对应插件就行

框架提供了标准的插件接口和完整的插件管理能力——注册、加载、卸载、资源释放全流程自动化。对用户来说，最大的感受就是自由与可定制：你不会被厂商锁定在某个固定功能上，不满意就换。

目前阶段：成熟度还不够

目前是开发者预览阶段，官方明确声明有兼容性破坏性变更，正处于持续快速迭代中。API 不稳定意味着你写的插件可能下个版本就挂了，目前仅适合开发体验与生态探索，不适合生产环境。

另外，Claude Code、Cursor 是"开箱即用"的成品，DeepSeek Harness 是"搭积木"的框架。如果你只是想用 AI 写代码，Harness 不是你需要的；如果你想自己搭建一个 AI 编程工具，Harness 是目前最好的底座。

对开发者的启示

Harness 的插件体系降低了定制 Agent 的门槛——你不需要从头造轮子，只需要在框架上挂一个插件。开源后社区讨论度很高，说明开发者对"可自由定制的 Agent 框架"这件事本身是有强烈需求的。

---

八、和 Claude Code、Cursor 放一起看

维度	DeepSeek Harness	Claude Code	Cursor
定位	Agent 框架，搭积木	CLI 编程工具，开箱即用	编辑器内嵌 Agent
架构	一切皆插件，全部可替换	单体工具，通过 MCP/Plugin 扩展	编辑器沙箱内 Agent
开源	MIT 开源	非开源	非开源
成熟度	开发者预览	生产可用	生产可用
适合谁	想自己搭建/定制 Agent 工具的开发者	日常用 AI 写代码的开发者	习惯在编辑器里用 AI 的开发者

一句话总结：DeepSeek Harness 不是用来替代 Claude Code 或 Cursor 的，它是用来造下一个 Claude Code 或 Cursor 的。

---

九、常见问题

Q1：现在能用吗？

可以跑起来，但不建议在生产环境使用。官方明确声明接口会变，目前适合学习架构、试用插件开发。不过以社区的活跃度和官方的迭代速度来看，后续版本值得期待。

Q2：和 Claude Code 是什么关系？

不是同一个东西。Claude Code 是成品工具，Harness 是 Agent 框架。你可以用 Harness 搭建一个类似 Claude Code 的工具，但 Harness 本身不直接替代它。

Q3：插件用什么语言开发？

TypeScript。框架本身也是 TypeScript 写的。

Q4：和 LangChain 有什么区别？

LangChain 是应用层编排框架，侧重提供链式调用、RAG 等高层抽象，帮你快速编写 Agent 业务逻辑。DeepSeek Harness 是运行时底层基座，负责承载 Agent 生命周期、沙箱隔离、事件系统、插件热更新等基础设施。定位不同，可以互补。

---

十、总结

DeepSeek Harness 给我的整体感觉是：架构设计超前，产品成熟度还没跟上，但方向是对的。

它带来了四个核心价值：

• 自由：不喜欢的原生功能可以直接替换，甚至整套 UI 和运行循环全部换掉
• 灵活：统一标准化接口，插件替换后独立运行，无需改动底层框架
• 安全：访问范围隔离、多层权限管控、操作全程留痕
• 可拓展：插件市场是必然趋势，普通开发者也能按需定制

往更深层看，这套设计有可能改变 AI 产品开发规则——不再是少数厂商决定产品形态，而是社区共同定义。

如果你只是日常用 AI 写代码，Claude Code 或 Cursor 更合适。但如果你对 Agent 的底层实现感兴趣，或者想自己定制一个 AI 编程工具，DeepSeek Harness 的源码值得一读。它的"Cordis + 一切皆插件"设计思路，很可能会影响下一代 AI 编程工具的架构方向。

我个人的判断是：Harness 本身不一定成为最终产品，但它的架构理念会被后续的工具框架大量借鉴。

---

参考资料

• DeepSeek Harness GitHub 仓库
• Cordis 框架论文
• DeepSeek Harness 架构文档
• DeepSeek API 开放平台