Github 仓库指南 PDF

将一个 GitHub 仓库转换为以使用为导向的中文指南及 PDF 文档。

输入要求

• 接受 GitHub 仓库 URL 或 OWNER/REPO 格式标识符。
• 默认目标读者：终端用户或运维人员，而非维护者或贡献者。
• 若该仓库为单体仓库（monorepo）、包含多个产品，或同时混杂 SDK、服务端代码与文档，请在继续前先提出一个范围界定问题。

工作流程

1. 标准化仓库标识符。
2. 优先使用 gh CLI 获取仓库元数据；仅当 gh 被屏蔽或缺失必要信息时，才回退至 browser 方式访问 GitHub 页面或关联文档站点。
3. 尽可能以浅克隆（shallow clone）方式将仓库克隆至临时目录。
4. 检查面向用户的文档和主要入口点（如 CLI 命令、API 入口、配置文件等）。
5. 编写一份中文 Markdown 指南，聚焦于“如何使用”，而非内部实现细节。
6. 通过 scripts/build_pdf.py 构建 PDF 文件。
7. 回复时仅包含一行简短状态说明，以及若干以 MEDIA: 开头的生成文件路径行。

资料采集规则

按以下优先级顺序选取信息源：

1. README* 及本地化 README 文件（如 README.zh-CN.md）
2. docs/ 目录及明显属于用户指南的文件
3. 命令参考文档与配置说明文档
4. package.json、pyproject.toml、Cargo.toml、go.mod 或其他等效清单文件（用于推断安装与运行依赖）
5. 示例（examples）、模板（templates）或样例配置文件
6. 来自 gh repo view 的 GitHub 仓库元数据

使用 rg --files 快速定位文件；优先采用面向用户的文档，而非架构设计或内部实现说明。

分析规则

聚焦真实用户所需掌握的核心内容：

• 项目是什么
• 面向哪些用户群体
• 前置依赖与安装方法
• 快速上手步骤
• 核心命令或典型工作流
• 关键配置项
• 不同模式或命令的适用场景
• 常见问题排查与典型陷阱
• 一页式速查表（cheat sheet）

除非对解释使用方式确有必要，否则避免深入实现细节。

若官方文档薄弱，则需谨慎地从清单文件、命令帮助文档、示例代码及 CLI 入口点中进行合理推断；对存疑之处应简明标注不确定性，切勿强行虚构。

推荐的 GitHub 数据获取方式

始终优先使用 gh CLI。

示例：

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

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

若 gh 获取的信息不足，则使用 browser 访问 GitHub 页面或其链接的文档网站。

推荐的文件发现命令

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

仅读取构建指南所必需的文件，切勿将整个仓库内容载入上下文。

输出结构

除非仓库结构明显需要调整，否则统一采用以下章节顺序：

1. 项目简介
2. 适用人群
3. 安装与前置依赖
4. 快速开始
5. 核心工作流或命令
6. 配置与运行模式
7. 按使用场景推荐的操作路径
8. 故障排查与常见错误
9. 一页式速查表
10. 参考来源

输出路径

所有输出文件须写入 workspace 的 media 目录下，以便直接发送：

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

其中 应为基于仓库名称生成的简洁标识符。

PDF 构建

待 Markdown 指南完成后，执行：

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