会话唤醒桥 Asheep233/dsh-session-wake

dsh-session-wake

从外部进程即时唤醒一个正在运行/已持久化的 DSH 会话，让它在几毫秒内接受一轮新 turn。
支持 standard、ptc、minimal 等任意 agent preset，冷会话/忙碌中的会话都行——这是 dsh --profile headless 做不到的。

外部进程 ──HTTP POST /wake──┐ └──写文件队列───────┤ dsh web 进程内（host 插件） └─▶ ctx.sessionController.prompt() ──▶ 目标会话新 turn（GUI 里直接可见）

- ✅ 不重启 DSH、不换 preset、不动会话历史
- ✅ 忙时排队不打断（mode:"queue"）、冷会话自动 resume
- ✅ 两条触发通道：HTTP（毫秒级）与文件队列（dsh 挂了请求积压、起来补投）
- ✅ 零运行时依赖（只用 node: 内置模块），单文件 lib/index.js

为什么需要它（以及为什么 headless 不行）

DSH 官方唯一「脚本唤醒会话」入口是 headless：

dsh --profile headless --session-id <id> "继续干活"

但它只能驱动「从未记录过 agent preset」的裸 core 会话。只要会话记录过 preset（Web GUI 创建的会话都记录），就报：

dsh: session "session-..." runs under agent preset "standard",
which the one-shot runner does not compose

根因不是 profile 组合不全，而是 @deepseek-ai/dsh-headless/lib/index.js 里的硬判断：

function assertAdoptable(header, events, sessionId, cwd) {
const preset = currentPreset(header, events, sessionId);
if (preset !== void 0) throw new Error(... does not compose); // ← 无条件拒绝
...
}

补 bundle、写 --patch 都不会改变这个判断（0.2.0-rc.2 读源码确认）。

正确入口是浏览器客户端发消息所用的同一个官方 Host 服务 —— ctx.sessionController.prompt()：

Admit one prompt after explicitly resuming its Session.

它按会话记录的 preset resume/组合 Agent，所以冷会话、standard 会话都能被它拉起来。本插件就是把这个能力包成外部可触发的桥。

安装

要求：DSH ≥ 0.2.0-rc.2（更低版本未验证）；dsh web profile（host 平面插件，不需要 client 半边）。

方式 A：运行时注入（有 dsh-super-injector 时，免重启）

dev_inject_plugin /path/to/dsh-session-wake

方式 B：持久装配（官方 profile 机制，推荐）

git clone https://github.com/Asheep233/dsh-session-wake ~/.dsh/plugins/dsh-session-wake
bash ~/.dsh/plugins/dsh-session-wake/scripts/install-into-profile.sh # 默认 web profile 然后重启 dsh web

install-into-profile.sh 做三件幂等的事（先备份 package.json）：写 dependencies（link:）、追加 dsh.profile.bundles、建 node_modules 链接。注意：dsh plugin add 只装包、不会加进 bundles（bundle 插件必须出现在 dsh.profile.bundles 才会被组合），所以别漏这一步。

方式 C：手动装配（知道自己在做什么）

1. 把本包装到 ~/.dsh/profiles/<profile>/node_modules/dsh-session-wake（symlink 到源码目录即可）
2. ~/.dsh/profiles/<profile>/package.json：

{
"dependencies": { "dsh-session-wake": "link:/path/to/dsh-session-wake" },
"dsh": { "profile": { "bundles": ["... 现有 bundles ...", "dsh-session-wake"] } }
}

3. 重启 dsh web

用法

HTTP（推荐：即时、有返回）

唤醒：给会话投一条 user message
curl -s -X POST http://127.0.0.1:3080/wake \
-H 'content-type: application/json' \
-d '{"sessionId":"session-1173e241-25f1-4a25-96f5-b48db0a3026c","text":"磁盘告警，请处理"}'
→ {"ok":true,"accepted":true,"sessionId":"...","requestId":"...","ms":37}

状态：桥版本、心跳、处理计数、依赖的 Host API 形状
curl -s http://127.0.0.1:3080/wake

自检：只解析会话、不跑模型（dryRun）
curl -s -X POST http://127.0.0.1:3080/wake \
-H 'content-type: application/json' \
-d '{"sessionId":"session-...","dryRun":true}'
→ {"dryRun":true,"sessionId":"...","found":true,"preset":"standard","cwd":"/path","events":4920,"live":true}

请求字段：

| 字段 | 必填 | 说明 |
| sessionId | 是* | 完整 session-<uuid>（可省略 session- 前缀）；省略时用配置的 defaultSessionId |
| text | 否 | prompt 文本；省略时用配置的 defaultPrompt |
| mode | 否 | "queue"（默认，忙时排队）/ "steer"（插进当前 turn） |
| requestId | 否 | 幂等键：同一个 id 重试不会重复插入消息 |
| dryRun | 否 | true 时只 inspect() 会话，不投递、不跑模型 |

路由由插件 ctx.webServer.register() 自注册，不经过 /api/ 的 browser-trust 围栏，因此外部进程可以直接调；dsh web 默认只监听 127.0.0.1。

文件队列（dsh 挂了也不丢，起来补投）

默认目录 $DSH_HOME/wake-inbox（可配置 queueDir）：

.req：第一行 session id（省略则用 defaultSessionId），其余为 prompt printf 'session-1173e241-25f1-4a25-96f5-b48db0a3026c\n磁盘告警，请处理\n' > "$DSH_HOME/wake-inbox/a.req"

或 .json
echo '{"sessionId":"session-1173e241-...","text":"构建完成，继续"}' > "$DSH_HOME/wake-inbox/b.json"

- 成功即删；失败移到 failed/<name>.<ts>.err；心跳写在 wake-inbox/bridge.json
- 轮询间隔 pollMs（默认 1500ms）——dsh 启动时会立即补投积压请求
- .json 兼容 BOM / CRLF（PowerShell Set-Content -Encoding UTF8 的产物直接可用）

触发场景示例

- 构建/测试完成 → 唤醒智能体继续下一步
- 磁盘/服务告警 → 唤醒会话处置（本项目来源场景）
- CI 状态变化、文件出现、进程退出码、定时器（替代/补充 schedule）
- 任意语言/任意进程，只要能发 HTTP 或写文件

配置

cordis.patch.yml 的 config（或运行时注入时传 config），全部有默认值：

| 键 | 默认 | 说明 |
| queueDir | null → $DSH_HOME/wake-inbox | 文件队列目录（null = 运行时解析） |
| pollMs | 1500 | 队列轮询间隔 |
| heartbeatMs | 10000 | bridge.json 心跳间隔 |
| logFile | /tmp/dsh-session-wake.log | 审计日志（追加） |
| defaultSessionId | '' | 请求缺 sessionId 时的默认目标 |
| defaultPrompt | 「外部唤醒：请检查最新状态与待办事项，并继续处理。」 | 请求缺 text 时的默认文本 |
| http | true | 是否注册 HTTP 入口 |
| httpPath | /wake | HTTP 路由路径（exact） |
| httpToken | '' | 非空时要求 x-wake-token 头或 ?token= |
| maxBodyBytes | 65536 | HTTP body 上限 |
| archiveDone | false | 成功后是否留档到 done/ |

示例：

- insert:
- id: dsh-session-wake
name: dsh-session-wake
config:
http: true
httpPath: /wake
httpToken: 'change-me'
defaultSessionId: session-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

语义与实测

| 场景 | 行为 | 实测（DSH 0.2.0-rc.2） |
| 热会话（web 进程内有 Agent） | 直接投递，起新 turn | accepted 39ms |
| 冷会话（仅持久化） | 按记录 preset 自动 resume，再起 turn | accepted 123ms，turn/start 正常 |
| 忙碌会话（正在跑 turn） | queue 模式排队，不打断，当前 turn 结束后处理 | 忙时投递 1ms 接受，结束后新 turn 处理 |
| 会话不存在 | HTTP 500 / 文件落 failed/ | {"error":"session \"...\" not found"} |

设计约束：

- 不写任何会话自定义事件：第三方插件 session.append() 自定义类型会让会话永久无法 resume
（Session.append() 无法设置 ignorable，reader 见到未知类型必须拒绝重建）。本插件只走官方 prompt 收件箱。
- 单写者：同一个会话同时被两个进程驱动会 SessionAlreadyOwnedError / session/writer-held。
如果该会话正在被 headless 驱动，别再用本桥；反之亦然。
- 冷会话沿用记录的模型：若会话记录的 provider/model 已下线，turn 会以 NO_ADAPTER 结束（机制本身正常）。

安全

- 服务默认只监听 127.0.0.1；HTTP 入口等价于「本机用户可发消息」，与 Web GUI 同级。
- 需要更强约束：配置 httpToken，请求带 x-wake-token: <token> 或 ?token=<token>。
- 不要把 dsh web 绑到公网再开这个入口（dsh web --host 0.0.0.0）——那等于开放任意 prompt 注入。
- 文件队列目录权限按需收紧（默认在 $DSH_HOME 下）。

兼容性与升级

依赖面刻意压到最小（零 npm 依赖、只 contact 两个 Host 服务）：

| 依赖 | 风险 | 说明 |
| profile dependencies + dsh.profile.bundles + cordis.patch.yml | 低 | 官方装配机制 |
| inject: ['sessionController','webServer'] | 中 | 服务改名会让插件停在 pending（可观测：无心跳） |
| ctx.sessionController.prompt(request, signal) | 低-中 | @Remote("prompt")，与浏览器客户端同一 RPC 契约 |
| ctx.webServer.register({kind,path,handler}) | 低-中 | 官方 webserver 路由 API |

升级后一条命令自检：

bash scripts/post-upgrade-check.sh
7 项：dsh 版本 / web 监听 / 路由 / API 形状 / dryRun 解析目标会话（不花 token）/ 心跳 / 事件循环

GET /wake 的 api 字段会带出 {sessionController, prompt, promptArity, inspect, webServer, register}；探测不到会打 ERROR 日志。若只是 API 形状变了，改 lib/index.js 的 deliver() / installHttp() 即可。

故障排查

| 现象 | 原因 / 处理 |
| curl /wake 404 | 插件没加载：确认 dsh.profile.bundles 含 dsh-session-wake，重启 dsh web；看 /tmp/dsh-session-wake.log |
| 日志 sessionController.prompt 不可用 | DSH 升级改了 Host API → 改 deliver()；GET /wake 的 api 字段定位 |
| session/writer-held | 该会话正被另一个进程（如 headless）驱动 → 换目标或停掉另一写者 |
| 文件请求不处理 | queueDir 与写入目录不一致（看 GET /wake 的 queueDir）；failed/ 里有错误文件 |
| 心跳过期 | 插件卡死/未 apply；tail /tmp/dsh-session-wake.log |

卸载

1. 从 ~/.dsh/profiles/<profile>/package.json 的 dependencies、dsh.profile.bundles 里删掉 dsh-session-wake
2. 删 node_modules/dsh-session-wake 链接
3. 重启 dsh web

（有注入器时也可 dev_uninject_plugin dsh-session-wake 立即卸载运行时实例。）

目录结构

dsh-session-wake/
├── package.json # dsh.bundle.patch 指向 cordis.patch.yml（官方 bundle 插件格式） ├── cordis.patch.yml # insert 本插件行（bundle 层） ├── lib/index.js # 全部实现（零依赖，单文件） ├── scripts/ │ ├── install-into-profile.sh # 持久装配（deps + bundles + link，幂等带备份） │ └── post-upgrade-check.sh # 升级自检（7 项） └── examples/ ├── curl-wake.sh # HTTP 触发示例 └── file-queue-wake.sh # 文件队列触发示例

实现要点：所有资源注册挂 ctx.effect（热重载/卸载自动清理）；投递串行化避免并发抢同一会话；文件按 rename 原子认领；同文件重试用内容 hash 做 requestId 幂等去重。

License

MIT