AI 项目清单自动生成流程¶

本文档说明 AI 项目清单（manifest）的自动生成机制，确保在添加新的 AI 资源时能够自动更新并同步到 Worker。

概述¶

ai-projects-manifest.json 是一个关键文件，包含了所有 AI 开源项目的元数据。这个文件：

生成位置: static/data/ai-projects-manifest.json
发布位置: https://jimmysong.io/data/ai-projects-manifest.json
消费者: AI OSS Rank Worker 使用此文件获取项目列表并收集 GitHub 指标

自动生成流程¶

触发时机¶

Manifest 会在以下情况自动生成：

本地开发构建 - 运行以下命令：
```
npm run build
```
预览构建 - 运行以下命令：
```
npm run build:preview
```
Cloudflare Pages 部署 - 自动触发流程：
- 当推送到 GitHub 时
- Cloudflare Pages 执行构建命令
- Manifest 自动生成并部署

构建流程¶

npm run build
  ↓
1. npm run generate:ai-manifest  # 生成 AI 项目清单
  ↓
2. npm run generate-analysis     # 生成内容分析数据
  ↓
3. node scripts/run-hugo.js      # Hugo 构建
  ↓
4. npm run compress-json         # 压缩 JSON 文件

生成脚本详解¶

脚本位置¶

scripts/generate-ai-project-manifest.js

工作原理¶

扫描内容目录
遍历 content/zh/ai/ 和 content/en/ai/
读取每个项目的 index.md 文件
提取元数据
GitHub 仓库 URL
项目标题（多语言）
Slug 和页面路径
标签、特色标记、开源日期
数据聚合
按仓库 slug 聚合多语言数据
去重并排序
生成输出

{
  "generatedAt": "2025-10-04T09:18:14.878Z",
  "projectCount": 458,
  "projects": [
    {
      "repo": "microsoft/autogen",
      "github": "https://github.com/microsoft/autogen",
      "locales": ["zh", "en"],
      "titles": {
        "zh": "AutoGen",
        "en": "AutoGen"
      },
      "slugs": {
        "zh": "autogen",
        "en": "autogen"
      },
      "pagePaths": {
        "zh": "/ai/autogen/",
        "en": "/en/ai/autogen/"
      },
      "tags": {
        "zh": ["AI Agent", "Dev Tools"],
        "en": ["AI Agent", "Dev Tools"]
      },
      "featured": {
        "zh": false,
        "en": false
      },
      "ossDates": {
        "zh": "2023-08-18T11:43:45.000Z",
        "en": "2023-08-18T11:43:45.000Z"
      }
    }
  ]
}

添加新项目的工作流¶

1. 创建项目内容¶

# 创建中文版本
hugo new content/zh/ai/my-project/index.md

# 创建英文版本
hugo new content/en/ai/my-project/index.md

2. 编辑 Front Matter¶

确保包含必要字段：

---
title: "项目名称"
github: "https://github.com/owner/repo"
slug: "my-project"
tags:
  - "AI Agent"
  - "Dev Tools"
featured: false
oss_date: "2024-01-01T00:00:00Z"
---

3. 本地测试¶

# 生成 manifest
npm run generate:ai-manifest

# 检查生成的文件
cat static/data/ai-projects-manifest.json | grep "my-project"

# 完整构建测试
npm run build

4. 提交并推送¶

git add content/zh/ai/my-project/
git add content/en/ai/my-project/
git commit -m "feat: 添加 AI 项目 my-project"
git push

5. 自动部署¶

Cloudflare Pages 检测到推送
执行 npm run build
Manifest 自动生成并部署
Worker 在下次同步时获取新项目

Worker 同步机制¶

自动同步¶

AI OSS Rank Worker 每周自动同步一次：

[triggers]
crons = ["0 0 * * 1"]  # 每周一午夜（UTC）

手动同步（推荐）¶

添加新项目后，使用同步脚本立即更新数据库：

方法一：使用 npm 脚本（最简单）

cd tools/ai-oss-rank-worker

# 同步特定项目
npm run sync:repo rasbt/LLMs-from-scratch

# 增量同步（下一批）
npm run sync

# 完全重新同步所有项目
npm run sync:full

方法二：使用 shell 脚本

cd tools/ai-oss-rank-worker

# 查看所有选项
bash scripts/sync-new-projects.sh --help

# 同步特定项目
bash scripts/sync-new-projects.sh --mode single --repo owner/repo

# 仅同步中文项目
bash scripts/sync-new-projects.sh --locale zh --limit 20

# 完全重新同步
bash scripts/sync-new-projects.sh --mode full --reset

方法三：直接使用 curl

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

# 增量同步所有项目
curl "https://ai-oss-rank-worker.jimmysong.workers.dev/recalculate"

# 完全重新同步（重置游标）
curl "https://ai-oss-rank-worker.jimmysong.workers.dev/recalculate?reset=true"

完整工作流示例：

# 1. 创建新 AI 资源
hugo new content/zh/ai/my-project/index.md
hugo new content/en/ai/my-project/index.md

# 2. 编辑 front matter，确保包含 github 字段

# 3. 提交并推送
git add content/*/ai/my-project/
git commit -m "feat: 添加 AI 项目 my-project"
git push

# 4. 等待 Cloudflare Pages 部署（约 2-3 分钟）
# 这会自动生成并发布新的 manifest.json

# 5. 同步到 Worker 数据库
cd tools/ai-oss-rank-worker
npm run sync:repo owner/repo

# 6. 验证数据已同步
curl "https://ai-oss-rank-worker.jimmysong.workers.dev/api/health/owner/repo?locale=zh" | jq .

# 7. 访问网站查看
open https://jimmysong.io/ai/my-project/

验证和调试¶

验证 Manifest 生成¶

# 1. 运行生成脚本
npm run generate:ai-manifest

# 2. 检查项目数量
cat static/data/ai-projects-manifest.json | grep projectCount

# 3. 验证特定项目
cat static/data/ai-projects-manifest.json | jq '.projects[] | select(.repo == "microsoft/autogen")'

验证部署后的 Manifest¶

# 检查线上版本
curl https://jimmysong.io/data/ai-projects-manifest.json | jq '.projectCount'

# 查看生成时间
curl https://jimmysong.io/data/ai-projects-manifest.json | jq '.generatedAt'

# 搜索特定项目
curl https://jimmysong.io/data/ai-projects-manifest.json | jq '.projects[] | select(.repo == "microsoft/autogen")'

常见问题¶

1. Manifest 没有更新¶

原因: 构建脚本没有执行或失败

解决:

# 检查构建日志
npm run build 2>&1 | tee build.log

# 手动运行生成脚本
npm run generate:ai-manifest

2. 项目缺失¶

原因: Front matter 缺少 github 字段或格式错误

解决:

# 检查项目的 index.md
cat content/zh/ai/my-project/index.md | grep github

# 验证 GitHub URL 格式
# 正确: https://github.com/owner/repo
# 错误: http://github.com/owner/repo （使用 http）
# 错误: https://github.com/owner/repo.git （包含 .git）

3. Worker 没有新数据¶

原因: Worker 还没有同步新的 manifest

解决:

# 手动触发同步
curl "https://ai-oss-rank-worker.jimmysong.io/recalculate?repo=owner/repo"

# 检查 Worker 日志
wrangler tail ai-oss-rank-worker

监控和维护¶

定期检查¶

建议每月检查一次：

# 1. 验证项目数量
curl https://jimmysong.io/data/ai-projects-manifest.json | jq '.projectCount'

# 2. 检查生成时间
curl https://jimmysong.io/data/ai-projects-manifest.json | jq '.generatedAt'

# 3. 验证 Worker 数据
curl "https://ai-oss-rank-worker.jimmysong.io/api/health?repos=microsoft/autogen&locale=zh"

数据一致性¶

确保以下数据源同步：

Content 目录: content/*/ai/
Manifest 文件: static/data/ai-projects-manifest.json
Worker D1 数据库: AI OSS Rank Worker
前端显示: 网站 AI 资源页面

脚本源码¶

完整实现请参考：scripts/generate-ai-project-manifest.js