building-github-index

构建 GitHub 索引

创建针对 Claude 项目知识优化的 GitHub 仓库 Markdown 索引。索引支持通过 GitHub API 检索，并提供语义描述以实现有效匹配。

快速开始

# Documentation repos (markdown/notebooks)
python scripts/github_index.py owner/repo -o index.md

# Code repos (extract symbols via tree-sitter)
python scripts/github_index.py owner/repo --code-symbols -o index.md

# Multiple repos combined
python scripts/github_index.py owner/repo1 owner/repo2 -o combined.md

脚本选项

标志	描述
-o, --output	输出文件（默认：github_index.md）
--token	GitHub PAT；也会读取 GITHUB_TOKEN 环境变量
--include-patterns	仅索引匹配的 glob 模式："docs/**" "src/**"
--exclude-patterns	跳过匹配的 glob 模式："test/**"
--max-files	限制每个仓库的文件数（默认：200）
--skip-fetch	仅获取文件树，不获取内容（速度快，描述仅基于文件名）
--code-symbols	包含代码文件，并通过 tree-sitter 提取函数/类名称

描述提取优先级

1. YAML frontmatter - title: 和 description: 字段
2. Markdown 标题 - 将第一个 h1/h2 作为标题，后续标题作为主题
3. Notebook 单元格 - 第一个 Markdown 单元格中的标题
4. 代码符号 - 公共函数/类名称（使用 --code-symbols）
5. 从路径推导 - 将文件名转换为词语（后备方案）

描述提取失败时

有些仓库包含占位文件（指向外部文档的链接、空的 readme）。这类情况下：

建议手动整理。 使用文件树输出和领域知识：

# Get tree structure only (fast)
python scripts/github_index.py owner/repo --skip-fetch -o skeleton.md
# Then manually enhance descriptions based on domain knowledge

对于包含内嵌应用的代码密集型仓库：

• 目录名称可体现用途：acc_wav_gen →“ACC 波形生成”
• 外设缩写对应具体功能：AFEC=ADC、MCAN=CAN、TWIHS=I2C
• 操作模式：阻塞、中断、dma、轮询

输出格式

# {Repo} - Content Index

**Repository:** {url}
**Branch:** `{branch}`

## Retrieval Method
{API curl commands}

---

## {Category}

| Description | Path |
|-------------|------|
| {What this covers} | `{path/file.md}` |

描述列在前（用于相关性匹配），路径在后（作为检索键）。

API 访问

枚举文件：

curl -sL "https://api.github.com/repos/OWNER/REPO/git/trees/BRANCH?recursive=1"

获取内容：

curl -s "https://api.github.com/repos/OWNER/REPO/contents/PATH?ref=BRANCH" \
  -H "Accept: application/vnd.github+json" | \
  python3 -c "import sys,json,base64; print(base64.b64decode(json.load(sys.stdin)['content']).decode())"

网络

两个脚本都会下载仓库 tarball（单个 HTTP 请求，不受逐文件速率限制），然后在本地处理文件。允许列表：api.github.com（tarball 通过此端点重定向）

相关技能

• accessing-github-repos - 私有仓库、PAT 设置、tarball 下载
• tree-sitting - 详细的代码结构（方法、导入项、行号）

精简格式（pk_index.py）

对于受 token 限制的项目知识，请使用精简脚本：

python scripts/pk_index.py owner/repo -o repo_pk.md

输出内容约小 80%：

• 每个文件占一行：path — 描述
• 仅包含符号（不含签名）
• 每个类别最多 15 个文件
• 不包含检索说明部分

适合在项目知识中添加多个仓库索引。