Skip to content

治好 Antigravity CLI 深思考模型“闷头调工具零开口”:Prompt 先验 + 轻量 PreInvocation 防静默双层方案 ​

本文档介绍一套面向 Antigravity CLI(agy)的极简双层防静默方案(~/.gemini/config/GEMINI.md + ~/.gemini/config/hooks/silent_turn_nudge.py),专门用于解决深度推理模型(尤其是 Hydrogen XHigh 等高思考预算档位)在连续工具调用期间长期“零正文输出、闷头干活”导致交互像卡死一样的体验痛点。

整套方案零外部依赖,核心 Hook 脚本仅 187 行纯标准库 Python,在 23.43 MB / 10,385 步超长日志上纯判定耗时 0.10 ms,跨 /compact 与 压缩后无损回水方案 天然零残留;经 45 个真实会话、296 次生产级触发 验证,次轮立即开口唤醒率达 94.9%,其中 89.0% 做到了开口同时继续调用工具(零额外废回合)。


1. 背景与单一变量实测:为什么模型越“会想”,体感反而越像“卡死”? ​

在终端 Agent 场景下,高思考预算模型(如 Hydrogen XHigh)能连续规划几十步排查、编译和 UI 测试,但伴随出现一个非常影响日常协作的现象:终端长时间停留在转圈状态,界面上没有任何中文进展说明,用户根本分不清它是在正常跑编译/测试,还是已经陷入死循环或卡死。

为了确认这是不是偶然波动,我们在一条真实运行的 6,400+ 步长对话 中保持上下文、项目与全局规范完全一致,做了一次单一变量模型热切对照:

对照分组(同一 6,400+ 步长对话)模型档位观测范围边调工具边汇报占比最长连续静默表现
基线组Carbon High66 次模型回复28.8%常规间隔即会输出阶段进展
热切对照组Hydrogen XHighUI 测试与编译长链0.0%连续 74 步、20 次工具调用全程 0 开口,直到全部跑完才一口气吐出最终总结

将这条主会话继续追踪至 10,385 步 后,我们在上线防静默 Hook 前的 Hydrogen XHigh 完整窗口(steps 6345..6688)中观测到更极端的黑盒静默:99 次模型回复里边调工具边开口仅有 4 次(4.0%,仅占工具轮次的 4.7%),最长一段连续静默达到 37 轮工具调用(累计 102 次工具、跨越 138 步、持续 538 秒 / 近 9 分钟全程零文字输出)。


2. 根因拆解:为什么单靠写一句“请汇报进度”救不了深思考模型? ​

单纯在系统提示词里写“请多汇报进度”,在深思考模型上往往很快失效,甚至引入副作用。拆解日志后可以看到三个底层原因:

  1. 双通道可见性错觉(Internal Thinking ≠ User-Visible Output) 深度推理模型在调用工具前,通常会先在隐藏的 thinking 通道里写下几百字的排查思路、假设与下一步计划。在模型自己的认知视角里,它“已经把计划交代得很清楚了”,于是正文 content 留空、直接发出 tool_calls。但终端用户默认看不到内部思考和原始工具输出,只能看到 PLANNER_RESPONSE.content,导致**“模型以为自己说了,用户以为它哑了”**。
  2. 长工具链下的指令注意力衰减(Recency Decay) 全局提示词位于上下文最顶部。一旦进入连续十几轮高密度的 tool_call ↔ tool_result 闭环,每一轮大量的思考 Token 与工具输出都会不断稀释顶部风格规范的注意力权重——这正是同上下文下 Hydrogen XHigh 工具轮次开口率跌至 4.7% 的直接原因。
  3. 朴素催促带来的两种反作用陷阱
    • 陷阱 A(过度刷屏):不区分任务复杂度,导致查个 1~2 步的简单命令也先写一段开场白,拉低信息密度;
    • 陷阱 B(“只说不做”断流):模型为了响应催促,单独输出一句“接下来我去查配置文件”却不附带任何 tool_calls,直接提前结束当前 Agent 循环,反逼用户手动再敲一次“继续”。

3. 两层极简架构:Prompt 管开场分流,Hook 做兜底熔断 ​

基于上述根因,我们把“开口时机”和“长链保活”拆成正交的两层——不叠加冗长规则,也不引入任何外部 LLM 调用:

双层防静默与可见性架构

3.1 第一层:全局提示词先验(~/.gemini/config/GEMINI.md) ​

第一层负责第 1 轮开场和简单/复杂任务分流,零运行时延迟。核心只有三点精准措辞:

  1. 直接戳破双通道盲区:开篇第一句写明*“用户看不到你的内部思考或原始工具结果,只能看到你输出的文本”*,把“在 thinking 里想过”与“对用户可见”彻底拆开;
  2. 明确 1~2 步静默边界:简单问答或 1~2 步即可结束的只读查询保持静默直答,避免高频刷屏;
  3. 锁死同回合开场 + 禁只说不做:要求多步排查、修改或执行耗时命令时,“第一批工具调用同回合必须先附带 1 句中文开场说明准备查/做什么(勿只说不做或空正文闷头连跑)”,同时要求后续关键节点用 1~2 句中文简报已确认事实与下一步。

3.2 第二层:无状态 PreInvocation 防静默轻推(silent_turn_nudge.py) ​

当深思考模型在长链中发生注意力衰减、忘记第一层规范时,第二层 PreInvocation Hook 会以极低成本介入兜底。整套状态机完全无状态(不写任何外部 sidecar 状态文件,transcript.jsonl 本身就是唯一真相源):

silent_turn_nudge.py 倒扫与双阈值状态机

脚本内的 5 个关键工程细节:

  1. 首轮零开销短路(invocationNum <= 1):每轮用户提问后的第 1 次推理直接跳过返回 {},既不抢第一层提示词的活,也不干扰单轮简单问答。
  2. 常数级 I/O 尾扫紧凑日志(TAIL_READ_BYTES = 262_144):刻意读取紧凑版 transcript.jsonl(长工具输出已截断)而非动辄几十 MB 的 transcript_full.jsonl,无论会话跑了 10 步还是 10,385 步,都只 seek 末尾 256 KiB 并丢弃可能被拦腰切开的首行半截 JSON,随后倒序扫描直到命中以下任一清零锚点:
    • USER_INPUT(用户发起了新一轮对话);
    • PLANNER_RESPONSE 且 content.strip() 非空(模型刚刚向用户开过口);
    • CHECKPOINT(刚刚发生过上下文压缩)。
  3. 双阈值 OR 触发(同时拦住“高频连扫”与“单步慢命令”):
    • 轮次阈值:连续空正文调工具 silent_turns >= 5(默认 AGY_SILENT_NUDGE_TURNS=5),防止高频连读十几个文件不吭声;
    • 时长阈值:静默调工具 silent_turns >= 1 且距锚点(用户发言/上次开口/压缩点)已满 60 秒(默认 AGY_SILENT_NUDGE_SECONDS=60),防止单条耗时编译或 UI 测试跑了一两分钟回来后继续哑着往下跑。
  4. 单段封顶 1 次 + 防断流精准文案:
    • 倒扫期间同步计数当前静默段内已出现的 MARKER = "[进度轻推]",达到 AGY_SILENT_NUDGE_MAX=1 立即 break 并返回 {},绝不在同一段静默里反复轰炸上下文;
    • 注入正文严格压缩至 46 字(122 字节,约 30 tokens),且末尾显式防“只说不做”:

      [进度轻推] 已连续多步静默调用工具,下一回合请先随工具调用输出 1 句中文进展,勿只回文字不调工具。

  5. 与 /compact 无损回水方案天然正交、跨压缩零残留:
    • 本脚本倒扫遇到 CHECKPOINT 自动归零;
    • 配套的 rehydrate_after_compact.py 在重建历史时只采集 USER_INPUT 与 PLANNER_RESPONSE,不收集任何 SYSTEM_MESSAGE。因此压缩一旦发生,所有历史 [进度轻推] 都会被彻底清理出上下文,不会跨压缩周期滚雪球累积。

4. 真机生产验收数据(10,385 步前后消融 + 45 会话 / 296 次触发统计) ​

将两层方案同步部署到主力开发机后,我们对真实生产会话日志进行了全量离线回溯统计(无人工挑样本)。

4.1 同一超长会话(10,385 步)上线前后对比 ​

在同一条主会话的连续时间线上(step 6689 首次启用防静默 Hook),对比同一模型在上线前后的行为变化:

观测阶段(同一 10,385 步主会话)模型档位回复总数边调工具边开口(占全部回复 / 占工具轮次)>=10 轮静默次数最长连续静默(轮数 / 工具数 / 时长)
上线前(steps 6345..6688)Hydrogen XHigh994(4.0% / 4.7%)137 轮 / 102 工具 / 538 s
上线后(steps 6689..7152)Hydrogen XHigh12540(32.0% / 38.5%,8.0×)06 轮 / 20 工具 / 75 s
上线前(steps 5406..6344)Carbon High303145(47.9% / 57.3%)312 轮 / 31 工具 / 388 s
上线后(steps 7153..10259)Carbon High921631(68.5% / 77.8%)05 轮 / 12 工具 / 97 s
上线后(steps 10260..10385)Neon High4035(87.5% / 97.2%)01 轮 / 2 工具 / 0 s

关键发现:

  • 在最容易“哑火”的 Hydrogen XHigh 上,边调工具边汇报比例从 4.0% 跃升至 32.0%(提升 8 倍),原本长达 9 分钟(538 秒 / 37 轮) 的黑盒静默被直接压回 75 秒 / 6 轮 以内;
  • 在 Carbon High 超过 3,100 步、1,689 次工具调用的长周期运行里,>=10 轮静默彻底清零,最长静默轮数精确封顶在阈值 5 轮。

4.2 全机 45 个真实会话、296 次生产触发唤醒率统计 ​

生产指标(45 个活跃会话全量扫描)实测结果占比 / 说明
[进度轻推] 累计触发次数296 次覆盖 45 个不同工作区与任务类型
次轮立即开口唤醒次数281 / 29694.9%(收到轻推后的紧邻下一轮即输出可见文本)
其中:同回合“开口 + 继续调工具”250 / 281占开口回复的 89.0%(占全部触发 84.5%,零废回合)
其中:纯文字回复(收尾总结 / 向用户请示)31 / 28111.0%
2 轮内开口唤醒次数284 / 29695.9%
次轮仍保持静默次数10 / 2963.4%(其余 5 次在次轮前被用户新消息打断)
经 /compact 回注泄漏的 SYSTEM_MESSAGE0 / 2960.0%(零跨压缩残留)

4.3 运行时延迟与 Token 开销压测 ​

在 23.43 MB、10,385 步的真实 transcript.jsonl 上连续基准测试:

测量项实测耗时 / 体积说明
invocationNum <= 1 快路径(函数级)0.17 μs不打开日志文件,直接返回 {}
invocationNum >= 2 尾扫 256 KiB(函数级)0.10 ms与文件总大小无关,恒定 $O(1)$ 字节读取
含 Python 进程启动的端到端耗时(20 次均值)18.75 ms远低于单次模型首字延迟(秒级),体感无感
单次轻推注入体积46 字符 / 122 B(~30 tokens)同一静默段最多注入 1 次

5. 诚实的边界与设计取舍 ​

为了避免过度承诺,以下三处边界需要提前明确:

  1. PreInvocation 发生在“下一轮模型推理前”,无法中断正在执行中的单条命令 如果模型在第 1 轮静默发起了耗时 5 分钟的 run_command,Hook 只能等该命令执行完毕、准备进入第 2 轮推理前才触发轻推。这正是为什么必须保留第一层 GEMINI.md,在源头要求“第一批工具同回合必须先附带 1 句中文开场”。两层是互补关系,缺一不可。
  2. 单段封顶 1 次(DEFAULT_MAX_NUDGES = 1)的克制取舍 实测有约 3.4% 的极少数情况下,模型收到 1 次轻推后次轮仍未开口。我们刻意选择不反复连推,避免在模型专注排障时往上下文塞入多条重复系统提示干扰注意力;如希望更激进,可通过环境变量 AGY_SILENT_NUDGE_MAX=2 调整。
  3. 严格 Fail-Open 容错 脚本内所有文件 IO、JSON 解析与时间转换均包在顶层异常保护内,任何异常都静默返回 {} 并以 exit 0 放行,绝不阻塞 CLI 正常推理。

6. 一键部署指南 ​

6.1 第一步:在 ~/.gemini/config/GEMINI.md 加入进度更新规范 ​

将以下段落写入全局 ~/.gemini/config/GEMINI.md(已存在其它个人规则时直接追加即可):

markdown
# 过程性进度更新规范

用户看不到你的内部思考或原始工具结果,只能看到你输出的文本。简单问答或 1~2 步可结束的简单查询保持静默直答;凡需多步排查、修改或执行耗时命令,**第一批工具调用同回合必须先附带 1 句中文开场说明准备查/做什么**(勿只说不做或空正文闷头连跑),并在后续关键节点提供简短进度更新,不要只在结束后汇报。

## 更新时机
- 开始新的排查、实现或修改工作时。
- 完成关键步骤,或获得重要发现时。
- 遇到错误、阻塞、风险,或需要调整方案时。
- 开始预计耗时较长的操作前。
- 需要用户补充信息或作出决策时,立即说明。

## 更新内容
- 每条更新用 1~2 句中文,简要说明已完成的工作、关键结果和下一步。任务刚开始时,说明即将开展的工作;尚无结果时,不必强行补齐。
  例如:“已找到配置文件,缓存路径可能存在问题。接下来会核对实际读取的配置,并验证修改是否生效。”

## 更新要求
- 只报告可验证的操作和结果,明确区分已确认事实与待验证判断。
- 不输出详细思维链,不编造进度。
- 合并琐碎步骤,避免逐条复述工具输出或频繁刷屏。
- 遇到阻塞或风险时,说明影响及所需协助;需要用户决策时,给出明确问题。
- 多步任务结束后,简要汇总结果、验证情况和遗留事项。

6.2 第二步:放置脚本并合入 ~/.gemini/config/hooks.json ​

  1. 直接下载 silent_turn_nudge.py(或复制附录全文)保存至 ~/.gemini/config/hooks/silent_turn_nudge.py 并赋予执行权限:
bash
mkdir -p ~/.gemini/config/hooks
chmod +x ~/.gemini/config/hooks/silent_turn_nudge.py
  1. 在 ~/.gemini/config/hooks.json 中注册 silent-turn-nudge(如同时使用 压缩后无损回水方案 或其他自定义 Hook,直接并列合入顶层对象,不要覆盖原有条目):
json
{
  "post-compact-rehydrate": {
    "enabled": true,
    "PreInvocation": [
      {
        "type": "command",
        "command": "/usr/bin/python3 ~/.gemini/config/hooks/rehydrate_after_compact.py",
        "timeout": 10
      }
    ]
  },
  "silent-turn-nudge": {
    "enabled": true,
    "PreInvocation": [
      {
        "type": "command",
        "command": "/usr/bin/python3 ~/.gemini/config/hooks/silent_turn_nudge.py",
        "timeout": 5
      }
    ]
  }
}

6.3 可选环境变量调优与一键自查 ​

无需修改源码,可通过环境变量覆盖默认阈值:

环境变量默认值含义
AGY_SILENT_NUDGE_TURNS5连续空正文调用工具达到几轮触发轻推
AGY_SILENT_NUDGE_SECONDS60至少静默 1 轮且距上次锚点满多少秒触发轻推
AGY_SILENT_NUDGE_MAX1同一段静默内最多注入几次轻推

运行一段时间后,可用一行只读命令核查本机全部会话的真实触发次数:

bash
python3 -c 'from pathlib import Path; hits=[sum("[进度轻推]" in l for l in open(p, errors="replace")) for p in (Path.home()/".gemini/antigravity-cli/brain").glob("*/.system_generated/logs/transcript.jsonl")]; print("sessions:", sum(h>0 for h in hits), "total_nudges:", sum(hits))'

7. 附录:完整源码(silent_turn_nudge.py,187 行零依赖标准库) ​

python
#!/usr/bin/env python3
"""Antigravity PreInvocation hook: lightweight anti-silence nudge for long tool chains."""

from __future__ import annotations

from datetime import datetime
import json
import os
from pathlib import Path
import sys
from typing import Any

MARKER = "[进度轻推]"
NUDGE_TEXT = (
    "[进度轻推] 已连续多步静默调用工具,"
    "下一回合请先随工具调用输出 1 句中文进展,勿只回文字不调工具。"
)

DEFAULT_TURN_THRESHOLD = 5
DEFAULT_SECONDS_THRESHOLD = 60
DEFAULT_MAX_NUDGES = 1
TAIL_READ_BYTES = 262_144


def _env_int(name: str, default: int, minimum: int = 1) -> int:
    raw = os.environ.get(name)
    if raw is None or not raw.strip():
        return default
    try:
        return max(minimum, int(raw))
    except ValueError:
        return default


def parse_iso_epoch(ts_str: Any) -> float | None:
    if not isinstance(ts_str, str) or not ts_str:
        return None
    try:
        norm = ts_str[:-1] + "+00:00" if ts_str.endswith("Z") else ts_str
        return datetime.fromisoformat(norm).timestamp()
    except ValueError:
        return None


def resolve_transcript_path(payload: dict[str, Any]) -> Path | None:
    tp = payload.get("transcriptPath")
    if isinstance(tp, str) and tp:
        p = Path(tp)
        if p.is_file():
            return p
    cid = payload.get("conversationId")
    if isinstance(cid, str) and cid:
        p = (
            Path.home()
            / ".gemini"
            / "antigravity-cli"
            / "brain"
            / cid
            / ".system_generated"
            / "logs"
            / "transcript.jsonl"
        )
        if p.is_file():
            return p
    return None


def read_tail_lines(path: Path, max_bytes: int = TAIL_READ_BYTES) -> list[bytes]:
    size = path.stat().st_size
    if size <= 0:
        return []
    with open(path, "rb") as fb:
        seek_pos = max(0, size - max_bytes)
        fb.seek(seek_pos)
        chunk = fb.read()
    lines = chunk.splitlines()
    if seek_pos > 0 and lines:
        lines = lines[1:]
    return lines


def analyze_silence(
    lines: list[bytes],
    now_epoch: float,
    max_nudges: int = DEFAULT_MAX_NUDGES,
) -> tuple[int, float | None, int]:
    """Scan backward to the latest user turn, spoken planner reply, or checkpoint."""
    silent_turns = 0
    nudges_in_stretch = 0
    anchor_epoch: float | None = None
    oldest_epoch: float | None = None

    for raw in reversed(lines):
        if not raw.strip():
            continue
        try:
            obj = json.loads(raw.decode("utf-8", "replace"))
        except json.JSONDecodeError:
            continue

        ts = parse_iso_epoch(obj.get("created_at"))
        if ts is not None:
            oldest_epoch = ts

        stype = obj.get("type")
        if stype == "USER_INPUT":
            if anchor_epoch is None:
                anchor_epoch = ts
            break
        if stype == "CHECKPOINT":
            if anchor_epoch is None:
                anchor_epoch = ts
            break
        if stype == "SYSTEM_MESSAGE":
            if MARKER in str(obj.get("content") or ""):
                nudges_in_stretch += 1
                if anchor_epoch is None:
                    anchor_epoch = ts
                if nudges_in_stretch >= max_nudges:
                    break
            continue
        if stype == "PLANNER_RESPONSE":
            content = str(obj.get("content") or "").strip()
            if content:
                if anchor_epoch is None:
                    anchor_epoch = ts
                break
            if obj.get("tool_calls"):
                silent_turns += 1

    ref_epoch = anchor_epoch if anchor_epoch is not None else oldest_epoch
    silent_seconds = max(0.0, now_epoch - ref_epoch) if ref_epoch is not None else None
    return silent_turns, silent_seconds, nudges_in_stretch


def should_nudge(payload: dict[str, Any], now_epoch: float | None = None) -> bool:
    inv_num = payload.get("invocationNum")
    if isinstance(inv_num, int) and inv_num <= 1:
        return False

    tpath = resolve_transcript_path(payload)
    if tpath is None:
        return False

    turn_threshold = _env_int("AGY_SILENT_NUDGE_TURNS", DEFAULT_TURN_THRESHOLD)
    sec_threshold = _env_int("AGY_SILENT_NUDGE_SECONDS", DEFAULT_SECONDS_THRESHOLD)
    max_nudges = _env_int("AGY_SILENT_NUDGE_MAX", DEFAULT_MAX_NUDGES)

    lines = read_tail_lines(tpath)
    if not lines:
        return False

    now = datetime.now().timestamp() if now_epoch is None else now_epoch
    silent_turns, silent_seconds, nudges_in_stretch = analyze_silence(
        lines, now, max_nudges=max_nudges
    )
    if nudges_in_stretch >= max_nudges or silent_turns <= 0:
        return False
    if silent_turns >= turn_threshold:
        return True
    if silent_seconds is not None and silent_seconds >= sec_threshold:
        return True
    return False


def main() -> None:
    try:
        raw_in = sys.stdin.read()
        if not raw_in.strip():
            print("{}")
            return
        payload = json.loads(raw_in)
        if not isinstance(payload, dict) or not should_nudge(payload):
            print("{}")
            return
        print(
            json.dumps(
                {"injectSteps": [{"systemMessage": {"systemMessage": NUDGE_TEXT}}]},
                ensure_ascii=False,
            )
        )
    except Exception:
        print("{}")


if __name__ == "__main__":
    main()