
Claude Code 完成信号持续演进:我们如何实现零感知的无缝兼容
为什么仅靠对 Claude Code 终端输出做关键字匹配注定会崩溃?深入探讨 MadoHub 如何通过黑盒 Watcher 与终端形态特征双轨判定 Agent 轮次结束。
在多 Agent 协同编排中,MadoHub 必须在 Agent 结束当前工作轮次的毫秒级瞬间准确捕捉到这一信号——因为正是这一事件触发了下游路由连线,将图块状态从 working 翻转为 done,并安全地通知下一个协同 Agent 提取输出。
在早期版本中,我们判断 Claude Code 是否完成的逻辑非常简单:对终端字符做纯文本字符串匹配。这在最初很奏效,直到 Claude Code 发布了新版本、换了一批不同的动词,整个检测逻辑瞬间瘫痪。
本文将分享我们如何推翻粗暴的关键字硬编码,以及为什么单纯优化正则表达式甚至都算不上真正的终极解法。
问题的本质
动词列表注定会过期
Claude Code 在完成一轮任务时,通常会在终端打印一行完成提示,类似:✽ Worked for 2m 30s。在最初的检测器中,我们硬编码匹配了横幅里的两个具体动词——Sautéed 和 Cogitated——因为这是当时特定版本恰好在输出的单词。检测逻辑其实就是简单的关键字检查:命中单词 $\rightarrow$ 启动空闲计时器 $\rightarrow$ 触发下游路由。
这种策略的寿命完全取决于 Claude Code 何时更换文案。不久之后,Anthropic 开始从一个幽默且不断轮换的动词词库中随机抽词——Worked、Churned、Sautéed、Cogitated 等等——每个新版本都可能带来新的动词,展现 CLI 工具的个性化风格。
然而每一次词库更替,我们的关键字匹配就会在静默中失效,所有依赖它的图块都无法正确感知任务完成,只能等开发者发现并人工提 PR 补充词表。
通过枚举有限的单词去追踪一个不断移动的靶子,注定是一场必败的游戏。唯一的出路是:彻底不再依赖具体动词是什么。
匹配语法形态,而非特定词汇
无论官方当周上线什么俏皮的新动词,每一条完成提示都保持着高度统一的几何与语法骨架:行首的特定 Glyph 字形符号、一个首字母大写的过去式动词、固定的 for 连接词、以及一个时间跨度。
只要符合这个结构形态,无论未来更新什么生僻动词,检测逻辑都无需改动任何代码即可持续生效。
此外,“严格要求字形位于行首”至关重要。因为在庞杂的编译与测试日志中,充斥着大量看似符合“动词 + for + 时长”却完全不代表本轮任务结束的杂乱文本——例如网络重试日志 Retried for 3s、构建步骤 Waited for 5s。强制匹配行首特定符号,便能干净利落地剔除所有误判。
MadoHub 的双轨判定架构
终端字符匹配只是加速器,而非终审裁决
必须明确的是:终端特征匹配并不是 MadoHub 判断 Claude Code 是否完成的唯一依据,它仅仅是一个低延迟加速器。
真正具备权威效力的判定源,来自直接读取 Claude Code 本地会话 Transcript 日志的后端核心观察者(Watcher):
- Watcher 实时剖析日志中的最新消息:如果是一条没有任何未处理工具调用的 Assistant 消息,则标志着 Agent 已经实质结束;
- 如果是 User 消息、Progress 进度更新,或是包含未执行完 Tool Call 的 Assistant 消息,则证明 Agent 仍在活跃运行中。
应用层会对这两种判定进行严格的置信度标记,清晰区分“基于 Transcript 文件的绝对事实”与“基于终端屏幕采样的推测事实”。
终端特征匹配存在的唯一价值,是为了抹平 Watcher 异步写入磁盘的几百毫秒滞后,让你在肉眼看到提示的那一瞬间,图块状态立即利落翻转。
纵深防御:宁可漏判,绝不误判
在“过于严格(可能漏判)”与“过于宽松(可能误判)”之间,MadoHub 坚定地倒向了前者。
这是经过深思熟虑的工程权衡:一次漏判是无害的,因为底层的 Watcher 在毫秒之后依然会兜底上报真实的完成状态;而一次误判则是致命的,它可能在中途提前触发路由,把半成品的脏数据直接喂给下游流水线。
因此,MadoHub 在屏幕匹配层之上架设了纵深防御:如果屏幕嗅探给出了“done”的结论,但此时底层 Watcher 坚称 Agent 仍在“working”,MadoHub 会坚决抛弃屏幕嗅探的结果——Watcher 拥有无可争议的终审权。
实用建议
- 无需死记最新的终端动词: 依赖规则形态而非特定词汇,这是最稳健的解析范式。
- 状态出现微调是正常校准: 如果你偶遇图块短暂跳到“done”又瞬间回退,那是底层 Watcher 在矫正过于激进的屏幕匹配,属正常防误判机制。
- 切勿自行编写针对具体动词的脆弱规则: 在配置自定义 Flows 时,直接依赖 MadoHub 提供的状态机信号(Working / Done / Failed),避免自行截取终端文本导致版本迭代时静默失效。