<!--
DSH 插件生态公约声明（plugin-ecosystem-convention · 组合优先/声明清晰/兼容优先）
purpose: 给宿主的 ask_user_question 补「长时间无回答即跳过」——挂在 user-questions/request 公开 waterfall 上 race(人类回答, 超时)，超时抛出语义清晰的错误让 agent 继续
inject: （无 —— 纯 waterfall 中间层，不依赖任何 service）
tools: （无工具 —— 纯行为插件）
runtime: host-only（挂宿主公开 waterfall，不改宿主 packages/ 一个字节）
envDeps: 无
boundary: 中间层，不伪造答案、不短路下游链；人类路径零干预；下游错误原样传播
compat: cordis ^4.0.1 / dsh-tools >=0.1.0-rc.6
-->
dsh-agent-ask-timeout
一句话：给宿主的 ask_user_question 补一条超时——人类长时间不回答时，抛出语义清晰的错误让 agent 继续干活，而不是无限期卡住。
为什么值得用：没有它，一次无人应答的提问会让整个会话停在那儿（实测教训：2026-10-03 一次无超时的等待卡了 9.5 小时）。有了它，race(人类回答, 超时) 到点即返回错误——agent 拿到的是一个明确的失败信号（可以据此改道），而不是沉默。⚠ 它不是「自动替人回答」：超时路径只产生错误，不产生答案。
能力
行为侧（无工具）：挂在 user-questions/request 公开 waterfall 上做中间层——
- 人类在
timeoutMs内回答 ⇒ 与未装本插件时逐字一致地返回（I3） - 人类超时未答 ⇒ 抛出语义清晰的错误（不含
answers，I1） timeoutMs = 0⇒ 行为完全等同未装本插件（I4，fail-open）
快速开始
1) 装依赖（在目标 profile 的 package.json 加 link 依赖）：
"dsh-agent-ask-timeout": "link:E:/alice/self-plugins/dsh-agent-ask-timeout"
2) 挂组合：
- id: ask-timeout
name: dsh-agent-ask-timeout
config:
timeoutMs: 300000 # 5 分钟；0 = 关闭（回到宿主原语义）
3) 30 秒验证：调一次 ask_user_question 且故意不回答 → 应在 timeoutMs 后收到超时错误（而不是一直等待）；把 timeoutMs 设为 0 再试 → 行为应与未装本插件相同。
配置
| 项 | 默认 | 说明 |
|---|---|---|
timeoutMs |
见源码 Config 默认值 |
等待人类回答的上限；0 = 关闭（行为完全等同未装本插件） |
落盘与自证
本插件无持久产物——它是纯 waterfall 中间层，不写文件、不落侧车。判据因此全在行为侧（见下节），不靠轨迹文件。
生效判据与回退
怎么证明线上跑的是当前构建：
1. 行为级（最直接）：故意不回答一次 ask ⇒ 应在配置的超时后返回错误而非一直等；
2. 构建级：lib/index.js 的 mtime 晚于 web 进程启动时间（⚠ 重新构建 ≠ 生效——必须重启 web）。
回退：
1. 最快：config.timeoutMs: 0（I4 保证行为等同未装）；
2. 组合级：patch 行设 disabled: true；
3. 代码级：git revert → 重建 → 预检 + 重启。
测试
cd self-plugins/dsh-agent-ask-timeout && npm test
7 条用例（跑一次得到）：覆盖人类及时回答（逐字一致）· 超时抛错（不含 answers）· timeoutMs=0 的 fail-open · 必调 next()（不短路下游链）· 下游错误原样传播（不被超时逻辑掩盖）。无需网络与外部依赖。
设计要点
- I1 永不伪造答案：超时路径只产生错误，不产生
answers——这是本插件与「自动回答器」的分界线。 - I2 必调
next()：本插件是中间层，不是 answerer；不短路下游链。 - I3 人类路径零干预：人类在超时前回答时，返回的答案与未装本插件时逐字一致。
- I4 可关闭：
timeoutMs = 0⇒ 行为完全等同未装本插件（fail-open 到宿主原语义）。 - I5 不吞下游错误：下游 answerer 抛出的错误原样向上传播（不被超时逻辑掩盖）。
- 为什么不用「改宿主」的办法：宿主
packages/一改就要跟着版本升级反复迁移；挂公开 waterfall 是文档化扩展点，宿主升级不失效。
相关文档
docs/semantic.md—— 权威契约（定位/反定位 · 5 条不变量 · 验收表）- 中心仓：alice-digital-life（本插件归 治理层）
- 相关技能：
dsh-prompt-injection-placement（注入落位判据）
License
MIT © jonah791
本插件属于爱丽丝 DSH 自研插件生态（alice-digital-life · 73 个插件 · 8 个模块）：单一职责、独立仓库、独立可用。
