# Session Handoff Protocol - AI Reference v3.0 (Spec-Driven Aligned)

> 面向“规范驱动 + 接口先行”体系的会话接续协议。
> 核心目标：在多窗口、长任务场景下，通过单文档（Progress）实现 80% 上下文恢复。

---

## 🎯 核心目标
跨会话任务延续 = 读取 Progress 文档 + 引用模块 Spec 目录 = 立即开始工作。

---

## ⚡ 触发条件（硬门禁阈值）

当满足以下 **任一** 条件时，AI **必须** 启用本协议并维护进度文档：

| 维度 | 触发阈值（必须启用） | 目的 |
| :--- | :--- | :--- |
| **子任务数** | `spec/<module>/tasks.md` 中子任务 ≥ 5 个 | 避免长列表任务丢失状态 |
| **文件变更** | 预计或已修改文件数 ≥ 10 个 | 追踪改动范围，防止遗漏 |
| **工具调用** | 单个会话内工具调用次数 ≥ 40 次 | 应对上下文堆积导致的智能下降 |
| **上下文质量** | 用户反馈或 AI 自检发现明显的指令偏移 | 强制重置上下文并对齐 SSOT |

---

## 📋 进度文档强制清单（YAML 格式）

进度文档路径：`docs/progress/{module}-{feature}-progress.md`

```yaml
# 进度文档必须包含的字段（不可缺失）

context:
  module: "{module_name}"        # 对应 spec/<module>/ 目录名
  feature: "{feature_id}"       # 对应 requirements.md 中的 feature_id
  status: [🔄进行中 | ⏳待开始 | ✅已完成]

spec_references:
  # 必须引用模块 Spec 目录下的 SSOT 文档
  requirements: "spec/{module}/requirements.md"
  openapi_provider: "spec/{module}/openapi.provider.yaml"
  openapi_deps: "spec/{module}/openapi.deps.yaml"
  design: "spec/{module}/design.md"
  tasks: "spec/{module}/tasks.md"

overall_progress:
  format: "- [ ] Phase X: 名称 (进度%) [关联 Tasks.md ID]"
  min_phases: 3
  max_phases: 6

current_phase:
  goal: "一句话描述本阶段目标"
  sub_tasks:
    - [x] 子任务 A (✅) [Task ID]
    - [ ] 子任务 B (🔄) [Task ID]
  
  next_action:
    immediate: "下一步立即执行的具体原子任务"
    details:
      file: "path/to/file.ext:line_number"
      action: "具体做什么（如：实现 XXX 接口的校验逻辑）"
      reference: "参考文件及行号"
    constraints: "执行此任务必须注意的硬约束（如：必须符合 AC-REG-01）"

technical_context:
  module_structure: "本次任务涉及的核心目录/文件"
  key_decisions:
    - decision: "技术决策内容"
      reason: "为什么这么做"
      impact: "对后续任务的影响"
  code_snippets: "关键实现代码或 Mock 示例（至少 1-2 个）"

session_history:
  - session: "Session #X (YYYY-MM-DD)"
    completed: [任务列表]
    changes: [改动的文件清单]

startup_guide:
  - "Step 1: 读取本进度文档（了解当前位置与下一步）"
  - "Step 2: 读取 spec_references 中定义的模块规范（了解业务与接口约束）"
  - "Step 3: 直接执行 next_action"
```

---

## 🚀 工作规则（CRITICAL）

### 1. 启动模式
- **继续模式**：检查 `docs/progress/` 下是否存在对应模块的进度文档。若存在，Read 文档 → 引用 Spec 目录 → 简短汇报状态 → 直接开始。
- **新建模式**：若满足“触发条件（硬门禁阈值）”任一项（或涉及跨模块并行），必须先创建进度文档，再开始工作。

### 2. 下一步行动（The Gold Rule）
- 禁止输出模糊的下一步（如“继续开发”）。
- **必须**具体到 `文件路径:行号` 和 `原子动作`。

### 3. 停止与交接
- 触发条件：Phase 完成、达到稳定检查点、或工具调用次数过多需同步。
- **动作**：更新进度文档（标记 ✅、更新 🔄、详细记录 `next_action`）、告知用户如何接续。

### 4. 禁止事项
- 禁止编造或假设需求；信息不足必须询问用户，并在 Progress 中记录澄清结果。
- 禁止使用不存在的工具接口名；所有操作应基于当前环境可用工具。

---

## 🎨 响应模板

### 会话结束（产出交接）
```text
已达到阶段性检查点，进度文档已更新：
- 路径: docs/progress/{module}-{feature}-progress.md

当前进度：
✅ {已完成任务}
🔄 当前停留: {具体文件:行号}

下次接续请指令："继续 {module} 的 {feature} 任务"
```