# 中英文档一致性守护工作流（doc-sync-automation）

把 [`gitlink-doc-sync` Skill](../../../skills/gitlink-doc-sync/SKILL.md)（中英文档一致性守护）包成**可直接运行的端到端工作流**：

> **采集 → 检测 → 报告 → 回写**：用 `repo +tree` 按命名约定自动发现双语文档对，用 `file +view --raw` 拉取两版内容，做**确定性结构比对**（章节大纲 / 代码块 / 表格行数 / 版本号），输出分级（🔴严重 / 🟡中等 / 🟢轻微）漂移报告，并（仅在 `--apply` 时）用 `issue +create` 把报告作为 tracking issue 真实回写到 GitLink。

与仓库内已有能力的关系：`file` 命令组（文件读写）→ `gitlink-doc-sync` Skill（AI 语义比对与翻译同步知识）→ **本工作流（确定性可复现闭环）**，三层互为支撑而非重复：Skill 负责需要语义理解的翻译同步，本工作流负责可进 CI 的确定性漂移检测。

## 架构图

```mermaid
flowchart LR
    A["repo +tree<br/>仓库结构采集"] --> B["文档对自动发现<br/>README.md ⇄ README.zh-CN.md<br/>docs/*.md ⇄ docs/*.zh-CN.md"]
    B --> C["file +view --raw ×2<br/>拉取双语版本内容"]
    C --> D["确定性结构比对<br/>章节大纲 / 代码块 / 表格 / 版本号"]
    D --> E["分级漂移报告<br/>🔴严重 / 🟡中等 / 🟢轻微"]
    E -->|"dry-run（默认）"| F["Markdown 报告落盘<br/>退出码 0/2 → CI 门禁"]
    E -->|"--apply"| G["issue +create<br/>回写 tracking issue"]
    G -.->|"人工确认后"| H["gitlink-doc-sync Skill<br/>AI 语义翻译同步 → file +update → pr +create"]
```

## CI 门禁集成示例

利用退出码语义（`0` 无严重漂移 / `2` 存在严重漂移）可直接作为发布门禁。GitLink 引擎（`.gitea/workflows`）示例：

```yaml
name: doc-sync-gate
on:
  pull_request:
    paths: ["README.md", "README.zh-CN.md", "docs/**"]
jobs:
  doc-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @gitlink-ai/cli
      - env:
          GITLINK_TOKEN: ${{ secrets.GITLINK_TOKEN }}
        run: |
          python3 examples/workflows/doc-sync-automation/scripts/doc_sync_workflow.py \
            --owner ${{ github.repository_owner }} --repo ${{ github.event.repository.name }}
```

## 交付物

- `scripts/doc_sync_workflow.py`：文档对发现 + 漂移检测 + 报告 + tracking issue 回写（纯标准库，Python ≥3.9，零第三方依赖）
- `tests/test_drift.py`：确定性回归护栏（同输入 → 同发现 → 同退出语义）
- `docs/verification.md`：真实平台验证证据
- `examples/demo-outputs/`：对生产环境真实仓库运行的漂移报告

## 快速运行（默认 dry-run，不写远端）

```bash
npm install -g @gitlink-ai/cli
gitlink-cli auth login

python3 scripts/doc_sync_workflow.py --owner <owner> --repo <repo> --output-dir outputs
```

- 自动发现失败时手动指定文档对：`--pair README.md:README.zh-CN.md`（可多次）
- 指定分支：`--ref develop`
- 真实回写 tracking issue：加 `--apply`（请先在自有仓库演练）
- 退出码：`0` 无严重漂移，`2` 存在严重漂移（可直接作为 CI 门禁）

## 已在真实平台验证

全部证据见 [`docs/verification.md`](docs/verification.md)，要点：

| 验证 | 对象 | 结果 |
|------|------|------|
| 文档对自动发现 | 生产 gitlink.org.cn 真实仓库 | ✅ 自动识别 README.md ⇄ README.zh-CN.md |
| 漂移检测 | 本仓库 README 双语版本 | ✅ 检出真实漂移：代码块 32 vs 29、表格 43 vs 40 行 |
| `--apply` 真实回写 | 自有 fork | ✅ tracking issue 创建成功（issue #1，API 回执确认） |
| 单测 | `tests/test_drift.py` | ✅ 11/11 全绿 |

## 设计要点

- **确定性**：漂移检测只做结构比对（标题大纲、代码块数/行数、表格行数、版本号），同输入必同输出，可进 CI；需要语义理解的翻译同步交给 `gitlink-doc-sync` Skill。
- **围栏内解析**：代码块内的 `#` 不会被误判为标题；表格分隔行不计入行数。
- **安全默认**：dry-run 为默认行为，`--apply` 才写远端，且只创建 tracking issue（可追溯、可关闭），不直接改文档。
- **CLI 为唯一依赖**：所有平台交互都通过 `gitlink-cli`（`repo +tree` / `file +view` / `issue +create`），无直接 HTTP 调用。

> 依赖 `file` 快捷命令组（PR #330）；在其合并前可用 `--cli` 指向包含该命令的本地构建。
