DeepSeek Harness（dsh）上手实测：官方开源的 Agent 框架，一条命令跑起来

DeepSeek 除了模型，还开源了一个 Agent 框架：DeepSeek Harness，命令名 dsh。它不是又一个「聊天壳子」，而是把 Agent 拆成了可插拔的插件集合——模型、界面、工具、工作流各自是插件，按 profile 组合起来启动。

我装了一遍跑通了第一个任务，把过程整理成这篇。适合已经用过 Claude Code / Codex 这类工具、想看看 DeepSeek 官方这套怎么玩的人。

版本基线：@deepseek-ai/dsh v0.1.0-rc.6 ｜ 项目状态：开发者预览（developer preview），迭代很快，不排除破坏性变更 ｜ 实测环境：Linux + Node 22

一、它和别的 Agent 框架有什么不同

三个设计点值得先讲清楚，理解了这三条，后面的命令就都顺了：

用一句话概括：dsh 不提供「一个固定产品」，它提供的是一套启动方式，你决定这次要拉起来什么。

二、安装：两条路，推荐全局装

环境要求很简单，Node.js 22 LTS 及以上即可：

node --version
npm --version

临时试一下（不装）：

npx @deepseek-ai/dsh web

全局安装（推荐，后续命令都能直接敲）：

npm install -g @deepseek-ai/dsh
dsh --version
# 输出示例：0.1.0-rc.6

国内网络如果卡在下载，先换源再装：npm config set registry https://registry.npmmirror.com。

三、跑起来：Web UI 三步走

dsh web

终端会打印访问地址，默认 http://127.0.0.1:3080，浏览器打开就能用。常用参数：

dsh web --port 8080                 # 换端口
dsh web --host 0.0.0.0              # 监听所有网卡（局域网可访问，注意安全）
dsh web --trusted-host myhost:8080  # 额外放行的 /api 信任域，可重复

--port 0 会让系统随机分配一个空闲端口。

进界面之后只需要三步：

1. 配模型 —— Settings → Models，在 DeepSeek 卡片里填 API Key 保存。保存即生效，不用重启。Key 是只写存储，页面只显示脱敏信息。
2. 选工作区 —— 点 Choose workspace，把项目目录加进来并选中。dsh 默认以启动命令所在目录为文件系统根；没选工作区之前，会话编辑器是灰的，这点新手最容易卡住。
3. 发任务 —— 新建会话，直接下指令，比如「总结这个仓库并列出主要包」。它会读写工作区文件、执行命令、拆子任务、维护执行计划；遇到需要审批的操作会先问你。

如果只是想在脚本或 CI 里跑一次性任务，用 headless 模式，出结果就退出：

dsh --profile headless "run the tests"

四、CLI 速查

dsh --help       # 启动器自身的帮助
dsh --version    # 版本号

入口模式：

全局选项里有两个排查利器：

参数传递有一条铁律：启动器只解析自己的参数，剩下的原样透传给 profile 应用。所以启动器参数在前、应用参数在后：

dsh --profile web --port 8080        # --port 是 web 应用的参数
dsh --profile web --help             # 看 web 应用自己的帮助（不是启动器的）
dsh --help                           # 看启动器的帮助

我第一次就栽在这里：想看 Web 参数敲了 dsh web --help，结果出来的是应用侧帮助，还以为文档写错了。

五、Profile 与插件：配置是怎么叠出来的

一个 profile 目录就两样东西：

• package.json —— 声明目录外的插件依赖，以及 profile 清单 dsh.profile（里面是有序的 bundles 列表）
• cordis.patch.yml —— 你自己的补丁层

最终配置树按固定顺序叠加，后者覆盖前者：

1. dsh.profile.bundles 里每个 bundle 的补丁（按列表顺序）
2. profile 自己的 cordis.patch.yml
3. 用户主目录级 $DSH_HOME/cordis.patch.yml
4. --patch 指定的覆盖层

bundle 优先从 dsh 安装包里解析（@deepseek-ai/dsh-base、dsh-web-app、dsh-headless 等），找不到再看 profile 自己的 node_modules。想确认自己改的配置到底生效没有，用 --dump-config 打印一遍，比猜快得多。

加插件就是往 profile 里装包：

dsh plugin --profile tui add <package>
dsh plugin --profile <name> <pnpm 参数>   # 其余 pnpm 命令照常转发

web 和 headless 两个 profile 首次使用会自动从内置模板初始化；其他 profile 得自己用 dsh plugin 建。

六、模型配置：官方 Key、目录 Provider、自建网关

模型改动在下一次请求时生效，不需要重启服务，这点体验很好。

官方 DeepSeek：Settings → Models，卡片里只有一个 API Key 输入框，填完保存。

目录 Provider：Add provider → 从目录里选（Anthropic、OpenAI 等），填 Key 保存。目录会自带端点、协议和模型列表。

注意：原生认证的 provider 不是填个 Key 就完事——Bedrock / Vertex / Azure / Codex 分别要 AWS 凭据+region、ADC 项目、api-version、OAuth。

自建网关 / 第三方兼容端点：选 Add a custom provider，需要提供 Provider ID（小写，定了就不能改，因为请求、会话、模型默认值、凭据引用都挂在它上面）、显示名、base URL、API 协议、凭据，以及至少一个模型。想改 ID 只能新建一个再删旧的。表单填好后点 Model catalog 的 Fetch available models，能从当前 base URL 拉取模型列表（走 OpenAI 兼容的 GET /models，不支持该端点的就手动填）。

让模型支持图片：手工填的模型默认按纯文本处理，要开视觉得在 $DSH_HOME/settings.yaml 里给该模型加 input：

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 支持 text 和 image，只作用于这一个模型；想让路由下所有手工模型都支持图片，可以在 route 上设一次 defaultInput: [text, image]（作为回退，不是强制覆盖）。目录模型则用 modelOverrides 按模型 id 单独收窄。

七、数据都在哪儿

所有用户态配置集中在 $DSH_HOME（不设置就用默认位置）：

迁移或备份时，把这几个位置打包走就行。

八、踩坑表（实测汇总）

九、想从源码跑

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 <args...> 跑 TypeScript 入口。

十、我的判断

dsh 目前还在 developer preview，别急着拿它替掉日常主力工具，但**「一切皆插件 + profile 组合」这个思路值得早点上手熟悉**——它意味着同一套框架既能当 Web IDE 里的编码助手，也能当 CI 里跑一次就退出的批处理执行器，切换成本只是换个 profile。

我的建议路径：全局装 → dsh web 配好 DeepSeek Key → 拿一个小仓库选成工作区 → 让它「总结仓库并列出主要包」，跑通这一条你就明白它和聊天机器人的区别了。

参考资料

• GitHub: deepseek-ai/deepseek-harness
• 讨论与 Bug 反馈
• 插件发现：给仓库加 dsh-plugin 话题

总结

DeepSeek Harness（dsh）是 DeepSeek 官方开源的 Agent 框架：一条 npm install -g 装好，dsh web 拉出 Web UI，配好 Key、选好工作区就能让它动手干活。核心概念就三个——插件、profile、补丁层叠加；踩坑集中在模型声明（图片模态）和参数传递顺序上，都有明确的解法。

相关文章：

• 将 DeepSeek Responses API 接入 Hermes Agent——同样是 DeepSeek 系，讲 API 协议层的差异与接入方案
• 在 VSCode 里用 Claude Code 接入 DeepSeek V4——如果只想在编辑器里用 DeepSeek 写代码，这条路更省事
• Codex 桌面版跳过手机号验证攻略——同属「把官方 Agent 工具跑起来」系列
• New API 公益中转搭建指南——自建 OpenAI 兼容网关后，正好可以按上面的「自定义 Provider」接进 dsh