what-happened

发生了什么

当用户希望了解某段代码的来源时，使用此技能。

支持的输入：

• path:line
• path:start-end
• path 加上从该文件粘贴的代码片段

如果用户提出含糊的来源问题，没有提供文件路径、行范围或粘贴的代码片段，请询问目标代码，然后停止操作；不要运行命令，也不要使用标头。

目标

找出与用户指定行匹配的最新更改块，列出匹配的提交哈希和检查点状态，然后使用最佳可用上下文概述每个代码块为何被更改。如果无法获取检查点关联的上下文，仍需明确说明当前代码的作用，并清楚标记该说明并非基于检查点。

规则

1. 不要猜测文件内容或行号。先确定确切的目标行，再进行任何说明。
2. 使用 PATH 中已安装的 entire 二进制文件，不要使用当前仓库中的 ./entire。
3. 优先使用 git blame 确认来源，并使用 entire checkpoint explain --commit 获取基于转录记录的上下文。此技能不要使用实验性的 entire why。
4. 此技能用于查询特定代码块的最新更改来源。若要了解某个符号、文件或功能的整体原始意图，请优先使用 explain 技能。
5. 不要手动搜索 .git/entire-sessions/ 或原始转录文件来查询提交来源。如果 entire checkpoint explain 无法提供转录上下文，请报告确切的缺失或不可用状态。
6. 如果有多个匹配的 blame 代码块，请包含所有不同的范围。运行 entire checkpoint explain 前先对提交哈希去重；每个唯一提交只查询一次转录，而不是每个范围都查询一次。扩展检查点转录前也要对检查点 ID 去重；每个唯一检查点只扩展一次，而不是每个提交或范围都扩展一次。
7. 明确区分以下状态：
   • 提交未引用任何检查点
   • 提交引用了检查点，但该检查点在本地或远程不可用
   • 检查点可用，但完整转录扩展失败，且用户未明确要求扩展原始转录
   • Entire 转录查询失败（entire checkpoint explain 命令本身出错）
   • 代码未跟踪、未提交，或因其他原因没有已提交的历史记录
   • 目标代码确定后，其他来源查询命令失败
8. 对每个已确定的代码块，提供基于检查点的历史，或说明当前代码作用的后备解释。将后备解释标记为“非基于检查点”，且不得暗示其意图或历史依据来自检查点。
9. 将 entire checkpoint explain 命令输出视为用于总结的中间材料。除非用户明确要求原始输出，否则不要将原始命令输出或完整转录粘贴到回复中。仅在有助于用户修复查询失败时，提供简短的错误摘录。
10. 最终说明应简洁并聚焦于代码块。不要概述文件中无关的部分。

工作流程

1. 确定目标代码块

如果用户没有提供文件路径和准确的行号／行范围，或没有粘贴代码片段，请让他们提供目标代码，然后停止。不要运行命令，也不要使用 Entire What Happened: 标题。

如果用户提供了 path:line 或 path:start-end，请直接使用该行或范围，并在解释前只读取文件中的目标内容。如果路径不存在、文件无法读取，或行号／范围超出文件范围，请明确说明并停止，不要使用 Entire What Happened: 标题。

如果用户提供了路径和代码片段：

• 从代码片段中选取最具辨识度的准确行，并使用固定字符串匹配在文件中搜索，查找候选位置：

grep -n -F -- "<distinctive snippet line>" "<path>"

• 读取每个匹配位置附近的小范围内容，而不是读取整个文件；除非文件本身已经很小，或搜索结果过多，无法高效检查。
• 在候选范围内查找准确的代码片段。
• 将匹配位置转换为 start-end 行号。
• 如果空白字符不同，但代码其余部分相同，请先规范化行首缩进和行尾空白，再判定代码片段是否不匹配。
• 如果代码片段出现多次，请说明存在歧义并列出候选范围，不要默默挑选其中一个。对于此类尚未解决的输入，不要使用 Entire What Happened: 标题。
• 如果找不到完全匹配的代码片段，请明确说明并停止，不要推断附近的匹配项。对于此类尚未解决的输入，不要使用 Entire What Happened: 标题。

2. 收集来源信息

只有在目标已解析为当前文件中的实际行号后，才能运行 blame。不要针对尚未解析的粘贴代码片段、推断出的附近代码块、符号名称或近似范围运行 git blame -L。

运行：

git blame --porcelain -L <start>,<end> -- "<path>"

如果命令因文件未跟踪而失败，请将整个目标范围标记为没有已提交历史记录的未跟踪文件，保留该范围的准确代码片段，并继续执行后备代码行为分析。

如果 blame 报告了未提交的伪提交（例如全零哈希或 Not Committed Yet），请将这些范围标记为本地未提交更改，不要对其运行 entire checkpoint explain。如果其他目标范围解析到了实际提交，则继续处理这些已提交范围。

使用输出找出目标范围内的所有 blame 代码块。如果相邻目标行对应同一个提交，且构成一个连续匹配块，请将它们合并。对每个匹配块，收集：

• 行范围
• 当前文件中该确切范围的匹配代码片段
• 提交哈希
• 作者／摘要（有助于说明来源或提供后备分析上下文时）

收集所有匹配块对应的唯一实际提交 SHA，同时保留每个不同的范围。排除未跟踪文件和本地未提交的伪提交。建立从提交 SHA 到该提交对应的所有目标范围的映射。对于多个共享同一提交的范围，不要分别运行 entire checkpoint explain。

如果解析后的目标范围涉及超过 5 个唯一实际提交，请在运行 entire explain 前停止。报告匹配范围，并请用户缩小范围或确认进行更深入的查询。对于此确认请求，不要使用 Entire What Happened: 标题。

保留目标解析时读取到的准确代码片段，以便最终答复能向用户展示每条来源信息所对应的代码。只有在尚未捕获某个范围的代码片段时，才重新读取该匹配块。

3. 解释每个唯一提交

对于映射中的每个唯一提交 SHA，恰好运行一次：

entire checkpoint explain --commit <commit-sha> --no-pager

如果有多个唯一提交，且 Agent 环境支持并行工具调用，请并行执行这些互不依赖的提交查询。

使用此输出回答问题并确定检查点状态。除非用户明确要求扩大失败查询的范围，否则不要使用 --search-all；它会移除分支和深度限制，可能运行较慢。

如果此命令失败，不要运行额外的提交元数据查询，也不要扫描原始会话文件。将该范围标记为需要进行回退代码行为分析，并报告 Entire 转录查询失败。只有在有助于用户解决问题时，才包含命令错误，例如身份验证或缺少远程配置。

如果提交视图显示了检查点 ID，但仍不足以回答用户的问题，请收集该检查点 ID 以便展开。运行检查点查询之前，先对所有提交视图中的检查点 ID 去重；如果多个提交引用同一个检查点，只展开该检查点一次，并将结果映射回所有相关范围。

对于每个需要进一步了解的唯一检查点 ID，运行：

entire checkpoint explain --checkpoint <checkpoint-id> --full --no-pager

不要自动展开原始转录。如果 --full 失败或信息不足，请将受影响的范围标记为需要进行当前代码回退分析，除非用户明确要求原始转录详情。仅在用户明确要求时，才运行：

entire checkpoint explain --checkpoint <checkpoint-id> --raw-transcript --no-pager

使用收集到的输出回答：

• Agent 试图做什么
• 此代码块为何发生变化
• 导致最终代码的约束、错误、边缘情况或重构压力

默认不要展示原始 entire checkpoint explain 输出。只总结与目标范围相关的部分。

如果提交没有检查点 ID，仅使用 entire checkpoint explain --commit 返回的提交级上下文说明来源，并将该范围标记为需要进行回退代码行为分析。明确说明“没有基于检查点的摘要；未引用任何 Entire 检查点。”

如果存在检查点 ID，但 entire checkpoint explain --checkpoint 无法加载该检查点，请在答案中保留检查点 ID，并说明“已引用检查点 ，但该检查点在本地或远程不可用。”只有在有助于用户解决问题时，才包含命令错误，例如身份验证或缺少远程配置。

如果检查点已加载，但 --full 失败，请说明检查点元数据可用，但完整转录展开失败。如果用户未明确要求原始转录详情，请说明未自动展开。根据 entire explain --commit 输出回答有检查点支持的事实；对于该输出无法支持的内容，使用当前代码回退分析。

将每个唯一提交的说明映射回所有归因于该提交的目标范围。

4. 必要时添加回退代码行为分析

对于落入规则 7 所列状态、且无法获得基于检查点上下文的任何已解析范围，仍需说明当前代码的行为。

仅使用有源代码依据的分析：

• 查看目标代码块及理解它所需的最小周边范围，例如外层函数、类型、导入项或常量。
• 仅当无法通过局部上下文理解代码块时，才使用 grep -n -F 检查直接调用点或定义。
• 说明可观察到的行为、输入、输出、副作用及重要分支。
• 不要将此分析表述为历史意图、检查点原因或 Agent 转录摘要。
• 说明仅凭当前代码无法确定的内容。

响应格式

首次成功解析代码的响应必须以此行开头，作为对此技能调用的响应：

Entire What Happened:

接着空一行，然后写入内容。

• 此标题仅用于本次调用中的首次成功解析代码的响应。 如果先前的响应因输入未解析而未包含标题，且用户之后消除了目标歧义，则在解析代码的响应中包含标题。本次调用中的后续轮次不要再次打印标题。
• 输入未解析的响应（例如，未找到代码片段、代码片段存在歧义、路径或范围无效）不得包含标题。如果已解析目标代码，但没有基于检查点的上下文，仍需使用标题，并明确将答案标注为当前代码回退分析，而非检查点摘要。
• 标题后面必须恰好包含一条简短、原创、非歌词的“Tell me why”句子，从以下示例中随机选择。不得引用、转述或模仿 Backstreet Boys 或其他歌曲的歌词。

允许的示例：

• Tell me why: the blame points here.
• Tell me why: the diff left a trail.
• Tell me why: the context starts here.

先用 Rule 7 中的状态，为每个范围写一条简短的来源摘要：

Entire What Happened:

Tell me why: the blame points here.

Matches
- <path>:<start>-<end> -> commit <sha> | checkpoint <id>
  ```<language>
  <matched code snippet>
  ```
- <path>:<start>-<end> -> commit <sha> | no Entire checkpoint
  ```<language>
  <matched code snippet>
  ```
- <path>:<start>-<end> -> commit <sha> | Entire transcript lookup failed
  ```<language>
  <matched code snippet>
  ```
- <path>:<start>-<end> -> commit <sha> | checkpoint <id> unavailable
  ```<language>
  <matched code snippet>
  ```
- <path>:<start>-<end> -> commit <sha> | checkpoint <id> metadata only, transcript expansion failed
  ```<language>
  <matched code snippet>
  ```
- <path>:<start>-<end> -> local uncommitted changes | no committed history
  ```<language>
  <matched code snippet>
  ```
- <path>:<start>-<end> -> untracked file | no committed history
  ```<language>
  <matched code snippet>
  ```

对于有基于检查点的上下文的范围，每个匹配块单独写一个简短小节：

Why
- <path>:<start>-<end>: <2-4 sentence explanation of why this block changed last time>

对于没有基于检查点的上下文的范围，改用此独立小节：

Current-code fallback (not checkpoint-backed)
- <path>:<start>-<end>: <2-4 sentence explanation of what the current code does, plus any
  limits on what can be inferred without checkpoint history>

代码片段指南：

• 优先使用文件中完全匹配的行。
• 代码片段应紧贴匹配块；除非需要，否则避免包含无关的周边代码。
• 如果代码块较长，请提供最小的连续摘录，确保用户仍能识别，并说明该摘录经过截断。

输入为粘贴的代码片段时，请在答案中注明解析出的行范围。

触发短语

以下问题应触发此技能：

• “这段代码到底怎么回事”
• “告诉我为什么这段代码是这样的”
• “告诉我为什么这段代码会是那样”
• “告诉我为什么这里改了”
• “这里发生了什么”
• “这段代码块怎么了”
• “为什么代码会是这样”
• “这段代码为什么看起来是这样”
• “为什么看起来很奇怪”
• “为什么要改这里”
• “为什么会有这个”
• “为什么要这样写”
• “这段代码背后的历史是什么”
• “帮我理解这段代码”
• “这里改了什么，为什么”

尤其是在用户包含以下内容时触发：

• 单个文件行号，例如 cmd/entire/cli/explain.go:103
• 文件范围，例如 cmd/entire/cli/explain.go:103-107
• 文件路径以及粘贴的代码片段