From e595109df094fd64315839111167696eb0968dcb Mon Sep 17 00:00:00 2001 From: xiexin12138 Date: Mon, 31 Aug 2026 11:58:40 +0800 Subject: [PATCH] =?UTF-8?q?[AI]=20fix:=20=E5=85=81=E8=AE=B8=E5=90=8C?= =?UTF-8?q?=E6=AD=A5=20Action=20=E5=AE=A1=E6=A0=B8=E5=A4=A7=E8=A7=84?= =?UTF-8?q?=E6=A8=A1=E5=88=A0=E9=99=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/sync-docs.yml | 2 +- README.md | 2 +- scripts/README.md | 4 ++-- scripts/sync-pr-summary.ts | 2 +- scripts/tests/sync-pr-summary.test.ts | 11 +++++++++++ 5 files changed, 16 insertions(+), 5 deletions(-) diff --git a/.github/workflows/sync-docs.yml b/.github/workflows/sync-docs.yml index 3a3ab30..d74baa9 100644 --- a/.github/workflows/sync-docs.yml +++ b/.github/workflows/sync-docs.yml @@ -54,7 +54,7 @@ jobs: pnpm test - name: Synchronize official Markdown - run: pnpm docs:sync --prune + run: pnpm docs:sync --prune --allow-large-prune - name: Publish the automation branch id: publish diff --git a/README.md b/README.md index 918b5f6..3e3a38b 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ pnpm translate:simulate -- --match guides/agents/quickstart.md --limit 1 - `docs:check`：联网检查官方内容或本地镜像是否变化，不写文件；有变化时退出码为 `1`。 - `docs:sync`：以低并发和全局限速联网同步 Markdown；本轮全部下载成功后才更新文件和 `docs/en/.source-manifest.json`。 -完整同步会拒绝空索引和异常大幅删除。超过自动安全阈值的 prune 必须由维护者使用 `--allow-large-prune` 明确确认；定时任务不会自动绕过这道保护。 +完整同步会拒绝空索引和异常大幅删除。命令行同步超过自动安全阈值时，必须由维护者使用 `--allow-large-prune` 明确确认。定时同步只会把变更写入待审核的自动 PR，不会直接写入 `main`，因此会显式启用该参数；大规模删除仍须由维护者在 PR 中审核后合并。 维护细节和筛选参数见 [`scripts/README.md`](scripts/README.md)，文档目录说明见 [`docs/README.md`](docs/README.md)。 diff --git a/scripts/README.md b/scripts/README.md index f22e05b..0cf9963 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -51,7 +51,7 @@ node scripts/sync-docs.ts sync --prune --allow-large-prune 使用 `--match` 或 `--limit` 的部分扫描不会判断页面是否已被官方移除，避免把未扫描页面误判为删除。 -完整扫描会先验证索引：某个栏目没有解析出 Markdown 页面时立即中止；相较 manifest 的有效记录，单个栏目拟移除超过 20 页或 10% 时也会中止。确认这是官方的真实大规模调整后，维护者才能通过 `--allow-large-prune` 明确放行。删除路径始终从经过验证的官方 URL 重新计算，并严格限制在 `sourceRoot` 内，manifest 中保存的历史 `localPath` 不具有删除权限。 +完整扫描会先验证索引：某个栏目没有解析出 Markdown 页面时立即中止；相较 manifest 的有效记录，单个栏目拟移除超过 20 页或 10% 时也会中止。确认这是官方的真实大规模调整后，本地同步可由维护者通过 `--allow-large-prune` 明确放行；定时任务使用该参数时只会生成待审核 PR。删除路径始终从经过验证的官方 URL 重新计算，并严格限制在 `sourceRoot` 内，manifest 中保存的历史 `localPath` 不具有删除权限。 ## 网络策略 @@ -96,7 +96,7 @@ node scripts/sync-docs.ts sync --prune --allow-large-prune ## 定时任务 -`.github/workflows/sync-docs.yml` 每天北京时间 00:00（UTC 16:00）从受信任的 `main` 重建固定分支 `automation/sync-openai-docs`，运行完整同步和 `--prune`，并只提交 `docs/en/` 的真实变化。专用分支使用 `--force-with-lease` 安全更新，工作流不会执行分支自身修改过的脚本。随后创建或更新面向 `main` 的中文 PR；`scripts/sync-pr-summary.ts` 根据实际 Git 差异区分新增、修改和删除，并在 PR 中列出对应文件路径。维护者批准自动 PR 的工作流运行后，PR 必须通过标准 `pull_request` 触发的 `Quality gate`；工作流不会直接 push `main`。官方内容重新与 `main` 一致时，失效的同步 PR 会被关闭。Job 最长运行 45 分钟，避免上游持续故障或异常 `Retry-After` 无限占用执行器。 +`.github/workflows/sync-docs.yml` 每天北京时间 00:00（UTC 16:00）从受信任的 `main` 重建固定分支 `automation/sync-openai-docs`，运行完整同步和 `--prune --allow-large-prune`，并只提交 `docs/en/` 的真实变化。定时任务允许把超过命令行安全阈值的大规模删除写入待审核 PR，但不会直接写入 `main`。专用分支使用 `--force-with-lease` 安全更新，工作流不会执行分支自身修改过的脚本。随后创建或更新面向 `main` 的中文 PR；`scripts/sync-pr-summary.ts` 根据实际 Git 差异区分新增、修改和删除，在 PR 中列出对应文件路径，并提醒维护者审核删除清单。维护者批准自动 PR 的工作流运行后，PR 必须通过标准 `pull_request` 触发的 `Quality gate`；工作流不会直接 push `main`。官方内容重新与 `main` 一致时，失效的同步 PR 会被关闭。Job 最长运行 45 分钟，避免上游持续故障或异常 `Retry-After` 无限占用执行器。 首次启用前，需要在仓库 **Settings → Actions → General → Workflow permissions** 勾选 **Allow GitHub Actions to create and approve pull requests**。随后可对 `main` 设置必须通过 PR 和 `Quality gate` 的 Ruleset，无需给同步机器人配置 bypass。 diff --git a/scripts/sync-pr-summary.ts b/scripts/sync-pr-summary.ts index b9c3c2d..4a3e08c 100644 --- a/scripts/sync-pr-summary.ts +++ b/scripts/sync-pr-summary.ts @@ -113,7 +113,7 @@ export function renderSyncPullRequestBody(summary: SyncDiffSummary): string { "## 合入要求", "", "- 同步器已在写入前校验官方索引和页面响应。", - "- 自动任务不会绕过异常大规模删除保护。", + "- 自动任务会显式允许超过命令行安全阈值的大规模删除；合入前必须审核“删除文件”清单。", "- 仅在 `Quality gate` 通过后合入。", "", ].join("\n"); diff --git a/scripts/tests/sync-pr-summary.test.ts b/scripts/tests/sync-pr-summary.test.ts index fdd2ffe..3cb93e5 100644 --- a/scripts/tests/sync-pr-summary.test.ts +++ b/scripts/tests/sync-pr-summary.test.ts @@ -55,6 +55,17 @@ test("renderSyncPullRequestBody uses Chinese sections and lists every path", () assert.match(body, /仅在 `Quality gate` 通过后合入/); }); +test("renderSyncPullRequestBody warns reviewers when automation permits large prunes", () => { + const body = renderSyncPullRequestBody({ + added: [], + modified: [], + removed: ["docs/en/api/reference/legacy.md"], + }); + + assert.match(body, /自动任务会显式允许超过命令行安全阈值的大规模删除/); + assert.match(body, /合入前必须审核“删除文件”清单/); +}); + test("renderSyncRelease keeps article changes and resolves page metadata", () => { const release = renderSyncRelease( {