DeepSeek Harness 集成指南：Model + Harness = Agent 的开源实践
DeepSeek Harness 集成指南：让模型长出「手脚」的开源 Agent 基础设施
2026 年，DeepSeek 提出了一个简洁的公式：Agent = Model + Harness。模型负责理解、推理与生成，Harness 则赋予模型理解环境、调用工具、在真实工作流中持续工作的能力。本文整理 DeepSeek Harness（简称 DSH）的架构思路、安装集成方式与插件扩展实践，供准备上手或二次集成的开发者参考。
一、DeepSeek Harness 是什么
DeepSeek Harness 是 DeepSeek 开源的 Agent 执行框架（harness），于 2026 年 8 月发布开发者预览版并同步开源（MIT 协议），目前处于全球公开预览阶段。它既可以作为桌面应用运行，也可以通过代码启动为 Web UI。
它能做的事情覆盖典型 Agent 场景：
- 日常工作：整理资料、分析表格、撰写文档、制作汇报；
- 编码：理解仓库、修复 Bug、开发功能、运行测试；
- 调研：搜索资料、交叉查证、给出有来源的结论；
- 后台任务：运行脚本、批量处理文件、定时任务与进度跟踪；
- 插件扩展：安装现成插件，或在「创造模式」中通过对话创建插件。
二、核心架构：一切皆插件
DSH 的设计核心是 「一切皆插件」（Everything is a Plugin），整体分为三层：
- Cordis 内核：只负责插件的加载、卸载和依赖关系管理，不承载任何 Agent 具体能力。Cordis 是一个成熟的 TypeScript 插件化框架，其设计思想可参考《A Programming Paradigm for Spatiotemporal Composability》。
- 插件提供能力：模型、工具、技能、会话、沙箱、存储、循环（agent loop）、调度、UI 等 Agent 能力全部由插件提供，插件之间通过 Cordis 的服务与事件机制协作。
- 配置层自由组合：开发者不需要改动 DSH 源码，在配置层就可以选择、替换或扩展任一能力——比如换掉默认模型适配器、替换沙箱实现、定制 UI。
这种架构带来的直接好处是：集成成本低、替换自由度高。想接入自己的内部工具链，本质上是写一个插件；想深度定制 Agent 行为，也是写一个插件。
可追溯的运行轨迹
模型看到的一切都会写入仅追加（append-only）设计的会话日志，包括系统提示词、思维链、工具调用与结果、子 Agent 调度，以及每一次上下文注入。在 Trajectory（轨迹）视图中可以按来源查看这些信息；会话的恢复、分叉、检索与回放也共享同一份事件流。这对调试工具调用、审计 Agent 行为非常关键。
四种运行模式
| 模式 | 说明 |
|---|---|
| 标准模式 | 提供完整的工具组合，适合日常任务 |
| PTC 模式 | 由模型生成一段代码来组合多轮工具调用，减少往返 |
| 极简模式 | 只保留一个 shell 工具与一个文件编辑工具，用于最小环境下的模型基准测试 |
| 创造模式 | 可检查当前运行时、在内存中试验 Cordis 插件，并组合创作新的模式 |
三、安装与启动
方式一：npx 直接启动（推荐快速体验）
安装 Node.js 后执行：
npx @deepseek-ai/dsh web
- 默认在
http://127.0.0.1:3080启动 Web UI，并自动打开浏览器； - SSH 远程环境下只会打印宿主 URL（本地转发地址由 SSH 客户端持有）；
- 加
--no-open可只启动服务不打开浏览器。
方式二：源码构建
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
pnpm run build 负责准备仓库产物，pnpm dsh web 直接使用已构建产物启动，不会触发重新构建。适合需要阅读源码或做插件开发的场景。
四、集成要点
1. 模型接入
DSH 的模型能力本身也是插件。预览版默认搭配 DeepSeek 系列模型（界面上可见 DeepSeek-V4 系列 Flash 等档位），官方定位是与 DeepSeek-V4 深度协同、共同进化的一体化产品。由于架构基于「双 LLM 适配器」等抽象（仓库 ADR 中有相关设计记录），模型适配层是可替换的接缝点，具体可用模型与配置方式以官方文档为准：https://deepseek-harness.github.io/deepseek-harness/
2. 插件开发
插件是 DSH 的能力单元，一个插件可以同时扩展工具、技能和界面。官方提供了「创造模式」：直接用自然语言描述需求（例如「给我写一个番茄钟插件」），Harness 会自动加载 cordis-plugin-development 技能，完成生成代码、安装 bundle、运行验证的完整闭环——官方演示中一个悬浮番茄钟插件从零到安装验证约 5 分钟。
如果是手工开发，标准流程是：
- 创建插件包（
package.json声明 Cordis 插件入口）； - 实现 plugin 服务（注册工具、技能或 UI 插槽）；
- 通过插件管理器安装 bundle 并在运行时验证。
3. 定时任务与自动化
DSH 内置自动化任务能力，支持按计划执行重复工作。例如设置「每周五 17:00（北京时间）汇总本周项目笔记生成周报」，任务会以结构化的 prompt + 调度配置持久化，到点自动执行并产出结果。
4. 可观测性与调试
开发者工具面板可以查看执行轨迹（trajectory）与详细运行时信息，按来源过滤系统提示词、思维链、工具调用等事件。集成到生产流程前，建议先利用这套轨迹机制确认工具调用链路和上下文注入符合预期。
五、适用场景与选型建议
- 个人效率工具：桌面端开箱即用，适合文档、表格、汇报类日常任务；
- 工程团队：源码部署 + 插件机制，适合把内部 API、数据库、CI 流程封装成工具接入 Agent；
- 模型评测：极简模式只保留 shell 与文件编辑两个工具，环境噪声最小，适合做模型能力的基准对比；
- Agent 平台二次开发：Cordis 内核 + 配置层组合的设计，天然适合作为自研 Agent 平台的底座。
需要注意：预览版的核心插件和基础 API 仍在持续迭代，生产集成前建议锁定版本并关注仓库更新。
六、相关链接
- 官网：https://deepseek.com/harness
- GitHub 仓库：https://github.com/deepseek-ai/deepseek-harness
- 官方文档：https://deepseek-harness.github.io/deepseek-harness/
- Cordis 框架：https://github.com/cordiverse/cordis
参考资料：DeepSeek Harness 官网与 GitHub README（2026-10 查证）。预览版能力以官方最新文档为准。
