Skip to content

AI 资源标签同步工具

概述

sync-ai-tags.js 是一个自动化脚本，用于将中文 AI 资源（content/zh/ai/）中的标签同步到对应的英文 AI 资源（content/en/ai/）中。这样你只需要维护中文版本的标签，英文版本会自动同步。

功能特性

  • 🔄 自动同步标签：从中文版本读取 tags，自动更新到英文版本
  • 🎯 批量或单个处理：支持同步所有资源或指定单个资源
  • 👀 预览模式：使用 --dry-run 参数可以预览将要进行的更改而不实际修改文件
  • 📊 详细报告：提供清晰的同步统计信息和变更详情
  • ⚠️ 错误处理：自动检测缺失的文件和错误，并提供警告信息

使用方法

1. 同步所有 AI 资源

npm run sync-ai-tags

或直接运行脚本：

node scripts/sync-ai-tags.js

2. 预览模式（推荐首次使用）

在实际修改文件之前，先预览将要进行的更改：

npm run sync-ai-tags -- --dry-run

或：

node scripts/sync-ai-tags.js --dry-run

3. 同步特定资源

只同步某个特定的 AI 资源（例如 cline）：

node scripts/sync-ai-tags.js cline

预览特定资源的更改：

node scripts/sync-ai-tags.js --dry-run cline

输出示例

预览模式输出

🔄 Synchronizing AI resource tags from Chinese to English...

📋 DRY RUN MODE - No files will be modified

✓ agentgateway: Would update
  Old tags: [OSS, MCP, AI Agent, Dev Tools]
  New tags: [OSS, AI Gateway]
✓ cline: Already synchronized
✓ semantic-router: Already synchronized

════════════════════════════════════════════════════════════
📊 Summary:
  Total resources: 379
  Updated: 48
  Already synchronized: 310
  Skipped: 3
  Errors: 18

💡 Run without --dry-run to apply changes

实际执行输出

🔄 Synchronizing AI resource tags from Chinese to English...

✓ agentgateway: Updated
  Old tags: [OSS, MCP, AI Agent, Dev Tools]
  New tags: [OSS, AI Gateway]
✓ cline: Already synchronized

════════════════════════════════════════════════════════════
📊 Summary:
  Total resources: 379
  Updated: 48
  Already synchronized: 310
  Skipped: 3
  Errors: 0

✅ Tags synchronized successfully!

状态说明

脚本会显示每个资源的处理状态：

  • ✓ Updated / Would update: 标签已更新或将要更新
  • ✓ Already synchronized: 标签已经是同步状态，无需更改
  • ⊘ Skipped: 跳过处理（通常是因为中文版本没有标签）
  • ⚠ Warning: 警告信息（例如英文文件不存在）

工作流程建议

日常维护流程

  1. 在中文 AI 资源文件中更新标签
  2. 运行预览模式查看将要同步的更改：
npm run sync-ai-tags -- --dry-run
  1. 确认无误后执行实际同步：
npm run sync-ai-tags
  1. 提交更改到 git

批量更新标签

如果你一次性更新了多个中文 AI 资源的标签：

# 1. 先预览所有更改
node scripts/sync-ai-tags.js --dry-run

# 2. 确认无误后执行同步
node scripts/sync-ai-tags.js

# 3. 查看git变更
git status
git diff content/en/ai/

# 4. 提交更改
git add content/en/ai/
git commit -m "Sync AI resource tags from Chinese to English"

注意事项

YAML 格式化

gray-matter 库在解析和重写 YAML front matter 时可能会重新格式化某些字段：

  • 添加引号到 URL 等字段
  • 将长描述转换为多行格式
  • 调整数组的缩进格式

这些都是正常的 YAML 格式化行为，不会影响内容的实际含义。

文件缺失

如果某个中文资源在英文目录中没有对应文件，脚本会显示警告但不会报错：

⚠ Warning: English file not found: /path/to/content/en/ai/resource-name/index.md

这种情况下，你需要先创建对应的英文资源文件。

空标签处理

如果中文版本没有设置标签，脚本会跳过该资源，不会清空英文版本的标签。

技术细节

实现原理

  1. 扫描 content/zh/ai/ 目录下的所有子目录
  2. 对每个目录，读取 index.md 文件的 front matter
  3. 提取 tags 字段
  4. 在对应的 content/en/ai/ 目录中找到同名资源
  5. 更新英文版本的 tags 字段
  6. 保持其他 front matter 字段不变

依赖

  • gray-matter: YAML front matter 解析和序列化
  • Node.js 内置模块：fs, path

脚本位置

scripts/sync-ai-tags.js

相关脚本

  • scripts/update-lastmod.js: 更新 lastmod 字段
  • scripts/remove-tags-by-list.js: 批量删除特定标签
  • scripts/remove-tags-by-frequency.js: 按频率删除标签

故障排查

脚本执行失败

如果脚本运行出错，请检查：

  1. 是否在项目根目录执行
  2. Node.js 版本是否满足要求（v20+）
  3. 依赖是否已安装（npm install）

标签未同步

如果某些标签没有同步，请检查：

  1. 中文版本的 front matter 格式是否正确
  2. tags 字段是否使用正确的 YAML 数组格式
  3. 运行时是否有警告或错误信息

格式变化过大

如果发现 YAML 格式变化过大，这通常是 gray-matter 的正常格式化行为。你可以：

  1. 使用 git diff 仔细检查实际内容是否正确
  2. 如果只是格式变化，可以安全提交

贡献

如果你发现 bug 或有改进建议，欢迎提交 Issue 或 Pull Request。