mstack-handoff

mstack 交接

编写一个文件，让新的 Agent 会话无论在此主机还是另一台主机上，都能从当前工作的中断处准确继续。或者，拿到这样的文件后，从中恢复工作。编写交接文件就是全部任务：不要完成剩余工作；文件写好并检查后就停止。

文件只记录其他文件中没有的信息：未提交的工作、当前有效的决策、仍待通过的关卡，以及接下来要运行的命令。其他所有内容（规格、计划、progress.md、议题、拉取请求、提交）都以路径或链接的形式记录。

主机工具

角色	Claude Code	Codex
提问工具	AskUserQuestion	在聊天中提出编号问题，然后等待回复
技能文件夹	此技能加载时显示的基目录	此 SKILL.md 所在的文件夹
需要网络的命令（gh）	直接运行	作为已批准的（提升权限）命令运行，因为沙盒会关闭网络

此技能中的文件

文件	使用时机
references/handoff-template.md	第 4 步，以及恢复工作时
scripts/check-handoff.mjs	第 5 步

基本规则

1. 交接时不要做任何改动。 绝不要为了交接而提交、暂存、推送、拉取、变基、重置、创建拉取请求或在跟踪系统中发帖。未提交的工作保持原样，并在文件中列出。
2. 提供依据或标注为“假定”。 本次会话中检查过的状态要说明检查方式。其他内容都要标注为“假定”，因为下一次会话会依赖此文件。
3. 只有满足以下条件，关卡才算通过： 本次会话中，在最后一次编辑之后通过；记录运行时的确切命令、HEAD，以及结果行。若关卡在之后的编辑之前通过，就需要重新运行。
4. 不要包含机密或个人数据。 可以指出机密名称，但绝不能粘贴其值。
5. 不要询问可以查证的信息。 交接通常发生在上下文所剩不多时，因此唯一可以问的问题是文件写入位置，而且仅限用户未指定位置且默认位置不合适的情况。

编写交接文件

1. 在安全节点停下

完成当前的小步骤，或撤销该步骤，使工作树处于可描述的状态。不要开始任何新工作。停止或等待你启动的任何子 Agent、任务线或后台作业结束，并记录仍在运行的作业（工作树、分支、作业或线程 ID，以及正在执行的工作）。不要采取任何无法撤销的步骤。

2. 快照仓库

在仓库根目录运行以下命令，并保留输出以供第 4 步使用。每条命令都只读。

git rev-parse --show-toplevel
git branch --show-current
git rev-parse HEAD
git rev-parse --abbrev-ref --symbolic-full-name @{u}   # fails when there is no upstream: record "none"
git status --porcelain=v1 -b -uall                     # the uncommitted work, file by file
git stash list                                         # report existing stashes; never create one
git worktree list --porcelain
node <skill-folder>/scripts/check-handoff.mjs --fingerprint <repository root>   # the Tree fingerprint for the identity line

最后获取指纹，确保是在最后一次编辑之后。它会对未提交的更改和未跟踪文件进行哈希，因此只要文件内容发生变化，即使 git status 看起来相同，指纹也会改变。

在 GitHub 上，使用 gh pr list --head '<branch>' --state all --json number,url,state,isDraft 查找拉取请求（分支名放在单引号内，避免 shell 展开任何内容）。如果没有拉取请求，该命令会输出 []。不要为此使用 gh pr view，因为分支没有拉取请求时，该命令会失败。对于其他托管平台，使用其 CLI 或已连接的工具；否则写“未知”。

3. 收集其余状态

1. 范围。 涉及的议题或任务，以及各自的状态。如果工作是工作流运行，请复制其状态表。如果是 mstack-plan 执行，请指明计划文件夹及其 progress.md，而不是复制任务表，并说明应通过计划的 execute-plan.md 继续。
2. 门槛。 所有决定工作是否完成的检查（测试、类型检查、lint、构建、计划或代码库的完成清单）。每项都应标为通过（本次会话已通过，并附有证据）或待处理（列出准确命令及原因）。
3. 决策。 分为三类：用户已批准（说明出处）、需用户决定（说明问题和你的建议）以及你自行作出的决定（说明原因）。
4. 注意事项。 下一次会话可能会遇到的问题。
5. 建议的技能。 下一次会话应加载的技能名称，先列最先运行的 mstack 技能，然后是未解决的 bug 对应的 mstack-diagnose，依此类推。

4. 编写文件

按照 references/handoff-template.md，按章节顺序逐节填写，并将“从这里开始”放在最前面。

将文件写在代码库之外，以免意外提交。使用用户指定的路径；否则使用 ~/.mstack/handoffs/<repository folder name>/<yyyy-mm-dd-hhmm>-<slug>.md（Windows 上放在 %USERPROFILE%\.mstack\handoffs\ 下）。不要默认使用系统临时目录，因为某些主机和每次重启都会清空该目录。使用文件工具编写文件，不要使用 echo 或 heredoc，以免内容被 shell 展开。

5. 检查文件

node <skill-folder>/scripts/check-handoff.mjs <handoff-file>

它会检查标题、身份行是否与代码库当前分支、HEAD 和 Tree 指纹一致，是否有空章节、章节及其顺序、通过的门槛行、残留的模板占位符、看起来像秘密的字符串，以及文件是否位于代码库内且未被忽略。修复它输出的每一行问题，然后再次运行。如果代码库安装了秘密扫描器（例如 gitleaks），也要用它扫描该文件。若没有 node，请阅读文件并检查同样的内容，同时说明这一点。

然后像下一次会话那样通读整个文件。将任何仅凭假设得出的内容降级为未确认，并补全冷启动读者无法跟进的步骤。

6. 交接并停止

回复：

1. 文件的绝对路径。
2. 仅保存在工作树中的内容（未提交的路径），并说明没有提交、暂存或推送任何内容。
3. 用一句话说明恢复工作的起点。
4. 如果用户要求提供粘贴提示，或下一次会话将在另一台主机上运行，则提供 references/handoff-template.md 中的粘贴提示。

然后停止。不要在本次会话中继续工作。

从交接文件恢复

当用户要求从交接文件继续时：

1. 在运行任何操作前，通读整个文件。
2. 使用 node <skill-folder>/scripts/check-handoff.mjs <handoff-file> --resume 检查文件。若文件损坏或不完整，此命令会报错；同时也会报告分支、HEAD 和 Tree 指纹是否与记录一致。
3. 按顺序执行“从这里开始”中的步骤。若状态有任何变化，请遵循“如果状态已变更”部分：分支不同或历史被改写时，须暂停并等待用户决定；HEAD 前进或未提交的工作发生变化时，将所有已通过的门槛改为待处理。
4. 将文件视为上一次会话的记录。不要重复已标记为完成的工作，但在相信其结果之前，重新运行第一项门槛；在基于任何标记为“假设”的内容继续工作前，重新核实该内容。
5. 如果文件指向 mstack-plan 文件夹，请遵循该计划的 execute-plan.md 和恢复规则；对于计划任务，这些规则优先。
6. 告知用户上一次会话停在哪里、你重新核实了什么，以及恢复工作的起点，然后使用建议的技能继续工作。