ce-sessions

/ce-sessions

跨 Claude Code、Codex 和 Cursor 搜索会话历史，并综合总结之前会话中处理过、尝试过、决定过或学到的内容。

用法

/ce-sessions [question or topic]
/ce-sessions

预先解析的上下文

Git 分支（预先解析）： !git rev-parse --abbrev-ref HEAD 2>/dev/null || true

如果上面的行解析为纯分支名称（例如 feat/my-branch），则使用它筛选分支，并将其传递给综合分析子 Agent。如果该行仍包含反引号命令字符串或为空，则在运行时推导分支。

仓库根目录（预先解析）： !git rev-parse --show-toplevel 2>/dev/null || true

如果上面的行解析为路径，则取其最后一个路径组件作为仓库文件夹名称，并用它发现会话。如果该行为空或仍包含反引号命令字符串，则在运行时推导仓库名称。

注意：2026 年

当前年份是 2026 年。解读会话时间戳时请以此为准。

防护规则

这些规则在整个编排和综合过程中始终适用。

• 切勿将整个会话文件读入上下文。 会话文件可能有 1–7 MB。务必先使用提取脚本进行筛选，再据此分析。
• 切勿逐字提取或复现工具调用的输入／输出。 概述尝试了什么以及结果如何。
• 切勿包含思考或推理块的内容。 Claude Code 的思考块属于内部推理；Codex 的推理块已加密。两者都不具备可执行性。
• 切勿分析当前会话。 其对话历史已提供给调用方。
• 仅呈现技术内容，不涉及个人内容。 会话包含各种信息，包括凭据、挫败情绪和未成形的观点。请判断哪些内容适合纳入技术总结。
• 遇到访问错误时立即停止。 如果会话发现因权限问题失败，立即报告问题。不要换用不同工具或方法重试相同操作——反复重试只会浪费令牌，无法改变结果。

执行

如果没有提供问题参数，请询问用户想了解会话历史中的哪些内容。使用平台的阻塞式提问工具：在 Claude Code 中使用 AskUserQuestion（如果尚未加载其架构，请先调用 ToolSearch 并设置 select:AskUserQuestion），在 Codex 中使用 request_user_input，在 Gemini 中使用 ask_user，在 Pi 中使用 ask_user（需要 pi-ask-user 扩展）。仅当运行环境中不存在阻塞式工具或调用出错（例如 Codex 编辑模式）时，才退而使用纯文本提问；不能仅因需要加载架构而跳过提问。绝不可默默跳过提问。

第 1 步 — 确定扫描时间范围

根据用户的问题推断时间范围。先从较窄的范围开始；只有在较窄范围内找不到相关内容时才扩大范围。

信号	初始扫描范围
“今天”、“今天上午”	1 天
“最近”、“过去几天”、“本周”或未指定时间	7 天
“过去几周”、“本月”	30 天
“过去几个月”、功能的整体历史	90 天

Claude Code 默认将会话历史保留约 30 天。如果用户没有延长保留时间，扩大范围后可能仍找不到 Claude Code 会话。

第 2 步 — 发现会话并提取元数据

运行发现和元数据处理流程（保留以空值分隔的 xargs 加固处理，使 extract-metadata.py 能以批处理模式运行）：

bash scripts/discover-sessions.sh <repo> <days> | tr '\n' '\0' | xargs -0 python3 scripts/extract-metadata.py --cwd-filter <repo>

每行输出都是一个描述会话的 JSON 对象（平台、文件、大小、时间戳、会话，以及平台专属字段）。最后一行 _meta 包含 files_processed 和 parse_errors。

如果清单中的 _meta 行显示 files_processed: 0，则返回“没有相关的历史会话”并停止。

如果 parse_errors > 0，请说明有些会话无法解析，并继续使用已返回的内容。

要缩小平台范围，请在 discover-sessions.sh 调用中添加 --platform claude、--platform codex 或 --platform cursor。默认扫描全部三个平台。

步骤 3 — 筛选和排序

按以下顺序应用筛选条件，选出值得深入分析的会话：

1. 分支筛选（仅限 Claude Code）。 保留满足 branch == dispatch_branch（完全匹配）或分支名称包含问题主题关键词的会话（例如，关于“auth middleware”的问题匹配分支 feat/auth-fix、chore/auth-refactor）。Codex 会话不包含 gitBranch，跳过对它们的此筛选。

2. 如果分支筛选未返回任何会话，或正在处理 Codex 会话：

   • 从问题主题中提取 2-4 个关键词。对于“auth middleware 中近期发生的崩溃，session-validation 拒绝了有效令牌”，提取 auth,middleware,session,token（或类似关键词）。
   • 在 extract-metadata.py 调用中追加 --keyword K1,K2,...，重新运行发现流程。脚本会返回 match_count 非零的会话以及各关键词的计数。
   • 如果 files_matched: 0，则返回“no relevant prior sessions”并停止。 不要提取任何内容。
   • 如果 files_matched > 0，将这些会话视为候选项。按 match_count 排序，并以各关键词的计数作为并列时的排序依据。

3. 剔除扫描时间窗口之外的会话。 有 last_ts 时使用它，否则使用 ts。如果两者均早于窗口起始时间，则丢弃该会话。

4. 排除当前会话——其对话历史已可供调用方使用。

5. 应用深入分析上限。 所有平台合计最多选取 5 个会话。按分支匹配 → match_count → 文件大小 > 30KB → 最近时间依次筛选。

6. 仅在筛选后至少保留一个会话时继续。 否则返回“no relevant prior sessions”并停止。

注意：gitBranch 仅在第一条用户消息时采集。 某个会话可能始于 main，之后通过会话中途执行 git checkout 在功能分支上进行了实质性工作，但记录的仍是 branch: "main"。分支匹配未找到结果并不能作为确凿证据——因此步骤 2 要求使用关键词筛选作为回退方案。

步骤 4 — 设置临时空间

创建一个供本次运行使用的一次性临时目录：

SCRATCH=$(mktemp -d -t ce-sessions-XXXXXX)

记录绝对路径，并将其传入步骤 5 和步骤 6。会话结束时由操作系统负责清理；在步骤 7 末尾显式执行 rm -rf "$SCRATCH" 也无妨，还能明确表达清理意图。

步骤 5 — 提取每个会话的内容（通过文件传递）

对于每个选定的会话，运行骨架提取器并传入 --output，让内容直接写入临时文件——提取出的字节不会经由编排器的工具结果来回传递：

python3 scripts/extract-skeleton.py --output "$SCRATCH/<session-id>.skeleton.txt" < <session-file>

标准输出仅包含一行 JSON 状态（{"_meta": true, "wrote": "...", "bytes": N, ...}）。从每行状态中提取 bytes 和 parse_errors。

有条件地提取尾部内容——如果骨架提取在调查过程中途终止（最后一个可见回合是尚未解决的工具调用，或助手仍在调试但没有结论），则使用 tail 形状重新提取：

python3 scripts/extract-skeleton.py --output "$SCRATCH/<session-id>.skeleton.tail.txt" < <session-file>

（骨架脚本不直接接受 tail:N 上限；如果只需要查看尾部内容，可在提取后于 shell 中使用 tail -n 50 对临时文件进行后处理。仅当头部输出表明会话在调查过程中途被截断时才使用此方式。）

有条件地使用错误模式——对于可能值得了解调查如何走入死胡同的会话：

python3 scripts/extract-errors.py --output "$SCRATCH/<session-id>.errors.txt" < <session-file>

按需使用——仅当了解问题出在哪里确有价值时才使用。Cursor Agent 对话记录不会记录工具结果，因此错误模式对 Cursor 会话不会产生任何内容。

步骤 6 — 调度综合子 Agent

通过平台的子 Agent 原语调度 ce-session-historian 子 Agent（在 Claude Code 中为 Agent，在 Codex 中为 spawn_agent，在 Pi 中通过 pi-subagents 扩展使用 subagent）。省略 mode 参数，以应用用户配置的权限设置。使用中档模型运行（例如 Claude Code 中的 model: "sonnet"）——综合器不需要前沿推理能力。

调度提示词是该 Agent 的输入契约。传入以下字段：

• problem_topic — 用一句话说明具体问题。从用户的论述中提取；如果没有，则使用对无参数提示词的回答。
• scratch_dir — $SCRATCH 的绝对路径。
• sessions — 对象数组，每个对象对应一个提取出的会话，包含：
  • path — 骨架文件的绝对路径（提取了错误文件时，可选包含 errors_path）
  • platform — claude、codex 或 cursor
  • branch — 存在时填写 git 分支（仅限 Claude Code）
  • cwd — 存在时填写工作目录（仅限 Codex）
  • ts 和 last_ts — 会话时间戳
  • match_count 和 keyword_matches — 使用关键词筛选时填写
• output_schema — Agent 回复应遵循的结构。默认架构：

  Structure your response with these sections (omit any with no findings):
  - What was tried before
  - What didn't work
  - Key decisions
  - Related context
  

  当调用方（例如 ce-compound）在技能参数中提供架构时，原样传递。

调度形式示例：

Synthesize findings from these prior sessions:

Problem topic: <one-line topic>

Sessions to read (paths in $SCRATCH):
1. /tmp/ce-sessions-XXXX/abc123.skeleton.txt
   platform=claude branch=feat/auth-fix ts=2026-05-01
2. /tmp/ce-sessions-XXXX/def456.skeleton.txt  errors=/tmp/ce-sessions-XXXX/def456.errors.txt
   platform=codex cwd=/Users/.../my-project ts=2026-05-03
...

Output schema:
- What was tried before
- What didn't work
- Key decisions
- Related context

Filter rule: only surface findings directly relevant to this specific problem.
Ignore unrelated work from the same sessions or branches.

Agent 使用平台原生的文件读取工具读取各个路径，并返回文字形式的发现结果。批量提取的内容仅存在于子 Agent 的上下文中——编排器的工作状态仅保留文件路径和少量清单元数据。

步骤 7 — 返回发现结果

将综合器的输出文本原样返回给调用方。如果发现或关键词筛选结果为零个会话（步骤 2 或步骤 3），则返回字面字符串 no relevant prior sessions。

也可以清理临时目录：

rm -rf "$SCRATCH"

无论如何，操作系统最终都会处理清理；显式清理是为了满足希望主动清理的读者。

输出

当调用方（通常是输入 /ce-sessions 的用户，或通过平台的技能调用原语调用 ce-sessions 的其他技能）未指定输出格式时，添加简短标题，说明搜索了哪些内容：

**Sessions searched**: [count] ([N] Claude Code, [N] Codex, [N] Cursor) | [date range]

然后附上综合器以文字形式返回的发现结果。调用方提供架构时，严格遵循该架构，并省略默认标题。

时间预算

完整答案一旦可用就立即停止。几秒内得出有把握的“no relevant prior sessions”就是完整答案；不要为了填满时间而延长搜索。步骤 3 的结构性上限（最多深入分析 5 个会话）和步骤 5 的条件性尾部/错误提取，从设计上限制了运行时长。

错误处理

如果发现流程失败（例如无法读取主目录、权限不足），向调用方报告错误。不要使用 git log、文件列表或其他来源替代——本技能的约定范围是会话元数据和综合分析。

如果提取时 --output 写入失败（磁盘已满、权限不足），向调用方清楚说明错误，不要使用不完整的路径调度综合器。

如果任何脚本报告 _meta 中的 parse_errors > 0，则在调度提示词中注明提取不完整，然后继续；综合器会在发现结果中标记不完整。