AGENT SKILL

cn-sync

增量同步英文内容;当需要将当前中文镜像项目对齐 https://github.com/mattpocock/skills 的最新变化时使用

License 许可
MIT
最近更新
2026-07-23
Stars
★ 1
Forks
0

01 前言 Front Matter

name
cn-sync
description
增量同步英文内容;当需要将当前中文镜像项目对齐 https://github.com/mattpocock/skills 的最新变化时使用

02 资源文件 4

03 SKILL.md 正文

cn-sync

当前项目是 https://github.com/mattpocock/skills 的中文镜像。本 skill 只同步上次成功位置之后的上游变化,不凭时间、文件内容或本地提交历史猜测增量范围。

固定资源

  • 英文源仓库:当前项目的兄弟目录 skills 或 mattpocock-skills
  • 翻译 Prompt:.agents/skills/cn-sync/resource/任意文档式项目工程所有英文文档翻译中文的Prompt.md
  • 同步状态:.agents/skills/cn-sync/last/state.json
  • 最近报告:.agents/skills/cn-sync/last/report.md

last/ 是本 skill 的内部状态目录,不属于翻译范围。状态文件只能由主代理写入,不能交给翻译子代理并发修改。

一次成功运行必须创建一个本地 Git 提交。此授权仅覆盖本轮 cn-sync 产生的翻译与状态变更,不包含 push、tag、发布、amend 或其他仓库改动。

状态规则

last/state.json 是确定增量起点的唯一事实源:

  • last_success.source_commit 表示上次完整翻译并验证成功的上游提交,也是下一次同步的 base。
  • last_attempt 表示最近一次执行结果,可以是 completed、no_changes、blocked 或 failed;初始占位状态可以是 uninitialized。
  • 只有翻译、写入和验证全部成功后,才能把 last_success.source_commit 推进到本次 head。
  • 任务失败或阻断时,只更新 last_attempt,必须保留原来的 last_success。
  • 不得把英文源仓库的本地 HEAD 当成上游位置;必须使用状态中记录并经远端更新的 source_ref。

状态文件不存在、损坏、缺少 last_success.source_commit,或其中的 remote/ref 与当前英文源不一致时,禁止猜测基线。只有以下两种方式可以初始化:

  1. 用户明确提供一个已经同步完成的上游 commit;或
  2. 本轮对目标范围执行完整初始化同步并通过验证,然后把当前上游 head 写为首次成功位置。

无法完成其中任一方式时,以 blocked 结束并记录原因。

工作流

  1. 检查兄弟目录中的英文源仓库,并确认其 origin 规范化后等于 https://github.com/mattpocock/skills。不符合时结束任务并记录 blocked。
  2. 读取 last/state.json。保存已有的 last_success,并记录中文项目开始时的 Git HEAD、已暂存、未暂存和未跟踪路径;本轮任何失败都不能覆盖原成功位置。
  3. 安全更新英文源的远端引用。保留英文仓库已有改动和本地提交;不得 reset、清理或覆盖。以远端默认分支对应的 remote-tracking ref 为 source_ref,通常是 refs/remotes/origin/main。
  4. 令 base = last_success.source_commit,head = source_ref 当前提交:
    • base == head:无需翻译,记录 no_changes;
    • base 是 head 的祖先:唯一同步范围为 base..head;
    • base 不存在、不是祖先或历史发生分叉:停止并记录 blocked,不得自行改用 merge-base、时间点或某个“看起来合理”的提交。
  5. 使用 base..head 获取完整提交清单和文件变更,包括新增、修改、删除、移动;据此拆分精确目标范围。若任何预计写入、删除或重命名的中文目标文件在任务开始时已经有改动,必须在翻译前以 blocked 结束,不能把既有改动混入自动提交。last/state.json 和 last/report.md 是任务专属状态文件,不受此重叠规则限制。
  6. 开启翻译子代理。提示词必须由“固定翻译 Prompt + 本次上下文 + 精确目标范围”融合而成。子代理只处理分配范围,不得写入 last/,不同子代理不得并发修改同一文件。
  7. 主代理将译文逐范围、逐文件应用到当前中文项目,保留现有无关改动,并按翻译 Prompt 做最小必要验证。
  8. 汇总所有子代理结果。只要仍有未处理文件、翻译失败、冲突或验证失败,本轮就不能标记成功。
  9. 按“自动提交”一节更新状态并创建一个本地提交。提交成功后,才可以在最终回复中宣告同步完成并汇报 commit hash。

自动提交

completed 和 no_changes 都必须自动创建一个本地提交,不需要再次询问用户;blocked 或 failed 只更新状态文件,不创建成功提交。

提交范围只能包含:

  • 本轮实际新增、修改、删除或重命名的中文目标文件;
  • .agents/skills/cn-sync/last/state.json;
  • .agents/skills/cn-sync/last/report.md。

严格遵守以下规则:

  1. 根据任务开始快照生成精确路径清单。不得使用 git add .、git add -A、通配整个目录或任何会暂存范围外文件的命令。
  2. 提交前检查每个目标文件的差异、git diff --check、适用的文档验证结果以及最终路径清单。发现意外文件或未解决问题时停止,不得提交。
  3. 已有的范围外 staged/unstaged/untracked 改动保持原样。先精确暂存本轮路径,再使用 git commit --only ... -- <本轮路径...> 或等价的隔离索引机制创建提交,确保已有 staged 内容不会被夹带;不得还原、整理或暂存其他改动。提交后还要确认任务开始时已有的范围外 staged 集合保持不变。
  4. 提交消息使用 docs(cn-sync): sync upstream through <head短哈希>;无上游变化时使用 chore(cn-sync): record no changes at <head短哈希>。
  5. 正常运行仓库配置的提交钩子,不得使用 --no-verify。提交失败时只精确撤销本轮路径的暂存,保留翻译工作区供排查,恢复原 last_success,把 last_attempt.status 改为 failed 并记录原因;不得宣告完成。
  6. 提交成功后核对新提交的文件清单只包含允许路径,并在最终回复中报告 commit hash。不得自动 push、发布或修改刚创建的提交。

为使状态与提交保持一致,成功路径按以下顺序执行:

  1. 准备 completed 或 no_changes 的最终状态;completed 将 last_success.source_commit 设为本次 head,no_changes 保留原成功位置。
  2. 写入并校验 last/state.json 与 last/report.md。
  3. 精确暂存本轮路径,复核即将提交的差异和文件清单。
  4. 创建一个本地提交。
  5. 提交成功后报告完成;提交失败则按上面的失败规则恢复状态,不推进成功位置。

每次结束必须记录

无论结果成功、无变化、阻断还是失败,每次退出前都必须更新。若进程被强制终止而来不及记录,下次必须从旧的 last_success 重新核验,不能把中断任务视为成功。

last/state.json

保持合法 JSON,至少包含:

  • schema_version
  • source.remote 与 source.ref
  • last_success:成功的 source_commit、完成时间和同步范围;从未成功时为 null
  • last_attempt:状态、开始/结束时间、base_commit、head_commit、比较范围、上游提交数、上游变更文件数、中文修改文件、验证结果和失败原因

使用环境允许的安全编辑方式完整写入,并在写后解析校验 JSON;无效状态不能替换可信的旧状态。不要记录文档正文、密钥、代理推理或无关环境信息。

last/report.md

用简短中文覆盖写入最近一次运行摘要,至少说明:

  • 本轮状态;
  • 使用的 remote、ref、base 和 head;
  • 上游提交及变更文件范围;
  • 中文项目实际修改;
  • 已执行的检查与结果;
  • 计划使用的提交消息;
  • 阻断原因或待用户裁决事项。

completed 时必须同时满足状态文件落盘、验证通过和本地提交成功。no_changes 也必须留下本轮记录并提交状态文件,但不改变既有成功基线。

04 同仓库更多 Skills