无头运行避坑指南 Grimnirobser/running-dsh-headless

无头运行 DeepSeek Harness：没人写过的那些坑

在 macOS（Apple 芯片）上针对 @deepseek-ai/dsh 0.1.0-rc.6 测试，2026-08-17。dsh 是快速迭代的开发者预览版——预计其中一些问题很快会被修掉（或者以另一种方式坏掉）。

DeepSeek Harness（dsh）四天前发布，是我们见过架构上最有野心的开源智能体框架——所有东西，包括智能体循环本身，都是可替换的插件。文档写得不错。但它是写给坐在 Web UI 前面的开发者看的。

我们无头运行框架：由自动化启动，跑在没人盯着的机器上，由其他智能体驱动。今天用 dsh 这么干，会踩进几个没人提醒你的坑。我们全踩了一遍，你就不用踩了。其中两个已经提了上游（#2707、#1523）；下面是完整走查，附一份能跑通的配方。

60 秒顺利路径

Node 24.x recommended. The whole package tree is ~600 MB on first fetch.
export DEEPSEEK_API_KEY=sk-... # before launch — this is the trick
nohup npx -y @deepseek-ai/dsh web > ~/dsh-web.log 2>&1 &
wait for: dsh web: http://127.0.0.1:3080

隐藏的宝藏：环境变量自动发现 API key。 如果启动时 DEEPSEEK_API_KEY 就在服务器进程的环境变量里，官方适配器会按请求解析它，Web UI 会完全跳过「添加 API key」引导流程。不需要往 UI 里粘贴任何 key，也不会往磁盘写任何东西。对无头部署来说，这正是你想要的，而且很容易漏掉，因为引导对话框让填 key 看起来像必选项。

然后你点 Add workspace，结果……

坑 1：「Add workspace」按钮点了没反应

什么都没发生。没有对话框，没有报错，日志里也没有。按钮看起来是坏的，因为对你的进程来说它确实是坏的。

原因： dsh 的目录选择器本身就是一个可插拔的接缝，有三个后端：-native（操作系统文件夹对话框）、-browse（页面内的 Miller 分栏浏览器）、-auto（启动时自动挑一个）。在 macOS 和 Windows 上，-auto 假定存在显示会话——它自己的 README 都承认「Aqua 会话之外的 Darwin 进程仍算作有显示」。一个 nohup 或守护进程化的进程能通过所有检查，解析到 native，然后 macOS 拒绝这次交互。在贴近 GUI 的启动方式下，你至少还能看到 osascript 的 execution error: user interaction not allowed (-1713)（#335）；在完全脱离终端的启动方式下，你只会得到一片沉默（#2707）。

坑 2：文档里写的修复方案渲染不出来

文档给出的答案是固定 -browse 后端——「直接组合 -browse 行，这是接缝处文档化的替换点」。dsh 的配置系统在这里确实让人印象深刻，但有一个坑：

补丁无法就地替换某一行的插件 name——name 充当守卫：

patch: name mismatch for "directory-picker" (expected "...-auto", got "...-browse"), skipping

组合写法是禁用 + 插入，写在 ~/.dsh/profiles/web/cordis.patch.yml 里：

- id: directory-picker
name: '@deepseek-ai/dsh-host-directory-picker-auto'
disabled: true
- insert:
- id: directory-picker-browse
name: '@deepseek-ai/dsh-host-directory-picker-browse'

运行 dsh --profile web --dump-config，你会得到组合后的树，每一行都标注了哪一层动过它——可追溯性真的出色，而且补丁文件在运行时是热监听的。

然而：browse 后端的服务端部分挂载正常，浏览器端部分却始终不出现。服务端提供的客户端模块表（/plugins/@deepseek-ai//client.js）列出了约 37 个 UI 模块，其中没有一个 directory-picker 条目，于是工作区下拉菜单在空弹出层上切换 aria-expanded="true"。补丁插入的行似乎永远不会加入客户端模块表。Windows 源码构建和 macOS npx 安装上症状相同（#1523）。

逃生通道：直接走 RPC，跳过选择器

选择器只是用来生成路径字符串的 UX。它背后的 RPC 可以无头运行，而且线上格式是自描述的——你发垃圾数据过去，校验错误会告诉你信封长什么样：

curl -s http://127.0.0.1:3080/api/workspace.create \
-H 'content-type: application/json' \
-d '{"type":"client-request","rpcId":"cli","method":"workspace.create",
"payload":{"path":"/abs/path/to/project"}}'

{"result":{"ok":true,"value":{"workspace":{"workspaceId":"6ffcb28f-…","path":"/Users/observer/dsh-playground","title":"dsh-playground"}}}}

刷新页面：工作区已列出，composer 可用，模型路由已生效。workspace.list、session.list 之类的接口都遵循同样的信封。

它真的能用吗？（能——而且很快）

通过刚配置好的实例跑的第一个真实任务，用中文，要求它创建一个文件并汇报：

- 智能体跑了 Context injection → Think → Write → Think → answer，每一步都在 Chat 流里可见，并可在 Trajectory 标签页回放
- 墙钟时间：约 4 秒。hello.txt 已在磁盘上验证，内容与要求完全一致
- 统计栏显示：1 turns · 2 steps · LLM 2.4s · TTFT 0.7s · 144 tok/s · Cache hit 50% · Input 22.3K tok · Output 150 tok

会话第一轮就有 50% 的 KV-cache 命中率不是运气——dsh 把提示词前缀稳定性当作一等工程约束（仓库里有 233 个包的 README 都带一个必写的「KV Cache effect」小节）。这种纪律值得单独写一篇。

可用的无头配方，端到端

1. 用环境变量里的 key 启动
export DEEPSEEK_API_KEY=sk-...
nohup npx -y @deepseek-ai/dsh web > ~/dsh-web.log 2>&1 &

2. 等待就绪 until curl -sf http://127.0.0.1:3080/ >/dev/null; do sleep 2; done

3. 通过 RPC 创建工作区（完全跳过选择器）
curl -s http://127.0.0.1:3080/api/workspace.create \
-H 'content-type: application/json' \
-d '{"type":"client-request","rpcId":"init","method":"workspace.create","payload":{"path":"'"$PWD"'"}}'

4. 跑起来：Web UI 在 :3080，或者一次性无头运行
npx -y @deepseek-ai/dsh --profile headless "summarize this repository"

给 dsh 团队

已提交，附复现步骤和排查分析：在 darwin 上探测真实的交互能力，而不是想当然地假设它存在（照搬 Linux 上 zenity 的探测方式）；原生选择器挂掉时，UI 要明确报错；让补丁插入的行能加入客户端模块表（#2707、#1523）。这些都不伤架构 —— 上面每一个绕行方案都还留在产品自己的配置和 RPC 接口之内，这就是我们能给出的、对「一切皆插件」最有力的背书。

本文由 SkillRouter 团队撰写 —— 为 AI 智能体编写操作手册。我们在生产环境里跑 dsh 这类 harness，好让我们的地图保持新鲜；像这样的实地笔记只是副产品。*

License: CC BY 4.0。欢迎通过 issues/PRs 指正和补充。