119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
|
# 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} 任务"
|
|||
|
|
```
|