把已有 Semgrep 规则移植到其他语言时…

当你已有一条 Semgrep 规则，需要把它移植到一个或多个目标语言并保证每条变体都通过测试时使用。

适用场景

解决思路

1. 优先以工作流方式运行：调用 `/semgrep-rule-variant-creator:port-rule-to-languages`，传入三个必需参数，以及可选的 `outputDir`（默认当前工作目录，在仓库内通常不是你想要的）。
2. `languages` 每个条目只写一种语言：`"Go and Java"` 会被当成一个名为该短语的单一语言，脚本会拒绝。
3. `referencesDir` 必须是已解析的绝对路径，工作流脚本无法展开变量。按顺序尝试，先命中者为准（`-d` 是关键，裸 `ls` 只会打印目录内文件名）：1) Claude Code：`ls -d -- "${CLAUDE_PLUGIN_ROOT}/skills/semgrep-rule-variant-creator/references"`；2) Codex：把变量换成 `${CODEX_PLUGIN_ROOT}` 的同一命令；3) 两者都未设置：`find ~/.claude ~/.codex . -type d -path '*/semgrep-rule-variant-creator/skills/*/references' -print -quit 2>/dev/null`。
4. 用 `ls -1 -- "<that path>"` 确认打印出的目录里同时包含两个参考文件。
5. 按打印出的路径原样传入。若三次都为空就停下并说明，不要手工拼路径：脚本会拒绝相对路径和未展开的 token，但一个恰好不存在的绝对路径能通过所有校验，随后会在完全没读到指导的情况下把每种语言都报告为通过。
6. 传入参数 JSON：`rulePath`（被移植规则的路径）、`languages`（如 `["Go", "Java"]`）、`referencesDir`（上面 `ls` 打印的绝对路径）、`outputDir`（变体目录落点）。
7. 规则以路径而非文本形式传递：每个阶段都读取该文件，因为让 agent 逐字复述规则并不可靠（一个 HTML 转义的 `<` 和 `>` 就会破坏下游所有阶段的 `<... ...>` 操作符）。
8. 若运行在会话仍存活时被中断（你手动停止，或 agent 遇到终止性错误），用 `Workflow({scriptPath: "…", resumeFromRunId: "<runId>", args: {…}})` 重新启动，并再次传入相同参数；参数不会随运行保存，省略参数会在重放前就通不过预检。
9. 注意 resume 仅限同一会话：会话限额会结束会话，而运行记录存在该会话自己的目录下，下个会话无法访问。无法解析的 run id 也不是错误——工作流会以该 id 从头开始并全量重跑所有语言，且不会有任何提示。
10. 依赖 resume 前先确认 run id 还在：`ls -d ~/.claude/projects/*/*/subagents/workflows/*/`。这是当前运行记录的落点而非文档化接口，空结果可能意味着布局变了而非运行没了；两种情况下安全做法相同：无法确认 id 或会话已结束，就用相同参数重新调用并把 `outputDir` 指向新位置。
11. 注意脚本从不删除目录：第二次运行中翻转为 `NOT_APPLICABLE` 的语言，会留下第一次运行的变体。
12. 脚本位于插件根目录的 `workflows/port-rule-to-languages.js`，它为每个阶段固定推理强度（读规则便宜，翻译和修到绿最高），并编码了阶段顺序，使规则不可能先于规定它的测试被写出。
13. 脚本把两个没有 oracle 的决策排除在单个 agent 之外：`NOT_APPLICABLE` 判定在丢弃该语言前交给独立 refuter 复核；验证失败最多重试三次，而不是信任单个 agent 迭代到绿。
14. 仅在移植到单一语言且想留在环中，或移植已半完成只需一个阶段时，才手工运行各阶段。工作流是移植唯一需要的委派：一个 agent 读规则，每种语言在首次即绿时四个 agent——被反驳的判定加一个，每次验证重试也加一个。其他环节都不够大或独立，不值得单独开 agent，所以手工跑阶段意味着自己动手而非交给子 agent。
15. 阶段 1 适用性分析：判断该模式是否属于目标语言——漏洞类是否存在、每个 source/sink/sanitizer 是否有等价构造、移植后的规则是否会检测真实风险而非表面语法匹配。判定为 `APPLICABLE`、`APPLICABLE_WITH_ADAPTATION` 或 `NOT_APPLICABLE`。`NOT_APPLICABLE` 是下游无法反驳的判定（不产生测试、规则和目录），因此行动前要第二意见。
16. 阶段 1 另需单独用 Semgrep 回答：Semgrep 能否读取该语言？Perl 没有前端，Elixir 的解析器是 Pro 专属；这两种情况下漏洞类存在但规则无法评分——这与 `NOT_APPLICABLE`（声称漏洞类不存在）是不同的结论。参见 [applicability-analysis.md]({baseDir}/references/applicability-analysis.md) 中每种判定的实例。
17. 阶段 2 测试创建：先用目标语言的地道代码写测试文件。至少两个 `ruleid:` 用例和两个 `ok:` 用例，每个注解紧贴其所评代码的上一行。要包含该语言自身正确做法的安全形式，因为那正是移植最常引入的误报。
18. 阶段 3 规则翻译：dump 目标语言的 AST 并对照它翻译，因为模式形状取决于 AST 形状而非源码相似度。保留原规则的检测意图和模式；把 id 改为 `<original-id>-<language>`，改 `languages` 键，并添加 `original-rule` 和 `ported-from` 元数据。参见 [language-syntax-guide.md]({baseDir}/references/language-syntax-guide.md)。
19. 阶段 4 验证：`semgrep --test` 是验收标准，必须报告所有测试通过。漏报行说明模式比漏洞窄，误报行说明比漏洞宽。测试文件就是规格，要改规则去满足它。测试仍失败就停下意味着该语言未完成。参见 [workflow.md]({baseDir}/references/workflow.md) 了解如何读测试失败，以及模式不匹配或污点不传播时的排查。
20. 验收标准是读取规则时记录的那个特定 Semgrep 版本。换二进制去换绿正是要防的失败——有 agent 因 Elixir 测试不过而装了最后一个带 Elixir 解析器的 OSS 构建，并为在这里是红的移植报告了真实的 "All tests passed"。另外两种绿毫无意义：Semgrep *跳过*的规则也会以 "All tests passed" 结束，测试文件扩展名与规则语言不关联时也一样，因为两者都评了零个测试。
21. 输出：每个适用语言一个目录，内含移植后的规则和测试文件，例如 `python-command-injection-go/` 下有 `python-command-injection-go.yaml` 和 `python-command-injection-go.go`。
22. 把 `All tests passed` 仅当作规则与测试文件彼此一致的证据，而非漏洞类在目标语言可利用的证据（同一循环写了二者），因此把完成的变体当作待评审候选而非已验证规则。
23. 只把交给你的规则移植到你被要求的语言。不要修复原规则、不要扩大到邻近漏洞类、不要添加没人指定的语言；若原规则看起来有误或明显目标缺失，用一句话说明后继续按要求移植。
24. 每个被指定的语言都要完成——移植的完成标准是测试通过，而不是文件存在。
25. 保持文字简短并花在结果上：首个工具调用前用一句话说明要做什么；移植过程中只在判定变化、目标需要原规则没有的模式形状、或测试无法转绿时出声，而不是每次 `semgrep --test` 迭代都说话。
26. 汇报时先给结果：第一句说明哪些语言通过、哪些验证失败、哪些不适用、哪些 Semgrep 无法分析，细节放后面。当错误改变了规则、判定或下一步行动时更正先前说法，然后继续；不改变任何事的口误无需说明。
27. 规则和测试文件的长度与问题规模相称：测试文件的长度来自不同构造和不同安全形式，而非同一用例的重复；两个文件都不需要重复代码已说明内容的注释。
28. 拒绝这些合理化："模式结构相同"（不同语言 AST 不同，必须 dump 目标语言 AST）；"同一漏洞同一检测"（数据流因语言而异，要分析目标语言惯用法）；"原规则能跑所以不需要测试"（语言边界情况不同，要为目标写新测试）；"跳过适用性——显然适用"（有些模式是语言专属的，先完成适用性分析）；"先建所有变体再测试"（错误会累积、难调试，先完成一种语言再做下一种）；"库等价物足够接近"（表面相似掩盖差异，要验证 API 语义一致）；"直接 1:1 翻译语法"（语言惯用法不同，要研究目标语言模式）；"大部分测试通过"（部分规则报告部分真相，要么 `All tests passed` 要么移植未完成）；"旧版 semgrep 仍能解析该语言"（一个在规则必须运行的 semgrep 上没人能复现的绿，应报告失败输出并说明解析器是 Pro 专属）；"类存在所以规则能移植"（Semgrep 没有 Perl 前端、Elixir 是 Pro 专属，污点会静默失效，移植前先确认 semgrep 能读该语言）；"Semgrep 说所有测试通过"（对跳过的规则或从未匹配的文件，它在零个评分测试上也会这么说，要检查规则确实运行且测试文件扩展名与语言匹配）。
29. 常用命令：跑测试 `semgrep --test --config rule.yaml test-file`；校验 YAML `semgrep --validate --config rule.yaml`；dump AST `semgrep --dump-ast -l <lang> <file>`；调试污点流 `semgrep --dataflow-traces -f rule.yaml file`。
30. 参考文档：Pattern Syntax（元变量与匹配）、Pattern Examples（各语言参考，翻译时最有用）、Testing Rules（注解语义）、Trail of Bits Testing Handbook（高级污点模式）。

适用边界 · 注意事项

• 目标语言 Semgrep 无法分析时（如 Perl 无前端、Elixir 解析器为 Pro 专属），不要移植，应报告该语言不可评分。
• 需要创建全新规则而非移植已有规则时，应改用 `semgrep-rule-creator`。
• 会话已结束或无法确认 run id 时，不要指望 resume，应带相同参数重新调用并把 `outputDir` 指向新位置。