using-entire

使用 Entire

探索或理解代码时，默认应当：阅读记录下来的意图，不要猜测。

Entire 检查点会捕获每次 Agent 驱动的更改背后的提示词、对话记录和决策。需要了解代码为何存在或某个模块如何演变时，请先查阅检查点历史。只有在没有历史记录时，才根据代码结构进行推断，并明确标注这一点。

此技能何时激活

遇到以下任务时，请使用此技能：

• 请求表述为“研究 X”“调查 X”“了解 X”“深入研究 X”或“查明 X 如何运作”
• 探索或理解不熟悉的模块或文件
• 准备重构、扩展或调试并非由你编写的代码
• 回答“为什么要这样设计？”或“原本的意图是什么？”
• 在进行更改前开展研究工作
• 任何有助于了解历史背景的代码库探索

对于研究或调查类请求，第一步必须通过 search 技能执行 entire search。不要先打开源文件或运行 grep；记录下来的历史会说明之前尝试了什么以及原因，之后再阅读代码进行确认。

对于简单、明确且你已完全了解背景的编辑（例如“在第 5 行添加注释”），不要使用此技能。

第一步：检查仓库状态

开始具体查找前，先检查 Entire 是否可用，以及仓库是否有检查点历史：

entire status

这可以告诉你 Entire 是否已启用、安装了哪些 git 钩子、元数据分支是否已初始化，以及当前分支上是否有活跃会话。

场景路由

此技能激活时，请判断哪项子技能最符合用户需求：

场景	用户常见表达	委派给
代码块来源	“为什么要这样设计？”/“到底发生了什么？”/“src/auth.ts:42 发生了什么？”/“告诉我为什么改了这里”	what-happened
研究或调查主题	“研究 X”/“调查 X”/“了解 X”/“深入研究 X”/“我们对 X 有哪些了解？”	先用 search，然后视需要使用此技能的探索流程
查找以往工作	“以前有人做过 X 吗？”/“搜索过去关于速率限制的工作”/“找出之前的实现”	search
回忆任务操作指南	“以前做过这个吗？”/“回想一下我们怎么做 X”/“上次我们是怎么做的？”	recall
重现功能历史	“重现 ”/“带我了解 X 是如何构建的”/“展示 Y 的开发历程”	replay
讲解仓库主题	“教我 ”/“这个仓库中的 如何运作？”/“给我讲解一下 X”	teach
理解原始意图	“解释这个函数”/“解释 parseConfig”/“src/auth.ts 背后的意图是什么？”	explain
生成简报/摘要	“总结近期工作”/“生成简报”/“这周完成了什么？”	直接运行 entire dispatch
基于意图上下文进行代码审查	“审查这些更改”/“审查这个分支”/“合并前进行审计”	review
移交给其他 Agent	“移交此会话”/“在另一个 Agent 中继续”/“接续 codex 会话”	session-handoff
将会话转换为技能	“把它变成技能”/“根据此会话创建技能”	session-to-skill
将会话关联到其他仓库	“将会话关联到其他仓库”/“将会话附加到 foo 仓库”	session-crosslink
一般探索	“理解这个模块”/“探索 auth 的工作原理”/“帮我了解这个代码库”	(自行处理——见下文)

如果场景明确对应某项子技能，请完全遵循该技能的工作流程进行委派。不要在此重复其步骤。

通用探索流程

当没有适用的特定子技能时——例如用户要求“理解此模块”或“探索身份验证的工作原理”——请使用此流程：

1. 识别目标区域中的关键文件（入口点、主要类型、核心函数）。

2. 检查每个关键文件是否有检查点覆盖：

git log --format='%H %s' -5 -- <file>

查找提交正文中的 Entire-Checkpoint: 结尾标记：

git log --format='%H %b' -5 -- <file> | grep -B1 'Entire-Checkpoint:'

3. 阅读已覆盖提交的意图——从结尾标记中提取检查点 ID，然后使用 JSON 输出以便非交互式使用：

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

如果你只有提交哈希（没有检查点 ID），请使用：

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

4. 综合分析：结合记录的意图（来自检查点）与当前代码结构，建立全面的理解。

5. 报告你的发现，并明确区分：

   • 有检查点记录文本支持的事实（标记为“记录的意图”）
   • 仅根据代码推断出的观察（标记为“根据代码推断”）

AI Agent 使用说明

在 Agent 子进程中运行 Entire 命令时：

• 对支持 --json 且可能交互式提示的命令，始终传入 --json。--json 表示使用非交互式输出。
• 始终传入 --no-pager，以防止在子进程环境中启动分页器。
• 对 entire checkpoint explain，始终指定 --checkpoint <id> 或 --commit <sha>——如果不指定定位参数，命令会回退到交互式选择器。

没有检查点时

如果目标代码早于 Entire，或没有检查点覆盖：

1. 明确说明：“此代码没有可用的 Entire 检查点历史记录。”
2. 按标准方式理解代码（阅读源代码、检查 git log、追踪调用位置）。
3. 将所有说明标记为“根据代码推断——没有记录的意图支持”。
4. 如果用户希望了解更深入的历史记录，建议使用相关关键词进行 search——即使特定文件没有直接覆盖，也可能存在与相关工作有关的检查点。

透明度原则

始终明确说明你的回答依据是：

• 有检查点记录支持的历史——你阅读了实际会话记录文本，并了解开发者陈述的意图
• 代码推断——你分析了代码结构，并据此推断可能的意图

切勿将推断出的意图说成记录在案的事实。此工作流的核心价值就在于区分两者。

参考资料

如需深入了解子技能未涵盖的 Entire 功能，请参阅以下资源：

• CLI 帮助：运行 entire help 查看所有可用命令和标志
• 文档：https://docs.entire.io/llms.txt — 面向 AI 的文档索引，遵循 llms.txt 标准，旨在供大模型和编码 Agent 直接使用