AI 开源项目健康度分析与排名实施落地指南¶

本文档记录了网站中 AI 开源项目健康度分析与展示能力的完整落地方案。内容覆盖数据准备、Cloudflare Worker、前端渲染、样式增强、测试验证以及运维守护。请在上线或运维过程中参考本文档逐步执行。

组成概览¶

数据准备¶

1. 在本地执行清单生成脚本 - 运行以下命令：

   npm run generate:ai-manifest
   

   该脚本会遍历 content/zh/ai 与 content/en/ai，筛选出包含有效 GitHub 仓库链接的条目，并生成 static/data/ai-projects-manifest.json。字段包括项目的 repo slug、标题、语言、Slug、页面路径、标签、Featured 状态等元信息。Worker 仅会处理清单中出现的仓库。

2. 清单文件发布配置 - 发布到静态资源：

   清单文件会在 Hugo 构建后随站点静态资源发布。例如生产环境可通过 https://<domain>/data/ai-projects-manifest.json 访问。将该 URL 配置到 Worker 的 PROJECT_FEED_URL 变量。

数据采集与托管（CI / 定时任务）¶

本项目不依赖 Cloudflare Functions / Pages Functions。数据采集与评分通过在仓库中运行的 Node/TypeScript 脚本（位于 tools/ai-oss-rank-worker）完成，常见做法为使用 GitHub Actions 或其他 CI 定时触发：

• 采用周期性任务（例如 GitHub Actions 的 schedule 触发）拉取 static/data/ai-projects-manifest.json，分批调用 GitHub API，计算评分后将结果写回到仓库的静态数据目录（例如 static/data/ai-projects-ranking.json）并提交到主分支，或上传到 CDN / 对象存储并更新对应 URL。
• 分批处理同样适用：每次处理固定数量仓库（例如 10 个）以避免 GitHub API 限流或并发限制，并将中间状态保存至本地/CI 的缓存或在提交中记录游标以便下次继续。
• 脚本入口与模块划分与原设计类似（manifest 读取、github 指标抓取、评分计算、持久化），只是执行环境从 Cloudflare Worker 切换为 CI/自托管进程。

环境配置（CI / 本地）¶

1. 在 CI 中配置 Secrets - 配置以下环境变量：

   • GITHUB_TOKEN：用于访问 GitHub API
   • PROJECT_FEED_URL（可选）：若脚本直接从已发布站点读取清单，或直接读取仓库内 static/data/ai-projects-manifest.json 则可省略

2. CI 工作流示例行为 - 执行以下步骤：

   • checkout 代码
   • 安装依赖（npm install）
   • 运行脚本（npm run typecheck && node ./tools/ai-oss-rank-worker/dist/backfill.js）
   • 将生成的静态数据文件（例如 static/data/ai-projects-ranking.json）提交回仓库或上传到指定 CDN

3. 本地测试 - 按以下步骤操作：

   • 安装依赖：npm install
   • 类型检查：npm run typecheck
   • 运行测试：node ./tools/ai-oss-rank-worker/dist/worker.js --local --limit=10

部署步骤¶

1. 生成清单并提交 - 执行以下命令：

   npm run generate:ai-manifest
   git add scripts/generate-ai-project-manifest.js static/data/ai-projects-manifest.json \
           assets/scss/layouts/_ai.scss layouts/partials/ai-card.html layouts/ai/single.html \
           tools/ai-oss-rank-worker docs/features/ai-oss-rank-implementation.md
   git commit -m "feat(ai): add ai projects manifest and ranking pipeline"
   git push
   

2. 配置 CI 工作流 - 设置定时任务：

   在仓库中添加或更新 CI 工作流（例如 .github/workflows/ai-rank.yml），配置定时触发与必要的 Secrets（GITHUB_TOKEN）。工作流应运行 tools/ai-oss-rank-worker，生成并提交/上传评分数据文件。

3. 构建并发布网站 - 部署到生产环境：

   正常执行 npm run build 并发布到 Pages/部署平台。若评分数据被提交回仓库，下一次站点构建会包含最新数据；如上传到外部 CDN，则在模板中读取对应 CDN URL。

首轮数据回填¶

在 CI 或本地运行回填脚本，脚本会循环处理清单直到完成；若采用提交回仓库策略，回填完成后会产生一次带有数据文件的 commit。

Hugo 模板占位¶

为确保 HTMLRewriter 有明确挂载点，模板做了以下更新：

• layouts/partials/ai-card.html
• 新增 data-ai-repo="{owner/repo}" 属性，供列表卡片匹配。
• 在卡片正文插入 <div class="ai-health-indicators" data-ai-health-indicators> 作为评分、徽章容器。
• layouts/ai/single.html
• div.ai-detail 与侧边栏信息区添加 data-ai-repo。
• 在标题下方添加 data-ai-health-indicators，用于展示详情页的评分模块。
• 在信息卡内新增 data-ai-health-summary，展示分项指标与统计数据。

样式增强¶

assets/scss/layouts/_ai.scss 新增多个组件样式：

• .ai-score-badge：综合得分圆形徽章
• .ai-health-meter / .ai-score-breakdown / .ai-score-row：评分条布局
• .ai-health-badges：状态徽章容器，包含 --hot / --new / --inactive / --archived
• .ai-detail-health：详情页指标卡片布局
• .ai-card--inactive / .ai-card--archived：卡片灰度、遮罩状态

修改 SCSS 后，执行 npm run build 或常规构建流程即可将样式编译进最终 CSS。

测试清单¶

运维与监控¶

• 日志：使用 Cloudflare Dashboard 查看 Worker Logs，关注 GitHub API 429/5xx。必要时增加 Token 或调整 Cron 频率。
• D1 数据巡检：

wrangler d1 execute ai-oss-rank --command "SELECT repo_slug, score_overall FROM ai_projects ORDER BY score_overall DESC LIMIT 5"

• 异常处理：若 GitHub API 长期失败，可暂缓调用刷新接口，待 GitHub 恢复后再次执行剩余 cursor。
• 批量回填：如果计划手动触发，可运行 npm run backfill -- --base-url=... --no-reset，脚本会从当前游标继续直至完成。
• 缓存策略：Pages Functions 输出仍为静态 HTML，可按需配置 Cloudflare Cache TTL（默认保持原 Hugo 输出）。

常见问题¶

1. 清单缺失仓库：确认内容 front matter 的 github 字段指向 GitHub 仓库且未拼写错误；重新执行生成脚本。
2. 评分未显示：
3. 检查模板是否含 data-ai-repo
4. 确认 D1 中存在对应 repo_slug + locale 的记录
5. 检查 Pages Functions 是否已正确绑定 D1 与 PROJECT_FEED_URL
6. GitHub API 速率受限：
7. 利用多个 Token 轮询（修改 Worker）
8. 增加 Cron 运行间隔或降低并发
9. 页面显示灰度：说明仓库被标记为 inactive 或 archived，可在 D1 中查看 tag_* 字段验证规则是否满足。

后续迭代建议¶

• 增加历史快照表（如 ai_projects_history）记录周级评分曲线，借助可视化展示趋势。
• 引入第三方指标（OpenSSF Scorecard、OpenRank 等）丰富评分维度。
• 对评分阈值引入配置文件（例如存储在 D1 settings 表）以支持在线调权。
• 在详情页增加图表（Sparkline）展示 Star/Commit 趋势。

以上内容覆盖了项目健康度分析功能从数据入口到页面渲染的完整链路。部署、调试或扩展时请以本文档为基础执行。

测试清单¶

运维与监控¶

• 日志：使用 Cloudflare Dashboard 查看 Worker Logs，关注 GitHub API 429/5xx。必要时增加 Token 或调整 Cron 频率。
• D1 数据巡检：

wrangler d1 execute ai-oss-rank --command "SELECT repo_slug, score_overall FROM ai_projects ORDER BY score_overall DESC LIMIT 5"

• 异常处理：若 GitHub API 长期失败，可暂缓调用刷新接口，待 GitHub 恢复后再次执行剩余 cursor。
• 批量回填：如果计划手动触发，可运行 npm run backfill -- --base-url=... --no-reset，脚本会从当前游标继续直至完成。
• 缓存策略：Pages Functions 输出仍为静态 HTML，可按需配置 Cloudflare Cache TTL（默认保持原 Hugo 输出）。

常见问题¶

1. 清单缺失仓库：确认内容 front matter 的 github 字段指向 GitHub 仓库且未拼写错误；重新执行生成脚本。
2. 评分未显示：
3. 检查模板是否含 data-ai-repo
4. 确认 D1 中存在对应 repo_slug + locale 的记录
5. 检查 Pages Functions 是否已正确绑定 D1 与 PROJECT_FEED_URL
6. GitHub API 速率受限：
7. 利用多个 Token 轮询（修改 Worker）
8. 增加 Cron 运行间隔或降低并发
9. 页面显示灰度：说明仓库被标记为 inactive 或 archived，可在 D1 中查看 tag_* 字段验证规则是否满足。

后续迭代建议¶

• 增加历史快照表（如 ai_projects_history）记录周级评分曲线，借助可视化展示趋势。
• 引入第三方指标（OpenSSF Scorecard、OpenRank 等）丰富评分维度。
• 对评分阈值引入配置文件（例如存储在 D1 settings 表）以支持在线调权。
• 在详情页增加图表（Sparkline）展示 Star/Commit 趋势。

以上内容覆盖了项目健康度分析功能从数据入口到页面渲染的完整链路。部署、调试或扩展时请以本文档为基础执行。