From f3c90a52d7c13ef751de7f242b2494168808d530 Mon Sep 17 00:00:00 2001 From: farmyobutu5233 Date: Sun, 5 Jul 2026 09:45:42 +0000 Subject: [PATCH] =?UTF-8?q?feat(skills):=20=E6=96=B0=E5=A2=9E=20gitlink-do?= =?UTF-8?q?c-sync=20=E4=B8=AD=E8=8B=B1=E6=96=87=E6=A1=A3=E4=B8=80=E8=87=B4?= =?UTF-8?q?=E6=80=A7=E5=AE=88=E6=8A=A4=20Skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- skills/gitlink-doc-sync/SKILL.md | 136 +++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 skills/gitlink-doc-sync/SKILL.md diff --git a/skills/gitlink-doc-sync/SKILL.md b/skills/gitlink-doc-sync/SKILL.md new file mode 100644 index 0000000..0c6fab7 --- /dev/null +++ b/skills/gitlink-doc-sync/SKILL.md @@ -0,0 +1,136 @@ +--- +name: gitlink-doc-sync +version: 1.0.0 +description: "中英文档一致性守护：检测 README/文档中英文版本之间的内容漂移（章节缺失、更新滞后、示例不一致），生成漂移报告并自动提交同步修复 PR。当用户需要检查文档翻译是否同步、维护双语文档、或在发版前审计文档一致性时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + cliHelp: "gitlink-cli file --help" +--- + +# gitlink-doc-sync（中英文档一致性守护） + +**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。** +**CRITICAL — 所有写操作（`file +update` / `pr +create`）必须先向用户展示漂移报告并获得确认，且一律通过 `--new-branch` 提交到新分支走 PR 流程，禁止直接推主分支。** +**CRITICAL — GitLink 操作只能用 `gitlink-cli`。** + +> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)；文件读写命令详见 [`../gitlink-file/SKILL.md`](../gitlink-file/SKILL.md)。 + +--- + +## 功能概述 + +开源项目普遍维护中英双语文档（如 `README.md` + `README.zh-CN.md`），但两个版本极易漂移：英文更新了新功能，中文没跟上；中文修了错误，英文仍是旧说法。本技能提供完整的文档一致性守护流程： + +1. **文档对发现** — 自动识别仓库中的双语文档对 +2. **漂移检测** — 逐节比对两个版本的结构与内容新鲜度 +3. **漂移报告** — 生成分级报告（缺失章节 / 滞后章节 / 示例不一致） +4. **同步修复** — 翻译补齐漂移内容，经用户确认后提交同步 PR +5. **发版前审计** — 与 `release` 流程配合，在发版前做文档一致性门禁 + +--- + +## 一、文档对发现 + +```bash +# 列出仓库根目录，寻找双语文档对 +gitlink-cli repo +tree --owner --repo --ref master --format json + +# 常见文档对命名约定（按文件名搜索确认） +gitlink-cli file +search --owner --repo --keyword README +gitlink-cli file +search --owner --repo --keyword zh-CN +``` + +**AI 判断逻辑**：以下命名模式视为文档对（`` 为主文档）： + +| 主文档 | 翻译文档 | +|--------|----------| +| `README.md` | `README.zh-CN.md` / `README_zh.md` / `README.zh.md` | +| `docs/.md` | `docs/.zh-CN.md` / `docs/zh/.md` | +| `CONTRIBUTING.md` | `CONTRIBUTING.zh-CN.md` | + +若用户明确指定了文档对，跳过本步骤。 + +## 二、漂移检测 + +### 2.1 拉取两个版本的内容 + +```bash +gitlink-cli file +view --owner --repo --path README.md --raw > /tmp/doc-en.md +gitlink-cli file +view --owner --repo --path README.zh-CN.md --raw > /tmp/doc-zh.md +``` + +### 2.2 结构比对（AI 逐节分析） + +对两个文件分别提取标题大纲（`#`/`##`/`###`），按语义对齐章节后检查： + +- **缺失章节**：一侧存在、另一侧完全没有对应章节（严重） +- **滞后章节**：章节都在，但一侧的命令示例、表格行数、功能列表明显多于另一侧（中等） +- **示例不一致**：代码块中的命令、参数、输出与另一侧不一致（中等） +- **链接/版本号不一致**：安装版本、徽章、链接指向不同目标（轻微） + +### 2.3 新鲜度佐证（可选，用提交历史判断谁滞后） + +```bash +# 查看两个文件最近的提交时间，更新较早的一侧通常是滞后方 +gitlink-cli api GET "/:owner/:repo/commits?filepath=README.md&limit=1" --format json +gitlink-cli api GET "/:owner/:repo/commits?filepath=README.zh-CN.md&limit=1" --format json +``` + +## 三、漂移报告 + +向用户输出报告（先报告，后动手）： + +```markdown +# 文档一致性报告：README.md ⇄ README.zh-CN.md + +| 等级 | 类型 | 位置 | 说明 | +|------|------|------|------| +| 🔴 严重 | 缺失章节 | ## File Operations | 中文版缺少「文件操作」整节 | +| 🟡 中等 | 滞后章节 | ## Features 表格 | 英文 19 行 / 中文 18 行，缺 File 一行 | +| 🟢 轻微 | 版本号 | 安装说明 | 英文 Go 1.26+ / 中文 Go 1.25+ | + +建议：同步 2 处到 README.zh-CN.md，1 处到 README.md。是否创建同步 PR？ +``` + +## 四、同步修复（需用户确认） + +```bash +# 1. 在本地补齐滞后内容（AI 完成翻译/同步，保持术语与既有风格一致） +# 修改后的完整文件保存为 /tmp/doc-zh-fixed.md + +# 2. 提交到新分支 +gitlink-cli file +update --owner --repo --path README.zh-CN.md \ + --content-file /tmp/doc-zh-fixed.md -b master --new-branch docs/sync-readme-zh \ + -m "docs: 同步 README.zh-CN 与英文版" + +# 3. 创建 PR +gitlink-cli pr +create --owner --repo \ + --title "docs: 同步中英文 README" \ + --head docs/sync-readme-zh --base master \ + --body "由 gitlink-doc-sync 检测到文档漂移并同步，详见漂移报告。" +``` + +**翻译原则**： + +- 术语不翻译（命令名、参数、API 路径、专有名词保持原样） +- 保持代码块逐字一致，仅翻译注释 +- 保持表格结构、章节顺序与主文档对齐 +- 不确定的表述在 PR 描述中标注，交由维护者复核 + +## 五、发版前文档审计（与 release 流程配合） + +```bash +# 发版前对所有文档对跑一遍漂移检测，存在 🔴 严重漂移时提醒用户暂缓发版 +gitlink-cli release +list --owner --repo --format json +``` + +审计输出示例：`3 个文档对，1 个存在严重漂移（README ⇄ README.zh-CN），建议同步后再发版。` + +--- + +## 安全与边界 + +- 只读命令（`+view` / `+search` / `+tree`）可直接执行；任何写操作必须先出报告并确认。 +- 同步修复一律 `--new-branch` + PR，由维护者 review 合并。 +- 漂移判断由 AI 语义比对完成，报告中必须给出具体位置与证据，不允许笼统结论。 -- 2.34.1