SuperAPI AI 工具集

recall-reasoning

编程与开发

查看项目

更新于 10-16 06:08

技能介绍

用途

Recall Reasoning 用于追溯某次代码变更背后的推理过程。它通过定位产生该变更的 Claude Code 会话记录(transcript),提取实现者当时的思考与理由。典型用途包括:回答审查者关于某处改动的提问、事后撰写变更说明,或恢复已遗忘的上下文。

输入

该技能接受以下任意一种输入:

  • 一个提交 SHA
  • 一个文件路径,可选带行号(<path>:<line>)
  • 一个审查者问题加上相关上下文(文件和行号)

如果只给出文件,则通过 git blame 解析最后修改该行的提交。

使用方式

第一步:解析提交并运行脚本

调用 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>

脚本执行以下操作:

  • 通过 git rev-parse 或 git blame 解析提交
  • 查找 ~/.claude/projects/<encoded-cwd>/(斜杠和点会变成短横线)
  • 对修改时间在提交前后 --window-days 天内的候选会话记录排序(默认 14 天)
  • 根据对涉及文件的提及和针对这些文件的工具使用编辑进行打分
  • 从排名靠前的候选中抽取清理后的用户提示和实质性的助手文本

JSON 输出包含 status、commit、project_dir,以及 candidates(含 session_id、score、match_reasons 和 excerpts)。

状态值:

  • ok — 返回了候选
  • no-commit — 无法解析提交
  • no-transcripts — 该仓库没有 Claude Code 会话记录目录
  • no-match — 存在会话记录,但窗口内没有与涉及文件匹配的

第二步:阅读并综合

如果状态为 ok:

  • 从得分最高的候选开始,先读其摘录。
  • 如果摘录已能解释该变更,就停止。如果摘录内容单薄或含糊,直接读取 jsonl_path 处的完整会话记录以获取更多上下文。
  • 忽略低分或远低于最高分的候选,它们是误报。
  • 当推理跨越多个摘录时,引用最具体的那一条。

综合出与所回答问题相关的简洁摘要:

  • 以“为什么”开头。差异本身已经展示了“是什么”。
  • 当实现者自己的话已经表达得很好时,直接引用。
  • 控制在一到两段,不要叙述整个会话过程。

如果状态不是 ok,报告未找到推理,并回退到阅读提交差异和周边代码。明确说明这一点,以便清楚答案是否仍然成立。

第三步:输出

按以下格式返回推理:

**Commit:** <short-sha> — <subject>
**Transcript:** <session-id> (score <N>)

<一到两段推理,必要时引用实现者原话>

如果未找到会话记录:

**Commit:** <short-sha> — <subject>
**Transcript:** none found (<status>)

<基于阅读提交和当前代码得出的回退解释>

然后使用 TaskList 工具,继续处理剩余任务。

规则

  • 将摘录视为证据而非绝对真相。实现者当时的意图可能已经改变。如果当前代码与某条摘录矛盾,指出这一差异。
  • 仅在摘录不足时才读取完整的 .jsonl 文件。这些文件很大。
  • 绝不要引用 <command-message> 或技能加载占位符之类的噪声前缀。脚本会过滤这些内容,但直接读取会话记录时仍需留意。
  • 如果多个候选得分相近且都很高,同时列出两者,并优先选择时间窗口包含该提交的那个。

适用场景

  • 回答代码审查中关于某处改动原因的提问
  • 为历史变更补写说明文档
  • 恢复已遗忘的开发上下文
  • 核对当前代码与当初实现意图是否一致

限制

  • 依赖 Claude Code 会话记录的存在,若记录缺失或不在时间窗口内则无法追溯。
  • 会话记录文件较大,完整读取需谨慎。
  • 摘录内容反映的是当时意图,可能与当前代码状态不符。
  • 关于收费、价格、平台支持范围等信息,资料中暂未提供。