最近 Agent 工具的“harness”层正在形成一个新战场。Prime Agent、Claude Code、Codex CLI 都在争夺这块地盘DeepSeek 也抛出了自己的答案——DeepSeek Harnessdsh一个 MIT 开源、基于 Cordis 插件内核的 Agent 运行框架。它在 2026 年 8 月 13 日发布开发者预览版后迅速登上 GitHub Trending。但 dsh 不是 Claude Code 那种“装完就能用”的终端助手。它更像一个乐高底盘模型、工具、技能、会话、沙箱、存储、循环、调度、UI所有能力都是插件通过配置层的堆叠与覆盖来组合。这意味着“会启动 Web UI”只是起点真正会用它的标志是理解它的四层配置合成模型。这篇文章不会教你填 API Key。我会带你从npx deepseek-ai/dsh web出发拆解 profile、bundle、cordis.patch.yml、--patch四层如何合成一棵真实的插件树并给出 headless 模式与自定义插件扩展的实战步骤。一、背景为什么 agent 工具突然都在做“harness”过去一年LLM 的普及路径经历了明显的分层模型层DeepSeek、OpenAI、Anthropic负责“思考”IDE/客户端层Cursor、Claude Code、Codex CLI负责“把思考变成文件改动”而 dsh 这类harness 层则试图回答一个问题如果把“模型 工具 状态 会话”全部拆成可替换组件能不能让 Agent 既开放又可控dsh 的核心假设是Agent Model Harness。模型负责推理harness 负责让模型安全、持久、可审计地接触真实世界。它用 Cordis 作为插件元框架——这套机制在论文《A Programming Paradigm for Spatiotemporal Composability》里有形式化描述核心思想是“副作用可逆”插件可以动态挂载、卸载、替换运行中也能修改自身能力。但官方 README 也写得很直白DeepSeek Harness is currently in developer preview and is iterating rapidly.THERE WILL BE COMPATIBILITY-BREAKING CHANGES.所以本文不会把它捧成 Claude Code 的替代者而是把它当成一个需要理解架构才能用好的开发者预览品来实战拆解。二、环境准备真实版本号与安装命令所有命令在 Windows、macOS、Linux 上通用。请注意 dsh 对 Node 版本有硬门槛不要拿旧 LTS 硬跑。2.1 前置条件依赖版本要求来源Node.js22.19 或 24CI 覆盖 22.19 / 24 / 26官方docs/development.mdpnpm仓库锁定pnpm11.7.0需 Corepack 启用官方docs/development.mdGit2.26 或更新官方docs/development.mdAPI Key可选Web / headless / ACP 真实 API 测试需要官方 CLI reference# 检查 Node 是否满足要求 node --version # 输出应 v22.19.0 或 v24.0.0 启用 Corepack 并检查 pnpm corepack enable pnpm --version 输出应为 11.7.0 附近2.2 两种启动方式方式 Anpx 最快启动适合尝鲜npx deepseek-ai/dsh web这条命令会下载并启动 Web UI默认监听http://127.0.0.1:3080。注意dsh 目前故意不支持--host 0.0.0.0带这个参数会报 usage error。方式 B从源码构建适合写插件、看架构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。三、dsh 的插件分层没有“特权内核”dsh 最吸引人的宣传点是“Everything is a plugin”。但这句话不能只看字面。它的真实含义是dsh 把 Agent 的每一层都拆成 Cordis 插件并且没有任何一层在代码层面享有不可替换的特权。下图展示了从内核到外部插件的分层结构图1dsh 插件分层架构概念示意图非运行截图。最底层 Cordis 只负责插件的加载/卸载与依赖关系dsh-base 提供模型适配、工具、沙箱等基础能力其上再选择 web-app 或 headless 应用形态最外层是社区插件。各层职责如下Cordis 内核插件元框架负责服务注册、类型化事件、生命周期管理。它不实现任何 Agent 能力。deepseek-ai/dsh-base官方基础 bundle包含模型适配器、工具集、持久化、沙箱/审批策略、settings、credentials、telemetry默认关闭。应用层 bundledeepseek-ai/dsh-web-app提供浏览器 UIdeepseek-ai/dsh-headless提供一次性无 UI runner。out-of-tree 插件通过dsh plugin add安装的社区或私有插件仓库通常带dsh-pluginGitHub topic 以便检索。也就是说“模型”不是 dsh 写死的“UI”也不是 dsh 写死的。你想要换模型后端、换审批策略、甚至换一个完全不同的 UI 框架理论上都只需改配置文件不需要 fork dsh 源码。四、真正会用它四层配置合成模型这是本文的核心。理解下面这张图比记住任何安装命令都重要。图2dsh 配置合成顺序概念示意图非运行截图。空配置树依次叠加 bundle patch → profile patch → home patch →--patch覆盖层后一层按“行”覆盖前一层且 home 层优先级高于 profile 层。4.1 profile 目录里有什么每个 profile 是一个独立的 Node 工作区位于$DSH_HOME/profiles/name/$DSH_HOME/profiles/web/ ├── package.json # out-of-tree 插件依赖 dsh.profile manifest ├── pnpm-lock.yaml # 插件锁定 ├── pnpm-workspace.yaml # pnpm workspace 配置 ├── cordis.patch.yml # 你自己的 patch 层 └── node_modules/ # 插件 bundle 实际落在这里其中package.json里有一个关键字段{ dsh: { profile: { bundles: [ deepseek-ai/dsh-base, deepseek-ai/dsh-web-app ] } } }bundles的顺序就是配置合成的顺序。顺序变了最终生效的配置可能完全不同。4.2 四层合成顺序官方 CLI reference 白纸黑字定义了合成顺序空根配置树 → ① 各 bundle 的 patch按 bundles 顺序 → ② profile 的 cordis.patch.yml → ③ home 的 cordis.patch.yml → ④ --patch 覆盖层按 argv 顺序关键规则按行覆盖不是深度合并。后面的层如果命中了某一行就把该行的config整体替换没命中则保留前一层。可以插入新行。patch 不只能覆盖还能新增配置行。home 层优先级高于 profile 层。这一点反直觉。官方原话是home-level patch “outranks the per-profile layer”因为它被设计为“机器级偏好”跨 profile 共享。4.3 最容易踩的坑把 !!js 表达式写死了很多 bundle 的配置行会写类似这样的内容- id: webStartup config: port: !!js ctx.webStartup.port ?? 3080这行的意思是运行时去ctx.webStartup.port里取值取不到就用3080。于是命令行--port 8080才能生效。但如果你在自己的cordis.patch.yml里直接写- id: webStartup config: port: 8080你确实改了端口但你同时也把!!js表达式整个干掉了。以后再带--port 9090就无效了因为配置里已经是个纯字面量。经验法则能用--port解决的就别写死到 patch 里。如果必须写 patch优先只覆盖你真正需要改的行保留原 bundle 的表达式语义。五、用 --dump-config 对齐“我以为”和“真实生效”dsh 提供了两个 dump 命令专门用来排查配置合成结果# 只看 bundle 层默认合成结果 $ dsh --profile web --dump-default-config 加上 profile / home / --patch 后的真实生效树 $ dsh --profile web --patch ./extra.yml --dump-config这两个命令的本质区别见下图图3dsh 参数边界与 dump 可见范围概念示意图非运行截图。左侧说明 launcher flag 与应用参数的边界右侧说明--dump-default-config仅含 bundle 层而--dump-config追加 profile、home、--patch层。dump 输出的特点每行前面会有注释标注它来自哪个文件、被哪些覆盖层修改过。!!js表达式保持原样不会求值。没有命中目标的 patch 会输出到 stderr。dump 拒绝任何应用参数比如dsh --profile web --dump-config --port 8080会报错因为--port属于 web 应用。实际排查时建议先跑--dump-default-config确认 bundle 默认值再跑--dump-config确认自己的 patch 有没有意外覆盖掉不该动的东西。六、插件不只是 npm 包dsh plugin 的真实语义很多人看到 dsh 就说“它是基于 npm 的插件系统”。准确地说dsh plugin是带 bundle 自动调和的 pnpm 转发器。6.1 安装插件# 给名为 tui 的 profile 安装一个社区 UI 插件 $ dsh plugin --profile tui add github:deepseek-harness/turtle-ui 用 pnpm 的 update / remove / why 同样有效 $ dsh plugin --profile tui update $ dsh plugin --profile tui remove turtle-uidsh plugin --profile name会做三件事如果 profile 不存在自动初始化web/headless 从模板初始化其他名字用deepseek-ai/dsh-base。把后续参数转发给pnpm工作目录就是这个 profile 的目录。执行完后自动扫描所有已安装依赖把声明了dsh.bundle.patch的包加入dsh.profile.bundles。6.2 bundle 自动登记规则一个 npm 包如果想成为 dsh 的 bundle需要在它的package.json里声明{ dsh: { bundle: { patch: ./cordis.patch.yml } } }dsh 安装完会自动检查这个字段并把它加入dsh.profile.bundles。如果删除该依赖下次启动时它也会从层栈中移除。这个设计让 profile 的 bundle 列表始终和node_modules里的真实安装状态保持一致。6.3 git 源码插件的构建拦截如果你安装的插件是从 git 拉下来的源码包pnpm ≥ 10 会拦截它的prepare脚本第一次add会失败并提示你pnpm allowBuilds: key解决办法把提示的 key 写进 profile 的pnpm-workspace.yaml然后重新执行dsh plugin --profile name add ...。已经构建好的 tarball 或本地 checkout 不会被拦截。七、把 dsh 塞进 CIheadless 模式实战dsh 的 headless 模式很容易被忽略但它其实是把 dsh 接入脚本/CI 的关键入口。$ dsh --profile headless run the tests它的行为非常明确创建一个全新的持久化 Agent 会话。把任务文本提交给 Agent。等待任务进入“静默”状态。flush 会话。提取最后一条非空的 assistant 文本。如果任务 completedstdout 输出结果并退出码 0否则退出码 1。7.1 为什么适合 CI与 Web 模式相比headless 模式做了大量减法不启动 ApiProxy、Host、HTTP server、Web runtime、浏览器客户端。成功运行时不写 stderr也不监听任何端口。退出码语义清晰completed 0其余 1方便 GitHub Actions / GitLab CI 判断。7.2 一个 GitHub Actions 示例name: agent-smoke on: [push] jobs: harness: runs-on: ubuntu-latest env: DSH_HOME: ${{ runner.temp }}/dsh DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }} steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 24 - run: corepack enable - run: | npx deepseek-ai/dsh --profile headless Run npm test and report any failures concisely这个 workflow 里没有 Web UI没有手动点“同意”agent 会在 CI 环境里以workspace-write权限 preset 执行。注意dsh 的默认沙箱不限制网络访问和进程可见性它只把 bash 和文件系统写入限制在工作区内。如果你的 CI 环境敏感请额外配置DSH_PERMISSION_MODE。八、模式选择标准 / PTC / 极简 / 创造新建 Web 会话时dsh 提供了几种运行模式。官方文档没有把它们说得很系统但根据 CLI reference 和 UI 提示可以整理如下模式特点适合场景标准完整编码 Agent支持文件编辑、shell、搜索、skills、计划、子代理日常开发任务PTC标准模式能力 Code Mode SDK让模型用 TypeScript 程序组合多步操作复杂多步骤工作流极简只保留bash和str_replace_editor两个持久工具固定系统提示跑 benchmark、调试特定能力创造标准模式能力 preset 创作向导与运行时检查设计自定义 Agent preset其中“极简模式”对应官方minimalagent preset它的配置被设计为最小可复现集合很适合拿来做基准测试只给模型两个工具看它在限定条件下的表现。DSH_TOOLS_MODE环境变量还可以在进程级选择native内置工具、codeCode SDK 工具或both。九、避坑清单Node 版本不够dsh 需要 Node 22.19 或 24旧 LTS 直接启动失败。忘了选 workspacenpx deepseek-ai/dsh web启动后必须在 UI 里选 workspace否则输入框不可用。patch 写死导致 flag 失效把!!js表达式改成字面量后--port等命令行 flag 会失效。home 层覆盖 profile把通用配置写进$DSH_HOME/cordis.patch.yml会覆盖所有 profile 的同名行。telemetry 默认关闭但开启即无脱敏DSH_TELEMETRY_MODEFULL会导出消息文本、工具参数与结果、workspace 路径没有内置脱敏规则。MCP 默认不启用dsh 内置了 MCP client 支持但每个 MCP server 命令都是沙箱外的可信可执行代码默认不启用。源码启动没 buildpnpm dsh web需要先pnpm run build否则 module resolution 报错。--host 0.0.0.0不支持本地 only需要反向代理或 tunnel。十、总结与延伸DeepSeek Harness 的野心不在于做一个“更好用的 Claude Code”而在于把 Agent 的每一层都拆成可替换、可审计、可回滚的插件。这种架构带来的好处和风险都很明显好处你可以自由组合模型、工具、UI、沙箱策略官方、社区、私有插件可以在同一个配置层里混用。风险配置合成顺序和覆盖语义非常反直觉没搞清楚cordis.patch.yml的优先级就很容易出现“我以为改了但没用”“命令行 flag 突然失效”这类问题。掌握下面三个命令基本就能脱离“只会启动 Web UI”的阶段# 看 bundle 默认配置 $ dsh --profile web --dump-default-config 看真实生效配置 $ dsh --profile web --dump-config 在 CI 里跑一次任务 $ dsh --profile headless 你的任务描述延伸阅读与官方链接DeepSeek Harness 仓库GitHub - deepseek-ai/deepseek-harness: DeepSeek Harness: Everything is a Plugin. · GitHubdsh npm 包https://www.npmjs.com/package/deepseek-ai/dshCordis 插件元框架GitHub - cordiverse/cordis: Meta-Framework of Spatiotemporal Composability · GitHubCordis 论文《A Programming Paradigm for Spatiotemporal Composability》dsh CLI behavior referencedeepseek-harness/apps/cli/reference/README.md at master · deepseek-ai/deepseek-harness · GitHub官方讨论区deepseek-ai/deepseek-harness · Discussions · GitHub注dsh 当前为开发者预览版API 与行为可能随版本发生破坏性变更。建议先在独立项目或沙箱环境中试用再决定是否接入生产工作流。