用结构化交接减少智能体跨会话返工
作者针对智能体跨会话丢失上下文的问题,提出包含目标、背景、决策、文件变更、待定问题、后续步骤、验证状态和敏感信息排除声明的八段式交接文档。重点是记录已验证事实与被否决方案,让接手者能从最小可验证动作继续工作。
AI 深度解读
AI 编程任务跨会话继续时,最容易丢的往往是判断依据:为什么改这里、哪条路已经试过、哪些检查真的跑过。作者给一个 250-SKU 商店运行频繁轮换的 Agent,提出用八项必填的结构化交接文档,再用脚本检查完整度,替代随手写的聊天摘要。
这个方案值得看,因为它把「给下个会话留点上下文」变成了可检查的流程。不过,检查文档有没有写全,与确认文档里的话可信,是两件事。
下一个 Agent 缺的究竟是什么
原文设想了一个很常见的断点:会话 A 做了三个小时,触及上下文限制后结束;会话 B 从头启动,却不知道为什么认证重构牵涉计费模块,也不知道哪些方案已经被否决。
仓库能告诉它代码现在长什么样,却未必能解释代码为什么变成这样。聊天记录里可能有答案,但接手者还得重新搜索、筛选,并区分已经过时的想法与最终决定。
作者认为,普通聊天摘要记录的往往是 Agent「说自己做了什么」,没有充分保留后续行动需要的依据。真正的交接要让接手者迅速判断:目标是什么、哪些结论可以沿用、下一步从哪里开始。
交接文档的价值,是减少下一轮重复调查和错误假设。
八项必填,怎样变成可执行的交接
作者要求交接文档包含八个部分,每项都承担具体职责:
- Objective:用一句话定义什么状态才算完成。
- Context:补充仓库之外、接手者必须知道的信息。
- Decisions made:记录已选方案和被否决的替代方案,避免重新争论。
- Files touched:列出精确文件路径,减少接手后全仓搜索。
- Open questions:区分真正没决定的问题与已经有结论的问题。
- Next steps:按顺序安排后续动作,第一步必须是最小、可验证的操作。
- Verification state:区分实际运行并通过的检查与尚未验证的假设。
- Secrets excluded:提醒凭证不能写入交接文档。
其中最有用的是「下一步」和「验证状态」。只有「继续完成认证重构」,接手者仍然需要重新规划;如果第一步已经缩小到一个能验证的动作,就更容易恢复工作。类似地,「测试通过」也不够,应该留下实际执行与结果的凭据。原文提到了这种凭据格式,但没有展开具体写法。
为了让八项要求得到执行,作者提供了 handoff_check.py。它只依赖 Python 标准库,针对八个部分给出 0–100 分的完整度评分,并通过 --fail-below 75 接入 CI 门禁:低于阈值,自动化流水线就不允许完成交接。
这套售价 $14 的工具包包含 JSON 和 Markdown 模板、校验器、完整示例,以及一个故意缺项的示例,用来展示评分失败的情况。
我的判断
这个方案说得对的地方,是把接手所需的信息明确列了出来。尤其是被否决的方案、精确路径和验证状态,都是普通摘要容易省掉、下一轮却可能花时间重新确认的内容。
但作者明确承认,校验器只检查结构,不检查真实性。八项全填,不代表判断正确;分数够高,也不代表工作已经验证充分。75 是工具提供的门槛,原文没有解释其合理性,也没有给出交接耗时、返工率或错误率的对照数据。它目前更适合被理解为作者的实践方案,不能据此认定效果已经得到量化证明。
「优于记忆工具」也有适用范围。作者把长期记忆用于长期召回,把会话搜索用于查找日志,把交接文档用于当前任务的集中简报。这个分工合理,但原文没有证明其他工具无法组合出同样的流程。
至于凭证泄漏,作者称其为 Agent 工作流中最常见的泄漏途径,却没有提供统计依据。而且,仅仅存在 Secrets excluded 一栏,也不能证明文档里没有秘密。
能拿来做什么
- 前端或 Node 任务需要跨会话继续时,可以先采用这八项结构,重点留下仓库里看不到的约束、被否决方案的理由和精确文件路径。
- 把下一步写成最小可验证动作,例如先运行与当前改动相关的检查,并明确要确认什么,减少新会话重新规划的成本。
- 在交接里分开记录「实际运行且通过」「尚未运行」「仅凭推断」的内容,避免下一轮把假设当作事实。
- 如果交接已经进入自动化流程,可以参考
handoff_check.py的门禁思路检查缺项;把完整度评分当作文档检查,技术结论仍需用验证结果支撑。