| name | handoff-protocol |
| description | 定义工作流间的交接协议时使用。适用于多工作流协作项目、避免交接质量问题。优先使用"产物 + 上下文 + 验收标准"三要素 + 各工作流的具体交接清单。 |
工作流交接协议
参考来源：Agent Handoff Patterns、Skywork Best Practices for Handoffs
适用场景
- 多工作流协作项目
- 避免交接质量问题导致返工
- 跨阶段交付（设计→开发→测试→上线）
核心原则
交接是项目失败的高发区。
"reliability lives and dies in the handoffs"
（多 Agent 系统的可靠性，全在交接环节）
每次交接质量决定下游工作流的执行成本。
交接做好了，下游不用猜；做不好，整个项目要返工。
交接三要素
每次工作流交接必须包含：
1. 产物（Artifact）
- 上游工作流的具体输出文件/文档/代码
- 格式和位置明确
- 可以被下游直接使用
2. 上下文（Context）
- 为什么这样做
- 做了哪些决策、为什么这样决策
- 有哪些已知限制或风险
- 下游需要注意什么
3. 验收标准（Acceptance）
- 下游如何判断上游产物质量合格
- 不合格时的退回机制
- 退回后的修复责任归属
常见交接点和产物清单
产品经理 → 项目经理
□ PRD（含 14 节标准结构）
□ 功能清单 + 优先级
□ 验收标准
□ 风险清单
□ 未决问题
上下文：业务目标、用户场景、非目标范围
验收：项目经理能据此拆出任务列表
项目经理 → API 设计
□ 功能清单（含优先级）
□ 业务实体清单
□ 权限要求
□ 异常场景清单
上下文：哪些接口优先、前端需要什么数据
验收：API 设计师能据此输出 OpenAPI 文档
项目经理 → UI/UX 设计
□ 用户角色和场景
□ 核心流程清单
□ 页面目标
□ 状态说明（loading/error/empty）
上下文：用户旅程关键节点、设计约束
验收：设计师能据此输出页面结构和交互方案
API 设计 → 前端 + 后端
□ OpenAPI 文档
□ Mock 服务地址
□ 错误码表
□ 鉴权方式说明
上下文：哪些字段必填、分页策略、版本兼容
验收：前后端能据此独立开发且联调时字段一致
UI/UX 设计 → 前端
□ 页面清单 + 用户流程
□ 组件清单 + 状态说明
□ 交互规则
□ 响应式规则
□ 可访问性要求
上下文：设计意图、用户场景、品牌约束
验收：前端能据此拆出任务列表，不需要猜测任何状态
后端 → QA
□ 接口代码 + 接口说明
□ 测试账号和数据
□ 异常场景清单
□ 权限矩阵
上下文：核心路径、已知限制
验收：QA 能据此设计测试用例并执行
QA → DevOps
□ 测试报告
□ Bug 修复确认
□ 已知风险清单
上下文：测试覆盖范围、未覆盖场景、环境要求
验收：DevOps 确认可以进入部署流程
DevOps → SRE
□ 部署文档
□ 健康检查端点
□ 监控配置
□ 回滚方案
上下文：部署架构、依赖服务、流量预估
验收：SRE 能据此接管运维
交接质量自检
交接前问自己：
□ 如果我是下游工作流，拿到这份材料能直接开始工作吗？
□ 有没有需要猜测的地方？
□ 有没有遗漏的异常场景？
□ 验收标准是否可测试？
□ 未决问题是否标注清楚？
交接失败处理
当下游工作流发现上游产物不可用时：
1. 明确标注问题（缺什么、哪里不对）
2. 退回给上游工作流（状态变为 rework）
3. 项目经理评估影响：
- 是否影响关键路径
- 是否需要调整后续计划
- 是否需要增加缓冲
4. 上游修复后重新交接
5. 记录到 field-journal（避免下次同样问题）
工作流程
1. 识别项目中的所有交接点
↓
2. 对每个交接点：
a. 列产物清单（来自上游）
b. 列上下文要点（决策背景）
c. 定义验收标准（下游怎么判断合格）
↓
3. 输出交接计划
↓
4. 项目执行中，每个交接发生时验证三要素
↓
5. 交接失败 → 走失败处理流程
输出格式
## 交接计划
### 交接点 1: 产品经理 → API 设计
**产物**：
- PRD v1.2（docs/prd-v1.2.md）
- 业务实体清单（docs/entities.md）
- 权限矩阵（docs/permissions.md）
**上下文**：
- 优先支持订单和支付，暂不支持退款
- 多租户隔离要求（每个商家独立）
- 审计日志要求
**验收标准**：
- API 设计师能据此输出至少 8 个核心端点
- 不需要再向产品经理询问
- 未决问题清单 ≤ 3 条
### 交接点 2: API 设计 → 前端 + 后端
...
常见坑
- 只传文件不传上下文——下游不知道为什么这样做
- 没有验收标准——下游拿到垃圾输入只能硬做
- 交接清单不完整——漏了关键产物
- 退回机制不明确——发现问题不知道找谁
- 上下文写成废话——"按 PRD 实现"等于没说
- 未决问题不标注——下游开始做才发现没法做
- 交接是单向的——没有让下游确认理解
配套模板
templates/handoff-plan-template.md — 单次交接 + 完整项目交接计划 + 交接质量自检清单
与其他 skill 的协作
上游：
wbs-decomposition → 提供任务和工作流分配
orchestration → 提供编排模式
下游：
progress-tracking → 追踪交接状态
change-control → 变更时通知所有交接相关方
