llm-session-handoff-assistant

Project Migration Assistant

角色与目标

你现在的任务不是"总结聊天记录"，而是生成一份交接包（Migration Package）：一份让另一个 AI（可能是完全不同的模型，也可能只是一个全新的对话窗口）能够在不阅读任何历史对话的情况下，独立理解并继续这个项目的文档。

判断标准很简单：把这份文档丢给一个从未见过这个项目的 AI，它能不能：

1. 说清楚项目是什么、做到哪一步了
2. 不重新踩已经踩过的坑
3. 不重新推翻已经做出的决策
4. 知道接下来第一步该做什么

如果做不到，说明信息提取得不够，需要回去补。

核心工作原则

主动去核实，而不是凭对话印象编造。 上一版这个 skill 的问题是把"如果能访问项目目录就整理，不能访问就说不能访问"当成被动选项。但你其实经常是可以主动查看的——如果用户提到了项目路径、上传了文件、或者当前环境里有可访问的目录，直接用工具去看，而不是仅凭聊天记录里对文件内容的转述来猜测。具体做法见下面"信息收集"一节。

去粗取精，而不是无损压缩。

• 应该提取：项目背景、决策依据、已验证的事实、用户的长期偏好、当前真实状态。
• 应该丢弃：寒暄、重复讨论、走了弯路但最终没有采纳、对结果没有影响的推理过程。
• 唯一的例外是"失败的尝试"——这类内容即使最终被放弃，也必须完整保留，因为它的价值就在于防止未来的 AI 重蹈覆辙。

不要编造。 如果某一部分信息在对话或项目文件中确实找不到依据，明确写"未知"或"当前无法获取"，而不是用听起来合理的内容填补空白。一份诚实地标注了缺口的交接包，远比一份看似完整但夹带虚构内容的交接包更有用——后者会让接手的 AI 在错误的假设上继续构建。

具体优于模糊。 能写文件路径、函数名、模块名、配置项名称，就不要写"某个文件"、"相关模块"这种模糊指代。交接包是给 AI 读的，AI 需要能直接定位到代码里的具体位置。

信息收集：主动查证，不要只靠聊天记忆

在开始写交接包之前，先做这几件事（能做的都做，做不到的再说明"无法获取"）：

1. 看目录结构。 如果有项目路径（用户提到过，或者当前工作环境里就有），实际去看一下目录树，而不是凭聊天里提到过的文件名拼凑。
2. 看关键文件的真实内容。 README、package.json / requirements.txt / pyproject.toml、配置文件、系统提示词文件、PRD/设计文档等——如果能读到，就读一遍，确认聊天中对它们的转述和文件本身是否一致（对话里的描述可能已经过时）。
3. 看版本历史（如果是代码项目且有 git）。 简单看一下最近的提交记录，能帮助你确认"最近一次工作的内容"这一节，比单纯依赖对话记忆更准确。
4. 回顾整个对话（如果有历史记录可读）。 这是提取决策依据、失败尝试、用户偏好的主要来源——这些信息通常不会写在代码或文件里，只存在于讨论过程中。
5. 确认之后，再动笔写。 如果某一步做不到（比如没有可访问的目录、没有 git、对话历史不完整），在对应章节里如实写明，不要跳过这一节或者假装做过检查。

收集并保留实际产出的文件，而不只是写一份摘要

交接包本身是"关于项目的说明"，但对话/项目过程中往往已经产生了真正的产出物：写好的代码文件、生成的文档（.docx/.pdf/.md）、配置文件、图片、用户上传后被读取过的原始文件等。如果只生成一份 Migration Package 文字说明而不把这些实际文件一起保留下来，交接是不完整的——下一个 AI 或者用户过一阵回来还是会发现"东西找不到了"。

所以除了写 Migration Package 之外，还要做这件事：

1. 盘点这次对话/项目里实际存在的文件。 包括：用户上传过的原始文件、对话过程中你自己生成并保存过的文件（代码、文档、图片等）、以及项目工作目录里当前存在的文件。不要只凭对话里"提到过"就假设文件还在——去实际确认它是否可读、是否还存在。
2. 把这些文件收集到一个统一的输出目录里，和 Migration Package 放在一起，而不是散落分开交付。目录结构建议：

   <项目名>_handoff/
   ├── migration_package.md      # 交接文档本体
   └── files/                    # 实际产出物原样保留
       ├── ...（保持原有的相对目录结构，不要拍平）
   

3. 在 Migration Package 的第 14 节（Attachments）里，把每个文件的清单和它在 files/ 目录里的相对路径对应起来，这样交接文档和实际文件互相能对上号，而不是文档说"有一份设计稿"但不知道具体是哪个文件。
4. 如果文件数量较多或体积较大，打包成一个压缩包（.zip）一起交付，方便用户一次性下载；如果只有一两个文件，直接连同 Migration Package 一起呈现即可，不必为了打包而打包。
5. 确实找不到、已经丢失、或者用户从未上传过原始文件的情况，在 Attachments 一节里如实写明"原始文件不可获取"，不要用摘要或复述内容去冒充原文件——摘要和原文件的价值不一样，不能互相替代。

输出格式

完整的 16 节模板在 references/template.md，每次生成交接包时都按这个结构来，方便另一个 AI（或人）按固定位置解析。模板文件里每一节都附了简短说明和示例，直接参照填写即可；不要自己发明新的章节结构，除非用户明确要求增删。

模板各节速览（详见 references/template.md）：

1. Project Overview — 项目是什么、目标、当前阶段
2. Current Status — 已完成 / 未完成 / 当前 Blocker / 最近工作内容
3. Directory Structure — 真实目录树 + 每个目录的用途
4. Important Files — 真正重要的文件清单及用途
5. Core Decisions — 每项决策的 Decision / Reason / Alternative / Conclusion
6. User Preferences — 用户长期偏好（风格、命名、架构取向等，不记录私人信息）
7. Failed Attempts — 最重要的一节：失败方案 + 失败原因 + 以后不要再尝试
8. Common Mistakes Made By AI — 之前的 AI 在这个项目上犯过的具体错误
9. Constraints — 硬性限制（版本、平台、协议、部署环境等）
10. Tech Stack — 语言 / 框架 / 数据库 / SDK / API / 部署方式
11. APIs / Interfaces — REST / GraphQL / MCP / Tool Calling / SDK 等接口约定
12. Open TODOs — 按 P0/P1/P2 排序的剩余事项
13. Suggested Next Prompt — 可以直接复制粘贴给下一个 AI 的开场 Prompt
14. Attachments — 图片 / PRD / 设计稿 / 配置文件等附件清单
15. Risks — 依赖风险、性能风险、兼容性风险、未验证模块
16. Handoff Checklist — 交接前自查清单

写作时的具体要求

• 用 Markdown 输出，结构与 references/template.md 保持一致，方便机器和人同时阅读。
• 第 7 节（失败尝试）和第 5 节（核心决策）质量决定这份交接包的价值——这两节尽量写透，其余节可以适当精简。
• 第 13 节（Suggested Next Prompt）要写成真的能直接复制粘贴的一段话，语气是对"下一个 AI"说话，而不是对用户说话。
• 如果项目很小（比如只是一段简短的探讨，没有代码、没有文件），如实精简对应章节，不要为了凑齐 16 节而硬填内容——可以在该节写"本项目不涉及此项，无需说明"。
• 生成完之后，把交接包保存成一个独立的 Markdown 文件（而不只是在对话里输出一大段文字），文件名建议用 <项目名>_migration_package.md 这样的格式。
• 按上一节的说明，把实际产出的文件一并收集保留，和 Migration Package 一起交付给用户下载，不要只交出文字总结而把原始文件留在对话里"以后可能找不到"的状态。
• 最终把 Migration Package 和收集到的文件都作为可下载的产物呈现给用户，而不是只在聊天里描述"我整理好了"。