· Model + Harness = Agent：让大模型真正动手干活的运行时

· Cordis 微内核驱动，一切皆插件，热插拔可逆副作用

· 四种运行模式 + 插件市场 + 本地优先数据策略

一、Harness 是什么：从模型到智能体的关键一环

DeepSeek Harness （命令行简称为 dsh）是 DeepSeek 于 2026 年 8 月 13 日开源的 AI Agent 运行框架，采用 MIT 协议，发布当晚即登顶多家技术社区热搜。它本身不是大语言模型，而是一套智能体执行运行时（runtime）：模型负责思考与推理，Harness 负责环境感知、工具调度、任务状态维护、会话管理与沙箱权限控制，把模型的「想法」转化为真实可执行的操作。

DeepSeek 官方曾用一个公式概括这层关系：Model + Harness = Agent 。光有模型，它只会和你聊天；加上 Harness，它才能读你的代码、跑你的命令、改你的文件，直到把一整件事办完。可以理解为：模型是灵魂，Harness 是让灵魂能在你的电脑上动手干活的那具身体。

这一定位直接对标 Anthropic 的 Claude Code 与 OpenAI 的 Codex，但 DSH 从第一天起就走了另一条路------把这一层整体开源 。2026 年 9 月起，DeepSeek Harness 面向全球开放公测并同步开源，同时提供命令行、Web UI 与 Electron 桌面客户端三种形态，官方将其定义为「本地优先（local-first）、可扩展的 Coding Agent 与 Agent 开发/运行环境」。

传统 Agent 开发方案普遍存在几个痛点：工具调用硬编码、模块耦合严重、更换模型成本高、任务执行链路不可追溯。开发者每换一个业务场景，就要大量修改底层循环逻辑、工具定义与会话存储代码。DSH 的目标正是用「插件化 + 可追溯 + 可替换」一次性解决这些问题：所有核心组件------模型适配器、工具集、会话存储、任务调度循环、沙箱安全策略、甚至前端 Web 界面------全部封装为可插拔插件，无需修改框架源码，通过配置文件即可自由组合与替换能力模块。

1.1 为什么叫 Harness

Harness 在工程语境中本意是「马具/线束」------把力量传导到该去的地方。在 AI Agent 领域，Harness Engineering 指围绕模型构建的一整套工程外壳：上下文管理、工具协议、执行循环、权限与日志。模型只输出 token，Harness 决定这些 token 何时变成一次文件写入、一条 Shell 命令或一次子任务委派。DSH 是这一方法论的第一个重量级开源参考实现。

二、架构设计：Cordis 微内核与「一切皆插件」

DSH 的底层是 Cordis 插件内核 （源自开源项目 Koishi 的成熟微内核，作者 Shigma）。Cordis 内核本身不提供任何 Agent 能力，它只做两件事：管理插件的生命周期（加载/卸载/依赖解析），以及提供插件间的通信与上下文隔离。所有 Agent 能力都由插件提供------包括 DeepSeek 自家的模型适配器，它与其他模型适配器在框架内的地位完全相同，没有任何特权。

这套架构最关键的技术点是 可逆副作用（reversible side effects） ：每个插件在注册工具、界面、事件监听时，框架都会追踪其产生的全部副作用；插件被卸载时，这些副作用被自动回收。这意味着 DSH 支持热插拔 ------不重启框架即可更换模型、增删工具、替换 UI，正在运行的其他插件不受影响。这是传统一体化 Agent 框架难以做到的。

2.1 插件化的组件全景

|------------|--------------|-------------------------------------|
| 组件 | 插件形态 | 说明 |
| 模型适配器 | provider 插件 | 接入 DeepSeek 及 OpenAI 兼容 API，可配多模型路由 |
| 工具注册表 | tool 插件 | 文件读写、Shell、搜索、规划、子 Agent 等能力入口 |
| 会话存储 | storage 插件 | 仅追加式（append-only）会话日志，全链路可追溯 |
| 任务调度循环 | runtime 插件 | Agent 主循环本身也是一个可替换的插件 |
| 沙箱安全策略 | sandbox 插件 | 高危命令拦截、文件越权访问限制 |
| 前端界面 | UI 插件 | Web UI、TUI、桌面端均可替换或增强 |

2.2 全链路可追溯执行

DSH 采用仅追加式会话日志：系统提示、模型思考过程、每次工具调用、子 Agent 交互全部永久记录，在 Web UI 的 Trajectory 面板中逐步展示，支持任务回放、分支调试和故障溯源。同时内置原生可观测埋点：Token 计量、KV-Cache 命中率、工具耗时等指标直接在界面呈现，方便评估成本与性能。

2.3 数据策略：本地优先

按官方数据处理声明，安装运行后，用户输入、模型输出、会话上下文、工具调用记录、附件、执行结果与运行日志等默认全部保存在本机，未经用户同意不上传服务器。用户配置的模型服务地址、API Key 等敏感信息同样本地存储（密钥文件脱敏展示）。仅在用户主动调用外部模型、Web 工具、MCP 服务或第三方插件时，数据才会流向对应服务方。

三、四种运行模式：不同场景选不同底座

DSH 内置四种预设运行模式，本质是四套不同的插件组合。模式之间的差别不是「功能强弱」，而是给模型的「手脚」多与少：

|------------|---------------|----------------------------------|----------------------------------|
| 模式 | 定位 | 开箱加载的能力 | 适用场景 |
| 标准模式 | 默认模式，完整 Agent | 文件编辑、Shell、搜索、规划、子 Agent、工作流 | 代码项目分析、修 bug、重构、文档整理等绝大多数场景 |
| PTC 模式 | 程序化工具调用 | 模型生成 TypeScript 脚本，一次性编排多轮工具调用 | 批量数据处理、多分支条件任务，可显著减少往返与 Token 消耗 |
| 极简模式 | 裸模型基准 | 仅一个持久 Bash + 一个文件编辑器 | 跑能力基准测试、科研实验，看模型真实水平 |
| 创造模式 | 插件实验场 | 标准模式全部能力 + 运行时检查器 + Cordis 插件热加载 | 开发调试插件、让 Agent 用对话现场造插件甚至新模式 |

建议的使用路径是：第一次接触先用极简模式 感受模型裸能力，熟悉后切到标准模式 做日常开发；PTC 模式 适合工具调用链长、Token 成本敏感的任务（有实测在理想场景下 KV-Cache 命中率达 99%），但需要重点配置沙箱隔离、超时与资源配额；创造模式 权限要求最高，不建议在生产业务中直接使用。官方演示中，「帮我写一个番茄时钟插件」就是在创造模式下由 Agent 自主完成的：它读取插件开发技能文档、查询运行时插槽、直接写入插件包文件并热加载。

除四种预设外，还可以编写配置文件自定义插件组合，打造专属运行模式------因为模式本身就只是插件的排列组合。

四、安装与快速上手

DSH 提供多种安装形态，覆盖从五分钟体验到二次开发的不同需求。基础环境：Node.js 22.19+（22.x）或 24+；源码编译需 Git 与 pnpm；Python SDK 需 Python 3.10+；最低硬件 2 核 4G。

4.1 npx 一键启动（推荐新手）

需 Node.js v22.19+ 或 v24+

npx @deepseek-ai/dsh web

启动后 Web UI 默认运行在 http://127.0.0.1:3080（仅本地回环，不对外暴露）。首次使用在 Settings 中配置模型供应商与 API Key，或直接编辑配置文件：

~/.dsh/settings.yaml

agent-default-model:

provider: my-provider

model: deepseek-chat

llm:

providers:

my-provider:

api: openai-completions

baseURL: https://api.example.com/v1

apiKeyEnv: MY_API_KEY

4.2 全局安装与桌面客户端

npm install -g @deepseek-ai/dsh

dsh --version

dsh web

Windows/macOS 用户也可直接下载 Electron 桌面客户端（安装包约 275 MB），图形化管理后台服务、端口与进程，不依赖命令行。服务器长期部署建议用 systemd 托管；如需外部访问，将监听地址改为 0.0.0.0 并务必配好认证与防火墙。

4.3 源码构建与 Python SDK

git clone https://github.com/deepseek-ai/deepseek-harness.git

cd deepseek-harness

pnpm install

pnpm run build

pnpm dsh web

pip install deepseek-harness-sdk

from deepseek_harness import Agent

agent = Agent(model="deepseek-chat")

result = agent.run("分析当前目录的代码结构并生成报告")

异步：await agent.arun(...)

SDK 适合把 Agent 嵌入 CI/CD 或自动化脚本。注意：Windows 原生环境下 Python SDK 兼容性尚未完全验证，Windows 用户优先使用 Web UI 或桌面版。

五、插件生态与插件开发

5.1 生态现状

开源发布当晚，社区即收录 288 个插件仓库；发布数周内 GitHub 上带 dsh-plugin 标签的仓库已超过 1000 个。社区维护的目录有 awesome-deepseek-harness 等。生态中最活跃的几类插件：

能力扩展：dsh-vision-toolkit（图片问答/OCR/UI 还原）、浏览器自动化、RAG 向量检索等
界面增强：dsh-TUI（Claude Code 风格全屏终端）、dsh-web-ui（任务看板/Git 图谱/实时 Token 统计）、DSH-better-sidebar（侧边栏变完整工作台）
即时通讯接入：qqbot、dsh-weixin-bot、dsh-feishu-bot、dsh-wecom-bot、telegram 等，装完即可把 Agent 变成可被 @ 的聊天机器人

5.2 插件的安装方式

DSH 的插件安装不需要手动拼命令：把插件仓库地址发给对话框里的 Agent，用自然语言描述需求，它会自动安装并加载；卸载同样是一句话。也可以在插件市场（插件商店）中一键安装。

5.3 自己写一个插件

基于 Cordis 内核，一个最小工具插件只需注册 name、description、parameters 与 handler：

// multi-tool.js ------ 示例：注册一个自定义查询工具

export function apply(ctx) {

ctx.plugin.registerTool({

name: 'db_query',

description: '查询内部数据库并返回结果',

parameters: {

type: 'object',

properties: { sql: { type: 'string' } },

required: $'sql'$ ,

async handler(args) {

// 这里写真实逻辑：连接数据库、执行查询

return { rows: await queryDb(args.sql) };

});

}

在配置文件中注册插件后重启服务即可生效。除了工具，插件还可以扩展技能（skills）、界面、预设与整个运行模式，配合创造模式甚至能让 Agent 用对话帮你把插件写出来。

六、安全与权限控制

Agent 能碰文件系统和 Shell，安全边界就是产品的生命线。DSH 的安全设计分三层：

工作区权限三档： ReadOnly（只读）、Workspace Write（工作区读写）、Full Access（完全访问）。生产与日常场景建议遵循最小权限原则，只给到 Workspace Write。
沙箱策略： 限制高危命令（如格式化、删库类操作）与文件越权访问，命中规则的操作触发审批弹窗；工作目录独立隔离。
插件审慎安装： 第三方插件天然能触达 Shell 与文件系统，属于最大攻击面。安全团队已发布 13 个可复现攻击链示范，安装前务必阅读插件源码或仅信任可信来源。

此外需注意：当前版本（v0.2.x）仍处于公开预览阶段，官方明确声明后续会有不兼容变更 ，不建议接入生产关键路径。社区还报告过 Bash 空转 bug（反复执行空命令不推进任务），遇到时手动中断重新发起即可。

七、与 Claude Code、Codex 的对比

|------------|--------------------------|---------------------|----------------------|
| 维度 | DeepSeek Harness | Claude Code | OpenAI Codex |
| 开源程度 | MIT 协议全开源（含运行时内核） | CLI 部分开源，服务闭源 | 闭源为主 |
| 架构 | Cordis 微内核，一切皆插件，热插拔 | 一体化设计 | 一体化设计 |
| 模型绑定 | 无特权模型，OpenAI 兼容接口均可接入 | 深度绑定 Claude | 深度绑定 GPT |
| 运行形态 | CLI + Web UI + 桌面端 + SDK | CLI 为主 | CLI / 云端 |
| 可追溯性 | 仅追加日志，全链路回放 | 会话记录 | 会话记录 |
| 扩展方式 | 插件（1000+ 社区仓库） | 技能/MCP | 工具/MCP |

简单概括：Claude Code 与 Codex 是「为自家模型量身定制的最佳体验」，DSH 则是把 Harness 这一层基础设施整个交还给社区------模型可换、界面可换、循环可换。对于需要私有化部署、多模型路由或深度定制的团队，DSH 提供的自由度是前两者无法比拟的；而对于只想开箱即用的个人用户，Claude Code 的打磨度仍然更高。

八、落地实践建议

8.1 场景选型

个人开发：桌面客户端 + 标准模式，日常写码、文档、数据处理一站式解决
团队私有化：云服务器部署 Web UI + 内网 OpenAI 兼容网关，数据不出域
批量自动化：PTC 模式 + Python SDK，把多步骤任务编排进 CI/CD
平台研究：极简模式做基准测试，创造模式做插件与新模式实验

8.2 成本控制

工具调用密集型任务是 Token 消耗大户。三条实测有效的省钱路径：优先 PTC 模式合并多轮工具调用为一次脚本执行；利用会话缓存提高 KV-Cache 命中率（社区实测可到 99%）；结合各厂商峰谷定价，把批量任务调度到低谷时段执行。

8.3 上线路径

建议按「极简体验 → 标准模式日常使用 → 沙箱与权限调优 → 只读/工作区权限接入真实项目 → PTC/SDK 自动化」的顺序渐进推进。在预览阶段，把 DSH 定位为效率工具而非关键链路组件，等版本进入稳定期再评估生产化。

DeepSeek Harness 详解开源插件化 AI Agent 运行时：架构、模式、安装与生态

目 录