DeepSeek Harness 实战指南
DeepSeek Harness(简称 dsh)是 DeepSeek 以 MIT 协议开源的 Agent 运行时。和常见的闭源编程客户端不同,它把执行循环、工具注册、上下文压缩、模型适配和界面全做成了独立插件(底层基于 Cordis 微内核),改能力基本就是改 YAML 配置或加减插件,不用动核心代码。
这篇不展开框架论文,直接整理截至 2026 年 11 月(v0.2 阶段)在本地跑通 dsh 的真实命令、配置文件写法、MCP 环境变量陷阱以及复用现有 .claude/ 资产的具体做法。
四种启动方式:按场景直接挑
dsh 围绕 Profile 组织运行形态,Web、终端、无头自动化各走各的 profile,互不打架:
# 1. 免全局安装直接拉起本地 Web 工作台(默认监听 http://127.0.0.1:3080)
npx @deepseek-ai/dsh web
# 2. 自定义端口启动 Web profile
dsh --profile web --port 8080
# 3. 终端交互模式并恢复历史会话
dsh --profile tui --resume <session_id>
# 4. 无头脚本模式(跑完打印结果并以退出码 0 退出,适合脚本或 CI)
dsh --profile headless "运行集成测试并总结失败用例的根因"如果不想开着终端进程,官方在 GitHub Releases 提供了打包好的 macOS(Apple Silicon)和 Windows 64 位桌面客户端,本质上是把 Web 工作台和本地运行时封进 Electron 壳里,适合日常常驻。
上手先注意两个细节:
- Web UI / 桌面端新建任务前必须先选定具体项目目录作为 Workspace,没选工作区任务发不出去;也不要偷懒把整个
$HOME挂进去。 dsh迭代很快,npm 上的latest与预发布 tag 偶尔存在版本差,遇到文档里的新参数不生效,先跑dsh --version对照官方 Releases 确认版本。
内置 Preset 与自定义模型接入
官方预设了四组常见工作模式(界面里通常显示为 Minimal、Standard、Code/PTC、Creator),本质上是不同的默认工具集组合(比如是否开启文件读写、持久终端和字符串替换编辑器),按任务轻重切换即可,不需要每次手写大段系统提示。
dsh 的配置采用三层叠加机制,后一层覆盖前一层:
- Profile 内置默认配置;
- 用户主目录补丁:
$DSH_HOME/cordis.patch.yml(默认~/.dsh/cordis.patch.yml); - 单次会话或项目级覆盖:启动时通过
--patch指定。
如果要把自建网关或第三方 OpenAI 兼容模型接进同一个界面,直接在用户配置或补丁里声明 provider,通过环境变量引用密钥而不写死明文:
llm-pi-ai:
providers:
custom-gateway:
apiKeyEnv: CUSTOM_API_KEY
api: https://api.example.com/v1插件管理与 MCP 接入(重点避开环境变量过滤坑)
官方内置的 MCP 客户端默认不启用,先通过内置插件管理器装到对应 profile 里:
# 为 web profile 安装官方 MCP 客户端插件
dsh plugin --profile web add @deepseek-ai/dsh-mcp-client
# 卸载不再需要的插件
dsh plugin --profile web remove <plugin-package-name>在 dsh 里,一个插件实例对应一个 MCP Server,暴露出来的工具会自动按 mcp__<serverName>__<rawToolName> 命名注册进 Agent 上下文。传输层同时支持本地 stdio 和远程 streamable-http。
把下面这段直接放进 cordis.patch.yml 就能挂接本地和远程 MCP:
- id: mcp-github
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: github
transport: stdio
command: npx
args: ['-y', '@modelcontextprotocol/server-github']
env:
GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN
- id: mcp-internal
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: internal
transport: streamable-http
url: http://localhost:3000/mcp
headers:
Authorization: !!js '`Bearer ${process.env.MCP_TOKEN}`'这里藏着一个非常容易排查半天的坑:使用 stdio 启动本地 MCP 子进程时,dsh 出于安全考虑会默认剥离宿主环境变量里名字带 KEY、TOKEN、SECRET、PASSWORD 的键。你明明在终端里 export GITHUB_TOKEN=... 了,MCP 子进程里拿到的却还是空的——必须在配置里像上面那样用 !!js process.env.GITHUB_TOKEN 显式映射,才能把凭据递进去。
直接复用已有的 .claude/ 仓库资产
如果你在仓库里已经按 Claude Code 最佳实践 沉淀了 .claude/ 目录(包括 skills、自定义 commands、rules、hooks 和 .mcp.json),不需要为 dsh 另写一套规范。社区维护的 dsh-claude-compat 兼容插件可以直接桥接这些现有资产;同理,也可以通过社区扩展(如 Codex Connect)把外部编码模型挂进同一个选择器做横向对比。
现阶段适合干什么、不适合干什么
把 dsh 放在独立开发者的工具箱里,定位其实非常清晰:
- 最值得用的场景:当开源多模型本地工作台、拿现成的
.claude/和 MCP 配置低成本评测开源模型在真实仓库里的表现,或者基于 MIT 协议二次开发自己的垂直领域 Agent 桌面工具。 - 目前别硬扛的场景:仓库的 SAFETY.md 明确写着尚未经过完整安全审计。加上「装第三方插件 = 本机直接执行对方代码」,不要在存有生产数据库密钥或云主账号凭证的环境里盲装社区插件,也不要拿它做高权限无人值守生产运维。日常主力写业务代码、提 PR,成熟度更高的 Claude Code 或 Codex 依然更省心。