执行反馈闭环揭秘:AgentHandover 让 Skill 越用越聪明的 MCP 执行协议(report_execution_*)全解析
执行反馈闭环揭秘:AgentHandover 让 Skill 越用越聪明的 MCP 执行协议(report_execution_*)全解析
AgentHandover 是一个开源的 AI 代理「工作交接」工具:它默默观察你在 Mac 上的操作,把重复性工作流学成一份份可执行的 Skill,并交给 Claude Code、Codex、OpenClaw 等 AI 代理执行。本文完整解析它的核心机制——执行反馈闭环:通过 MCP 执行协议的三个工具 report_execution_start、report_step_result、report_execution_complete,让每次 Skill 的执行结果都回流为学习信号,实现"越用越聪明"的自改进。
为什么"只交任务、不管结果"不够用
大多数工作流工具止步于"把步骤交给代理,祝你好运":Skill 交给代理后,执行得好不好、哪里走了样,工具一无所知。AgentHandover 选择了另一条路——闭环(Execution Feedback Loop):
- 每份 Skill 自带一段「执行协议」,明确告诉代理如何汇报进度;
- 代理执行过程中通过 MCP 服务器逐步回传每一步的结果;
- 每一次运行(无论成功、偏离还是失败)都会被记录,并反过来改进 Skill。
这套机制在 README.md 中被列为项目特性,官方描述一针见血:"大多数工具止步于『给你一份流程,祝你好运』,AgentHandover 把环闭合了。"
MCP 执行协议三步走:如何接入反馈回路
所有接入 AgentHandover MCP 服务器的代理,都能在 Skill 文本末尾看到这样一段协议(真实示例见 worker/tests/fixtures/skill_packets/mcp.md):
- 开始前调用
report_execution_start(带上 Skill 的 slug)- 每完成一步调用
report_step_result,如果做了与步骤不同的事,把status设为deviated并在actual_action里说明- 结束时调用
report_execution_complete
三个工具全部定义在 worker/src/agenthandover_worker/mcp_server.py 中,各司其职:
第一步:report_execution_start —— 登记开工,领取执行编号
代理开工前先"报到"。系统会:
- 生成唯一的
execution_id,作为后续所有汇报的凭据; - 返回
expected_steps——这份 Skill 每一步的编号(如step_1、step_2),与 Skill 文本中括号里的 id 一一对应; - 把这次运行写入数据库的
runs表,即使代理中途崩溃,记录也不会丢。
第二步:report_step_result —— 每步回执,偏离自动识别
每完成一步,代理用 step_id(step_2 或数字 2 均可)汇报。这一步有两个值得注意的细节:
- 偏离判定是自动的:如果你描述的
actual_action与预期步骤在语义上对不上(系统会用词元相似度做宽松比较,时态和单复数不影响判断),即使你没声明,系统也会记为deviated; - 允许"计划外动作":报告一个 Skill 里没有的步骤时,不会报错,而是记为动态步骤,同样纳入学习。
第三步:report_execution_complete —— 收尾并触发学习
结束时声明 completed、failed 或 aborted 三种状态之一。这一次调用是闭环的"齿轮咬合点":系统立即用 worker/src/agenthandover_worker/skill_improver.py 把整次运行写回 Skill 本体,返回中会带上 improvements 字段,告诉你这次运行改了什么。
反馈落地:一次运行如何让 Skill 变聪明
执行数据的记录与流转由 worker/src/agenthandover_worker/execution_monitor.py 承担。三种结果,三种学习信号:
| 运行结果 | 系统学到什么 | 对 Skill 的影响 |
|---|---|---|
| ✅ Completed | 步骤完全按文档执行 | 计入执行信心分,刷新"最后确认"时间;连续 3 次照做,步骤从"假设"升级为"已知" |
| ⚠️ Deviated | 代理实际做的替代方案 | 存入该步骤的 observed_alternatives;若偏离发生在"决策"步骤,该决策回到"未知"并向你发起提问;同一处出现 2 次以上则建议拆分分支 |
| ❌ Failed | 失败错误信息 | 作为漂移(drift)信号记在 Skill 上,提醒流程可能已过期 |
这里有个精妙的设计:执行信心分与合成信心分是两套账。confidence_avg 衡量"Skill 与你真实操作的吻合度",而 execution_confidence 用拉普拉斯平滑统计"代理跑这份 Skill 的成功率"(偏离算半分、放弃不算数)。两者互不污染,Skill 不会因为代理偶尔发挥失常而被误伤。
同样重要的还有安全边界:代理的运行数据永远不会自动改写你的步骤。Skill 的更新路径是——系统记录现象 → 向你提问(如"代理在第 2 步没按文档做,你在这个步骤是怎么决策的?")→ 由你的回答和人工评审最终定稿。
完整链路可以在端到端测试 worker/tests/journeys/test_mcp_feedback.py 中读到:一个模拟代理通过真实 MCP 会话执行 Skill、按 id 和数字混合汇报、产生一次偏离,最后断言 execution_stats、observed_alternatives 正确写回,且 Skill 重新生成后这些数据依然保留。
快速上手:3 行配置接入闭环
任何支持 MCP 的客户端都能接入,配置只需指向 agenthandover-mcp 命令:
{
"mcpServers": {
"agenthandover": {
"command": "agenthandover-mcp"
}
}
}
针对主流代理还有更省事的快捷方式,例如 Claude Code 一键配对:
agenthandover connect claude-code
菜单栏应用会自动检测已安装的代理(Claude Code、Cursor、Windsurf、Codex、OpenClaw)并支持一键连接,且只有确认代理真的能列出 MCP 服务器后才显示"Connected"。
小结:闭环才是自改进的起点
AgentHandover 的 report_execution_* 协议看似只是三个简单的 MCP 工具,实则是"观察 → 学习 → 交接 → 执行 → 反馈 → 再学习"飞轮的传动轴:
- 对代理:执行 Skill 时多几次轻量调用,换回系统级的记忆与进化;
- 对 Skill:每次运行都在积累证据,步骤从假设变已知,替代方案沉淀为分支,失败沉淀为漂移信号;
- 对用户:改动始终经过提问与评审,既聪明又不越权。
这正是标题里"越用越聪明"的工程含义——不是玄学,而是一条可审计、可测试的数据回路。


