DeepSeek Harness（dsh）安装与使用指南

本文基于官方仓库 tag dsh-v0.1.7-rc.2 的 README、CLI 说明、模型配置、网络代理与安全文档整理，并补充 CC Switch 的协作方案。整理时间：2026-10-23。DSH 仍处于开发者预览阶段，官方明确会有破坏兼容性的变更；执行前请以 dsh --help、dsh web --help 和官方文档为准。

1. 简介

DeepSeek Harness（命令名 dsh）是 DeepSeek AI 开源的 agent harness（智能体框架），采用「一切皆插件」的架构，由 Cordis 驱动。模型、工具、技能、会话、沙箱、存储等能力都通过插件组合，无需改框架源码即可替换或扩展。

官网文档：https://deepseek-harness.github.io/deepseek-harness/
仓库：https://github.com/deepseek-ai/deepseek-harness
许可证：MIT
设计论文：A Programming Paradigm for Spatiotemporal Composability（arXiv:2608.25512）

它能做什么：

读取和编辑工作区文件、运行命令；
委派子任务、维护计划；
按权限策略在执行敏感操作前请求审批；
以 Web UI、无头（headless）、SDK、ACP 等多种形态运行。

先懂 4 个概念

概念	说明
Profile	一套插件组合 + 配置，位于 `$DSH_HOME/profiles/<name>`。内置 `web`、`headless`、`sdk`、`sdk-minimal`、`acp`，首次使用时自动从模板初始化。
Bundle	profile manifest（`package.json` 的 `dsh.profile.bundles`）中按顺序叠加的插件组合包。
Patch 层	用户覆盖配置，主要是 `cordis.patch.yml`。优先级：bundles → profile 的 `cordis.patch.yml` → `$DSH_HOME/cordis.patch.yml` → `--patch` 指定的覆盖层。
Workspace / Session	启动 `dsh` 时所在目录是默认 workspace 根；Web UI 需手动添加工作区。会话持久化在 `$DSH_HOME/sessions/`。

入口模式

命令	用途
`dsh web`	启动 Web UI（最常用）
`dsh <name>` / `dsh --profile <name>`	启动 `$DSH_HOME/profiles/<name>` 指定的 profile
`dsh --profile <name> --from-default-profile <template>`	基于内置模板创建自定义 profile 并启动
`dsh --profile headless "job"`	跑一个持久化会话，打印最终答案后退出
`dsh --profile sdk`	通过 JSON-RPC stdio 为 SDK 客户端服务
`dsh --profile sdk-minimal`	极简 agent 配置树的 SDK 服务
`dsh --profile acp`	通过 ACP stdio 为自动化客户端服务
`dsh plugin --profile <name> <pnpm args>`	管理该 profile 的插件（参数转发给 pnpm）

2. 环境要求

项目	要求
Node.js	`^22.19.0 \|\| >=24.0.0`（仓库 `engines` 声明）
包管理器	用 npx 运行无需预装；从源码构建需 `pnpm@11.7.0`
网络	能访问 npm registry 与模型 API；企业网络需配代理
浏览器	Web UI 需要现代浏览器；纯 CLI 模式不需要

检查 Node 版本：

sh
node -v
# 应为 v22.19+ 或 v24+

版本不符时用 nvm 切换：

sh
nvm install 22
nvm use 22

代理（国内或企业网络常用）

DSH 只读标准代理环境变量，不读操作系统代理设置：

sh
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890

要点：

可写入 $DSH_HOME/.env（默认 ~/.dsh/.env），但已导出的环境变量优先；项目自己的 .env 不能设置代理，DSH 会拒绝启动。
不支持 SOCKS：socks5:// 会在启动时报告并跳过，请改用代理软件的 HTTP 端口。
需要直连的内网域名用 NO_PROXY，例如 export NO_PROXY=.corp.example.com,internal.example.com；CIDR 网段无效。

TLS 拦截型企业代理需要 CA：

sh
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

关闭使用情况遥测：
```
sh
export DSH_TELEMETRY_MODE=DISABLED
```

验证代理是否生效：

sh
env | grep -i proxy
dsh --profile headless "fetch https://example.com and tell me the page title"

3. 安装

方式 A：npx 直接运行（官方推荐，零安装）

sh
npx @deepseek-ai/dsh web

npx 会临时拉取并运行，不污染全局环境，适合尝鲜。

验证版本：

sh
npx @deepseek-ai/dsh --version

升级到最新版：

sh
npx @deepseek-ai/dsh@latest web

若发现版本没更新，多为 npx 缓存，显式加 @latest 或指定版本即可。

方式 B：全局安装（长期使用）

sh
npm install -g @deepseek-ai/dsh
dsh --version
dsh web

升级：

sh
npm update -g @deepseek-ai/dsh

官方 README 只承诺 npx 路径；全局安装属于便捷用法，遇到问题时优先回到 npx 复现。

方式 C：从源码运行

sh
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 直接使用已构建产物，不会重新构建。
开发热更新：pnpm run dev:web 会在一个终端里构建、启动，并在源码修改时重建 client bundle。
make help 列出 Web 与 Desktop 对应的 Make target。

方式 D：桌面版（自行构建）

仓库包含 apps/desktop，可用根目录脚本构建安装包：

sh
pnpm run build:desktop
pnpm run package:desktop:mac:arm64   # macOS Apple Silicon
pnpm run package:desktop:mac:x64     # macOS Intel
pnpm run package:desktop:win:x64     # Windows

桌面版适合需要原生窗口的场景；日常使用 Web UI 更简单，官方 README 也以 Web 为主。

4. 启动与运行命令

4.1 启动 Web UI

sh
npx @deepseek-ai/dsh web

默认行为：

监听 http://127.0.0.1:3080
本机启动时自动用默认浏览器打开页面
通过 SSH 启动时只打印宿主机 URL（本地转发地址由 SSH 客户端或编辑器持有）

4.2 常用参数

参数	作用
`--no-open`	只启动服务器，不打开浏览器
`--port <端口>`	指定端口，例如 `dsh web --port 8080`
`--help`	查看 web 应用自己的参数（不是启动器参数）

示例：

sh
# 换端口 + 不开浏览器
npx @deepseek-ai/dsh web --port 8080 --no-open

# 查看启动器参数
npx @deepseek-ai/dsh --help

# 查看 web 应用参数
npx @deepseek-ai/dsh web --help

启动器只解析自己的 flag，遇到第一个不认识的 token 就把其后的参数交给 profile 内的应用插件。所以 --port 必须写在 web 之后。

4.3 通过 SSH 或远程机器访问

推荐 SSH 端口转发，不要把无鉴权的 Web UI 直接暴露到公网：

sh
# 在本地终端执行
ssh -N -L 3080:127.0.0.1:3080 user@remote-host

然后本地浏览器打开 http://127.0.0.1:3080。

服务器侧启动：

sh
nohup npx @deepseek-ai/dsh web --no-open > ~/.dsh/web.log 2>&1 &

查看日志与停止：

sh
tail -f ~/.dsh/web.log
lsof -i :3080
kill <PID>

4.4 无头模式（一次性任务）

适合脚本、CI、定时任务：

sh
npx @deepseek-ai/dsh --profile headless "分析当前项目的依赖结构"

运行一个全新的持久化会话；
打印最终答案后退出；
运行目录即默认 workspace。

后台跑：

sh
nohup npx @deepseek-ai/dsh --profile headless "整理 docs 目录并输出摘要" \
  > ~/.dsh/task.log 2>&1 &

4.5 SDK 与 ACP 模式

sh
# JSON-RPC stdio，供 SDK 客户端
npx @deepseek-ai/dsh --profile sdk

# 极简 agent 配置树
npx @deepseek-ai/dsh --profile sdk-minimal

# Agent Client Protocol，供编辑器/自动化客户端
npx @deepseek-ai/dsh --profile acp

SDK 与 ACP 都是 profile，不是独立的公开可执行命令；Python 运行时 wheel 中也包含同一个 dsh 命令。

4.6 插件管理

sh
# 安装插件到 web profile
npx @deepseek-ai/dsh plugin --profile web add @scope/dsh-plugin-xxx

# 卸载
npx @deepseek-ai/dsh plugin --profile web remove @scope/dsh-plugin-xxx

dsh plugin 把参数转发给 profile 目录里的 pnpm，因此 add、remove 等 pnpm 子命令都可以用。安装和启动会校验插件声明的 DSH peer 版本范围；不兼容插件需要显式确认精确版本豁免。

4.7 配置诊断（不启动）

sh
# 查看默认配置树
npx @deepseek-ai/dsh --profile web --dump-default-config

# 查看组合后的实际配置
npx @deepseek-ai/dsh --profile web --dump-config

# 打印配置 JSON Schema（会导入插件声明的 schema）
npx @deepseek-ai/dsh --profile web --dump-config-schema

只对可信插件执行 schema dump；检查不受信任插件前先阅读官方安全说明。

4.8 自定义 profile

sh
# 基于 web 模板创建名为 work 的 profile 并启动
npx @deepseek-ai/dsh --profile work --from-default-profile web

# 之后启动
npx @deepseek-ai/dsh --profile work
# 或简写
npx @deepseek-ai/dsh work --port 3081

desktop 名称保留给 Electron 持有的 profile，CLI 会拒绝对它启动、dump 配置或管理插件。

5. 首次配置与使用

5.1 配置模型（DeepSeek 官方）

启动 dsh web，打开 http://127.0.0.1:3080；
进入 设置 → 模型；
在 DeepSeek 卡片填入 DeepSeek 平台的 API Key，保存；
模型路由立即生效，无需重启服务器。

密钥是只写的：保存后页面只拿到脱敏描述符，明文存在 $DSH_HOME/.credentials.yaml，settings 只保留引用。

5.2 选择工作区

点击 选择工作区，添加启动 dsh 时所在的项目目录并选中。未选中工作区前，会话输入框不可用。

5.3 跑第一个任务

新建会话，发送例如：

Summarize this repository and identify its main packages.

Agent 可以读写工作区文件、执行命令、委派工作、维护计划；按当前权限策略需要审批的操作会先询问。

5.4 页面配置模型（一）：内置第三方提供商

DeepSeek 官方：见 5.1（设置 → 模型 → DeepSeek 卡片填 Key）。

内置第三方：

设置 → 模型 → 添加模型提供商；
卡片默认停在 第三方模型提供商；
从列表选提供商 id：anthropic、openai、Kimi 的 moonshotai、GLM 的 zai 等；
填该提供商的 API Key，保存。

已安装目录会提供端点、协议和模型列表；通过 OAuth 登录的提供商（如 Codex）暂不支持。模型路由在下一次请求生效，不需要重启服务器。

5.5 页面配置模型（二）：自定义模型 API（分步）

适用于中转站、公司网关、自建服务。

打开 设置 → 模型，点 添加模型提供商；
把卡片切到 自定义模型 API；
填 Provider ID：小写、唯一，如 company-gateway、ccs-deepseek。它是永久标识，请求、会话、模型默认值和凭据引用都用它，保存后不能改名；要改名只能新建再删旧；
填 显示名称：只影响界面；
填 基础 URL：写到 /v1 为止，例如 https://gateway.example/v1、http://127.0.0.1:8080/v1；不要带 /chat/completions；
选 API 协议：OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 三选一，必须与网关实际协议一致；
填凭据：只填裸 API Key。不要粘贴 OPENAI_API_KEY=sk-xxx 整行，不要加引号；校验规则是 trim 后非空且全部为可打印 ASCII（[\x21-\x7E]）。若网关不校验鉴权，可填一个非空占位串；
添加模型：至少一条。可点「获取可用模型」探测，也可直接手填（字段见 5.6）；
点 Apply / 保存；
在会话页模型选择器选中它，或设为默认模型（见 5.7）。

一个提供商只能选一种协议；网关同时提供两种协议时，建两个提供商。

模型页会按 <PROVIDER_ID>_API_KEY 生成 apiKeyEnv 默认值。例如 Provider ID 为 ccs-deepseek，对应 CCS_DEEPSEEK_API_KEY，值写入 $DSH_HOME/.credentials.yaml 的 refs: 段。

5.6 模型条目字段说明

字段	作用	填法
Model ID	上游真实模型名	必填，必须与网关一致，如 `deepseek-chat`、`gpt-4o`
显示名称（Name）	模型选择器显示名	可留空；填 `Auto` 之类更易识别
上下文窗口（Context window）	声明可用上下文	按上游实际值；不确定时可留空或按 95% 保守折算
最大输出 token	单次输出上限	不确定就留空，用端点默认
输入类型	text / image	纯文本只留 text；多模态再勾 image

保存后写入 providers.<id>.models[]；同一提供商可并存多条模型，选择器按数组顺序展示。手工录入的模型不带推理等级，需要时在 cordis.patch.yml 补 reasoningEfforts（见 6.2）。

5.7 探测模型、默认模型与验证

探测模型：在 模型目录 点 获取可用模型，DSH 调用端点 GET /models，弹窗勾选后 添加所选；保存或创建提供商之前不会写入任何内容。

何时必须手填：探测只识别 {"data":[...]} 或 {"models":{...}}（对象）。若网关返回 {"models":[...]}（数组）等非标准结构，会报 llm/model-discovery-rejected，此时手填模型即可，与自动发现等价。

设为默认模型：模型页保存后会成为新会话默认值。等价的 YAML 配置是：

yaml
- id: agent-default-model
  config:
    provider: ccs-deepseek
    model: deepseek-chat

验证：新建会话，发 Reply with OK；失败按第 10 节排查。

6. 模型进阶配置

模型页写入的是 $DSH_HOME/profiles/web/cordis.patch.yml（用 dsh web 时 <profile> 就是 web）。修改后适配器在下一次请求时重读，无需重启。

6.1 自定义 OpenAI 兼容网关

yaml
- id: llm-pi-ai
  config:
    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]

baseURL 一般写到 /v1 结尾，以供应商文档为准。api 可选 openai-completions、openai-responses、anthropic-messages。

6.2 推理等级

yaml
- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        apiKeyEnv: GATEWAY_API_KEY
        api: openai-completions
        baseURL: https://gateway.example/v1
        reasoning: high
        models:
          - id: my-reasoner
            reasoningEfforts:
              off:
              high: high
              max: max

每个键是模型选择器里的等级，值是通过 reasoning_effort 发送的写法；
只有 off 可以留空（表示不传该参数）；
DeepSeek 官方路由无需此配置，已内置 off、low、high、max。

6.3 让 DeepSeek 模型真正「停止思考」

对「不明确关闭就会思考」的模型（例如 OpenAI 兼容网关后面的 DeepSeek V4），需要：

yaml
        models:
          - id: deepseek-v4-pro
            compat:
              thinkingFormat: deepseek
            reasoningEfforts:
              off:
              high: high
              max: max

thinkingFormat: deepseek 会让 off 发送 thinking: {type: disabled}，其他等级发送 thinking: {type: enabled}。

6.4 请求兼容性开关

很多网关会拒绝 OpenAI 的某些请求形状，最常见两项：

yaml
- id: llm-pi-ai
  config:
    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

supportsDeveloperRole: false：系统提示词不用 role: "developer"；
maxTokensField: max_tokens：输出上限改用 max_tokens；
路由上的 compat 是模型默认值，模型自身字段逐项覆盖；
写下的开关必须给值，冒号后留空会被拒绝。

6.5 图片输入

在模型编辑页的 自定义设置 → 模型选项 → 输入类型 勾选图片；或写 YAML：

yaml
          - id: vision-preview
            input: [text, image]

DeepSeek 直连适配器对应字段是 inputModalities；省略视为纯文本，空列表会被拒绝。

7. 目录、配置与数据

路径	内容
`$DSH_HOME`	主目录，默认 `~/.dsh`，可用环境变量覆盖
`$DSH_HOME/profiles/<name>/package.json`	profile manifest：树外插件依赖、`dsh.profile.bundles`
`$DSH_HOME/profiles/<name>/cordis.patch.yml`	该 profile 的用户配置（模型页写入这里）
`$DSH_HOME/cordis.patch.yml`	home 级覆盖，作用于所有 profile
`$DSH_HOME/.credentials.yaml`	凭据；`refs:` 段存放按 `<PROVIDER_ID>_API_KEY` 派生的键值
`$DSH_HOME/settings.yaml`	部分插件/配置向导使用的设置文件
`$DSH_HOME/.env`	可放代理变量等（已导出的环境变量优先）
`$DSH_HOME/sessions/`	会话记录，形如 `sessions/<cwd>/session-*.jsonl.zstd`

隔离多套环境：

sh
DSH_HOME=~/.dsh-work npx @deepseek-ai/dsh web --port 3081

8. 在 CC Switch 中接入 DSH

8.1 先说结论（截至 2026-10）

CC Switch（开源版，farion1231/cc-switch）目前不把 DSH 作为受管应用。官方 README 列出的受管工具是：Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code、Kimi Code。

社区需求在 issue 中跟踪：

https://github.com/farion1231/cc-switch/issues/6430（状态以仓库为准；相关实现 PR 尚未合并）

能力边界：

期望	能否做到
在 CC Switch 侧栏出现 DSH，一键切换供应商	❌ 不能
复用 CC Switch 里已配好的供应商地址/Key/模型	✅ 可以，手工映射（见 8.2）
统一统计 DSH 的 Token/费用	❌ 不能：DSH 直连上游，不走 CC Switch 本地路由；路由也只服务固定 app_type
用 DSH 的 profile / DSH_HOME 模拟「多供应商切换」	✅ 可以（见 8.4）

不要把 DSH 的 baseURL 指向 CC Switch 本地路由 http://127.0.0.1:15721：该路由只服务 Claude Code / Codex / Gemini CLI / Grok Build 等固定应用类型，没有通用 OpenAI 兼容入口，请求不会进入统计，通常也无法正确转发。

8.2 方案 A：复用 CC Switch 的供应商参数（推荐）

思路：CC Switch 继续做「供应商与凭据的单一来源」，DSH 侧手工登记同一个上游、直连上游网关。

第 1 步：在 CC Switch 里确认供应商

选一个能正常工作的供应商（DeepSeek 官方、硅基流动、OpenRouter 或中转站），打开供应商编辑页，记下三项：

API 地址 / Base URL
API Key（若已掩码，回供应商后台复制）
模型 ID（如 deepseek-chat、deepseek-reasoner）

同时看一下「高级选项 → 上游格式」，它决定 DSH 里选哪种协议。

第 2 步：在 DSH 里添加自定义提供商

启动 npx @deepseek-ai/dsh web；
设置 → 模型 → 添加模型提供商 → 自定义模型 API；
按下表填写：

DSH 字段	填什么
Provider ID	小写唯一值，如 `ccs-deepseek`（永久，不能改名）
显示名称	如 `CCS-DeepSeek`
基础 URL	CC Switch 里的 API 地址，通常以 `/v1` 结尾
API 协议	按下方对照表选
凭据	该供应商真实的 API Key；只填裸字符串，不要粘贴 `NAME=value` 整行或带引号
模型	手动填模型 ID（探测可能因格式不兼容失败）

协议对照表：

CC Switch「上游格式」	DSH「API 协议」
Anthropic Messages	`Anthropic Messages`（`anthropic-messages`）
OpenAI Chat Completions	`OpenAI Chat Completions`（`openai-completions`）
OpenAI Responses API	`OpenAI Responses`（`openai-responses`）
Gemini Native generateContent	❌ DSH 不支持，需要网关转成 OpenAI/Anthropic 格式

第 3 步：验证

保存后，在模型选择器选中新模型；
新建会话，发一句 Reply with OK；
失败时按第 10 节排查（401、协议 404/405、developer 角色被拒等）。

若供应商就是 DeepSeek 官方，不必走自定义提供商：直接用「设置 → 模型 → DeepSeek」卡片填 Key 更稳，DSH 内置的 DeepSeek 适配器支持推理等级与 thinking 开关。

该方案是直连上游，所以换供应商要改 DSH 配置，也不能享受 CC Switch 的失败切换与用量统计。

8.3 方案 B：把供应商写成 DSH 配置

适合想固定下来、或用脚本批量维护的场景。编辑 $DSH_HOME/profiles/web/cordis.patch.yml：

yaml
- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        apiKeyEnv: MY_GATEWAY_KEY
        api: openai-completions
        baseURL: https://api.deepseek.com/v1
        models:
          - id: deepseek-chat
          - id: deepseek-reasoner
            compat:
              thinkingFormat: deepseek
            reasoningEfforts:
              off:
              high: high
              max: max
- id: agent-default-model
  config:
    provider: my-gateway
    model: deepseek-chat

然后在 $DSH_HOME/.env 或 shell 里提供密钥：

sh
export MY_GATEWAY_KEY=sk-xxxxxxxx

也可以不用 apiKeyEnv，改为在模型页保存密钥（写入 .credentials.yaml 并由配置引用）。

要点：

agent-default-model 决定新会话的默认 provider 与模型；不写则沿用 bundle 默认；
compat 可写在 route 级（该 route 所有模型的默认值），也可写在单个模型上并逐项覆盖；
编辑已有覆盖项时要保留其他 provider 和字段，Cordis 的配置覆盖会替换整条条目；
Provider ID 一旦用于请求和会话就不可改名；
该文件由适配器在下一次请求时重读，通常无需重启；若未生效再重启 dsh web。

8.4 方案 C：用 profile 或 DSH_HOME 模拟「一键切换」

CC Switch 的核心价值是快速切换账号/供应商。在 DSH 里可以用两种粒度模拟：

粒度 1：多 profile（共享凭据，分开配置）

sh
# 首次：基于 web 模板创建 work profile 并启动
npx @deepseek-ai/dsh --profile work --from-default-profile web

# 之后：不同供应商对应不同 profile，用不同端口并行
npx @deepseek-ai/dsh --profile work --port 3081 --no-open
npx @deepseek-ai/dsh web --port 3080 --no-open

各自的模型配置在 $DSH_HOME/profiles/<name>/cordis.patch.yml；凭据仍共享 $DSH_HOME/.credentials.yaml。

粒度 2：多 DSH_HOME（完全隔离，最接近 CC Switch）

sh
# 供应商 A
DSH_HOME=~/.dsh-a npx @deepseek-ai/dsh web --port 3080

# 供应商 B
DSH_HOME=~/.dsh-b npx @deepseek-ai/dsh web --port 3081

每个 home 有独立的 profile、凭据、会话和插件。配合 shell alias 就很接近「切换」：

sh
alias dsh-a='DSH_HOME=~/.dsh-a npx @deepseek-ai/dsh web --port 3080'
alias dsh-b='DSH_HOME=~/.dsh-b npx @deepseek-ai/dsh web --port 3081'

注意：不要把两个实例指向同一个 DSH_HOME 和同一端口，profile 写锁与端口都会冲突。

8.5 方案 D：等官方支持

关注 issue #6430 与相关 PR。若自行构建带 DSH 支持的 CC Switch 分支，属于非官方用法：

数据库/配置格式可能随版本变化；
DSH 自身仍在开发者预览，插件与配置可能破坏兼容；
升级前备份 ~/.cc-switch 与 ~/.dsh。

8.6 用量统计

CC Switch 的用量面板依赖各工具会话解析或本地路由，DSH 两者都不满足，因此看不到 DSH 的调用明细。替代做法：

看上游控制台 / 中转站后台的账单与用量；
从 DSH 会话记录自行统计：~/.dsh/sessions/<cwd>/session-*.jsonl.zstd 中每条 assistant 消息带 usage: {inputTokens, outputTokens, cacheReadTokens}，可解压后聚合；
若网关支持，给不同用途分配不同 API Key，靠供应商侧分账。

9. 安全须知（务必阅读）

官方 SAFETY.zh.md 明确指出：DSH 是实验性软件，未经过安全审计，不应视为可安全用于生产环境。它可以执行模型生成的代码和命令、加载第三方插件，并访问被开放的网络、进程、凭据和文件。

建议：

只授予所需的最小权限与访问范围；
优先在一次性虚拟机、容器或专用环境中运行；
备份 DSH 可访问的文件；
不要把敏感凭据或数据暴露给它；
运行前检查插件、配置和将要执行的命令；
沙箱、审批提示与权限控制能降低风险，但不保证隔离；
Web UI 默认仅供本机使用，远程访问走 SSH 隧道，不要裸奔到公网；
~/.dsh/.credentials.yaml 明文保存凭据/API Key，不要提交仓库或外发。

10. 常见问题排查

现象	原因与处理
`npx` 一直卡住或版本很旧	配好 npm 代理；显式用 `@latest` 或指定版本
Node 版本报错	升级到 `^22.19.0` 或 `>=24`
端口被占用，Web 启动失败	`dsh web --port 8080` 换端口；`lsof -i :3080` 找占用进程
浏览器没有自动打开	SSH 场景正常；本机可手动访问打印的 URL，或去掉 `--no-open`
输入框不可用	还没选中工作区，先「选择工作区」
`MISSING_CREDENTIAL`	在模型页保存 Key，或提供配置引用的环境变量
`UNKNOWN_MODEL`	选已配置模型，或给自定义提供商补上模型 ID
「获取可用模型」返回 401	Key 错误；或端点没有 `GET /models`，改手动填模型
探测提示既无 `data` 也无 `models`	端点列表格式不兼容（如 `models` 返回数组），手动填模型
API key 输入框报格式错误	粘贴了 `NAME=value` 整行或带引号；只填裸字符串
同名 provider 冲突	UI 建的 route 与 patch 手写重复；只保留一处（建议保留 UI 写入的）
改了 patch 没反应	改错 profile 路径；先新建会话，仍无效再重启 `dsh web`
Key 和地址都对，但每个请求都被拒	先设 `compat.supportsDeveloperRole: false` 与 `compat.maxTokensField: max_tokens`
只有推理模型失败	网关拒绝 `developer` 角色，同上
手填模型没有推理等级菜单	在 `cordis.patch.yml` 给该模型加 `reasoningEfforts`
`off` 无法让 DeepSeek 停止思考	加 `compat.thinkingFormat: deepseek`
compat 开关报「没有值」	冒号后留空会被拒绝，给值或删掉该键
图片在发送前被拒	模型未声明 image 模态；加 `input: [text, image]`；DeepSeek 路由下选支持图片的目录条目
改完配置没生效	确认改的是当前 profile 的 `cordis.patch.yml`；多数配置下一次请求生效，插件/HMR 相关改动可能需重启
代理不生效	DSH 不读系统代理；导出 `HTTP_PROXY/HTTPS_PROXY`，且不支持 SOCKS
代理可达但报证书错误	设置 `NODE_EXTRA_CA_CERTS` 后重启
想彻底关闭遥测	`export DSH_TELEMETRY_MODE=DISABLED`

11. 命令速查

sh
# ===== 安装与版本 =====
npx @deepseek-ai/dsh --version
npx @deepseek-ai/dsh@latest web
npm install -g @deepseek-ai/dsh

# ===== 启动 =====
npx @deepseek-ai/dsh web
npx @deepseek-ai/dsh web --port 8080 --no-open
npx @deepseek-ai/dsh --profile web --port 8080

# ===== 一次性任务 =====
npx @deepseek-ai/dsh --profile headless "分析当前项目的依赖结构"

# ===== SDK / ACP =====
npx @deepseek-ai/dsh --profile sdk
npx @deepseek-ai/dsh --profile sdk-minimal
npx @deepseek-ai/dsh --profile acp

# ===== Profile =====
npx @deepseek-ai/dsh --profile work --from-default-profile web
npx @deepseek-ai/dsh --profile work --port 3081

# ===== 插件 =====
npx @deepseek-ai/dsh plugin --profile web add @scope/dsh-plugin-xxx
npx @deepseek-ai/dsh plugin --profile web remove @scope/dsh-plugin-xxx

# ===== 配置诊断 =====
npx @deepseek-ai/dsh --profile web --dump-default-config
npx @deepseek-ai/dsh --profile web --dump-config
npx @deepseek-ai/dsh --profile web --dump-config-schema

# ===== 帮助 =====
npx @deepseek-ai/dsh --help
npx @deepseek-ai/dsh web --help

# ===== 环境隔离 =====
DSH_HOME=~/.dsh-work npx @deepseek-ai/dsh web --port 3081

# ===== 后台运行 =====
nohup npx @deepseek-ai/dsh web --no-open > ~/.dsh/web.log 2>&1 &
tail -f ~/.dsh/web.log
lsof -i :3080
kill <PID>

# ===== 代理 =====
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export NO_PROXY=.corp.example.com,internal.example.com
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
export DSH_TELEMETRY_MODE=DISABLED

12. 参考链接

仓库与 README：https://github.com/deepseek-ai/deepseek-harness
官方文档站：https://deepseek-harness.github.io/deepseek-harness/
Web UI 指南：docs/user/guide/index.zh.md
模型配置：docs/user/guide/providers.zh.md
网络代理：docs/user/guide/network-proxy.zh.md
安全说明：SAFETY.zh.md
CLI 说明：apps/cli/README.zh.md
DeepSeek 开放平台：https://platform.deepseek.com/
CC Switch：https://github.com/farion1231/cc-switch
CC Switch 支持 DSH 的 issue：https://github.com/farion1231/cc-switch/issues/6430
CC Switch 使用文档：https://cc-switch.io/zh/docs