DeepSeek Harness 安装与使用指南

手里是哪种 key，决定走哪条路

官方 key 直连；OpenRouter key 要经本地垫片转一道，因为两边格式有两处对不上。

安装

一条 npm 命令即可，前提是本机有 Node.js 和 npm（官方要求 Node ^22.19.0 或 >=24，见 GitHub 仓库根目录 package.json 的 engines；我们在 v24.14.1 上验证过）。

npm install -g @deepseek-ai/dsh@latest
dsh --version        # 输出 0.1.7-rc.2 即成功

• npm 上的 latest 标签目前指向候选版 0.1.7-rc.2，不是正式版。
• 配置和数据都放在 ~/.dsh/，卸载用 npm rm -g @deepseek-ai/dsh，再删这个目录即可清干净。
• 不想全局安装，也可以临时跑：npx @deepseek-ai/dsh web。

配置 API Key

没有 key 什么都跑不了。DeepSeek 官方 key 在 platform.deepseek.com 的 API Keys 页创建，按用量付费；两种填法任选一种：

• Web 界面里填：启动 dsh web 后进 Settings → Models，粘贴保存，存进 dsh 自己的凭据库。
• 环境变量：dsh 默认读 DEEPSEEK_API_KEY，命令行和脚本用这种更方便。

export DEEPSEEK_API_KEY=<你的 DeepSeek API Key>   # 写进 ~/.zshrc 可长期生效

三种用法

日常用 Web 界面，批量或脚本用 headless。命令行模式以启动时所在目录为工作区，Web 界面在页面上选工作区；用命令行时先 cd 进项目再启动。

headless 的常用写法：

dsh headless "跑一下测试，总结失败原因"
echo "审查这段改动：$(git diff)" | dsh headless -   # - 表示从 stdin 读任务，stdin 全文就是任务
dsh headless --json "跑一下测试"                  # 输出机器可读的事件流
dsh headless --session-id session-xxxx "接着上次的继续"  # 把 session-xxxx 换成真实会话 id

会话 id 形如 session-<uuid>，在 --json 事件流开头的 session 事件里。续接时必须在原来的目录下执行，否则会报错退出。

答案输出到 stdout，诊断信息到 stderr。其他帮助：dsh --help、dsh web --help、dsh headless --help。

先命令行验证，再上 Web

建议先在一个不怕改坏的小项目里试。我们用一个含 3 个失败测试的 Python 小项目跑过下面的流程。

1. 进入项目目录：cd ~/你的项目。
2. 命令行先验证链路通：dsh headless "用一句话介绍这个目录里有哪些文件"。
3. 让它干活：dsh headless "运行 python3 -m pytest -q，修复导致测试失败的 bug，不要改测试文件，修完再跑一遍"。实测它自己跑测试、改代码、复跑，3 条测试全部通过。
4. 换 Web 界面：dsh web，关掉「Internal Testing Notice」提示，点「Choose workspace」选项目文件夹。
5. 在输入框用中文说任务，比如「新增 median 函数并补测试」。我们单次实测用了 24 秒、改 2 个文件，5 条测试全部通过。
6. 看结果：点「Edited N files」看 diff，点顶部「Trajectory」看它每一步调了什么工具。

单次实测两个任务合计花费约 $0.004（OpenRouter 账单接口读数，模型 deepseek-v4-flash）。

用 OpenRouter key 接入

用 OpenRouter key 要多做两步：写一份配置覆盖文件，再跑一个本地垫片。原因是 dsh 按 DeepSeek 自家的 Anthropic 格式发请求，而 OpenRouter 的 Anthropic 兼容接口有两处对不上：

第 1 步：写配置覆盖 ~/.dsh/cordis.patch.yml

对所有 profile 生效，删掉这个文件即恢复默认；没跑过 dsh 的先执行 mkdir -p ~/.dsh。

- id: llm-deepseek
  config:
    baseURL: http://127.0.0.1:18080/api   # 指向本地垫片
    thinking: disabled
    models:
      - id: deepseek/deepseek-v4-flash
        name: DeepSeek-V4-Flash (OpenRouter)
        contextWindow: 1048576
        maxTokens: 131072
        inputModalities: [text]
      - id: deepseek/deepseek-v4-pro
        name: DeepSeek-V4-Pro (OpenRouter)
        contextWindow: 1024000   # OpenRouter 上 Pro 的上游上限
        maxTokens: 384000
        inputModalities: [text]
- id: agent-default-model
  config:
    provider: deepseek-official
    model: deepseek/deepseek-v4-flash

第 2 步：保存垫片 ~/.dsh/openrouter-shim.mjs

import http from 'node:http';

const PORT = Number(process.argv[2] ?? 18080);
const UPSTREAM = 'https://openrouter.ai';
const fixNulls = (s) => s.replace(/"(cache_creation_input_tokens|cache_read_input_tokens)":null/g, '"$1":0');

http.createServer(async (req, res) => {
  try {
    const chunks = [];
    for await (const c of req) chunks.push(c);
    const body = Buffer.concat(chunks);
    const headers = { ...req.headers };
    delete headers.host;
    delete headers['content-length'];
    delete headers['accept-encoding'];
    const up = await fetch(UPSTREAM + req.url, { method: req.method, headers, body: body.length ? body : undefined });
    res.writeHead(up.status, { 'content-type': up.headers.get('content-type') ?? 'application/json' });
    if (!up.body) return res.end();
    const decoder = new TextDecoder();
    let pending = '';
    for await (const chunk of up.body) {
      pending += decoder.decode(chunk, { stream: true });
      const cut = pending.lastIndexOf('\n') + 1; // 只改整行，避免字段被切开
      if (cut > 0) {
        res.write(fixNulls(pending.slice(0, cut)));
        pending = pending.slice(cut);
      }
    }
    res.end(fixNulls(pending + decoder.decode()));
  } catch (err) {
    console.error(new Date().toISOString(), req.url, err.message);
    if (!res.headersSent) res.writeHead(502, { 'content-type': 'application/json' });
    res.end(JSON.stringify({ type: 'error', error: { type: 'api_error', message: `shim: ${err.message}` } }));
  }
}).listen(PORT, '127.0.0.1', () => console.error(`openrouter-shim listening on 127.0.0.1:${PORT}`));

第 3 步：每次使用前启动

重启电脑后垫片要重新开：

node ~/.dsh/openrouter-shim.mjs &                  # 先起垫片
export DEEPSEEK_API_KEY=<你的 OpenRouter Key>       # sk-or-v1- 开头
cd ~/你的项目 && dsh web                           # 或 dsh headless "任务"

成功标志：启动后 Web 界面模型栏显示 DeepSeek-V4-Flash (OpenRouter)。OpenRouter 上 deepseek-v4-flash 的标价是输入 $0.14、输出 $0.28 / 百万 token（2026-09-28 从 OpenRouter models 接口读取）。

常见问题

用之前记住这几条