GitHub Trending Agent

每日抓取 GitHub Trending 页面，生成面向 Agent 全栈工程师的中文趋势仓库日报。

主要能力

• 抓取 GitHub Trending Daily 页面。
• 解析仓库名、简介、语言、星标、Fork、Built by 等字段。
• 按技术方向、应用场景、参考价值、Agent 全栈结合点生成中文分析。
• 输出每日 Markdown、JSON、CSV 与结构化运行日志。
• 支持基于 config/default-rules.json 的仓库覆盖规则与关键词分类规则。
• 从第二份 JSON 报告开始，自动对比新增上榜、掉榜与连续上榜仓库。

目录

Run-GitHubTrendingAgent.ps1   # 主脚本
Run-GitHubTrendingAgent.bat   # Windows 启动入口
config/default-rules.json     # 分类/描述/技术路线覆盖规则
reports/                      # 日报、HTML、JSON、CSV 输出
logs/                         # 运行日志与结构化 JSON 日志
tests/                        # 回归测试
.claude/CLAUDE.md             # Claude Code 项目说明

运行方式

方式一：双击或通过批处理运行

.\Run-GitHubTrendingAgent.bat

默认输出到：

reports/latest.md
reports/YYYY-MM-DD-github-trending.md
reports/latest.json
reports/YYYY-MM-DD-github-trending.json
reports/latest.csv
reports/YYYY-MM-DD-github-trending.csv
reports/github-trending-daily.html

方式二：PowerShell 直接运行

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Run-GitHubTrendingAgent.ps1

指定输出目录

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Run-GitHubTrendingAgent.ps1 -OutputRoot .\reports

使用本地 HTML 做回归测试

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Run-GitHubTrendingAgent.ps1 `
  -OutputRoot .\test-reports\check `
  -TrendingUrl "file://$PWD/reports/github-trending-daily.html"

参数

参数	默认值	说明
OutputRoot	.\reports	报告输出目录
TrendingUrl	https://github.com/trending?since=daily	数据源 URL；也支持 file:// 本地 HTML
ProxyUrl	空	代理地址；脚本默认先直连，失败后再使用代理

输出

latest.md

最新一次生成的日报，适合固定打开或作为快捷入口。

YYYY-MM-DD-github-trending.md

按日期归档的日报。

latest.json / YYYY-MM-DD-github-trending.json

结构化数据，供历史趋势对比、二次加工或自动化消费。

latest.csv / YYYY-MM-DD-github-trending.csv

表格化数据，便于导入 Excel、Notion 或其他分析工具。

github-trending-daily.html

本次抓取到的 GitHub Trending HTML，可用于排查解析问题或作为回归测试 fixture。

logs/run-YYYYMMDD_HHMMSS.json

结构化运行日志，包含本次运行的输入参数、抓取策略、每个 curl 尝试的退出码、解析数量、输出文件和错误信息。

配置规则

config/default-rules.json 支持两类能力：

1. repoOverrides：按 owner/repo 覆盖描述、技术分类、场景、增长原因、参考价值、Agent 结合点和技术路线。
2. keywordRules：按关键词补充技术分类、场景分类和增长原因。

新增重点仓库或修正分类时，优先补充 config/default-rules.json，再考虑修改脚本里的通用规则。

周报/月报聚合

# 生成周报
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Aggregate-TrendingReports.ps1 -Mode weekly

# 生成月报
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Aggregate-TrendingReports.ps1 -Mode monthly

输出到 reports/aggregate/，包含：

• 周期概览（各技术领域上榜频次）
• 持续热门（上榜 >= 50% 天数的仓库）
• Top 10 仓库（按上榜天数排序）
• 新面孔（仅出现 1 天的仓库）

需要先有至少 1 天的 JSON 日报（reports/YYYY-MM-DD-github-trending.json）。

安全与合规提示

日报中每个仓库自动附带 ComplianceNote 字段，Markdown 报告中单独输出 安全与合规提示 章节。

• 安全/网络相关：仅建议用于授权安全研究、公开信息分析和合规边界评估。
• 医疗/健康：仅作为技术路线参考，不构成医疗建议。
• 内容生成：注意素材版权、平台规则、深度合成标识和人工审核。
• 其他：基于公开简介推断，建议复核许可证、维护活跃度和合规边界。

字段同步输出到 JSON（ComplianceNote）和 CSV（ComplianceNote 列）。

回归测试

.\tests\test-fixture.ps1

测试会：

1. 使用 reports/github-trending-daily.html 作为输入。
2. 生成到 test-reports\fixture-check。
3. 校验解析数量、仓库链接、语言缺省值、重点推荐链接。
4. 校验 JSON、CSV、结构化日志和历史趋势对比章节。
5. 校验安全与合规提示章节、ComplianceNote 字段。

常见问题

代理连接失败

日志里如果出现：

curl: (7) Failed to connect to 127.0.0.1 port 7890

说明本机代理不可用。当前脚本默认先直连，直连失败且配置了 ProxyUrl 时才会尝试代理。

解析不到仓库

通常是网络问题或 GitHub 页面结构变化。优先检查：

1. reports/github-trending-daily.html 是否存在且包含 <article class="Box-row">。
2. 日志里的 curl 错误。
3. 是否被 GitHub 限流或需要登录。

分类不够准确

当前分类基于 repo 名、简介、语言和规则关键词推断。对于重点仓库，建议继续打开 README、许可证、提交记录和维护活跃度复核。