前言¶

在 DSH 里做自动化时，常见需求是：构建结束、告警触发或 CI 状态变化后，让已经在 Web GUI 里跑着的 Agent 会话立刻接一轮新任务，而不是再起一个 headless 进程或重开会话。

官方提供的脚本入口是 dsh --profile headless --session-id <id> "继续干活"，但它只能驱动从未记录过 agent preset 的裸 core 会话。Web GUI 创建的会话都会带上 preset（如 standard），headless 会直接报错「does not compose」。根因是 headless 在源码里无条件拒绝带 preset 的会话，补 bundle 或 --patch 也绕不过去。

dsh-session-wake 把 Host 侧与浏览器发消息同源的 sessionController.prompt() 做成外部可触发的桥，支持 HTTP 与文件队列两条通道，适合在「会话已持久化、preset 已固定」的前提下做本机联动。

这是什么¶

dsh-session-wake 是维护者 Asheep233 发布的 DSH host 平面插件（分类：联网工具）。它从外部进程向正在运行或已持久化的会话投递一条 user prompt，在几毫秒内启动新 turn，GUI 里可直接看到结果；支持 standard、ptc、minimal 等任意 agent preset，冷会话与忙碌中的会话均可处理。

实现上零 npm 运行时依赖，逻辑集中在单文件 lib/index.js，通过 ctx.webServer.register() 注册 HTTP 路由，并轮询文件队列；投递路径统一走 ctx.sessionController.prompt()，不重启 DSH、不换 preset、不改会话历史。

与 headless 的差异（简要）¶

核心功能¶

下面介绍资料中已写明的能力。

1. HTTP 唤醒（推荐）：对本机 dsh web 默认地址发 POST，毫秒级返回是否接受请求。
2. 文件队列：向 $DSH_HOME/wake-inbox（可配置 queueDir）写入 .req 或 .json；dsh 未运行时请求可积压，启动后补投。
3. 忙时排队：默认 mode: "queue"，当前 turn 不被打断；可选 "steer" 插入当前 turn。
4. 冷会话自动 resume：按会话记录的 preset 恢复 Agent 后再投递。
5. 幂等与自检：requestId 防重复插入；dryRun: true 只 inspect 会话、不跑模型。
6. 可选鉴权：配置 httpToken 后要求请求头 x-wake-token 或查询参数 token。

路由由插件自注册，不经过 /api/* 的 browser-trust 围栏；dsh web 默认只监听 127.0.0.1。

环境与安装¶

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

资料说明：dsh plugin add 只装包、不会把 bundle 写进 dsh.profile.bundles，本插件必须出现在 bundles 里才会被组合，因此推荐用仓库自带的装配脚本。

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

dev_inject_plugin /path/to/dsh-session-wake

方式 B：持久装配（推荐）¶

先把仓库放到本地插件目录，再执行官方 profile 装配脚本（默认 web profile），最后重启 dsh web：

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

install-into-profile.sh 会幂等地备份 package.json、写入 dependencies（link:）、追加 dsh.profile.bundles、建立 node_modules 链接。

方式 C：手动装配¶

1. 将本包放到 ~/.dsh/profiles/<profile>/node_modules/dsh-session-wake（symlink 到源码目录即可）。
2. 在 ~/.dsh/profiles/<profile>/package.json 中配置 dependencies 与 dsh.profile.bundles（示例见仓库 README）。
3. 重启 dsh web。

典型用法¶

HTTP¶

唤醒：向默认路径 /wake 投递 JSON（端口以你本机 dsh web 为准，README 示例为 3080）：

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":"磁盘告警，请处理"}'

查看桥状态（版本、心跳、处理计数、Host API 形状）：

curl -s http://127.0.0.1:3080/wake

自检（不跑模型）：

curl -s -X POST http://127.0.0.1:3080/wake \
  -H 'content-type: application/json' \
  -d '{"sessionId":"session-...","dryRun":true}'

常用请求字段：sessionId（可省略前缀 session-；省略时用配置的 defaultSessionId）、text（省略时用 defaultPrompt）、mode（queue / steer）、requestId、dryRun。

文件队列¶

默认目录为 $DSH_HOME/wake-inbox：

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/；心跳写在 wake-inbox/bridge.json。轮询间隔默认 pollMs 1500ms。

配置片段¶

在 cordis.patch.yml 的 config 中可覆盖默认值，例如开启 token、指定默认会话：

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

更多键（queueDir、pollMs、logFile、maxBodyBytes 等）见仓库 README 配置表。

适用场景与注意¶

适合：构建或测试完成后唤醒 Agent 继续下一步；本机告警脚本触发处置；CI、文件出现、定时器等只要能发 HTTP 或写文件的联动；需要替代或补充 schedule 的简单触发。

权限与安全：插件在当前 dsh web 进程权限下运行，HTTP 入口等价于「本机用户可向会话发消息」，与 Web GUI 同级。安装前请阅读仓库源码与 MIT 许可证，确认行为符合你的环境。不要把 dsh web 绑到公网（如 --host 0.0.0.0）再暴露未鉴权的 /wake；需要约束时配置 httpToken。

设计约束（资料原文）：

• 同一会话勿与 headless 等另一写者同时驱动，否则可能出现 session/writer-held。
• 插件不写自定义 session 事件，只走官方 prompt 收件箱。
• 冷会话沿用会话记录的模型；若 provider/model 已不可用，turn 可能以 NO_ADAPTER 结束。

升级 DSH 后可运行仓库内自检：

bash scripts/post-upgrade-check.sh

结尾¶

dsh-session-wake 把 Host 官方的 sessionController.prompt() 暴露给外部进程，用 HTTP 与文件队列解决「带 preset 的持久会话无法被 headless 一键唤醒」的问题，适合本机自动化与运维联动。社区目录页与源码仓库如下，版本与细节以 README 为准。

• 目录页：https://www.skillhub.cn/plugins/Asheep233/dsh-session-wake
• GitHub：https://github.com/Asheep233/dsh-session-wake