fix(prompt): 消除 Claude Code「无可见输出」误判导致的重复发送

[Barrierml]

⚠️ 方案待讨论：本 PR 仅为提示层缓解的参考实现，不能根治该问题。根因分析、5 模型 A/B、以及三个修复方向的完整权衡见 #545——复核后，brief 模式（因 PTY 接入无法 opt-in）与适配层拦截（够不着 harness 内部注入点）均不可行，实际只剩本 PR 这条提示层缓解可落地。请先在 #545 对齐方向后再决定本 PR 的去留。

---

现象

用户在飞书里对同一条消息收到多条重复回复。下图是生产环境（模型 gpt-5.6-sol）里对同一条 !pwd 的回复——同一个问题被换着花样回了 5~6 次（当前目录 / 当前 pwd / pwd = / 纯路径 / 还附了个 botmux-pwd.txt）：

原因（已逐层定位）

这句 [Your previous response had no visible output. Please continue and produce a user-visible response.] 不是 botmux 发的，是底层 CLI Claude Code（≥ 2.1.212）注入的。我在 botmux 整个仓库（含 build/）里 grep 不到这句原文，而在 @anthropic-ai/claude-code 二进制里能抠到，且 codex / gemini / cursor-agent 的二进制里都没有。

从 Claude Code 二进制反编译出的精确触发条件：

// 一轮以 end_turn / stop_sequence 正常结束，但该轮 assistant 消息里
// 没有任何非空 text 块（只有 tool_use / thinking），且最后一轮不是 Task 工具调用
if ((stop_reason==="end_turn" || stop_reason==="stop_sequence")
    && !isApiError && querySource!=="compact"
    && !assistantMsgs.some(m => m.content.some(b => b.type==="text" && b.text.trim().length>0))
    && !hasTaskToolUse(msgs)) {
  if (!thinkingOnlyNudged) {
    // 埋点 query_thinking_only_response = "nudged"
    inject("[Your previous response had no visible output. Please continue and produce a user-visible response.]");
    // thinkingOnlyNudged = true, transition.reason = "thinking_only_retry"
  } else {
    // query_thinking_only_response = "nudge_exhausted"（最多 nudge 3 次）
  }
}

为什么 botmux 特别容易中招：botmux 的核心指令是「回复必须走 botmux send（外部 shell 命令），终端输出用户看不到」。于是模型正确的一轮就是「调用 botmux send + 结尾没有任何可见文本」——恰好命中上面的 thinking-only 检测。模型把这条 nudge 误读为「上一条没发成功」，于是重发；每重发一次又是一次「无可见文本结尾」，再次被 nudge，直到 nudge_exhausted。这就是截图里同一条消息被重复回复的来源。

旁注：Claude Code 自带的 brief 模式（CLAUDE_CODE_BRIEF + 内建 send tool）在协议层把「工具即回复渠道、静默结束合法」做对了，理论上能根治。但复核发现它需要结构化用户消息 opt-in（userMsgOptIn），而 botmux 是用 PTY 把 Claude Code 当交互式 TUI 驱动、没有该 opt-in 通道——单设 CLAUDE_CODE_BRIEF=1 不生效。真正根治需改 Claude 家族的接入方式或由上游 harness 提供豁免（详见 #545）。

修复

纯提示层纠偏，不动发送 / 去重 / 桥接架构。明确告诉模型三件事：

1. botmux send 退出码 0（返回 {"success":true,...}）就代表已送达用户；
2. 本轮「终端没有可见文本、直接结束」是正常且预期的；
3. 若看到「无可见输出，请继续」这类提示是底层 CLI 的误判，不要重发——只有当 botmux send 自身报错（非零退出 / 打印「发送失败」）才重试。

改动落点（6 文件，+34/-4）：

• src/i18n/{zh,en}.ts：新增 ai.routing.no_visible_output_ok、ai.shell.no_visible_output_ok；扩写每轮注入的 ai.followup.reminder（覆盖非 injectsSessionContext CLI 的追问轮）。
• src/adapters/cli/shared-hints.ts：注入两条路径——buildBotmuxSystemPromptText（claude-code / grok / genius 的 --append-system-prompt）+ buildBotmuxShellHints 及旧 BOTMUX_SHELL_HINTS（约 15 个内联提示 CLI）。
• src/skills/definitions.ts：botmux-send 技能补「发送成功判定 & 不要重发」。
• 测试：更新 test/prompt-builder.test.ts 的 reminder 断言 + 在 test/workflow-discovery-hints.test.ts 新增纠偏提示落位断言。

不动：hermes（final 文本转发模型，语义相反）与 bridge/adopt 模式（模型无感知 botmux）。

影响面

仅提示词文本，不改任何运行逻辑。跨全部走 botmux send 的 CLI、每轮生效。

验证

单测

pnpm exec vitest run test/prompt-builder.test.ts test/workflow-discovery-hints.test.ts test/cli-adapters.test.ts
→ 3 files, 356 passed
# 相关套件：insight-readers / resumable-session-discovery / codex-app-clean-prompt / grok-transcript → 73 passed

本地隔离 A/B 复现

方法：真实 claude（Claude Code 2.1.212）+ 一个假 botmux（send 只落盘、不回显，模拟「终端输出用户看不到」）。CONTROL 用 botmux 真实系统提示（master 版），TREATMENT 用本 PR 补丁版——两者逐字仅差本 PR 新增的纠偏句。任务强制「零文本静默结束」以稳定触发 nudge。指标 = 从事件流判定「触发 nudge 后是否又发生 botmux send」（真正的重发）。

生产同款模型 gpt-5.6-sol，各 4 轮：

组	T1	T2	T3	T4	nudge 后重发率
CONTROL（修复前）	未重发	重发	未重发	重发	2/4
TREATMENT（本 PR）	未重发	未重发	未重发	未重发	0/4

8 轮全部触发了 nudge（Claude Code 确定性行为）。典型时序对比：

CONTROL（重发）:  botmux send → NUDGE → botmux send（重复!） → NUDGE → 结束
TREATMENT（正确）: botmux send → NUDGE → 识别为误报 → 安静结束，不重发

关于模型差异（如实说明）：nudge 是 Claude Code harness 的确定性行为，与后端模型无关；是否重发是模型相关的。除 gpt-5.6-sol（生产同款）能干净复现外，另跑了 deepseek-v4-flash（更易感，简化提示下 4→1 条）；而 claude-opus-4-8 / claude-sonnet-5 / glm-5.2 这类更强的模型多数能自我纠错、仅偶发重发（n 小、噪声大）。结论：本修复是提示层的显式护栏——对易感模型/易感回合帮助明显，对强模型无害。

模型说明：生产现象为 gpt-5.6-sol；本地 A/B 主验证亦为 gpt-5.6-sol（经 traex 代理经由 Claude Code 2.1.212 harness 路由）。

[deepcoldy]

Review：代码正确、安全、零回归 —— 可合入(方向问题留给 #545)

由 @BOTMUX开发者(Claude) 独立复核。结论：代码层面无阻塞，纯提示词改动、零运行逻辑变更、干净合入 master、无回归。是否走「提示层」这一层是产品方向问题(作者已在 #545 提出待讨论),不属于代码缺陷。

我独立验证过的点

构建 & 测试

• pnpm build ✅
• 触及提示/i18n/适配器/reminder 信封的全部相关套件 430 用例全绿：prompt-builder / workflow-discovery-hints / cli-adapters / resumable-session-discovery / insight-readers / codex-app-clean-prompt / grok-transcript

合入现状：PR base 落后 master 230 个 commit,但 i18n 高频 churn 未冲突——git merge-tree --write-tree exit 0,逐文件 merge-file 均 CLEAN。

诊断依据成立:no visible output / please continue 原文在 botmux src+dist 里 grep 不到(只有本 PR 新增的纠偏 key),确认该 nudge 非 botmux 注入,来自 Claude Code 二进制——与 PR/#545 描述一致。

易感 CLI 覆盖完整:只有 Claude-Code 家族(claude-code / genius / grok)驱动 claude 二进制、会触发该 nudge;三者都走 buildBotmuxSystemPromptText,已带上 ai.routing.no_visible_output_ok。mir/mira 包 mircli、codex-app 包 codex、riff 是远端 agent——均不经此 harness,无需覆盖。

机制成立:纠偏句经 --append-system-prompt 在 spawn 时注入一次、会话级常驻;nudge 是同会话内注入的一条 user 消息,系统提示仍在上下文里 → 模型能看到纠偏。

hermes 排除双重成立:

1. adapter.systemHints 在运行时从不被读(全仓 grep 只有注释引用它;实际走 buildBotmuxShellHints/buildHermesBotmuxHints 按 locale 重新取)——所以 BOTMUX_SHELL_HINTS 多一行不会泄漏进 hermes;
2. hermes 是「final 文本转发」模型,每轮以可见文本结尾 → 本就不触发 thinking-only 检测;follow-up 也走独立的 hermesFollowupReminder(未改)。

i18n 完整性:两个新 key ai.routing.no_visible_output_ok / ai.shell.no_visible_output_ok 在 zh/en 均已定义,全量 key-set 无 zh-only / en-only 漂移。

边角安全:

• 字面量 {"success":true,...} 安全:interpolate 正则 /\{(\w+)\}/g 要求 { 后接 word char,而实际是 {",永不匹配;且所有新调用点 params 为 undefined,interpolate 根本不执行。
• adopt/bridge 路径正确不注入 <botmux_reminder>(模型对 botmux 无感知),纠偏句不会污染桥接模式。
• 无「必须以可见文本结尾」类矛盾指令。
• 无脆弱的 hint 数组长度/精确匹配断言会被 +1 行打破。

观察(非阻塞)

• follow-up reminder(ai.followup.reminder)实际覆盖除 mira 外全部 CLI(含 claude-code),PR 描述写的「覆盖非 injectsSessionContext CLI 的追问轮」略窄——实际覆盖面更广,对 claude-code 是「系统提示常驻 + 每轮 reminder」双保险,无害。仅描述措辞可微调。
• 效力如实:A/B(gpt-5.6-sol)CONTROL 2/4 重发 → TREATMENT 0/4。提示层护栏对易感模型/回合帮助明显、对强模型无害;但天然无法 100% 保证——这正是 #545 要对齐的方向问题。

建议

代码可合。先在 #545 对齐「提示层缓解 vs 根治」的方向,方向 OK 后本 PR 即可落地。

[deepcoldy]

追加改动:改为全局实验开关(默认关) — 已推送 70ae9609

按讨论把本 PR 的「无可见输出/不要重发」纠偏提示从无条件注入改为全局实验开关门控,默认关闭。评审共识:该提示主要在 Claude Code 驱动非 Claude 后端模型时才有明显收益(易把 harness 的 thinking-only nudge 误读为发送失败而重复回复),对纯 Claude 场景无害但通常无需——因此做成可选、默认关,有需要再在 dashboard 打开。

开关设计

新增 dashboard.noVisibleOutputHint(布尔,默认 OFF,absent ⇒ off),完全套用现成 codexRpcInput 的成熟链路(实验性、live-read、翻动下一个会话即生效、无需重启 daemon):

层	改动
global-config.ts	接口字段 + readDashboard 布尔解析(非布尔丢弃)
config.ts	live getter config.noVisibleOutputHint(readGlobalConfig().dashboard?.noVisibleOutputHint === true)
shared-hints.ts	两处高频注入面(buildBotmuxSystemPromptText 路由块 + buildBotmuxShellHints)按开关条件插入。静态 BOTMUX_SHELL_HINTS 不加(其契约禁止 module-load 期读运行时配置)
session-manager.ts	每轮 <botmux_reminder> 按开关在 ai.followup.reminder(基线) / ai.followup.reminder_no_resend(纠偏)间选择
i18n(src)	ai.followup.reminder 回退 master 原短句;新增 ai.followup.reminder_no_resend(zh/en);ai.routing/shell.no_visible_output_ok 保留(仅开关开时被引用)
dashboard	ResolvedDashboardSettings 字段 + resolve + settings-write-applier 校验(invalid_noVisibleOutputHint)+ settings-page.tsx 实验性区块 ToggleRow + i18n label/help(zh/en)

技能文档 botmux-send 里那段「不要重发」按讨论保留不门控(按需查阅、非每轮强注入,为它改 installer 幂等/签名不划算)。

影响面

仅提示词文本 + 一个默认关的实验开关,不改发送/去重/桥接逻辑。门控在共用注入面,对全部走 botmux send 的 CLI 一致生效;hermes 仍走自己的 hermesFollowupReminder,不受影响。

验证

• pnpm build 绿
• 相关套件全绿:workflow-discovery-hints(重写为 OFF/ON 双态)/ prompt-builder / global-config / settings-write-applier / cli-adapters / dashboard-i18n / codex-rpc-lifecycle / daemon-internal-api
• 运行时门控双向验证:OFF ⇒ 路由/shell/reminder 三处均无纠偏句;ON ⇒ 三处均出现
• ⭐字节级对拍:当前分支 OFF 状态 vs PR base 父提交(pre-feature master) 的 buildBotmuxSystemPromptText/buildBotmuxShellHints(zh+en)渲染 逐字完全一致;ON 与 OFF 有差异(纠偏句确实出现)。即:默认关时对既有行为零影响
• 全量 pnpm test:9 失败全部落在 scheduler / schedule-card-model / v3-distillation-runner;在干净 origin/master 同 3 文件跑出一模一样的 9 失败 = 机器级时间敏感/沙盒基线,零回归

新增测试:global-config 解析(布尔/非布尔丢弃)、settings-write-applier(写入 + invalid_noVisibleOutputHint 拒绝)、workflow-discovery-hints(OFF 基线态 + ON 态)、prompt-builder(OFF 基线 reminder + ON 纠偏 reminder)。

[Barrierml]

已 rebase 到最新 master + 解冲突，转正式 PR

按讨论把分支从旧 base（落后 master 245 commit）rebase 到最新 origin/master，两个 commit 原样保留（fix(prompt) 作者 shir0ha / feat(config) 作者 申晗）。

冲突只集中在实验开关那一版触及的 4 个 dashboard 文件，全部是「master 新增 codexNotifier 设置」与「本 PR 新增 noVisibleOutputHint 开关」在同一处各自追加，两边保留即可，无逻辑取舍：

• src/dashboard.ts（ResolvedDashboardSettings 字段 + resolve）
• src/dashboard/settings-write-applier.ts（字段 + 错误类型 union；校验/写入块非冲突区已干净落入）
• src/dashboard/web/i18n.ts（zh + en label/help）
• src/dashboard/web/settings-page.tsx（类型 + 本地 state + JSX：CodexNotifierSettingsEditor 与新 ToggleRow 并存）

验证

• mergeable: MERGEABLE（GitHub 侧确认干净合入）
• 开关链路 4 文件（global-config / config / shared-hints / session-manager）门控完整无缺
• 相关套件全绿：global-config / settings-write-applier / workflow-discovery-hints / prompt-builder / cli-adapters = 453 passed
• 注：本地沙盒 tsc 会报 122 个 Cannot find namespace 'JSX'，但干净 origin/master 上同样报 122 个、数目一致，是环境缺 JSX 运行时类型配置所致、非本次改动引入（实际 dashboard 走 esbuild bundle）

默认 OFF，行为与 pre-feature master 逐字一致。方向问题仍以 #545 为准。