实验性交接(Experiment Handoff)
角色
你是实验性交接的执行者。项目进行到中途要试功能/跑测试时:隔离出一个沙箱(worktree/branch/copy),写一份小实验文档交接给下一个 agent/session,实验有结论后把验证过的改动合并回主项目或丢弃,并清理沙箱。
与 project-handoff(项目状态交接)并列:本技能只管单个实验的隔离与回收,自足——不依赖其它技能的脚本或文件。
何时使用(已挂载 · 仅用户手动 /experiment-handoff)
本技能已挂载(~/.agents/skills/experiment-handoff,用户可用 /experiment-handoff 调用),但 agent 不得自主触发——只有用户显式调用时才执行:
- 触发方式:用户键入
/experiment-handoff(或明确点名该技能);仅手动。 - 三段手动:① 用户
/invoke本技能 ② 用户手动把会话交给另一个 agent ③ 用户手动宣告实验结束。 - 其余全自动:探测 VCS、选隔离策略、建隔离、写文档/索引、记基线、合并回主、清理。
硬约束
- 隔离优先——实验改动不得污染主工作树;一律先进沙箱。
- 结论驱动合并——先写
结论/反馈,再决定合并范围(全量/部分/丢弃);不得先合并后补结论。 - 可回滚——合并前记基线(commit/快照 hash);合并后跑验证,不通过即回滚。
- 必清理——收束必删沙箱(worktree/branch/copy)与临时分支;不留残留。
- 防膨胀——实验文档小(≤~600 tokens);收束即迁
archive/;活跃实验 ≤10 条(超出先归档)。 - 脱敏——文档不含 API Key/密码/PII。
隔离策略(agent 自动选)
| 项目状态 | 策略 | 落地 |
|---|---|---|
git 仓、git worktree 可用、主树干净 |
worktree(默认) | 兄弟目录 ../<proj>-exp-<slug> + 分支 exp/<slug>(不嵌在主树内) |
| git 仓、主树有未提交改动 | 先 commit/stash → worktree | worktree 看不到未提交改动 |
| git 仓、小改动就地 | branch(--mode branch) |
直接切 exp/<slug> |
| 无 git / 无 commit(unborn HEAD) | copy | 复制到 ../<proj>-exp-<slug>,排除 node_modules/dist/.venv/target/.next/.git;记快照 hash |
| 沙箱在外置盘/可能卸载 | git worktree lock |
防误 prune |
worktree 各自独立依赖(无 node_modules)——建后需 install(pnpm 共享 store 可省)。
交接文档
- 位置:
<项目>/.experiments/<slug>.md(本地私有,自动加.gitignore);索引.experiments/EXPERIMENTS.md(自动生成,勿手改)。 - 字段(按 spike 模板:Goal→Method→Evidence→Conclusions→Next Steps):
- 状态: open | running | concluded | promoted | discarded
- 日期 / 标题
- Goal: 一句话问题/假设
- Method: 方法
- 隔离: <worktree|branch|copy> · 位置: <path> · 分支: <exp/slug 或 ->
- 基线: <commit 短 hash 或 copy 快照 hash>
- Run: 命令
- 结论: <反馈——合并依据>
- Next Steps:
- 合并计划: 全量 | 部分(<paths>) | 丢弃
- 合并结果: <merge commit / patch 文件 / 未合并>
- 清理: <命令>
## Evidence(追加式:测试/指标/观察)
工作流
【手动触发 1】开
- [ ] 1. 探测:git 仓?worktree 可用?主树干净?(无 git → copy)
- [ ] 2. 选隔离策略(见上表),建沙箱(worktree/branch/copy)
- [ ] 3. 写 .experiments/<slug>.md(含基线)+ 生成索引
- [ ] 4. (worktree)cd 沙箱 && install 依赖
【手动触发 2】续 / 交办
- [ ] 5. 读文档 → 若文档里的基线 commit 已前进,先确认是否需要重取基线 / 重新隔离
- [ ] 6. 进沙箱继续实验,Evidence 追加
【手动触发 3】收
- [ ] 7. 填 结论/反馈 → 定合并计划(全量/部分/丢弃)
- [ ] 8. 合并回主:git 系 `merge`/`cherry-pick`(部分用 `git checkout exp/<slug> -- <paths>`);copy 系生成补丁后应用
- [ ] 9. 合并后:跑测试 → 按项目交接约定留一行引用(`project-handoff`;不复制)
- [ ] 10. 清理沙箱 + 归档文档(状态 promoted/discarded)
合并回主项目(反馈驱动)
| 隔离方式 | 合并手段 |
|---|---|
| worktree / branch | git merge --no-ff exp/<slug>(或 cherry-pick);部分合并:git checkout exp/<slug> -- <paths> |
| copy(非 git) | 生成补丁(脚本用 diff -ruN 或 git diff --no-index)→ 审阅后 git apply -p1 / patch -p1 |
- 粒度:全量 / 部分(只带验证过的文件)/ 丢弃——由
结论决定。 - 回滚:合并前基线的 hash 是回滚锚点(
git reset --hard <base>/git revert);copy 系原副本仍在,可重来。 - 落痕:成功后按项目交接约定留一行 引用(commit/补丁路径;
project-handoff维护),不复制内容。
防膨胀
- 收束即
mv到.experiments/archive/;索引自动区分 active/archived。 - 活跃实验 >10 →
list告警,先归档/收束旧的。 - 文档保持小;大段证据进项目 docs(引用即可)。
附带脚本
| 脚本 | 平台 | 说明 |
|---|---|---|
scripts/experiment.sh |
Linux / macOS / WSL / Git Bash | init(建隔离+文档)/ close(合并+清理+归档)/ list |
scripts/experiment.ps1 |
Windows PowerShell 5.1+(UTF-8 带 BOM) | 同行为;参数为位置式(-File 下 --x 会被当参数名) |
零 python/node 依赖(bash 用 coreutils+git+tar;PS 用内建 + git/tar)。用法:
scripts/experiment.sh init <slug> [--title T] [--mode worktree|branch|copy] [--base REF]
scripts/experiment.sh close <slug> --keep|--discard [--paths p1,p2]
scripts/experiment.sh list
experiment.ps1 init <slug> [title] [mode] [base]
experiment.ps1 close <slug> keep|discard [paths]
experiment.ps1 list [write]
反模式
- 实验改动直接落主工作树(无隔离)→ 污染主线
- 先合并后补结论(无反馈依据)
- 合并前不记基线(无法回滚)
- 收束不清理沙箱/分支(残留膨胀)
- 实验文档写成大百科(超预算、不归档)
- agent 自主调用本技能(应等用户
/experiment-handoff) - 依赖其它技能的脚本/文件(本技能须自足)
完成标准
- 沙箱已建且主树未被污染(worktree/branch/copy 其一)
- 由用户
/experiment-handoff显式触发(非 agent 自主调用) -
.experiments/<slug>.md存在(含 Goal/Method/基线/结论/合并计划/合并结果/清理) - 索引
.experiments/EXPERIMENTS.md已生成 - 收束:按结论合并或丢弃;合并后有验证 + 按项目交接约定引用一行
- 沙箱/分支已清理;文档已迁
archive/ - 无敏感信息
常见错法 → 改法 / FAQ
| 错法 | 改法 |
|---|---|
| 直接改主工作树"就试一下" | 停手——先 experiment.sh init <slug>,改动进沙箱 |
init 报 exit 2(用法错) |
核对调用形:experiment.sh init <slug> [--title T] [--mode ...] [--base REF];slug 必填 |
init 报 exit 1(执行错) |
看 stderr 首行:多为 worktree 不可用或主树未提交改动未 stash——按提示处理后重跑 |
close 想只带部分文件 |
用 --paths p1,p2;不带则全量合并,--discard 则丢弃 |
close --keep 后测试不过 |
回滚锚点=文档里的基线 hash:git reset --hard <base>;copy 系原副本仍在,可重来 |
| 主树有未提交改动时开 worktree | 先 git stash 或 commit——worktree 看不到未提交改动 |
手改 .experiments/EXPERIMENTS.md |
索引是自动生成的,手改会被覆盖;改状态请改各自实验文档的 状态: 字段 |
| 实验做完忘了收 | experiment.sh list 会列出 open/running 的实验与告警(活跃 >10 条) |
边界判定: 无 git 仓 → 自动走 copy,无需选择;slug 与已有实验重名 → 先 list 查看再用新 slug,不覆盖旧文档;沙箱目录已存在 → 报错退出(exit 1),换 slug 或先清理,不静默复用。
方法论来源(2026-09 调研)
- Technical Spike 模板(Microsoft Engineering Playbook):Goal / Method / Evidence / Conclusions / Next Steps——本技能文档字段来源
- Git worktree 最佳实践(GitWorktree.org):兄弟目录布局、
<project>-<branch-slug>命名、合并后git worktree remove+prune、每 worktree 独立依赖——隔离策略来源 - Agent handoff 模式(Microsoft Agent Framework / AutoGen):显式交接控制权——手动三段触发模型来源