cross-agent-handoff

用途

Cross-Agent Handoff 用于在 AI 智能体会话之间转移工作，避免因上下文限制、任务切换或超时而丢失上下文、决策与进度。当一次会话结束时，下一个智能体若没有结构化交接，往往会重新探索已理解的代码、重新做出已决定的决策、与前一智能体的方案相矛盾，或遗漏此前发现的关键约束。该技能通过交接文档、状态序列化和决策日志保留来解决这些问题。

主要能力

交接文档结构

交接文档包含以下部分：

• 标题与元信息：任务名、来源会话 ID、日期、当前阶段。
• 当前状态：当前存在的内容——已创建的文件、分支、测试状态。
• 已完成工作：已完成事项及证据（例如已创建的 SKILL.md 文件列表）。
• 关键决策：做出的决策及其理由，避免下一个智能体重新争论。文档中给出示例表格，如使用 governance_norm_group: repo-hygiene 用于打包技能，理由是打包属于基础设施卫生而非质量门；将 data-backup-patterns 放在 development/ 而非 security/，因为它是工程模式，安全基线通过 norm_group 适用。
• 关键上下文：下一个智能体需要知道的非显而易见信息，例如 ecosystem.yaml 显示目标 130+ 技能、当前 101；治理元数据格式包含 governance_phases、governance_norm_group、organ_affinity、triggers、complements；bundle 技能使用 includes: 字段列出组成技能名。
• 下一步行动：明确无歧义地说明接下来做什么，例如创建 Wave 1 技能、运行 refresh_skill_collections.py、用 validate_skills.py --collection example --unique 验证。
• 风险与警告：可能出错的事项，例如技能名必须与目录名完全一致、技能变更后必须刷新 .build/ 产物、16GB 内存限制下最多 4-6 个并发智能体。

上下文压缩

提供按 token 预算分级的摘要级别：

级别	Token 预算	内容
完整	不限	完整交接文档
标准	约 2000 tokens	状态 + 决策 + 下一步行动
最小	约 500 tokens	仅当前状态 + 下一步行动
紧急	约 100 tokens	“从计划 Y 的第 X 步继续”

并给出 compress_handoff 函数的 Python 示例，根据目标 token 数选择不同格式。

多智能体协调

支持并行智能体交接，示例 coordination 配置包含任务名、多个智能体（各自 id、scope、owns 路径、status）、shared_state（已完成与待处理技能）以及 conflict_zones（如 .build/skills-registry.json 同一时间只允许一个智能体刷新，ecosystem.yaml 需协调更新）。

冲突预防定义所有权规则：exclusive（仅一个智能体修改该路径）、append_only（多个可添加、不可修改已有）、coordinator_only（仅协调者智能体修改）。并提供 check_conflict 函数示例，检查某智能体是否与其它智能体拥有的路径冲突。

交接触发条件

触发条件	动作
上下文窗口占用 80%	开始压缩，准备交接
任务阶段完成	在阶段边界写交接文档
错误超过阈值	交接并附错误日志与已尝试修复
时间临近限制	保存状态并生成下一步行动列表
用户显式请求	完整交接所有上下文

恢复模式

从不完整交接恢复的协议：读取最后交接文档；验证当前文件系统状态与“当前状态”一致；若不一致，查看 git log 了解交接后的变更；重新验证关键决策是否仍成立；从“下一步行动”继续。

从缺失交接冷启动的协议：读取计划文件（.claude/plans/*）；检查 git log 了解近期会话活动；盘点现有内容与计划要求的差距；根据文件存在情况推断当前进度；继续前请用户确认。

使用方式

资料中未提供具体的安装命令或调用方式，仅提供了交接文档模板、压缩函数示例、协调配置示例和冲突检查函数示例。

适用场景

适用于需要跨会话延续的 AI 智能体工作，尤其是多智能体并行协作、任务阶段边界、上下文接近上限、错误频发或时间受限的场景。

限制与反模式

资料列出的反模式包括：不写交接文档（每个可能延续的会话都必须产出一份）；交接不含决策（原始状态没有理由则无用）；过度压缩上下文（宁可冗长也不要丢失关键上下文）；仅写入文件而不在对话中同步（用户需要可见性）；缺少冲突区（并行智能体会破坏共享状态）；假设上下文连续（会话开始时始终验证状态）。