DeepSeek Harness

配置模型

1. 环境要求

项目	要求
Node.js	`^22.19.0` 或 `>= 24.0.0`（推荐最新的 22 LTS 或 24）
包管理器	通过 npm/npx 运行无需额外安装；从源码构建需要 `pnpm@11.7.0`
操作系统	macOS / Linux / Windows（本机沙箱与终端工具随平台启用）

检查 Node.js 版本：

node -v
# 例如 v22.19.0 或更高

提示：若版本过低，请先到 https://nodejs.org 安装新版 Node.js，或使用 nvm 等版本管理器切换。

2. 下载与安装

2.1 快速开始（推荐）

无需显式安装，直接使用 npx 运行即可。npx 会自动下载并缓存 @deepseek-ai/dsh 包：

npx @deepseek-ai/dsh web

首次运行会从 npm 下载依赖，之后启动 Web UI，默认地址为 http://127.0.0.1:3080。

2.2 作为项目依赖安装（可选）

如果想固定版本、离线使用或写脚本调用，可以安装到本地项目：

npm install -D @deepseek-ai/dsh

之后通过 npx dsh ... 或 ./node_modules/.bin/dsh ... 调用：

npx dsh web

2.3 验证安装

查看版本号：

npx @deepseek-ai/dsh --version
# 0.1.0-rc.6

查看启动器帮助（注意：dsh --help 显示的是启动器自身的 flag，不是应用内的帮助）：

npx @deepseek-ai/dsh --help

输出示例：

Usage: dsh [options] [args...]

dsh: boot a DeepSeek Harness profile — an ordered stack of plugin-bundle patch
layers under your own overrides.

Options:
  -V, --version               output the version number
  --profile <name>            the profile under $DSH_HOME/profiles to boot
  --patch <path>              extra patch-list overlay applied after the profile layer (repeatable)
  --dump-config               print the composed profile tree and exit
  --dump-default-config       print the profile tree without its user layer or --patch overlays and exit

Examples:
  dsh --profile web                          boot the web profile (same as: dsh web)
  dsh --profile headless "run the tests"     answer one task, print the result, and exit
  dsh --profile tui --patch ./extra.yml      boot a custom profile with one extra overlay
  dsh --profile tui --resume <session>       arguments after the launcher flags reach the app
  dsh --profile web --help                   the web app's own flags and help
  dsh plugin --profile tui add <package>     install a plugin into the tui profile

3. 启动 Web UI

npx @deepseek-ai/dsh web

web 是 --profile web 的别名。
首次使用会自动初始化 web profile（从随附模板生成到 $DSH_HOME/profiles/web）。
启动成功后终端会打印 URL，默认 http://127.0.0.1:3080，用浏览器打开即可。
运行 dsh 命令时所在的目录会被当作默认 workspace 根目录，但 Web UI 中仍需手动选择一个工作区（见第 5 节）。

3.1 Web 应用自身的启动参数

启动器 flag 必须写在最前面；第一个启动器不认识的 token 之后，全部参数会原样交给被启动的应用（这里是 web 应用）：

# 指定端口
npx @deepseek-ai/dsh web --port 8080

# 查看 web 应用的参数帮助（注意不是启动器的帮助）
npx @deepseek-ai/dsh web --help

web 应用支持的参数：--host、--port、可重复的 --trusted-host。
（当前版本不支持 --host 0.0.0.0 全接口绑定，这是 CLI 的刻意限制。）

注意：修改端口等参数后需重启服务生效；模型配置则无需重启（见第 4 节）。

添加自定义提供方（OpenAI 兼容网关）

点击 添加自定义提供方。
填写：Provider ID（小写、永久）、显示名称、基础 URL、API 协议、API 密钥、至少一个模型。
在模型目录中可点 获取可用模型 查询端点（调用 OpenAI 兼容的 GET /models）。
保存后即可在模型选择器中选用。

Provider ID 是永久的（请求、已保存会话、模型默认值和凭据引用都会引用它）；想重命名就新建一个再删旧的。

5. 选择工作区并运行任务

点击 Choose workspace（选择工作区）。
添加并选中你启动 dsh 时所在的项目目录（也可以选其他目录）。

未选择工作区之前，会话输入框不可用。
新建会话，发送任务，例如：

总结这个仓库的结构，并说明它的主要包。
智能体会在所选工作区内：读取/编辑文件、运行命令、委派子任务（subagent）、维护计划（plan）。
当操作触发当前权限策略下需要审批的操作时，Web UI 会先弹窗询问，批准后才执行。

6. 命令行模式（CLI）

命令	用途
`dsh --profile <name>`	启动 `$DSH_HOME/profiles/<name>` 下的指定 profile
`dsh --profile headless "<任务>"`	跑一次全新的持久化会话，打印最终答案后退出（无 UI）
`dsh web`	`--profile web` 的别名
`dsh plugin --profile <name> <pnpm 参数>`	在 profile 目录中转发给 pnpm，管理该 profile 的插件

6.1 headless 模式（一次性任务）

npx @deepseek-ai/dsh --profile headless "运行这个仓库的测试并汇总结果"

首次使用自动初始化 headless profile。
适合脚本化、CI 集成。

6.2 启动器 flag 一览

Flag	说明
`--profile <name>`	启动指定 profile（必填，`web` 别名除外）
`--patch <path>`	追加一个 patch-list 覆盖层（可重复：`--patch a.yml --patch b.yml`）
`--dump-config`	打印组合后的配置树后退出（含用户层与 `--patch`）
`--dump-default-config`	打印不含用户层的组合配置树后退出（不接受 `--patch`）
`-V, --version`	打印版本
`-h, --help`	启动器自身的帮助

参数分隔规则示例：

dsh --profile web --port 8080        # --port 属于 web 应用
dsh --profile headless "run the tests"
dsh --profile web --help             # 打印 web 应用自己的帮助
dsh --help                           # 打印启动器自己的帮助

6.3 插件管理（dsh plugin）

# 安装插件到 profile（首次使用会自动初始化该 profile）
npx @deepseek-ai/dsh plugin --profile tui add <package>

# 移除插件
npx @deepseek-ai/dsh plugin --profile tui remove <package>

# 其他 pnpm 参数原样转发（why、update 等）
npx @deepseek-ai/dsh plugin --profile tui update

web、headless 之外的 profile 必须通过 dsh plugin 创建。
依赖中声明了 dsh.bundle 的包会自动进入该 profile 的 layer 栈；没有声明 dsh.bundle 的包会作为普通依赖安装并给出提示。

7. Profile（配置档案）机制

profile 是 dsh 的"应用配置档案"：一个有序叠加的插件 bundle patch 层，上面再盖你自己的覆盖配置。

7.1 目录结构

一个 profile 目录（$DSH_HOME/profiles/<name>/）包含：

文件	作用
`package.json`	树外插件依赖 + profile manifest（`dsh.profile` 字段，含有序的 `bundles` 列表）
`cordis.patch.yml`	用户自己的 patch 层（按条目 id 覆写配置、`insert` 插入条目）

7.2 配置树叠加顺序（低 → 高）

空根
dsh.profile.bundles 中每个 bundle 的 patch（按列表顺序）
profile 自身的 cordis.patch.yml
home 级 $DSH_HOME/cordis.patch.yml（覆盖 profile 级）
--patch 指定的覆盖层（最高）

注意：按 id 定位的 patch 是整条替换对应条目的 config（不是深度合并），所以覆写时要写全要保留的字段。

7.3 检查组合后的配置

# 打印 web profile 的组合配置树（含用户层）
npx @deepseek-ai/dsh web --dump-config

# 只打印 bundle 层（不含用户层与 --patch）
npx @deepseek-ai/dsh web --dump-default-config

7.4 自制 profile 示例

# 创建一个名为 tui 的 profile 并装一个插件（首次运行自动初始化目录）
npx @deepseek-ai/dsh plugin --profile tui add some-plugin-package

# 启动它
npx @deepseek-ai/dsh --profile tui

8. 配置文件与目录结构

8.1 Harness home（`$DSH_HOME`）

默认位置为 ~/.dsh（DSH_HOME 环境变量可覆盖；空白值视为未设置）。重要文件：

路径	作用
`$DSH_HOME/profiles/`	所有 profile 目录（`web`、`headless` 及自定义）
`$DSH_HOME/profiles/<name>/cordis.patch.yml`	profile 级用户 patch 层
`$DSH_HOME/cordis.patch.yml`	home 级用户 patch 层（优先级高于 profile 级）
`$DSH_HOME/.credentials.yaml`	各提供方的 API 密钥（只写，界面不回显）
`$DSH_HOME/settings.yaml`	用户配置（如自定义提供方、模型 `input` 模态等）
`$DSH_HOME/.env`	用户环境变量层（低于调用目录的 `.env` 与继承环境）

配置层的环境优先级（从低到高）：继承环境 → 项目目录 .env → Harness home 的 .env。

8.2 自定义提供方的 `settings.yaml` 示例

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY      # 从环境变量读密钥
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]        # 声明该模型支持图片输入

input 只对该模型生效；省略或空列表则用已安装目录记录/路由默认值（defaultInput，默认 [text]）。
目录提供方的模型覆写写在 modelOverrides 下，以模型 id 为键。

8.3 目录提供方模型示例

llm-pi-ai:
  providers:
    anthropic:
      modelOverrides:
        claude-sonnet-4-5:
          input: [text]

8.4 patch 层示例（`cordis.patch.yml`）

# 覆写某个条目的完整 config
- id: some-plugin-id
  config:
    enabled: true
    port: 9000

# 插入新条目
- insert:
    - id: my-plugin
      plugin: my-plugin-package

9. 从源码运行

适合想要二次开发、调试或跟踪最新功能的场景：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

pnpm dsh <args...> 运行 TypeScript 入口并把参数全部转发。
生产运行需要已构建的包与前端产物，所以必须先 pnpm run build。
参与贡献前请阅读 CONTRIBUTING.md 与 AGENTS.md。

10. 升级与卸载

升级

# npx 方式：清理缓存后重新拉取最新版
npm cache clean --force
npx @deepseek-ai/dsh web

或使用 npx @deepseek-ai/dsh@latest web 指定最新标签。

卸载

由于 npx 方式不产生全局安装，卸载分两步：

# 1) 清理 npx 缓存中的 dsh 相关包
npm cache clean --force   # 或手动删除 ~/.npm/_npx 下对应目录

# 2) 删除配置与数据（谨慎：包含所有会话与凭据）
rm -rf ~/.dsh

如果之前用 npm install -D @deepseek-ai/dsh 安装过，在对应项目里执行 npm uninstall @deepseek-ai/dsh。

11. 常见问题排查

现象	处理
`node -v` 版本过低	升级 Node.js 到 `^22.19.0` 或 `>=24.0.0`
启动时报 `MISSING_CREDENTIAL`	在设置→模型中保存提供方密钥，或提供被引用的环境变量
报 `UNKNOWN_MODEL`	选择已配置的模型，或给自定义提供方补上缺失的模型
获取可用模型返回 401	检查密钥；模型发现调用 OpenAI 兼容的 `GET /models`，不提供该端点的服务请手动录入模型
图片在发送前被拒绝	该模型未声明图片模态；给自定义提供方的模型加 `input: [text, image]`
端口被占用	用 `npx @deepseek-ai/dsh web --port 8080` 换端口
改了 `cordis.patch.yml` 不生效	确认层级（profile 级 → home 级 → `--patch`），并检查条目 id 是否存在于组合树中；patch 会整条替换 config，记得写全保留字段
patch 文件为空或只有注释	空文件会解析失败，禁用该层请写 `[]`

12. 参考链接

官方仓库：https://github.com/deepseek-ai/deepseek-harness
npm 包：https://www.npmjs.com/package/@deepseek-ai/dsh
Web UI 指南（官方 docs）：https://github.com/deepseek-ai/deepseek-harness/tree/master/docs/user/guide
配置模型（提供方文档）：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.zh.md
Python SDK：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/python-sdk.md
插件开发指南：https://github.com/deepseek-ai/deepseek-harness/tree/master/docs/develop
社区讨论：https://github.com/deepseek-ai/deepseek-harness/discussions

本文档对应版本：@deepseek-ai/dsh@0.1.0-rc.6（开发者预览版，接口可能随时变化）。