诚实完成的秘密：mercury-agent v1.2.3 完成契约与防卡死恢复架构深度解析

【免费下载链接】mercury-agentSoul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.项目地址: https://gitcode.com/gh_mirrors/me/mercury-agent

mercury-agent 是一款 Soul-driven AI 智能体，支持权限加固工具、Token 预算管理与多通道接入。v1.2.3 版本（代号 "Unstoppable Mercury"）引入了完成契约（Completion Contract）与防卡死恢复架构：每个任务结束时都必须经过一次"裁决"——要么给出有证据的完成，要么诚实地暂停并指明卡点。从此任务不再虚报成功、不再静默死亡、也不会无限循环。

痛点：AI 智能体为什么会"谎报"任务完成？

在 v1.2.3 之前，大多数 Agent 循环只做一次"乐观执行"：模型生成 → 工具执行 → 不管结果如何，一律庆祝"Task complete"。常见的翻车场景包括：

• 📉步数预算耗尽：活儿干了一半，却因为工具调用次数用完而停下，却挂出绿色"完成"横幅
• ✂️输出被截断：写大文件时撞上输出上限，文件写到一半被切断
• 🌀叙述型模型：一直说"我正在构建 X……"，却迟迟不产生任何文件
• 💥内存压力：长任务在堆内存见顶时直接崩溃

完整的问题与恢复路径图，可以在官方文档 completion-architecture.md 中查看。

完成契约：任务结束的 5 种"裁决"

完成契约的核心是一个简单的问题：这一轮为什么结束？这个结束算不算真正的完成？

源码位于 src/core/completion-verdict.ts，它把每次回合结束分类为 5 种裁决之一：

其中流式完整性由 src/core/stream-completion.ts 负责判定：服务商断流（缺少 finish 信号）永远不被当作成功；length截断如果恰好切断了文件写入，系统会要求改用"分段写入"——先create_file写前 ~80 行，再用edit_file逐段追加。

防卡死恢复：升级阶梯的四步"强制执行"

当模型只叙述不干活时，mercury-agent 不依赖模型的"自觉"，而是机械式地逐级升级，全程不消耗模型的好感度：

1. 接地（Grounding）—— Agent 自己执行一次确定性的目录列表（不经 LLM），把真实目录状态注入上下文，模型再也无法声称"缺少上下文"
2. 强制行动—— 守护回合的第一步以toolChoice: 'required'运行，且只允许变更类工具（write_file、create_file、edit_file、run_command 等），该步骤上叙述在机制上不可能发生
3. 服务商轮换—— 守护回合沿回退链切换下一个模型，被叙述锁死的模型不是唯一的工人
4. 叫醒服务—— 一整轮失败后，上限翻倍（共 10 个机械回合），并附一条直白指令："你的下一条回复必须以变更工具调用开头，零散文"

只有走完全部 10 个回合仍无进展，系统才会诚实暂停并点名卡点。

三层防卡死机制：内存、时间与看门狗

v1.2.3 的可靠性来自三个互补的守护层：

• 🧠内存治理器—— src/core/memory-governor.ts 在每个工具步边界检查堆增长；内存压力时原地压缩对话并继续（超过最新 8 条之外的超大工具结果被替换为头尾摘要），只有持续压力才中止，长构建不再死于内存上限
• ⏱️卡死看门狗—— src/core/stall-watchdog.ts 守护"时间"维度：静默 3 分钟 → 界面显示可见的"still working"脉冲；静默 8 分钟 → 中止并进入恢复机制，绝不让任务无声燃烧。阈值可用MERCURY_STALL_SOFT_MS/MERCURY_STALL_HARD_MS调整
• 🔁自动续跑—— 步数预算与服务商故障自动继续（6 份新预算），手动 "continue" 只是最后保险，不是检查点

诚实的收尾：暂停、点名、可恢复

这套架构最动人的部分不是"不停"，而是说实话：

• ✅证据门禁—— 实现类任务必须先跑通 build/test/typecheck 才允许挂出完成横幅
• 📌点名卡点—— 每次暂停都携带最后失败的变更工具结果（如write_file: permission denied），修复方向直接在聊天里可见
• 💾可恢复暂停—— 工作台账记录paused状态（src/core/work-ledger.ts）：重启后自动恢复，发送 "continue" 即可续跑
• 🏷️诚实横幅—— 无文件改动时显示 git 验证过的 "Response delivered · no file changes"，完成时附带每文件 +/− 统计与验证证据（"✓ Verified: npm test ✓"）

这些保证全部由回归测试钉死：completion-contract.test.ts 确保"预算耗尽"永远只能产生paused状态，暂停路径在代码上先于完成横幅，子智能体在预算耗尽时上报paused而非completed。

快速上手：升级并体验诚实的完成

升级无需任何配置变更，一条命令即可：

npm install -g @cosmicstack/mercury-agent

安装后进入 Mercury Code 默认即启用 AUTO 模式：先读、静默规划、立即实现，只有大型变更才会弹出一次确认。想调参的话，参考 configuration.mdx。

延伸阅读与源码索引

• 📖 官方文档：完成架构 · v1.2.3 发布说明
• 🔍 核心源码：完成裁决 · 执行守护 · 流完整性 · 卡死看门狗
• 📝 更新日志：CHANGELOG.md

一句话总结：mercury-agent v1.2.3 让 Agent 从"LLM 的聊天外壳"升级为"带保证的编排器"——模型叙述时它机械地迫使行动，任务中断时它点名卡点，而每一次"完成"都有证据背书。

【免费下载链接】mercury-agentSoul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.项目地址: https://gitcode.com/gh_mirrors/me/mercury-agent