project-handoff

为任意项目建立或维护跨模型、跨会话、跨 agent 的自动接手工作规范,保存状态、决策、待办与证据,支持中途换 agent 的检查点、归属核对、一致性检查和接手包导出。用于建立或迁移长期交接机制;普通实现任务沿用已有入口,不重复初始化。

SKILL.md

GitHub

项目交接

目标:接手者自动找到当前状态,明确最后成功动作、证据、下一步和验收。记录落在项目,不依赖聊天记忆。人类最新指令优先,历史记录不扩大授权。

选择操作

  • 建立机制:核对项目根、嵌套仓库、有效AGENTS/override、已有文档及未知改动。读 工作规范,初始化骨架并填写真实事实。
  • 已有机制:优先维护既有权威文件/工具,不另建状态。补入口或迁移前映射旧来源,保留决策、未完任务和他人规则。
  • 接手/换agent:主动读入口、状态、任务与决策,运行检查。核对检查点和实际工作区;旧执行体仍写同文件时先协调或停止,不能凭时间戳接管。
  • 收尾/导出:阶段完成或中断前更新状态、生成摘要、检查。导出仅白名单交接文档与状态指纹,不含源码、业务库、原始对话、凭据或登录态。

随时换 agent

修改前登记任务、可识别owner、文件范围、最后成功动作、下一动作和验收。每个关键阶段立即落盘,长任务不等最终回复。外部操作之前记准备执行,之后记已执行/失败/结果待核验、操作标识和确认办法;响应丢失不能盲目重试。

python tools/handoff.py checkpoint --owner <执行体标识> --summary <最后成功动作及下一步>

检查点不改变代码基准或推断任务完成。新agent核对未提交改动与未闭环操作;源码漂移先恢复核查,不能直接record-local抹掉差异。确认外部操作结果再续做,不重复已留证阶段。突发中断前未保存的信息不能凭空恢复,不承诺任何中断都绝对无错误。

状态字段修改使用工具load/validate/save API的原子保存与读取版本核对,禁止整文件覆盖绕过保护;详情见工作规范。operations数组显式登记外部操作,running/unknown会使check失败,先确认实际结果。检查点和文件归属不能替代停止旧执行体。

建立新项目

Python 3.10+标准库。技能目录由SKILL.md位置确定,不写死盘符:

python <技能目录>/scripts/init_project.py --root <项目根> --name <项目名>
python <技能目录>/scripts/init_project.py --root <项目根> --name <项目名> --source src --source tools/handoff.py --apply

首条预览,--apply执行。用户已请求建立时核查后直接执行,不另索许可。--source按项目选代码/数据定义/资产,排除业务数据与秘密;默认仅工具自身,不能宣称产品已核验。

生成有效入口附加规则和自动摘要、状态源、看板/待办、决策、指南、规范、独立tools/handoff.py。非Git可用,不自动创建Git或操作网络/生产。已有状态/同名工具拒绝覆盖,转维护或迁移。

随后补全:目标/请求、真实环境/命令、交付方式、用户决定、归属、任务背景/证据/下一动作/验收、基准/验证范围。未知写待核验,不把生成骨架说成完整项目审查。

python tools/handoff.py record-local
python tools/handoff.py render
python tools/handoff.py check
python tools/handoff.py export --output .handoff-export

record-local只记所选源码指纹,不跑测试/证明发布;先核查再记录。纯文档推进HEAD正常,按项目规则精确提交。

边界

单一来源:规则在入口/规范,状态与待办在状态源,决策独立,发布/验证留证据。摘要/看板生成,禁止手工分叉。区分实现、测试、发布、业务验收及本次实测/长期历史/未复验观察/未测试。

自动接手依赖宿主加载AGENTS和项目访问权,技能选择不等于每条消息执行脚本;旧会话恢复主动重读。首次建立后无需每次调用技能。

不改无关全局设置,不主动启动子agent或定时任务,不替用户部署/清理生产。项目特有规则放在项目指南,不推广其他项目路径或偏好。只读无新状态不机械写文件。完成报告具体产物、验证和限制。