github-doc-maintainer

name	github-doc-maintainer
description	全自动检索 GitHub 热门仓库，分析并维护项目文档，自动提交 PR。用于发现文档问题（死链、typo、过时内容等）并自动修复提交。当用户需要批量维护开源项目文档、自动提 PR 修复文档问题时触发此技能。

GitHub 文档维护助手

全自动检索 GitHub 热门仓库，发现并修复文档问题，自动提交 PR。

工作流程

1. 检索 → 2. 分析 → 3. 修复 → 4. 提交 PR

1. 检索热门仓库

使用 scripts/fetch_repos.py 检索仓库：

# 按 star 数排序（默认）
python3 scripts/fetch_repos.py --language go --min-stars 1000 --limit 50

# 按最近趋势
python3 scripts/fetch_repos.py --trending --language python --since weekly

# 按 topic 搜索
python3 scripts/fetch_repos.py --topic documentation --min-stars 100

输出：/tmp/gh_repos_YYYYMMDD_HHMMSS.json

2. 分析文档问题

使用 scripts/analyze_docs.py 分析仓库文档健康度：

# 分析已检索的仓库列表
python3 scripts/analyze_docs.py --input /tmp/gh_repos_*.json --workers 5

# 只检查 README
python3 scripts/analyze_docs.py --input repos.json --readme-only

检测的问题类型：

• 死链（404 链接）
• 拼写错误（常见 typo）
• 过时的 badge/shield
• 失效的 anchor 链接
• 图片加载失败

输出：/tmp/doc_issues_YYYYMMDD_HHMMSS.json

3. 生成修复

使用 scripts/generate_fixes.py：

python3 scripts/generate_fixes.py --input /tmp/doc_issues_*.json --output ./fixes/

生成结构：

./fixes/
├── owner_repo/
│   ├── README.md.fixed      # 修复后的文档
│   ├── fixes.json           # 修复详情
│   └── pr_description.md    # PR 描述模板

4. 选择修复项（可选）

使用 scripts/select_fixes.py 交互式选择要提交的修复：

# 交互式选择
python3 scripts/select_fixes.py --input ./fixes/

# 自动选择全部
python3 scripts/select_fixes.py --input ./fixes/ --auto-select all

# 自动选择指定项
python3 scripts/select_fixes.py --input ./fixes/ --auto-select "1,3,5"

选择方式：

• all - 选择全部
• none - 取消全部
• 1,3,5 - 选择第 1、3、5 项
• 1-5 - 选择第 1 到 5 项
• -2 - 排除第 2 项（先选全部再排除）

5. 自动提交 PR

使用 scripts/submit_prs.py：

# 需要配置 GH_TOKEN 环境变量
export GH_TOKEN="ghp_xxxxxxxx"

# 批量提交（确认模式）
python3 scripts/submit_prs.py --input ./fixes/ --confirm

# 全自动模式（无需确认）
python3 scripts/submit_prs.py --input ./fixes/ --auto

PR 流程：

1. Fork 目标仓库
2. 创建修复分支 (doc-fix-YYYYMMDD)
3. 提交修改
4. 创建 PR（使用模板描述）

完整自动化命令

一键执行全流程：

# 全自动模式（无需确认，提交所有）
python3 scripts/auto_maintain.py \
  --language go \
  --min-stars 1000 \
  --limit 20 \
  --auto

# 交互式选择模式（推荐）
python3 scripts/auto_maintain.py \
  --language go \
  --min-stars 1000 \
  --limit 20 \
  --select

# 干跑测试（不实际提交）
python3 scripts/auto_maintain.py \
  --language go \
  --min-stars 1000 \
  --limit 20 \
  --dry-run

配置

GitHub Token

需要 Personal Access Token（classic）：

• public_repo - 访问公共仓库
• repo - 如果需要访问私有仓库

export GH_TOKEN="ghp_xxxxxxxx"

速率限制

GitHub API 限制：

• 未认证：60 请求/小时
• 已认证：5000 请求/小时

脚本会自动处理速率限制和重试。

自定义规则

编辑 references/check_rules.json 添加自定义检查规则：

• 添加特定的 typo 映射
• 配置忽略的链接模式
• 自定义 badword 检测

注意事项

1. 礼貌原则：批量 PR 注意频率，避免 spam
   • 已内置速率限制：每天最多 10 个 PR，同一仓库 7 天冷却期
2. 小步快跑：一次 PR 只修复一个明确问题
3. 测试先行：首次使用加 --dry-run 检查
4. 遵守规范：遵循目标项目的贡献指南
5. 敏感项目：大型项目（如 torvalds/linux）建议手动提交

最佳实践

避免被标记为 Spam

• 不要频繁向同一仓库发送 PR（已自动限制）
• 不要只修复一个标点符号
• 避免修改测试文件或生成的文档
• 尊重 .github/CONTRIBUTING.md 中的特殊要求

查看优化建议

cat OPTIMIZATION.md

依赖

pip install requests urllib3 beautifulsoup4 pyspellchecker

或运行：

pip install -r scripts/requirements.txt