skill-family-doc-render 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# 变更日志
+
+## 0.2.1 - 2026-09-06
+
+### 变更
+
+- 生成的主导航带有可访问名称，并用 `aria-current="page"` 标出当前页。
+- 教程翻页导航带有可访问名称；不参加翻页链的页面不再生成空导航元素。
+
+## 0.2.0 - 2026-09-05
+
+发布坐标：tag `skill-family-doc-render-v0.2.0`。
+
+### 不兼容变更
+
+- `site-baseline.json` 基线格式升级：新增必填字段 `digests`（渲染产物逐文件
+  sha256）。`--check` 由「磁盘 docs/ 与基线比对」改为三重比对：内存渲染产物
+  逐文件摘要对 `digests`、磁盘实际文件清单对 `files` 集合、磁盘树摘要对
+  `sha256`。0.1.x 旧格式基线（无 `digests`）会被新 schema 拒绝（exit 2）；
+  升级后必须重渲一次（`npx skill-family-doc-render@0.2.0`）更新基线。
+- 退出码语义统一：exit 1 归漂移/泄漏类（`--check` 漂移、泄漏扫描命中、
+  `--assert-git` 缺文件、基线缺失/损坏）；exit 2 归配置类（配置缺失或非法、
+  JSON 解析失败、`@TOKEN@` 占位符残留、`--repo` 误用）。0.1.x 中泄漏失败与
+  配置失败同为 exit 1，且 JSON 解析失败会以裸异常漏出。
+- `--repo` 后缺有效值现在直接报错 exit 2；0.1.1 会静默当作「渲染全部」。
+
+### 新增
+
+- `pages.json` 走 JSON Schema（`schemas/pages.schema.json`）：缺 `pages` 字段
+  或非法 JSON 由裸 TypeError 变为 fail-fast exit 2。
+- `--check` 能抓到「源改未重渲」与「渲染器回归」两类漂移（0.1.x 只能抓
+  产物被手改）。
+
+### 变更
+
+- 泄漏扫描覆盖 assets（`.html`/`.css`/`.js`/`.svg`）写盘前扫描；多趟解码
+  防绕过（HTML 实体双趟、JS 反转义、URL 百分号解码），字面量大小写不敏感。
+  默认字面量与正则一字未动；扩展仍只经 `forbiddenPublicPaths` /
+  `privateLiterals` 配置追加。
+- 未替换的 `@TOKEN@` 占位符残留 fail-fast（exit 2），列出 token 与所在文件。
+- 写盘前预检：在 target 的 canonical parent 内创建 sibling staging，全部产物经 Foundation
+  `writeFileAtomic` 写入。渲染、扫描、基线计算和 `--assert-git` 预检全部成功后才发布：
+  target 已存在时用 `replaceFixedSetAtomic` 单次交换，成功后旧 target 位于
+  `displacedTargetPath`，仅清理该路径；target 不存在时先用
+  `createFixedSetPublicationManifest` 生成清单，再用 `publishFixedSet` 发布。预检或未提交
+  失败时清理 staging，既有 target 保持不变；交换成功后的旧 target 清理失败不回滚已完成的发布。
+- 多仓遍历失败隔离：逐仓收集结果，单仓失败不中断其他仓，末尾汇总并非零退出。
+- `package.json` 缺失或缺 `version` 时输出醒目 WARNING 并回退 0.0.0
+  （0.1.x 静默回退）；`package.json` 非法 JSON 为 fail-fast exit 2。
+- `--assert-git` 在写盘前检查，期望清单从实际渲染产物派生，不再写死文件名；改用
+  `execFileSync` 数组参数，消除 shell 注入面。
+- Foundation 依赖统一精确锁定到 0.18.0：`skill-family-harness-node`、
+  `skill-family-contracts` 与工作区使用的 `skill-family-engineering-kit` 均须从官方
+  npm registry 安装并复核；不接受 `latest`、本地工作树、候选 tarball 或浮动版本。
+
+## 0.1.1 - 2026-08-12
+
+### 变更
+
+- 自 0.1.0 以来：CLI 新增 `--help` 输出与 README 最小示例（`34c8bfd`）；
+  引入 release-skill 发布配置与 README 合同标记（`d194801`）。
+- 版本号随技能族 codebuddy 市场分发路径调整统一抬升，渲染器实现本身无行为变化。
+
+发布坐标：tag `skill-family-doc-render-v0.1.1`（公开仓 commit `8b9c3d67`）。
+
+## 0.1.0 - 2026-08-12
+
+### 新增
+
+- 初始版本：配置驱动的 GitHub Pages 知识站渲染器。读取工作区根
+  `public-release.json`，遍历带 `site` 字段的 repo 渲染到各自 target；
+  nav / pager / footer 注入、版本占位符替换、assets 拷贝、`.nojekyll` 与
+  `site-baseline.json` 树基线、`--check` 漂移检测、`--repo` 单仓选择、
+  写盘前内容级泄漏扫描。

package/README.md

@@ -5,34 +5,52 @@ Config-driven GitHub Pages knowledge-site renderer for skill-family projects (mu
 Reads `public-release.json` from the current working directory, renders every repo carrying a
 `site` field from its site source directory to its target directory (typically `docs/`), injects
 nav / pager / footer, replaces version placeholders, copies assets, writes `.nojekyll` and a
-tree baseline (`site-baseline.json`), and runs a content-level leak scan before any write.
+tree baseline (`site-baseline.json`), and runs a content-level leak scan over every output file
+(pages **and** assets) before any target change. Render, scan, baseline computation and the
+`--assert-git` preflight all finish before the target is changed, so failures in those steps
+leave the existing target untouched. The final directory commit uses Foundation's fixed-set
+publication APIs. A failure before commit removes staging and leaves the existing target
+untouched. After commit, or when publication is indeterminate, staging or displaced data may
+remain for diagnosis; the renderer does not guess or roll back.
 
 ## Install
 
 ```sh
-npm install skill-family-doc-render
+npm install skill-family-doc-render@0.2.0
 ```
 
 Requires Node.js `>=22.22.2 <23` (aligned with the skill-family foundation packages).
 
+0.2.0 consumes the three Foundation packages at the exact `0.18.0` pin:
+`skill-family-contracts@0.18.0`, `skill-family-harness-node@0.18.0` and
+`skill-family-engineering-kit@0.18.0` (the last one is used by the workspace profile check).
+The 0.2.0 baseline format and exit-code changes are breaking changes; existing 0.1.x users
+must re-render their baseline before using `--check`. See the changelog for the full migration
+notes.
+
 ## CLI
 
 ```sh
 # render all repos with a site field (writes to disk)
-npx skill-family-doc-render
+npx skill-family-doc-render@0.2.0
 
 # drift check only: compare in-memory render against committed site-baseline.json, write nothing
-npx skill-family-doc-render --check
+npx skill-family-doc-render@0.2.0 --check
 
 # render / check a single repo by name
-npx skill-family-doc-render --repo <name>
+npx skill-family-doc-render@0.2.0 --repo <name>
 
 # additionally assert every rendered file is tracked in the git index
-npx skill-family-doc-render --assert-git
+npx skill-family-doc-render@0.2.0 --assert-git
 ```
 
-Exit codes: `0` success, `1` drift / check failure / leak-scan hit, `2` configuration or
-schema validation error (the message includes the JSON field path).
+Exit codes: `0` success; `1` drift class — `--check` drift, leak-scan hit, `--assert-git`
+missing files, missing/corrupt baseline; `2` configuration class — missing/invalid
+`public-release.json` or `pages.json`, JSON parse failures, unreplaced `@TOKEN@` placeholders,
+invalid `--repo` usage (the message includes the JSON field path). When several repos are
+rendered in one run, each repo is isolated: a failure in one does not stop the others, and the
+run ends with a summary of successes/failures plus a non-zero exit (2 if any failure was
+configuration-class, otherwise 1).
 
 ## Configuration: `public-release.json`
 
@@ -63,9 +81,12 @@ anything runs.
 }
 ```
 
-- Only repos with a `site` field are rendered; `--repo <name>` selects one by `name`.
-- `site.pages` points to a pages manifest: `{ "pages": [{ "id", "title", "order", "inPager" }] }`.
-  Pages are sorted by `order`; `inPager: false` excludes a page from the prev/next pager.
+- Only repos with a `site` field are rendered; `--repo <name>` selects one by `name`
+  (`--repo` without a valid value is an error, never a silent "render all").
+- `site.pages` points to a pages manifest: `{ "pages": [{ "id", "title", "order", "inPager" }] }`,
+  validated against `schemas/pages.schema.json`. Pages are sorted by `order`;
+  `inPager: false` excludes a page from the prev/next pager. Page `id` is restricted to
+  `[A-Za-z0-9][A-Za-z0-9_-]*`.
 - `forbiddenPublicPaths` / `privateLiterals` append project-specific literals to the leak scan.
 
 ## Placeholders
@@ -82,26 +103,45 @@ Version tokens are derived automatically from the repo's `package.json` version
 - `@{NAME}_TAG@` — e.g. `my-project` → `@MY_PROJECT_TAG@` = `tagPrefix` + version
 - `@{NAME}_VERSION@` — the bare version
 
-`site.tokens` adds arbitrary static placeholder replacements on top.
+`site.tokens` adds arbitrary static placeholder replacements on top. If a rendered page still
+contains an unreplaced `@TOKEN@` (`@[A-Z0-9_]+@`), the run fails fast (exit 2) naming the
+tokens and the file — placeholder typos never slip into the published site silently.
+
+If a repo has no `package.json` (or no valid `version`), the version falls back to `0.0.0`
+with a loud `WARNING` on stderr, because that fallback is baked into the output and the
+baseline; a malformed `package.json` fails fast (exit 2).
 
 ## Leak scan
 
-Every rendered page is scanned **before** any write (`scripts/lib/leak-scan.mjs`). The scanner
-decodes HTML entities and JS escape sequences first, then matches the decoded text against
-built-in private literals (absolute home paths) and secret regexes (private keys, GitHub /
-Slack / AWS / OpenAI tokens), plus the configured `forbiddenPublicPaths` / `privateLiterals`.
-Any hit fails the run fast — encoding tricks do not slip through.
+Every output file — rendered pages **and** copied assets (`.html`/`.css`/`.js`/`.svg`) — is
+scanned **before** any write (`scripts/lib/leak-scan.mjs`). The scanner decodes HTML entities
+(two passes, defeating double encoding), JS escape sequences and URL percent-encoding first,
+then matches case-insensitively against built-in private literals (absolute home paths) and
+secret regexes (private keys, GitHub / Slack / AWS / OpenAI tokens), plus the configured
+`forbiddenPublicPaths` / `privateLiterals`. Any hit fails the run fast (exit 1) — encoding
+tricks do not slip through.
 
 ## Tree baseline
 
-After writing, the renderer records `site-baseline.json` in the target directory:
+After staging, the renderer records `site-baseline.json` in the target directory:
 
 ```json
-{ "sha256": "<closure digest>", "files": ["<sorted relative paths, excluding the baseline itself>"] }
+{
+  "sha256": "<closure digest over the staged tree>",
+  "files": ["<sorted relative paths, excluding the baseline itself>"],
+  "digests": { "<path>": "<per-file sha256 of the rendered bytes>" }
+}
 ```
 
-`--check` recomputes the digest from the in-memory render and fails on any drift. The digest is
-a deterministic set-level sha256 over the contained resources.
+`--check` is read-only and fails on any of three drift classes:
+
+1. **Stale render / renderer regression** — per-file sha256 of the in-memory render vs
+   `digests` (catches "source changed but never re-rendered" and "renderer output changed");
+2. **Hand-added or deleted files** — the actual on-disk file listing of the target vs the
+   `files` set;
+3. **Hand-modified output** — the on-disk tree closure digest vs `sha256`.
+
+The digest is a deterministic set-level sha256 over the contained resources.
 
 ## Foundation dependencies
 
@@ -110,30 +150,41 @@ dependencies:
 
 - [`skill-family-harness-node`](https://github.com/ifoohoo/skill-family-harness-node) — all file
   reads go through `resolveContained` / `readFileContained` (path traversal, symlink and realpath
-  escapes rejected), all writes through `writeFileAtomic` (containment + atomic rename), and the
-  tree baseline is computed with `computeResourceClosure`.
+  escapes rejected), per-file digests use `digestBytes`, the tree baseline is computed with
+  `computeResourceClosure`. Output is staged in a sibling directory under the target's canonical
+  parent, with contained writes through `writeFileAtomic`. A new target uses
+  `createFixedSetPublicationManifest` followed by `publishFixedSet`; an existing target uses
+  `replaceFixedSetAtomic`. Staging is removed after success or a clearly pre-commit failure;
+  post-commit or indeterminate failures may retain it for diagnosis. These APIs do not add a
+  broader atomicity guarantee than Foundation provides.
 - [`skill-family-contracts`](https://github.com/ifoohoo/skill-family-contracts) —
-  `validateDocument` (JSON Schema 2020-12, strict policy) validates `public-release.json` and
-  `site-baseline.json`; validation failure aborts with exit code 2.
+  `validateDocument` (JSON Schema 2020-12, strict policy) validates `public-release.json`,
+  `pages.json` and `site-baseline.json`; validation failure aborts with exit code 2.
 
 ## License
 
 Apache-2.0
 
 <!-- release-skill:capability:safe-first-command -->
-> **Start here:** `npx skill-family-doc-render --check` — the drift check is read-only:
+> **Start here:** after installing the exact `skill-family-doc-render@0.2.0`, run
+> `./node_modules/.bin/skill-family-doc-render --check` — the drift check is read-only:
 > it renders in memory, compares against the committed `site-baseline.json`, writes
-> nothing, and touches no network, git, or credentials.
+> nothing and touches no network or credentials. The CLI performs no Git writes; only an
+> explicit `--assert-git` performs a read-only query of the Git index.
 
 <!-- release-skill:capability:external-write-boundary -->
-> **External write boundary:** this CLI writes only inside the site target directories
-> declared by the project's own `public-release.json` (via contained, atomic writes).
-> It performs no git operations, no network calls, and no writes outside those
-> directories. The pre-write leak scan fails closed on private literals.
+> **External write boundary:** this CLI writes the declared target and a controlled sibling
+> staging directory, both within the target's canonical parent, with contained path checks.
+> Render, scan, baseline and `--assert-git` preflight failures happen before target changes.
+> Staging is removed after success or a clearly pre-commit failure; post-commit or
+> indeterminate failures may retain it to preserve diagnosable state.
+> It performs no Git writes, no network calls, and no writes outside that parent scope.
+> Only an explicit `--assert-git` performs a read-only query of the Git index. The pre-write
+> leak scan fails closed on private literals.
 
 ## Minimal example
 
 ```sh
-npx skill-family-doc-render --help     # show usage
-npx skill-family-doc-render --check    # read-only drift check — the safe first command
+npx skill-family-doc-render@0.2.0 --help     # show usage
+npx skill-family-doc-render@0.2.0 --check    # read-only drift check — the safe first command
 ```

package/bin/skill-family-doc-render.mjs

@@ -1,29 +1,13 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: Apache-2.0
-// CLI 入口：从 process.cwd() 解析 public-release.json，
-// 转发 --check / --repo <name> / --assert-git 到渲染器主流程。
+// CLI 入口：全部 argv 原样委托给 main()，闭集解析与 --help/-h 呈现统一由 main() 裁决。
 import { main, RenderError } from '../scripts/render-public-site.mjs';
 
-const argv = process.argv.slice(2);
-
-if (argv.includes('--help') || argv.includes('-h')) {
-  console.log(`skill-family-doc-render — config-driven GitHub Pages knowledge-site renderer
-
-Usage:
-  skill-family-doc-render                render every repo with a site field (writes)
-  skill-family-doc-render --check        read-only drift check against site-baseline.json
-  skill-family-doc-render --repo <name>  render / check a single repo by name
-  skill-family-doc-render --assert-git   also assert rendered files are git-tracked
-
-Reads public-release.json from the current working directory.`);
-  process.exitCode = 0;
-} else {
-  main(argv, { cwd: process.cwd() })
-    .then((code) => {
-      process.exitCode = code;
-    })
-    .catch((err) => {
-      console.error(err.message);
-      process.exitCode = err instanceof RenderError ? err.exitCode : 1;
-    });
-}
+main(process.argv.slice(2), { cwd: process.cwd() })
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((err) => {
+    console.error(err.message);
+    process.exitCode = err instanceof RenderError ? err.exitCode : 1;
+  });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-family-doc-render",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Config-driven GitHub Pages knowledge-site renderer for skill-family projects (multi-repo capable).",
   "author": "广州市风荷科技有限公司",
   "license": "Apache-2.0",
@@ -16,6 +16,7 @@
     "scripts",
     "schemas",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
@@ -24,7 +25,7 @@
     "render:site:check": "node bin/skill-family-doc-render.mjs --check"
   },
   "dependencies": {
-    "skill-family-contracts": "0.2.1",
-    "skill-family-harness-node": "0.2.1"
+    "skill-family-contracts": "0.18.0",
+    "skill-family-harness-node": "0.18.0"
   }
 }

package/schemas/pages.schema.json

@@ -0,0 +1,27 @@
+{
+  "$id": "https://github.com/ifoohoo/skill-family-doc-render/schemas/pages.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "pages.json",
+  "description": "站点页面清单：页面顺序、导航与翻页的真源。site 块为站点元数据（渲染器不消费）。id 限文件名片段字符，顺带消除拼路径时的 shell 元字符面。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["pages"],
+  "properties": {
+    "site": { "type": "object" },
+    "pages": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "title", "order"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" },
+          "title": { "type": "string", "minLength": 1 },
+          "order": { "type": "integer" },
+          "inPager": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}

package/schemas/site-baseline.schema.json

@@ -2,15 +2,19 @@
   "$id": "https://github.com/ifoohoo/skill-family-doc-render/schemas/site-baseline.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "site-baseline.json",
-  "description": "站点树基线：closure 集合级 sha256 + 排序后的相对路径列表（排除基线自身）。",
+  "description": "站点树基线：closure 集合级 sha256 + 排序后的相对路径列表（排除基线自身）+ 逐文件 sha256 摘要（--check 用于内存渲染产物逐文件比对）。",
   "type": "object",
   "additionalProperties": false,
-  "required": ["sha256", "files"],
+  "required": ["sha256", "files", "digests"],
   "properties": {
     "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
     "files": {
       "type": "array",
       "items": { "type": "string", "minLength": 1 }
+    },
+    "digests": {
+      "type": "object",
+      "additionalProperties": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
     }
   }
 }

package/scripts/lib/leak-scan.mjs

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
-// 内容级泄漏扫描：解码后再匹配，防 HTML 实体 / JS 反转义绕过。
+// 内容级泄漏扫描：解码后再匹配，防 HTML 实体 / JS 反转义 / URL 百分号编码绕过。
 // 默认扫描绝对路径与私钥 / Token；项目特定的私有字面量通过调用方传入
 // （来自 public-release.json 的 forbiddenPublicPaths / privateLiterals）。
+// 字面量匹配大小写不敏感；实体解码跑两趟（防双重编码）。
+// 命中抛 LeakScanError，由调用方归入各自的错误分类体系。
 export const DEFAULT_LITERALS = [
   '/Users/',
   'C:\\Users\\',
@@ -20,37 +22,65 @@ export const DEFAULT_REGEXES = [
   /sk-[A-Za-z0-9]{32,}/,
 ];
 
-// 对文本做 HTML 实体解码 + JS 反转义，得到规范化文本，与原文拼接后扫描，
-// 使绕过者无法用实体 / 转义把敏感字面量藏过简单 includes 检查。
-export function decodeText(s) {
-  let d = s
+// 泄漏命中专用错误类型：调用方可据 instanceof 归类退出码，不与配置错误混淆。
+export class LeakScanError extends Error {}
+
+// HTML 实体解码单趟。允许常见实体省略数字实体末尾分号（浏览器兼容形式）。
+function entityDecode(s) {
+  return s
     .replace(/&/g, '&')
     .replace(/&lt;/g, '<')
     .replace(/&gt;/g, '>')
     .replace(/&quot;/g, '"')
-    .replace(/&#x([0-9a-fA-F]+);/g, (m, h) => String.fromCodePoint(parseInt(h, 16)))
-    .replace(/&#(\d+);/g, (m, d) => String.fromCodePoint(parseInt(d, 10)));
-  d = d
+    .replace(/&sol;/gi, '/')
+    .replace(/&#x([0-9a-fA-F]+);?/gi, (m, h) => String.fromCodePoint(parseInt(h, 16)))
+    .replace(/&#(\d+);?/g, (m, d) => String.fromCodePoint(parseInt(d, 10)));
+}
+
+// JS 转义序列反转义（\xNN / \uNNNN / \u{N} / 八进制 \NNN）。
+function jsUnescape(s) {
+  return s
     .replace(/\\x([0-9a-fA-F]{2})/g, (m, h) => String.fromCharCode(parseInt(h, 16)))
     .replace(/\\u\{([0-9a-fA-F]+)\}/g, (m, h) => String.fromCodePoint(parseInt(h, 16)))
     .replace(/\\u([0-9a-fA-F]{4})/g, (m, h) => String.fromCharCode(parseInt(h, 16)))
     .replace(/\\([0-7]{3})/g, (m, o) => String.fromCharCode(parseInt(o, 8)));
-  return s + '\n' + d;
+}
+
+// URL 百分号解码（逐字节 %XX → 字符；不调用 decodeURIComponent，畸形输入不抛）。
+function pctDecode(s) {
+  return s.replace(/%([0-9a-fA-F]{2})/g, (m, h) => String.fromCharCode(parseInt(h, 16)));
+}
+
+// 对文本做多趟解码：HTML 实体两趟（防双重编码）→ JS 反转义 → URL 百分号解码，
+// 各趟结果与原文拼接后统一扫描，使绕过者无法用各种编码把敏感字面量藏过匹配。
+export function decodeText(s) {
+  const entities = entityDecode(entityDecode(s));
+  const unescaped = jsUnescape(entities);
+  // 固定两趟百分号解码，覆盖双重编码但不允许输入驱动的无界循环。
+  const percent = pctDecode(unescaped);
+  const percentTwice = pctDecode(percent);
+  return [s, entities, unescaped, percent, percentTwice].join('\n');
 }
 
 // relPath: 仅用于报错信息；text: 待扫描原文；opts.literals / opts.regexes 为追加项。
+// 字面量匹配大小写不敏感（原文与小写化探针各匹配一趟，utf8 / utf16le 两编码）。
 export function scanLeak(relPath, text, { literals = [], regexes = [] } = {}) {
   const probe = decodeText(text);
+  const probeLower = probe.toLowerCase();
   const allLit = [...DEFAULT_LITERALS, ...literals];
   for (const lit of allLit) {
+    const litLower = lit.toLowerCase();
     for (const enc of ['utf8', 'utf16le']) {
-      if (Buffer.from(probe, enc).includes(Buffer.from(lit, enc))) {
-        throw new Error(`[泄漏扫描] ${relPath} 命中私有字面量: ${lit}`);
+      if (
+        Buffer.from(probe, enc).includes(Buffer.from(lit, enc)) ||
+        Buffer.from(probeLower, enc).includes(Buffer.from(litLower, enc))
+      ) {
+        throw new LeakScanError(`[泄漏扫描] ${relPath} 命中私有字面量: ${lit}`);
       }
     }
   }
   const allRe = [...DEFAULT_REGEXES, ...regexes];
   for (const re of allRe) {
-    if (re.test(probe)) throw new Error(`[泄漏扫描] ${relPath} 命中私有正则: ${re}`);
+    if (re.test(probe)) throw new LeakScanError(`[泄漏扫描] ${relPath} 命中私有正则: ${re}`);
   }
 }

package/scripts/render-public-site.mjs

@@ -2,25 +2,45 @@
 // 通用 GitHub Pages 知识站渲染器（配置驱动，多仓库）。
 // 遍历 public-release.json 中所有带 site 字段的 repo，渲染各自 docs/public/site/ 源到 docs/。
 // 注入 nav / pager / footer、替换版本占位符、拷贝 assets、写 .nojekyll 与 tree 基线。
-// 写盘前做内容级泄漏扫描（解码后再匹配，防 HTML 实体 / JS 反转义绕过）。
+// 写盘前对所有产物（页面 + assets）做内容级泄漏扫描（解码后再匹配，防 HTML 实体 /
+// JS 反转义 / URL 百分号编码绕过），并 fail-fast 检查未替换的 @TOKEN@ 占位符残留。
 //
-// harness 化：所有配置 / 源文件读取经 readFileContained，所有写盘经 writeFileAtomic
-// （收容 + 原子写，见 skill-family-harness-node）；树基线摘要改用 computeResourceClosure。
-// 配置与基线文件先经 skill-family-contracts validateDocument（JSON Schema 2020-12，
-// strict 策略）校验，校验失败 fail-fast。
+// 写盘事务化：在 target canonical parent 下创建 sibling staging，全部产物先写入其中，
+// 使用 writeFileAtomic；目标不存在时走 createFixedSetPublicationManifest + publishFixedSet，
+// 目标存在时走 replaceFixedSetAtomic。提交前失败清理 staging；提交后或状态不确定时保留现场。
+// --check 为只读：对内存渲染产物逐文件算 sha256（harness digestBytes）与基线逐文件比对，
+// 并把磁盘 target 实际文件清单与 baseline.files 做集合比对，不写任何字节。
+//
+// harness 化：所有配置 / 源文件读取经 readFileContained，staging 的相对输出经
+// writeFileAtomic 收容并原子写入（见 skill-family-harness-node）；树基线摘要用
+// computeResourceClosure，逐文件摘要用 digestBytes。
+// 配置、pages.json 与基线文件先经 skill-family-contracts validateDocument
+// （JSON Schema 2020-12，strict 策略）校验，校验失败 fail-fast。
+//
+// 错误分类（退出码语义）：
+//   exit 1 — 漂移类：--check 检出漂移、泄漏扫描命中、--assert-git 缺失、
+//            基线缺失 / 基线 JSON 损坏；
+//   exit 2 — 配置类：public-release.json / pages.json 缺失、非法或 JSON 解析失败、
+//            package.json JSON 解析失败、@TOKEN@ 占位符残留、--repo 参数无效；
+//   其余意外异常（HarnessError 等）原样抛出，CLI 归为 exit 1。
+//   可预期失败统一封装为 RenderError 携带 exitCode。
 import { existsSync, readFileSync } from 'node:fs';
-import { readdir, rm } from 'node:fs/promises';
-import { resolve, relative, extname, join, dirname } from 'node:path';
+import { readdir, rm, mkdtemp, realpath } from 'node:fs/promises';
+import { resolve, relative, extname, join, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import {
   resolveContained,
   readFileContained,
-  writeFileAtomic,
+  digestBytes,
   computeResourceClosure,
+  writeFileAtomic,
+  createFixedSetPublicationManifest,
+  publishFixedSet,
+  replaceFixedSetAtomic,
 } from 'skill-family-harness-node';
 import { validateDocument } from 'skill-family-contracts';
-import { scanLeak } from './lib/leak-scan.mjs';
+import { scanLeak, LeakScanError } from './lib/leak-scan.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -31,8 +51,11 @@ const publicReleaseSchema = JSON.parse(
 const siteBaselineSchema = JSON.parse(
   readFileSync(join(__dirname, '..', 'schemas', 'site-baseline.schema.json'), 'utf8'),
 );
+const pagesSchema = JSON.parse(
+  readFileSync(join(__dirname, '..', 'schemas', 'pages.schema.json'), 'utf8'),
+);
 
-// 可预期失败（配置缺失、校验失败、check 漂移等）以此类型抛出，携带退出码。
+// 可预期失败（配置缺失、校验失败、check 漂移、泄漏命中等）以此类型抛出，携带退出码。
 export class RenderError extends Error {
   constructor(message, exitCode = 2) {
     super(message);
@@ -48,16 +71,38 @@ function assertValid(doc, schema, label) {
   }
 }
 
+// JSON 解析失败属于配置类错误：包装为 RenderError(exit 2)，其余异常原样抛出。
+async function readJsonContained(root, rel, label, name) {
+  try {
+    return JSON.parse(await readFileContained(root, rel, { encoding: 'utf8' }));
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      throw new RenderError(`[render-public-site] ${name}: ${label} JSON 解析失败: ${err.message}`, 2);
+    }
+    throw err;
+  }
+}
+
 function tokenName(name) {
   return name.toUpperCase().replace(/[^A-Z0-9]+/g, '_');
 }
 
-async function pkgVersion(root, src) {
-  try {
-    return JSON.parse(await readFileContained(root, join(src, 'package.json'), { encoding: 'utf8' })).version;
-  } catch {
+async function pkgVersion(root, source, name) {
+  const pkgRel = join(source, 'package.json');
+  const fallback = (why) => {
+    console.warn(
+      `[render-public-site] WARNING: ${name}: ${why}，版本回退 0.0.0（将烤进产物与基线，请确认是否有意为之）`,
+    );
     return '0.0.0';
+  };
+  if (!existsSync(resolve(root, pkgRel))) {
+    return fallback(`未找到 ${pkgRel}`);
   }
+  const doc = await readJsonContained(root, pkgRel, 'package.json', name);
+  if (!doc || typeof doc.version !== 'string' || !doc.version) {
+    return fallback(`${pkgRel} 缺少有效 version 字段`);
+  }
+  return doc.version;
 }
 
 // --- 树摘要（基于 computeResourceClosure，排除 site-baseline.json 自身，防 hash 循环） ---
@@ -82,32 +127,56 @@ async function listTargetFiles(rootAbs) {
   return out.filter((f) => f !== 'site-baseline.json').sort();
 }
 
+// 泄漏扫描统一入口：命中归为 RenderError(exit 1)，其余异常原样抛出。
+function scanOrThrow(relPath, text, leakLiterals) {
+  try {
+    scanLeak(relPath, text, { literals: leakLiterals });
+  } catch (err) {
+    if (err instanceof LeakScanError) throw new RenderError(err.message, 1);
+    throw err;
+  }
+}
+
 // --- 渲染单仓 ---
 async function renderRepo(root, repo, release, leakLiterals, { check, assertGit }) {
   const site = repo.site;
   const dirRel = join(repo.source, site.dir);
   const pagesRel = join(dirRel, site.pages);
   const targetRel = join(repo.source, site.target);
+  const sourceAbs = resolve(root, repo.source);
+  const dirAbs = resolve(root, dirRel);
   const targetAbs = resolve(root, targetRel);
+  const rootSourceRel = relative(root, sourceAbs);
+  const sourceTargetRel = relative(sourceAbs, targetAbs);
+  const sourceDirRel = relative(sourceAbs, dirAbs);
+  const contained = (rel) => rel !== '' && rel !== '..' && !rel.startsWith('../') && !rel.startsWith('/');
+  const overlaps = (a, b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+  if (!(rootSourceRel === '' || contained(rootSourceRel)) || !contained(sourceTargetRel) || !contained(sourceDirRel) || overlaps(sourceTargetRel, sourceDirRel)) {
+    throw new RenderError(
+      `[render-public-site] ${repo.name}: site.target 必须严格收容于 repo.source，且不得与 site.dir 相同或重叠 (source=${repo.source}, dir=${site.dir}, target=${site.target})`,
+      2,
+    );
+  }
   if (!existsSync(resolve(root, pagesRel))) {
     throw new RenderError(`[render-public-site] ${repo.name}: pages.json 未找到: ${pagesRel}`, 2);
   }
-  const pages = JSON.parse(await readFileContained(root, pagesRel, { encoding: 'utf8' })).pages;
-  const ordered = [...pages].sort((a, b) => a.order - b.order);
+  const pagesDoc = await readJsonContained(root, pagesRel, 'pages.json', repo.name);
+  assertValid(pagesDoc, pagesSchema, `${repo.name} pages.json`);
+  const ordered = [...pagesDoc.pages].sort((a, b) => a.order - b.order);
   const pagerPages = ordered.filter((p) => p.inPager !== false);
 
   function navHtml(currentId) {
     const items = ordered
-      .map((p) => `    <a href="${p.id}.html"${p.id === currentId ? ' class="active"' : ''}>${p.title}</a>`)
+      .map((p) => `    <a href="${p.id}.html"${p.id === currentId ? ' class="active" aria-current="page"' : ''}>${p.title}</a>`)
       .join('\n');
-    return `<nav class="toc">\n${items}\n  </nav>`;
+    return `<nav class="toc" aria-label="主要导航">\n${items}\n  </nav>`;
   }
   function pagerHtml(currentId) {
     const idx = pagerPages.findIndex((p) => p.id === currentId);
-    if (idx < 0) return '<nav class="pager"></nav>';
+    if (idx < 0) return '';
     const prev = pagerPages[(idx - 1 + pagerPages.length) % pagerPages.length];
     const next = pagerPages[(idx + 1) % pagerPages.length];
-    return `<nav class="pager">\n    <a href="${prev.id}.html">← ${prev.title}</a>\n    <span class="spacer"></span>\n    <a href="${next.id}.html">${next.title} →</a>\n  </nav>`;
+    return `<nav class="pager" aria-label="教程翻页">\n    <a href="${prev.id}.html">← ${prev.title}</a>\n    <span class="spacer"></span>\n    <a href="${next.id}.html">${next.title} →</a>\n  </nav>`;
   }
   function footerHtml() {
     const owner = release.owner || 'your-org';
@@ -115,7 +184,7 @@ async function renderRepo(root, repo, release, leakLiterals, { check, assertGit
   }
 
   // 版本占位符：按 repo 名自动派生（@{NAME}_TAG@ / @{NAME}_VERSION@）+ site.tokens 静态补充
-  const version = await pkgVersion(root, repo.source);
+  const version = await pkgVersion(root, repo.source, repo.name);
   const tn = tokenName(repo.name);
   const tokens = {
     [`@${tn}_TAG@`]: (repo.tagPrefix || `${repo.name}-v`) + version,
@@ -128,7 +197,9 @@ async function renderRepo(root, repo, release, leakLiterals, { check, assertGit
     return out;
   }
 
-  const rendered = [];
+  // --- 内存渲染全部产物（页面 + assets + .nojekyll）；任何失败发生在写盘之前 ---
+  // outputs: { path: target 内相对路径, text: 扫描用文本, bytes: 落盘字节 }
+  const outputs = [];
   for (const p of ordered) {
     let html = await readFileContained(root, join(dirRel, p.id + '.html'), { encoding: 'utf8' });
     html = html
@@ -136,9 +207,37 @@ async function renderRepo(root, repo, release, leakLiterals, { check, assertGit
       .replace(/<!--PAGER-->/g, pagerHtml(p.id))
       .replace(/<!--FOOTER-->/g, footerHtml());
     html = replaceTokens(html);
-    rendered.push({ p, html });
+    // 未替换的 @TOKEN@ 占位符残留 fail-fast（防占位符幻觉静默穿透进产物 / 基线 / 发布）
+    const residual = html.match(/@[A-Z0-9_]+@/g);
+    if (residual) {
+      throw new RenderError(
+        `[render-public-site] ${repo.name}: ${p.id}.html 残留未替换的占位符: ${[...new Set(residual)].join(', ')}`,
+        2,
+      );
+    }
+    const out = '<!-- generated by skill-family-doc-render -->\n' + html;
+    outputs.push({ path: p.id + '.html', text: out, bytes: Buffer.from(out, 'utf8') });
+  }
+  // assets（allowlist：html/css/js/svg，不含 png；配图全部自绘 SVG）
+  const assetSrc = resolve(root, dirRel, 'assets');
+  if (existsSync(assetSrc)) {
+    for (const f of (await readdir(assetSrc)).sort()) {
+      if (['.html', '.css', '.js', '.svg'].includes(extname(f))) {
+        const bytes = await readFileContained(root, join(dirRel, 'assets', f));
+        outputs.push({ path: 'assets/' + f, text: bytes.toString('utf8'), bytes });
+      }
+    }
   }
-  for (const { p, html } of rendered) scanLeak(`${repo.name}/${p.id}.html`, html, { literals: leakLiterals });
+  // .nojekyll：禁止 GitHub Pages 跑 Jekyll
+  outputs.push({ path: '.nojekyll', text: '', bytes: Buffer.alloc(0) });
+
+  // 写盘前统一泄漏扫描：页面与 assets 同一规则（对解码后内容）
+  for (const o of outputs) scanOrThrow(`${repo.name}/${o.path}`, o.text, leakLiterals);
+
+  // 逐文件 sha256（harness digestBytes），--check 与基线逐文件比对用
+  const digests = {};
+  for (const o of outputs) digests[o.path] = digestBytes(o.bytes);
+  const files = Object.keys(digests).sort();
 
   if (check) {
     if (!existsSync(targetAbs)) {
@@ -147,17 +246,6 @@ async function renderRepo(root, repo, release, leakLiterals, { check, assertGit
         1,
       );
     }
-    // 不写盘，仅依据内存产物计算树摘要，与已提交的 site-baseline.json 比对
-    const memFiles = [];
-    for (const { p } of rendered) memFiles.push(p.id + '.html');
-    const assetSrc = resolve(root, dirRel, 'assets');
-    if (existsSync(assetSrc)) {
-      for (const f of await readdir(assetSrc)) {
-        if (['.html', '.css', '.js', '.svg'].includes(extname(f))) memFiles.push('assets/' + f);
-      }
-    }
-    memFiles.push('.nojekyll');
-    const memHash = await treeDigest(targetAbs, memFiles);
     const baselineRel = join(targetRel, 'site-baseline.json');
     if (!existsSync(resolve(root, baselineRel))) {
       throw new RenderError(
@@ -165,11 +253,42 @@ async function renderRepo(root, repo, release, leakLiterals, { check, assertGit
         1,
       );
     }
-    const base = JSON.parse(await readFileContained(root, baselineRel, { encoding: 'utf8' }));
+    let base;
+    try {
+      base = JSON.parse(await readFileContained(root, baselineRel, { encoding: 'utf8' }));
+    } catch (err) {
+      if (err instanceof SyntaxError) {
+        throw new RenderError(
+          `[render-public-site --check] ${repo.name}: site-baseline.json JSON 解析失败（基线损坏，请重新渲染）: ${err.message}`,
+          1,
+        );
+      }
+      throw err;
+    }
     assertValid(base, siteBaselineSchema, `${repo.name} site-baseline.json`);
-    if (base.sha256 !== memHash) {
+
+    const drift = [];
+    // 1) 内存渲染产物 vs 基线逐文件摘要：抓「源改未重渲」与「渲染器回归」
+    for (const f of files) {
+      if (!(f in base.digests)) drift.push(`基线缺少文件（源新增未重渲）: ${f}`);
+      else if (base.digests[f] !== digests[f]) drift.push(`内容漂移（源已改未重渲或渲染器回归）: ${f}`);
+    }
+    for (const f of Object.keys(base.digests)) {
+      if (!(f in digests)) drift.push(`基线仍有但源渲染已不产生: ${f}`);
+    }
+    // 2) 磁盘 target 实际文件清单 vs baseline.files：抓 docs/ 被手工增删文件
+    const diskFiles = await listTargetFiles(targetAbs);
+    const baseSet = new Set(base.files);
+    const diskSet = new Set(diskFiles);
+    for (const f of diskFiles) if (!baseSet.has(f)) drift.push(`target 多出未登记文件: ${f}`);
+    for (const f of base.files) if (!diskSet.has(f)) drift.push(`target 缺少基线文件: ${f}`);
+    // 3) 磁盘产物内容 vs 基线树摘要：抓产物被手工修改
+    const diskHash = await treeDigest(targetAbs, diskFiles);
+    if (diskHash !== base.sha256) drift.push('磁盘产物树摘要与基线不一致（产物被手工修改）');
+
+    if (drift.length) {
       throw new RenderError(
-        `[render-public-site --check] ${repo.name}: 漂移：内存产物树摘要与基线不一致`,
+        `[render-public-site --check] ${repo.name}: 漂移:\n  - ${drift.join('\n  - ')}`,
         1,
       );
     }
@@ -177,75 +296,119 @@ async function renderRepo(root, repo, release, leakLiterals, { check, assertGit
     return;
   }
 
-  // 写盘：清空 target 后重建（docs/ 即站点目录）。
-  // harness 不提供删除原语，先经 resolveContained 证明目标收容在工作区内，再整目录重建；
-  // 之后所有文件写入均走 writeFileAtomic（收容 + 原子写）。
-  await resolveContained(root, targetRel);
-  await rm(targetAbs, { recursive: true, force: true });
-  for (const { p, html } of rendered) {
-    await writeFileAtomic(
-      root,
-      join(targetRel, p.id + '.html'),
-      '<!-- generated by skill-family-doc-render -->\n' + html,
-    );
-  }
-  // 拷贝 assets（allowlist：html/css/js/svg，不含 png；配图全部自绘 SVG）
-  const assetSrc = resolve(root, dirRel, 'assets');
-  if (existsSync(assetSrc)) {
-    for (const f of await readdir(assetSrc)) {
-      if (['.html', '.css', '.js', '.svg'].includes(extname(f))) {
-        const bytes = await readFileContained(root, join(dirRel, 'assets', f));
-        await writeFileAtomic(root, join(targetRel, 'assets', f), bytes);
-      }
-    }
-  }
-  // .nojekyll：禁止 GitHub Pages 跑 Jekyll
-  await writeFileAtomic(root, join(targetRel, '.nojekyll'), '');
-  // 树基线（防漂移）
-  const files = await listTargetFiles(targetAbs);
-  const treeHash = await treeDigest(targetAbs, files);
-  await writeFileAtomic(
-    root,
-    join(targetRel, 'site-baseline.json'),
-    JSON.stringify({ sha256: treeHash, files }, null, 2),
-  );
-
-  console.log(`[render-public-site] ${repo.name}: 已渲染 ${rendered.length} 页 + assets 到 ${targetRel}`);
-  console.log(`[render-public-site] ${repo.name}: tree-sha256=${treeHash.slice(0, 16)}…`);
-
-  // 可选：对真实导出快照逐页断言
+  // assert-git 必须在任何 target 变更前完成，避免门禁失败留下部分替换结果。
   if (assertGit) {
-    const expected = ordered.map((p) => `${targetRel}/${p.id}.html`);
-    expected.push(`${targetRel}/assets/style.css`);
-    expected.push(`${targetRel}/.nojekyll`);
-    expected.push(`${targetRel}/index.html`);
+    const expected = files.map((f) => `${targetRel}/${f}`);
     let missing = 0;
     for (const f of expected) {
       try {
-        execSync(`git ls-files --error-unmatch ${f}`, { cwd: root, stdio: 'pipe' });
+        execFileSync('git', ['ls-files', '--error-unmatch', f], { cwd: root, stdio: 'pipe' });
       } catch {
         console.error(`[assert-git] ${repo.name}: 未跟踪（需 git add 并提交）: ${f}`);
         missing++;
       }
     }
-    if (missing) {
-      throw new RenderError(
-        `[assert-git] ${repo.name}: ${missing} 个文件未进 Git 快照，站点无法进入发布`,
-        1,
-      );
-    }
+    if (missing) throw new RenderError(`[assert-git] ${repo.name}: ${missing} 个文件未进 Git 快照，站点无法进入发布`, 1);
     console.log(`[assert-git] ${repo.name}: 全部站点文件已在 Git 快照中`);
   }
+
+  // --- 写盘事务化：在目标目录的 canonical parent 内创建 sibling staging，
+  // 写入和发布均使用 Foundation 公共目录发布 API。 ---
+  await resolveContained(root, targetRel);
+  const targetParent = await realpath(dirname(targetAbs));
+  const targetSegment = basename(targetAbs);
+  const staging = await mkdtemp(join(targetParent, '.sf-doc-render-'));
+  let treeHash;
+  let publicationAttempted = false;
+  try {
+    for (const o of outputs) await writeFileAtomic(staging, o.path, o.bytes);
+    treeHash = await treeDigest(staging, files);
+    await writeFileAtomic(staging, 'site-baseline.json', JSON.stringify({ sha256: treeHash, files, digests }, null, 2));
+    const targetExists = existsSync(targetAbs);
+    if (!targetExists) {
+      const manifest = await createFixedSetPublicationManifest({ sourceRoot: staging, targetParent, targetSegment });
+      publicationAttempted = true;
+      const receipt = await publishFixedSet({ sourceRoot: staging, targetParent, targetSegment, manifest });
+      if (receipt.status !== 'succeeded') {
+        if (receipt.commitState === 'not-committed') await rm(staging, { recursive: true, force: true });
+        throw new Error(`[render-public-site] ${repo.name}: 目录发布失败 (${receipt.status}): ${receipt.error?.message ?? 'unknown'}`);
+      }
+    } else {
+      publicationAttempted = true;
+      const result = await replaceFixedSetAtomic({ sourceRoot: staging, targetParent, targetSegment });
+      try {
+        await rm(result.displacedTargetPath, { recursive: true, force: true });
+      } catch (cleanupError) {
+        throw new Error(`[render-public-site] ${repo.name}: 发布已成功、旧目标清理失败: ${result.displacedTargetPath}; ${cleanupError.message}`, { cause: cleanupError });
+      }
+    }
+    console.log(`[render-public-site] ${repo.name}: 已渲染 ${ordered.length} 页 + assets 到 ${targetRel}`);
+    console.log(`[render-public-site] ${repo.name}: tree-sha256=${treeHash.slice(0, 16)}…`);
+  } catch (err) {
+    const preCommit = err?.details?.phase === 'pre-commit' && err?.details?.publicationState === 'not-published' && err?.details?.commitState === 'not-committed';
+    if (!publicationAttempted || preCommit) await rm(staging, { recursive: true, force: true });
+    throw err;
+  }
+
 }
 
 // === 主流程 ===
+// 闭集参数解析：允许参数只有 --check / --assert-git / --repo <name> / --help / -h。
+// 未知选项、游离位置参数、重复取值参数、--repo 缺值或值本身是另一个选项，
+// 均以 RenderError（exit 2）失败，错误信息指出具体参数。不引入 CLI 框架。
+// --help / -h 由 main() 统一呈现：闭集解析先于配置读取与写盘，打印 USAGE_TEXT 后退出 0。
+const USAGE_TEXT = `skill-family-doc-render — config-driven GitHub Pages knowledge-site renderer
+
+Usage:
+  skill-family-doc-render                render every repo with a site field (writes)
+  skill-family-doc-render --check        read-only drift check against site-baseline.json
+  skill-family-doc-render --repo <name>  render / check a single repo by name
+  skill-family-doc-render --assert-git   also assert rendered files are git-tracked
+
+Reads public-release.json from the current working directory.`;
+
+function parseArgs(argv) {
+  const flags = { check: false, assertGit: false, repoArg: null, help: false };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === '--check') {
+      flags.check = true;
+    } else if (arg === '--assert-git') {
+      flags.assertGit = true;
+    } else if (arg === '--help' || arg === '-h') {
+      flags.help = true;
+    } else if (arg === '--repo') {
+      if (flags.repoArg !== null) {
+        throw new RenderError('[render-public-site] 参数错误: --repo 重复出现，取值语义不明确', 2);
+      }
+      const value = argv[i + 1];
+      if (value === undefined || value === '' || value.startsWith('-')) {
+        throw new RenderError('[render-public-site] --repo 后必须跟一个有效的 repo 名（不能缺省，且值不能是另一个选项）', 2);
+      }
+      flags.repoArg = value;
+      i += 1; // 消费取值
+    } else if (arg.startsWith('-')) {
+      throw new RenderError(`[render-public-site] 参数错误: 未知选项 ${arg}`, 2);
+    } else {
+      throw new RenderError(`[render-public-site] 参数错误: 未知位置参数 ${arg}`, 2);
+    }
+    i += 1;
+  }
+  return flags;
+}
+
 // argv: CLI 参数（不含 node/script 名）；cwd: 工作区根（public-release.json 所在目录）。
 // 返回退出码 0；可预期失败抛 RenderError（携带 exitCode），其余异常原样抛出。
+// 多仓遍历失败隔离：每 repo try/catch 收集结果，全部遍历完后汇总，任一失败整体非零退出；
+// 单个 repo 内部（含泄漏扫描命中）保持 fail-fast。
 export async function main(argv = process.argv.slice(2), { cwd = process.cwd() } = {}) {
-  const check = argv.includes('--check');
-  const assertGit = argv.includes('--assert-git');
-  const repoIdx = argv.indexOf('--repo');
-  const repoArg = repoIdx >= 0 ? argv[repoIdx + 1] : null;
+  // 闭集解析在读取任何配置或写盘之前完成；参数失败时目标树一个字节都不动。
+  const { check, assertGit, repoArg, help } = parseArgs(argv);
+  if (help) {
+    console.log(USAGE_TEXT);
+    return 0;
+  }
 
   const root = resolve(cwd);
 
@@ -254,7 +417,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd() }
   if (!existsSync(releasePath)) {
     throw new RenderError('[render-public-site] 未找到 public-release.json', 2);
   }
-  const release = JSON.parse(await readFileContained(root, 'public-release.json', { encoding: 'utf8' }));
+  const release = await readJsonContained(root, 'public-release.json', 'public-release.json', '(workspace)');
   assertValid(release, publicReleaseSchema, 'public-release.json');
 
   // 泄漏扫描追加字面量（来自配置；路径类用 forbiddenPublicPaths，任意私有词用 privateLiterals）
@@ -276,7 +439,36 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd() }
     throw new RenderError('[render-public-site] public-release.json 中没有带 site 字段的 repo', 2);
   }
 
-  for (const repo of selected) await renderRepo(root, repo, release, leakLiterals, { check, assertGit });
+  const results = [];
+  for (const repo of selected) {
+    try {
+      await renderRepo(root, repo, release, leakLiterals, { check, assertGit });
+      results.push({ name: repo.name, ok: true });
+    } catch (err) {
+      results.push({
+        name: repo.name,
+        ok: false,
+        exitCode: err instanceof RenderError ? err.exitCode : 1,
+        message: err.message,
+        cause: err,
+      });
+    }
+  }
+  const failed = results.filter((r) => !r.ok);
+  if (failed.length) {
+    // 汇总报告哪些成功哪些失败；退出码取失败中最严重一类（配置类 2 优先于漂移/泄漏类 1）
+    const exitCode = failed.some((f) => f.exitCode === 2) ? 2 : 1;
+    const lines = results.map((r) => (r.ok ? `  ✓ ${r.name}: 成功` : `  ✗ ${r.name}: ${r.message}`));
+    const aggregate = new RenderError(
+      `[render-public-site] ${failed.length}/${results.length} 个 repo 失败:\n${lines.join('\n')}`,
+      exitCode,
+    );
+    if (failed.length === 1 && failed[0].cause?.code) {
+      aggregate.code = failed[0].cause.code;
+      aggregate.details = failed[0].cause.details;
+    }
+    throw aggregate;
+  }
   return 0;
 }