用途
gh-search-code 用于在 GitHub 上跨仓库搜索代码，围绕 GitHub CLI 的 gh search code 命令提供语法参考。当需要跨多个仓库查找代码模式、在仓库或组织内定位特定文件类型或文件名、按语言或文件大小检索代码、排除某些结果，或需要正则搜索时，可使用该技能。
主要能力
基础语法为：
gh search code <query> [flags]
常用的过滤标志包括：
--extension <string>：按文件扩展名过滤，例如--extension js--filename <string>：定位特定文件名，例如--filename package.json--language <string>：按编程语言过滤，例如--language python--owner <strings>：限定到特定所有者，例如--owner microsoft-R, --repo <strings>：在指定仓库内搜索，例如--repo cli/cli--size <string>：按文件大小（KB）过滤，例如--size ">100"--match <strings>：在文件或路径中搜索，例如--match file或--match path-L, --limit <int>：最大结果数，默认 30-w, --web：在浏览器中打开--json <fields>：以 JSON 输出，可选字段为 path、repository、sha、textMatches、url
使用方式
排除语法
使用内联查询排除（用 - 取反）时，必须使用 -- 分隔符：
正确：gh search code -- "search-terms -qualifier:value"
错误示例包括：gh search code "search-terms" --flag=-value、gh search code "search-terms" --flag=!value、gh search code "search-terms" --filename="!test"。
实际例子：
gh search code -- "function -filename:test"（排除名为 test 的文件）gh search code -- "import -language:javascript"（排除某语言）gh search code -- "config -path:vendor"（排除 vendor 目录）gh search code -- "TODO -extension:md"（排除某扩展名）
-- 的作用是让 shell 停止解析标志，把其后的内容都当作参数；否则引号内的 -qualifier:value 可能被误解析。
-filename: 与 -path: 的区别
-filename:只匹配文件名（如 test.js、utils_test.py），适合按文件名模式排除文件。-path:匹配完整文件路径（如 src/test/file.js、lib/testing/util.js），适合排除目录路径或路径片段。
匹配示例：-filename:test 会匹配 test.js、utils_test.py、test_helper.rb，但不匹配 src/file.js（文件名不含 test）、tests/utils.js（文件名是 utils.js）；-path:test 会匹配 tests/utils.js、src/test/file.js、lib/testing/helper.py、test.js，但不匹配 src/utils.js。
语法选择
决策原则：如果搜索包含排除（NOT、减号、without、except）或复杂布尔逻辑（OR、AND），使用带 -- 的查询语法；否则使用标志语法。
标志语法（正向过滤）：
gh search code "import" --language python --extension py
查询语法（排除时必需）：
gh search code -- "function -filename:test.js -language:javascript"
不要在同一条命令中混用两种语法，例如 gh search code "function" --language python -filename:test 是错误的，应写成 gh search code -- "function language:python -filename:test"。
PowerShell 下排除需使用 --% 防止解析，例如 gh --% search code -- "function -filename:test.js"。
常见排除模式示例：gh search code -- "config -path:vendor -path:node_modules"、gh search code -- "function -filename:test -filename:spec"、gh search code -- "class -size:>500"、gh search code -- "TODO -extension:md -extension:txt"、gh search code -- "api -path:examples -path:docs"。
引用与大小比较
多词搜索需要加引号，如 gh search code "error handling"。大小比较运算符需要加引号，如 gh search code "import" --size ">50" --language python，范围写法如 --size "100..500"。
适用场景与示例
- 搜索函数模式：
gh search code "async function" --language typescript - 查找配置文件：
gh search code "database" --filename config.json --owner myorg - 在指定仓库搜索：
gh search code "TODO" --repo owner/repo --language go - 按文件大小搜索：
gh search code "import" --size "100..500" --language python
网络标志与限制
-w/--web 会在 GitHub 网页界面中打开搜索，网页端支持 CLI API 不具备的功能，例如正则搜索。示例：gh search code "function.*test" --language javascript -w，随后可在网页中改用 /function.*test/ language:javascript。当需要正则模式、更新的搜索特性、更直观地浏览结果，或希望获得更好结果时使用 -w。也可以先用 CLI 构建查询再在网页中补充正则，例如 gh search code --language python --repo myorg/myrepo -w。
CLI API 的限制：使用旧版 GitHub 搜索引擎，结果可能与 github.com 不同，不支持正则搜索（改用 -w），部分高级功能可能不可用。
安装与认证
若 gh 命令未找到，可先检查：
which gh
如未安装，参见 https://cli.github.com/manual/installation 。如未认证，执行：
gh auth login
常见错误
--extension="NOT js"或--language=-python：标志语法不支持否定，应改用-- "-extension:js"或-- "-language:python"。gh search code import -language:js：-language被当作标志，应使用--。"function NOT language:js"：不支持 NOT 关键字，应使用-。- 混用标志与查询限定符：排除时应全部使用查询语法。
- 多词查询未加引号：会被分开搜索。
- 比较运算符未加引号：shell 会解释
>。 - 内联使用
-filename却未加--：会被解析为标志。 - 试图在 CLI 使用正则：CLI API 不支持，改用
-w。 - PowerShell 未使用
--%：排他时会出错。
其他资源的搜索可参考 gh-search-issues、gh-search-prs、gh-search-repos、gh-search-commits。GitHub 搜索语法参见 https://docs.github.com/search-github/searching-on-github/searching-code 。