ai-robot-core/docs/session-handoff-protocol.md

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

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

context:
  module: "{module_name}"        # 对应 spec/<module>/ 目录名
  feature: "{feature_id}"       # 对应 requirements.md 中的 feature_id
  status: [🔄进行中 | ⏳待开始 | ✅已完成]
  version: "0.3.0"              # 当前迭代版本号
  active_ac_range: "AC-MOD-21~30"  # 当前活跃的 AC 编号范围

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"

  # 版本化迭代信息（从 requirements.md frontmatter 读取）
  active_version: "0.2.0-0.3.0"  # 活跃版本范围（仅关注这些版本的 AC）

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 目录 → 简短汇报状态 → 直接开始。
• 新建模式：若满足”触发条件（硬门禁阈值）”任一项（或涉及跨模块并行），必须先创建进度文档，再开始工作。
• 版本化迭代模式：
  • 读取 requirements.md 的 frontmatter，识别 active_version 和 version
  • 在进度文档中记录 active_ac_range（如 AC-AISVC-91~110）
  • 仅关注活跃版本的 AC，历史版本（折叠在 <details> 中）可跳过

2. 下一步行动（The Gold Rule）

• 禁止输出模糊的下一步（如“继续开发”）。
• 必须具体到 文件路径:行号 和 原子动作。

3. 停止与交接

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

4. 禁止事项

• 禁止编造或假设需求；信息不足必须询问用户，并在 Progress 中记录澄清结果。
• 禁止使用不存在的工具接口名；所有操作应基于当前环境可用工具。
• 禁止引用历史版本（已折叠）的 AC 编号；所有代码/测试/提交必须引用活跃版本的 AC。

5. 版本化迭代支持

• 读取版本信息：启动时从 requirements.md frontmatter 读取 active_version 和 version_history
• 聚焦活跃版本：仅关注活跃版本范围内的 AC（如 0.6.0-0.7.0），历史版本可跳过
• AC 编号连续性：新迭代的 AC 编号延续上一版本（如 AC-AISVC-90 → AC-AISVC-91）
• 进度文档同步：在 context.active_ac_range 中记录当前迭代的 AC 范围，便于快速定位

---

🎨 响应模板

会话结束（产出交接）

已达到阶段性检查点，进度文档已更新：
- 路径: docs/progress/{module}-{feature}-progress.md

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

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