Plan Handoff

---
name: plan-handoff
description: "三段式交接工作流：强模型调研并写方案 → 新 agent 一句话执行并写反馈 → 复盘回填经验。只在出现以下明确信号时使用：①用户要求把方案/计划写到 ./temp/<目录>/PLAN.md（或点名 plan-handoff 出方案）；②用户说“基于 ./temp/<目录>/PLAN.md 执行”；③用户要求复盘 ./temp/<目录>/FEEDBACK.md。普通的规划、讨论、改进建议不要使用。"
---

# plan-handoff：出方案 → 一句话执行 → 反馈 → 复盘

目的：聪明的 agent 负责调研和设计，执行的 agent 只收到一句话也能独立做完，用户几乎不用亲自测试，每轮的经验沉淀回本 skill。

先判断自己的角色，只读对应的那一节。

---

## 角色一：出方案（Planner）

产物：`./temp/<短横线命名的专项目录>/PLAN.md`（确认 `temp/` 已被 git 忽略；没有的话在交付时告诉用户）。结构按 `references/plan-template.md`。

### 步骤

1. **读规矩**：项目的 AGENTS.md / CLAUDE.md，以及与任务相关的子目录说明。
2. **调研代码**：读核心实现、测试、文档、配置模板。大文件按函数定位，不要整文件读完。
3. **本地实测**（关键，别只读代码）：用最小实验验证最可疑的点，例如起容器跑一下、curl 一下、对照实验（127.0.0.1 与 0.0.0.0 各一组）、看版本号。每条结论标注依据：【实测】或【源码】。记下环境规格（OS、架构、CPU、内存、运行时及版本、有没有桌面 / DISPLAY、代理）。
4. **在线调研**：只在第三方行为影响设计时做，例如新版本的安全默认值、检测机制、平台差异。
5. **只问产品决策**：会改变方案走向、而且只有用户能决定的问题（删不删功能、命名、范围），集中用一次 AskUserQuestion 问完，并给出推荐项。技术细节自己定。
6. **写 PLAN.md**：对照下面的检查清单逐条落实。用户后续追加的要求（例如“清理历史债”“版本改成 x”），**写进 PLAN，不要写进给用户的提示词**。
7. **交付**：用三五行说明核心结论，然后给出执行提示词，固定为一句话：
   ```
   基于 ./temp/<目录>/PLAN.md 执行
   ```

### PLAN 检查清单（每条都要落实或明确写“不适用”）

- [ ] 开头有「执行须知」：执行者只会收到一句话；全程自主，不中途找用户确认；没覆盖到的取舍按什么优先级决定（例如“易用 > 仿真 > 改动量”）；要先读哪些文件；结论以实测为准，先写失败用例再修；可以用子 agent，但结论要亲自复核；执行中持续写 `FEEDBACK.md`。
- [ ] **授权边界写死**：哪些对外动作已授权（提交、推送哪个分支、合并 main），哪些没有（workflow、发布、镜像、npm）。版本号要不要改、改成多少。人工门禁（真机检查等）的豁免要写明范围（哪个版本、哪一项、绑哪个提交）；之后再命中时一律停下交接——用户说“授权发布”不等于“豁免检查”，没听到“这项不用查”就不能代勾。
- [ ] **用成果完成一次真实任务作为验收**（dogfood）：做的是工具 / 流程，就用它完成一次真实任务（例如用新发布流程真实发一版），自测发现不了的缺陷往往在这一步暴露。
- [ ] **硬约束**：用户强调的核心目标、不能退化的能力（例如反检测）、“清理历史债、不为兼容妥协”这类态度，以及项目规范中的关键条目。
- [ ] **现状 / 缺陷清单**：带证据标注和影响，按共性问题和个别问题分开写。
- [ ] **目标设计**：先从用户视角写“我想… → 命令”，再写架构；关键决策写明理由。
- [ ] **让 agent 自测，不让用户测**：凡是能自动化的都写进测试方案——真实浏览器（有桌面就用有头的，没有就用无头或 Xvfb）、截图看效果、模拟键盘鼠标（python-xlib/xdotool；模拟打字前先切到英文输入法）、起真实容器、调用真实 LLM（说明 token 从哪里来，强调不能打印）。只有确实做不到的才留给用户，并写明为什么做不到；本机能复现的问题不要让用户去另一平台验证，缺的环境先尝试嵌套造（如特权 `docker:dind`、`podman/stable`）；嵌套环境的文件属主与能力不等于真实 rootful，涉及“容器里的 root 读宿主机私有目录”时单独用非 root 属主的目录验证。
- [ ] **分层测试**：单元 → 真实依赖集成（含破坏性场景：重启、kill -9、删状态目录、并发、端口被占、代理）→ 质量 / 仿真对比（修改前后都有数据）→ 真实端到端 → 让一个只看新文档的新子 agent 当新手试用，按它的卡点迭代文档，直到一次通过（试用任务要走用户真实入口，如网页终端、对话，不要让它自己 `exec` 开 shell；改完文档要再试一次）。基线先跑完再动代码。新断言 / 夹具必须先在旧实现上跑出红灯才算数；“启动成功”类断言要落到“真的生效”（对照组、目标列表），不能只看退出码。
- [ ] **第三方库的安全默认值列为必验项**：Host/Origin 校验、sandbox 要求、权限弹窗、绑定地址等；换依赖的渠道或大版本后，新版本新增的默认策略也要列进来。只验证功能会漏掉这些。
- [ ] **隔离边界审查**：功能让低信任方（容器里的 Agent、网页、局域网）控制高信任方的资源（宿主机进程、浏览器、端口）时，列出“对方连上之后协议层能做什么”（读写文件、原始调试协议、加载代码、下载目录），用最小实验确认，并写成“越界被拒”的回归用例。只看自家代码会漏掉第三方协议本身提供的能力。还要逐个问“这份输入谁能写”：高信任方读取的文件、配置、命令输出（如容器里的 `/etc/hosts`、挂载目录里的文件、容器内的 `test`）只要低信任方能写，就按不可信输入处理（符号链接、FIFO、超大文件、伪造内容）。按来源 / 身份认人的设计，单列“这个身份谁能伪造”，按运行时逐个列默认能力（如 docker 默认带 `NET_RAW`、podman 没有；特权容器；多网卡），并在对应运行时里实测伪造用例。
- [ ] **引入或替换第三方依赖 / 内核**：说明来源与信任依据；非官方产物要求从公开源码可复现构建，并以 `npm pack` 的 sha512 与 registry integrity 是否相同作判据（写明目录布局、`set -o pipefail`）；版本钉死后 grep 所有会升级它的脚本；删依赖或命令前查全部调用方与隐含副作用（例如 `install-deps` 顺带 `apt-get update`）。
- [ ] **收紧类功能（默认禁止、白名单、限流）先列“会被误伤的合法链路”**：用户已有用法和产品自身依赖（模型服务、内置浏览器、CDN、遥测、登录回调）逐条写放行或自动缓解；被拒时用户 / Agent 能否立刻看到原因与“一键放行”。每个预设 / 模式都用真实 Agent 跑一遍端到端，不能只用 curl 验证规则。
- [ ] **界面一致性规则**（有前端时）：先列现有界面范式（字段标签、一行一项的列表编辑、卡片页脚保存、折叠区、移动端），新 UI 必须复用；同类控件共用一个组件，不发明复合文本语法；与已有字段语义重叠（如两套 env）在方案阶段就合并概念。自测时把新控件与同页已有控件并排截图对比；审查清单里要有“提示文字是否一句话、无实现细节和术语”，只查视觉会漏掉啰嗦的文案。
- [ ] **改核心流程先盘点测试替身与常驻进程**：grep 假运行时、`jest.fn` 替身、注入点，把改造量写进计划；测试前确认没有旧代码的常驻服务（watcher、serve）在抢同一批资源，产品对“不属于自己的对象”默认不动手。新增常驻资源（sidecar 容器等）时，列出所有按名字 / 镜像枚举对象的地方（列表、孤儿判断、卸载、升级）逐个确认排除；多个进程都能创建同一资源时，写清幂等与竞态规则。
- [ ] **每个“某平台未实测”的假设，同时写出它失败时的备选方案**，省掉一次发版。
- [ ] **收益先量后写**：提速 / 优化项的预期收益要有本地小实验数据，否则标【推测】并写放弃门槛（如“恢复 ≥90s 就放弃”）。缓存类提速按首次（冷）数据估算上线效果（缓存常有作用域，例如分支写的 main 读不到）。
- [ ] **临时措施写出加和删**：为绕开平台限制加的临时触发器 / 开关，方案里同时写删除步骤，并用断言保证交付时已删除。
- [ ] **外部状态探测用权威端点**：判断“发布了没 / 可见了没”这类探测，固定官方地址，不依赖维护者本机配置（镜像源、代理）。
- [ ] **测试隔离**：任何会写用户目录（例如 `~/.xxx`）的代码路径，测试必须注入临时 home（注意 `process.env.HOME` 改了不影响 `os.homedir()`；临时 HOME 写绝对路径并先检查非空，变量为空时状态会写进当前目录）；点名那些会顺手改用户真实配置的命令（例如 build 写回配置），要求执行后恢复。
- [ ] **环境与资源**：写明本机规格、只验证哪种架构、并发上限；允许 agent 自行安装需要的工具。
- [ ] **发布副作用**（涉及镜像、产物时）：隐私 / 安全扫描的允许列表、产物体积上限、版本号同步的位置、发布顺序；需要用户授权的步骤写进交付说明。
- [ ] **实施步骤**：每步都有验收标准，可以单独通过测试；分支、提交信息、合并方式按项目规范写。
- [ ] **交付要求**：执行者结束时写好 `FEEDBACK.md`（PLAN 模板里已内联了反馈结构，执行者不依赖本 skill 也能照做），并在对话里给出简要结论。

---

## 角色二：执行（Executor）

收到“基于 ./temp/<目录>/PLAN.md 执行”时：

1. 完整读 PLAN.md，以及它要求读的文件。PLAN 的「执行须知」和硬约束优先于你的默认习惯，但不能凌驾于用户在对话里的明确指令和安全规则。
2. 先核实 PLAN 里的每条结论（把缺陷转成失败用例），复现不了的如实标注，不要硬修。
3. 按实施步骤推进，自主决策；能自己测的绝不留给用户：截图、模拟键鼠、真实浏览器、容器、LLM 都要用起来。
4. 子 agent 用 worktree 时，让它把要保留的文件写到主检出的绝对路径；用完立即合并并删除 worktree（仓库内的 worktree 可能被测试框架扫到）。
5. **边做边写** `./temp/<目录>/FEEDBACK.md`（结构按 PLAN 里的要求；PLAN 没写就用 `references/feedback-template.md`）。发现计划偏差、遗漏、踩坑时当场记下来，不要等到最后回忆。只记高价值的内容：计划错在哪、遗漏了什么、下次出方案该怎么写。不写流水账。
6. 对外动作严格按 PLAN 的授权边界执行，授权范围外的只写进交付说明。
7. 结束时在对话里给出：做了什么、测试结果、没验证的部分、需要用户授权或亲自做的事。

---

## 角色三：复盘（Retro）

用户带着 FEEDBACK.md 回来时：

1. 读 FEEDBACK.md，按三类分拣：
   - **通用经验**（下次任何方案都适用）→ 改本 skill：检查清单、模板或这份 SKILL.md。保持精炼，合并同类项，不堆砌案例。
   - **项目经验**（读代码看不出来的约束）→ 提议补进项目的 AGENTS.md / CLAUDE.md；如果执行者已经补过，就核对一下。
   - **一次性事实** → 不沉淀。
2. 遗留问题如果需要新一轮工作，就按“角色一”出新方案，放到新的目录里。
3. 向用户简要汇报：改了 skill 的哪几条，以及建议的下一步。