Handoff - 全局跨会话/跨Quest协作协议

本 skill 为全局规则，适用所有项目，不绑定特定技术栈或仓库。

功能一：启发式任务接收（接收方）

当任务 prompt 或上下文中包含 "Task Handoff Context" 结构时，执行以下协议：

Step 1: 识别 Handoff（秒级）

• 检测任务中是否包含结构化的 Handoff Context（含"项目快照""目标任务""最快实现路径"段落）
• 若包含 → 跳过 Step 2-3，直接按"最快实现路径"中的步骤执行
• 若不包含 → 继续 Step 2

Step 2: 解析意图 + 关键词映射

• 提取任务中的：动词（新增/修改/修复/删除）+ 名词（模块/表/API/事件/页面）
• 判断任务类型：新功能 / Bug修复 / 重构 / 配置变更
• 若项目有 AGENTS.md 中的"模块关键词速查表" → 查表定位 crate/文件/表
• 若无速查表 → 从任务描述中提取文件路径关键词，精确 Grep 定位

Step 3: 按需读取（最小集原则）

• 只读：被修改的目标文件 + 直接依赖的接口定义
• 不读：无关模块、通用配置文件、测试文件（除非任务明确要求）
• 禁止：技术栈确认、项目结构遍历、Hello World 测试、全量 list_dir

Step 4: 执行

• 完成定位后立即开始实现
• 执行过程中发现缺失信息 → 精确补读单个目标文件，不回退到全量探索
• 每次 Read/Grep 前先明确："我需要从这个文件获取什么信息"

功能二：Handoff 自动生成（发送方）

触发条件

以下任一场景均触发自动生成：

场景 A：用户主动传递 用户消息中同时包含：

• 目标路径指示词（"写到""传给""放到""输出到"）+ 具体文件地址
• 内容指示词（"方案""思路""结论""计划""调研结果"）

场景 B：审查/审计/调研完毕后生成 用户消息中包含：

• 完成指示词（"审查完毕""审计完成""调研结束""分析完了""review done"）
• 交接指示词（"生成handoff""输出交接文档""写handoff""交接给下个会话"）
• 可选：目标文件路径（若未指定，询问用户或输出到当前项目根目录的 handoff.md）

执行流程

1. 从当前会话上下文中提取：调研结论、方案决策、实施路径、已发现问题、踩坑经验
2. 按下方模板填充所有字段（不允许留占位符）
3. 将填充后的完整内容写入目标文件（路径规则见下方「文件路径约定」）
4. 无需用户额外确认格式
5. 写入完成后，必须输出「下游触发提示词」（见下方）

文件路径约定

Handoff 文件统一存放在项目 _handoffs/ 目录下，命名规则：

_handoffs/{日期}_{主题}-{序号}.md

示例：

• handoffs/20260621scheduling-optimization-01.md
• handoffs/20260621scheduling-optimization-02.md（第二轮修改后）

若 _handoffs/ 目录不存在，自动创建。

绝对路径强制规则：凡向用户交付/展示文件地址的场合——下游触发提示词、回复正文、Metadata 表、审查发现的"涉及文件"列——必须给出完整绝对路径（如 /Users/allen/Coding/project/handoffs/20260621xxx-01.md），禁止只写 _handoffs/xxx.md 这类相对路径：接收方在新 Quest 中无上下文，相对路径无法直接定位。仅模板内部的目录约定描述（即本节的命名规则）允许用相对形式书写。

下游触发提示词（强制输出）

Handoff 文件写入成功后，必须在回复末尾输出以下提示词块，供用户直接复制到下一个 Quest：

---
请读取以下Handoff方案文件并进行杠精审查：

{/项目根目录/_handoffs/文件名.md  ← 完整绝对路径}

请调用 /杠精审查 对该方案进行七维度对抗性审查，输出审查报告。
---

此提示词中的文件路径必须替换为实际写入的完整绝对路径。用户复制整段（--- 之间）粘贴到新 Quest 即可触发杠精审查。

输出模板

# Task Handoff Context

## 1. 项目快照 (Project Snapshot)

| 字段 | 值 |
|------|-----|
| 技术栈 | {当前项目技术栈一行概述} |
| 架构模式 | {架构一行概述} |
| 后端入口 | {关键入口文件路径，无则填 N/A} |
| 前端入口 | {前端入口路径，无则填 N/A} |
| 构建命令 | {编译/测试/运行命令} |
| 测试命令 | {测试命令} |

## 2. 目标任务 (Target Task)

- **意图**：{一句话描述}
- **任务类型**：{新功能/Bug修复/重构/配置变更/性能优化}
- **涉及模块**：{具体模块/包名 + 路径}
- **涉及文件**（按修改优先级排序）：
  1. `{path}` — {说明}
  2. `{path}` — {说明}
- **前置结论**：{本轮已确认的事实，避免接收方重复探索}
- **不涉及**：{明确排除的模块/文件，防止误触}

## 3. 最快实现路径 (Fastest Path)

### 步骤
1. **{文件路径}** — {具体行为}
2. **{文件路径}** — {具体行为}

### 已知陷阱
- {具体避坑点，来自本轮实际经验}

### 依赖约束
- {前置依赖}

## 4. 验收标准 (Acceptance Criteria)

- [ ] {可验证条件1：具体命令 + 预期输出}
- [ ] {可验证条件2}

## 5. 上下文传递元数据 (Metadata)

| 字段 | 值 |
|------|-----|
| 来源会话/Quest | {标识} |
| 生成时间 | {ISO 8601} |
| 关联 memory | {相关 memory title，便于接收方 recall} |
| 剩余风险 | {已知但未解决的问题} |

填充要求

• 所有字段必须是具体值，不允许留占位符 {...}
• "涉及文件"必须是真实存在的完整绝对路径（通过工具验证），禁止相对路径
• "最快实现路径"必须是可直接执行的步骤（不是笼统描述），其中引用的文件路径同样用完整绝对路径
• "已知陷阱"必须包含本轮发现的所有避坑点（来自实际踩坑，不是猜测）
• "验收标准"必须是可验证的具体条件（如命令 + 预期输出）
• "前置结论"必须包含本轮调研/审查中确认的关键事实

功能三：审查/审计后的 Handoff 增强

当 handoff 由审查/审计任务触发时，除标准模板外，还需额外填充：

附加段落（追加到模板末尾）

## 6. 审查/审计发现 (Review Findings)

### 已确认问题
| 序号 | 问题描述 | 严重程度 | 涉及文件（完整绝对路径） | 建议处理方式 |
|------|---------|---------|---------|------------|
| 1 | {问题} | 高/中/低 | {完整绝对路径} | {建议} |

### 已修复项
- {本轮审查中直接修复的问题}

### 遗留项（需后续处理）
- {需要后续会话/Quest处理的问题}

### 代码质量评估
- 整体健康度：{优/良/中/差}
- 关键风险点：{列表}
- 建议优先级：{下一步应该先做什么}

此段落仅在审查/审计场景下追加，普通方案传递场景不需要。

功能四：审查后修改协议（接收审查报告方）

当收到的任务中包含「审查报告」路径 + 「原方案」路径时，执行以下流程：

执行步骤

1. 读取审查报告：读取审查 Handoff 文件，提取所有高危/中危/待澄清问题
2. 读取原方案：读取原方案 Handoff 文件
3. 决策：

- 高危问题 > 0 → 必须修改原方案，输出修改后的 Handoff V2 - 高危问题 = 0 且中危问题 > 0 → 建议性修改，输出修改后的 Handoff V2 - 高危问题 = 0 且中危问题 = 0 → 无需修改，跳过此步，直接输出最终 HTML 报告

1. 修改原方案（如需要）：

- 在 Handoff V2 中明确标注每个审查问题的对应修改 - 在 Metadata 中标注「基于审查报告修改」+ 审查报告完整绝对路径

1. 写入文件：将修改后的 Handoff V2 写入 _handoffs/ 目录
2. 输出下游触发提示词（见下方）

文件命名

_handoffs/{日期}_{主题}-{序号+1}.md

示例：原方案是 01，修改后为 02。

下游触发提示词（强制输出）

修改后 Handoff 写入成功后，输出以下提示词供用户复制到新 Quest：

---
请读取以下修改后的方案并输出最终HTML报告：

{/项目根目录/_handoffs/修改后文件名.md  ← 完整绝对路径}

审查报告：{/项目根目录/_handoffs/审查报告文件名.md  ← 完整绝对路径}

请根据修改后的方案生成最终 HTML 交付报告，输出到 _reports/ 目录。
---

无需修改时

如果审查报告无高危/中危问题，直接输出：

---
审查通过，无需修改。请读取以下方案并输出最终HTML报告：

{/项目根目录/_handoffs/原方案文件名.md  ← 完整绝对路径}

请根据方案生成最终 HTML 交付报告，输出到 _reports/ 目录。
---

禁止行为清单

无论接收还是发送，以下行为始终禁止：

1. 全量 list_dir 项目根目录来"了解项目结构"
2. 读取与任务无关的文件来"确认技术栈"
3. 打印 Hello World 或任何测试性输出
4. 在已有明确路径时仍做广域 Grep 搜索
5. 重复确认已在 Handoff 中明确的信息
6. 输出冗长的文件内容摘抄（给结论，不给原文）
7. 在模板中留占位符 {...} 而不填充实际值
8. 将未经实际验证的路径写入"涉及文件"
9. 向用户交付文件地址时只给相对路径（如 _handoffs/xxx.md、src/xxx.rs）而不给完整绝对路径