gh-code-search

GitHub 代码搜索

通过智能的多重搜索编排，从 GitHub 获取真实代码示例。

前提条件

必需：

• 已安装并完成身份验证的 gh CLI（gh auth login --web）
• Node.js + pnpm

验证：

gh auth status  # Should show authenticated

用法

cd plugins/knowledge-work/skills/gh-code-search
pnpm install  # First time only
pnpm search "your query here"

使用场景

在用户提出以下需求时调用此技能：

• 真实案例（“大家如何实现 X？”）
• 库的用法模式（“给我看看 workflow.dev 的用法示例”）
• 实现方式（“使用 GitHub 搜索的 Claude code 技能”）
• 架构模式（“TypeScript 中的仓储模式”）
• 特定框架或库的最佳实践

需要细致的多重搜索的示例：

• “查找 React hooks” → 需要搜索 useState/useEffect（导入）、function use（定义）、const use =（箭头函数）
• “Express 错误处理中间件” → 搜索 (req, res, next) =>（签名）、app.use（注册）、function(err,（错误处理程序）
• “大家如何使用 XState？” → 搜索 useMachine、createMachine、interpret（实际函数名，而非“状态机”）
• “TypeScript 项目的 GitHub Actions” → 搜索 .yml 工作流文件 + actions/setup-node + tsc 或 pnpm build（实际命令）

工作原理

职责划分：

脚本职责（工具实现）

1. 使用 GitHub 身份验证（gh CLI 令牌）
2. 执行单个搜索查询（Octokit API、分页、文本匹配）
3. 按质量排序（星标数、近期程度、代码结构）
4. 并行获取排名前 10 的文件
5. 提取事实数据（导入、语法模式、指标）
6. 返回包含代码、元数据以及所有文件的 GitHub URL 的整洁 Markdown

该脚本是单查询工具。 Claude 负责编排多次调用。

Claude 的编排职责

Claude 执行多阶段工作流：

1. 查询策略生成： 制定 3-5 个有针对性的搜索查询，并考虑：

   • 语言上下文（TypeScript 与 JavaScript）
   • 文件类型差异（React 的 tsx 与 ts、配置文件与实现文件）
   • 不同的具体程度（从宽泛到具体）
   • 扩展相关术语

2. 顺序执行搜索： 多次运行工具，根据中间结果调整查询

3. 汇总结果： 合并所有代码文件，按仓库和路径去重，并保留 GitHub URL

4. 模式分析： 提取常见导入、架构风格和实现模式

5. 全面总结： 综合发现，说明权衡与建议，突出关键代码，并提供所有有意义文件的 GitHub URL

---

Claude 的编排工作流

第 1 步：分析请求并生成查询（阻塞）

分析用户请求，确定：

• 主要语言／框架（TypeScript、Python、Go 等）
• 要查找的具体模式（钩子、中间件、配置、操作）
• 需要涵盖的文件类型变体（tsx 与 ts、yaml 与 json）

考虑细节，生成 3-5 个有针对性的查询：

示例 1：“查找 React 钩子”

• 查询 1：useState useEffect language:typescript extension:tsx（匹配导入语句、组件中的钩子用法）
• 查询 2：function use language:typescript extension:ts（匹配 function useFetch() 之类的钩子定义）
• 查询 3：const use = language:typescript（匹配 const useAuth = () => 之类的箭头函数钩子）

示例 2：“Express 错误处理”

• 查询 1：(req, res, next) => language:javascript（匹配中间件函数签名）
• 查询 2：app.use express（匹配 Express 中间件注册）
• 查询 3：function(err, req, res, next) language:javascript（匹配包含 4 个参数的错误处理程序签名）

示例 3：“React 中的 XState 状态机”

• 查询 1：useMachine language:typescript extension:tsx（匹配 const [state, send] = useMachine(machine) 之类的 React 钩子用法）
• 查询 2：createMachine language:typescript（匹配状态机定义和导入）
• 查询 3：interpret xstate language:typescript（匹配 const service = interpret(machine) 之类的服务创建代码）

每个查询的理由：

• 匹配实际代码模式（函数名、导入语句、签名）
• 不要使用便于人类阅读的搜索词或文档表述
• 不同文件扩展名可涵盖不同用例（组件用 tsx，工具代码用 ts）
• 具体的函数／变量名称有助于找到实际实现
• 签名模式可匹配常见代码结构（箭头函数、函数声明）
• 语言／扩展名筛选条件可避免无关语言带来的噪声

**检查点：**继续之前，确认已生成 3-5 个查询

---

第 2 步：依次执行搜索

按顺序处理每个查询：

cd plugins/knowledge-work/skills/gh-code-search
pnpm search "query text here"

每次搜索后：

1. 记录结果数量——太多？太少？
2. 检查质量指标——星标数、时效性、代码结构评分
3. 识别模式——结果是否集中在特定方法上？
4. 必要时调整下一个查询：
   • 结果太多 → 缩小范围（添加更多筛选条件）
   • 结果太少 → 扩大范围（移除限制性筛选条件）
   • 找到明显模式 → 搜索相似变体

跟踪哪些查询成功——记录哪些策略有效，以便在摘要中说明

**提前停止：**如果前 2-3 个查询得到 30 个以上高质量结果，其余查询可选

---

第 3 步：汇总结果

合并所有搜索得到的代码文件：

1. 收集文件，包括每次搜索输出中的 GitHub URL
2. 按 repository.full_name + file_path 去重
   • 如果存在重复项，保留评分最高的版本
   • 记录哪些查询找到了相同文件（表明其相关性很高）
3. 保持多样性——确保包含多个仓库（避免 10 个文件都来自同一个仓库）
4. 跟踪来源——记住每个文件由哪个查询找到（便于分析）
5. 保留 GitHub URL——为每个文件保留完整的 GitHub URL，以便纳入摘要

**结果：**包含 15-30 个唯一、高质量代码文件及其 GitHub URL 的统一列表

---

第 4 步：分析模式

提取所有代码文件中的事实模式：

导入分析：

• 列出最常见的导入项（按库分组）
• 区分标准库与第三方依赖
• 记录特定版本的模式（例如，React 18 hooks）

架构模式：

• 函数式实现与基于类的实现
• 自定义 hooks 与内联逻辑
• 中间件链与单处理程序
• 配置模式（环境变量、配置文件、内联配置）

代码结构：

• 函数签名（参数、返回类型）
• 错误处理方式（try/catch、错误中间件、Result 类型）
• 测试模式（单元测试与集成测试、模拟策略）
• 文档风格（JSDoc、内联注释、README）

语言分布：

• TypeScript 与 JavaScript 的占比
• 严格模式的使用情况
• 类型定义模式

不要发表主观评价——提取事实，而非观点。分析将在第 5 步进行。

---

第 5 步：生成全面摘要

输出格式（结构必须完全一致）：

# GitHub Code Search: [User Query Topic]

## Search Strategy Executed

Ran [N] targeted queries:
1. `query text` - [brief rationale] → [X results]
2. `query text` - [brief rationale] → [Y results]
3. ...

**Total unique files analyzed:** [N]

---

## Pattern Analysis

### Common Imports
- `library-name` - Used in [N/total] files
- `another-lib` - Used in [M/total] files

### Architectural Styles
- **Functional Programming** - [N] files use pure functions, immutable patterns
- **Object-Oriented** - [M] files use classes, inheritance
- **Hybrid** - [K] files mix both approaches

### Implementation Patterns
- **Pattern 1 Name**: [Description with prevalence]
- **Pattern 2 Name**: [Description with prevalence]

---

## Approaches Found

### Approach 1: [Name]
**Repos:** [repo1], [repo2]
**Characteristics:**
- [Key trait 1]
- [Key trait 2]

**Example:** [repo/file_path:line_number](github_url)
```language
[relevant code snippet - NOT just first 40 lines]

方法 2：[名称]

[类似结构]

---

权衡

方法	优点	缺点	最适用场景
方法 1	[优点]	[缺点]	[用例]
方法 2	[优点]	[缺点]	[用例]

---

建议

针对你的用例（[根据用户上下文推断]）：

1. 首选建议：[方法名称]

   • 原因：[基于分析的理由]
   • 实现：[高层步骤]
   • 参考资料：repo/file_path:line_number

2. 备选方案：[另一种方法]

   • 适用情形：[更适合此方案的场景]
   • 参考资料：repo/file_path:line_number

---

关键代码部分

[概念 1]

来源：repo/file_path:line_range

[Specific relevant code - imports, key function, not arbitrary truncation]

重要性：[简要说明]

[概念 2]

来源：repo/file_path:line_range

[Specific relevant code]

重要性：[简要说明]

---

分析的所有 GitHub 文件

重要：列出所有搜索中找到的有意义文件的 GitHub URL。

列出分析过的每个唯一文件（15-30 个），并按仓库分组：

[repo-owner/repo-name]（[stars]⭐）

• file_path - [语言] - [简要说明该文件展示的内容]
• file_path - [语言] - [简要说明]

[repo-owner/repo-name2]（[stars]⭐）

• file_path - [语言] - [简要说明]

**格式：**直接使用带行号的 GitHub blob URL（如相关），例如：https://github.com/owner/repo/blob/main/path/file.ts#L10-L50

**Summary characteristics:**
- **Factual** - Based on extracted data, not assumptions
- **Actionable** - Clear recommendations with reasoning
- **Contextualized** - References specific code locations with line numbers
- **Balanced** - Shows trade-offs, not just "best practice"
- **Comprehensive** - Covers patterns, approaches, trade-offs, recommendations
- **Accessible** - GitHub URLs for ALL meaningful files so users can explore full source code

---

### Step 6: Save Results to File

**After generating comprehensive summary, persist for future reference:**

1. **Generate timestamp:**
   - Invoke `timestamp` skill to get deterministic YYYYMMDDHHMMSS format
   - Example: `20250110143052`

2. **Sanitize query for filename:**
   - Convert user's original query to kebab-case slug
   - Rules: lowercase, spaces → hyphens, remove special chars, max 50 chars
   - Example: "React hooks useState" → "react-hooks-usestate"

3. **Construct file path:**
   - Directory: `docs/research/github/`
   - Format: `<timestamp>-<sanitized-query>.md`
   - Full path: `docs/research/github/20250110143052-react-hooks-usestate.md`

4. **Save using Write tool:**
   - Content: Full comprehensive summary from Step 5
   - Ensures persistence across sessions
   - User can reference past research

5. **Log saved location:**
   - Inform user where file was saved
   - Example: "Research saved to docs/research/github/20250110143052-react-hooks-usestate.md"

**Why save:**
- Comprehensive summaries represent significant analysis work (30-150s of API calls)
- Users may want to reference patterns/trade-offs later
- Builds searchable knowledge base of GitHub research
- Avoids re-running expensive queries for same topics

---

## Error Handling

**Common issues:**

- **Auth errors:** Prompt user to run `gh auth login --web`
- **Rate limits:** Show remaining quota, reset time. If hit during multi-search, stop gracefully with partial results
- **Network failures:** Continue with partial results, note which queries failed
- **No results for query:** Note in summary, adjust subsequent queries to be broader
- **All queries return same files:** Note low diversity, recommend broader initial queries

**Graceful degradation:** Partial results are acceptable. Complete summary based on available data.

---

## Limitations

- GitHub API rate limit: 5,000 req/hr authenticated (multi-search uses more quota)
- Each tool invocation fetches top 10 results only
- Skips files >100KB
- Sequential execution takes longer than single query (10-30s per query)
- Provides factual data, not conclusions (Claude interprets patterns)
- Deduplication assumes exact path matches (renamed files treated as unique)

---

## Typical Execution Time

**Per query:** 10-30 seconds depending on:
- Number of results (100 max)
- File sizes
- Network latency
- API rate limits

**Full workflow (3-5 queries):** 30-150 seconds

**Optimization:** If first queries yield sufficient results, skip remaining queries

---

## Integration Notes

**Example: User asks "find Claude Code skills doing github search"**

```javascript
// 1. Claude analyzes: Skills use SKILL.md with frontmatter, likely in .claude/skills/
// 2. Claude generates queries:
//    - "filename:SKILL.md github search" (matches SKILL.md files with "github search" text)
//    - "octokit.rest.search language:typescript" (matches actual Octokit API usage)
//    - "gh api language:typescript path:skills" (matches gh CLI usage in skills)
// 3. Claude executes sequentially:
cd plugins/knowledge-work/skills/gh-code-search
pnpm search "filename:SKILL.md github search"
// [analyze results]
pnpm search "octokit.rest.search language:typescript"
// [analyze results]
pnpm search "gh api language:typescript path:skills"
// 4. Claude aggregates, deduplicates, analyzes patterns
// 5. Claude generates comprehensive summary with trade-offs and recommendations

---

测试

使用多样化的查询验证工作流：

• 简单： "React hooks"（应生成 3 个以上查询，并合并结果）
• 复杂： "GitHub Actions TypeScript project setup"（需要配置和实现相关查询）
• 模糊： "state management"（应针对 Redux、Zustand、XState、Context 生成查询）

检查质量：

• 去重正常（摘要中没有重复文件）
• 仓库多样化（并非全部来自同一个仓库）
• 摘要包含权衡和建议
• 代码片段与主题相关（不是随意截取的内容）