用途:用于协调相互独立的工作流之间的交接(如 skill-editor 交给 programming-pm),发现可用的目标工作流、在传输前校验交接载荷、通过分布式追踪调试多跳交接链,以及为新增或已有技能添加交接支持。
主要能力:提供通用交接 schema v3.0,包含 5 个必需顶层字段(version、schema_type、timestamp、trace_id、source、target、context、payload、meta);采用分层上下文结构:payload.working(约 500 token 内)、payload.session(约 1000 token,可选)、payload.references(约 500 token,可选);提供校验规则、目标工作流发现与分布式追踪参考文档。
使用方式:交接生命周期分为发送方与接收方。发送方确定交接、发现目标、生成 trace_id、构建载荷、估算 token(字符数 / 4)、校验并写入 {session_path}/handoffs/{source}-to-{target}-{timestamp}.json 并记录到 trace.jsonl;接收方读取交接文件、校验 version 为 3.0、提取并传播 trace_id、读取 context.summary 与 context.problem_type、加载 payload.working 后开始处理。生成 trace_id:python3 -c "import uuid; print(uuid.uuid4())",估算 token:wc -c < handoff.json | awk '{printf "Estimated tokens: %d\n", $1/4}'。
适用场景:独立工作流之间的交接协调;不适用于 programming-pm 内部专家交接(用内部 v1.2 schema)、简单的文件传递、单技能调用或单任务内的 agent 团队协调。
限制:这是 v3.0 试点(仅文档 + schema 产物)。token 计数仅为指引式启发估算(字符 / 4,非 tiktoken);schema 校验需手动调用(python3 一行命令);循环交接检测仅为建议性,非自动化;CLI 工具、适配层、注册表同步工具均推迟到 v1.1。token 预算为 2000,超额需压缩。