个人知识库

文件交接协议

7分钟阅读

文件交接协议

多智能体协作的输出规范：子智能体把完整过程（调查、代码片段、测试日志）写入文件，只向主会话返回简短状态和文件地址，从根源上防止主上下文被中间过程污染

简介

文件交接协议（file handoff contract）是多智能体编排里的输出规范，核心原则一句话：完整结果写文件，主会话只接收简短状态和文件地址。它解决的是多智能体协作中最容易犯、也最致命的错误——让子智能体把所有调查过程、代码片段、测试日志都直接返回给主会话，从而迅速污染主上下文。

在 Coding Agent 处理复杂任务时，子智能体会产生大量中间产物（报告、日志、截图）。如果这些内容全部回灌主会话，主智能体的有效上下文很快被挤爆，决策质量下降。文件交接协议通过”重活写盘、回传只留指针”的方式，让主智能体上下文保持干净，同时让整个过程可追踪、可复盘、可验收。它与 子智能体 Brief 中的 output_path、handoff_format 字段直接对应，是 Brief 落地的下半场。

关键信息

核心特性

只回传状态和路径，不回传过程

反模式是让子智能体把全部过程塞回主上下文。正确做法是子智能体只返回结构化的短消息，例如成功时：

STATUS: PASS
REPORT: .agent-runs/2026-07-01/task-003/test-report.md
ARTIFACTS: .agent-runs/2026-07-01/task-003/screenshots/
SUMMARY: Auth API validation tests passed. No regression found.

失败时返回失败摘要，细节仍在文件里：

STATUS: FAIL
REPORT: .agent-runs/2026-07-01/task-003/test-report.md
FAILED_CASES:
 - tests/auth.test.ts::should_return_400_when_password_missing
REASON: Password missing case returns 500 instead of 400.
SUGGESTED_NEXT_STEP: Send back to auth-api-implementer for repair.

统一的 .agent-runs 目录结构

所有子智能体的详细产物写入统一目录，按日期和任务编号组织：

.agent-runs/2026-07-01/task-001/
├── plan.md                    # 规划/调查报告
├── investigation-report.md
├── implementation-report.md   # 实现变更记录
├── test-report.md             # 测试结果
├── review-report.md           # 审查结果
├── screenshots/               # UI 验证截图
└── final-summary.md           # 主智能体汇总

这个目录本身就是一条可追溯的证据链。

两个直接收益

  1. 主智能体上下文保持干净：主会话只保留决策信息（状态 + 路径 + 一句话摘要），不被日志和代码片段淹没，决策空间不被挤占
  2. 过程可追踪、可复盘、可验收：用户事后想知道”到底改了什么""测试有没有跑""为什么失败”，直接去 .agent-runs/ 目录看报告即可，不必依赖主会话记忆

与验证证据链的关系

文件交接协议是”验证策略”落地的载体。验证策略要求”一个任务在存在至少一个验证产物之前不算完成”——测试命令与结果、构建结果、运行时输出、截图、日志摘录等。这些验证产物正是通过文件交接协议沉淀到 .agent-runs/ 目录，最终由主智能体汇总成交付报告里的 VERIFICATION 段。

不同素材中的观点

来自 2026-07-01-woshipm-multi-agent-coding-pipeline：

  • 最容易犯的错误是把过程塞回主会话：作者明确指出多智能体协作里最容易犯的错误，就是让子智能体把所有调查过程、代码片段、测试日志都直接返回主会话，这会迅速污染主上下文。文件交接协议是针对性的解药
  • file-handoff-contract.md 是整套系统的关键：在设计 multi-agent-programming Skill 时，作者把文件交接契约列为”整套系统的关键”文件，要求所有子智能体必须把详细结果写入文件、只返回状态和路径
  • 报告目录反哺知识沉淀：.agent-runs/ 里的报告不仅用于当次验收，还能反过来优化 Skill、补充常见错误、形成项目知识库——让”经验可沉淀”成为多智能体协作提升的第四项价值

实用信息

落地清单

  • 约定统一根目录 .agent-runs/{日期}/{task-id}/
  • 为每类子智能体规定固定的报告文件名（plan / implementation-report / test-report / review-report）
  • 在 子智能体 Brief 的 output_path 中指向具体报告路径
  • 规定回传消息只含 STATUS + 报告路径 + 一句话摘要，禁止回灌全文
  • 失败消息包含 FAILED_CASES、REASON、SUGGESTED_NEXT_STEP，便于主智能体路由

注意事项

  1. 回传消息要克制：SUMMARY 控制在一两句话，细节一律进文件
  2. 路径要真实可读：主智能体和用户都可能去读，路径必须准确
  3. 状态值要标准化：统一用 PASS / FAIL / BLOCKED，便于主智能体做分支判断
  4. 与 Brief 成对使用：Brief 定义”输出到哪里、怎么交接”，交接协议定义”回传长什么样”，两者配套才完整

相关页面

关系图谱

快速导航

反向链接