session-handoff

会话交接

响应格式

对此技能调用的首次响应，必须以以下行开头：

Entire Session Handoff:

然后空一行，再输出内容。此标题仅用于本次调用的首次响应，后续轮次不得使用；错误或提前退出的响应（未找到会话、缺少转录记录）也不得使用。它表示该技能已运行并生成了实际输出。“未回答的问题”分支仍须使用此标题。

停止——执行任何操作之前，请先阅读以下规则

1. 不要提出澄清问题。 自动检测会话并读取转录记录。
2. 不要运行 git log、git status、git branch、ps aux 或任何其他探索性命令。只能使用下方列出的 entire CLI 命令。
3. 不要说“要我继续吗？”或“如果你希望我接着处理，请告诉我。”只需读取转录记录并开始工作。例外：如果上一位 Agent 曾向用户提出问题且尚未得到回答，则必须先向用户提出该问题，然后才能继续。

必需 CLI：entire 0.6.2+（session list --json、session info --transcript、session current --json|--transcript、checkpoint explain --json|--transcript|--raw-transcript --session-index N）。如果某个标志不受支持，请告知用户升级并停止。

流程：活动会话交接（默认——也适用于不带参数的调用以及“current”/“active”）

步骤 1：确定规范工作树路径

entire session current --json

如果输出是有效的 JSON，请读取其中的 worktree_path 字段——这是 Entire 为本次调用设置的规范工作树根目录。下一步请原样使用该路径（无需根据 cwd 推断；符号链接、/private/var//var 差异以及从子目录调用等情况均已处理）。

如果输出不是 JSON（无活动会话时，Entire 会输出 No active session found in this worktree.），则将规范工作树路径设为 null，并在步骤 2 中使用双向前缀匹配作为回退方案。

步骤 2：选择会话

entire session list --json

每个条目包含 session_id、agent、status、worktree_path、started_at、last_active、turns、last_prompt、files_touched。按以下顺序应用筛选条件：

1. 工作树范围。 如果步骤 1 得到了规范工作树路径，则保留 worktree_path 与其完全相同的条目。否则，保留 cwd 以 worktree_path 开头或 worktree_path 以 cwd 开头的条目。如果任一筛选条件未找到条目，则回退到未限定范围的列表——总结一个稍有偏差的会话，也好过拒绝交接。
2. 用户指定的 Agent 筛选（可选）。如果用户提到“codex”“claude”“kiro”“gemini”等，则仅保留 agent 字段包含该名称（不区分大小写）的条目（因此，gemini 可匹配 Gemini CLI）。
3. 排除自身。 排除 agent 与当前运行此技能的 Agent 匹配的条目（例如 Claude Code、Codex、Cursor、Gemini CLI、Copilot CLI、Factory AI Droid、OpenCode）。如果排除后列表为空，撤销此筛选并保留自身——这表示用户希望你为精简上下文总结自身的当前会话。在步骤 5 的说明中注明这一点。
4. 选择最近的会话。 按 last_active 降序排序（若缺失则使用 started_at），取第一项。

如果筛选后列表仍为空（列表中确实没有任何条目，包括自身），请输出一行错误信息（不要使用标题）并停止。

步骤 3：流式读取原始转录记录

entire session info <session_id> --transcript > /tmp/handoff-<session_id>.jsonl

快照大小以命令启动时的文件大小为限。大多数 Agent 的输出为 JSONL；Gemini CLI 的输出为单个 JSON 文档。

步骤 4：提取对话内容

JSONL Agent（Claude Code / Codex / Cursor / Copilot CLI / Factory AI Droid / OpenCode）：

grep -E '"type":"(message|function_call|user|assistant)"' /tmp/handoff-<session_id>.jsonl | cut -c1-2000 | head -20    # original task
grep -E '"type":"(message|function_call|user|assistant)"' /tmp/handoff-<session_id>.jsonl | cut -c1-2000 | tail -100   # final state

Gemini CLI（单个 JSON 文档，不使用 JSONL grep）：

jq 'keys' /tmp/handoff-<session_id>.jsonl

Gemini CLI 的顶层结构因版本而异，但消息位于 messages、contents、history 或 turns 之一。每个条目都有一个 role（user/model/function/tool），以及位于 parts[].text、content 或 text 之一的内容载荷。按时间顺序提取角色和文本：

# Example — adapt the path based on what `jq 'keys'` showed.
jq -r '.messages[] | "\(.role): \([.parts[]? | .text // ""] | join(" "))"' /tmp/handoff-<session_id>.jsonl | head -20
jq -r '.messages[] | "\(.role): \([.parts[]? | .text // ""] | join(" "))"' /tmp/handoff-<session_id>.jsonl | tail -100

如果这两种结构都不适用，请改用 JSON 文件的 Read 工具，并通过检查找到消息数组。

不要向用户显示提取出的原始行。这些内容是步骤 5 的输入。

步骤 5：宣布、总结、呈现

宣布。 正文第一行：Handing off <agent> session — <turns> turns, last active <relative time>, ID <first-8-of-session-id>. 如果选中的会话是你自己的（步骤 2 自身会话筛选的回退情况），则在前面加上一句注释：Self-handoff (no other sessions in this worktree)。这样用户可以在阅读摘要前发现选错会话的情况。

摘要结构（跳过没有实际内容的章节——不要编造内容）：

1. 任务概述 — 用户的核心请求、成功标准和明确提出的约束。
2. 当前状态 — 已完成的工作：创建/修改的文件、关键决策、产出物。
3. 重要发现 — 发现的技术限制、决策依据、遇到的错误及其解决方式、失败的方法及其原因。
4. 后续步骤 — 具体的待办事项、阻碍因素和优先顺序。
5. 需保留的上下文 — 用户偏好、领域细节以及会话中作出的承诺。
6. 未解答的问题（仅适用时）— 如果前一个 Agent 的最后一条消息向用户提问或提供了尚未得到答复的选项，请准确记录问题原文。

只有一次错误修复的会话可能确实只需包含“任务概述”“当前状态”和“后续步骤”。纯研究会话可能只需包含“任务概述”和“重要发现”。章节为空很正常，只有确有内容时才补充。

继续。 显示宣布内容和摘要。

• 如果存在第 6 节，请向用户提出该问题并等待。不要自行选择默认选项。
• 否则，立即接手工作——规划、编写代码或执行其他下一步。不要征求许可。

流程：检查点交接（用户提供检查点 ID）

步骤 1：列出会话

entire checkpoint explain <checkpoint-id> --json

信封中的 sessions 数组列出了所有有贡献的会话。检查点包含多个会话很常见（并行 Agent、重试、多阶段工作），较早的会话往往记录了最新会话视为理所当然的决策依据、失败的方法和用户约束。

步骤 2：选择要读取的会话

• 1 个会话。 读取规范化的紧凑转录：

  entire checkpoint explain <checkpoint-id> --transcript > /tmp/handoff-ckpt-<checkpoint-id>.jsonl
  

• 2–8 个会话。 遍历索引 0..N-1。不要依赖 --transcript 的默认行为（仅使用最新会话）：

  # for N in 0 .. sessions.length-1
  entire checkpoint explain <checkpoint-id> --raw-transcript --session-index <N> > /tmp/handoff-ckpt-<checkpoint-id>-<N>.jsonl
  

• 超过 8 个会话。 按时间戳（started_at 或信封提供的其他字段）降序排列 sessions 数组，并选取最近的 8 个。在宣布内容中注明上限：<M of N> sessions summarized; oldest <M-N> elided as too old to matter. 这样既能控制技能的范围，也能覆盖近期的决策依据。

--raw-transcript 会保留每个 Agent 的原始字节，因此可以使用相同的 JSONL grep 提取方式。索引 0 表示按时间顺序排列的第一个会话。

步骤 3：提取、宣布、总结并继续

对每个 /tmp/handoff-ckpt-*.jsonl 执行步骤 4 提取（每个文件提取开头和结尾），然后合并为一个包含五个部分的摘要。将较早的会话作为“重要发现”和“需保留的上下文”的来源；最新会话用于“当前状态”和“后续步骤”。适用当前会话流程中的空部分规则。然后按照当前会话流程的步骤 5 宣布并展示，宣布内容需根据检查点上下文调整为 Handing off checkpoint <short-id> — <M> sessions, <total turns> turns total.。