hermes-connect-services 1.1.0 → 1.3.0

package/README.md

@@ -118,8 +118,66 @@ model:
 | `… --no-reasoning` | 全部模型标 `supports_reasoning: false` |
 | `… --config <path>` | 指定配置文件 |
 | `node bin/ensure-services.mjs [--verbose]` | 单独执行懒启动(也是 hook 本体) |
+| `node bin/patch-hermes-stall-gate.mjs` | 给 hermes 补「宣布下一步却没动手」的续跑闸门 |
+| `… --check` | 只报告补丁状态(升级后跑一次看是否失效) |
+| `… --revert` | 撤销补丁,恢复到原始字节 |
 
-## 五、排障
+## 五、续跑闸门:模型说要做什么,然后就停了
+
+模型常见的收尾是「我先检查配置，再修改这里：」——宣布了下一步,零工具调用就结束这一轮。这不是完成,是卡住。
+
+ZCode / pi / dsh 三端各有一个官方钩子点可以兜住(Stop hook、`turn_end`、`agent/turn-stopping`)。**hermes 没有**:
+
+- `hermes_cli/plugins.py` 的 `VALID_HOOKS` 里没有任何「回合正常结束」事件(`agent_loop_stopped` 是 `/stop` 打断,不是收尾)。
+- 唯一能续跑的闸门是 `pre_verify`,但它的前置条件是 `if _edited and has_hook("pre_verify")` —— 本轮**写过文件**才触发。而「我先检查配置」这种收尾往往只读不写,或一个工具都没调,正好落在门控之外。
+- 内置的 `_dropped_toolcall_nudge` 只处理 `finish_reason == "tool_calls"` 但 `tool_calls` 为空 —— 协议层信号,精确但覆盖面窄。
+
+所以只能往宿主的收尾闸门链里加第 5 道。
+
+```sh
+node bin/patch-hermes-stall-gate.mjs            # 打补丁
+node bin/patch-hermes-stall-gate.mjs --check    # 看状态
+node bin/patch-hermes-stall-gate.mjs --revert   # 干净回退
+```
+
+改动面刻意压到最小 —— 宿主原有行一个字节不动:
+
+| 文件 | 改动 |
+|---|---|
+| `agent/turn_stop_gates.py` | 两个 marker 块:模块级判定函数 + 一处调用 |
+| `agent/stall_detector.py` | 新增,判定逻辑本体(与 JS 版逐条对齐) |
+
+`--revert` 会从首次打补丁时留下的快照还原 `turn_stop_gates.py`,实测与原始文件**逐字节相同**。
+
+### 生效方式
+
+**改完必须重启 hermes gateway** —— 已 import 的模块不会自动重载,不重启就等于没打。
+
+### hermes 升级会覆盖
+
+自更新会重置 `hermes-agent/` 下的源码,两块一起消失。表现是「续跑不再发生」而不是报错:模块级 import 包在 `try/except` 里,`stall_detector.py` 不在时闸门静默失效,不影响正常结束。升级后重跑一次脚本即可,`--check` 会告诉你当前状态。
+
+### 开关与防护
+
+```yaml
+agent:
+  stall_guard: false      # 或环境变量 HERMES_STALL_GUARD=0
+```
+
+- **同一段回复只续一次**:按文本 sha1 指纹去重,模型被提示后原样复读不会二次触发。
+- **一个会话上限 3 次**:与 ZCode 侧一致。连续 3 次都唤不醒,再提示也只是复读计划。
+- **本轮有工具调用就不判**:`_zc_tool_calls_this_turn()` 只看最后一条 user 消息之后的 `tool_calls`,`> 0` 一律跳过。
+- 闸门内部全部 fail-open:任何异常只写 debug 日志,绝不让一次正常收尾因为插件出错而崩。
+
+### 阈值不是「看到冒号就续跑」
+
+判定是打分制,否决规则先于肯定规则求值:问句收尾、把决定权交回用户、明确完成宣告 —— 一律不续跑。冒号只是加权项(说明性文字大量以冒号收尾)。规则表与 ZCode / pi / dsh 完全同源,`tests/test-detector-parity.mjs` 会拿同一批文本喂给 JS 与 Python 两份实现,逐字段比对 `verdict` / `score` / `signals` —— 任一边改了规则而另一边没跟上,这个测试就红。
+
+### 一个已知差异
+
+ZCode 的 Stop hook 由宿主保证「只在一轮零工具调用时执行」,所以那边按**每轮**计数。hermes 这边没有可靠的轮次标识(续跑本身会追加一条 user 消息),所以上限按**会话**计:同一会话累计续跑 3 次后不再触发。保守方向是一致的 —— 只能少续,不会多续。
+
+## 六、排障
 
 **401 / 模型不在了** — 端点 token 轮换或上游名册变了,重跑 `sync-hermes-config.mjs`。
 
@@ -155,13 +213,15 @@ no_proxy=127.0.0.1,localhost,::1,0.0.0.0
 
 **思考档位** — hermes 全局 `agent.reasoning_effort` 默认 `ultra`,这些端点会原样转发 OpenAI 的 `reasoning_effort`。上游不认 `ultra` 时把它降到 `high`。不想让任何模型思考就加 `--no-reasoning`。
 
-## 六、测试
+## 七、测试
 
 ```sh
-node hermes-connect-services/tests/test-yaml-patch.mjs
+node tests/test-yaml-patch.mjs          # 托管块插入/替换/卸载、幂等、--only、孤儿标记自愈
+node ../tests/test-detector-parity.mjs  # JS ↔ Python 判定器逐字段对齐
+node tests/test-stall-gate.mjs          # 闸门行为(需要本机装有 hermes)
 ```
 
-覆盖的是最危险的那部分:托管块插入/替换/卸载、幂等性、`--only` 不删邻居、孤儿标记自愈。
+`test-stall-gate.mjs` 直接 import 宿主的 `apply_stop_gates`,让整条闸门链真实跑一遍 —— 不是 mock 一个函数名对得上就算过。
 
 ---
 

package/bin/patch-hermes-stall-gate.mjs

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+/**
+ * patch-hermes-stall-gate.mjs — 给 hermes 补一个「宣布下一步却没动手」的续跑闸门。
+ *
+ * ## 为什么这里必须打补丁，而 ZCode / pi / dsh 不用
+ *
+ * 另外三端各有一处「回合结束后仍可续跑」的官方钩子点：
+ *   ZCode  Stop hook（宿主保证只在一轮零工具调用时触发）
+ *   pi     turn_end 返回 {continue:true, entries:[...]}
+ *   dsh    agent/turn-stopping 里 agent.steer()
+ *
+ * hermes 没有。`hermes_cli/plugins.py` 的 VALID_HOOKS 里没有任何「回合正常结束」事件
+ * （`agent_loop_stopped` 是 /stop 打断，不是收尾）。唯一能续跑的闸门是 `pre_verify`，
+ * 但 `agent/turn_stop_gates.py` 里它的前置条件是 `if _edited and has_hook("pre_verify")`
+ * —— 本轮**写过文件**才触发。而「我先检查配置，再修改这里：」这种收尾往往一个工具都
+ * 没调，或者只读不写，正好落在门控之外。
+ *
+ * 所以只能往宿主的收尾闸门链里加第 5 道。改动面刻意压到最小：
+ *
+ *   agent/turn_stop_gates.py   两个托管块（模块级判定函数 + 一处调用），marker 包围
+ *   agent/stall_detector.py    新增文件，判定逻辑本体（从 shared/stall_detector.py 分发）
+ *
+ * 宿主自带的行一个字节不动，revert 时两条 marker 之间的内容整段删除即可。
+ *
+ * ## 升级会覆盖
+ *
+ * hermes 自更新会重置 hermes-agent/ 下的源码，这两个块会一起消失。表现是「续跑不再
+ * 发生」而不是报错（模块级 import 有 try/except，文件不在时 `_zc_detect_stall` 为 None，
+ * 闸门静默失效）。升级后重跑本脚本即可恢复 —— `--check` 会告诉你当前状态。
+ *
+ * @module patch-hermes-stall-gate
+ */
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(HERE, '..');
+const HOME = process.env.HOME ?? process.env.USERPROFILE ?? '';
+const MARKER = 'zcode-ai-connect stall-guard';
+const START = `# >>> ${MARKER} >>>`;
+const END = `# <<< ${MARKER} <<<`;
+
+const argv = process.argv.slice(2);
+const has = (name) => argv.includes(name);
+const valueOf = (name) => {
+  const i = argv.indexOf(name);
+  return i === -1 ? undefined : argv[i + 1];
+};
+
+const options = {
+  check: has('--check'),
+  revert: has('--revert'),
+  dryRun: has('--dry-run'),
+  verbose: has('--verbose') || has('-v'),
+  home: valueOf('--home') ?? process.env.HERMES_HOME ?? null,
+};
+
+/** hermes 的 home：Windows 是 %LOCALAPPDATA%/hermes，其他地方是 ~/.hermes。 */
+function locateHome() {
+  const candidates = [
+    options.home,
+    process.env.HERMES_HOME,
+    process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, 'hermes') : null,
+    join(HOME, '.hermes'),
+  ].filter(Boolean);
+  return candidates.find((p) => existsSync(join(p, 'config.yaml'))) ?? null;
+}
+
+/** 运行时的源码树。installs/<id>/environments/<id>/workspace 是项目沙箱副本，不是主进程加载的那份。 */
+function locateAgentRoot(home) {
+  const candidates = [
+    join(home, 'hermes-agent'),
+    join(HOME, '.hermes', 'hermes-agent'),
+  ];
+  return candidates.find((p) => existsSync(join(p, 'agent', 'turn_stop_gates.py'))) ?? null;
+}
+
+/** 找 hermes 自带的解释器，用来做语法检查。 */
+function findPython(home) {
+  const candidates = [
+    process.env.HERMES_PYTHON,
+    join(home, 'tools', `python-3.14.9+20261021-win32-x64`, 'python.exe'),
+    'python',
+    'python3',
+  ].filter(Boolean);
+  for (const exe of candidates) {
+    const probe = spawnSync(exe, ['-c', 'print(1)'], { encoding: 'utf8', timeout: 15000 });
+    if (probe.status === 0 && probe.stdout.trim() === '1') return exe;
+  }
+  return null;
+}
+
+const MODULE_BLOCK = (source) => [
+  START,
+  '# 由 hermes-connect-services/bin/patch-hermes-stall-gate.mjs 写入 —— 勿手改。',
+  '#',
+  '# 第 5 道收尾闸：模型只宣布下一步、本轮零工具调用就结束，追加一条 user 提示把本轮续上。',
+  '# 判定逻辑在 agent/stall_detector.py，与 ZCode / pi / dsh 三端同一套规则。',
+  'import hashlib as _zc_hashlib',
+  '',
+  '# 一个会话内最多续跑几次。与三端一致：连续 3 次都唤不醒，再提示也只是复读计划。',
+  '_ZC_STALL_MAX_NUDGES = 3',
+  '',
+  'try:',
+  '    from agent.stall_detector import detect_stall as _zc_detect_stall',
+  'except Exception:  # 升级后 stall_detector.py 可能不在：静默降级，绝不阻断正常结束',
+  '    _zc_detect_stall = None',
+  '',
+  '',
+  'def _zc_stall_guard_enabled() -> bool:',
+  '    env = os.environ.get("HERMES_STALL_GUARD")',
+  '    if env is not None:',
+  '        return env.strip().lower() not in {"0", "false", "off", "no", "disabled"}',
+  '    try:',
+  '        from hermes_cli.config import load_config_readonly',
+  '',
+  '        cfg = (load_config_readonly() or {}).get("agent") or {}',
+  '    except Exception:',
+  '        return True',
+  '    value = cfg.get("stall_guard", True)',
+  '    if isinstance(value, bool):',
+  '        return value',
+  '    return str(value).strip().lower() not in {"0", "false", "off", "no", "disabled"}',
+  '',
+  '',
+  'def _zc_tool_calls_this_turn(messages) -> int:',
+  '    """本轮（最后一条 user 消息之后）发出的 tool_call 总数。',
+  '',
+  '    与 ZCode 侧的 toolCallCount 同义：> 0 就不存在「只说不做」。',
+  '    """',
+  '    start = 0',
+  '    for i in range(len(messages) - 1, -1, -1):',
+  '        msg = messages[i]',
+  '        if isinstance(msg, dict) and msg.get("role") == "user":',
+  '            start = i + 1',
+  '            break',
+  '    total = 0',
+  '    for msg in messages[start:]:',
+  '        if not isinstance(msg, dict):',
+  '            continue',
+  '        calls = msg.get("tool_calls")',
+  '        if isinstance(calls, list):',
+  '            total += len(calls)',
+  '    return total',
+  '',
+  '',
+  'def _zc_stall_guard_nudge(agent, messages, final_response):',
+  '    """命中则返回要回灌的提示，否则 None。',
+  '',
+  '    收尾闸门里抛异常会打断本轮的正常结束，所以整个函数是 fail-open 的。',
+  '    """',
+  '    try:',
+  '        if _zc_detect_stall is None or not _zc_stall_guard_enabled():',
+  '            return None',
+  '        text = final_response if isinstance(final_response, str) else ""',
+  '        if not text.strip():',
+  '            return None',
+  '        digest = _zc_hashlib.sha1(text.encode("utf-8", "ignore")).hexdigest()',
+  '        seen = getattr(agent, "_zc_stall_guard_seen", None)',
+  '        if not isinstance(seen, list):',
+  '            seen = []',
+  '        if digest in seen or len(seen) >= _ZC_STALL_MAX_NUDGES:',
+  '            return None',
+  '        verdict = _zc_detect_stall(text, _zc_tool_calls_this_turn(messages))',
+  '        if not isinstance(verdict, dict) or not verdict.get("stall"):',
+  '            return None',
+  '        agent._zc_stall_guard_seen = seen + [digest]',
+  '        logger.debug(',
+  '            "stall-guard matched (verdict=%s score=%s signals=%s)",',
+  '            verdict.get("verdict"), verdict.get("score"), verdict.get("signals"),',
+  '        )',
+  '        return verdict.get("prompt")',
+  '    except Exception:',
+  '        logger.debug("stall-guard check failed", exc_info=True)',
+  '        return None',
+  END,
+].join('\n');
+
+const CALL_BLOCK = [
+  `    ${START}`,
+  '    # 放在最后一道：前面的闸门（late-LSP / verify-on-stop / pre_verify / kanban）',
+  '    # 已经各自 return 了，走到这里说明没有别的理由继续这一轮。',
+  '    _zc_nudge = _zc_stall_guard_nudge(agent, messages, final_response)',
+  '    if _zc_nudge:',
+  '        final_msg["finish_reason"] = "stall_guard_continue"',
+  '        _append_interim_answer(',
+  '            agent, final_msg, messages, conversation_history, "stall-guard interim flush failed"',
+  '        )',
+  '        logger.debug(',
+  '            "stall-guard nudge issued (%d/%d)",',
+  '            len(getattr(agent, "_zc_stall_guard_seen", []) or []),',
+  '            _ZC_STALL_MAX_NUDGES,',
+  '        )',
+  '        return _continue(_zc_nudge, "_zc_stall_guard_synthetic")',
+  `    ${END}`,
+].join('\n');
+
+/**
+ * 删掉**所有** marker 块。
+ *
+ * 必须按整行删除：调用块是缩进在函数体里的，若只从 `#` 开始切，会留下那 4 个
+ * 空格残行，导致结果变成 `            return StopGateVerdict(`（12 空格）—— 语法
+ * 合法但缩进错误，Python 会把它当缩进块的一部分。所以按行首/行尾切。
+ */
+function stripBlock(text) {
+  let lines = text.split('\n');
+  for (;;) {
+    const s = lines.findIndex((line) => line.includes(START));
+    if (s === -1) break;
+    let e = lines.findIndex((line, i) => i > s && line.includes(END));
+    if (e === -1) break;
+    lines.splice(s, e - s + 1);
+    // 块两侧原本各有一个空行分隔；删完如果两边都是空行，会多出一个。
+    if (lines[s - 1] !== undefined && lines[s] !== undefined
+      && lines[s - 1].trim() === '' && lines[s].trim() === '') {
+      lines.splice(s, 1);
+    }
+  }
+  return lines.join('\n');
+}
+
+/** 锚点必须唯一，否则宁可报错也不猜。 */
+function assertUniqueAnchor(text, anchor, label) {
+  const first = text.indexOf(anchor);
+  if (first === -1) throw new Error(`找不到插入锚点: ${label}`);
+  if (text.indexOf(anchor, first + 1) !== -1) throw new Error(`插入锚点不唯一: ${label}`);
+  return first;
+}
+
+function main() {
+  const home = locateHome();
+  if (!home) {
+    console.error('找不到 hermes home（可设 HERMES_HOME 或用 --home 指定）');
+    process.exit(1);
+  }
+  const agentRoot = locateAgentRoot(home);
+  if (!agentRoot) {
+    console.error(`找不到 ${join(home, 'hermes-agent')}/agent/turn_stop_gates.py`);
+    process.exit(1);
+  }
+
+  const gatePath = join(agentRoot, 'agent', 'turn_stop_gates.py');
+  const detectorPath = join(agentRoot, 'agent', 'stall_detector.py');
+  const sourceDetector = join(PKG_ROOT, 'lib', 'stall_detector.py');
+
+  if (!existsSync(sourceDetector)) {
+    console.error(`包里缺 lib/stall_detector.py —— 先在仓库根跑 node scripts/sync-stall-guard.mjs`);
+    process.exit(1);
+  }
+
+  let gate = readFileSync(gatePath, 'utf8');
+  const patched = gate.includes(START);
+  const detectorPresent = existsSync(detectorPath);
+
+  if (options.check) {
+    console.log(`home:       ${home}`);
+    console.log(`gate file:  ${gatePath}`);
+    console.log(`patched:    ${patched ? 'yes' : 'no'}`);
+    console.log(`detector:   ${detectorPresent ? 'yes' : 'no'}`);
+    if (patched && detectorPresent) {
+      const same = readFileSync(detectorPath, 'utf8') === readFileSync(sourceDetector, 'utf8');
+      console.log(`detector in sync: ${same ? 'yes' : 'NO (重跑本脚本)'}`);
+      if (!same) process.exit(2);
+    } else {
+      process.exit(2);
+    }
+    return;
+  }
+
+  if (options.revert) {
+    if (!patched && !detectorPresent) {
+      console.log('没有需要撤销的改动');
+      return;
+    }
+    if (options.dryRun) {
+      console.log(`--dry-run: 会移除 ${gatePath} 的托管块${detectorPresent ? ' 与 stall_detector.py' : ''}`);
+      return;
+    }
+    const bakPath = `${gatePath}.bak-zcode-stall-guard`;
+    // 首次打补丁时留下的原始快照优先 —— 它比"按 marker 反删"更能保证零字节还原。
+    const bakIsPristine = existsSync(bakPath) && !readFileSync(bakPath, 'utf8').includes(START);
+    if (bakIsPristine) {
+      copyFileSync(bakPath, gatePath);
+      console.log(`  从原始快照恢复 ${bakPath}`);
+    } else {
+      writeFileSync(gatePath, stripBlock(gate), 'utf8');
+    }
+    if (detectorPresent) {
+      const current = readFileSync(detectorPath, 'utf8');
+      if (current === readFileSync(sourceDetector, 'utf8')) {
+        unlinkSync(detectorPath);
+      } else {
+        console.log(`stall_detector.py 已被改动过，保留不删: ${detectorPath}`);
+      }
+    }
+    console.log(`已撤销${bakIsPristine ? '' : `（备份: ${bakPath}）`}`);
+    return;
+  }
+
+  // ── 应用补丁（幂等：先清旧块再按锚点插新块） ─────────────────────────────
+  gate = stripBlock(gate);
+
+  const moduleAnchor = '\ndef _verify_on_stop_nudge(agent) -> Optional[str]:';
+  const callAnchor = '\n    return StopGateVerdict(\n        continue_turn=False, final_response=final_response,';
+
+  const moduleAt = assertUniqueAnchor(gate, moduleAnchor, 'def _verify_on_stop_nudge');
+  gate = `${gate.slice(0, moduleAt)}\n${MODULE_BLOCK()}\n${gate.slice(moduleAt)}`;
+
+  const callAt = assertUniqueAnchor(gate, callAnchor, 'return StopGateVerdict(continue_turn=False');
+  gate = `${gate.slice(0, callAt)}\n${CALL_BLOCK}\n${gate.slice(callAt)}`;
+
+  if (options.dryRun) {
+    console.log(`--dry-run: 会给 ${gatePath} 插入 ${START} / ${END} 两块`);
+    if (options.verbose) console.log(MODULE_BLOCK().split('\n').slice(0, 4).join('\n'));
+    return;
+  }
+
+  // 只有在文件还是原样时才留快照。重打补丁时覆盖快照，会让 --revert 失去干净的回退点。
+  if (!patched) copyFileSync(gatePath, `${gatePath}.bak-zcode-stall-guard`);
+  writeFileSync(gatePath, gate, 'utf8');
+  mkdirSync(dirname(detectorPath), { recursive: true });
+  writeFileSync(detectorPath, readFileSync(sourceDetector, 'utf8'), 'utf8');
+
+  // ── 语法检查：补丁后宿主必须仍然可 import ─────────────────────────────────
+  const python = findPython(home);
+  if (python) {
+    const check = spawnSync(python, ['-m', 'py_compile', gatePath, detectorPath], {
+      encoding: 'utf8', timeout: 60000, cwd: agentRoot,
+    });
+    if (check.status !== 0) {
+      copyFileSync(`${gatePath}.bak-zcode-stall-guard`, gatePath);
+      console.error('语法检查失败，已回滚:');
+      console.error((check.stderr || check.stdout || '').slice(0, 1200));
+      process.exit(1);
+    }
+    console.log(`  syntax ok (${python})`);
+  } else {
+    console.log('  (没找到 python，跳过语法检查)');
+  }
+
+  console.log(`  patched ${gatePath}`);
+  console.log(`  wrote   ${detectorPath}`);
+  console.log('');
+  console.log('生效需要重启 hermes gateway —— 已 import 的模块不会自动重载。');
+}
+
+main();

package/lib/stall_detector.py

@@ -0,0 +1,301 @@
+"""stall_detector —— 「宣布了下一步却没调用工具」的启发式判定（Python 版）。
+
+与 ``shared/stall-detector.mjs`` 逐条对齐，供 hermes 的回合结束闸门使用。
+**两份实现必须同步**：改任意一份都要跑 ``node tests/test-detector-parity.mjs``，
+它会把同一批用例喂给两边的实现并逐字段比对（verdict / score / signals）。
+
+设计约束与 JS 版一致：
+
+ 1. 这是启发式，不是判定器。宁可漏掉一次续跑，也不要打断一条正常收尾的回复。
+ 2. 否决（veto）规则先于肯定（cue）规则求值。
+ 3. 冒号只是加权项，不足以独立触发。
+ 4. 零依赖、纯函数、无 IO —— 会被复制进宿主包，不能 import 本项目其他模块。
+
+与 JS 版的唯一刻意差异：返回值是 dict 而不是对象字面量。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict
+
+__all__ = ["detect_stall", "CONTINUE_PROMPT"]
+
+# 上限：只看最后两块 + 最多 600 字符。更早的内容是背景，不是收尾意图。
+TAIL_BLOCK_COUNT = 2
+TAIL_CHAR_LIMIT = 600
+
+# 低于这个（加权）长度的回复不判 —— 「好的。」「Done.」没有可续跑的动作。
+# 中日韩文字按 1.6 字计权：同样表达一个完整动作，中文比英文短得多。
+MIN_WEIGHTED_CHARS = 14.0
+
+# 请求用户裁决 / 提供输入的措辞。命中即否决。
+REQUEST_PATTERNS = [
+    # 中文：把决定权交回用户
+    r"请你?(?:确认|批准|授权|选择|决定|提供|粘贴|发送|告知|告诉|现在|立刻|马上|配合|扫码|扫|在)",
+    r"你(?:可以|需要|来)(?:确认|决定|选择|提供|先)",
+    r"需要你(?:确认|决定|操作|提供|回复|选择)",
+    r"(?:是否|要不要|需不需要|要不要我|需要我)(?:继续|执行|我|帮|先|再)?",
+    r"等你(?:确认|回复|决定|操作|安排)",
+    r"告诉我(?:你|是否|要|结果|选择|一声|什么时候)",
+    r"(?:说|吱|喊)一声",
+    r"你(?:点个?头|说[「“\"']?开[」”\"']?)(?:我就|我立刻|我马上)?",
+    r"要我[^。！？\n]{0,24}(?:就|的话|吗)",
+    r"扫完(?:不用回复|告诉我|说一声)",
+    r"让我知道",
+    r"由你(?:决定|来|选|定)",
+    r"你(?:先|来)(?:确认|决定|操作|选|说)",
+    r"确认后(?:我)?再",
+    r"(?:你|您)看(?:看|一下)?(?:是否|要不要|行不行)",
+    # English: handing the decision back
+    r"\blet me know\b",
+    r"\bwould you like\b",
+    r"\bdo you want\b",
+    r"\bshall i\b",
+    r"\bplease (?:confirm|advise|provide|choose)\b",
+    r"\byour call\b",
+    r"\bwhich (?:one|option|approach) (?:do you|would you)\b",
+    r"\bcan you (?:confirm|provide|share|tell)\b",
+    r"\bwaiting (?:for|on) your\b",
+]
+
+# 确认/复述长期规则或未来条件约定（「以后遇到…我会先…」「可以，主人。以后…」）。
+# 这是回答用户的规则设定，不是当前回合宣布下一步动作后漏调工具。
+STANDING_RULE_PATTERNS = [
+    r"(?:以后|今后|之后|下次|后续|往后|接下来每次|每当|每次)[^。！？\n]{0,40}(?:提到|遇到|收到|让我|你让我|要求|需要|开始|做|时|的时候)[^。！？\n]{0,30}我(?:会|将|都会|先|就)",
+    r"^(?:可以|好的?|明白|没问题|收到|记下了|知道了)[，,。！!\s]*(?:主人|小主|老板)?[，,。！!\s]*(?:以后|今后|之后|下次|后续|往后|每当|每次)",
+]
+
+# 「已经做完」的收尾。命中且无未来标记时否决。
+DONE_PATTERNS = [
+    r"(?:已|已经)(?:经)?(?:完成|修好|改好|搞定|处理完|就绪|生效|上线|发布|通过)",
+    r"(?:全部|都)(?:完成|通过|搞定|就绪|闭合)",
+    r"(?:搞定|收工|完事|可以收尾)(?:了)?[。.!！]?$",
+    r"(?:到|就)这里(?:为止|结束)?",
+    r"(?:没有|无需)(?:其他|更多|别的)(?:改动|问题|需要)",
+    r"\b(?:all )?done\b",
+    r"\b(?:finished|completed|ready to go)\b",
+    r"\bnothing (?:else|more) (?:to do|needed)\b",
+    r"\ball (?:tests? )?pass(?:ed|ing)?\b",
+]
+
+# 强未来标记：明确宣布「我即将做」。单独出现即高置信。
+FUTURE_STRONG = [
+    # 「我先…」「我这就…」是中文里最典型的「宣布即将动手」，不必再跟动词。
+    r"我(?:先|这就|马上|立刻|接下来|现在)",
+    r"我(?:来|将|会|要|去)(?:先|先来)?",
+    r"先让我",
+    r"让(?:我们|我)先",
+    r"(?:接下来|下面|现在)我(?:来|将|会|要)",
+    r"开始(?:执行|处理|修改|实现|写|改|跑|检查)",
+    r"(?:^|[。！？\n]\s*)(?:开始[。，,\s]*)?先(?:把|将|从|去|给|对|用|跑|看|查|改|写|读|登记|核对|整理|创建|执行|检查)[^。！？\n]{1,60}再",
+    r"(?:^|[。！？\n]\s*)现在(?:重新|开始|把|将|先|去|来|给|对|跑|开|改|写|整理|执行|检查)",
+    r"\blet me\b",
+    r"\bi'?ll\b",
+    r"\bi will\b",
+    r"\bi'?m going to\b",
+    r"\bnow i'?ll\b",
+    r"\blet'?s\b",
+]
+
+# 弱未来标记：推进语，但单独不足以说明「要动手」—— 也可能是继续讲解。
+FUTURE_WEAK = [
+    r"接下来",
+    r"下一步",
+    r"下面(?:我|我们)?",
+    r"然后(?:我|我们)?",
+    r"首先",
+    r"现在(?:我|我们)?",
+    r"\bnext,?\b",
+]
+
+# 动作动词：把「未来时」落到「要做一件具体的事」上。
+ACTION_VERB = [
+    r"(?:检查|查看|看看|查一下|读取|打开|搜索|定位|核对|登记|整理)",
+    r"(?:修改|改成|改掉|编辑|写入|创建|新建|删除|移除|重写|写进)",
+    r"(?:执行|运行|跑一下|跑起|启动|重启|安装|部署|发布|提交|开窗口|重新开)",
+    r"(?:修复|实现|添加|增加|补充|更新|替换|迁移|重构)",
+    r"(?:验证|测试|校验|确认一下|跑通|编译|上机)",
+    r"\b(?:check|read|open|inspect|look at|search|grep)\b",
+    r"\b(?:edit|write|create|add|remove|delete|rewrite|patch|update)\b",
+    r"\b(?:run|execute|install|deploy|build|start|restart|publish)\b",
+    r"\b(?:fix|implement|refactor|migrate|verify|test)\b",
+]
+
+# 尾部形态加权。冒号不足以独立触发。
+COLON_TAIL = re.compile(r"[:：]\s*\Z")
+ELLIPSIS_TAIL = re.compile(r"(?:\.{3,}|…)\s*\Z")
+QUESTION_TAIL = re.compile(r"[?？]\s*\Z")
+
+# action-colon 判定用：末行收尾的冒号、分句切分、列表项前缀。
+_COLON_AT_END = re.compile(r"[:：]\s*\Z")
+_CLAUSE_SPLIT = re.compile(r"[，,。；;！!？?]")
+_LIST_ITEM = re.compile(r"^[-*•\d|]")
+
+# 阈值。只有弱未来标记时必须靠额外信号才能过线。
+THRESHOLD_STRONG = 3.0
+THRESHOLD_WEAK_ONLY = 4.5
+
+_CJK_CHAR = re.compile(r"[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]")
+
+_COMPILED: Dict[str, list] = {}
+
+
+def _compile(group: str, patterns: list) -> list:
+    """每个模式组只编译一次，且大小写不敏感（与 JS 版逐条带 ``i`` 等价）。
+
+    注意：JS 版里只有英文模式带 ``i``，中文模式没有。这里统一用 IGNORECASE
+    是安全的 —— 中文模式不含字母，加不加都一样。
+    """
+    if group not in _COMPILED:
+        _COMPILED[group] = [re.compile(p, re.IGNORECASE) for p in patterns]
+    return _COMPILED[group]
+
+
+def _any_match(group: str, text: str) -> bool:
+    return any(rx.search(text) for rx in _compile(group, _PATTERN_GROUPS[group]))
+
+
+_PATTERN_GROUPS = {
+    "request": REQUEST_PATTERNS,
+    "standing_rule": STANDING_RULE_PATTERNS,
+    "done": DONE_PATTERNS,
+    "future_strong": FUTURE_STRONG,
+    "future_weak": FUTURE_WEAK,
+    "action_verb": ACTION_VERB,
+}
+
+
+def _strip_noise(text: str) -> str:
+    """去掉代码围栏/行内代码/标签 —— 代码里的冒号和动词不是模型的收尾意图。"""
+    text = re.sub(r"```[\s\S]*?```", " ", text)
+    text = re.sub(r"`[^`\n]*`", " ", text)
+    text = re.sub(r"</?[a-zA-Z][^>]{0,200}>", " ", text)
+    text = re.sub(r"\[[^\]]{0,80}\]\([^)]{0,300}\)", " ", text)
+    text = re.sub(r"[ \t]+", " ", text)
+    return text.strip()
+
+
+def _tail_of(text: str) -> str:
+    """最后两块非空段落，按字符上限截尾。"""
+    blocks = [b.strip() for b in re.split(r"\n{2,}", text) if b.strip()]
+    if not blocks:
+        return ""
+    joined = "\n".join(blocks[-TAIL_BLOCK_COUNT:]).strip()
+    return joined[-TAIL_CHAR_LIMIT:] if len(joined) > TAIL_CHAR_LIMIT else joined
+
+
+def _weighted_length(text: str) -> float:
+    """中日韩字符按 1.6 计权后的长度，见 MIN_WEIGHTED_CHARS。"""
+    return sum(1.6 if _CJK_CHAR.match(ch) else 1.0 for ch in text)
+
+
+def _result(verdict: str, score: float = 0.0, signals=None, stall: bool = False) -> Dict[str, Any]:
+    return {
+        "stall": stall,
+        "verdict": verdict,
+        "score": score,
+        "signals": list(signals or []),
+        "prompt": CONTINUE_PROMPT if stall else None,
+    }
+
+
+def detect_stall(raw_text: Any, tool_call_count: int = 0) -> Dict[str, Any]:
+    """判定一条 assistant 收尾文本是否「宣布了下一步却没动手」。
+
+    ``tool_call_count > 0`` 一律不判 —— 已经有工具调用的轮次不存在「只说不做」。
+    """
+    if tool_call_count > 0:
+        return _result("had-tools")
+
+    raw = "" if raw_text is None else str(raw_text).strip()
+    if raw == "":
+        return _result("empty")
+
+    text = _strip_noise(raw)
+    if _weighted_length(text) < MIN_WEIGHTED_CHARS:
+        return _result("too-short")
+
+    tail = _tail_of(text)
+
+    # ── 否决 ①：以问句收尾 ────────────────────────────────────────────────
+    if QUESTION_TAIL.search(raw):
+        return _result("question")
+
+    # ── 否决 ②：把决定权交回用户 ──────────────────────────────────────────
+    if _any_match("request", tail):
+        return _result("asked-user")
+
+    # ── 否决 ③：确认/复述长期规则约定（「以后遇到…我会先…」）──────────────
+    if _any_match("standing_rule", tail):
+        return _result("standing-rule")
+
+    has_strong = _any_match("future_strong", tail)
+    has_weak = _any_match("future_weak", tail)
+
+    # ── 否决 ④：明确宣告完成且没有未来时 ──────────────────────────────────
+    if not has_strong and not has_weak and _any_match("done", tail):
+        return _result("already-done")
+
+    # ── 打分 ──────────────────────────────────────────────────────────────
+    score = 0.0
+    signals = []
+
+    if has_strong:
+        score += 2.0
+        signals.append("future-strong")
+    if has_weak:
+        score += 1.5
+        signals.append("future-weak")
+    has_verb = _any_match("action_verb", tail)
+    if has_verb:
+        score += 1.0
+        signals.append("action-verb")
+    has_colon = bool(COLON_TAIL.search(raw))
+    if has_colon:
+        score += 1.5
+        signals.append("colon-tail")
+    if ELLIPSIS_TAIL.search(raw):
+        score += 0.5
+        signals.append("ellipsis-tail")
+
+    # 末行非列表项以「动作动词 + 冒号」收尾（例如「……整份重写干净：」）：
+    # 即使省略了显式「我先/接下来」代词，也是典型的即将发起工具调用。
+    #
+    # 动词必须落在冒号前的**最后一个分句**里，否则「已定位问题并修好，根因有
+    # 三层：」这类说明性收尾会被误判 —— 它的动词讲的是已完成的事，冒号引出的
+    # 是名词性解释。宁可漏掉一次续跑，也不要把说明性收尾当成漏执行。
+    lines = [line.strip() for line in raw.split("\n") if line.strip()]
+    last_line = lines[-1] if lines else ""
+    tail_clause = _CLAUSE_SPLIT.split(_COLON_AT_END.sub("", last_line))[-1] if last_line else ""
+    is_action_colon = (
+        has_colon
+        and has_verb
+        and _any_match("action_verb", tail_clause)
+        and not _LIST_ITEM.match(last_line)
+        and len(last_line) <= 160
+    )
+    if not has_strong and not has_weak and is_action_colon:
+        score += 1.0
+        signals.append("action-colon")
+
+    if not has_strong and not has_weak and not is_action_colon:
+        return _result("no-future-cue", score, signals)
+
+    threshold = THRESHOLD_STRONG if (has_strong or is_action_colon) else THRESHOLD_WEAK_ONLY
+    if score < threshold:
+        return _result("weak-only", score, signals)
+
+    return _result("stall", score, signals, stall=True)
+
+
+# 回灌给模型的续跑提示。
+#
+# 刻意不命令「继续」，而是给出三个出口：执行 / 说明为何不需要执行 / 提出具体问题。
+# 只写「继续」会让模型重复一遍刚才那段计划。
+CONTINUE_PROMPT = "\n".join([
+    "你上一条回复宣布了下一步操作（例如「我先…」「接下来…」「Let me…」），但没有调用任何工具就结束了这一轮。",
+    "请直接执行这个操作。",
+    "如果它其实已经完成，或不需要执行，用一句话说明结论即可，不要重述计划。",
+    "如果需要用户先决定，提出一个具体的问题，不要继续描述待办。",
+])

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hermes-connect-services",
-  "version": "1.1.0",
-  "description": "Bring zcode-ai-connect's four loopback endpoints to hermes: lazy-start them on session start and sync them into hermes' config.yaml as OpenAI-compatible providers.",
+  "version": "1.3.0",
+  "description": "Bring zcode-ai-connect's four loopback endpoints to hermes, and add the missing turn-end gate that re-runs a turn when the model announces a next step but calls no tool.",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -23,13 +23,15 @@
   "files": [
     "bin",
     "src",
+    "lib",
     "tests",
     "README.md",
     "LICENSE"
   ],
   "bin": {
     "hermes-connect-ensure": "bin/ensure-services.mjs",
-    "hermes-connect-sync": "bin/sync-hermes-config.mjs"
+    "hermes-connect-sync": "bin/sync-hermes-config.mjs",
+    "hermes-connect-stall-gate": "bin/patch-hermes-stall-gate.mjs"
   },
   "dependencies": {},
   "keywords": [
@@ -39,6 +41,8 @@
     "trae",
     "workbuddy",
     "qoder",
-    "qwenwork"
+    "qwenwork",
+    "stall-guard",
+    "hook"
   ]
 }

package/tests/probe_stall_gate.py

@@ -0,0 +1,73 @@
+"""给 tests/test-stall-gate.mjs 调用的探针：在宿主进程里跑真实闸门链。
+
+输出 JSON 行，一行一个用例，便于 Node 侧断言。找不到 hermes 时由调用方 SKIP，
+这里不做探测。
+"""
+import json
+import sys
+
+agent_root = sys.argv[1]
+sys.path.insert(0, agent_root)
+
+from agent.turn_stop_gates import _ZC_STALL_MAX_NUDGES, apply_stop_gates  # noqa: E402
+
+
+class FakeAgent:
+    def __init__(self):
+        self._session_messages = []
+        self._turn_file_mutation_paths = set()
+        self.platform = "cli"
+        self.session_id = "stall-gate-test"
+        self.model = "test/model"
+
+    def _interim_content_was_streamed(self, text):
+        return True
+
+    def _emit_interim_assistant_message(self, msg):
+        pass
+
+    def _flush_messages_to_session_db(self, messages, history):
+        pass
+
+    def _emit_diagnostic_status(self, text):
+        pass
+
+
+def run(text, tools=0):
+    agent = FakeAgent()
+    messages = [{"role": "user", "content": "帮我看看那个配置文件"}]
+    for i in range(tools):
+        messages.append({
+            "role": "assistant", "content": "",
+            "tool_calls": [{"id": f"c{i}", "type": "function",
+                            "function": {"name": "read_file", "arguments": "{}"}}],
+        })
+        messages.append({"role": "tool", "content": "ok", "tool_call_id": f"c{i}"})
+    verdict = apply_stop_gates(
+        agent, {"role": "assistant", "content": text},
+        final_response=text, messages=messages, conversation_history=[],
+        pending_verification_response=None, pending_verification_response_previewed=False,
+    )
+    return {
+        "continue_turn": bool(verdict.continue_turn),
+        "nudge_role": messages[-1].get("role") if isinstance(messages[-1], dict) else None,
+        "nudge": messages[-1].get("content") if verdict.continue_turn else None,
+        "fallback": verdict.pending_verification_response,
+    }
+
+
+CASES = [
+    {"name": "announce+colon", "text": "我先检查配置，再修改这里：", "tools": 0, "expect": True},
+    {"name": "done", "text": "已完成全部修改，测试通过。", "tools": 0, "expect": False},
+    {"name": "question", "text": "需要我先确认一下端口状态吗？", "tools": 0, "expect": False},
+    {"name": "handed-back", "text": "接下来需要你决定用哪个方案，我再动手。", "tools": 0, "expect": False},
+    {"name": "had-tools", "text": "我先检查配置，再修改这里：", "tools": 2, "expect": False},
+    {"name": "english", "text": "Let me check the config first, then patch the providers block:", "tools": 0, "expect": True},
+]
+
+print(json.dumps({"max_nudges": _ZC_STALL_MAX_NUDGES}))
+for case in CASES:
+    result = run(case["text"], case["tools"])
+    result["name"] = case["name"]
+    result["expect"] = case["expect"]
+    print(json.dumps(result, ensure_ascii=False))

package/tests/test-stall-gate.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * hermes 侧续跑闸门的回归测试。
+ *
+ * 直接 import 宿主的 `apply_stop_gates`,让**整条闸门链**真实跑一遍 —— late-LSP /
+ * verify-on-stop / pre_verify / kanban 四道闸都会执行,只是触发条件不成立。这比
+ * mock 一个函数名对得上要有说服力:它证明我们的闸门插在了正确的位置,而且返回值
+ * 形状能让 turn loop 接受。
+ *
+ * 本机没装 hermes 时 SKIP(不判失败),这样 CI 上也能通过。
+ *
+ * Run: node hermes-connect-services/tests/test-stall-gate.mjs
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const HOME_DIR = process.env.HOME ?? process.env.USERPROFILE ?? '';
+
+console.log('test-stall-gate (hermes)');
+
+function locateAgentRoot() {
+  const homes = [
+    process.env.HERMES_HOME,
+    process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, 'hermes') : null,
+    join(HOME_DIR, '.hermes'),
+  ].filter(Boolean);
+  for (const home of homes) {
+    const root = join(home, 'hermes-agent');
+    if (existsSync(join(root, 'agent', 'turn_stop_gates.py'))) return { home, root };
+  }
+  return null;
+}
+
+function findPython(home) {
+  const candidates = [
+    process.env.HERMES_PYTHON,
+    join(home, 'tools', 'python-3.14.9+20261021-win32-x64', 'python.exe'),
+    'python',
+    'python3',
+  ].filter(Boolean);
+  for (const exe of candidates) {
+    const probe = spawnSync(exe, ['-c', 'print(1)'], { encoding: 'utf8', timeout: 15000 });
+    if (probe.status === 0 && probe.stdout.trim() === '1') return exe;
+  }
+  return null;
+}
+
+const located = locateAgentRoot();
+if (!located) {
+  console.log('  SKIP 本机没有 hermes（找过 HERMES_HOME / LOCALAPPDATA / ~/.hermes）');
+  process.exit(0);
+}
+
+const gatePath = join(located.root, 'agent', 'turn_stop_gates.py');
+const patched = existsSync(gatePath)
+  && spawnSync(process.execPath, ['-e', `process.exit(require('fs').readFileSync(${JSON.stringify(gatePath)},'utf8').includes('zcode-ai-connect stall-guard')?0:1)`]).status === 0;
+if (!patched) {
+  console.log('  SKIP 补丁未打（先跑 bin/patch-hermes-stall-gate.mjs）');
+  process.exit(0);
+}
+
+const python = findPython(located.home);
+if (!python) {
+  console.log('  SKIP 找不到 Python 解释器');
+  process.exit(0);
+}
+
+const probe = spawnSync(python, [join(HERE, 'probe_stall_gate.py'), located.root], {
+  encoding: 'utf8', timeout: 60000, cwd: located.root,
+});
+if (probe.status !== 0) {
+  console.log(`  FAIL 探针执行失败（status=${probe.status}）`);
+  console.log((probe.stderr || probe.stdout || '').slice(0, 1500));
+  process.exit(1);
+}
+
+const lines = probe.stdout.split('\n').map((l) => l.trim()).filter(Boolean);
+let passed = 0;
+let failed = 0;
+
+const meta = JSON.parse(lines[0]);
+console.log(`  max nudges = ${meta.max_nudges}`);
+
+for (const line of lines.slice(1)) {
+  const r = JSON.parse(line);
+  const ok = r.continue_turn === r.expect;
+  if (ok) {
+    passed += 1;
+    const extra = r.continue_turn ? ` nudge→${r.nudge_role} fallback=${r.fallback ? 'kept' : 'LOST'}` : '';
+    console.log(`  ok   ${r.name} → continue_turn=${r.continue_turn}${extra}`);
+    // 续跑时必须把候选答案留作 fallback,否则预算耗尽时用户什么都看不到
+    if (r.continue_turn && !r.fallback) {
+      failed += 1;
+      passed -= 1;
+      console.log(`       FAIL ${r.name}: pending_verification_response 丢了`);
+    }
+  } else {
+    failed += 1;
+    console.log(`  FAIL ${r.name} → continue_turn=${r.continue_turn} (expect ${r.expect})`);
+  }
+}
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);