DeepSeek Harness 怎么用？dsh 安装部署、Agent Harness 插件架构、AI Coding 工作流与 Claude Code/Codex 对比实战

你已经能让 Agent 修改代码，却发现换一个项目就要重新配置工具、权限和上下文，升级后还可能出现插件失效。

最快的判断是：DeepSeek Harness 值得试用，但不适合现在就全面替换稳定的编码 Agent；个人研究者可以立即安装，团队则应先做小范围双轨验证。

最后更新于 2026 年 9 月 21 日，启动命令、developer preview 状态、架构与配置说明核实自 DeepSeek Harness 官方 GitHub 仓库、官方架构文档与官方子系统说明。

如果你正在规划云端开发环境，重点看远程访问、权限隔离、会话持久化和插件治理；如果你只是想完成日常编码任务，先不要为了“开源”二字迁移全部工作流。

先按迁移风险做选择

DeepSeek Harness 目前明确处于 developer preview，官方已经提示可能出现兼容性变化。因此，不能把“能启动 Web UI”理解成“已经适合生产交付”。

立即迁移

只有在以下条件同时满足时，才适合把 dsh 放进日常主流程：

• 你明确接受预览版的兼容性变化；
• 团队有人能够阅读源码、定位插件加载问题；
• 代码仓库、模型密钥和 Shell 权限可以隔离；
• 失败时仍然保留 Claude Code 或 Codex 作为回退路径。

双轨试用

这是多数小团队更稳妥的选择：让 DeepSeek Harness 负责一个限定范围的仓库或任务类型，同时保留当前 Agent 处理主线工作。

你可以选择“修复一个测试失败”“生成变更说明”“检查依赖更新”这类可复核任务，用同一份代码、同一组权限、同一模型提供方进行对照。不比较没有来源的“谁更快”，只记录是否完成、改动是否可审查、日志是否完整以及恢复成本。

暂不迁移

如果你的团队没有人维护 Node.js 运行时、插件版本和远程权限，或者开发环境必须依赖稳定的审批流程，那么先不要把 dsh 作为默认入口。等官方预览周期结束或你的验证结果足以覆盖升级风险，再决定是否扩大范围。

先把 dsh 安装路径跑通

npm 启动

官方仓库给出的最短启动方式是：

npx @deepseek-ai/dsh web

默认 Web UI 地址为 http://127.0.0.1:3080。这个地址只监听本机回环接口，适合本地使用；如果你通过 SSH 进入远程开发环境，浏览器不会自动获得远程页面，通常需要 SSH 端口转发或受控代理访问。官方说明也指出，SSH 启动时会输出主机地址，而本地转发地址由 SSH 客户端或编辑器负责。

如果你不希望命令自动打开浏览器，可以使用：

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

npx 是 npm 提供的包执行工具，适合在不把命令行工具永久安装到全局环境的情况下运行指定包；具体行为可参考 npm 官方 npx 文档。Node.js 运行时与 npm 的安装方式，则应以 Node.js 官方下载与版本说明 为准，不要直接照抄社区教程中的版本号。

源码构建

需要开发插件、阅读包结构或固定源码版本时，再使用源码路径：

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：前者准备构建产物，后者使用已经生成的产物启动，不会自动替你重新构建。

首次启动检查

不要只确认浏览器能打开。首次启动后，按下面顺序检查：

• [ ] node --version 与项目当前要求相符；
• [ ] npx @deepseek-ai/dsh web 能正常下载并启动；
• [ ] 端口没有被其它进程占用；
• [ ] 运行目录是你准备交给 Agent 的项目目录；
• [ ] DSH_HOME 或默认 Harness home 对当前用户可读写；
• [ ] 模型提供方已经配置，且密钥没有写入 Git 仓库；
• [ ] Shell、文件读写和网络工具的权限符合项目要求；
• [ ] 远程环境使用 SSH 转发或身份认证代理，而不是直接暴露服务端口；
• [ ] 关闭并重新启动后，会话和配置仍能恢复。

模型设置可以在 Web UI 中完成。官方提供方文档说明，密钥以凭据引用方式保存，实际凭据写入 $DSH_HOME/.credentials.yaml；同时，某些需要 OAuth 登录的提供方并不一定已经得到支持。相关细节可参考 官方提供方配置说明。

远程访问时，SSH 端口转发应优先于直接开放 Web UI 端口。OpenSSH 官方手册对 LocalForward 与 RemoteForward 的行为有明确说明，部署前应根据实际访问方向选择参数，而不是把端口映射规则写进未经审查的启动脚本。(OpenSSH 官方手册)

注意：不要把 127.0.0.1:3080 改成公网监听就当作远程部署完成。Web UI 能访问文件和执行命令，端口暴露、密钥泄露与未授权会话会把“开发工具”变成高权限入口。

再理解 Agent Harness 的插件树

DeepSeek Harness 的关键不是多一个聊天界面，而是把运行时拆成可组合的插件。官方架构资料将模型适配器、工具注册表、会话日志和 Agent loop 都视为插件，profile 再把这些能力按层组合起来。

可以把一次任务理解成下面这条链：

用户请求
  ↓
Session 会话日志
  ↓
System Prompt 与工具清单
  ↓
Agent Loop
  ↓
模型适配器
  ↓
Tool / Shell / 文件系统 / 子 Agent
  ↓
Sandbox 与审批策略
  ↓
日志、持久化与 Web UI

其中，Session 不是普通聊天记录，而是追加式事件日志；模型上下文从日志重新推导，工具调用、模型响应和部分运行状态都可以参与恢复与回放。关于核心运行时、事件和会话关系，可以查看 DeepSeek Harness 官方核心子系统文档。

这里要区分“profile”和“preset”：profile 更接近启动时的插件组合，preset 则可以影响 Agent 能力配置。当前仓库存在 standard、code、minimal 和 creator 等预设，但预览期名称和组合关系可能变化，实际应以你安装版本的帮助信息和配置输出为准。

你可以先查看启动树，而不是直接修改源码：

dsh --profile web --dump-config

最小插件流程可以这样理解：

1. 模型插件提供请求接口；
2. 工具插件注册文件编辑或 Shell 能力；
3. Agent loop 把模型输出转成工具调用；
4. 沙箱插件检查命令和文件影响范围；
5. Session 插件写入事件；
6. Web 插件把流式状态呈现给你。

这就是 Agent Harness 的实际价值：你可以替换其中一层，而不是复制整个编码 Agent。但代价也很明显——每增加一个插件，就增加一组版本、权限、日志和回归测试关系。

用真实任务评估 AI Coding 适配度

不要先问“它是不是比 Claude Code 或 Codex 强”，而要把 AI Coding 工作流拆成可验收的动作。

Bug 修复

适合交给 Harness 的第一类任务是：读取指定文件、复现测试、提出小范围修改，再重新运行相关测试。你需要限制仓库范围，并要求 Agent 输出：

• 修改了哪些文件；
• 哪条测试命令成功或失败；
• 是否改变依赖、配置或数据库结构；
• 哪些问题没有被验证。

如果它只能修改代码，却无法稳定留下工具调用和测试结果记录，那么它还不适合作为团队交付入口。

变更说明

第二类任务是根据已完成的 Git diff 生成变更说明。这个任务风险低，适合验证会话日志、文件读取边界和输出稳定性，也能观察模型是否把未验证的内容写成确定结论。

多步骤协作

当任务需要“分析问题 → 修改文件 → 运行测试 → 解释失败 → 再次修复”时，Harness 的插件化结构会更有意义。模型请求、工具调用和会话事件持续经过同一套运行时，而不是由多个互不相识的脚本拼接。

但不要把社区演示中的顺利完成当作官方性能结论。你应该记录以下指标：

• 任务是否能从空会话开始完成；
• Agent 是否遵守文件和命令权限；
• 测试失败后是否正确回到上下文；
• 会话重启后能否恢复；
• 插件异常时是否能给出可定位日志；
• 失败后回退到原有 Agent 需要多少人工操作。

把模型、工具和沙箱分开治理

dsh 的配置难点不在“在哪里填 API Key”，而在于模型、工具、沙箱和存储是不同的治理对象。

模型提供方

模型提供方负责请求协议、模型名称和凭据。你可以在 Web UI 的模型设置中添加官方支持的提供方，也可以使用自定义提供方连接团队网关或自托管服务。设置变更通常在下一次请求生效，不必重启整个服务器。

工具注册

工具由 ctx.tools 注册，并向模型暴露参数模式与执行函数。工具的执行函数、超时和 UI 呈现信息不会全部泄露到模型请求中，工具注册表会组装模型真正能看到的 schema。具体接口可参考 官方工具子系统说明。

因此，团队应把“模型能看到什么”和“进程实际上能执行什么”分别审计。不能因为某个工具没有显示在提示词里，就认为它不存在风险。

沙箱与审批

Shell、文件系统和子进程需要单独限制。官方子系统索引把 sandbox 描述为进程约束与执行策略的扩展点，并提供失败即拒绝的错误边界；扩展手册还列出基于 landlock 或 sandbox-exec 的子进程沙箱路径。

部署前至少做一次拒绝测试：

• [ ] Agent 不能读取项目目录以外的敏感文件；
• [ ] 禁止执行的命令会被拦截；
• [ ] 需要人工确认的操作确实弹出审批；
• [ ] 网络访问范围有明确说明；
• [ ] 子 Agent 不会继承超出主 Agent 的权限；
• [ ] 日志中能区分模型请求、工具调用和实际执行结果。

存储与会话

会话日志与其它持久化数据不是同一个层面。非会话数据可以交给 JSON 或 SQLite 等存储插件，而会话本身通过独立的持久化接口处理。

远程环境中，你至少要持久化三类内容：

1. Harness home 与 profile 配置；
2. Session 日志与工作区关联信息；
3. 插件版本、补丁文件和运行日志。

如果只把项目目录挂载到持久化磁盘，却把 DSH_HOME 留在临时容器里，下一次重启可能出现“代码还在，但会话、模型配置和插件状态都丢失”的问题。

用双轨表决定是否替换

下面这张表用于实际验证，不是泛泛比较产品优缺点：

只有当 dsh 在“任务完成、权限控制、日志恢复、升级回退”四项都达到你的团队门槛，才值得从双轨试用进入长期部署。否则，它更适合作为研究平台，而不是默认生产 Agent。

远程云端部署的落地顺序

如果你计划把 DeepSeek Harness 放进远程云端开发环境，建议按以下顺序实施：

1. 固定运行用户。 不要用共享管理员账号启动，给 Agent 分配独立用户与项目目录。
2. 固定 Harness home。 将 profile、凭据引用、插件清单和会话存储放到明确目录，并纳入备份策略。
3. 先用 SSH 访问。 通过 SSH 端口转发验证 Web UI，确认稳定后再考虑身份认证代理。
4. 锁定插件版本。 预览版升级可能带来兼容性变化，至少保存 package-lock、构建提交和 patch 文件。
5. 建立回归任务。 每次升级都执行同一组 Bug 修复、测试运行和变更说明任务。
6. 验证中断恢复。 强制停止进程，再检查会话日志、工作区和未完成任务是否处于可解释状态。
7. 配置维护记录。 记录升级日期、Node.js 版本、插件变化、失败任务和回退步骤。
8. 最后开放团队访问。 在权限、日志和会话交付没有验证前，不要让多人共享同一个高权限实例。

如果你需要的是远程 Mac 开发节点，而不是自己维护完整的 Linux 容器或服务器，可以先查看 ZavCloud 的云端 Mac 租用方案，再根据项目对 macOS、Xcode、物理接口和长期运行时的要求做选择。关于账号、访问和使用边界，也可以参考 ZavCloud 帮助中心。

常见问题

本地和 SSH 环境分别怎样启动 Web UI？

本地可以直接运行 npx @deepseek-ai/dsh web，远程环境则应先确认端口监听范围，再通过 SSH 端口转发访问。你还要检查运行用户、工作目录、Harness home、模型凭据和端口占用情况，不能把远程服务简单绑定到公网地址。

插件化运行时具体解决了什么问题？

它把模型适配器、工具注册、Agent loop、会话日志、存储、沙箱和界面拆成可组合单元。这样你可以替换某一层，而不必重写整个编码 Agent；相应代价是插件之间存在版本、权限和回归测试关系。

是否应该把现有编码 Agent 全部换成 dsh？

不建议仅凭一次成功启动就替换现有 Agent。DeepSeek Harness 当前仍是 developer preview，更适合研究插件化运行时、定制工具链和自托管流程；日常交付应先保留原有工具，用相同仓库、相同权限和相同任务做双轨验证。

模型、工具和沙箱分别在哪里控制？

模型通常在 Web UI 的设置页中配置，凭据写入 DSH_HOME 下的凭据文件；工具由 profile 或插件注册，沙箱则通过执行策略与 sandbox 后端控制。修改前应先导出配置，并分别验证文件访问、Shell 执行、审批行为和日志记录。

远程部署时最容易漏掉哪些维护项？

最容易漏掉的是 Harness home、会话日志、插件版本和工作目录的持久化。远程部署还需要验证 SSH 转发、进程重启、日志落盘、密钥权限、插件锁定和失败回退，否则环境重启后可能只剩代码，失去上下文与运行记录。

如果你现在使用的是临时服务器、共享开发机或没有持久化目录的容器，主要缺点通常是：环境重启后状态容易丢失、权限边界难以统一、远程访问需要自行维护、插件升级也缺少稳定回退路径。对需要短期测试、隔离实验或临时 AI Coding 工作流的人来说，租用 ZavCloud 的远程 Mac 环境可以减少自建机器和维护底层运行时的负担；但如果你需要长期稳定的高负载服务、固定物理接口或完全掌控底层网络，自购设备或自建环境仍然更合适。

因此，更稳妥的路线不是立刻迁移，而是先阅读 远程云端开发环境的使用说明，再按本文的双轨表验证 dsh。只有当插件升级、权限隔离、会话持久化和团队交付都能稳定通过，你才有理由把 DeepSeek Harness 从研究工具提升为长期运行方案。