DeepSeek Harness 中文实测：安装、模型配置、插件机制与 OpenCode 对比

DeepSeek Harness 刚出现时，最容易产生两个误解：一是把它当成“DeepSeek 模型的另一个聊天界面”，二是因为官方口号是“一切皆插件”，就把它等同于普通插件市场。

实际上，DeepSeek Harness（命令名 dsh）更接近一个可组合的 Agent 运行框架。模型适配器、工具、会话日志、沙箱、审批策略、Web UI，甚至 Agent Loop 本身都可以由插件组成和替换。它可以使用 DeepSeek，也支持 Anthropic、OpenAI 和自定义 OpenAI-compatible Provider。

我在隔离目录测试了 0.1.1-rc.2：CLI 可以运行，Web UI 成功启动并返回 200，一个最小 TypeScript 插件也成功加载。但安装和参数行为并非完全顺滑，官方也明确把当前版本标记为 Developer Preview，并警告未来会有破坏兼容性的变更。

版本复核（2026-09-23）

下文的安装、插件和模型任务记录仅适用于 2026-08-22 测试的 0.1.1-rc.2，不能代替当前版本的结论。2026 年 9 月 23 日复核时，官方最新预发布已到 0.1.7-alpha.2；这一代版本已经出现 Agent Team、后台任务与工作流、性能与用量面板、会话 V4、Headless JSON 事件、权限预设和更完整的插件配置能力。官方仓库仍将项目标为 Developer Preview，并明确提醒可能出现破坏兼容性的变更。

这意味着旧版命令、Profile、Patch、默认工具和会话格式都不能直接假设在新版保持不变。本次复核只核对了官方仓库和发布说明，没有安装 0.1.7-alpha.2 或复跑模型任务；升级前仍应在隔离目录重新验证 CLI 帮助、Web 启动、插件加载、Provider、审批与沙箱边界，再决定是否迁移。

先看实测结论

这次测试证明了“安装—启动—加载插件”的最小闭环，不证明模型质量，也不证明它适合直接进入生产环境。

真实模型任务：先遇到余额不足，充值后跑通

随后我使用权限为 600 的临时凭据文件，在同一个隔离项目中调用 Harness 默认路由 deepseek-official/deepseek-v4-flash。任务要求 Agent 先运行失败测试，只修复 sum() 的加减号，再重新运行测试。

请求在 1.77 秒后结束，Harness 返回：

dsh: QUOTA: Insufficient Balance

这说明请求已经进入 DeepSeek Provider 的真实认证与配额检查，但账户余额不足，模型没有生成回复，也没有触发读文件、改代码或运行命令。测试后再次执行 npm test，结果仍是 -10 !== 10，math.js 保持原样；临时凭据文件随后已删除。

账户充值后，我没有换题、放宽权限或修改测试，而是用相同项目和提示再次运行。第二次 Headless 任务在 15.84 秒内完成，模型把 math.js 中唯一的减号改为加号：

return values.reduce((total, value) => total + value, 0)

Harness 的最终报告说明修改前是 -10 !== 10，修改后输出 tests passed，并声明没有改动 package.json 与 test.js。为了避免只相信模型自报结果，我在进程退出后独立执行 npm test，同样得到：

tests passed

目录中仍只有原来的三个文件，test.js 仍检查 sum([2, 3, 5]) === 10。这补齐了模型—工具—编辑—测试的最小闭环。它只能代表当前版本、当前模型和这个单行错误，不能外推到大型仓库。

本次 Headless 标准输出没有提供 Token 或费用字段，因此本文不填写估算数字；实际费用应以 DeepSeek 控制台账单为准。测试结束后，权限为 600 的临时凭据文件已删除。

DeepSeek Harness 到底是什么

传统 Coding Agent 往往先提供一个完整产品：终端或桌面客户端、内置工具、固定的 Agent Loop，再开放少量扩展点。DeepSeek Harness 的思路更底层：运行中的 dsh 是一棵插件树，由 Profile、Bundle 和 Patch 逐层组合。

官方架构文档把核心能力拆成多个可替换部分：

• session 记录仅追加的会话事件；
• system-prompt 组装提示词和工具 Schema；
• tools 管理工具注册与执行流水线；
• agent-loop 驱动模型请求、工具调用与轮次；
• 文件系统、Shell、沙箱和子 Agent 都通过各自的能力接口接入。

所以“一切皆插件”的实际价值不是装主题，而是允许开发者替换模型适配器、执行环境、工具、安全策略和会话行为。代价也很直接：概念和配置层次比即装即用的聊天客户端更多。

安装前先检查 Node.js

当前仓库 package.json 声明的 Node.js 要求是：

^22.19.0 || >=24.0.0

先检查本机环境：

node --version
npm --version

官方最短启动命令是：

npx @deepseek-ai/dsh web

它默认在 http://127.0.0.1:3080 启动 Web UI，并尝试打开浏览器。服务器或 SSH 环境建议关闭自动打开：

npx @deepseek-ai/dsh web --no-open

不要为了远程访问直接把监听地址改成 0.0.0.0 并暴露到公网。Agent 能读写工作区、执行命令并接触模型凭据，远程访问应放在经过认证和网络访问控制的环境后面。

本次安装遇到的两个真实问题

npm 长时间没有完成

本机默认 npm 缓存里存在历史遗留的 root-owned 文件，第一次 npm install 长时间停留在依赖解析阶段，目标目录仍为空。npm cache verify 给出了权限错误。

我没有直接修改整个用户缓存的所有权，而是先换成隔离缓存排除环境污染。随后改用项目本身采用的 pnpm，在临时目录完成安装。

这不是 DeepSeek Harness 必然存在的错误，但说明排错时要区分“包本身失败”和“本机缓存权限异常”。不要看到安装卡住就反复使用 sudo npm install，否则会继续制造 root-owned 文件。

pnpm 提示构建脚本被忽略

安装完成时，pnpm 报告部分依赖的构建脚本未获批准，包括 node-pty、koffi 等。尽管本次 CLI、Web UI 和最小插件仍可运行，但涉及原生终端或其他原生能力时，不能据此断言所有功能都完整。

应先审查脚本来源，再根据团队供应链策略决定是否批准，而不是为消除警告无条件运行所有安装脚本。

启动 Web UI

为了不读取个人配置，我使用了独立的 Harness Home：

export DSH_HOME="/path/to/an/isolated/dsh-home"
dsh web --host 127.0.0.1 --port 3196 --no-open

进程输出：

dsh web: http://127.0.0.1:3196

首页实际返回 HTTP 200，标题为 DeepSeek Harness。启动目录会作为默认文件系统位置，但新 Web UI 不会自动选中工作区；进入界面后仍需显式添加和选择工作区，之后输入框才可用。

第一次测试不要指向包含生产密钥、客户代码或个人资料的目录。创建一个小型临时仓库，更容易看清 Agent 到底读了什么、改了什么、运行了什么。

配置 DeepSeek 和其他模型

Web UI 中进入“设置 → 模型”，可以直接填写 DeepSeek API Key。官方说明密钥是只写字段：保存后，前端只收到脱敏描述符，明文保存在：

$DSH_HOME/.credentials.yaml

普通设置则保存在 $DSH_HOME/settings.yaml，其中只引用凭据，不应复制明文 Key。

对于 OpenAI、Anthropic 等目录 Provider，可以在模型页选择 Provider 并保存对应凭据。AWS Bedrock、Vertex、Azure 和 Codex 等原生认证方式还需要各自的 AWS 凭据、ADC、api-version 或 OAuth，不能只填一个 API Key。

本次使用临时 DeepSeek Key 发起了真实请求：首次因余额不足失败，充值后相同任务成功完成文件修改和测试。以下 Provider 配置路径仍以当前官方文档为准。

自定义 OpenAI-compatible Provider

公司网关、自建模型服务或未收录的 Provider，可以通过“添加自定义提供方”填写：

• 永久的小写 Provider ID；
• 显示名称；
• Base URL；
• API 协议；
• API Key 或凭据引用；
• 至少一个模型 ID。

Provider ID 会进入请求、会话、默认模型和凭据引用，保存后不适合随意改名。要改名时，官方建议新建 Provider，再删除旧项。

一个容易踩坑的地方是“OpenAI-compatible”并不保证请求字段完全一致。有些网关不接受 developer 角色，或只认 max_tokens 而不是 max_completion_tokens。当前官方文档给出的兼容修正示例是：

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: my-model

这里的开关只是告诉 Harness 应该怎样构造请求，不会自动证明服务端真的兼容。保存后仍要用最小请求验证 401、404、字段错误和返回结构。

如果你需要先理清 Provider、Base URL、模型名和密钥的职责，可阅读OpenAI 兼容 API 多模型统一配置。

最小插件实测

我创建了一个不访问网络、不修改文件，只打印加载日志的 TypeScript 插件：

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

export const name = 'article-test-plugin'

export function apply(_ctx: Context) {
  console.log('[article-test-plugin] loaded')
}

Patch 文件使用绝对路径插入插件：

- insert:
    - id: article-test-plugin
      name: '/absolute/path/to/hello-plugin.ts'

官方插件教程当前写的是：

dsh web --patch ./article-test-plugin.cordis.yml

但在实测的 0.1.1-rc.2 中，web 别名返回：

error: unknown option '--patch'

改成 CLI 顶层 Profile 形式后成功：

dsh --profile web \
  --patch ./article-test-plugin.cordis.yml \
  --host 127.0.0.1 \
  --port 3196 \
  --no-open

终端出现：

[article-test-plugin] loaded
dsh web: http://127.0.0.1:3196

加载插件后首页仍返回 HTTP 200。这是当前版本中“一切皆插件”最小路径的真实验证，也说明 Developer Preview 阶段应优先相信当前 CLI 的 --help 和实际结果，而不是机械复制文档命令。

插件机制为什么值得关注

插件导出 apply(ctx)，通过上下文注册服务、事件或工具。使用 ctx 注册的监听器、工具和定时器，在插件卸载时会自动清理；需要手动释放的网络连接等资源可以通过 ctx.effect() 声明清理函数。

如果插件依赖工具注册表或模型服务，需要声明依赖，例如：

export const inject = ['tools']

Cordis 会等待依赖就绪后再加载插件。配置则使用 Schemastery 定义 Schema，使错误配置在加载时直接失败，而不是带着无效参数继续运行。

这套机制更像可组合应用内核，而不是简单的“把一段 Prompt 放进插件目录”。开发者需要理解服务、依赖、事件、Profile 和 Patch，才能安全地替换核心能力。

权限、沙箱和密钥边界

官方 Web UI 说明 Agent 可以读取和编辑工作区文件、运行命令、委派工作并维护计划；某些操作会根据权限策略请求审批。

审批不等于完整隔离。测试时至少做到：

• 只绑定 127.0.0.1，不直接暴露公网；
• 使用专门的测试工作区和 DSH_HOME；
• API Key 只放凭据存储或环境变量；
• 不把家目录、SSH 配置或生产仓库作为第一个工作区；
• 审查插件来源、安装脚本和它声明的依赖；
• 对不可信任务使用容器、虚拟机或受限执行环境。

Agent Harness 的扩展能力越强，供应链和权限边界就越重要。 服务端密钥的加密落盘、轮换和泄露处置流程可继续参考大模型 API Key 安全实践，不要把 Harness 自带的凭据存储等同于完整的组织级密钥治理。

DeepSeek Harness 和 OpenCode 怎么选

如果目标是“马上用 AI 修改代码”，先看OpenCode 中文安装与真实任务实测更直接。如果目标是搭建可替换模型、工具、沙箱和会话机制的 Agent 平台，DeepSeek Harness 更值得研究。

这不是模型质量排行榜。两者可以连接不同模型，结果会受到模型、提示词、工具、权限、仓库和网络共同影响。

现在适合用于生产吗

我的结论是：适合研究、插件实验和受控原型，暂不适合在没有版本锁定与回归测试的情况下直接承载关键生产流程。

理由不是它“不能运行”，而是当前仍处于 RC 和 Developer Preview：

• 官方明确预告破坏兼容性的变更；
• 安装涉及大量拆分子包和部分原生依赖；
• 文档命令与当前 CLI 已出现参数行为差异；
• 插件可以深入执行、文件系统和模型调用链，升级风险面较大。

如果团队准备试用，应锁定准确版本，保留最小启动、Provider 请求、插件加载和工具权限测试，并在升级前完整重跑。

最终建议

DeepSeek Harness 最值得关注的不是 DeepSeek 品牌，也不是短期 GitHub 热度，而是它把 Agent 的模型、工具、会话、执行环境和循环都放进可组合插件树的设计。

0.1.1-rc.2 已经能完成 CLI、Web UI 和本地插件加载闭环，但开发者预览阶段的安装、文档和兼容性仍在快速变化。现在最合理的使用方式是：隔离安装、锁定版本、从无副作用插件开始、用测试工作区验证，再决定是否接入真实模型和代码库。

常见问题

DeepSeek Harness 必须使用 DeepSeek 模型吗？

不必须。官方模型设置支持 DeepSeek，也提供 Anthropic、OpenAI 和自定义 OpenAI-compatible Provider。不同 Provider 需要各自的认证方式。

DeepSeek Harness 可以接公司内部模型网关吗？

可以添加自定义 Provider，但要核对 Base URL、协议、模型 ID，以及 developer 角色和 Token 字段兼容性。本文没有使用真实公司网关完成请求，不宣称所有兼容接口都能直接使用。

dsh web --patch 为什么报错？

在本文实测的 0.1.1-rc.2 中，web 别名不接受 --patch。使用 dsh --profile web --patch ... 成功。后续版本可能修复，应以当前 dsh --help 为准。

DeepSeek Harness 是安全沙箱吗？

不能这样理解。它包含沙箱和审批相关插件，但实际隔离强度取决于当前 Profile、配置和执行后端。不要把审批弹窗等同于系统级安全边界。

现在值得从 OpenCode 迁移吗？

如果只是需要日常 Coding Agent，没有充分理由迁移。DeepSeek Harness 更适合希望开发或替换 Agent 平台能力的人，两者定位并不完全相同。

下一步可进入Headless、JSON 事件与 CI 自动化，或返回DeepSeek Harness 专题路线按顺序阅读。