sync-provider

同步提供商

同步克隆的提供商仓库中的更改，同时保留本地自定义内容。

概述

除 opencode 外，大多数提供商都从外部仓库克隆而来，需要与上游更改保持同步。本技能将指导你完成整个工作流，从检查更新到安全应用更改。

前提条件

1. GitHub CLI (gh)：必须已安装并完成身份验证

   gh --version
   gh auth login
   gh auth status
   

2. GitHub 令牌：将 GITHUB_TOKEN 添加到根目录的 .env 文件中

   GITHUB_TOKEN=your_token_here
   

3. 仓库信息：每个提供商的 package.json 都包含 repository.url 字段（格式：https://github.com/owner/repo-name）

工作流

步骤 1：识别提供商和仓库

检查提供商的 package.json 中的仓库 URL：

cat providers/<provider>/package.json | grep -A 2 repository

提取 owner/repo 格式：https://github.com/owner/repo-name → owner/repo-name

步骤 2：检查是否有新提交

使用 check-provider-commit.sh 自动检查是否有新提交：

COMMIT_HASH=$(scripts/check-provider-commit.sh <provider> 2>/dev/null)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ] && [ -n "$COMMIT_HASH" ]; then
  echo "Proceeding with sync from commit: $COMMIT_HASH"
elif [ $EXIT_CODE -eq 0 ]; then
  echo "Already up to date - no sync needed"
  exit 0
else
  echo "No state file found - need to determine initial commit hash manually"
  exit 1
fi

脚本行为：

• 已是最新：以代码 0 退出，并显示“已是最新”
• 有新提交：输出提交哈希（上次同步的提交），以代码 0 退出
• 没有状态文件：以代码 1 退出，并显示最新提交（首次同步时需要手动确定）

重要提示： 捕获提交哈希时，重定向标准错误输出（2>/dev/null），以避免混入提示信息。

步骤 3：运行 Git diff 脚本

使用适当的参数执行同步脚本：

REPO=$(cat providers/<provider>/package.json | grep -A 2 repository | grep url | cut -d'"' -f4 | sed 's|https://github.com/||')

pnpm exec tsx scripts/git-diff.ts \
  -r $REPO \
  -c "$COMMIT_HASH" \
  -i "src/**/*" \
  -i "docs/**/*" \
  -i "examples/**/*" \
  --state-file-path ./providers/<provider>/diff_last_commit.txt

参数：

• -r, --repo：采用 owner/repo 格式的 GitHub 仓库（必需）
• -c, --commit：用于比较的提交哈希（必需）——使用状态文件中上次同步的提交
• -i, --include：用于筛选文件的 Glob 模式（可多次指定）
  • 始终使用以下三个默认模式：
    • src/**/* - 所有源文件
    • docs/**/* - 文档文件
    • examples/**/* - 示例文件
• --state-file-path：存储上次同步的提交哈希的路径

步骤 4：深入研究和分析

必须执行：应用任何更改之前，先进行深入研究：

# List all generated diff files
ls -R .diffs/<commit_hash>/

# Review all diffs to understand scope
find .diffs/<commit_hash>/ -name "*.txt" -exec echo "=== {} ===" \; -exec cat {} \;

# Get list of affected files
find .diffs/<commit_hash>/ -name "*.txt" | sed "s|\.diffs/<commit_hash>/||" | sed 's|\.txt$||'

研究步骤：

1. 分析所有差异：检查每个差异文件，了解：

   • 正在修改、添加或删除的文件
   • 更改性质（错误修复、功能、重构、破坏性更改）
   • 对现有本地自定义内容的影响
   • 更改之间的依赖关系

2. 检查本地自定义内容：检查当前本地文件，以确定：

   • 可能发生冲突的自定义修改
   • 应予以保留的本地添加内容
   • 配置差异

3. 查看项目规则：必须执行——检查 .cursor/rules，了解：

   • 哪些规则适用于此提供商（TypeScript、React 等）
   • 项目标准和模式
   • 相关技术的最佳实践

第 5 步：使用 Pal MCP 创建重构计划

必须：使用 Pal MCP 重构工具和 Gemini 3.0 Pro 创建全面的计划。

- **任务作废**：在完成 Pal Refactor 工具的所有步骤之前，如果你对文件进行任何编辑，**任务将作废** - **不得例外**：在操作任何文件之前，必须完成整个 Pal Refactor 工作流（所有步骤，直到 `next_step_required: false`） - **验证**：只有在收到 Pal Refactor 所有步骤均已完成的确认后，才能继续执行第 7 步

重构工具用法：

1. 确定相关文件：收集所有会受影响的文件：

   • .diffs/<commit_hash>/ 中有变更的文件
   • providers/<provider>/ 中与变更文件相对应的当前本地文件
   • 所有文件都使用完整绝对路径

2. 运行 Pal Refactor 分析：

   // Use mcp_zen_refactor with:
   // - model: "gemini-3.0-pro" or "anthropic/claude-opus-4.6"
   // - relevant_files: Array of absolute paths to affected files
   // - refactor_type: "modernize" or "organization" (as appropriate)
   // - focus_areas: ["sync-upstream-changes", "preserve-local-customizations"]
   

3. 完成所有步骤：必须完成所有步骤，直到 next_step_required: false

   • 持续调用重构工具，直到收到所有步骤均已完成的确认
   • 在确认完成之前，不要继续编辑任何文件
   • 如果跳过此步骤，任务将作废

4. 查看重构建议：工具将提供：

   • 应用变更的最佳方法
   • 如何保留本地自定义内容
   • 潜在冲突及其解决方法
   • 代码质量改进
   • 架构方面的考量

重构工具要求：

• 模型：必须使用 gemini-3.0-pro 或 anthropic/claude-opus-4.6
• 多步骤：完成所有步骤，直到 next_step_required: false——不得例外
• 文件路径：使用完整绝对路径（例如，/Users/pedronauck/Dev/compozy/compozy-code/providers/claude-code/src/index.ts）
• 重点领域：提供有关同步上游变更并保留本地自定义内容的上下文
• 完成情况验证：只有在工具确认所有步骤均已完成后，才能继续

第 6 步：创建实施计划

根据 Pal 重构分析，创建详细的实施计划：

1. 确定变更优先级：按依赖关系排序（先处理依赖项）、风险等级排序（先处理低风险项）、影响范围排序（先处理关键文件）

2. 确定冲突：记录存在与上游变更冲突的本地自定义文件、每个冲突的解决策略，以及保留与更新内容的决策

3. 规划测试策略：确定每项变更后要运行哪些测试、如何验证本地自定义内容已保留，以及要测试的集成点

4. 记录决策：记录应用或跳过某些变更的原因、保留本地自定义内容的方式，以及做出的任何架构决策

第 7 步：按计划应用变更

- **必须验证**：继续之前，请验证： 1. Pal Refactor 的所有步骤均已完成（`next_step_required: false`） 2. 你已收到完整的重构分析和建议 3. 你已创建详细的实施计划（第 6 步） - **任务作废**：在完成 Pal Refactor 的所有步骤之前，如果你开始编辑文件，**任务将作废** - **不得例外**：即使你认为自己已理解变更，也必须先完成整个 Pal Refactor 工作流

只有在完成第 4 至第 6 步并确认 Pal Refactor 已完成后，才能应用变更：

1. 对于已修改的文件：按照重构计划应用变更，同时保留本地自定义内容
2. 对于新增文件：遵循项目规范添加新文件
3. 对于已删除的文件：评估是否应在本地应用删除（可能需要保留）
4. 对于已重命名的文件：根据计划处理重命名和内容变更

最佳实践：

• 按优先级计划逐步应用变更
• 每次重大变更后运行测试
• 保留计划中确定的本地自定义内容
• 记录与计划有任何偏差

步骤 8：更新状态文件

成功应用更改后，确认状态文件已更新：

cat providers/<provider>/diff_last_commit.txt
# Should contain the latest commit hash that was synced

示例工作流

同步 claude-code 提供方

# 1. Check repository info
cat providers/claude-code/package.json | grep repository

# 2. Check for new commits
COMMIT_HASH=$(scripts/check-provider-commit.sh claude-code 2>/dev/null)
EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
  echo "⚠️  No state file found - need to determine initial commit hash manually"
  exit 1
elif [ -z "$COMMIT_HASH" ]; then
  echo "✅ Already up to date - no sync needed"
  exit 0
fi

# 3. Extract repository name
REPO=$(cat providers/claude-code/package.json | grep -A 2 repository | grep url | cut -d'"' -f4 | sed 's|https://github.com/||')

# 4. Run sync script
pnpm exec tsx scripts/git-diff.ts \
  -r $REPO \
  -c "$COMMIT_HASH" \
  -i "src/**/*" \
  -i "docs/**/*" \
  -i "examples/**/*" \
  --state-file-path ./providers/claude-code/diff_last_commit.txt

# 5. Deep research and analysis
find .diffs/$COMMIT_HASH/ -name "*.txt" -exec echo "=== {} ===" \; -exec cat {} \;

# 6. Use Pal MCP refactor tool (complete all steps)
# 7. Create implementation plan
# 8. Apply changes according to plan
# 9. Verify state file updated
cat providers/claude-code/diff_last_commit.txt

可用提供方

提供方	仓库	备注
claude-code	ben-vargas/ai-sdk-provider-claude-code	已克隆
gemini	ben-vargas/ai-sdk-provider-gemini-cli	已克隆
codex	ben-vargas/ai-sdk-provider-codex-cli	已克隆
opencode	N/A	在本地创建 - 无需同步

关键要求

- **必须**使用 `gh` CLI 自动检查是否有新提交，然后再进行同步 - **必须**在运行脚本前，通过 `package.json` 验证仓库 URL - **必须**始终使用三个默认包含模式：`src/**/*`、`docs/**/*`、`examples/**/*` - **必须**使用状态文件中的提交哈希（上次同步的提交）作为 `-c` 参数 - **必须**在制定计划前，对所有差异进行深入研究和分析 - **必须**查看 `.cursor/rules` 文件，了解哪些规则适用（强制步骤） - **必须**使用 Pal MCP 重构工具和 Gemini 3.0 Pro，找出应用更改的最佳方法 - **必须**完成 Pal 重构工具的所有步骤——不要中途停止 - **必须**在进行任何文件编辑前，确认 Pal 重构已完成（`next_step_required: false`） - **必须**在应用更改前，根据重构分析制定详细的实施计划 - 使用 Pal MCP 工具时，**必须**使用完整的绝对路径（切勿使用相对路径） - 应用上游更改时，**必须**保留本地自定义内容 - 应用更改后，**必须**测试提供方（在提供方目录中运行 `pnpm test`） - 应用更改后，**必须**运行 lint 和类型检查（`pnpm run lint && pnpm run typecheck`） - **必须**更新状态文件路径，使其与提供方目录结构一致 - **切勿**同步 `opencode` 提供方（该提供方是在本地创建的，并非克隆而来） - **切勿**在未进行深入研究和规划的情况下直接应用更改 - **切勿**在完成 Pal 重构的所有步骤前开始编辑文件 - **切勿**使用权宜之计——应始终优先采用良好且设计完善的解决方案 - **始终**使用准确的仓库格式：`owner/repo-name`（不要加 `https://github.com/` 前缀） - **始终**在制定计划前，检查 `.diffs//` 文件夹是否存在且包含预期文件 - **始终**确认 `gh` CLI 已通过身份验证（`gh auth status`） - **始终**采用绿地开发方式——不必考虑向后兼容，优先保证质量 - **始终**在开始前再次确认 `.cursor/rules` 中哪些规则适用于该任务（强制步骤）

故障排除

没有文件匹配 glob 模式

• 检查提交哈希是否正确
• 确认仓库名称格式
• 使用更宽泛的模式（如 **/*）查看所有更改

未找到状态文件

• 首次同步：使用克隆时的初始提交哈希
• 后续同步：脚本会自动创建状态文件

检测到二进制文件

二进制文件会记录在 .diffs/<commit_hash>/<file-path>.txt 中，但不会生成差异。请手动处理：

• 图片：在 GitHub 上查看或直接下载
• 其他二进制文件：判断是否需要更新

GitHub API 速率限制

• 稍后重试
• 使用速率限制更高的 GitHub 令牌
• 考虑分批进行同步

同步后

• 必须测试：在提供方目录中运行测试：

  cd providers/<provider>
  pnpm test
  pnpm run lint
  pnpm run typecheck
  

• 必须验证：确保所有更改均已正确应用，且未丢失任何本地自定义内容

• 必须记录：记录同步过程中做出的所有决定，尤其是：

  • 已解决的冲突
  • 已保留的本地自定义内容
  • 与上游更改的差异
  • 架构决策