DeepSeek Harness 深度入门:插件架构、上手路径与任务实践
从“一切皆插件”的 Cordis 架构出发,详解 DeepSeek Harness 的 Agent 循环、模型与工作区配置、最小插件开发及执行边界,并通过工单 CSV 简报案例说明任务约束、产物核验和故障排查,配三张原创中文示意图。

文章目录
本文面向希望理解、试用或扩展 AI Agent 工作台的开发者与技术使用者,依据 2026 年 11 月 6 日查阅的 DeepSeek Harness 官网、仓库及开发文档整理。项目处于开发者预览阶段,接口和配置可能发生不兼容变化;命令与代码应以实际使用的包版本或源码提交为准。本文未在目标环境安装或运行 Harness,案例结果为可人工核对的教学预期。
让 AI 回答一个问题,与让 AI 完成一项工作,中间相隔着许多工程环节:它需要看到哪些文件?能调用哪些工具?命令失败后怎么办?谁批准写入?最后交付的文件是否真的存在、内容是否正确?
DeepSeek Harness 关注的正是这层“把模型接到工作环境里”的能力。它既提供面向用户的工作台,也提供可组合、可扩展的 Agent 运行基础。本文从日常任务出发,逐步讲清模型、工具、插件、执行循环与权限之间的关系。
阅读路线:先理解第 1—3 节的架构,再按第 4—5 节设计第一次试用;准备开发扩展时重点阅读第 6—7 节,最后用第 8—9 节的方法检查结果。
一、Harness 是什么:模型如何走向实际工作?
在 AI Agent 的语境中,Harness 可以理解为围绕模型构建的运行环境:组织上下文、暴露工具、调度执行、保存过程,并把结果呈现给用户。
DeepSeek 官方将 DeepSeek Harness(命令简称 dsh)定义为开源的 Agent Harness,基于 Cordis 构建,采用“一切皆插件”的架构。官网展示了文档与表格处理、代码任务、插件扩展、自动化及运行信息查看等方向。项目官网、官方仓库
可以用下面的分工建立直觉:
| 层次 | 主要负责什么 | 不能直接等同于什么 |
|---|---|---|
| 模型 | 理解问题、生成内容、提出工具调用 | 不直接拥有本机文件或进程权限 |
| Harness | 连接模型与环境,组织任务执行过程 | 不保证每项任务一定成功 |
| 工具 | 读取文件、执行命令、调用具体服务 | 工具返回成功不等于业务结果正确 |
| 插件 | 为运行时提供或组合服务、工具、界面等能力 | 不等于只有提示词的说明文档 |
| 工作台 | 让用户选择工作区、发起任务、查看产物和过程 | 不自动构成安全隔离环境 |
例如,模型可以建议“读取 CSV 并按状态统计工单”,但真正打开文件的是执行环境中的工具;模型可以输出一段修改建议,但文件是否写入、测试是否通过,需要观察实际执行结果。
因此,评价 Harness 应关注完整链路:任务是否表达清楚、执行是否受控、失败是否可定位、产物是否能够核验。
二、一切皆插件:从功能堆叠到运行时组合

图 1:原创概念图。图中的模块表示职责,不代表必须拆成独立进程;实际能力由所选配置与插件决定。
2.1 重要的不只是“可以安装插件”
很多软件会在固定核心之外增加插件入口。DeepSeek Harness 的架构文档则把模型适配、工具注册、会话日志、Agent 循环等本身也作为插件组织。扩展可以挂接到公开能力接口,而不是每次修改一套不可替换的核心流程。架构文档
这种设计的意义,在于能够替换或重组能力。例如,相同的任务交互可以配合不同模型适配器;同一个工具接口可以由不同执行后端实现。但能否替换、需要哪些依赖,以及行为是否一致,仍应遵循对应接口契约。
可替换与等价是两件事:两个执行后端都能启动命令,不意味着它们拥有相同文件、环境变量、系统依赖或网络访问条件。更换后端后,应重新验证实际任务。
2.2 Cordis 提供的三个关键概念
Cordis 是插件之间协作的基础。初次阅读时,可先抓住三点:
- Context 与服务:插件通过上下文中的服务接口使用能力,例如模型、工具或会话服务,降低对具体实现的直接耦合。
- 依赖与事件:插件声明所需服务,通过具有明确语义的事件进行协作;观察、顺序处理和拦截不是同一种行为。
- 生命周期与清理:通过上下文注册的能力和显式管理的资源,在卸载时按生命周期清理。Cordis 入门
对开发者而言,这意味着“加一个功能”还需要回答:它依赖哪个服务、在哪个阶段介入、卸载后如何释放资源。仅把代码运行起来,并不足以证明插件能够稳定重载。
2.3 Profile、Bundle、Patch 分别是什么?
| 名称 | 可以怎样理解 | 使用时需要注意 |
|---|---|---|
| Profile | 一套具名的运行组合 | 不同入口或用途可以采用不同组合 |
| Bundle | 分发插件代码及相关配置的组合单元 | 安装了包,不代表所有能力都已启用 |
| Patch | 在已有组合上应用的配置覆盖或插入 | 核对目标条目和覆盖范围 |
架构文档描述了按层组合插件树的方式。配置覆盖某个条目时,不能想当然地把它理解成任意深度的字段合并;修改前应核对当前 Patch 语义,保留仍然需要的配置。
插件管理也有作用范围:当前文档说明,Profile 级插件变更会影响使用该 Profile 的会话;配置是否立即生效,还取决于是否启用相应的热更新能力。插件管理说明
试验扩展时,使用独立测试组合比直接修改多人共用的组合更容易控制影响。
三、Agent 如何完成任务:请求、执行、观察、再继续

图 2:用于理解的简化流程。实际事件、调度和错误处理应以当前实现为准。
3.1 一次任务通常需要多次模型请求
假设用户要求“读取项目工单,生成状态简报”。Agent 可能先列出文件,再读取表头,之后运行统计脚本,检查输出,最后解释结果。这些动作不一定能在一次模型请求中完成。
官方实现将 Step 与 Turn 区分开:可以把 Step 理解为一次模型请求及其相关工具调用,而一次 Turn 可以包含多个 Step。默认 Agent 循环负责驱动模型交互与工具使用,具体工具执行器负责调用调度、取消和相关记录。Agent 循环说明
理解这个区别有助于诊断耗时:长时间未完成,可能是模型请求慢、工具执行慢、审批待处理,也可能是任务持续尝试但没有收敛。
3.2 工具调用提议不等于已经执行
工具执行流水线会在调用过程中应用策略、检查、执行与结果处理。需要审批却未获得批准时,不能把“模型已经提出调用”当成“工具已经运行”。工具执行流水线
查看过程时,应区分三种信息:
| 信息 | 说明什么 | 仍需检查什么 |
|---|---|---|
| 模型计划 | 想要做什么 | 是否实际发起调用 |
| 工具结果 | 本次调用返回了什么 | 参数、退出状态、错误和真实产物 |
| 最终总结 | Agent 如何解释执行结果 | 是否准确引用证据,是否遗漏失败 |
例如,命令退出成功可以证明脚本正常结束,但还需要检查结果文件是否为空、统计范围是否正确。相反,工具被拒绝后,模型也不应根据自己的计划写成“报告已生成”。
3.3 会话记录帮助解释过程,但不是事务回滚
架构文档以会话事件记录组织历史,并从中构建模型上下文和多种运行视图。它帮助开发者追踪输入、请求和工具结果的关系。
需要避免两种误解:第一,保留会话不意味着每次重试都会得到相同答案,模型、输入文件和外部服务都可能变化;第二,能够查看历史不等于能够撤销文件写入、已发送请求或其他外部副作用。
涉及重要文件时,应另有版本控制或备份;涉及外部写操作时,应另有幂等和业务恢复设计。
四、如何上手:先完成一个范围明确的小任务
4.1 选择合适的入口
| 方式 | 适合谁 | 起点 |
|---|---|---|
| 桌面端 | 希望直接使用工作台的用户 | 从官方页面下载适配系统的版本 |
| npm 启动 Web UI | 已有 Node.js 环境、希望快速体验的用户 | 使用官方命令启动本地工作台 |
| 源码运行 | 需要调试、阅读或开发插件的开发者 | 克隆仓库、安装依赖并构建 |
官网提供桌面下载入口,本文主要解释 Web UI 与源码路径。界面、模型配置和所带插件可能随版本变化。官方入口
4.2 从 npm 启动 Web UI
准备符合当前包要求的 Node.js 环境后,官方 README 给出的入口为:
npx @deepseek-ai/dsh web
当前 README 说明,本地启动默认使用 http://127.0.0.1:3080 并打开浏览器;添加 --no-open 可以只启动服务。首次使用 npx 可能需要下载包,实际监听地址应以终端输出为准。运行说明
这一步只是启动运行环境,还需要配置可用模型和工作区。安装应用也不等同于已经取得模型调用权限或额度。
4.3 源码运行与环境要求
官方源码路径为:
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
当前开发指南要求 Node.js 24.9 或更高版本,并使用仓库指定的 pnpm 工具链。构建完成后,pnpm dsh web 使用已构建的产物,不会自动替你重新构建所有源码修改。开发指南
Windows 可以使用原生环境,也可以选择 WSL 2。源码、依赖和工具链应保持在同一个系统环境内;不要复用另一个系统安装出来的依赖目录。试用时先选择一种环境,减少文件路径与原生依赖差异带来的干扰。
4.4 配置模型并选中工作区
官方 Web UI 指南的基本顺序是:打开“设置 → 模型”,完成模型配置,然后添加并选中项目工作区。全新 Web UI 未选工作区时,会话输入框不可用。Web UI 入门
模型、服务地址与协议要相互匹配。凭据被检测到,不代表连接或鉴权一定成功;先用不含业务资料的简单问题验证请求,再接入文件。自定义端点还需核对模型标识、输入类型与请求兼容性。模型配置指南
第一次任务可以只要求读取一个测试目录并解释文件结构,确认读取范围和工具输出。之后再增加写入产物、运行脚本或使用扩展能力。
五、完整案例:把工单 CSV 变成项目状态简报
下面是一个可在独立测试工作区复现的任务设计。它说明怎样约束任务、检查计算和验收产物,不代表本文已经在 Harness 中执行。
5.1 准备一个足够小的输入
建议目录结构如下,input 保存输入,output 保存生成结果:
harness-demo/
input/
tickets.csv
output/
示例 tickets.csv 内容:
ticket_id,component,status,priority
T001,login,done,P1
T002,payment,in_progress,P0
T003,payment,done,P1
T004,analytics,blocked,P2
约定每行是一个工单,ticket_id 唯一;status 只接受 done、in_progress、blocked,分别表示完成、处理中、阻塞。它是一份当前状态快照,没有创建和完成时间,不能据此推断本周吞吐量、处理时长或团队效率。
5.2 把需求写成可核验的任务
可以用下面的任务说明开始:
请只读取 input/tickets.csv,先检查字段、工单编号唯一性和状态取值。按状态及模块统计工单,计算当前快照的完成占比,并列出尚未完成的 P0 工单。
原始输入保持不变,结果仅写入 output/metrics.csv 和 output/status-report.html。HTML 中说明输入文件、统计口径、结果表与数据限制。
不访问外部网络,不安装依赖,不修改输入目录。不把未完成项描述为已解决;缺少时间字段时不要计算周期效率。如现有工具或依赖无法完成,请明确说明缺口。结束前检查两个产物是否存在,并说明验证结果。
这段描述给出了对象、允许动作、交付文件和边界。文字要求还需要与实际权限配置配合,不能把提示词当成操作系统级访问控制。
5.3 预期应得到什么?
四条数据可以直接人工核对:
| 检查项 | 预期结果 |
|---|---|
| 工单总数 | 4 |
| 完成 | 2 |
| 处理中 | 1 |
| 阻塞 | 1 |
| 当前快照完成占比 | 2 ÷ 4 = 50% |
| 未完成 P0 | T002,payment 模块 |
按模块核对时,login 有 1 条已完成,payment 有 2 条且完成 1 条,analytics 有 1 条阻塞。各模块数量应合计为 4,各状态数量也应合计为 4。
若结果写成“本周解决率 50%”,计算虽然相同,业务含义却已经改变:输入没有给出本周新增、完成时间或观察窗口。这正是人工核验需要发现的语义问题。
5.4 验收不只看页面好不好看
一个完整的验收过程至少包括:
- 对比输入,确认没有静默删除、重复或改写工单。
- 检查异常值如何处理,未知状态不能悄悄归入“完成”。
- 打开 metrics.csv,核对总数、分组与百分比。
- 打开 HTML,检查标题、表格、编码与显示效果。
- 核对总结是否准确说明执行成功、失败或未验证的部分。
如果需要扩展到自动化任务,应先让同一输入能稳定通过这些检查,再考虑触发方式、并发、重复执行和产物保留。定时运行并不能自动修复不清楚的统计口径。
六、开发一个最小插件:先理解加载与清理
当重复需求已经明确,再考虑编写扩展。第一次插件开发,最好只验证生命周期,不同时引入网络、数据库和复杂界面。
6.1 创建一个简单的 TypeScript 模块
以下示例基于官方“第一个插件”教程的 apply(ctx) 与 ctx.effect() 形式编写。它只输出状态日志,不注册模型工具,也不自动处理上一节的 CSV。插件入门教程
在完成源码构建的仓库中,新建 scratch-plugin/src/status-note.ts:
import type { Context } from '@deepseek-ai/cordis'
export const name = 'status-note'
export function apply(ctx: Context) {
console.log('[status-note] ready')
ctx.effect(() => {
const timer = setInterval(() => {
console.log('[status-note] active')
}, 60_000)
return () => clearInterval(timer)
})
}
apply 是加载入口。ctx.effect 接收资源创建逻辑,并通过返回的清理函数释放计时器。不要把“使用 Cordis”理解成所有任意创建的资源都会自动被回收;应按框架要求管理注册,并为显式资源提供清理逻辑。
6.2 使用 Patch 加载本地插件
新建 scratch-plugin/cordis.yml。下面路径只是 Windows 示例,需要替换成你自己的源码文件绝对路径:
- insert:
- id: status-note
name: 'D:/experiments/deepseek-harness/scratch-plugin/src/status-note.ts'
从仓库根目录启动:
pnpm dsh web --patch ./scratch-plugin/cordis.yml
如果已有 Web 服务占用默认端口,应先处理旧进程或按当前启动配置使用其他端口。插件文件使用绝对路径,是因为 Patch 文件的位置并不会自动改变插件模块路径的解析基准。
验证时,先查看启动日志是否出现 ready,再观察定时日志;移除或禁用该条目并触发实际卸载后,检查计时器是否停止。退出整个进程也应完成资源释放。不同组合的热更新行为可能不同,不能只改了配置文件就假定已卸载。
6.3 从演示插件演进到业务能力
真正的工单报告扩展,需要设计输入、结果、异常和副作用边界:
| 设计项 | 应明确的问题 |
|---|---|
| 输入契约 | 路径范围、编码、文件大小、字段和枚举是否合法? |
| 计算职责 | 固定计算是否由确定性代码完成,模型负责什么? |
| 工具结果 | 如何表示成功、错误、告警和生成文件? |
| 写入策略 | 是否覆盖旧文件,失败后如何避免半成品? |
| 生命周期 | 文件句柄、进程、连接和事件监听如何释放? |
| 可观测性 | 日志能否定位问题,是否包含不应记录的数据? |
对确定的计数、去重和比例,优先用可验证的代码实现;让模型解释结果、组织文案与提出下一步。工具注册、界面扩展等 API 应查对应版本的开发参考,不要把本节的日志示例误认为完整业务插件。
七、权限与执行边界:插件、工作区和沙箱分别保护什么?

图 3:边界核对示意。它用于解释需要检查的路径,不代表系统默认提供完全隔离。
7.1 先理解官方对预览版的定位
官方安全说明指出,项目仍是实验性开发者预览软件,尚未完成安全审计,不能作为已具备生产安全保障的软件使用。它可以运行模型生成的代码、加载第三方插件,并访问实际授予的文件、网络和凭据等资源。官方安全说明
首次试用应使用最小权限和可丢弃的测试环境,准备文件备份,核对插件与命令;不要把沙箱或审批当成唯一保护手段。被允许访问的资源,仍可能因错误操作受到影响。
7.2 Host 插件不等同于沙箱里的命令
插件管理文档明确说明,已安装的 Host 插件代码在宿主进程中运行,处于工作区沙箱之外。因此,安装插件是一项代码信任决策,不能只检查插件声称提供的工具名称。
需要区分以下控制层次:
| 层次 | 主要作用 | 仍需核对 |
|---|---|---|
| 工作区 | 指明项目与任务上下文 | 实际可访问和可写的范围 |
| 工具策略与审批 | 控制具体调用是否允许 | 参数、对象和可能产生的副作用 |
| 文件与进程执行后端 | 决定命令和文件操作在哪里发生 | 挂载、网络、凭据与资源限制 |
| 插件代码信任 | 决定哪些代码进入运行时 | 来源、版本、依赖和宿主权限 |
在桌面端、本地 Web 和远程环境之间切换时,还要确认“文件在哪里”“命令在哪里运行”“模型请求发往哪里”。浏览器在本机打开,并不代表所有处理都在本机完成。
7.3 三个容易混淆的“撤销”
- 卸载插件可以清理已管理的注册与资源,但不能自动撤回已经发送的数据。
- 取消任务不证明外部操作完全没有发生,尤其是远程请求超时或取消时。
- 查看会话历史可以帮助追踪,但不会自动恢复被修改的文件。
涉及外部写入时,应独立设计幂等键、结果查询与补偿;涉及文件覆盖时,应考虑临时产物、验证后替换和旧版本保留。这些是业务扩展需要落实的工程措施。
八、如何判断一次任务是否完成?
8.1 保留从输入到结果的证据链
一份有用的任务完成说明,应包含输入范围、所用规则、实际执行动作、生成产物、验证方法和剩余限制。
以工单案例为例,“已完成分析”不够具体;“读取 4 条记录,得到 2 条完成、1 条处理中、1 条阻塞,输出两个文件并核对总数为 4”才便于检查。若 HTML 未能打开预览,也应如实标记该项尚未验证。
官网展示的运行信息查看能力,可以帮助定位模型请求和工具调用,但“是否满足业务目标”仍需按照任务约定验收。
8.2 先定位失败在哪一层
| 现象 | 优先检查 |
|---|---|
| 页面能打开,但输入框不可用 | 是否已选中工作区、模型是否可用 |
| 模型请求失败 | 凭据、服务地址、协议、模型标识和服务响应 |
| 计划写得完整,却没有文件 | 是否实际调用工具、是否被拒绝、输出路径是否正确 |
| 插件装了但功能没出现 | 是否加载到当前组合、依赖是否满足、是否需要重启 |
| 修改源码后仍是旧行为 | 是否重新构建、运行的是否为正确产物与进程 |
| 任务一直反复执行 | 错误是否被准确返回、是否存在明确结束条件和预算 |
| 数字或结论不对 | 输入、清洗、统计口径和工具计算,而不只是最终文案 |
不要通过扩大权限来掩盖尚未定位的问题。例如,文件路径错误、模型协议不匹配和插件未启用,都不应以“授予全部访问”作为默认修复办法。
8.3 为重复任务建立小型评估集
可以保留几组无敏感信息的输入,覆盖正常数据、空文件、重复编号、未知状态、不可写目录和中途取消。固定预期结果后,每次升级模型、插件或运行环境,都重新比较。
评估时同时记录正确性、实际完成率、人工修正次数、耗时和调用成本。只有成功案例的演示,无法说明失败时能否给出清楚、可恢复的结果。
九、从一次试用走向可维护的工作流
建议按以下顺序推进:
- 用独立测试工作区验证模型调用和文件读取。
- 用四条示例工单跑通输入、计算、产物和验收。
- 固定重复规则,明确哪些由代码计算、哪些由模型解释。
- 再开发插件或接入外部能力,补齐权限与生命周期设计。
- 在小型评估集通过后,才扩大数据和任务范围。
DeepSeek Harness 的核心价值,是提供一种可组合的 Agent 运行方式,让模型、工具、会话、界面和执行策略能够协同工作。理解这种设计后,使用者更容易表达清楚任务,开发者也更容易把扩展放到合适的位置。
真正可持续的工作流,应能回答三件事:任务在哪里执行、结果凭什么可信、失败之后怎样处理。
参考资料与图示说明
- DeepSeek Harness 官网与GitHub 仓库:产品入口、预览状态和运行方式。
- 架构文档、Cordis 入门:插件组合与协作机制。
- Web UI 入门、模型配置、开发指南:配置与开发环境。
- 插件入门、插件管理:加载、生命周期与变更范围。
- 工具执行流水线、Agent 循环、安全说明:执行机制和适用边界。
封面为 AI 生成的模块化 Agent 工作台概念插画,非 DeepSeek 官方素材或产品截图;正文三张中文图为原创示意。代码与案例用于学习,未在目标环境实跑,不构成产品性能或生产可用性承诺。




交流与讨论
留下你的思考,友善交流。昵称和评论将公开展示,请勿填写个人敏感信息。