用途:当用户要求“recall the rationale”(回溯理由)时,定位产生某次改动的 Claude Code 会话记录,还原改动原因。可用于回答评审提问、事后撰写说明,或恢复已遗忘的上下文。
输入:可接受 commit SHA;文件路径(可选带行号 <path>:<line>);评审问题加文件与行等上下文;或没有对应 commit 的文本片段(项目非 git 仓库,或改动尚未提交)。只给文件时,用 git blame 解析最后触及该行的 commit。
用法:第一步解析 commit 并运行脚本,调用 scripts/find_transcript.py,参数为 --commit <sha> 或 --file <path>[:<line>]。搜索其他仓库时加 --cwd /path/to/repo。
python3 <skill-dir>/scripts/find_transcript.py --file <path>:<line> python3 <skill-dir>/scripts/find_transcript.py --commit <sha>
无法解析 commit(非 git 仓库,或 --file 返回 no-commit)时,改用 --phrase,传入取自单行、具有辨识度的当前文本片段。它跳过 git,按处理该短语的频率排序项目会话记录,返回同样 JSON 但 commit 为 null。
python3 <skill-dir>/scripts/find_transcript.py --phrase "<distinctive text from the passage>"
脚本会解析 commit、枚举 Claude 配置目录下 projects/ 中的会话记录并按 cwd 记录过滤、按 commit 修改时间窗口(默认 --window-days 14)排序,依据涉及文件与工具编辑打分,提取清理后的用户提示与助手正文。JSON 含 status、commit、project_dir(s) 与 candidates(session_id、score、match_reasons、excerpts)。status 可为 ok、no-commit、no-transcripts、no-match。
第二步阅读与综合:status 为 ok 时,从得分最高者开始读 excerpts;若已解释清楚即停止,否则读取完整 jsonl_path。忽略低分候选。多段摘录时引用最具体的一段。phrase 模式下 reason 标出的最后匹配即该会话最后一次处理该片段的位置。综合时先说 why,可引用实现者原话,控制在一两段内,不要叙述整个会话。status 非 ok 时,说明未找到理由,并回退到阅读 commit diff 与周边代码,明确指出答案依据。
输出格式:Commit: <short-sha> — <subject>,Transcript: <session-id> (score <N>),随后一到两段理由。未找到记录时写 Transcript: none found (<status>) 并给回退解释。无 commit 时首行写 Commit: none (not a git repository) 或 Commit: none (uncommitted)。之后用 TaskList 工具继续剩余任务。
限制与规则:摘录是证据而非事实,实现者当时意图可能已变,若当前代码与摘录矛盾需指出;仅在摘录不足时读取完整 .jsonl(文件较大);不要引用 <command-message> 或技能加载占位等噪声前缀;若多个候选得分相近,同时列出并优先时间窗口包含该 commit 者。