AI OSS Rank 同步指南¶

本文档介绍 AI OSS Rank 项目的同步机制和使用方法。

同步机制概览¶

三种同步方式¶

触发方式	条件	同步范围	耗时	说明
自动部署	Git push + Manifest 有变化	仅新增项目	~2-5 秒	检测到新项目自动同步
定时任务	每日 00:00 UTC	全量 460 项目	~8-10 分钟	Worker cron 全量同步
手动触发	执行命令	可自定义	按需	开发调试使用

自动部署同步¶

工作流程：

graph TD
    A[Git Push] --> B[Cloudflare Pages 部署]
    B --> C[检查 manifest 变化]
    C --> D{Manifest 是否变化?}
    D -->|否| E[跳过同步 ~0.5秒]
    D -->|是| F[检测新项目]
    F --> G{是否有新项目?}
    G -->|是| H[同步新项目 ~2-5秒]
    G -->|否| I[跳过同步 元数据更新等待cron]
    H --> J[完成]
    E --> J
    I --> J

部署日志示例：

🔍 Checking AI projects manifest changes...
✨ Manifest changes detected, checking for new projects...

🎯 Found 2 new project(s):
   • microsoft/autogen
   • openai/whisper

🔄 Syncing new projects...
   ✅ microsoft/autogen synced successfully
   ✅ openai/whisper synced successfully

✅ Successfully synced 2 new project(s)
✓ Post-deploy sync completed

配置：

脚本：scripts/post-deploy-sync.js
触发：package.json 的 postbuild hook
环境变量：Cloudflare Pages 自动设置

定时任务同步¶

Worker 配置了每日全量同步：

# tools/ai-oss-rank-worker/wrangler.toml
[triggers]
crons = ["0 0 * * *"]  # 每天 00:00 UTC

执行逻辑（worker.ts scheduled 函数）：

async scheduled(_, env) {
  // 1. 重置 cursor 到 0
  await writeSyncCursor(env, STATE_KEY_FULL_SYNC, 0);

  // 2. 循环处理所有项目
  while (cursor < totalProjects) {
    const result = await executeSync(env, {}, cursor, 10, false);
    cursor = result.nextCursor;
    // 每批间隔 1 秒
    await sleep(1000);
  }
}

特点：

✅ 保证数据完整性
✅ 更新所有项目的 GitHub 指标
✅ 处理遗漏的项目
⏱️ 约 8-10 分钟完成全量同步

手动同步¶

可用命令¶

1. 本地全量同步¶

npm run sync:worker:full

输出示例：

🔄 Triggering FULL sync (all projects)...
   Worker URL: https://ai-oss-rank-worker.jimmysong.io
   Manifest count: 460 projects
   Strategy: Loop until all projects synced

📦 Batch #1 (cursor: 0)
   Processed: 10/10 (failures: 0)
   Total: 10/460

📦 Batch #2 (cursor: 10)
   Processed: 10/10 (failures: 0)
   Total: 20/460

...

✅ Full sync completed!
   Total processed: 460 projects
   Total batches: 46

用途：

本地开发测试
手动触发全量更新
验证同步功能

2. 同步特定项目¶

npm run sync:repo owner/project

示例：

npm run sync:repo microsoft/autogen

用途：

新增项目后立即同步
更新特定项目的指标
调试单个项目

3. 增量同步¶

npm run sync:worker

行为：

从当前 cursor 位置同步下一批 10 个项目
不重置 cursor

用途：

手动触发增量更新
测试同步逻辑

4. 等待部署后同步¶

npm run sync:worker:wait

行为：

等待 180 秒（模拟部署完成）
然后触发增量同步

用途：

CI/CD 流程中使用

脚本参数¶

scripts/trigger-worker-sync.sh 支持的参数：

# 查看帮助
bash scripts/trigger-worker-sync.sh --help

# 同步特定项目
bash scripts/trigger-worker-sync.sh --repo owner/project

# 全量同步
bash scripts/trigger-worker-sync.sh --full

# 自定义批次大小
bash scripts/trigger-worker-sync.sh --limit 50

# 等待后同步
bash scripts/trigger-worker-sync.sh --wait --repo owner/project

直接调用 Worker API¶

# 同步特定项目
curl "https://ai-oss-rank-worker.jimmysong.io/recalculate?repo=owner/project"

# 批量同步（从当前 cursor）
curl "https://ai-oss-rank-worker.jimmysong.io/recalculate?limit=10"

# 批量同步（从指定 cursor）
curl "https://ai-oss-rank-worker.jimmysong.io/recalculate?limit=10&cursor=100"

添加新项目的推荐流程¶

最佳实践（自动同步）¶

# 1. 编辑 manifest
vim data/ai-projects-manifest.json

# 2. 提交推送
git add data/ai-projects-manifest.json
git commit -m "feat: add AI project microsoft/autogen"
git push

# 3. 完成！
# ✅ 部署会自动检测并同步新项目（2-5秒）

优点：

无需手动操作
自动化流程
部署即可用

备选方案（手动同步）¶

如果需要立即验证或部署同步失败：

# 1. 提交推送
git push

# 2. 等待部署完成（2-3 分钟）

# 3. 手动同步新项目
npm run sync:repo microsoft/autogen

# 4. 验证
curl "https://jimmysong.io/api/ai/projects/microsoft/autogen" | jq

常见问题¶

Q1: 新项目多久能在网站上看到？¶

自动同步：

Git push → 部署完成 → 自动检测并同步 → 约 3-5 分钟

手动同步：

npm run sync:repo owner/project → 约 2 秒

定时任务：

等待每日 00:00 UTC cron → 最多 24 小时

Q2: 为什么部署时跳过了同步？¶

原因：Manifest 没有变化

日志输出：

🔍 Checking AI projects manifest changes...
ℹ️  No changes in AI projects manifest, skipping sync
   Daily cron job at 00:00 UTC handles routine synchronization

✓ Post-deploy check completed

这是正常的！ 只有 Manifest 有变化时才会触发同步，避免不必要的 API 调用。

Q3: 修改了项目元数据，但没有同步？¶

原因：元数据更新不会触发即时同步

日志输出：

🔍 Checking AI projects manifest changes...
✨ Manifest changes detected, checking for new projects...

ℹ️  Manifest updated but no new projects detected
   Changes may be metadata updates (existing projects will sync via cron)

解决方案：

等待每日 cron（推荐）
或手动同步：npm run sync:repo owner/project

Q4: 如何确认同步成功？¶

方法 1：查询 API

curl "https://jimmysong.io/api/ai/projects/owner/project" | jq

方法 2：查看 Worker 日志

npx wrangler tail ai-oss-rank-worker

方法 3：检查 D1 数据库

npx wrangler d1 execute ai-oss-rank-db \
  --command "SELECT * FROM ai_oss_metrics WHERE repo = 'owner/project'"

Q5: 遇到 "Too many subrequests" 错误？¶

原因：Cloudflare Worker 有 50 个 subrequest 限制，每个项目需要 3-5 个请求。

当前配置：

每批 10 个项目（~30 subrequests，安全范围）

解决方案（如果仍然出错）：

检查是否有其他 subrequest 消耗
考虑进一步减少批次大小

环境变量¶

Cloudflare Pages¶

变量	默认值	说明
`WORKER_URL`	`https://ai-oss-rank-worker.jimmysong.io`	Worker API 端点
`SYNC_LIMIT`	`10`	增量同步批次大小
`SYNC_ENABLED`	`true`	是否启用自动同步
`CF_PAGES`	自动设置	标识 Cloudflare Pages 环境

本地开发¶

# 模拟 Cloudflare Pages 环境
export CF_PAGES=1
export CF_PAGES_BRANCH=main
export CF_PAGES_COMMIT_SHA=$(git rev-parse HEAD)
export WORKER_URL=https://ai-oss-rank-worker.jimmysong.io

# 运行同步
node scripts/post-deploy-sync.js