search

搜索检查点和代码

使用 entire search 通过混合（语义 + 关键词）搜索查找以前的检查点、提交和会话，或使用 entire search --code 搜索各个仓库中的代码内容。需要先运行 entire login。切勿在不带 --json 的情况下运行 entire search——它会打开交互式 TUI。

执行环境（必需）

在 macOS 上，entire 会从本地密钥存储中读取凭据，而 Codex 沙盒无法访问该存储。此技能中使用的每条 entire 命令都必须在沙盒外首次尝试时运行。在 Codex 中，调用 shell 工具时设置 sandbox_permissions: "require_escalated"，并简要说明该命令需要访问用户的本地 Entire 凭据。此要求适用于 entire search 和 entire checkpoint explain。

不要先在沙盒中尝试运行 entire 命令，也不要将沙盒导致的凭据错误视为用户需要登录的证据。只有在沙盒外运行命令后报告需要身份验证。

响应格式

首次响应此技能调用时，以如下行开头：

Entire Search:

然后空一行，再接正文。

• 此标题仅用于本次调用的首次响应。在同一调用中的后续轮次（例如用户回答澄清问题后）不要再次打印。
• 出错或提前退出时（例如“未安装 Entire CLI”“需要身份验证”“没有匹配项”），不要包含此标题。只有在技能成功运行并生成实际结果时，才应显示该标题。

适用场景

• 用户提出“我们以前做过这个吗？”、“搜索过去的工作”、“查找之前的实现”或“查找关于 X 的检查点”等请求
• 需要从其他分支、仓库、作者或近期时间段查找先前的上下文
• 希望先找到可能的匹配项，再深入阅读最佳匹配项的完整记录
• 用户想要跨其有权访问的仓库查找代码，例如“X 是在哪里实现的？”、“在我们的其他仓库中查找 Y 的用法”——使用代码搜索（--code）

不要将此用于当前活跃会话。请改用 session-handoff。若要搜索当前工作副本中的文件，优先使用本地工具（grep、ripgrep），而不是代码搜索。

流程

1. 使用紧凑 JSON 输出执行有针对性的搜索：

entire search "<query>" --json --compact --limit 5

每条紧凑搜索结果都包含 id、type（checkpoint、commit、session、repo 或 pr）、repo、branch、author、date、截断后的 title、匹配的 snippet、filesTouched 和相关性 score，绝不包含完整提示词。结果按相关性排序；只有当前五条没有合适结果时，才提高 --limit（每页数量）或添加 --page（从 1 开始）。

如果 CLI 将 --compact 拒绝为未知标志（0.10.0 之前的版本），请去掉它并保留 --limit 5——不使用 --compact 时，每条结果都会嵌入完整提示词，因此默认一页可能达到几十 KB。

当用户已经提供筛选条件，或首次搜索范围过宽时，添加筛选条件：

entire search "<query>" --json --compact --limit 5 --repo owner/name --branch branch-name --author "Name" --date week

• --repo 可以指定多个仓库：重复使用该参数或用逗号分隔（--repo a --repo b、--repo a,b）
• 也可以在查询中内联筛选条件：author:<name>、date:<week|month>、branch:<name>、repo:<owner/name>、repo:*
• 默认只搜索当前仓库。要搜索所有可访问的仓库，请传入 --all-repos，在查询字符串中写入 repo:*，或传入 --repo '*'（加引号）。--repo repo:* 无效——内联标记不能放在标志的值中。

2. 查看排名靠前的结果，并向用户总结可能符合条件的候选项。除非用户要求，否则不要直接输出原始 JSON。如果某条结果的 title、snippet 和 filesTouched 已经回答了问题，就直接作答——除非用户要求详情或排名靠前的结果含糊不清，否则不要运行 explain。优先考虑 checkpoint 和 commit 结果；session 结果是同一批 checkpoint 的投影。

3. 要深入查看某条结果，请将其 id（checkpoint ID 或 commit SHA，会自动检测）传入：

entire checkpoint explain <id> --no-pager

• 添加 --full 以获取 checkpoint 的完整 session 转录；如果 --full 失败，则改用 --raw-transcript
• 对来自其他 GitHub 仓库的 checkpoint 结果，添加 --repo <owner/name>——这需要使用结果中的完整 checkpoint id，且该 checkpoint 必须已推送。如果该标志为未知（0.10.0 之前的版本）或 explain 未找到内容，请勿重试——直接根据紧凑字段作答
• 对当前分支上的 session 结果，使用 entire checkpoint explain --session <id> 进行关联，该命令会列出该 session 的 checkpoint；然后 explain 其中一个
• repo 和 pr 结果（以及来自其他仓库或分支的 session 或 commit）无法使用 explain——仅根据紧凑字段进行总结

代码搜索

添加 --code，改为搜索代码内容，而不是 checkpoint：

entire search "<query>" --code --json

使用标志指定范围并进一步筛选：

entire search "<query>" --code --json --repo owner/name --limit 20 --case-sensitive

• 默认情况下，结果仅限当前仓库；添加 --all-repos（或 repo:*）可搜索用户有权访问的所有仓库，也可以使用 --repo 列出仓库
• --case-sensitive 仅适用于 --code
• --limit 是代码搜索的结果总数（不是每页数量）
• --author、--branch、--date、--page 和 --compact 是 checkpoint 搜索选项——不要与 --code 一起使用
• 将结果显示为包含匹配片段的文件路径；除非用户要求，否则不要直接输出原始 JSON

代码搜索启发式

• 搜索有辨识度的标记：函数名、错误字符串、配置键——不要搜索自然语言描述
• 优先使用精确标识符，而不是部分单词；如果标识符的大小写很重要（例如 HttpClient 与 httpclient），请添加 --case-sensitive
• 如果用户指定了仓库，则用 --repo 限定范围；如果代码可能位于其他仓库，则先用 --all-repos；否则先搜索当前仓库，若未找到结果，再用 --all-repos 扩大范围
• 如果查询范围过宽，请在提高 --limit 之前添加第二个有辨识度的词，或提高查询的精确度
• 如果代码搜索失败或报告跳过了某些区域，请将结果视为不完整：使用 ripgrep/grep 搜索本地检出的仓库，或搜索此前涉及该代码的 checkpoint

搜索策略

• 从用户的领域术语、功能名称、错误文本、文件名或工单 ID 开始搜索
• 优先缩小搜索范围，再增大 --limit
• 需要指定仓库范围时，明确添加 --repo 或 repo:*
• 只要答案可能位于当前仓库之外（例如基础设施或部署仓库、技术栈中的其他服务、跨整个服务群的更改），就使用 --all-repos 扩大搜索范围，不要等到没有结果时才这样做
• 如果没有有用的结果，按以下顺序扩大搜索范围：移除分支筛选条件、扩大日期范围、简化查询词、添加 --all-repos

故障情况

• 如果搜索提示需要身份验证，告知用户运行 entire login
• 如果搜索提示“目前无法搜索此仓库”，说明该仓库尚未建立索引，或其所有者尚未启用语义搜索——请报告这一情况，而不是重试
• 如果没有匹配项，请明确说明，并提及尝试过的筛选条件或查询词
• 如果用户确实需要当前会话，请切换到 session-handoff，而不是搜索检查点