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
- 参考文档agents/openai.yaml245 B
- 参考文档last/report.md3.1 KB
- 参考文档last/state.json6.8 KB
- 参考文档resource/任意文档式项目工程所有英文文档翻译中文的Prompt.md4.0 KB
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 与当前英文源不一致时,禁止猜测基线。只有以下两种方式可以初始化:
- 用户明确提供一个已经同步完成的上游 commit;或
- 本轮对目标范围执行完整初始化同步并通过验证,然后把当前上游
head写为首次成功位置。
无法完成其中任一方式时,以 blocked 结束并记录原因。
工作流
- 检查兄弟目录中的英文源仓库,并确认其
origin规范化后等于https://github.com/mattpocock/skills。不符合时结束任务并记录blocked。 - 读取
last/state.json。保存已有的last_success,并记录中文项目开始时的 Git HEAD、已暂存、未暂存和未跟踪路径;本轮任何失败都不能覆盖原成功位置。 - 安全更新英文源的远端引用。保留英文仓库已有改动和本地提交;不得 reset、清理或覆盖。以远端默认分支对应的 remote-tracking ref 为
source_ref,通常是refs/remotes/origin/main。 - 令
base = last_success.source_commit,head = source_ref当前提交:base == head:无需翻译,记录no_changes;base是head的祖先:唯一同步范围为base..head;base不存在、不是祖先或历史发生分叉:停止并记录blocked,不得自行改用 merge-base、时间点或某个“看起来合理”的提交。
- 使用
base..head获取完整提交清单和文件变更,包括新增、修改、删除、移动;据此拆分精确目标范围。若任何预计写入、删除或重命名的中文目标文件在任务开始时已经有改动,必须在翻译前以blocked结束,不能把既有改动混入自动提交。last/state.json和last/report.md是任务专属状态文件,不受此重叠规则限制。 - 开启翻译子代理。提示词必须由“固定翻译 Prompt + 本次上下文 + 精确目标范围”融合而成。子代理只处理分配范围,不得写入
last/,不同子代理不得并发修改同一文件。 - 主代理将译文逐范围、逐文件应用到当前中文项目,保留现有无关改动,并按翻译 Prompt 做最小必要验证。
- 汇总所有子代理结果。只要仍有未处理文件、翻译失败、冲突或验证失败,本轮就不能标记成功。
- 按“自动提交”一节更新状态并创建一个本地提交。提交成功后,才可以在最终回复中宣告同步完成并汇报 commit hash。
自动提交
completed 和 no_changes 都必须自动创建一个本地提交,不需要再次询问用户;blocked 或 failed 只更新状态文件,不创建成功提交。
提交范围只能包含:
- 本轮实际新增、修改、删除或重命名的中文目标文件;
.agents/skills/cn-sync/last/state.json;.agents/skills/cn-sync/last/report.md。
严格遵守以下规则:
- 根据任务开始快照生成精确路径清单。不得使用
git add .、git add -A、通配整个目录或任何会暂存范围外文件的命令。 - 提交前检查每个目标文件的差异、
git diff --check、适用的文档验证结果以及最终路径清单。发现意外文件或未解决问题时停止,不得提交。 - 已有的范围外 staged/unstaged/untracked 改动保持原样。先精确暂存本轮路径,再使用
git commit --only ... -- <本轮路径...>或等价的隔离索引机制创建提交,确保已有 staged 内容不会被夹带;不得还原、整理或暂存其他改动。提交后还要确认任务开始时已有的范围外 staged 集合保持不变。 - 提交消息使用
docs(cn-sync): sync upstream through <head短哈希>;无上游变化时使用chore(cn-sync): record no changes at <head短哈希>。 - 正常运行仓库配置的提交钩子,不得使用
--no-verify。提交失败时只精确撤销本轮路径的暂存,保留翻译工作区供排查,恢复原last_success,把last_attempt.status改为failed并记录原因;不得宣告完成。 - 提交成功后核对新提交的文件清单只包含允许路径,并在最终回复中报告 commit hash。不得自动 push、发布或修改刚创建的提交。
为使状态与提交保持一致,成功路径按以下顺序执行:
- 准备
completed或no_changes的最终状态;completed将last_success.source_commit设为本次head,no_changes保留原成功位置。 - 写入并校验
last/state.json与last/report.md。 - 精确暂存本轮路径,复核即将提交的差异和文件清单。
- 创建一个本地提交。
- 提交成功后报告完成;提交失败则按上面的失败规则恢复状态,不推进成功位置。
每次结束必须记录
无论结果成功、无变化、阻断还是失败,每次退出前都必须更新。若进程被强制终止而来不及记录,下次必须从旧的 last_success 重新核验,不能把中断任务视为成功。
last/state.json
保持合法 JSON,至少包含:
schema_versionsource.remote与source.reflast_success:成功的source_commit、完成时间和同步范围;从未成功时为nulllast_attempt:状态、开始/结束时间、base_commit、head_commit、比较范围、上游提交数、上游变更文件数、中文修改文件、验证结果和失败原因
使用环境允许的安全编辑方式完整写入,并在写后解析校验 JSON;无效状态不能替换可信的旧状态。不要记录文档正文、密钥、代理推理或无关环境信息。
last/report.md
用简短中文覆盖写入最近一次运行摘要,至少说明:
- 本轮状态;
- 使用的 remote、ref、base 和 head;
- 上游提交及变更文件范围;
- 中文项目实际修改;
- 已执行的检查与结果;
- 计划使用的提交消息;
- 阻断原因或待用户裁决事项。
completed 时必须同时满足状态文件落盘、验证通过和本地提交成功。no_changes 也必须留下本轮记录并提交状态文件,但不改变既有成功基线。
04 同仓库更多 Skills
writing-great-skills
出色编写和编辑技能的参考资料——让技能具备可预测性的词汇与原则。
teach
在此工作区内向用户教授新的技能或概念。
handoff
将当前对话压缩成交接文档,以便另一个智能体接手。
grilling
围绕计划、决策或想法对用户进行不留情面的深度追问。当用户想对自己的思路进行压力测试,或使用任何“深度追问”触发措辞时使用。
grill-me
通过不留情面的深度追问打磨计划或设计。
obsidian-vault
使用 wikilink 和索引笔记搜索、创建和管理 Obsidian 仓库中的笔记。当用户想要在 Obsidian 中查找、创建或整理笔记时使用。