核心定位

本能力将 GitHub 仓库内容与元数据 转换为目标格式（Markdown 文档、JSON 元数据、CSV 表格、目录树 JSON）。它在不同格式间保持结构完整性与内容保真度——并非简单的文件复制，而是一种语义化转换，严格遵循 GitHub 的数据模型（仓库、树、提交、Issues、PRs、Releases）。

关键职责：

• 使用 GitHub API 或本地 .git 目录解析 GitHub 仓库结构（分支、目录树、文件）
• 将仓库数据模型（Issues、PRs、Releases、Contributors）转换为对应目标格式的表示形式
• 在格式转换过程中保留文件内容与编码（UTF-8、二进制检测）
• 提供转换清单（文件数量、类型分布、大小汇总）

运行模式

/convert-github-repository --markdown

仓库 → Markdown 文档。 将整个仓库转换为一组 Markdown 文件：

• 从仓库根目录提取 README.md
• 每个目录生成子目录，并在其内创建 README.md 描述其内容
• Issues 导出为 issues/YYYY-MM-DD-{number}-{title}.md
• PRs 导出为 pull-requests/YYYY-MM-DD-{number}-{title}.md
• Releases 导出为 releases/v{semver}.md
• 代码文件以原始语言保留，并添加语法高亮代码块围栏

/convert-github-repository --json

仓库 → JSON 元数据。 将仓库结构与内容导出为一个 JSON 文件：

{
  "repo": { "name": "...", "description": "...", "stars": N, "license": "...", "topics": [...] },
  "files": [{ "path": "...", "size": N, "type": "file|dir", "sha": "..." }],
  "branches": [{ "name": "...", "last_commit": "..." }],
  "contributors": [{ "login": "...", "contributions": N }]
}

/convert-github-repository --csv

Issues + PRs → CSV。 将 Issues 和 Pull Requests 导出为 CSV 行，列名包括：number, title, state, author, created_at, updated_at, labels, assignees, milestone, body_preview。

/convert-github-repository --tree

仓库 → 目录树 JSON。 输出一个表示仓库布局的树状结构：

{
  "path": "/",
  "type": "directory",
  "children": [
    { "path": "src/index.js", "type": "file", "size": 1234, "language": "JavaScript" },
    { "path": "tests/", "type": "directory", "children": [...] }
  ]
}

/convert-github-repository --readme-to-json

README.md → 结构化 JSON。 解析 README.md 并提取：标题（首个 H1）、描述（标题后首个段落）、安装步骤、使用示例、贡献指南、许可证信息。

执行步骤

1. 识别仓库来源

远程 GitHub 仓库： 解析 URL 提取 owner 和 repo：

https://github.com/owner/repo -> {owner: "owner", repo: "repo"}

使用环境变量中的 GITHUB_TOKEN（os.getenv("GITHUB_TOKEN")）调用 GitHub API。

本地仓库： 验证 .git 目录是否存在。使用 git CLI 提取以下信息：

• git ls-files 获取文件列表
• git log --oneline 获取最近提交记录
• git remote get-url origin 确认仓库身份

若无法识别任一来源，则报告：“无法识别仓库来源 —— 请提供 GitHub URL（如 https://github.com/owner/repo）或包含 .git 目录的本地路径。”

2. 获取仓库元数据

对于远程仓库，调用 GitHub API：

GET https://api.github.com/repos/{owner}/{repo}
Authorization: Bearer {GITHUB_TOKEN}
Accept: application/vnd.github+json

响应中包含：full_name、description、stargazers_count、forks_count、license.spdx_id、topics、default_branch、created_at、updated_at、homepage、language。

若缺失 Token 或遭遇限流（HTTP 403），尝试无认证请求（限流更低），或报告：“GitHub API 不可用 —— 请检查 GITHUB_TOKEN 或稍后重试（无认证请求限流：60 次/小时）。”

3. 获取仓库内容

获取默认分支树：

GET https://api.github.com/repos/{owner}/{repo}/git/trees/{default_branch}?recursive=1

返回所有文件的扁平化列表，含 path、type（blob/tree）、size、sha 字段。

对于本地仓库： 运行 git ls-tree -r --name-only {branch} 获取文件列表，再通过 git show {sha}:{path} 读取文件内容。

过滤常见非必要路径：

• node_modules/、.git/、vendor/ —— 默认跳过，除非显式指定 --include-ignored
• 二进制文件（图片、PDF、编译产物）—— 在清单中列出，但不包含内容
• .gitignore 中声明但未提交的文件 —— 跳过

4. 转换为目标格式

--markdown 转换：

• README.md：原样保留，并更新相对链接指向本地文件
• 代码文件：依据扩展名映射添加语法高亮代码块围栏（```language）：
  • .js → ```javascript、.py → ```python、.go → ```go、.rs → ```rust 等
• 目录：为每个目录创建 README.md，列出其包含的文件
• Issues：每个 Issue 转换为 {number}-{slug}.md，含 frontmatter：

  ---
  number: 42
  state: open
  author: username
  created: 2024-01-15
  labels: [bug, help-wanted]
  ---
  # Title
  body text...
  

• PRs：格式同 Issues，额外增加 merged 字段及审查评论

--json 转换：

• 从扁平文件列表构建嵌套结构（按目录路径分组）
• 对文本文件包含内容（若大于 1MB 则 Base64 编码）
• 对大型仓库（>10K 文件），采用流式输出避免内存耗尽

--csv 转换：

• 表头：number,title,state,author,created_at,updated_at,labels,assignees,milestone,body_preview
• Labels：用 ; 分隔符连接
• Assignees：用 ; 分隔符连接
• Body preview：取前 200 字符，去除 Markdown 格式
• 字段中含逗号时需加双引号；内部双引号转义为 ""

--tree 转换：

• 构建递归树结构
• 依据扩展名检测语言（.js → JavaScript、.py → Python 等）
• 报告总文件数、目录数、各类型大小分布

--readme-to-json 转换：

• 使用正则表达式或简易状态机解析 Markdown：
  • 首个 # Heading → title
  • 标题之间的段落 → 各节（installation、usage、contributing 等）
  • 代码块 → code_examples 数组
  • 表格 → 解析为对象数组
  • 链接 [text](url) → 收集至 links 数组

5. 验证输出

交付前执行以下校验：

• 若格式为 JSON：使用 json.loads() 解析并确认无错误
• 若格式为 CSV：验证所有行具有相同列数
• 若格式为 Markdown：验证所有文件可被正确读取为 UTF-8
• 检查是否静默跳过文件 —— 报告跳过与成功转换的文件数量对比

6. 附带清单交付

返回转换结果及清单：

{
  "format": "markdown",
  "files_converted": 142,
  "files_skipped": 3,
  "skipped_reasons": [
    {"path": "node_modules/package/index.js", "reason": "binary or non-text, excluded by default"},
    {"path": ".git/config", "reason": "contains sensitive data"}
  ],
  "total_size_bytes": 2048576,
  "output_path": "./{repo-name}-converted/"
}

强制规则

禁止行为

• 禁止硬编码 GitHub Token —— 必须使用 os.getenv("GITHUB_TOKEN")
• 禁止将二进制文件（图片、PDF、编译产物）作为文本转换 —— 应依据扩展名或大小（>5MB）进行检测
• 禁止转换 .gitignore 中列出的文件，除非用户显式指定 --include-ignored
• 禁止静默跳过文件 —— 所有跳过操作必须在清单的 skipped_reasons 中明确记录
• 禁止输出格式校验失败的内容（非法 JSON、不可解析 CSV）
• 禁止在未认证情况下转换私有仓库 —— 必须先验证未返回 HTTP 401 再继续执行

必须行为

• 始终生成含 files_converted、files_skipped、skipped_reasons 的清单
• 保留文件编码 —— 以二进制方式读取，按 UTF-8 解码，无效字节替换为 uFFFD
• 准确报告文件数量与大小，确保透明性
• 获取 Issues/PRs 时使用分页（GitHub API 默认每页 30 或 100 条）
• 处理本地仓库时，必须使用 git CLI —— 不得假定可直接访问原始文件系统
• 默认过滤常见非代码目录（node_modules、.git、pycache、build/、dist/）

质量标准

高质量输出应满足：通过目标格式解析器无报错、语义内容完全保留、且附带完整清单说明转换内容及跳过原因。

优质示例 vs 劣质示例