skill-family-doc-render 0.3.0 → 0.4.0

package/scripts/lib/rendered-links.mjs

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+// 只读检查已渲染站点的相对页面、资源、CSS 依赖与页内锚点。
+import { dirname, extname, relative, resolve } from 'node:path';
+import { readFileContained, resolveContained } from 'skill-family-harness-node';
+
+export class RenderedLinksError extends Error {
+  constructor(failures) {
+    super(`${failures.length} 个链接失败:\n  - ${failures.join('\n  - ')}`);
+    this.failures = failures;
+  }
+}
+
+function isExternal(value) {
+  return /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(value);
+}
+
+function anchorsOf(html) {
+  const anchors = new Set();
+  for (const match of html.matchAll(/\s(?:id|name)\s*=\s*["']([^"']+)["']/gi)) anchors.add(match[1]);
+  return anchors;
+}
+
+function referencesOf(html) {
+  const refs = [];
+  for (const match of html.matchAll(/\s(?:href|src)\s*=\s*["']([^"']+)["']/gi)) refs.push(match[1].trim());
+  return refs;
+}
+
+function cssReferencesOf(css) {
+  const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  const refs = [];
+  for (const match of withoutComments.matchAll(/url\(\s*(["']?)(.*?)\1\s*\)/gi)) refs.push(match[2].trim());
+  for (const match of withoutComments.matchAll(/@import\s+(?!url\()(["'])(.*?)\1/gi)) refs.push(match[2].trim());
+  return refs;
+}
+
+/**
+ * @param {{targetRoot:string,pageIds:string[]}} input
+ * @returns {Promise<{pages:number}>}
+ */
+export async function checkRenderedLinks({ targetRoot, pageIds }) {
+  const targetDir = resolve(targetRoot);
+  const htmlFiles = pageIds.map((id) => `${id}.html`);
+  const textCache = new Map();
+  const loadText = async (path) => {
+    if (!textCache.has(path)) {
+      textCache.set(path, await readFileContained(targetDir, relative(targetDir, path), { encoding: 'utf8' }));
+    }
+    return textCache.get(path);
+  };
+  const failures = [];
+  const visitedCss = new Set();
+  const visitedHtml = new Set();
+
+  async function inspectReference({ originPath, originLabel, raw }) {
+    if (!raw || raw === '#' || isExternal(raw)) return;
+    if (raw.startsWith('/')) {
+      failures.push(`${originLabel}: ${raw} 使用站点根绝对路径，部署到仓库子路径后会失效`);
+      return;
+    }
+    const [withoutFragment, fragment = ''] = raw.split('#', 2);
+    const pathPart = withoutFragment.split('?', 1)[0];
+    let decoded;
+    try {
+      decoded = decodeURIComponent(pathPart);
+    } catch {
+      failures.push(`${originLabel}: ${raw} 含无效 URL 编码`);
+      return;
+    }
+    const candidate = decoded ? resolve(dirname(originPath), decoded) : originPath;
+    let target;
+    try {
+      target = candidate === originPath
+        ? originPath
+        : await resolveContained(targetDir, relative(targetDir, candidate));
+      await readFileContained(targetDir, relative(targetDir, target));
+    } catch {
+      failures.push(`${originLabel}: ${raw} 指向不存在、越界或经过不安全符号链接的页面或资源`);
+      return;
+    }
+    const extension = extname(target).toLowerCase();
+    if (fragment && extension === '.html') {
+      const targetHtml = await loadText(target);
+      let decodedFragment;
+      try {
+        decodedFragment = decodeURIComponent(fragment);
+      } catch {
+        failures.push(`${originLabel}: ${raw} 含无效锚点编码`);
+        return;
+      }
+      if (!anchorsOf(targetHtml).has(decodedFragment)) failures.push(`${originLabel}: ${raw} 指向不存在的页内锚点`);
+    }
+    if (extension === '.html') await inspectHtml(target, relative(targetDir, target).replaceAll('\\', '/'));
+    if (extension === '.css') {
+      const cssRel = relative(targetDir, target).replaceAll('\\', '/');
+      if (visitedCss.has(cssRel)) return;
+      visitedCss.add(cssRel);
+      const css = await loadText(target);
+      for (const cssRef of cssReferencesOf(css)) {
+        await inspectReference({ originPath: target, originLabel: cssRel, raw: cssRef });
+      }
+    }
+  }
+
+  async function inspectHtml(pagePath, htmlFile, required = false) {
+    if (visitedHtml.has(htmlFile)) return;
+    visitedHtml.add(htmlFile);
+    let html;
+    try {
+      html = await loadText(pagePath);
+    } catch {
+      if (required) failures.push(`${htmlFile}: 生成页面不存在`);
+      return;
+    }
+    for (const raw of referencesOf(html)) await inspectReference({ originPath: pagePath, originLabel: htmlFile, raw });
+  }
+
+  for (const htmlFile of htmlFiles) {
+    await inspectHtml(resolve(targetDir, htmlFile), htmlFile, true);
+  }
+
+  if (failures.length) throw new RenderedLinksError(failures);
+  return { pages: htmlFiles.length };
+}

package/scripts/lib/svg-safety.mjs

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+// 对项目内容 SVG 做保守的主动内容检查；模板自带图标不走此入口。
+
+export class SvgSafetyError extends TypeError {
+  constructor(path, message) {
+    super(`unsafe SVG ${path}: ${message}`);
+  }
+}
+
+const reject = (path, message) => { throw new SvgSafetyError(path, message); };
+
+function decodeCssEscapes(value) {
+  return value
+    .replace(/\\([0-9a-f]{1,6})\s?/gi, (_match, digits) => {
+      const codePoint = Number.parseInt(digits, 16);
+      return codePoint === 0 || codePoint > 0x10ffff ? '\uFFFD' : String.fromCodePoint(codePoint);
+    })
+    .replace(/\\([^\r\n\f])/g, '$1');
+}
+
+export function assertSafeSvg(text, path) {
+  if (typeof text !== 'string' || !text.trim()) reject(path, 'file must be nonempty UTF-8 text');
+  if (text.includes('\u0000')) reject(path, 'NUL is not allowed');
+  if (!/^\s*(?:<\?xml\s[^?]*\?>\s*)?(?:<!--[\s\S]*?-->\s*)*<svg(?:\s|>)/i.test(text)) {
+    reject(path, 'root element must be svg');
+  }
+  if (/<!\s*(?:DOCTYPE|ENTITY)\b/i.test(text)) reject(path, 'DTD and entity declarations are not allowed');
+  if (/<\/?(?:[A-Za-z_][\w.-]*:)?(?:script|foreignObject)(?:\s|\/?>)/i.test(text)) {
+    reject(path, 'script and foreignObject elements are not allowed');
+  }
+  if (/\s(?:[A-Za-z_][\w.-]*:)?on[a-z0-9_.:-]*\s*=/i.test(text)) reject(path, 'event attributes are not allowed');
+  if (/<\?(?!xml\s)[\s\S]*?\?>/i.test(text)) reject(path, 'processing instructions are not allowed');
+  if (/\b(?:href|xlink:href|src)\s*=\s*(["'])(?!#)[\s\S]*?\1/i.test(text)) {
+    reject(path, 'external resource references are not allowed');
+  }
+  if (/\b(?:href|xlink:href|src)\s*=\s*[^\s"'=<>`]+/i.test(text)) {
+    reject(path, 'resource references must be quoted local fragments');
+  }
+  const decodedCss = decodeCssEscapes(text);
+  if (/@import\b/i.test(decodedCss)) reject(path, 'CSS imports are not allowed');
+  for (const match of decodedCss.matchAll(/url\(\s*(["']?)(.*?)\1\s*\)/gi)) {
+    if (!/^#[A-Za-z0-9][A-Za-z0-9_-]*$/.test(match[2])) reject(path, 'CSS URLs must be local fragments');
+  }
+  return text;
+}

package/scripts/render-public-site.mjs

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // 通用 GitHub Pages 知识站渲染器（配置驱动，多仓库）。
-// 遍历 public-release.json 中所有带 site 字段的 repo，渲染各自 docs/public/site/ 源到 docs/。
-// 注入 nav / pager / footer、替换版本占位符、拷贝 assets、写 .nojekyll 与 tree 基线。
+// 遍历 public-release.json 中所有带 site 字段的 repo，渲染各自站点源到目标目录。
+// format 缺省时兼容完整 HTML 注入；显式 markdown-v1 + editorial 时，将受限 Markdown
+// 编译为语义块并交给包内统一模板。两条路径共用扫描、基线和原子发布。
 // 写盘前对所有产物（页面 + assets）做内容级泄漏扫描（解码后再匹配，防 HTML 实体 /
 // JS 反转义 / URL 百分号编码绕过），并 fail-fast 检查未替换的 @TOKEN@ 占位符残留。
 //
@@ -21,11 +22,11 @@
 //   exit 1 — 漂移类：--check 检出漂移、覆盖快照缺失或落后、泄漏扫描命中、
 //            --assert-git 缺失、渲染基线缺失 / 基线 JSON 损坏；
 //   exit 2 — 配置或工具类：配置 / JSON / 覆盖输入非法、Git 调用失败、
-//            @TOKEN@ 占位符残留、--repo 参数无效；
+//            @TOKEN@ 占位符残留、markdown-v1/SVG 输入非法、--repo 参数无效；
 //   其余意外异常（HarnessError 等）原样抛出，CLI 归为 exit 1。
 //   可预期失败统一封装为 RenderError 携带 exitCode。
 import { existsSync, readFileSync } from 'node:fs';
-import { readdir, rm, mkdtemp, realpath, stat, glob } from 'node:fs/promises';
+import { readFile, readdir, rm, mkdtemp, realpath, stat, glob } from 'node:fs/promises';
 import { resolve, relative, extname, join, dirname, basename, posix } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
@@ -42,6 +43,10 @@ import {
 } from 'skill-family-harness-node';
 import { validateDocument } from 'skill-family-contracts';
 import { scanLeak, LeakScanError } from './lib/leak-scan.mjs';
+import { compileMarkdownV1, replaceMarkdownTokens } from './lib/markdown-v1.mjs';
+import { assertSafeSvg } from './lib/svg-safety.mjs';
+import { checkRenderedLinks } from './lib/rendered-links.mjs';
+import { renderEditorialSite } from '../templates/editorial/index.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -436,8 +441,81 @@ function scanOrThrow(relPath, text, leakLiterals) {
   }
 }
 
+function decodeUtf8(bytes, label) {
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch (cause) {
+    throw new TypeError(`${label} must be valid UTF-8`, { cause });
+  }
+}
+
+function editorialMetadata(pagesDoc, tokens) {
+  const text = (value, label) => replaceMarkdownTokens(value, tokens, label);
+  return {
+    site: {
+      title: text(pagesDoc.site.title, 'site.title'),
+      description: text(pagesDoc.site.description, 'site.description'),
+      productKind: pagesDoc.site.productKind,
+    },
+    groups: pagesDoc.groups.map((group) => ({
+      ...group,
+      title: text(group.title, `group ${group.id} title`),
+    })),
+  };
+}
+
+async function markdownOutputs(root, repo, dirRel, pagesDoc, tokens) {
+  if (repo.site.template !== 'editorial') {
+    throw new TypeError(`unsupported template: ${repo.site.template}`);
+  }
+  const containedDir = await resolveContained(root, dirRel);
+  const expected = new Set(pagesDoc.pages.map((page) => `${page.id}.md`));
+  const actual = new Set((await readdir(containedDir, { withFileTypes: true }))
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+    .map((entry) => entry.name));
+  const mismatches = [
+    ...[...expected].filter((name) => !actual.has(name)).map((name) => `missing ${name}`),
+    ...[...actual].filter((name) => !expected.has(name)).map((name) => `undeclared ${name}`),
+  ].sort();
+  if (mismatches.length) throw new TypeError(`Markdown source set does not match pages.json: ${mismatches.join(', ')}`);
+
+  const images = new Set();
+  const pages = [];
+  for (const page of pagesDoc.pages) {
+    const rel = join(dirRel, `${page.id}.md`);
+    const source = decodeUtf8(await readFileContained(root, rel), `${page.id}.md`);
+    const compiled = compileMarkdownV1(source, { pageId: page.id, tokens });
+    compiled.images.forEach((path) => images.add(path));
+    pages.push({
+      ...page,
+      title: replaceMarkdownTokens(page.title, tokens, `page ${page.id} title`),
+      ...(page.navTitle === undefined ? {} : {
+        navTitle: replaceMarkdownTokens(page.navTitle, tokens, `page ${page.id} navTitle`),
+      }),
+      blocks: compiled.blocks,
+    });
+  }
+
+  const rendered = renderEditorialSite({ ...editorialMetadata(pagesDoc, tokens), pages });
+  const outputs = rendered.pages.map((page) => {
+    const text = `<!-- generated by skill-family-doc-render -->\n${page.text}`;
+    return { path: page.path, text, bytes: Buffer.from(text, 'utf8') };
+  });
+  for (const asset of rendered.assets) {
+    const bytes = await readFile(asset.source);
+    outputs.push({ path: asset.path, text: decodeUtf8(bytes, asset.path), bytes });
+  }
+  for (const path of [...images].sort()) {
+    const bytes = await readFileContained(root, join(dirRel, path));
+    const text = decodeUtf8(bytes, path);
+    assertSafeSvg(text, path);
+    outputs.push({ path, text, bytes });
+  }
+  return outputs;
+}
+
 // --- 渲染单仓 ---
-async function renderRepo(root, repo, release, leakLiterals, { check, assertGit }) {
+async function renderRepo(root, repo, release, leakLiterals, { check, assertGit, inputOnly = false }) {
   const site = repo.site;
   const dirRel = join(repo.source, site.dir);
   const pagesRel = join(dirRel, site.pages);
@@ -500,32 +578,44 @@ async function renderRepo(root, repo, release, leakLiterals, { check, assertGit
 
   // --- 内存渲染全部产物（页面 + 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
-      .replace(/<!--NAV-->/g, navHtml(p.id))
-      .replace(/<!--PAGER-->/g, pagerHtml(p.id))
-      .replace(/<!--FOOTER-->/g, footerHtml());
-    html = replaceTokens(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,
-      );
+  let outputs;
+  if (site.format === 'markdown-v1') {
+    try {
+      outputs = await markdownOutputs(root, repo, dirRel, pagesDoc, tokens);
+    } catch (cause) {
+      throw configError(repo.name, `markdown-v1 输入错误: ${cause.message}`, cause);
     }
-    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 });
+  } else {
+    if (pagesDoc.groups !== undefined) {
+      throw configError(repo.name, 'markdown-v1 页面清单必须显式配置 site.format 与 site.template');
+    }
+    outputs = [];
+    for (const p of ordered) {
+      let html = await readFileContained(root, join(dirRel, p.id + '.html'), { encoding: 'utf8' });
+      html = html
+        .replace(/<!--NAV-->/g, navHtml(p.id))
+        .replace(/<!--PAGER-->/g, pagerHtml(p.id))
+        .replace(/<!--FOOTER-->/g, footerHtml());
+      html = replaceTokens(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') });
+    }
+    // 旧 HTML 兼容模式继续复制项目自有资源。
+    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 });
+        }
       }
     }
   }
@@ -534,6 +624,7 @@ async function renderRepo(root, repo, release, leakLiterals, { check, assertGit
 
   // 写盘前统一泄漏扫描：页面与 assets 同一规则（对解码后内容）
   for (const o of outputs) scanOrThrow(`${repo.name}/${o.path}`, o.text, leakLiterals);
+  if (inputOnly) return;
 
   // 逐文件 sha256（harness digestBytes），--check 与基线逐文件比对用
   const digests = {};
@@ -653,9 +744,41 @@ async function renderRepo(root, repo, release, leakLiterals, { check, assertGit
 
 }
 
+function projectRecoveryPrompt(repoName) {
+  return `请使用 skill-family-docs-render-site 处理仓库 ${repoName} 的知识站检查失败。先读取 public-release.json 和 skill-family-doc-render --check-project --repo ${repoName} 的实际输出，再判断需要内容刷新、纯渲染还是修正配置。不提前刷新覆盖快照，不手改生成产物。`;
+}
+
+function projectCheckError(repoName, cause, fallbackExitCode = 1) {
+  const exitCode = Number.isInteger(cause?.exitCode) ? cause.exitCode : fallbackExitCode;
+  return new RenderError(
+    `[render-public-site --check-project] ${repoName}: public-release.json 检查失败\n`
+    + `实际原因: ${cause.message}\n`
+    + `恢复提示: ${projectRecoveryPrompt(repoName)}`,
+    exitCode,
+    cause,
+  );
+}
+
+async function checkProject(root, repo, release, leakLiterals) {
+  try {
+    await renderRepo(root, repo, release, leakLiterals, { check: false, assertGit: false, inputOnly: true });
+    console.log(`[render-public-site --check-project] ${repo.name}: 输入、公开安全与正文机械合同通过`);
+    await reportCoverageStatus(root, repo);
+    await renderRepo(root, repo, release, leakLiterals, { check: true, assertGit: false });
+    const sourceRoot = await repoSourceRoot(root, repo);
+    const targetDir = await containedOrConfig(sourceRoot, repo.site.target, repo.name, 'site.target');
+    const pagesDoc = await readJsonContained(sourceRoot, join(repo.site.dir, repo.site.pages), 'pages.json', repo.name);
+    await checkRenderedLinks({ targetRoot: targetDir, pageIds: pagesDoc.pages.map((page) => page.id) });
+    console.log(`[render-public-site --check-project] ${repo.name}: 内部链接与资源通过`);
+    console.log(`[render-public-site --check-project] ${repo.name}: public-release.json 只读项目检查通过`);
+  } catch (cause) {
+    throw projectCheckError(repo.name, cause);
+  }
+}
+
 // === 主流程 ===
 // 闭集参数解析：允许参数只有 --check / --assert-git / --status /
-// --refresh-coverage / --repo <name> / --help / -h。
+// --refresh-coverage / --check-project / --repo <name> / --help / -h。
 // 未知选项、游离位置参数、重复取值参数、--repo 缺值或值本身是另一个选项，
 // 均以 RenderError（exit 2）失败，错误信息指出具体参数。不引入 CLI 框架。
 // --help / -h 由 main() 统一呈现：闭集解析先于配置读取与写盘，打印 USAGE_TEXT 后退出 0。
@@ -670,6 +793,8 @@ Usage:
                                         read-only coverage status and Git changes
   skill-family-doc-render --refresh-coverage --repo <name>
                                         refresh only site-coverage-lock.json
+  skill-family-doc-render --check-project --repo <name>
+                                        read-only input, coverage, render and link checks
 
 Reads public-release.json from the current working directory.`;
 
@@ -679,6 +804,7 @@ function parseArgs(argv) {
     assertGit: false,
     status: false,
     refreshCoverage: false,
+    checkProject: false,
     repoArg: null,
     help: false,
   };
@@ -693,6 +819,8 @@ function parseArgs(argv) {
       flags.status = true;
     } else if (arg === '--refresh-coverage') {
       flags.refreshCoverage = true;
+    } else if (arg === '--check-project') {
+      flags.checkProject = true;
     } else if (arg === '--help' || arg === '-h') {
       flags.help = true;
     } else if (arg === '--repo') {
@@ -721,6 +849,20 @@ function parseArgs(argv) {
   if ((flags.status || flags.refreshCoverage) && flags.repoArg === null) {
     throw new RenderError('[render-public-site] 参数错误: --status 与 --refresh-coverage 必须配合 --repo <name>', 2);
   }
+  if (flags.checkProject && (flags.check || flags.assertGit || flags.status || flags.refreshCoverage || flags.help)) {
+    throw projectCheckError(
+      flags.repoArg ?? '<missing>',
+      new RenderError('参数错误: --check-project 不能与其他检查、覆盖、Git 或帮助模式组合', 2),
+      2,
+    );
+  }
+  if (flags.checkProject && flags.repoArg === null) {
+    throw projectCheckError(
+      '<missing>',
+      new RenderError('参数错误: --check-project 必须配合 --repo <name>', 2),
+      2,
+    );
+  }
   return flags;
 }
 
@@ -730,7 +872,7 @@ function parseArgs(argv) {
 // 单个 repo 内部（含泄漏扫描命中）保持 fail-fast。
 export async function main(argv = process.argv.slice(2), { cwd = process.cwd() } = {}) {
   // 闭集解析在读取任何配置或写盘之前完成；参数失败时目标树一个字节都不动。
-  const { check, assertGit, status, refreshCoverage, repoArg, help } = parseArgs(argv);
+  const { check, assertGit, status, refreshCoverage, checkProject: projectCheck, repoArg, help } = parseArgs(argv);
   if (help) {
     console.log(USAGE_TEXT);
     return 0;
@@ -741,10 +883,17 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd() }
   // --- 读取发布配置 ---
   const releasePath = resolve(root, 'public-release.json');
   if (!existsSync(releasePath)) {
-    throw new RenderError('[render-public-site] 未找到 public-release.json', 2);
+    const cause = new RenderError('[render-public-site] 未找到 public-release.json', 2);
+    throw projectCheck ? projectCheckError(repoArg, cause, 2) : cause;
+  }
+  let release;
+  try {
+    release = await readJsonContained(root, 'public-release.json', 'public-release.json', '(workspace)');
+    assertValid(release, publicReleaseSchema, 'public-release.json');
+  } catch (cause) {
+    if (projectCheck) throw projectCheckError(repoArg, cause, 2);
+    throw cause;
   }
-  const release = await readJsonContained(root, 'public-release.json', 'public-release.json', '(workspace)');
-  assertValid(release, publicReleaseSchema, 'public-release.json');
 
   // 泄漏扫描追加字面量（来自配置；路径类用 forbiddenPublicPaths，任意私有词用 privateLiterals）
   const leakLiterals = [
@@ -757,7 +906,8 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd() }
   if (repoArg) {
     const hit = selected.find((r) => r.name === repoArg);
     if (!hit) {
-      throw new RenderError(`[render-public-site] 未找到带 site 的 repo: ${repoArg}`, 2);
+      const cause = new RenderError(`[render-public-site] 未找到带 site 的 repo: ${repoArg}`, 2);
+      throw projectCheck ? projectCheckError(repoArg, cause, 2) : cause;
     }
     selected = [hit];
   }
@@ -770,6 +920,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd() }
     try {
       if (status) await reportCoverageStatus(root, repo);
       else if (refreshCoverage) await refreshCoverageLock(root, repo);
+      else if (projectCheck) await checkProject(root, repo, release, leakLiterals);
       else await renderRepo(root, repo, release, leakLiterals, { check, assertGit });
       results.push({ name: repo.name, ok: true });
     } catch (err) {

package/templates/editorial/README.md

@@ -0,0 +1,129 @@
+# Editorial 文档模板
+
+本目录把已认可的阅读界面封装为渲染包内的纯模板函数。输入页面清单及语义内容块，返回静态 HTML 和固定资源位置；模板不读写项目文件。
+
+这份说明面向渲染器集成者，假定读者了解 JavaScript 模块和当前项目的页面清单。该模板从 `skill-family-doc-render` 0.4.0 起由唯一 CLI 在显式 `markdown-v1` 模式中调用；使用前仍需从官方 npm registry 核对该精确版本是否可用。
+
+## 最小调用
+
+以下虚构项目从同一包的深层路径导入函数。它只有首页和一篇教程，可展示基础目录、首页入口与代码组件：
+
+```js
+import { renderEditorialSite } from 'skill-family-doc-render/templates/editorial/index.mjs';
+
+const output = renderEditorialSite({
+  site: {
+    title: '青苔笔记',
+    description: '虚构项目的操作说明',
+    productKind: 'plugin',
+  },
+  groups: [{ id: 'start', title: '入门' }],
+  pages: [
+    {
+      id: 'index', title: '从一项具体操作开始', navTitle: '开始使用',
+      role: 'overview', kind: 'home', group: 'start', order: 0, inPager: false,
+      blocks: [{ type: 'paragraph', content: ['准备项目后，整理第一份说明。'] }],
+    },
+    {
+      id: 'setup', title: '准备项目并确认输入', navTitle: '准备项目',
+      role: 'setup', kind: 'task', group: 'start', order: 1, inPager: true,
+      blocks: [
+        { type: 'paragraph', content: ['提供项目位置及已有说明。'] },
+        { type: 'heading', level: 2, id: 'request', content: ['发起准备请求'] },
+        { type: 'code', language: 'prompt', text: '检查当前项目，保留已有配置。' },
+      ],
+    },
+  ],
+});
+```
+
+调用不访问磁盘。示例返回两个页面；渲染器再执行资源收容、SVG 安全检查、泄漏扫描、基线计算和输出替换。
+
+返回对象包含两个数组：
+
+- `pages`：每项为 `{ path, text }`。页面路径固定为 `<id>.html`，文字是完整 HTML。
+- `assets`：每项为 `{ path, source }`。`source` 是指向包内文件的 `URL` 对象；资源路径固定为 `assets/editorial/style.css`、`site.js` 和 `mark.svg`。
+
+页面、资源和链接均使用相对路径，可部署在站点子路径。资源列表只列模板自带文件；正文图片由调用者根据内容源收集和检查。相同输入产生相同页面字节，数组按页面顺序输出，不使用日期、随机数、系统路径或网络结果。
+
+## 页面清单
+
+`site` 提供站点标题、简短描述和项目类型。`productKind` 支持 `plugin`、`library`；本函数按已确定的清单渲染，不根据类型另建导航。首次清单由 `skill-family-docs` 的本地接入与生成流程建立。
+
+`groups` 按数组顺序定义分组，每组包含安全 ID 与显示标题。页面由 `group` 引用分组，在组内按 `order` 排序。页面字段及约束见下表。
+
+| 字段 | 含义与约束 |
+| --- | --- |
+| `id` | 页面地址来源，全站唯一；允许字母、数字、下划线、短横线，首字符必须为字母或数字 |
+| `title` | 唯一 H1、浏览器标题与搜索标题 |
+| `navTitle` | 可选短导航标签；未提供时使用页面标题 |
+| `role` | 读者任务，支持 overview、setup、first-success、maintenance、release、troubleshooting、upgrade、reference |
+| `kind` | 固定版式，支持 home、task、reference、troubleshooting |
+| `group` | 已声明的分组 ID |
+| `order` | 全站唯一的安全整数，可以为负数 |
+| `inPager` | 是否加入教程，只允许 task 页设为 true |
+| `blocks` | 顺序排列的语义内容块，首项必须为非空段落 |
+
+每站必须恰有一页 `home`，与 `overview` 职责成对出现。其余页面不强制凑齐职责；排错页和参考页使用相同阅读组件，但不生成教程操作入口。
+
+首段只在页首显示一次，同时派生首页任务说明、页面描述与搜索文字，不另设摘要字段。首页从教程页中按顺序生成任务入口，主操作指向第一项；存在其他 `maintenance` 任务时显示次操作。教程前后页使用同一顺序，首尾不循环；只有一篇教程时不显示翻页组件。
+
+## 语义内容块
+
+`content` 等行内字段使用数组。最简单的数组只有字符串；需要强调或链接时，加入下面四种对象：
+
+```js
+[
+  '操作完成后，查看',
+  { type: 'link', href: 'setup.html#request', content: ['准备请求'] },
+  { type: 'strong', content: ['必要条件'] },
+  { type: 'em', content: ['可选说明'] },
+  { type: 'code', text: 'project.config' },
+]
+```
+
+强调节点允许继续包含行内内容；链接不能嵌套链接。模板转义所有文字，不把字符串解释为 HTML。
+
+| 内容块 | 输入字段 | 输出 |
+| --- | --- | --- |
+| paragraph | `content` 行内数组 | 段落；首块用作导语 |
+| heading | `level` 为 2–4，`id` 与 `content` | 稳定标题、章节链接及页内目录 |
+| list | `ordered` 布尔值，`items` 为行内数组的数组 | 有序步骤或普通列表，不支持嵌套列表 |
+| table | `headers` 为行内单元格数组，`rows` 为行数组 | 带列标题的表格，宽表在本地容器滚动 |
+| code | `language` 语言标记，`text` 原文 | 代码块；prompt 标记显示提示词组件 |
+| callout | `tone` 为 NOTE、TIP、WARNING，`content` | 说明、建议或注意提示框 |
+| image | `src` 站内 SVG 路径，`alt` 非空替代说明 | 普通 img，不内联 SVG |
+
+代码复制保留 `text` 的首尾空白与换行。模板不执行命令，也不做语法高亮。列表项和提示框仅支持行内内容；嵌套容器、页签、自定义布局和任意属性不在当前接口内。
+
+标题 ID 与页面 ID 使用相同字符范围。同页标题不能重复，也不能与当前页面 ID 冲突。`editorial-` 前缀保留给页面外框及代码控件；输入使用此前缀时报告错误。标题更名应保留原 ID。
+
+普通链接支持 `http`、`https` 和不含查询参数的 `mailto`。站内链接使用已声明的 `页面ID.html`、`页面ID.html#章节ID` 或 `#章节ID`，页面地址可加 `./`。
+
+本站链接必须能在当前输入中找到目标。不接受上级目录、根相对地址、查询参数、协议相对地址或任意协议；外部网页不在本函数中联网验证。
+
+图片路径限于 `assets/` 下的 `.svg` 文件，目录与文件名使用字母、数字、下划线、短横线；`assets/editorial/` 是模板资源保留目录。这里只校验引用形式，不读取或检查 SVG 字节。调用者仍须执行资源收容、主动内容检查和现有泄漏扫描。
+
+无效清单、重复 ID、未知字段、非法链接及不支持的块会抛出 `TypeError`，不会返回部分产物。CLI 退出码和既有输出保留由后续唯一渲染入口处理。
+
+## 浏览器增强与降级
+
+不运行 JavaScript 时，正文、页面目录、章节链接及教程翻页都可用。手机目录采用原生 details；主题通过 CSS 跟随系统。无功能的按钮在初始 HTML 中隐藏，相关处理器安装后才显示。
+
+脚本提供本地搜索、复制、外观选择、移动目录和当前章节高亮。搜索索引从完整公开语义内容派生，包含代码、表格和图片替代说明；结果按标题命中优先，再按页面与章节顺序排列。搜索只使用页面内嵌数据，不联网。
+
+搜索支持方向键、回车、Escape 及中文输入法组合态保护。关闭模态窗口后恢复触发控件和阅读位置；正常页面跳转使用真实链接。外观偏好仅保存在浏览器本地，复制失败时提示手动复制，不虚报成功。
+
+## Markdown 接线与验证
+
+`markdown-v1` 使用精确依赖 `marked@18.0.11` 分词，再由本包的受限格式编译器生成上述内存对象。该对象是解析阶段到模板阶段的输入，不是另一份需要手工维护的内容源。新模式的项目只维护 Markdown 和允许的站内 SVG，不提供主题 CSS 或 JavaScript。
+
+目录访问、内容图片收集与安全检查、泄漏扫描、覆盖快照、基线和输出替换继续采用现有流程与 Foundation 能力。模板本身不包含这些机制，也没有另建 CLI、配置读取器或发布器。旧站点未声明 `format` 时继续走完整 HTML 兼容路径；只有显式 `markdown-v1` 与 `editorial` 才调用本模板。
+
+相邻测试位于 `test/editorial.test.mjs` 和 `test/markdown-v1.test.mjs`，虚构输入位于 `test/fixtures/editorial.mjs`。聚焦检查命令为：
+
+```sh
+node --test test/editorial.test.mjs test/markdown-v1.test.mjs
+```
+
+命令在渲染包目录、符合包内 `engines.node` 的运行时下执行。静态和输入测试不能代替浏览器的视觉、键盘及真实辅助技术验证。真实输入法、屏幕阅读器、跨应用粘贴和实际打印仍未完成设备验收。

package/templates/editorial/assets/mark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><rect x="1" y="1" width="38" height="38" rx="10" fill="#2f634c"/><path d="M12 12h11a5 5 0 0 1 5 5v12H17a5 5 0 0 1-5-5V12Z" fill="none" stroke="#f8faf6" stroke-width="1.5"/><path d="M17 12v17m4-12h3m-3 5h3" fill="none" stroke="#f8faf6" stroke-width="1.5" stroke-linecap="round"/></svg>