5.8 KiB

Raw Blame History

name

version

description

metadata

gitlink-doc-sync

1.0.0

中英文档一致性守护：检测 README/文档中英文版本之间的内容漂移（章节缺失、更新滞后、示例不一致），生成漂移报告并自动提交同步修复 PR。当用户需要检查文档翻译是否同步、维护双语文档、或在发版前审计文档一致性时触发。

requires

cliHelp

bins

gitlink-cli

gitlink-cli file --help

gitlink-doc-sync（中英文档一致性守护）

CRITICAL — 开始前必须先阅读 ../gitlink-shared/SKILL.md，其中包含认证、权限处理和 API 注意事项。 CRITICAL — 所有写操作（file +update / pr +create）必须先向用户展示漂移报告并获得确认，且一律通过 --new-branch 提交到新分支走 PR 流程，禁止直接推主分支。 CRITICAL — GitLink 操作只能用 gitlink-cli。

前置条件： 先阅读 ../gitlink-shared/SKILL.md；文件读写命令详见 ../gitlink-file/SKILL.md。

功能概述

开源项目普遍维护中英双语文档（如 README.md + README.zh-CN.md），但两个版本极易漂移：英文更新了新功能，中文没跟上；中文修了错误，英文仍是旧说法。本技能提供完整的文档一致性守护流程：

文档对发现 — 自动识别仓库中的双语文档对
漂移检测 — 逐节比对两个版本的结构与内容新鲜度
漂移报告 — 生成分级报告（缺失章节 / 滞后章节 / 示例不一致）
同步修复 — 翻译补齐漂移内容，经用户确认后提交同步 PR
发版前审计 — 与 release 流程配合，在发版前做文档一致性门禁

一、文档对发现

# 列出仓库根目录，寻找双语文档对
gitlink-cli repo +tree --owner <owner> --repo <repo> --ref master --format json

# 常见文档对命名约定（按文件名搜索确认）
gitlink-cli file +search --owner <owner> --repo <repo> --keyword README
gitlink-cli file +search --owner <owner> --repo <repo> --keyword zh-CN

AI 判断逻辑：以下命名模式视为文档对（<base> 为主文档）：

主文档	翻译文档
`README.md`	`README.zh-CN.md` / `README_zh.md` / `README.zh.md`
`docs/<name>.md`	`docs/<name>.zh-CN.md` / `docs/zh/<name>.md`
`CONTRIBUTING.md`	`CONTRIBUTING.zh-CN.md`

若用户明确指定了文档对，跳过本步骤。

二、漂移检测

2.1 拉取两个版本的内容

gitlink-cli file +view --owner <owner> --repo <repo> --path README.md --raw > /tmp/doc-en.md
gitlink-cli file +view --owner <owner> --repo <repo> --path README.zh-CN.md --raw > /tmp/doc-zh.md

2.2 结构比对（AI 逐节分析）

对两个文件分别提取标题大纲（#/##/###），按语义对齐章节后检查：

缺失章节：一侧存在、另一侧完全没有对应章节（严重）
滞后章节：章节都在，但一侧的命令示例、表格行数、功能列表明显多于另一侧（中等）
示例不一致：代码块中的命令、参数、输出与另一侧不一致（中等）
链接/版本号不一致：安装版本、徽章、链接指向不同目标（轻微）

2.3 新鲜度佐证（可选，用提交历史判断谁滞后）

# 查看两个文件最近的提交时间，更新较早的一侧通常是滞后方
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

三、漂移报告

向用户输出报告（先报告，后动手）：

# 文档一致性报告：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？

四、同步修复（需用户确认）

# 1. 在本地补齐滞后内容（AI 完成翻译/同步，保持术语与既有风格一致）
#    修改后的完整文件保存为 /tmp/doc-zh-fixed.md

# 2. 提交到新分支
gitlink-cli file +update --owner <owner> --repo <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 <owner> --repo <repo> \
  --title "docs: 同步中英文 README" \
  --head docs/sync-readme-zh --base master \
  --body "由 gitlink-doc-sync 检测到文档漂移并同步，详见漂移报告。"

翻译原则：

术语不翻译（命令名、参数、API 路径、专有名词保持原样）
保持代码块逐字一致，仅翻译注释
保持表格结构、章节顺序与主文档对齐
不确定的表述在 PR 描述中标注，交由维护者复核

五、发版前文档审计（与 release 流程配合）

# 发版前对所有文档对跑一遍漂移检测，存在 🔴 严重漂移时提醒用户暂缓发版
gitlink-cli release +list --owner <owner> --repo <repo> --format json

审计输出示例：3 个文档对，1 个存在严重漂移（README ⇄ README.zh-CN），建议同步后再发版。

安全与边界

只读命令（+view / +search / +tree）可直接执行；任何写操作必须先出报告并确认。
同步修复一律 --new-branch + PR，由维护者 review 合并。
漂移判断由 AI 语义比对完成，报告中必须给出具体位置与证据，不允许笼统结论。

5.8 KiB Raw Blame History Unescape Escape