mcpField
S
sync-upstream

sync-upstream

github.com/leandrocfe开发4172 次安装11 周前更新
代码仓库

关于 sync-upstream

用于将本仓库中的 skills 按上游项目的正式版本逐次同步的维护流程。它要求先检查变更并提交适配方案供维护者审批，再执行修改和验证，同时保留仓库自身的命名与专属内容。

主要功能

  1. 01按 release 逐次同步
  2. 02先查看 changelog 与差异
  3. 03审批后再应用变更
  4. 04保留本仓库专属 skills
  5. 05校验插件清单与引用

适用场景

  1. 01检查上游版本间的 skill 变化
  2. 02处理上游 skill 重命名或删除
  3. 03准备同步报告并等待维护者批准
  4. 04更新版本记录并完成 release

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/leandrocfe/skills --skill sync-upstream

安装后在 Claude Code 中输入/sync-upstream确认已加载。

详细介绍

与上游同步

本仓库是 mattpocock/skills 的巴西葡萄牙语改编版。目标不是逐字翻译：每项 skill 都保留原版的用途、行为、流程和意图，同时采用适合巴西受众的语言、示例和背景。

上游使用 semver 发布版本，并通过 CHANGELOG.md 记录每项变更。同步按每个发布版本进行，绝不持续跟踪分支。

真相来源

本仓库根目录下的 UPSTREAM.md：

  • upstream-version: — 最近一次完全同步的上游标签；
  • 本项目身份相关的有意重命名映射；
  • 本仓库独有的 skills（绝不移除——上游没有对应项）；
  • 已知待处理事项。

remote upstream 指向 Matt 的仓库。如果不存在：git remote add upstream https://github.com/mattpocock/skills.git。

标签命名空间

上游标签位于 upstream/* 下（例如：upstream/v1.1.0）；干净的 vX.Y.Z 命名空间属于本仓库的发布版本。这样就可以为同步打标签，而不会与 Matt 同名的标签冲突。

remote 已配置为使用此命名空间。如果新克隆的仓库尚未配置：

git config remote.upstream.tagOpt --no-tags
git config --add remote.upstream.fetch "+refs/tags/*:refs/tags/upstream/*"

绝不要运行 git fetch upstream --tags——这会将 Matt 的标签放入干净的命名空间，重新引入冲突。

流程

1. 找出差异
git fetch upstream
  • BASE = UPSTREAM.md 中 upstream-version: 的值（例如：v1.1.0），读取为 upstream/$BASE。
  • ALVO = 上游最新标签：git tag -l 'upstream/v*' | sort -V | tail -1。
  • BASE == ALVO → 无需处理，结束。
2. 理解变更——先看 CHANGELOG，再看 diff

  1. 阅读上游 CHANGELOG.md 中 BASE 到 ALVO 之间的章节（git show upstream/$ALVO:CHANGELOG.md）。它会说明发生了什么以及为什么——以此作为报告框架，不要从头重新整理。

  2. 生成实际差异，并检测重命名：

    git diff -M upstream/$BASE..upstream/$ALVO -- skills/ .claude-plugin/plugin.json

    docs/ 有意排除在外——请参阅 UPSTREAM.md 中有意保留的差异。

  3. 将 diff 与 UPSTREAM.md 中的名称映射对照（例如：对 setup-matt-pocock-skills 的变更应应用于 setup-leandrocfe-skills）。

3. 报告与提案——修改任何文件之前

向维护者说明：

  • 按类别归纳变更（新增 skills、重命名、修改、移除）；
  • 对每项变更说明：改了什么、为何重要（引用 CHANGELOG）以及对本版本的影响；
  • 提出适配方案，并遵守以下规则；
  • 明确标出需要人工决定的事项。

**在此处停止并等待批准。**如果存在歧义、版本冲突或多种有效的适配方案，请先询问再继续。

4. 应用变更——仅在获批后
  • 逐项适配 skill；绝不要复制粘贴。
  • 使用 git mv 镜像上游的重命名，但 UPSTREAM.md 映射中列出的项目除外。
  • 更新 .claude-plugin/plugin.json：skills 列表必须与实际目录一致，version 字段必须与同步的标签一致。“ARS scope guard” hook 会阻止 agents 写入此文件——将内容交给维护者手动保存，或请维护者关闭该 hook。
  • 检查本仓库独有的 skills（personal/）是否引用了上游 skills：重命名会导致这些引用无提示地失效。
  • 最后验证：plugin.json 中的每个条目都存在于 skills/ 中；frontmatter 中的 name: 均与目录名一致；没有遗留对已失效 skill 名称的引用（使用 grep 搜索旧名称）；根据 CLAUDE.md 更新 bucket 和顶层 README。
5. 完成同步
  1. 将 UPSTREAM.md 中的 upstream-version: 更新为 ALVO，并清理已解决的待办事项。
  2. 提交：sync: upstream ALVO。
  3. 为此仓库的发布创建标签，版本号与上游保持一致：git tag -a $ALVO -m "sync: upstream $ALVO"。由于 Matt 的标签位于 upstream/* 下，因此干净的命名空间可用。
  4. 运行 git push origin $ALVO 前，先与维护者确认推送事宜。
  5. 如果工作流创建了同步 issue，请将其关闭。
  6. 可选：翻译 CHANGELOG 中的发布说明，并将其发布为此仓库的发布说明。

适配规则

  • 切勿自动复制上游内容。
  • 保留此项目的身份特征（UPSTREAM.md 中映射的名称）。
  • 使用巴西葡萄牙语；保留约定俗成的英文技术术语。
  • 使用专业、精炼的文风。 不使用俚语、口语或刻意随意的表达（例如：“UX gostosa”“sacada”“dá pra”“maneiro”）。请将内容译为结构清晰、适合技术文档的葡萄牙语，优先选用准确术语。原文中的营销形容词（“delightful”“beautiful”）应译为稳重的对应表达（“精致”“做工精良”），而非俚语。如有疑问，请大声读一遍：如果听起来不像技术手册中的表达，请改写。
  • 优先保留技能的行为和意图，而非沿用相同措辞。
  • 对 Matt 现实中非常具体的示例，在适当时请提出符合巴西语境的替代方案。
  • 保留此仓库现有的定制内容，除非它们与上游的重要改进冲突——此时请在第 3 步的报告中指出冲突。
  • 切勿移除 UPSTREAM.md 中列出的专属技能。

与其自动同步，不如谨慎更新并充分说明理由。应用每项建议前，请先解释原因。

评论

支持 Markdown