dsh-exec
eray114514/dsh-exec
在终端、脚本、CI 或另一个 agent 里一行调用 DeepSeek Harness:会话由桌面宿主进程创建,因此会实时出现在侧边栏并能继续;stdout 默认只有最终回答(可选 NDJSON 事件流),四个 Agent 预设(standard / ptc / minimal / cordis)可按次选择。它提供需要 bearer token 的回环 HTTP 路由,设置路由另外接受来自应用页面的同源请求。它的 HTTP 路由没有 DSH 的访问检查,浏览器里打开的网页可以调用它们。它的 HTTP 路由没有 DSH 的访问检查,浏览器里打开的网页可以调用它们。
安装
dsh plugin --profile web add github:eray114514/dsh-execREADME
dsh-exec
中文 | English
在终端、脚本或 CI 里一行调用 DeepSeek Harness,并且会话会实时出现在桌面端侧边栏。
dshx "把这个仓库的 lint 报错全部修掉"
dshx --cwd D:/repo --mode ptc "调研滚动闪烁的原因" > answer.txt
dshx --json "跑一遍测试" | jq -r 'select(.type=="final") | .text'
定位很简单:codex exec 那种形态,但它跑在你自己的桌面端里 —— 用你已经配好的模型、插件、技能和权限,结果既回到 stdout,也留在 GUI 里。
为什么不是 dsh --profile headless
headless profile 会写出完全合法的会话文件,但侧边栏不扫描那个目录:它读的是 ctx.workspaceRegistry,索引在内存里,只有创建会话的那个进程才会把会话 attach 到工作区。外部进程自己改 workspace.json 会被桌面端的内存副本覆盖掉。
所以这个插件把控制面注册在桌面 host 内部,每个会话都通过 sessionController.create({ workspaceId, agentPreset }) 创建:工作区行被 upsert、会话在进程内 attach、UI 从第一个 token 起就能跟着更新。
代价说清楚:桌面端必须开着。没开时 dshx 会明确报"找不到 bridge 文件",不会静默降级成 headless。
安装
dsh plugin --profile desktop add dsh-exec
带 client 半边的插件,装完/更新后完全退出 App 再打开(HMR 说 applied 不代表下次启动能加载)。
装好后设置面板里会多一个「命令行执行」页;命令行两个入口都可用:dsh-exec 和 dshx(同一个脚本)。
名字提示:
@why913/dshx这个包也声明了dshx命令(MCP/Skill 管理,功能不重叠)。两个都全局安装的话,用dsh-exec这个入口避开冲突。
CLI
| 命令 | 作用 |
|---|---|
dshx "TASK" | 建会话、跑任务、把最终回答打到 stdout |
dshx --cwd DIR "TASK" | 指定工作目录(决定侧边栏分组) |
dshx --session ID "TASK" | 续接已有会话 |
dshx --mode standard|ptc|minimal|cordis "TASK" | 显式选预设 |
dshx --model M --provider P --effort E "TASK" | 仅本次运行覆盖模型 |
dshx --permission P --approval A "TASK" | 仅本次运行的权限 / 审批 |
dshx --task-file PATH | 从 UTF-8 文件读任务(- = stdin),Windows 多行必用 |
dshx --json "TASK" | stdout 输出 NDJSON 事件流(codex exec --json 风格) |
dshx --verbose "TASK" | stderr 输出实时执行轨迹(opt-in) |
dshx --log RUN_ID | 回放某次运行的执行记录(只含元数据,不 dump 回答) |
dshx --status / --runs / --stop RUN_ID | 桥状态 / 运行列表 / 取消 |
默认输出只有最终回答,stderr 完全静默,所以 dshx "TASK" > answer.txt 是干净的。执行记录一律 opt-in。完成一轮退出码 0,否则 1。
Windows 多行任务
cmd.exe 在第一个换行处截断命令行 —— 7000 字的 prompt 会变成第一段。这是 shell 的限制,不是插件的:
$path = Join-Path $env:TEMP 'task.txt'
[System.IO.File]::WriteAllText($path, $task, [System.Text.UTF8Encoding]::new($false))
dshx --cwd 'D:/repo' --task-file $path
四个模式
宿主自带四个 Agent 预设,本质是四份插件清单;这里都能选(--mode 或设置页):
| 模式 | 是什么 | 适合 |
|---|---|---|
standard | 全功能编码 Agent:文件编辑、Shell、检索、Skills、计划、子代理 | 大多数任务(默认) |
ptc | 标准模式全量 + Code Mode SDK:模型写一段 TypeScript 编排多步工具调用,五次往返变一次 | 复杂多步任务 |
minimal | 只有持久 bash + 编辑器,固定提示词,无压缩无子代理 | 基准测试、控制变量 |
cordis | 标准模式 + cordis_* 自指工具:能检视、挂载、替换自己运行时里的插件 | 写插件、造自定义预设 |
界面上 ptc 和 minimal 默认藏在「代码工作工具」开关后面,但预设 id 本身可用,所以 --mode 直接选得到。
这是这个插件和官方一次性 headless 最实质的区别。 dsh --profile headless "TASK" 走的是 @deepseek-ai/dsh-headless(一个直接跑 core Agent/Session 的 bundle,没有 Host 层),它的组合里没有 agent-preset-registry —— 可以自己验:
dsh --profile headless --dump-config | grep preset # 只有 permission-presets
dsh --profile web --dump-config | grep preset # agent-preset-registry 在这里
预设只存在于 web/desktop 那套组合里。dsh-exec 是在桌面进程内通过 sessionController.create({ agentPreset }) 建会话的,所以等于把那四个预设借出来给命令行用:同一个 dshx,换个 --mode 就是另一种 Agent。
和别的"headless 命令行"比
codex exec | claude -p | dsh --profile headless | dshx | |
|---|---|---|---|---|
| 一行调用、stdout 出最终回答 | ✅ | ✅ | ✅ | ✅ |
| 会话留在同一个 GUI 里、能点进去继续 | 各自 CLI 的会话,不进 DSH | 各自 CLI 的会话,不进 DSH | ❌ 侧边栏看不见 | ✅ 侧边栏实时更新 |
| 可选 Agent 预设 | — 一套 | — 一套 | ❌ 组合里没有 preset registry | ✅ standard / ptc / minimal / cordis |
| 复用本机已配好的模型、插件、技能、权限 | — | — | ✅ | ✅ |
| 流式事件给程序消费 | 自家 JSON 格式 | 自家 stream-json | — | ✅ --json(NDJSON) |
| 长任务静默期的心跳 | — | — | — | ✅ progress{alive:true} |
"—" 是"这个工具没有这个概念",不是缺点:codex exec 和 claude -p 各自有成熟的会话体系,只是那套体系不在 DSH 里。最后一行针对的是会长时间退避的 provider —— 静默 5 分钟到底是"在等"还是"挂了",只有心跳能回答。
默认值是"中性"的
这个包会装到别人的机器上,所以出厂默认不绑定作者的任何偏好:
- 不固定模型(
defaultModel: '')。留空 = 沿用桌面端当前模型。只有你填了模型并打开enforceDefaults,新会话才会被selectModel钉住 —— 硬编码一个别人机器上没有的模型会让每次运行都失败。 - 权限
workspace-write+ 审批never:够干活,也不会在无人值守时卡在审批弹窗上。danger-full-access是单次运行的选择(--permission danger-full-access),不是默认值。 - 不传
--model/--effort就一个都不发,不会被隐藏默认值影响。
想改本机默认值:打开设置页保存即可,不必改 YAML——存到 <DSH_HOME>/plugin-data/dsh-exec/config.json,叠加在 profile 的 cordis.patch.yml 之上(「恢复配置默认值」会删掉这个文件)。当然想直接改 YAML 也行,那一层是 profile 自己的,优先级比这个文件低。
设置页
设置 → 命令行执行(中英双语,跟随界面语言):
- 默认模式(四个预设)、默认模型 / 模型来源 / 思考档位
- 是否把新会话强制钉在上面那个模型
- 权限、审批策略、是否自动创建工作区
- 心跳间隔、并发上限
- 保存 / 恢复配置默认值
页面上同时显示桥状态(在线、运行中、累计运行、429 重试次数、pid 与端口)。
HTTP API
全部走回环地址;除标注外需要 Authorization: Bearer <token>(token 在 <DSH_HOME>/storages/dsh-exec.json,权限 0600,从不进入渲染进程)。
| 路由 | 方法 | 用途 |
|---|---|---|
/dsh-exec/status.json | GET | 桥状态、计数、生效配置(免 token,且不含运行详情) |
/dsh-exec/runs.json | GET | 运行列表 |
/dsh-exec/runs.json | POST | {task, cwd?, sessionId?, mode?, model?, provider?, effort?, permission?, approval?} → 202 + run |
/dsh-exec/runs.json | POST | {action:"stop", runId} → 取消 |
/dsh-exec/events.jsonl?runId=…&since=N | GET | NDJSON 流,可从 since 重放;snapshot=1 回放后立即关闭 |
/dsh-exec/config.json | GET | 生效配置(免 token) |
/dsh-exec/config.json | PUT | 保存默认值;需要同源或 bearer token |
响应里从不包含任务正文,也不包含 token。
429 不是崩溃
有些 provider 在配额吃紧时会返回 429 RESOURCE_EXHAUSTED。DSH 的重试层不会因此结束这一轮:它按退避等 30–300 秒,然后在同一个 turn 里重跑同一步。等待期间会话日志几乎不动,这种安静很容易被误读成"进程死了" —— 尤其是你并不总是盯着屏幕。
不是每个 provider 都会这样,也不是每个用 DSH 的人都会遇到;但只要遇到一次,你就会知道靠"日志有没有动"判断存活有多不可靠。
所以桥每 heartbeatMs(默认 15 秒)发一个 progress 帧,带 elapsedMs、silentMs、steps、retries 和 alive: true,外加带 provider 错误码的 retry 帧。dshx 会明说"provider 要求退避,turn 还在跑"。判断存活看心跳,不要看日志安静不安静。
退出取证:谁关掉了 DSH
host 会在 <DSH_HOME>/storages/ 写两个文件:
| 文件 | 行为 |
|---|---|
dsh-exec-heartbeat.json | 每 lifecycle.heartbeatMs(20 秒)覆盖写:pid、ppid、uptime、RSS、堆、活跃运行数 |
dsh-exec-lifecycle.jsonl | 追加式关键事件,超过 lifecycle.maxLogBytes(512 KB)轮转 |
记录的事件:start、before-quit(带调用方堆栈)、window-close、window-all-closed、will-quit、quit、exit、signal、uncaught、unhandled-rejection、os-shutdown / os-suspend / os-resume。
下次启动会判定上一个进程:
| 判定 | 证据 | 含义 |
|---|---|---|
clean | before-quit → quit/exit 且晚于最后一次心跳 | 正常退出;堆栈指出是谁发起的(托盘菜单、更新器、菜单项) |
killed | 心跳是新的,但没有任何退出事件 | TerminateProcess(任务管理器 / 清理工具)、硬崩、断电 |
crashed | 有 uncaught 记录 | host 未捕获异常 |
unknown | 心跳远早于下次启动 | 机器睡眠 / 关机,或心跳早就停了 |
用 dshx --status 看 lastExit。TerminateProcess 无法指名凶手(Windows 不告诉受害者),但能证明"不是通过它自己的菜单退出的" —— 这通常就是关键区别。
已知边界
- 只有 desktop profile 有这些服务。
sessionController/workspaceRegistry/webServer/agents不是文档化的插件 API;web / headless / acp profile 里它们不存在,插件会安静地不激活。跨版本可能碎,engines.dsh只声明验证过的范围(0.2.x)。 - 事件流在内存里,有上限(
maxEventBuffer)。缓冲滚掉之前用since重连。 stop是请求取消;已经在飞的一步可能先跑完。- 桌面端必须运行,没有 headless 兜底。
开发
node tests/offline.cjs # 假 ctx + 假 webServer,不起真实进程
覆盖:配置归一化与分层、请求校验、事件投影、四个路由、token / 回环 / 同源授权、工作区 + 预设 + 权限接线、只在被要求时覆盖模型、实时 NDJSON、turn/end 上的 final、免 token 状态的脱敏、bridge 文件清理、HMR 重载复用 token。
License
MIT