桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载导读EcoPaste 在仓库根目录同时维护 CHANGELOG.md英文与 CHANGELOG.zh-CN.md中文两份发布日志。本文围绕.agents/skills/sync-zh-changelog/SKILL.md这份 AI 技能文档完整讲解如何将一个发布版本从英文 changelog 同步到中文 changelog包括七步标准工作流、术语一致性约定、标题翻译映射表以及配套校验脚本check_sync.py的结构对比原理。读完本文你将掌握一套先同步、后校验、全自动可复验的双语文档维护方法并能独立为任意发布版本执行同步与验证。Skill 定位为双语文档一致性而生.agents/skills/sync-zh-changelog/SKILL.md定义了一个名为sync-zh-changelog的 Agent 技能Skill其description字段明确了职责边界Synchronize an EcoPaste release section fromCHANGELOG.mdintoCHANGELOG.zh-CN.mdwith project terminology and structural validation.即从英文 changelog 中取出一个发布段落同步进中文 changelog并附带项目术语project terminology与结构structural validation双重校验。它同时约定了两条使用前提只同步一个发布段落不改变发布元数据release metadata不触碰无关文件技能名称前缀$表示它属于可被显式调用的命令式技能也可由自然语言意图隐式触发。该技能的完整定义位于 .agents/skills/sync-zh-changelog/SKILL.md配套的校验脚本位于 .agents/skills/sync-zh-changelog/scripts/check_sync.py还有一份面向 OpenAI 风格 Agent 的接口描述 .agents/skills/sync-zh-changelog/agents/openai.yaml。触发方式与 Trellis 路由规则该 Skill 与项目的 Trellis 任务管理机制联动SKILL.md 的 Trellis routing 一节给出了两条明确的触发规则显式调用$sync-zh-changelog视为用户已作出跳过 Trellis 任务创建的既定选择因为这是一次窄范围的文档变更不要再询问也不要创建、激活或归档任何 Trellis 任务从自然语言意图隐式选中例如用户说把最新版本的中文更新日志同步一下则走正常的 Trellis 任务创建流程。无论哪种方式都必须继续遵守 AGENTS.md 中约定的工作树约束dirty worktree 处理与发布规范release specs。此外.agents/skills/sync-zh-changelog/agents/openai.yaml 提供了该技能面向 Agent 工具的默认提示词使用$sync-zh-changelog同步最新版本的中文更新日志可作为最小触发样例。七步同步工作流详解SKILL.md 将整个同步过程规范化为 7 个步骤每步都有明确的操作对象与边界约束。第 1 步读取双份 changelog确定目标版本编辑前必须先完整读取两份文件CHANGELOG.md与CHANGELOG.zh-CN.md。目标版本由用户指定若用户未指定则默认选取CHANGELOG.md中第一个发布段落即最新版本。以当前仓库为例最新版本为1.1.0其英文段落位于 CHANGELOG.md。第 2 步定位插入位置禁止产生重复段落判断目标版本是否已存在于 CHANGELOG.zh-CN.md已存在→ 在原位置就地更新update in place不存在→ 插入到# 更新日志一级标题之后、紧跟其后的位置。无论哪种情况严禁创建重复段落Never create a duplicate section。这保证了中文 changelog 与英文 changelog 一样按时间倒序、版本唯一排列。第 3 步翻译发布正文与标题将发布正文release prose与各级标题翻译为简洁的简体中文。当产品术语不明确时用rg在以下三处检索既有译法src/locales/zh-CN/中文 UI 文案src/locales/en-US/英文 UI 文案中文 changelog 中已有的历史条目也就是说产品术语的翻译以界面文案已有译法为唯一事实来源避免同一种概念在 UI 与 changelog 中译名不一致。例如备份导入导出敏感内容保护等说法应当与中文 UI 的既有措辞保持完全一致。第 4 步只翻译人话原样保留全部元数据这是本技能最关键的约束。以下信息在翻译中必须逐字保留必须保留的元数据说明版本号version如1.1.0体现在发布标题中对比链接compare URL如https://github.com/EcoPasteHub/EcoPaste/compare/v1.0.0...v1.1.0发布日期date如2026-07-22小节顺序section orderFeatures / Bug Fixes / ...的顺序不变条目顺序entry order每个小节内条目的先后顺序不变Issue 编号issue numbers如#1353提交哈希commit hashes如746cc05全部链接目标link targets无论 issue 链接还是 commit 链接真正需要翻译的只有人话human-readable prose。同时平台与产品专有名词EcoPaste、macOS、Windows、Token、AWS Key、JWT 等必须与 UI 文案保持一致不擅自翻译。第 5 步只改一个文件不提交不推送可修改的文件仅限CHANGELOG.zh-CN.md。以下内容一律不动CHANGELOG.md英文源文件版本文件、发布配置release configuration任何无关的 dirty changes工作树中已有的未提交改动并且明确不执行 commit、不执行 push——同步动作结束于文件修改与验证提交决策留给后续流程。第 6 步从仓库根目录执行两项验证python3 .agents/skills/sync-zh-changelog/scripts/check_sync.py git diff --check -- CHANGELOG.zh-CN.md第一条命令运行结构校验脚本比对中英文发布段落的结构与链接是否对齐原理见下文第二条命令用 Git 自带的空白检查whitespace errors如行尾空格、space-before-tab校验中文文件没有引入格式污染。当用户指定了非最新版本时需要给校验脚本加参数python3 .agents/skills/sync-zh-changelog/scripts/check_sync.py --version version第 7 步修复所有错误并汇报结果逐条修复脚本输出的每一项 error重新运行第 6 步的两条命令直到全部通过最后向用户报告已同步的版本号、校验结果。翻译标题映射表SKILL.md 给出了一份既定标题映射表established mappings遇到下列源标题时必须使用对应中文英文标题源中文标题目标✨ Features✨ 新功能 Bug Fixes 问题修复⚡️ Performance⚡️ 性能优化⏪ Reverts⏪ 回退⚠️ Upgrade Notice⚠️ 升级说明对于表中未出现的陌生标题则忠实翻译并保留其 emoji 与所在位置translate it faithfully while preserving any emoji and its position。这两条规则同时被校验脚本固化check_sync.py中的HEADING_TRANSLATIONS字典与这张表一一对应见 check_sync.py凡是出现在映射表中的源标题如果中文侧标题与预期值不一致脚本会直接报错。校验脚本check_sync.py的实现原理要让结构校验可自动化、可复验仓库配套了 Python 脚本check_sync.py依赖仅 Python 3 标准库无需第三方包。它的核心设计是把人工翻译是否忠实转化为一系列可机械比对的结构化断言。发布段落与小节的数据建模脚本用两个不可变数据类dataclass(frozenTrue)抽象文档结构Releasecheck_sync.py记录version、url、date和body发布标题之下的全部原文行Sectioncheck_sync.py记录一个小节标题及其内容行。解析器parse_releasesL47-L75通过正则RELEASE_HEADING识别形如## 1.1.0 (2026-07-22)的发布标题并按行累积正文parse_sectionsL99-L123再把每个发布段落切分为标题前的导语preamble和若干###小节。整体正则约束如下L13-L18RELEASE_HEADING^## \版本 (日期)$严格要求版本、链接、日期三者同在一行SECTION_HEADING^### 标题$LIST_ITEM^(?:[-*] |\d\. )识别无序/有序列表条目MARKDOWN_LINK\[([^]])]\(([^)])\)提取行内 Markdown 链接的文本与目标。内容单元content unit比对链接与类型的顺序约束脚本的精妙之处在于content_unitsL126-L153它把一段内容按空行和列表行切分成一个个内容单元每个单元记录两个维度的信息内容类型content kindparagraph段落还是list列表条目该单元内全部 Markdown 链接的(显示文本, 目标地址)元组序列。随后compare_unitsL156-L182对中英文两侧逐单元比对只要出现以下任一情况就产生 error单元数量不一致如英文 2 段 8 条列表中文变成 3 段 7 条对应位置的内容类型不一致如把列表改成了段落对应单元的 Markdown 链接序列不一致文本或目标地址有任何出入。这套机制的含义是链接不能增减、不能换位、不能改写目标——即使中文翻译把句子顺序调整到合法范围内链接与列表的结构形态也必须与英文完全同构。元数据与标题的强制校验validate函数L185-L223)按优先级执行断言链比对compare URL与发布日期是否完全一致比对发布导语preamble的内容单元比对小节数量逐小节先查HEADING_TRANSLATIONS映射校验标题译名再比对小节内容的单元结构。mainL244-L270统一组织流程默认以英文 changelog 的第一个版本为校验对象当未指定--version时还会额外检查中文 changelog 的第一个段落是否就是这个最新版本防止新版本插到了旧位置。所有错误通过error: version: detail格式输出到 stderr最终退出码 0 表示同步成功1 表示存在差异。从脚本结构可以推断它还隐含约束了同一版本在各自文件中只能出现一次find_release对重复版本直接报错见 L88-L96这正是第 2 步禁止重复段落的机器化保障。实操示例以 1.1.0 版本演练完整同步以当前仓库为例英文侧最新发布段落为1.1.0CHANGELOG.md其结构为## [1.1.0](https://github.com/EcoPasteHub/EcoPaste/compare/v1.0.0...v1.1.0) (2026-07-22) ### ✨ Features * add image save context menu (#1353) (746cc05) * add nightly update channel support (#1350) (9544725) ### Bug Fixes * correct timezone offset for legacy data import (#1338) (d6ea9ed) ...为便于阅读此处链接目标以省略号占位实际文件中为完整地址。中文侧对应段落已存在见 CHANGELOG.zh-CN.md标题被翻译为✨ 新功能与 问题修复条目按相同顺序、相同 issue 编号与 commit 哈希排列——这就是第 4 步只翻译人话的直接产物。若中文侧缺失该版本则执行第 2 步将其插入# 更新日志之后若两侧结构存在差异则运行校验脚本即可得到具体到小节与条目的报错定位python3 .agents/skills/sync-zh-changelog/scripts/check_sync.py # 输出示例CHANGELOG.zh-CN.md is synchronized for 1.1.0. python3 .agents/skills/sync-zh-changelog/scripts/check_sync.py --version 1.0.0 # 校验非最新版本CHANGELOG.zh-CN.md is synchronized for 1.0.0.注意--version的值必须与发布标题中的版本号完全一致如1.1.0而非v1.1.0这是由RELEASE_HEADING正则捕获组决定的。与仓库其他约定及工具的配合这套同步技能并非孤立存在它与项目的质量体系形成了闭环术语来源统一中文 UI 文案src/locales/zh-CN/与英文 UI 文案src/locales/en-US/是术语检索的既定目录。例如中文文案中的清空记录更改数据目录检测旧版数据等操作标签直接为 changelog 中同义描述提供译法参考见 src/locales/zh-CN/commands.json。这一做法与 AGENTS.md 中i18n 文案必须同步补齐zh-CN和en-US的约定相互呼应。Git 层面的格式防线git diff --check -- CHANGELOG.zh-CN.md补充了脚本未覆盖的空白字符检查项目通过 simple-git-hooks.json 挂载pre-commit并由 lint-staged.config.ts 在提交前对前端文件执行 Biome、对 Rust 文件执行cargo fmt与cargo clippy虽然 changelog 的.md文件不在 lint-staged 的 glob 内但脚本 git diff --check恰好补上了这一环。提交信息规范若后续需要提交同步结果AGENTS.md 要求使用单行 Conventional Commits如docs:前缀且遵循改 UI 后必须实际操作验证主路径与边界的验证精神——changelog 同步的实际操作验证正是第 6 步的两条校验命令。边界情况与常见问题从源码结构看基于 SKILL.md 与check_sync.py的实现可以推断出以下边界约束实际执行时值得注意版本重复同一版本若在CHANGELOG.zh-CN.md中出现两次脚本会因release appears N times直接拒绝与不创建重复段落的步骤 2 形成双重保障版本缺失find_release对缺失版本报 release is missing提示你需要先补上对应段落再验证导语也要对齐英文发布段落若在第一个###标题前有导语段落如 1.0.0 的 This is a fully refactored version...中文侧也必须有同样数量、同样链接结构的对应导语脚本会以release preamble为单位进行比对链接比文字更严格文本内容只要求单元结构同构段落对段落、列表对列表但链接的显示文本与目标必须逐字相等因此翻译时即使改动链接文字例如把 commit 哈希包上代码样式也会被检出。简而言之这套技能把翻译一份 changelog从纯人工劳动变成了人工翻译 机器验证的可重复流程人工负责语义与术语的准确check_sync.py负责结构与链接的忠实最终保证 EcoPaste 的英文与中文更新日志在任意版本上都能维持严格的对称性。赞分享桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载相关推荐Easydict 发布日志双分支同步实战sync-notes 如何原子更新 main/dev 与本地 GitEasydict 发布日志双分支同步实战 sync notes 如何原子更新 main/dev 与本地 Git 导读 发布一个 macOS App 之后人工桌面应用AI 应用OpenShell 文档同步实战update-docs-from-commits Agent 技能的七步工作流OpenShell 文档同步实战update docs from commits Agent 技能的七步工作流 OpenShell 仓库内贡献者文档存放在 dEasydict 发布流水线实战sync-notes 发布后日志同步机制的演进与原理Easydict 发布流水线实战 sync notes 发布后日志同步机制的演进与原理 发布完一个版本之后如果发现 changelog/version .桌面应用AI 应用上一篇零代码到企业级Druid UI与PostgreSQL无缝集成指南下一篇Get Shit Done突破性上下文工程如何终结AI编码质量衰退创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考