DeepSeek Harness dsh 安装教程：Web 启动、Headless 与 AI Coding 实测

DeepSeek Harness dsh 是什么？

DeepSeek Harness 是 DeepSeek 开源的 Agent 运行框架，MIT 许可，命令行叫 dsh。产品页的说法是：模型、工具、Skill、会话、沙箱、存储、循环和 UI 都是可替换插件，底层用 Cordis，口号是 Everything is a plugin。（deepseek.com/harness）

搜「DeepSeek Harness 是什么」时，真正要分清的是三件东西，而不是再听一遍函数调用协议。

API 是发动机，dsh 是已经装好方向盘、工具箱和驾驶逻辑的 Runtime。 自己写 while 循环调 chat/completions，是另一条路；8 月那篇 DeepSeek Harness AI Agent 指南 讲自建循环。这篇只验收官方启动器：怎么装、Web 开在哪、第一条编码任务怎样算跑通。

官网还列了几种运行模式。第一次用 Standard 的 Web UI 就够：完整编码 Agent，能改文件、跑 shell、做搜索。Code 模式是在 Standard 之上让模型用 TypeScript 编排多轮工具调用，等 3080 稳定再开。Minimal 几乎只留 bash 和编辑器，适合对比模型，不适合当日常 IDE。Creator 用来看运行时、试插件，第一小时可以跳过。

安装 dsh 前需要准备什么？

官方 README 的零安装路径只有两句：先装 Node.js，再跑 npx @deepseek-ai/dsh web。社区文档提过 Node ^22.19.0 或 >=24.0.0；以你本机 npx 能否拉起 @deepseek-ai/dsh 为准，不必为对齐某篇博客去降级系统 Node。

密钥按官方 CLI 说明解析：进程环境 → ~/.dsh/.credentials.yaml → 当前目录 .env → ~/.dsh/.env。第一次选一种即可，不要同时写四份还对不上：

export DEEPSEEK_API_KEY=sk-你的密钥
mkdir -p ~/.dsh
printf 'DEEPSEEK_API_KEY=sk-你的密钥\n' >> ~/.dsh/.env
chmod 600 ~/.dsh/.env

官方适配器名称是 deepseek-official，默认走官方模型路由。要把请求打到自建网关，属于第二步，先看 OmniRoute 实测 有没有必要，第一小时不必换 Base URL。

CLI 把你执行命令时所在的目录当作默认 workspace。先建一个空仓库或副本，例如 ~/work/dsh-first-run。SAFETY.md 建议最小权限，并优先用可丢弃的虚拟机、容器或专用环境。密钥和隔离目录没准备好，就先别执行 npx：界面能开、任务不能控，比装不上更糟。

DeepSeek Harness 怎么安装并打开 Web UI？

第一次不必 clone。进入隔离目录：

cd ~/work/dsh-first-run
npx @deepseek-ai/dsh web

这是官方 README 的安装入口。dsh web 是 --profile web 的别名，第一次会按模板初始化 ~/.dsh/profiles/web/。默认在 http://127.0.0.1:3080 起工作台，本机启动还会打开默认浏览器。通过 SSH 启动时只打印宿主机 URL，本地转发由 SSH 客户端或编辑器处理。预览阶段命令会改，以 deepseek-ai/deepseek-harness 当天 README、CLI 说明为准。

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

默认只绑回环地址。需要远程看界面，用 SSH 本地转发即可；第一天没有必要把 UI 暴露到局域网。官方用户指南写：workspace 在 Web UI 里用目录选择器指定，不是一条 CLI 旗标。打开 3080 后，先确认当前目录就是隔离仓库，再发任务。

配置落在 ~/.dsh/：家目录让它自己建；sessions/ 用来回看工具调用；.env 只放密钥，权限 600；profiles/web/ 第一天不用手改 patch。

三种情况才值得 clone 源码：要跟某个 commit、要改插件，或 npx 拉包失败、需要对构建产物。那时再 git clone 官方仓库，pnpm install、pnpm run build、pnpm dsh web。pnpm dsh web 直接用构建产物，不会再编一次。源码树里跟 AGENTS.md，不要把演示命令抄进生产脚本。

dsh Headless 怎么用？

dsh run 已删除。一次性任务用 headless：新开会话，把最后一段非空助手文本打到 stdout，然后退出。

cd ~/work/dsh-first-run
npx @deepseek-ai/dsh --profile headless "列出当前目录下的文件名，不要修改任何文件"

这就是第一条值得写进笔记的实测：进程退出码、stdout 有没有最终答复、~/.dsh/sessions/ 有没有多一条可回看的日志。任务必须只读。官方还有 sdk / sdk-minimal / acp 等 profile，给别的进程用 JSON-RPC 或 ACP 接入，那是第二周的事，第一小时不要并行开。

用 DeepSeek Harness 做 AI Coding

Web 或 headless 能说话，还不等于「可以让它改仓库」。按官方 Standard 能力，它确实能改文件、跑 shell、做搜索和子 Agent；预览软件加上模型会写命令，所以第一条编码任务必须能对照 git diff。下面不是跑分，而是确认 dsh 会不会在你指定的目录里改对一个函数。

先做一个能看清对错的小仓库：greet.ts 故意返回 hi Ada，测试期望 Hello, Ada。对错你自己能看出来，不依赖模型「说得像那么回事」。

mkdir -p ~/work/dsh-first-run && cd ~/work/dsh-first-run
git init
printf '%s\n' 'export function greet(name: string): string {' '  return "hi " + name' '}' > greet.ts
printf '%s\n' 'import { greet } from "./greet.ts"' 'if (greet("Ada") !== "Hello, Ada") {' '  throw new Error("unexpected greeting")' '}' > greet.test.ts
git add . && git commit -m "chore: isolated dsh first-run repo"

1. 只读：阅读 greet.ts 和 greet.test.ts，说明测试为什么会失败。不要修改任何文件。 通过：它指出返回值和测试期望不一致，工作区 git status 仍是干净的。
2. 单文件：只修改 greet.ts，让 greet("Ada") 返回 Hello, Ada。不要改测试，不要提交。 改完后自己跑测试，没有现成 runner 就直接看函数返回值，再执行 git diff。通过：diff 只动 greet.ts，返回值对上测试。
3. 测试仍失败，就把失败输出贴回去，让它再改同一文件。最后提交前必须你自己看 diff。编码任务失败时，打开 ~/.dsh/sessions/ 或官网 Trajectory，区分「选错工具」「参数不合法」「你拒绝了审批」「工作区根本不是这个目录」。

第一次用默认 Standard / native 工具。单文件任务已经稳定，再考虑 DSH_TOOLS_MODE=code 或 both，让模型用 TypeScript 编排多轮调用。官方参考里，DSH_PERMISSION_MODE 的进程级回退接近 workspace-write；danger-full-access 几乎不再问审批，第一次运行清单已经排除它。卡在 JSON 工具参数时，先读 JSON Schema 与 AI Agent，再考虑换模型。任务拆太大、来回改，见 AI Coding 工作流——dsh 只解决「官方运行时在不在」。

DeepSeek Harness 安装成功了吗？

标题里的「实测」在这里不是跑分榜，而是一份半小时清单。五项都过，才算「dsh 在这台机器上能用」。缺一项就回到对应步骤，先别扩大改文件范围。

五项里缺任何一项，都先别进入「自动改几十个文件」。预览版迭代快，把命令、Node 版本、dsh 包版本和日期记在笔记里，下周再跑时才分得清是你的环境变了，还是上游 breaking change。

dsh 常见报错与解决方法

npx 失败或很慢。 第一次要拉 @deepseek-ai/dsh。网络不稳就换源码构建，或先确认 npm registry。半套缓存目录不能当成「已经安装成功」。

3080 打不开。 加 --no-open 后手动访问；检查端口是否被占用，或你用了 --port 却仍打开 3080。

界面开了但模型不工作。 多半是密钥层没对上。进程环境优先级最高，~/.dsh/.env 只是兜底。改完重启 web 进程，不要指望热更新密钥。

改错了目录。 看启动时的当前目录，以及 Web 里选中的仓库。最常见的误操作是把家目录当成 workspace。

还在用 dsh run，或 headless 不退出。 官方用户指南写明该子命令已移除，一次性任务改 --profile headless。把任务收成一句只读指令，确认进程没有在等审批，再看 session 日志卡在哪一步。

dsh 不是 Claude Code、Codex 的皮肤。出品方分别是 DeepSeek、Anthropic 和 OpenAI；形态上 dsh 是独立运行时加 Web / headless，另外两套是各自的 CLI。配置目录也不互通：dsh 在 ~/.dsh。第一次验收，dsh 看 3080 或一条 headless，另外两套走各自官方冒烟。可以同时安装，但不能假设 Key、权限和会话互通。真的要把三套请求并到一个入口，再评估网关；第一天先把 dsh 自己跑通。

现在不适合按生产运行时对待。官方 README 写明处于 developer preview，会有破坏兼容性的变更。SAFETY.md 写得更硬：未经安全审计；它能执行模型生成的命令、加载第三方插件、碰网络和你交给它的文件。沙箱和审批能降低风险，不能当唯一安全控制。现在适合隔离目录里的安装验收、单函数级 AI Coding、对照 session 日志做实验。现在不适合对着生产仓库开高权限、无人值守改整个 monorepo、把 preview 写进对外 SLA。

常见问题