DeepSeek Harness：下载、Cordis、插件 DIY 与安全边界

DeepSeek Harness 的命令行名是 dsh。它把模型调用、工具执行、会话记录、权限控制和网页界面放进同一个运行时。模型负责生成下一步动作，Harness 负责把动作落到文件、Shell、浏览器、插件和日志上。

这篇文章按 2026 年 8 月 24 日可取得的 0.1.1-rc.2 整理。重点放在几件会影响实际使用的事：从哪里下载，Web UI 如何启动，Cordis 怎么组织插件，怎样写一个本地扩展，以及权限和数据会落到哪里。项目仍处于 Developer Preview。官方已提示接口会有破坏性变动，试用时应固定版本和提交，不要把它当成长期不变的生产依赖。

先把版本钉住

文中的官方事实均对应 DeepSeek 官方站点、Release 或上表中的固定提交。社区帖子和外部研究只用来补充测试维度，会标明其版本与适用范围。它们不能替代当前版本的复现。

1. 下载与第一次启动

官方提供 npm 和源码两条入口。只想看看界面和基本工作流时，npm 足够。要写插件、检查 profile 或跟踪某次行为时，直接使用固定提交的源码更省心。

npm：最短路径

下面命令来自官方 README。版本号已经写死，后续复现同一环境时不必猜测当时装到了哪个预发布包。

# 上游示例，本文未在本机执行
npx @deepseek-ai/dsh@0.1.1-rc.2 web

默认 Web UI 地址是 http://127.0.0.1:3080。这只是本机监听地址。浏览器打不开时，先检查终端是否仍在运行，再检查端口是否被别的进程占用。服务需要启动但不希望自动拉起浏览器时，加上 --no-open。

首次打开页面，先在设置 -> 模型配置提供方，再选择工作区。没有工作区时，输入框不会启用。官方文档说明密钥采用只写保存，配置后前端不会再显示明文。

页面里可以使用 DeepSeek API，也可以填写目录中已有的其他提供方。自定义 OpenAI 兼容端点时，接口兼容只是起点。模型名、输入模态、工具调用参数和流式行为都需要实测。网关写着 OpenAI-compatible，并不保证每个字段都能透传。

源码：适合开发和排错

需要本地 patch 或插件开发时，按固定提交运行源码。记录 commit、Node.js、pnpm 和操作系统版本，后面排查问题时会少掉很多无效比较。

# 上游示例，本文未在本机执行
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
git checkout b150a551b8d465e31e418e1b2eaf5e79bbb7d28e
pnpm install
pnpm run build
pnpm dsh web

pnpm run build 准备运行所需的构建产物，随后 pnpm dsh web 启动 Web UI。预发布项目的文档、包版本和插件 API 都会变化。只记下使用最新版基本无法复现环境。

2. Harness 在 Agent 执行链里做了什么

一次 Agent 任务从来不止模型回答一句话。系统需要把用户输入装进提示词，列出工具 schema，接收模型流式输出，执行工具调用，询问权限，再把结果写进会话。DeepSeek 的官方表述很直接：Agent = Model + Harness。

用户输入
  -> Agent inbox
  -> 组装 prompt 与工具 schema
  -> 模型流式输出
  -> 工具调用与权限检查
  -> 写入会话事件
  -> 继续下一步、等待审批或结束

模型看到的是上下文和可用工具。Harness 管理上下文以外的那些麻烦部分，包括工具注册、执行状态、会话持久化、沙箱策略和页面交互。把这些能力拆开后，模型提供方可以替换，工具集也能按工作区和 profile 改造。

一个 turn 可以有多个 step

官方架构将一轮模型请求及其工具调用称为 step，一个 turn 由一个或多个 step 组成。处理顺序大致如下：

turn/start
  -> 领取用户消息与队列消息
  -> agent/pre-step 检查或改写本轮输入
  -> 组装 system prompt 与工具 schema
  -> 请求模型并记录流式 chunk
  -> tool/call -> pre-execute -> execute -> post-execute -> tool/result
  -> 还有待处理输入或需要继续时，开始下一 step
turn/end

会话采用只追加的事件流，模型回复、工具调用和结果都会留下记录。恢复、分叉、搜索和回放都建立在同一条日志上。调试长任务时，这种记录很实用。处理敏感文件时，日志本身也要纳入数据边界。

3. Cordis：插件、服务和可撤销副作用

DeepSeek Harness 在仓库内以 vendor 方式使用 Cordis。模型适配器、工具注册表、会话日志、Agent loop、存储、沙箱、调度和 UI 都通过插件树组织。开发者不必先改动中心代码，很多扩展可以落在已有服务和事件上。

Cordis 里有三个经常用到的概念。

1. 服务通过 ctx.<key> 暴露，例如 ctx.tools、ctx.llm 和 ctx.sessions。插件依赖的是服务接口，具体实现可以替换。

2. inject 声明依赖。框架会在依赖就绪后挂载插件，加载顺序不需要散落在初始化代码里。

3. ctx.effect() 与 ctx.on() 记录可撤销的副作用。插件卸载或热替换后，监听器、工具和资源能被清理。

这套结构最有价值的地方在于可观察性。插件为什么没生效，可以检查依赖是否满足、配置有没有进入最终树、事件是否真的被触发。问题不必靠猜。

Cordis 的论文仓库描述了 effect tracking、配置协调和热替换的设计意图。该材料仍是修订中的预印本，适合辅助理解架构，不应把其中的描述当作已经完成同行评审的性能结论。

4. Profile、bundle 和 patch 如何叠加

一个运行中的 dsh 对应一棵插件树。官方文档把组装过程拆成 profile、bundle 和 patch 三层。

优先级由低到高依次为 profile 的 bundle、profile 自己的 cordis.patch.yml、$DSH_HOME/cordis.patch.yml，最后是命令行传入的 --patch。实际 DIY 时，优先在上层添加一条配置。改核心包会让升级和定位都变难。

下面命令可以把最终配置打印出来。插件没有加载、同名配置被覆盖、profile 选错时，先看这份输出。

# 上游示例，本文未在本机执行
dsh --profile web --dump-config

5. 从一个本地插件开始

官方教程中的最小插件只需要导出 apply(ctx)。下面例子没有假设某个复杂业务，它只要求 tools 服务已经存在。

import type { Context } from '@deepseek-ai/cordis'

export const name = 'workspace-note'
export const inject = ['tools']

export function apply(ctx: Context) {
  // 在此处注册工具、事件监听器或服务。
  // inject 保证 ctx.tools 可用后才会挂载该插件。
}

在一个独立目录里写好模块后，新建 cordis.yml，使用绝对路径将它插入插件树。

- insert:
    - id: workspace-note
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/workspace-note.ts'

# 上游示例，本文未在本机执行
pnpm dsh web --patch ./scratch-plugin/cordis.yml

先用这种 patch 方式验证扩展点。想加工具时，从 ctx.tools 入手。需要拦截模型请求或工具执行时，使用对应的 agent/*、tools/* 事件。只有要给多个插件提供稳定能力时，再引入 Service。插件边界越小，排错成本越低。

配置与资源清理

插件可以导出同名 Config schema，让 Cordis 校验 cordis.yml 并填充默认值。可调参数放进配置，不要散落在 TypeScript 常量里。配置变化会触发插件替换，定时器、文件句柄和事件监听器要在 ctx.effect() 返回的 disposer 中清理。

少了这一步，第一次加载也许看起来正常。改一次配置以后，旧监听器仍会运行，重复注册的工具也会留在会话里。此类问题很难从模型输出中看出来。

从 patch 到 bundle

本地验证通过后，可以把插件做成声明 dsh.bundle 的 npm 包，再安装到指定 profile。

# 上游示例，本文未在本机执行
dsh plugin --profile demo add ./hello-plugin
dsh --profile demo --dump-config
dsh --profile demo

官方也支持从 Git 安装插件。Git 来源包含源码，若依赖 prepare 这类构建步骤，pnpm 会要求用户授权在本机运行它。这个构建过程发生在 Agent 运行时沙箱之外。团队分发时，优先选择预构建的 npm 包或 tarball。必须使用 Git 时，审查源码并固定具体 SHA。

6. 四种模式，按最小能力开始

DeepSeek 官方列出 Standard、Code、Minimal 和 Creator 四种模式。它们对应不同的插件组合和工具集合。

第一次接入自己的模型或插件时，Minimal 很适合做底线测试。它暴露的能力少，输入、输出和副作用更容易对齐。插件加载问题则可以用 Creator 或 --dump-config 观察。功能越多，排查范围也会变大。

7. 沙箱、权限和数据流

文件系统策略只覆盖文件系统

官方文档定义了三档文件系统效果：

策略会按工具调用解析。官方的沙箱文档明确把网络与进程可见性放在另一层能力里。要隔离完整执行环境，需要容器、虚拟机或远程运行器。把 read-only 当成全部防护，会遗漏最重要的攻击面。

先为高风险动作留审批

DeepSeek 的安全使用政策提到，Agent 能执行本机代码和操作系统动作，不可信网页和工具输出可能携带间接提示注入。个人开发环境可以从下面几条开始：

1. 把试验放进低权限虚拟机、容器或专用目录，不直接接触主力项目和个人资料。

2. 删除、发布、读取密钥、安装依赖和联网提交等动作保留人工审批。

3. 审查模型生成的命令与代码。网页正文和工具输出只能算输入，不是可信指令。

4. 只接入审查过的插件、MCP、Skill、Hook 与依赖。Git 安装使用固定 SHA。

5. 将大任务切成小步骤，逐步观察工具调用和文件差异。

腾讯朱雀实验室的一篇外部预印本在固定 DSH 提交、单一模型后端和未启用其加固方案的受控基线里测试了间接提示注入。它提醒开发者，模型侧防护无法取代隔离和审批。研究针对的是特定版本与本地模拟安全 sink，不能外推出所有部署的漏洞率。

本地存储不等于整条链路都在本地

官方数据处理说明称，Harness 默认在用户设备上处理和保存会话上下文、工具调用记录、文件路径、执行结果、日志和模型配置等信息。文档也提到匿名化配置与项目列表的上报选项，用户可以关闭或修改上报地址。

模型端点、网页工具、MCP、插件和外部服务会各自处理传给它们的数据。接入新服务前，单独查看它的隐私政策、数据保留方式和地域设置。API key 能保存在本机，不代表附件、提示词、代码片段和工具结果没有离开设备。

8. 社区材料如何使用

项目发布较新。公开 Discussion 和 Issue 里出现过 Web UI 地址、会话恢复、旧版 Windows 目录选择、较旧 Linux 工具链构建等问题。很多内容只对应 0.1.0-rc.6 或更早版本，也不一定有维护者确认。

看到一条报错时，先对齐这几个变量：提交 SHA、操作系统、Node.js、pnpm、profile、模型提供方和插件列表。再看 Issue 是否有修复 PR 或 Release 注释。最后才在隔离工作区复现。预览版里，旧问题的搜索排名经常比它的有效期长。

9. 适合什么任务

Harness 很适合用来学习和原型化 Agent runtime，也适合需要替换模型、组合工具、记录任务事件、编写插件或维护多套 profile 的开发场景。它让这些部件可以在一个运行框架里观察和修改。

需要稳定兼容承诺、成熟插件供应链、固定性能指标或高敏感生产环境时，先做小范围验收。用独立工作区跑完一次模型配置、受限工具调用、会话回放、插件加载和卸载清理。把 Release、破坏性变更和关键 Issue 纳入升级检查表。通过这几项以后，再扩大权限和工作区范围。

10. 第一次试用的检查单

• 从官方 npm 或仓库安装，并记录包版本或 commit。

• 用测试目录和非敏感数据启动第一次会话。

• 确认模型提供方、密钥存储位置和外部服务的数据流。

• 运行 --dump-config，检查 profile 与 patch 是否进入最终配置。

• 从 read-only 或不写入工作区的任务开始，再评估 workspace-write。

• 先用本地 patch 验证插件，确认 disposer 能清理资源，再做 bundle 分发。

• Git 安装插件时审查源码、锁定 SHA，并谨慎授权构建脚本。

• 升级前阅读 Release，并复查沙箱、会话和插件相关 Issue。