目录

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 的配置采用三层叠加机制,后一层覆盖前一层:

  1. Profile 内置默认配置;
  2. 用户主目录补丁:$DSH_HOME/cordis.patch.yml(默认 ~/.dsh/cordis.patch.yml);
  3. 单次会话或项目级覆盖:启动时通过 --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 依然更省心。

参考资料