Github Repo 指南 PDF

将 GitHub 仓库转化为以使用为导向的中文指南和 PDF。

输入

• - 接受 GitHub 仓库 URL 或 OWNER/REPO 格式。
• 默认受众：用户/操作者，而非维护者或贡献者。
• 如果仓库是单体仓库、包含多个产品、或混合了 SDK 加服务器加文档，请在继续前先提出一个范围界定问题。

工作流程

1. 1. 规范化仓库标识符。
2. 优先使用 gh 获取仓库元数据。仅在 gh 被屏蔽或缺少所需细节时回退到 browser。
3. 尽可能以浅层克隆方式将仓库克隆到临时目录。
4. 检查面向用户的文档和入口点。
5. 编写中文 Markdown 指南，教授使用方法而非内部原理。
6. 使用 scripts/build_pdf.py 构建 PDF。
7. 回复一行简短状态信息，加上生成文件的 MEDIA: 行。

收集规则

按此顺序优先选择以下来源：

1. 1. README* 和本地化 README 文件
2. docs/ 和明显的用户指南文件
3. 命令参考和配置文档
4. package.json、pyproject.toml、Cargo.toml、go.mod 或等效清单文件（用于安装/运行时提示）
5. 示例、模板或示例配置文件
6. 来自 gh repo view 的 GitHub 仓库元数据

使用 rg --files 快速查找文件。优先选择面向用户的文档，而非架构或内部实现说明。

分析规则

关注真实用户需要学习的内容：

• - 项目是什么
• 面向谁
• 前提条件和安装
• 快速开始
• 主要命令或工作流程
• 重要配置选项
• 何时使用哪种模式或命令
• 故障排除和常见陷阱
• 精简速查表

除非需要解释用法，否则避免深入实现细节。

如果文档薄弱，请从清单文件、命令文档、示例和 CLI 入口点谨慎推断。简要说明不确定性，而非假装确定。

首选 GitHub 检索

优先使用 gh。

示例：

bash
gh repo view OWNER/REPO --json name,description,url,defaultBranchRef,licenseInfo,stargazerCount,forkCount,updatedAt

bash
gh repo clone OWNER/REPO /tmp/repo -- --depth=1

如果 gh 不足，使用 browser 检查 GitHub 页面或关联的文档站点。

推荐的文件发现

bash
rg --files . | rg (^README|^readme|^docs/|guide|manual|command|config|example|package\.json$|pyproject\.toml$|Cargo\.toml$|go\.mod$)

仅读取构建指南所需的文件。不要将整个仓库内容放入上下文。

输出结构

除非仓库明显需要不同结构，否则使用此结构：

1. 1. 它是什么
2. 面向谁
3. 安装和前提条件
4. 快速开始
5. 核心工作流程或命令
6. 配置和模式
7. 按场景推荐的使用路径
8. 故障排除和常见错误
9. 一页速查表
10. 使用的来源

输出路径

将输出写入工作区媒体目录，以便直接发送：

• - Markdown：media/-user-guide-zh-YYYYMMDD-HHMMSS.md
• PDF：media/-user-guide-zh-YYYYMMDD-HHMMSS.pdf

使用从仓库名称派生的简短 slug。

PDF 构建

Markdown 指南准备就绪后，运行：

bash
python3 skills/github-repo-guide-pdf/scripts/build_pdf.py \
--markdown /absolute/path/to/guide.md \
--output /absolute/path/to/guide.pdf \
--title