session-crosslink

Session Crosslink

响应格式

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

Entire Session Crosslink:

然后空一行，再输出内容。此标题仅用于本次调用的首次响应，后续轮次不要使用；错误或提前退出的响应（未解析到会话、未找到受影响的仓库）也不要使用。

停止 — 在执行任何操作前阅读以下规则

1. 在解析器／发现步骤运行之前，不要提出澄清问题。 通常可以通过 entire session current --json 的结果以及用户提供的信息，解析出会话 ID 和候选仓库列表。只有两者都为空时才提问。
2. 在展示预览表格之前，不要运行 entire session attach。 此技能的核心是先预览、再确认。attach 会修改目标仓库的 HEAD；预览错了，就会修改错误的提交。
3. 运行 entire session attach 之前，务必先 cd 到目标仓库。 CLI 会根据当前工作目录解析仓库。每次调用都使用一条 cd … && entire session attach … 命令，确保每次调用都针对正确的仓库。

必需的 CLI：entire 0.6.2+。无需特殊标志——此技能通过限定当前工作目录的 entire session attach 使用随附的 CLI。

流程

步骤 1：解析会话 ID

按顺序尝试以下策略，直到获得会话 ID。

策略 A：启用了 Entire 的当前工作目录。

entire session current --json

如果输出是有效 JSON 且包含非空的 session_id，则读取 session_id 和 agent，并使用这些值继续。如果 JSON 解析成功，但缺少 session_id 或其值为空，则视为策略 A 失败，并转到策略 B——不要在没有会话 ID 的情况下继续执行 attach。

策略 B：启用了 Entire 的同级仓库。 如果用户提到的仓库启用了 Entire（例如 the foo repo），则 cd 到该仓库，并重试 entire session current --json。会话状态保存在跟踪该会话的位置。

策略 C：特定运行时的转录文件目录。 如果策略 A 和 B 均无效，则 Entire 从未记录该会话，必须从 Agent 运行时读取：

• Claude Code： 转录文件位于 ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl。编码后的 cwd 是启动目录，其中的 / 替换为 -。项目目录下与 Agent 启动 cwd 匹配的最新 .jsonl 文件就是当前会话。读取去掉 .jsonl 后缀的文件名作为 session_id。将 agent 设为 claude-code。
• Codex： 检查 $CODEX_HOME/sessions/ 或 ~/.codex/sessions/。将 agent 设为 codex。
• 其他运行时： 向用户询问会话 ID。

记录 agent，以便步骤 4 将 --agent <name> 传递给 attach。

如果所有策略都失败： 输出“无法解析会话 ID——请明确传入会话 ID，或从启用了 Entire 的目录运行”，然后停止。

步骤 2：发现受影响的仓库

从以下来源汇总候选仓库，并按路径去重：

1. 来自用户消息： 用户明确提到的任何仓库路径或别名（例如“foo 仓库和 bar api”）。通过用户的 CLAUDE.md 解析别名，否则将其视为文件系统路径。

2. 来自启动目录下的同级仓库（仅当启动目录未启用 Entire 时）：列出含有自身 .git 和 .entire/settings.json 的直接子目录。

3. 来自本次会话中 Agent 的编辑历史： 根据 Agent 自身的上下文，找出本次会话中编辑过文件的任何仓库。如不确定，请询问用户。

对于每个候选仓库，在该仓库的工作目录中运行 entire status --json，并按以下规则处理：

• "enabled": true → 保留。
• "enabled": false，且出现设置解析错误（unknown field "..."）→ 保留。即使 attach 可以正常运行，状态检查也可能因本地设置配置错误而失败并输出错误信息。
• "enabled": false，且没有错误 → 丢弃。该仓库选择不使用 Entire。

如果候选仓库集合为空，请询问用户要交叉链接哪些仓库。

第 3 步：在本地计算预览

对于每个候选仓库，检查 git 和会话存储，以计算操作——使用与 entire session attach 内部相同的逻辑，但不修改任何内容：

# Get HEAD hash and message
HEAD_HASH=$(git -C <repo> rev-parse HEAD)
HEAD_MSG=$(git -C <repo> log -1 --format=%B HEAD)

# Existing Entire-Checkpoint trailer on HEAD, if any
EXISTING_TRAILER=$(printf '%s\n' "$HEAD_MSG" | grep -E '^Entire-Checkpoint:' | tail -1 | awk '{print $2}')

# Is the session already tracked in this repo's store?
STATE_FILE=<repo>/.git/entire-sessions/<session-id>.json

确定每个仓库要执行的操作：

• STATE_FILE 存在，且其 last_checkpoint_id 字段非空 → would_skip_existing_in_state。Attach 不执行任何操作；报告这一点。
• HEAD 中有 EXISTING_TRAILER → would_link_existing_in_head。Attach 会复用该检查点 ID，并将此会话添加到其中。
• 两者都不满足 → would_add_trailer。Attach 会生成一个新的检查点 ID，并将其添加到 HEAD。

对于 would_link_existing_in_head 行，检查点 ID 为 EXISTING_TRAILER。对于 would_add_trailer 行，无法提前知道检查点 ID——attach 会在写入时生成。在表格中显示“new”。

如果仓库中 HEAD 没有提交（git rev-parse 失败），则记录错误行：error: no commits yet。

第 4 步：呈现预览表

向用户显示一张简洁的表格：

repo                              HEAD commit   action                          checkpoint
foo                               a1b2c3d       would_add_trailer               (new)
bar                               e4f5g6h       would_link_existing_in_head     ckpt-7d6c
baz                               —             error: no commits yet           —

然后询问：“将会话 <id> 附加到 would_* 行吗？错误行和 would_skip_existing_in_state 行会跳过。”

第 5 步：确认后执行

对于用户确认且 action 为 would_add_trailer 或 would_link_existing_in_head 的每一行：

cd <repo> && entire session attach <session-id> --agent <agent> --force

跳过 would_skip_existing_in_state 行（在那里重新附加不会执行任何操作）和 error: 行。

捕获每个仓库的退出状态。报告最终摘要：

attached:
  foo    ckpt-9f8e  (new trailer on a1b2c3d)
  bar    ckpt-7d6c  (added to existing checkpoint on e4f5g6h)
skipped:
  baz    (no commits yet)
  qux    (already linked: ckpt-c97b)

提醒用户：attach 会修改 HEAD，因此每个被修改仓库的本地分支都会与远程分支产生分歧。如果这些分支有未合并的 PR，请执行强制推送（git push --force-with-lease）以更新它们。

失败情况

• 无法解析会话 ID：停止并显示一行消息——参见第 1 步。
• 没有候选仓库：询问用户要交叉关联哪些仓库。
• 所有候选仓库都报告 would_skip_existing_in_state：告知用户该会话已在所有仓库中关联；无需执行任何操作。
• 某个仓库的 attach 在运行中失败，而其他仓库已成功：不要自动重试。报告哪些仓库成功、哪些失败，并显示失败仓库的 stderr。成功完成的修改是幂等的——重新运行此技能是安全的。
• 候选仓库的 HEAD 没有提交：跳过该行，并标记为 error: no commits yet。告知用户先在该仓库中至少创建一次提交。
• entire session attach 失败并提示 Entire is disabled：目标仓库已选择退出。告知用户；不要重试。

此技能的用途

Entire 通过存储在每个仓库 git 公共目录下的状态，按仓库跟踪 Agent 会话。当 Agent 从更高层级的文件夹、同级仓库或未启用 Entire 的父级目录运行时，子仓库都无法看到该会话。此技能会从 Agent 运行时（其中始终包含会话 ID）解析会话 ID，发现受影响的仓库，逐个预览，然后在用户确认后对每个仓库运行 entire session attach——既不会修改错误的提交，也不需要用户逐个仓库手动执行 cd。