会话交接台 (Session Handoff)

AI 对话从此不再"翻篇"——上一段聊到哪、决定了什么、下一步做什么， 一份文档带走，新对话 30 秒接续。

一、定位

把"对话"变成"文档+对话"的混合工作流。
当上下文使用率逼近上限、任务进入里程碑、或者需要切换子任务时， 生成一份结构化交接文档 (handoff.md) + 一段启动提示词，让你在新会话中无缝接续。

与同类工具的关系：

互补关系，不是替代关系。建议组合使用：会话交接台（事中）→ 复盘（事后）→ 记忆固化（跨周）。

二、何时使用

早比晚好。60% 黄金交接点，80% 已偏晚。

主动建议规则（AI 自动识别）

AI 在满足以下条件时，温和建议用户交接（非强制）：

行为约束：

• 每段自然对话最多建议 1 次
• 用户说"不用"/"暂时不用"后，本次会话不再重复建议
• 建议语气用"建议"而非"应该"，降低打扰感

静默模式

用户可随时说"不要主动建议"或"静默模式"，AI 此后不再主动建议，仅响应用户明确触发词。

三、SOP：5 步标准流程

Step 1：扫描当前会话（10 类信息）

提取以下信息（按顺序）：

1. 项目身份：名称、描述、平台、版本、技术栈
2. 决策链：选了什么、否了什么、为什么
3. 数据流：输入→处理→输出
4. 能力边界：能做什么、不能做什么
5. 代码变更：本次改了哪些文件、为什么
6. 平台状态：GitHub/ClawHub/npm/PyPI 状态
7. 环境配置：哪些 env 已设、哪些待配置
8. 知识文件：docs/knowledge 和 docs/rules 索引
9. 用户偏好：语言、风格、安全敏感度
10. 可分叉方向：下一步能做什么 + 前置条件 + 复杂度

WorkBuddy 专属额外扫描（如可用）：

• SOUL.md / IDENTITY.md / USER.md
• MEMORY.md + 每日日志
• ~/.workbuddy/skills/ 技能列表
• 自动化/cron 任务
• IMA 知识库 ID、飞书通道
• MCP 连接器状态

Step 2：生成交接文档

输出位置（按平台区分）：

使用模板：templates/handoff-template.md

关键规则：

• ❌ 不含真实姓名、邮箱、具体路径、token、密钥、IP
• ✅ 用通用占位符：<项目名>、<负责人>、<仓库地址>
• ✅ 文档必须是可复用模板，不是一次性快照

Step 3：清单验证

对照 references/checklist.md 交叉检查。
12 大类 40+ 项，每项必须覆盖；不适用的写 N/A + 原因。

Step 4：生成启动提示词

使用模板：templates/startup-prompt.md

必须包含：

1. 新 AI 要读的精确文件路径（绝对/相对）
2. 三步启动流程：Load（加载）→ Report（报告）→ Ask（询问）
3. 明确角色："这是已有项目的延续，不是从零开始"

Step 5：呈现给用户

按以下顺序呈现：

1. 交接文档关键章节摘要（3-5 句话）
2. 启动提示词（可直接复制粘贴）
3. 创建的文件清单（含路径）
4. 询问："准备好打开新对话了吗？"

四、隐私与安全

所有生成内容必须先过 references/privacy-rules.md 审查。

核心原则：

• 🔒 端侧优先：默认本地存储，不上传云端
• 🔍 自动脱敏：姓名/邮箱/手机/身份证/路径/token/密钥/IP
• 🛡️ 占位符化：所有敏感信息用 <...> 包裹
• 📦 模板可复用：避免"一次性快照"导致模板腐烂

五、与其他工具的组合

会话交接台（事中分叉） → 对话复盘（事后总结） → 记忆固化（跨周沉淀）
              ↓                    ↓                    ↓
        30 秒新对话接续      方法论沉淀          长期知识库

详见 docs/composition.md

六、最小可运行示例

触发：

"开个支线，我把代码改到一半，要切到写文档"

AI 响应（节选）：

✅ 已生成交接文档：.workbuddy/session-handoff.md
✅ 已生成启动提示词：复制以下内容到新会话

## 关键摘要
本会话在做「票根经济论文 + 数字化系统」，
已完成第 3 章初稿，代码部分改到 src/ticket/parser.py 第 47 行。
下一步要切到 README 撰写。

## 启动提示词
请按以下流程开始：
1. **Load**：读取 `.workbuddy/session-handoff.md`
2. **Report**：用 3 句话总结项目状态
3. **Ask**：等待我确认后再开始工作

详见 examples/ 下的 4 大类完整案例。

七、失败模式与处理

模式判断流程

用户触发"session handoff"
       ↓
  对话轮次 ≥ 5？
       ↓
   No → 提示"先聊够 5 轮"
       ↓
  Yes → 是工作型对话？
       ↓
   No → 轻量模式（3 节）
       ↓
  Yes → 上下文使用率 ≥ 80%？
       ↓
  Yes → 快速模式（4 节必填 + 其余 N/A）
       ↓
  No  → 标准模式（12 节全量）

八、版本与贡献

• 当前版本：v1.2.0（2026-06-13）- 10+ 国产 AI 平台深度适配版
• 许可证：MIT-0（可商用、无限制）
• 贡献指南：CONTRIBUTING.md
• 变更日志：CHANGELOG.md
• 平台适配指南：docs/platforms/README.md

九、参考

• 原始灵感：session-branch (v1.1.0)
• 本地化扩展：10+ 国产 AI 平台适配 + 4 大场景案例库
• 中文化策略：docs/i18n-strategy.md