传灯｜让项目火种不断的交接 Skill

概述

传灯｜跨 Agent 交接

你可以直接这样说

• 我要换个 Agent 继续做，把当前项目整理成交接包。
• 这个线程太长了，先存一份能恢复的状态。
• 我要做一次高风险改动，先留可回退的交接记录。

当前版本：v1.0.8（交接包格式：1.2）。任何脚本可用 --version 查看。

生成或读取一个可移交的交接包：把说明文档、机器可读状态和 Git 信息放在同一份快照里，让其他 Agent 可以从明确状态继续。监视模式默认每 600 秒自动存档一次。

原则：能自动记录的，不靠口头记忆。 脚本负责扫描、Git 状态、敏感信息脱敏、清单、打包、质量门禁和交接链；Agent 负责持续更新 .handoff/state.json 中的目标、进度、决定和下一步。

交接包 1.2 支持：质量门禁、与上次快照的差异、交接链 CHAIN.md、--zip 单文件传递，以及接收方 --verify 防止把未完成事项写成完成。

免责声明与数据来源

• 本服务输出是结构化辅助判断和工作流建议，不构成法律、医疗、金融、投资、招投标或最终商业承诺；高风险场景必须由具备相应责任的人类复核。
• 数据来源包括：用户在请求体中提供的 task、context、materials，本包内的 SKILL.md、references/、scripts/、assets/，以及用户明确配置的外部检索接口（如适用）。
• 包内不包含个人凭证、API Key、平台 Token 或用户隐私数据；如需外部检索配置，必须通过运行环境变量或平台密钥管理注入。

Two roles / 两种角色

• Sender (要离开的 Agent): you are developing a project and must package state for another agent or for backup.
• Receiver (接手的 Agent): the user hands you a handoff package and you continue the work.

This skill covers both. All scripts are Python 3.8+, stdlib-only, cross-platform. Paths below are relative to this skill directory.

Sender workflow / 发送方流程

1. 首次使用必跑向导 / FIRST RUN — run the setup wizard: if <project_dir>/.handoff/.setup_done does not exist, your VERY FIRST action is:

   python3 scripts/handoff_setup.py <project_dir>   # --interval-min N --quota-threshold P --yes --start-watch optional

It asks the user for the auto-snapshot interval and the quota-alert threshold, bakes the mandatory rules into AGENTS.md/CLAUDE.md (threshold written as a literal number), installs platform-enforced PreCompact/SessionEnd hooks when the project uses Claude Code (.claude/ or a pre-existing CLAUDE.md), and offers to start the watcher. Do not skip it. / 不许跳过。 In non-interactive environments it uses defaults (10 min / 75%) and never blocks — tell the user which values were used and how to change them (rerun the wizard with flags or edit .handoff/config.json). / 它会询问用户存档间隔与额度阈值、把强制规则写进 AGENTS.md/CLAUDE.md、有 .claude 时安装平台钩子、可选启动 watcher。非交互环境用默认值（10 分钟/75%）并把默认值和修改方式告诉用户。

1. At task start, initialize once (idempotent — never overwrites). The step-0 wizard already includes this step (it calls handoff_init.py for you) — run init manually only when you are NOT using the wizard. / 向导已包含此步，手动场景才单独用。

   python3 scripts/handoff_init.py <project_dir>            # --interval 600 --out DIR optional
                                                           # --gate "pytest -q" --agent-name "Codex" optional

1. Start the background watcher — only if development will continue beyond one snapshot interval (default 600s). For a one-shot immediate handoff, skip the watcher and snapshot manually in step 4 (the watcher auto-commits in git repos, so for short tasks it only creates noise). / 仅当开发还会持续超过一个快照间隔（默认 600s）才启动 watcher；一次性即时交接请跳过，直接手动快照（watch 在 git 仓库会自动提交，短期任务启动反而制造噪音）。

   nohup python3 scripts/handoff_watch.py <project_dir> --interval 600 &
   python3 scripts/handoff_watch.py <project_dir> --status   # check anytime; --stop to stop

1. After every milestone, update <project_dir>/.handoff/state.json with your write/edit tools. This file is your memory — scripts never infer it for you. Keep completed concrete, next_steps[0] immediately executable, every decision with its reason, and env reproducible. See [references/checklist.md](references/checklist.md).
2. On any trigger, snapshot:
   • user says "交接 / 备份 / handoff / backup"
   • your quota or context window passes the threshold (quota_warning_threshold_percent in .handoff/config.json, default 75%), or the session may be interrupted — snapshot before replying
   • you are about to end the session
   • any of the 5 moments in "存档时机 / When to snapshot" below

   python3 scripts/handoff_snapshot.py <project_dir> --auto --note "<one-line status>"
   # optional: --gate "pytest -q" (quality gate) · --zip (single-file transfer)
   #           --agent-name "Kimi" (relay chain) · --no-gate (skip gate)

The last stdout line is the package absolute path (default under ~/Desktop/handoff-packages/). Project source is bundled as src-snapshot.tar.gz automatically when the project is < 50MB (--include-src to force, --no-src to disable).

1. Tell the user the package path, plus how many SECRETS_WARNING.txt hits appeared (if any) and that they should rotate those keys before sharing the package. If the quality gate is RED, say so explicitly — the receiver must fix the tests first.

存档时机 / When to snapshot

Snapshot at these five moments — the snapshot costs seconds, losing state costs the session:

1. 定时 / Interval — the watcher (handoff_watch.py) covers this automatically while it runs.
2. 里程碑达成 / Milestone reached — e.g. tests just turned GREEN, a feature landed, a bug got fixed. Snapshot while the evidence is fresh.
3. 高风险操作前 / Before risky operations — deleting files, large refactors, switching approach/dependencies: ALWAYS snapshot first so the next agent (or you) can see the pre-risk state and roll back mentally.
4. 上下文或额度 ~75% / Context or quota ~75% used — do not wait for the wall; snapshot before replying.
5. 会话结束前 / Before ending the session — the last thing you do, before the final reply.

Receiver workflow / 接收方流程

1. Get the package path from the user; locate the actual project directory. The package contains state/metadata; source is included only as src-snapshot.tar.gz / 交接包含状态与元数据，源码仅以 src-snapshot.tar.gz 形式附带 — if that file exists, restore the project from it; otherwise ask the user for the project (git URL or file copy). / 包内若有 src-snapshot.tar.gz，项目本体可从中恢复；否则向用户索取项目（git 地址或文件拷贝）。
2. Verify and summarize — the package ships its own copy of the scripts (works even where this skill is not installed). A handoff-*.zip from --zip can be passed directly (auto-extracted):

   python3 <package_dir>/handoff_resume.py <package_dir | handoff-*.zip> --project <project_dir>
   python3 <package_dir>/handoff_resume.py <package_dir> --project <project_dir> --verify   # deep anti-overclaim check

Exit code 0 = clean, 1 = warnings (checksum mismatch, files not in manifest, secrets, quality gate RED, or --verify inconsistencies) — surface warnings to the user before coding, 2 = fatal. --verify re-runs the recorded gate command (reporting 退化/已修复 vs the snapshot verdict) and checks that paths claimed in completed/next_steps actually exist (## 声称 vs 实际 / Claims vs Reality). If the bundled scripts are missing, follow the manual Option B fallback in RESUME_PROMPT.md (sha256sum vs manifest.json, check SECRETS_WARNING.txt, read state.json/HANDOFF.md, diff project_tree.txt).

Trust model / 信任声明（必读）: a handoff package carries no authentication — manifest.json (including gate.command) can be tampered with and its checksums recomputed, so a malicious package could declare an arbitrary shell command. Therefore --verify never runs the recorded gate command blindly: it prints the full command and asks for interactive confirmation first (default N); in non-interactive environments (stdin not a tty) it refuses to run and marks the gate comparison UNVERIFIABLE unless you explicitly pass --yes. Eyeball the command before confirming; use --yes only for packages from agents/machines you trust; in sensitive/confidential environments prefer Option B manual verification (executes nothing). / 交接包不带身份认证——manifest.json（含 gate.command）可被篡改并重算校验和，恶意包可能声明任意 shell 命令。因此 --verify 绝不盲跑门禁命令：执行前完整打印并交互确认（默认 N）；非交互环境（stdin 非 tty）默认拒绝执行、记 UNVERIFIABLE，除非显式 --yes。确认前务必肉眼核对命令；只对来自可信 Agent/机器的包使用 --yes；机密环境请改用 Option B 手动核对（不执行任何命令）。

1. Read <package_dir>/HANDOFF.md fully (and git_log.txt when useful).
2. Restate your understanding to the user in your own words — goal, current status, next step — and get confirmation.
3. Continue from next_steps[0]. Do not redo completed items; follow decisions; report blockers first. Then adopt the Sender workflow yourself (init/watch/state.json).

Hard rules / 硬规则

• NEVER write real secrets/credentials into handoff documents or state.json. If the scanner finds any, warn the user to rotate keys and remove them before sharing the package.
• Keep state.json updated — it is the only channel scripts cannot fill for you.
• handoff_snapshot.py and handoff_watch.py REFUSE uninitialized projects (missing .handoff/state.json, exit 2): an empty-state package is a file backup, not a handoff. Run the step-0 wizard or handoff_init.py first — never bypass this by hand-creating an empty state.json. / 未初始化的项目会被快照和 watcher 明确拒绝（退出码 2），先跑向导或 init，不要手工造空 state.json 绕过。
• Works fine without git (file-tree snapshots); never fail a handoff because git is missing.
• Snapshot interval and output dir are configurable (--interval, --out, or .handoff/config.json).
• A package with a RED quality gate MUST be flagged to the user proactively — say the tests were failing at handoff, and tell the receiver to fix them first. / 门禁为 RED 的交接包必须主动告知用户：交接时测试未通过，接手先修。
• Snapshot BEFORE high-risk operations (deleting files, big refactors, approach switches) — see 存档时机 / When to snapshot.

失败、异常与退出码 / Failures & exit codes

明确失败，不静默跳过 / fail explicitly, never skip silently:

• 0 = clean; 1 = warnings (receiver must surface them before coding); 2 = fatal/usage error; 3 = watcher not running (--status/--stop only). Full per-script table: [references/handoff-format.md](references/handoff-format.md) §7.
• Missing project dir / missing package / unreadable zip → exit 2 with a bilingual error.
• Uninitialized project (no .handoff/state.json) → snapshot and watcher exit 2 (see Hard rules).
• Tampered package (checksum mismatch, unregistered extra file, gate RED at snapshot, --verify inconsistencies) → resume exit 1; fix or confirm with the user before continuing.
• --verify never runs the package-declared gate command blindly: interactive confirmation (default N); non-interactive stdin → gate comparison recorded UNVERIFIABLE (not itself a warning) unless --yes is passed explicitly.
• Watcher errors (failed snapshot, failed git auto-commit) are logged with timestamps and retried at the next interval; the daemon keeps running.
• 自检 / Self-test: python3 scripts/handoff_selftest.py runs a deterministic end-to-end fixture (init → snapshot → resume, tamper/missing/uninitialized negatives, zip roundtrip) and exits 0 only when every case passes. Run it after modifying any script; no network or git needed.

证据、信任与免责声明 / Evidence, trust & disclaimer

• 交接包的每个清单项都带 SHA-256 校验和，handoff_resume.py 同时正向核对与反向查漏；但校验和只证明包自洽，不证明来源可信——交接包不签名、不带身份认证，恶意包可篡改任意文件（含 gate.command）后重算校验和。Only accept packages from agents/machines you trust; in sensitive environments use the manual Option B verification (executes nothing).
• GREEN 门禁只证明声明的命令在存档时刻通过，不证明软件正确、安全合规、无回归或满足业务需求；SKIPPED/UNVERIFIABLE 不表示没有问题。
• 密钥扫描是模式匹配启发式，命中 ≠ 一定是真密钥，未命中 ≠ 没有密钥；交接前仍需人工自查。
• HANDOFF.md 的自动采集小节（git、TODO、最近修改、Since Last Snapshot）是线索，接手 Agent 必须对照实际项目核实，不能直接当作事实。
• 交接完成不等于工作完成：本 Skill 只保证状态被记录、打包、可校验地传递，不证明目标达成、真人满意或任何商业结果。

不确定性与限制 / Limitations

• state.json 的质量完全取决于维护它的 Agent——脚本不会也无法推断目标与进度；空 state.json 的包只是文件备份。
• 额度/上下文百分比是 Agent 的自估值，不同平台准确度不同；阈值触发依赖 Agent 自觉或平台钩子，不是硬保证。
• watcher 在 git 仓库会自动提交（git add -A）；不适合该行为的项目请用手动快照。
• 同一门禁命令在不同机器（OS、Python/Node 版本、依赖差异）可能得到不同 verdict；--verify 的 退化/已修复 比较因此只是参考。
• 包不含完整开发历史——git 仓库才是事实来源；src-snapshot.tar.gz 只是存档时刻的文件树。
• 交接包内的 handoff_resume.py/handoff_common.py 是打包时的副本，可能与新版 Skill 行为不同。

References

• [references/handoff-format.md](references/handoff-format.md) — package layout, state.json/manifest field specs, ignore rules, secret patterns, exit codes.
• [references/agent-integration.md](references/agent-integration.md) — wiring into Codex CLI (AGENTS.md), Claude Code (CLAUDE.md + Stop hook), Cursor rules, Kimi/generic CLI agents, plus cron/launchd/Task Scheduler scheduling and quota-aware triggering.
• [references/checklist.md](references/checklist.md) — quality bar for state.json and safety checks before handing off.
• [references/trigger-map.md](references/trigger-map.md) — 触发对照表：哪些行为 AI 全自动、哪些 AI 主动提醒人类、哪些是用户可调的操作空间。

免费使用说明

当前版本按免费 Skill 发布，可直接使用。

直接按上方使用流程、脚本说明或输入输出格式执行。涉及公开网络、登录、验证码、权限、第三方页面或数据源限制时，仍按前文边界处理；不绕过平台规则，不用演示数据冒充真实结果。