GitHub Code Search：从跨仓定位到可审计候选集
搜到八处调用，不代表迁移只需要改八处
一个平台组准备淘汰 LegacyClient。负责人先在 GitHub 搜索框输入类名，得到八个仓库的命中，于是按八个仓库排了改造计划。第一批 PR 合并后，预发布环境仍有旧调用：一个仓库把适配器放在尚未合并的迁移分支，另一个生成目录没有进入索引，还有一个超大文件根本不在可搜索语料中。搜索结果没有撒谎，错误发生在团队把“当前账号、当前索引、默认分支返回的前若干结果”误读成了“组织全部代码”。
GitHub Code Search 最适合承担发现和收敛候选集：先限定仓库、组织、路径、语言和内容，再把命中交给仓库所有者复核。它不是构建系统，也不解析完整 classpath，更不会替团队证明动态调用、反射和生成代码已经清零。可靠的迁移从“这次到底搜索了什么”开始。
先把搜索入口跑通
GitHub.com 的新代码搜索是 GitHub 托管能力，不需要在开发机安装搜索服务，也没有可下载的 Blackbird 自托管发行版。使用者必须登录个人账号，即使只搜索公共仓库也是如此。进入 GitHub 顶部搜索框，输入查询后选择 Code；仓库页面里的搜索入口会自动带入仓库上下文。组织私库还要求当前身份本来就有仓库读取权限，搜索不会赋予额外访问权。产品入口和限制见 GitHub Code Search 概览。Tree-sitter 等组成部件是开源软件，不代表 GitHub.com 搜索服务本身可以按同一许可证私有部署；采购评审应核对 GitHub.com/GitHub Enterprise Cloud 或目标 GHES 版本的订阅条款，而不是从组件许可证反推产品许可。
第一次验证不要从一个宽泛类名开始。选择团队拥有、默认分支上存在已知标记的测试仓库，在文件 src/search-proof.txt 中放入：
SEARCH_PROOF_7F3A推送到默认分支并等待索引更新，然后搜索：
repo:your-org/search-lab content:"SEARCH_PROOF_7F3A" path:/src/可接受的证据是结果指向 your-org/search-lab 的默认分支、路径为 src/search-proof.txt，预览中包含完整标记。repo: 固定仓库，content: 阻止文件路径同名造成假命中，path:/src/ 固定目录。若只看到文件名却没有内容，应先检查是否遗漏 content:；不带限定词的普通词既可能匹配文件内容，也可能匹配路径。查询语法给出了这些限定词、布尔操作和正则表达式的准确行为。
这项网页验证不需要 Token、CLI、容器或本地守护进程。若团队脚本要求稳定输出，不应抓取搜索页面；页面排名、分页和界面都不是批处理合同。GitHub 确实提供 REST GET /search/code，GitHub CLI 的 gh search code 也调用代码搜索 API，但 CLI 官方手册明确说明它们仍由 legacy code search 驱动，结果可能与 GitHub.com 新代码搜索不同，也没有新搜索的正则等能力。网页查询和 API 查询必须作为两份不同的搜索合同保存，不能拿 API 的零结果证明网页索引清零。
查询字段会怎样改变候选集
把搜索式当成一份可评审配置，比在输入框里不断试词更可靠。一次淘汰旧客户端的候选查询可以写成：
org:your-org language:java content:/\bLegacyClient\s*\(/
NOT path:/generated/ NOT is:archived NOT is:forkorg: 决定仓库所有者范围；换成 repo:your-org/payment-api 会收窄到单仓。多个 repo: 必须用 OR 连接，而且仓库名不支持模糊匹配。language: 使用 GitHub Linguist 识别结果，它不是文件扩展名的简单别名；license:MIT 等 license: 值过滤的是 GitHub 识别出的仓库许可证，不证明某个文件、依赖或复制片段必然适用同一许可证。content: 只看内容；path: 可以匹配路径，并支持有限 glob 或斜杠包围的正则。is:fork、is:archived、is:generated、is:vendored 可显式纳入对应语料，NOT 则直接制造搜索盲区，所以每个排除条件都要写进迁移记录。
双引号匹配包含空格的精确字符串；斜杠包围的是正则。正则支持常见表达式，但不支持 look-around。symbol: 基于 Tree-sitter 提取的符号定义，只找定义，不找引用，也不是编译器级类型归因。它适合先定位 LegacyClient 定义，再用内容搜索寻找调用形态；重载、同名类型、反射字符串和依赖注入绑定仍要交给语言服务、编译器或结构化工具复核。
下面四条查询的结果不能互相替代：
repo:your-org/payment-api LegacyClient
repo:your-org/payment-api content:LegacyClient
repo:your-org/payment-api symbol:LegacyClient
repo:your-org/payment-api content:/\bLegacyClient\s*\(/第一条可命中路径或内容；第二条只证明文本存在；第三条只看受支持语言中的定义；第四条寻找一种调用外形。项目接入时应保存最终查询文本、执行身份、执行时的默认分支提交和排除项，而不是只保存截图中的命中数量。
API 与 CLI 要固定旧语法边界
先用 gh auth login 登录目标主机，再用一个已知公开或已授权仓库验证 legacy API 链路：
gh search code 'LegacyClient repo:your-org/payment-api' \
--match file --limit 100 \
--json repository,path,sha,url
gh api --method GET /search/code \
-f q='LegacyClient repo:your-org/payment-api in:file' \
-f per_page=100预期 CLI JSON 与 REST 响应都带仓库、路径和 blob SHA；私库查询还必须由当前 Token 对目标仓库具有最小只读访问权。脚本不得把 Token 写进 URL、命令历史、日志或缓存文件，组织启用 SSO 时还要验证凭据已获组织授权。代码搜索有独立速率额度，可通过 gh api /rate_limit --jq '.resources.code_search' 观察；遇到限流应按响应头退避，不能并发重试放大压力。
这条链使用 legacy 语法，适合可机器读取的候选采样，不支持网页新搜索的 content:、symbol:、布尔括号和斜杠正则合同。脚本必须分页并记录 in:file、仓库范围、执行身份、API 版本和截断状态；即使取完 API 可返回的页面，也仍要针对默认分支、索引资格和独立速率限制做本地复核。需要新搜索语义时，保留网页搜索证据或克隆精确提交后运行本地工具，不要偷偷把查询翻译成另一套语法。
两组实验揭开零结果和满页结果
先做默认分支反例。在 migration/search-proof 分支新增 BRANCH_ONLY_PROOF，推送但不合并，执行：
repo:your-org/search-lab content:"BRANCH_ONLY_PROOF"预期是代码搜索没有命中；这不是标记不存在，而是 GitHub.com 代码搜索只索引仓库默认分支。直接打开该分支文件可以证明对象存在。把提交合并到默认分支后重复查询，待索引更新后应出现结果。若迁移要覆盖未合并分支，可靠入口是克隆目标引用后本地搜索，不能把线上零命中当成清零证据。
再做索引排除反例。将同一个标记分别放入普通 UTF-8 小文件、生成文件、二进制文件和超大文本文件。GitHub.com 当前公开限制会排除 vendored 与 generated 代码、空文件、二进制、非 UTF-8 文件、超过索引大小限制的文件以及部分超大仓库；超长行还会被截断。查询只命中普通文件是符合索引合同的结果。具体大小和行长限制可能演进，执行重大清点前应重新查看 Code Search limitations，并用本地克隆补查被排除语料。
同样要验证结果上限。GitHub.com 新代码搜索最多展示 100 个结果，并且不支持穷举或结果排序。看到五页结果时，证据只能写成“查询达到展示上限”，不能写“共有 100 处”。把大查询按仓库、路径、语言或组件责任域切成互斥分片；每个分片低于上限后，再对仓库默认分支执行本地复核。相同内容还可能被折叠，需要在结果页展开 identical files。分片的并集是候选集，不是运行时调用图。
fork、submodule 与 LFS 要单独做语料盘点。fork 是独立仓库，NOT is:fork 会主动排除它；纳入 is:fork 也可能因相同 blob 折叠而只显示少量结果，必须展开 identical files 并按 fork 仓库清单复核。父仓库里的 submodule 只保存 gitlink 提交和 .gitmodules 配置，不把子仓库源码复制进父仓库索引；应解析 .gitmodules，逐个确认子仓库主机、精确提交和当前身份，再分别搜索或克隆。Git LFS 在 Git 树中保存的是小型指针，真正的大对象位于 LFS 存储；代码搜索最多命中指针文本，不会替你搜索对象内容。Git LFS 说明可以用来确认这一对象边界。需要检查 LFS 内容时，只在获准环境运行 git lfs fetch/git lfs checkout，并把下载流量、磁盘占用和敏感数据落盘纳入审批与清理。
私有仓库必须做双身份验证
私有仓库会被索引，但结果只返回给已经拥有该仓库访问权的人。准备一个不含真实业务数据的私有测试仓库和两个测试身份：A 能读取仓库，B 不能读取。两者登录后执行同一条带完整 repo: 的唯一标记查询。A 应看到命中并能打开文件；B 不应看到代码，也不应依靠错误文案推断仓库是否存在。随后撤销 A 的仓库权限，再验证文件和搜索结果都不可访问。
这组实验同时检查两个问题：搜索服务是否按当前身份过滤，离职或转组后的权限回收是否真正传播。不要把个人访问令牌贴进查询、保存搜索标题、截图或工单；网页交互本身不需要额外 Token。审计材料保留查询、账号角色、仓库可见性和结果特征即可，代码片段要脱敏。
项目真正接入时，可以在迁移 ADR 或 issue 中维护一份“搜索合同”：目标组织和仓库清单、默认分支提交、网页或 legacy API 引擎、查询文本、排除目录、fork 策略、submodule 提交、LFS 补查状态、达到上限的分片、仓库 owner、线上搜索结果与本地补查结果。PR 模板要求变更者附上旧查询和合并后的复查查询。这样 GitHub Code Search 负责发现，仓库内编译、测试、静态分析和运行观测负责证明行为没有被误伤。
GitHub.com 与 GHES 是两套运行事实
GitHub.com 的新代码搜索由 GitHub 托管。官方工程说明显示其 Blackbird 引擎为代码构建 n-gram 索引，以 Git blob 身份分片和去重，查询协调层解析查询并追加权限与范围条件；符号信息另行提取。这个机制解释了为什么子串和正则很快、相同 blob 可复用存储，也解释了为什么排名和展示上限不能承担穷举证明。实现细节见 GitHub 新代码搜索技术说明。
GHES 则随所部署的 Enterprise Server 版本提供搜索能力。实例使用 Elasticsearch 驱动搜索，企业所有者可以在站点管理界面查看、创建、修复索引，并独立启停源码搜索与索引。其查询语法、文件大小、仓库数量、归档与 fork 限制应查看目标 GHES 版本的 Searching code 文档，不能把 GitHub.com 新代码搜索的 content:、symbol:、100 结果上限或索引排除表直接复制过去。GHES 搜索索引管理也说明了 Elasticsearch、修复任务与源码搜索开关的管理职责。
遇到 GHES 零命中时，开发者先确认默认分支、文件资格和仓库权限；实例管理员再确认 Searching 与 Indexing 都已启用、索引可搜索且可写、修复任务没有持续失败。关闭 indexing 后旧数据可能仍可查但新提交不再进入索引；关闭 searching 则查询入口不可用。恢复时先修复并追平索引，再开放查询，避免把陈旧结果包装成实时事实。
容量、成本与长期治理
GitHub.com 把索引基础设施成本包含在托管服务中，团队仍承担账号与企业能力、API 限流、网络出口、人工复核、submodule 展开和 LFS 下载的成本。GHES 还要承担 Elasticsearch 存储、CPU、内存、备份、升级、修复任务和容量增长。不要写死套餐或金额；启用私库搜索、企业限定词或部署 GHES 前，应在当前官方产品页和目标版本文档核对可用能力、许可、支持生命周期和数据驻留要求。
治理重点不是建立越来越多的“万能查询”，而是让搜索合同有 owner 和失效条件。仓库改默认分支、生成目录规则变化、GitHub 或 GHES 升级、权限模型调整、查询触顶、索引修复后，都应重跑已保存的正例标记、分支反例和双身份权限实验。高敏感组织可以把查询文本视为元数据，因为类名、路径和错误字符串本身可能暴露系统结构；分享搜索 URL 前先检查其中是否包含客户名、内部域名或密钥片段。
清理测试时，删除唯一标记文件并合并到默认分支，删除临时分支和测试仓库，撤销测试成员权限，删除保存的搜索与脱敏截图；本地补查还要删除 submodule 工作树、LFS 对象缓存和 API 临时 JSON，并吊销实验 Token。验收不是要求标记立刻从所有缓存消失，而是确认默认分支不再含测试数据、测试身份不再拥有仓库访问权，并在索引更新后查询不再返回标记。若线上迁移需要退出 GitHub Code Search，只需移除团队模板与保存查询；代码仓库仍可由本地搜索或其他索引平台复核，不应留下搜索专用高权限账号或长期 Token。