问答超时提醒 SJTUMalPan/dsh-ask-timeout-notify

dsh-ask-timeout-notify

DSH 宿主插件：模型通过 ask_user_question 提问后，如果超过阈值（默认 60 分钟）仍无人回答，就往 notify-hub 投递一条 need_ack 消息，由 notify-hub 落成待办并按渠道推送（飞书 / webhook / email）。

典型场景：模型问了个选择题就去干别的了，你在开会/出门，DSH 的会话就这么挂着。
本插件让你在飞书里收到一条“DSH 在等你回答”的待办，而不是事后才发现它等了两小时。

它做什么、不做什么

| 做 | 不做 |
| 在 user-questions/request 这条 waterfall 链首起一个定时器 | 不替用户作答，也不改变 DSH “一直等”的语义 |
| 到点往 notify-hub 投一条待办（带 dedup_key 去重） | 不改 notify-hub 一行代码、不需要给它加规则 |
| 用户答了/请求取消/出错了就销毁定时器 | 不影响问答主流程（投递失败只记日志） |

为什么不用改 notify-hub：POST /api/v1/messages 本来就接受调用方声明 need_ack: true——分类器按 declared_need_ack or rule.need_ack 裁决并记
ack_reason=caller_declared，待办因此自动产生；dedup_key 让同一问题重复超时不会刷出
多条（服务端按 (source, dedup_key) 复用未完成的待办）。所以本插件只是一个普通的消息
生产者，跟 CI 脚本、监控告警走同一个入口。

什么时候会触发、什么时候不会

这一点是在真实 DSH 进程里实测确认的（不是推测），值得先讲清楚：

| 场景 | 链上的表现 | 本插件的行为 |
| 前端开着、你在忙，一直没点 | 回答者接手，next() 一直挂着 | 到阈值投一条待办 ✅ |
| 前端关掉 / 没有回答者 | 链上立刻以 NO_PROVIDER 拒绝 | finally 销毁定时器，不发（这条问答已经失败了，不是「在等你」）❌ |
| 前端开着，但你在阈值内答了 | next() 正常返回 | 定时器销毁，不发 ✅ |
| 会话被取消 / 处理中断 | next() 抛错 | 定时器销毁，不发 ✅ |

也就是说：它管的是「人还没回」，不是「人不在」。浏览器关掉导致无人接手时，DSH 会立刻判定这条问答失败，那种情况不会有待办——本插件的价值恰好在前端还开着、会话真的挂着等你的那段时间。

前置条件

1. DSH 已安装并能跑 dsh web（profile 名为 web）。
2. notify-hub 在跑，且你知道它的地址与访问令牌：
- 地址：默认 http://127.0.0.1:8000；
- 令牌：config.yaml 里 server.auth_token 的值（未配置令牌 = 服务不鉴权，此时本插件也要给一个非空令牌值，随便填即可——见下面「配置」）。

安装

本插件是独立仓库（仓库根目录就是插件包，因此插件市场的
dsh plugin add github:SJTUMalPan/dsh-ask-timeout-notify 可直接安装）。
它原先住在 notify-hub 仓库的 dsh-plugin/ 子目录里，拆出来时保留了提交历史。

从 GitHub 安装（推荐，锁 commit）

跟最新 main（方便，但会被上游改动影响）
dsh plugin --profile web add github:SJTUMalPan/dsh-ask-timeout-notify

锁 commit（可复现）
dsh plugin --profile web add "git+https://github.com/SJTUMalPan/dsh-ask-timeout-notify#"

本机开发（符号链接，改完即生效，不用重装）

dsh plugin --profile web add "link:$PWD" # 在本仓库根目录执行

裸路径与 link:/file: 是 pnpm link 语义（符号链接）：源码改了不用重装，但换机器就断。

安装之后

dsh plugin add 会做两件事：把包装进 ~/.dsh/profiles/web/，并把包名追加进该 profile
package.json 的 dsh.profile.bundles（因为本包声明了 dsh.bundle.patch）。所以不需要手改 profile 的任何文件。然后：

重启 dsh web 才生效（profile 的插件组合变更只对新进程生效）

卸载：

dsh plugin --profile web remove dsh-ask-timeout-notify

配置

两种方式，环境变量优先（同一份插件装在多台机器上时，只有环境变量能表达机器差异）。

| 环境变量 | cordis.patch.yml 里的键 | 默认 | 说明 |
| DSH_ASK_TIMEOUT_MINUTES | timeoutMinutes | 60 | 等待多少分钟算超时（正整数，1–10080） |
| DSH_NOTIFY_HUB_ENDPOINT | endpoint | 无（必填） | notify-hub 地址，如 http://127.0.0.1:8000 |
| DSH_NOTIFY_HUB_TOKEN | token | 无（必填） | 访问令牌，放查询串 ?token=…，不写日志 |
| DSH_ASK_NOTIFY_ENABLED | enabled | true | 设 false 可整体关闭 |
| DSH_ASK_NOTIFY_REQUEST_TIMEOUT_MS | requestTimeoutMs | 5000 | 单次 HTTP 投递超时（毫秒） |
| —（只认 config） | source | dsh | 消息来源标识，notify-hub 规则匹配用 |

环境变量应该跟 dsh web 的启动方式放在一起（例如启动脚本里 export），不要写进仓库。
修改 cordis.patch.yml 里的 config（~/.dsh/profiles/web/node_modules/dsh-ask-timeout-notify/cordis.patch.yml 不会生效——它属于包本身；要覆盖请改 profile 自己的 ~/.dsh/profiles/web/cordis.patch.yml）：

~/.dsh/profiles/web/cordis.patch.yml
- id: ask-timeout-notify
config:
timeoutMinutes: 15

怎么判断它在工作

- 没配置端点/令牌时：插件照常装载，但启动日志会有一条 warn 说明原因，超时后不会产生待办。这是刻意设计——补上环境变量重启即可生效，而不是静默缺席。
- 投递成功：DSH 日志里出现
ask-timeout-notify: 已投递待办 message_id=… todo_id=… dedup=ask::。
- 投递失败：日志里 ask-timeout-notify: 投递失败（…）；不影响等待中的问答，同时 DSH 里的问答照常继续等——通知失败永远不影响主流程。

DSH 的 ctx.logger.info 不一定落到 stdout（取决于 profile 的日志配置），所以最可靠的旁证是 notify-hub 侧：/todos 页面出现一条 source=dsh 的待办。

排障

| 现象 | 原因与处理 |
| 待办没出现，日志也没有 已投递 | 端点或令牌没配。用 curl -sS "$ENDPOINT/healthz" 先确认服务活着（/healthz 免鉴权） |
| 日志报 401 | 令牌不对。令牌取自 notify-hub config.yaml 的 server.auth_token |
| 日志报 请求超时 | notify-hub 没起或地址不可达；若它挂在公网隧道后面，确认隧道在线 |
| 有 apply 但从不触发 | 定时器只在有提问时才会起。让模型真的调一次 ask_user_question 试试 |
| 收到多条待办 | 不该发生——dedup_key 保证同一问题只建一条。若同一条待办被反复提醒，那是 notify-hub 的 reminders 在按日提醒，不是本插件 |
| 想立刻验证 | 把 DSH_ASK_TIMEOUT_MINUTES 设为 1，重启 dsh web，让模型问一个问题，然后不要回答，一分钟内应收到待办；验证完改回 60 |
| 启动报 Cannot find module '…/dsh-plugin/index.json' | 你是在 --patch 里写了目录路径。loader 对目录路径按 cordis:include 目录入口处理（找 index.json），不会读 package.json 的 main。--patch 里要写入口文件：.../dsh-plugin/lib/index.js；只有通过 dsh plugin add 安装（按包名装载）时才用目录/包名 |

开发

cd dsh-plugin
npm test # = node --test test/*.test.mjs

测试覆盖三块：配置解析（含环境变量/ config 优先级与非法值回退）、请求体构造（dedup_key 稳定性、字段只含契约声明的键）、以及真实 HTTP 投递——测试里起一个真的 node:http 服务端，断言发出去的请求行（含 ?token= 转义）、请求头与请求体，而不是断言我们自己的对象。超时、401、连不上、非 JSON 响应都有对应用例。

零依赖、纯 ESM JavaScript，没有构建步骤（这是刻意的：git 安装的包若要跑 prepare 脚本，pnpm 需要在 pnpm-workspace.yaml 的 allowBuilds 里逐个放行，一个百行插件不值得背这个负担）。

文件

| 文件 | 作用 |
| package.json | 声明 main 与 dsh.bundle.patch（后者是本包能成为 profile 层级的关键） |
| cordis.patch.yml | 两行 insert，把本插件挂进 profile 插件树 |
| lib/index.js | Cordis 接线：事件监听、定时器、effect 生命周期 |
| lib/notify.mjs | 纯函数层：配置解析、请求体构造、HTTP 投递（可独立测试） |
| test/notify.test.mjs | 单测 |