project-handover

触发条件

本 Skill 存在两种触发方式：

主动触发

当用户说出以下任一关键词时触发：

• "打包"
• "交接"
• "整理项目"

用户主动触发时，直接进入第一步（前置检查）。主动触发进入第二步时，AI 自动判定为"用户确认打包"，不显示询问，直接传递确认状态至第三步。

主动提醒触发

当用户说出会话结束信号时触发提醒判定。会话结束信号包括但不限于：

• "明天见"、"下次见"、"先走了"、"下班了"
• "换电脑了"、"换个设备"、"换个环境"
• "今天先到这"、"先这样"、"收工"

触发后进入第二步（主动提醒判定）。

执行流程（七步走）

以下七步为串行流程，任何一步失败或终止则不进入下一步。

第一步：前置检查

输入：当前工作目录

执行：

1. 识别项目根目录：
   - 优先使用当前工作目录。
   - 若当前工作目录不含项目特征文件，向上查找包含 .git、package.json、README.md 中任一文件的最近父目录作为根目录。
   - 若无特征文件且用户无法提供根目录，使用当前工作目录，并在自检报告中标注：⚠️ 根目录基于当前工作目录推断，如有误请手动调整。

2. 检查目标磁盘空间：
   - 判断归档目录所在磁盘是否有足够空间存放交接档案。
   - 若空间不足，终止执行，告知用户："磁盘空间不足，请清理或更换路径后重试。"

3. 检查写入权限：
   - 判断项目根目录下是否可创建目录和写入文件。
   - 若无写入权限，终止执行，告知用户："当前目录无写入权限，请更换路径或调整权限后重试。"

输出：确认的项目根目录路径

失败处理：任一检查项不满足，终止流程，向用户报告具体原因。

第二步：主动提醒判定

输入：用户发出的会话结束信号（或主动触发的自动确认状态）

执行：

1. 向用户询问："检测到您即将结束会话，是否需要打包项目交接档案？"

2. 根据用户回复执行判定：
   - 用户确认打包（说"好"、"需要"、"打包吧"等，或由主动触发自动确认） → 进入第三步（敏感信息预扫描）。
   - 用户明确拒绝（说"不用"、"不需要"、"不用了"等） → 记录拒绝状态，本会话内不再提醒，流程结束。
   - 用户未回复或转移话题 → 视为未明确拒绝，不记录拒绝状态，下次触发条件满足时可再次提醒，流程结束。

同会话拒绝记忆规则：
- 明确拒绝后，在当前对话上下文中记住拒绝状态，后续任何会话结束信号不再触发提醒。此记忆依赖当前对话上下文，若开启新会话则失效。

优先级：若用户直接指令"打包"等关键词，走主动触发流程，与主动提醒互不干扰。

输出：用户确认打包 → 进入第三步；用户拒绝或忽略 → 流程结束

失败处理：无失败场景，仅判定分支。

第三步：敏感信息预扫描

输入：确认的项目根目录

执行：

1. 全量扫描项目文件（含大文件，不因文件大小跳过扫描）：
   - AI 基于文件名、扩展名和目录名初步识别敏感文件，包括但不限于：.env 文件、含 config/secret/password/key/token 的文件名、客户资料目录下的文件。若无法确定内容，宁可标记为敏感，由用户确认。
   - 将识别出的文件标记为"敏感文件"，该标记贯穿后续所有步骤，不因用户选择（保留/脱敏/移除）而清除。AI 在内部上下文中维护此敏感文件清单，在第四步、第五步、第六步中引用同一清单。

2. 向用户展示扫描结果，按文件类型提供处理选项：
   - 纯文本文件（可读取和编辑的文件）：提供三个选项 — 保留原样 / 生成脱敏副本 / 移除不打包。
   - 二进制或复杂格式文件（无法可靠脱敏的文件）：仅提供两个选项 — 保留原样 / 移除不打包。
   - 批量处理优化：若敏感文件数量较多（>5个），提供批量选项："以上共 X 个敏感文件，请选择统一处理方式（全部保留/全部脱敏/全部移除/逐个确认）"

3. 记录用户选择，传递给后续步骤。

脱敏操作约束：
- AI 不原地修改源文件。
- 仅对纯文本文件生成脱敏副本，副本放入归档目录。
- 二进制/复杂格式文件不提供脱敏选项。

脱敏失败降级：
- 若脱敏执行失败（如误判文件类型导致生成副本失败），自动降级为"移除"处理。
- 在自检报告中标注：⚠️ [文件名] 脱敏失败，已自动移除，请手动补充。

优先级规则：敏感信息扫描优先级 > 大文件排除优先级。先全量扫描，再排除大文件。若大文件被标记为敏感，自检报告特殊标注：⚠️ 以下文件因超过10MB未打包，但包含敏感信息，请务必手动安全传输：[文件名]

输出：敏感文件清单及用户处理选择

失败处理：扫描过程出错 → 告知用户扫描失败的文件，继续处理其余文件。

第四步：智能复制

输入：项目根目录、敏感文件清单及用户选择

执行：

1. 在项目根目录下创建归档目录：
   - 默认路径：交接档案/YYYY-MM-DD/（日期使用当天日期）。
   - 若该路径已存在 → 追加 HH-MM，路径变为：交接档案/YYYY-MM-DD-HH-MM/。
   - 若秒级冲突 → 追加 HH-MM-SS，路径变为：交接档案/YYYY-MM-DD-HH-MM-SS/。
   - 若磁盘空间不足 → 终止执行并提示用户清理或更换路径。

2. 复制以下 5 类核心文件到归档目录（交接便签预留位置）：

(注：交接便签.md 将在第五步生成并放入此目录，此处仅预留位置)

3. 复制时自动排除以下内容：
   - node_modules、.git、venv、dist、build、__pycache__ 目录
   - 交接档案/ 目录（历史交接档案，防止递归复制到新档案中）
   - 文件大小 ≥ 10MB（10,485,760字节）的单个大文件（必须记录文件名和大小，用于自检报告）
   - 临时文件（.tmp、.log 等）

4. 排除优先级：硬排除规则（≥10MB、.tmp 等）优先执行，剩余文件再按"全部打包"原则处理。

5. 敏感文件处理：按用户在第三步的选择执行：
   - 保留原样 → 正常复制到归档目录。
   - 生成脱敏副本 → 仅将脱敏副本放入归档目录，源文件不复制。
   - 移除不打包 → 不复制该文件。

6. 增量交接检测：
   - 检查项目根目录下是否存在历史交接档案（交接档案/ 目录下其他日期的子目录，排除本次新建的目录）。
   - 若存在历史档案，读取最近一次的交接便签，用于后续增量对比。
   - 若历史档案存在但交接便签丢失或内容损坏无法解析，记录状态：⚠️ 历史交接便签丢失，无法进行增量对比。

7. 若记忆目录 .workbuddy/memory/ 不存在：跳过，在自检报告中标注"⚠️ 未发现 .workbuddy/memory/ 目录"。

8. 若无法判断文件分类（源代码 vs 文档）：全部打包，宁可多打包不漏。

输出：归档目录路径、复制的文件清单、大文件排除清单、敏感文件处理结果、增量对比基础数据

失败处理：复制单个文件失败 → 跳过该文件，在自检报告中标注失败文件名及原因，继续处理其余文件。

第五步：生成交接便签

输入：归档目录路径、项目信息、敏感文件处理结果、增量对比基础数据

执行：在归档目录中生成 交接便签.md，严格按以下模板填写：

# 项目交接便签

## 1. 项目当前状态
[用简洁3-5句话概括项目当前状态，控制在100字以内]

[增量摘要 — 条件渲染，规则见下方]

## 2. 技术栈与运行环境
[例：Python 3.9 + Pandas + OpenPyXL，需在 Conda 环境下运行]
[如有必填的 API Key 或密码，注明在哪个文件中配置]

[敏感信息标注 — 规则见下方]

## 3. 启动/运行命令
[例：python main.py --mode=test，接手方直接复制运行]
[如果是 exe，写双击哪个文件]

## 4. 接下来最重要的事（1-3 件）

<!-- AI指令：如果对话上下文中没有明确提及接下来的任务，绝不可自行推断业务走向，只能写"⚠️ 未明确，请接手方与用户确认" -->
1. [第一件要做的事]
2. [第二件要做的事]

## 5. ⚠️ 绝对不能碰的东西（禁止清单）
[列出绝对不能改的核心规则、已经和客户确认过的部分]
[列出绝对不能删除或覆盖的文件]

## 6. 🪤 已知陷阱与破解方案
[每个陷阱必须写现象+解法，不能让接手的人自己摸索]
[例：
🪤 陷阱：原始输出文件的 Sheet 结构混乱
💊 破解：送货文件 Sheet2 才是汇总，安装文件全是明细]

## 7. 🔧 未完成的技术债（Tech Debt）
[列出因为时间紧迫暂时硬编码或不优雅的地方]
[例：客户名称映射表目前写死在代码第 45 行，后续若客户增加需改为读取配置文件]

## 8. 关键联系人/待反馈事项
[如果有人在等你的东西，这里写上]
[如果已经发给客户确认但还没回复，这里标注清楚]

第 1 节增量摘要条件渲染规则：

• 若存在历史档案且历史便签可读取，在第 1 节末尾追加：

> 📎 上次交接便签：`../YYYY-MM-DD/交接便签.md`
> 📝 本次变更摘要：
>   - 新增：[列出新增内容/无]
>   - 修改：[列出修改内容/无]
>   - 删除：[列出删除内容/无]

增量 diff 判定标准：仅对以下扩展名执行内容对比：.py, .js, .ts, .md, .txt, .json, .yaml, .yml, .html, .css, .sql, .sh, .bat, .cfg, .ini, .conf。其余扩展名视为二进制，不参与内容对比，仅记录文件名新增/删除。若 diff 结果为空，写"本次变更摘要：无实质性变更"。

• 若无历史档案，在第 1 节末尾追加：

📎 首次交接，无历史记录

• 若历史档案存在但便签丢失或损坏，在第 1 节末尾追加：

⚠️ 历史交接便签丢失，无法进行增量对比

第 2 节敏感信息标注规则：

• 若本次交接存在敏感文件，在第 2 节末尾追加以下内容，并在便签底部强制追加安全提示：

⚠️ 敏感信息处理：
  - 以下文件已提供脱敏副本：[列出纯文本脱敏文件，若无则写"无"]
  - 以下文件未打包（应你要求）：[列出移除的文件，若无则写"无"]
  - ⚠️ 提示：请接手方手动复查本项目是否包含其他未脱敏的敏感信息。

便签底部强制追加：⚠️ 提示：本交接包含敏感信息，请接手方手动复查合规性。

• 若本次交接无任何敏感文件，不显示上述标注区块和底部提示，改为在第 2 节末尾追加简化确认：

✅ 本次交接未识别到敏感信息

输出：归档目录中的 交接便签.md 文件

失败处理：便签生成失败 → 告知用户，尝试重新生成一次；仍失败则终止流程。

第六步：自检校验

输入：归档目录内容、敏感文件处理结果、大文件排除清单、增量对比结果

执行：按以下模板输出自检报告：

打包完成，已生成交接档案。
✅ 前置检查通过（根目录/空间/权限）
✅ 核心代码文件 X 个
✅ 记忆文件 X 个（或 ⚠️ 未发现 .workbuddy/memory/ 目录）
✅ 敏感信息扫描完成（发现 X 个文件含敏感信息，已按用户选择处理 / 未发现敏感信息）
✅ 增量对比完成（基于 ../YYYY-MM-DD/ 的变更摘要已追加 / 首次交接无对比）
✅ 交接便签已生成
⚠️ 注意：以下大文件因超过 10MB 未打包，若为运行所需请手动传输：
  - [文件名] ([大小])
⚠️ 严重：以下文件因超过10MB未打包，但包含敏感信息，请务必手动安全传输：[文件名]
⚠️ 以下文件因包含敏感信息未打包（已移除），需手动补充：[文件名]
⚠️ 根目录基于当前工作目录推断，如有误请手动调整
⚠️ [文件名] 脱敏失败，已自动移除，请手动补充

条件显示规则：
- 无大文件被排除 → 省略"⚠️ 注意：以下大文件"行。
- 无敏感大文件 → 省略"⚠️ 严重"行。
- 无移除的敏感文件 → 省略"⚠️ 以下文件因包含敏感信息未打包"行。
- 根目录通过特征文件识别 → 省略"⚠️ 根目录基于当前工作目录推断"行。
- 无脱敏失败 → 省略"⚠️ [文件名] 脱敏失败"行。
- 记忆目录存在 → 显示"✅ 记忆文件 X 个"；不存在 → 显示"⚠️ 未发现 .workbuddy/memory/ 目录"。
- 增量对比有历史档案 → 显示"基于 ../YYYY-MM-DD/ 的变更摘要已追加"；首次交接 → 显示"首次交接无对比"。

输出：自检报告文本

失败处理：自检过程出错 → 输出已完成的自检项，标注出错项。

第七步：确认输出路径

输入：归档目录路径、自检报告

执行：

1. 向用户确认归档路径，格式：项目根目录/交接档案/YYYY-MM-DD/
2. 附上自检报告摘要（核心统计 + 所有 ⚠️ 项）。

输出：归档路径 + 自检摘要

失败处理：无失败场景。

AI 生成便签时的信息来源规则

• 禁止清单和已知陷阱：优先从 .workbuddy/memory/ 目录检索历史记录（如 bug-fix-log.md、constraints.md）。若无记录，则基于当前对话上下文总结，并在便签中标注"⚠️ 以下内容基于对话上下文提取，请接手方核实"。
• 技术债：从当前对话上下文中提取所有被用户提及但暂时搁置的改进项。
• 启动命令：基于当前对话上下文和已知项目结构推断主入口文件（如 main.py、app.py、run.py 等）或用户最近运行的脚本。

兜底规则（安全网）

以下兜底情况必须严格按规则执行，不要自行判断：