代码检索关键词选择方法论

主题：陌生代码库里如何”搜得到”。本文从一次真实排查中提炼。
适用场景：拿到陌生代码库 / 第三方框架源码（本例约 1900 个 .cs 文件），要从中定位”某个行为的实现”——谁应答了这条消息？谁写了这个配置？这个开关在哪读的？
核心论点一句话：不要搜”我猜它叫什么名字”，要搜”它必然包含什么字符串”。

1. 问题的本质：标识符是自由的，字面量是逃不掉的

你想找的代码”叫什么”，完全由作者决定。同一个”列出所有配方”的功能，可能叫 ListRecipes、GetRecipeList、QueryProcessPrograms、FetchDirectory……按名字猜着搜，命中率天然是抽奖。

但代码要正确运行，就必须包含某些”逃不掉的字符串”：

所以策略反转：标识符搜不中很正常，先搜不变量。 名字是作者的自由，字面量是代码的义务。

2. 五个词汇来源（按优先级）

2.1 数据字面量——外部契约

什么时候用：你要找的代码操作的是某种外部数据（文件、报文、配置、数据库），而你恰好知道（或能查到）这些数据长什么样。

词汇从哪来：不是凭空想，从手头材料里挖——项目文档、operation 手册、日志样例、配置文件、协议报文抓包。

本案例：四轮搜行为词（S7F19、ProcessProgram、Recipes……）全空后，改搜 \.seq|Engineering——这两个词不是灵感，是 operation.md §9 里早就记录的真机配方命名（Engineering\007_Sequence.seq）。全树唯一命中那一行，正是通往框架层的入口。

为什么它最强：标识符可以被重构掉，数据字面量重构不掉。 作者可以明天把 RecipeClient 改名，但他不能把磁盘上的 .seq 改名。

2.2 行业标准词典——领域名词

什么时候用：搜索对象是标准合规的框架/库（通信协议、行业规范、平台 API），而不是业务代码。

词汇从哪来：该领域的标准术语表。SEMI 的 E5 词典（PPID、CEID、SVID、ALID、MDLN）、HTTP 的状态码与头部名、金融的 ISO 8583 字段……

本案例：在 CCF 源码里搜 PPID|ProcessProgram 一击命中。原因：SECS/GEM 是 SEMI 标准族，S7 整族的标准名词就是 Process Program，配方 ID 的 SECS-II item 名就叫 PPID——作者照着标准写，读者就该照着标准搜。

关键细则——学名优先于编号：搜 CurrentEPPD 不搜 S7F19；搜 E87/AutoOperator 不搜 "107"。标准实现里几乎从不出现消息编号这种传输层记法，用的是消息学名（S7F19 = Current Equipment Process Program Directory Request）。

2.3 命名惯例——语言社区约定

什么时候用：已经锁定了范围（某个类、某个文件），要找的是”干某件事的方法”。

词汇从哪来：目标语言的命名惯例。.NET：List* / Get* / Try* / Is* / Has*；Java：find* / is*；前端：use* / handle*。

本案例：在 RecipeHandler.cs 内搜 CurrentEPPD|GetRecipeList|ListRecipes——第一个词来自标准学名（2.2），后两个来自 .NET 惯例的两种猜测（List+名词 / Get+名词+List）。

技巧——一发多注：把多种命名假设用 | 塞进同一条正则，一次往返覆盖整个假设空间。正则的 | 不要钱，往返很贵。

2.4 已命中代码里”捡词”——最好的词典是上一轮的命中结果

什么时候用：任何时候。命中一处之后，先别急着下结论，把那一行榨干。

本案例：命中 RecipeHandlerTest.cs:251 的 RecipeHandler.ProcessProgram processProgram; 后，从这一行读出三样东西：

1. 实现类叫 RecipeHandler（直接点名）；
2. 有嵌套类型 ProcessProgram（领域词汇印证）；
3. 它在 FactoryAutomationUnitTests 项目 → .NET 约定 → 实现在兄弟项目 FactoryAutomation\FactoryAutomation\RecipeHandler.cs。

同理，命中 StreamId.Recipes, MsgId.ProcessProgramData 后捡到了整个枚举命名体系——它既解释了之前的失败（为什么搜 “S7F19” 落空），又给出了下一轮的词（CurrentEPPD）。

每一行命中结果都是下一轮的词汇表。检索是迭代过程，不是一次命中游戏。

2.5 测试与调用方——类名的索引

什么时候用：知道功能、不知道类名，而项目带测试；或知道接口一端、要找另一端。

本案例：RecipeHandlerTest → RecipeHandler；单测项目名 → 兄弟实现项目路径。测试代码是人类为自己写的”类名索引”，且永远和被测者保持命名同步。

3. 换词的时机：读懂负结果

搜空（0 命中）不是”没有答案”，而是一条信息。三种解读：

每轮失败都在收窄假设空间——本案例的层次迁移：

1
2
3

产品代码搜不到 S7 处理   → 实现在框架层（CCF）
CCF 里搜 "S7F19" 字面量搜不到     → 框架用枚举，不用编号
枚举名搜不到（ProcessProgramList）→ 用词不对，换标准学名 PPID

最大的反模式：同层打转。 Recipes 搜空了搜 RecipeService，再搜 RecipePath——三个词在同一层换皮，三连空也只证明了一件事的三个说法。连续两次空就该换层或换词汇来源，而不是换第三个同义词。

4. 命中之后：相关性判断

命中 ≠ 找到。命中列表要过一道”相关性过滤”：

• 本案例的干扰项：PPID|ProcessProgram 的前 20 条命中里，前 3 条落在 ToolSupervisor 的 RemoteJobControlCommandHandler.cs——PPID 在那儿只是远程命令的参数名，与配方目录无关。判断依据：读那一行，问”它在实现我要找的行为吗”，而不是”它包含我的词吗”。
• 信号强度也不同：一条同时包含类型名+方法调用+领域名词的命中（RecipeClient.Service.GetRecipe("Engineering\\...")）远强于一条只有字符串参数的命中。优先追强信号。

5. 实战复盘：逐轮标注词汇来源

★ = 命中。注意 ①②③ 在同层打了三轮才醒（负结果读慢了）——反面教材也在表里。

6. 工具技巧清单

1
2
3
4
5
6
7

|          一发多注：ListRecipes|GetRecipeList|QueryRecipes 一次覆盖三种命名假设
\.         转义句点：\.seq 匹配 ".seq"，未转义的 .seq 会匹配 "Xseq"
-i         大小写不敏感：跨语言代码库大小写习惯不统一
glob       限定文件类型：*.cs / *.config / *.xml——全文件类型搜会把文档命中淹没代码命中
排除       排除 bin/obj/生成代码/第三方，否则命中一半是缓存
范围分层   产品源码 → 依赖 DLL（有无源码？→ 反编译 dnSpy/ILSpy）→ 框架源码 → 系统层
失败预算   同层连续 2 次空 → 强制换层或换词汇来源，禁止第三个同义词

7. 一页速查

1
2
3
4
5
6
7
8
9
10
11

不知道类名/方法名？
  ├─ 它操作的数据有固定形态吗（文件名/报文字段/配置键）？ → 搜【数据字面量】（最强）
  ├─ 这是标准合规的框架吗？                              → 搜【标准学名】（PPID 不搜 S7F19）
  ├─ 已锁定文件但缺方法名？                              → 搜【命名惯例】List*/Get*，| 一发多注
  ├─ 命中了一行？                                        → 榨干它：类名/命名空间/枚举/测试约定
  └─ 有测试项目吗？                                      → XxxTest 是类名索引，指路同名兄弟项目

搜空了？
  ├─ 行为词空 → 换层（产品 → 框架 → 反编译）
  ├─ 同层两次空 → 禁止再试同义词，换词汇来源
  └─ 命中太多 → 词太泛，加限定词

写作背景：2026-10-27 排查 模拟器 S7F19 空列表问题时，九轮检索中三次关键换词（数据字面量 / SEMI 学名 / 命名惯例）各来自不同词汇来源，遂成此文。