@geoly-ai/skills-hub 0.3.5 → 0.3.7

package/src/publish/github.mjs

@@ -0,0 +1,223 @@
+// `publish` 的 GitHub API 客户端 —— **这是 publish 唯一的出网口**。
+//
+// ── 🔴 为什么全走 API，一次 `git` 都不用 ────────────────────────────────────
+//
+// 带 token 的 `git push` 会让**本地** `pre-push` hook 拿到那个 token。
+// hook 是仓库里的普通可执行文件，`git` 无条件运行它 —— 于是「投稿一个 skill」
+// 变成了「把你的 GitHub 凭据交给一段任意代码」。
+// 这不是理论风险：投稿者的载荷目录常常就在某个 git 仓库里。
+//
+// ── 🔴 为什么是 Git Data API，不是 Contents API ───────────────────────────
+//
+// Contents API **没有设置 mode 的字段** —— 一个 `0755` 的文件会被写成 `0644`。
+// 而 mode **进 `tree_digest`**（`src/tree-digest.mjs`：mode 是每个叶子的编码的一部分，
+// 同字节不同 mode 算出来是两个不同摘要），也进 capability 语义
+// （`structural-gates.executableEvidence` 看的就是可执行位）。
+// 所以用 Contents API 投稿，等于**静默地改掉制品身份**。
+//
+// 另外 Contents API 每个文件一次 commit：中途失败会在 fork 上留下**半棵可见的
+// 投稿树**，而我们的策略是「同名分支只读、不自动改写」—— 那棵半成品就没人能收拾了。
+// Git Data API 的顺序是 blob → tree → commit → **最后一次性建 ref**：
+// 失败只留下不可见的 orphan object，仓库上什么都看不见。
+
+import { TokenError, scrub } from './token.mjs';
+
+/** 🔴 API host 固定。不从任何输入取，不支持 GHE。 */
+export const API_ORIGIN = 'https://api.github.com';
+/** 🔴 上游固定。不是参数。 */
+export const UPSTREAM_OWNER = 'geoly-ai';
+export const UPSTREAM_REPO = 'skills-hub';
+export const UPSTREAM_FULL = `${UPSTREAM_OWNER}/${UPSTREAM_REPO}`;
+/** 🔴 base 分支固定。 */
+export const BASE_BRANCH = 'main';
+
+/** 网络类错误 → EXIT.NETWORK(6)。 */
+export class ApiNetworkError extends Error {
+  constructor(message, extra = {}) {
+    super(message); this.name = 'ApiNetworkError'; this.exitCode = 6; Object.assign(this, extra);
+  }
+}
+
+/**
+ * HTTP 层的失败。`status` 一定有；401/403 映射到 EXIT.AUTH(7)，其余到 EXIT.NETWORK(6)。
+ *
+ * 🔴 **401/403 绝不静默换下一个 token 来源重试**（见 `commands/publish.mjs`）：
+ *    那会让用户看到的身份与实际投稿身份不同 —— 而这条命令的全部风险都在身份上。
+ */
+export class ApiHttpError extends Error {
+  constructor(message, { status, method, path, docUrl = null } = {}) {
+    super(message);
+    this.name = 'ApiHttpError';
+    this.status = status;
+    this.method = method;
+    this.path = path;
+    this.docUrl = docUrl;
+    this.exitCode = (status === 401 || status === 403) ? 7 : 6;
+  }
+}
+
+/**
+ * 路径参数的转义。**每一段都转**，然后 URL 里绝不出现未转义的用户输入。
+ *
+ * ⚠️ `encodeURIComponent` 会把 `/` 转成 `%2F` —— 这正是我们要的：
+ *    一个叫 `a/b` 的分支名不该变成两层路径。调用方把**不该转义的**斜杠
+ *    写在模板字面量里，把**每一个变量**用这个函数包起来。
+ */
+export const seg = (s) => encodeURIComponent(String(s));
+
+/**
+ * 建客户端。
+ *
+ * @param {object} a
+ * @param {string} a.token
+ * @param {function} a.fetchImpl  🔴 **必填**。不给就抛 —— 见下。
+ * @param {string} a.userAgent
+ * @param {number} [a.timeoutMs]
+ */
+export function createClient({ token, fetchImpl, userAgent, timeoutMs = 30000 }) {
+  // 🔴 `fetchImpl` 必填、且**没有隐式回退到 globalThis.fetch**。
+  //    测试忘了注入时，回退版本会**真的出网**，而那次出网看起来像一次通过的测试。
+  //    这条命令会创建 fork、建分支、开 PR —— 一次意外出网就是一次真实的写操作。
+  //    调用方（`commands/publish.mjs`）显式传 `ctx.fetchImpl ?? globalThis.fetch`，
+  //    于是"用了真 fetch"是一个**写得出来的动作**，不是一个默认值。
+  if (typeof fetchImpl !== 'function') {
+    throw new ApiNetworkError('publish 的 GitHub 客户端必须显式拿到 fetch 实现（不接受隐式回退）');
+  }
+  if (typeof token !== 'string' || token === '') throw new TokenError('内部错误：客户端拿到空 token');
+
+  /**
+   * @param {'GET'|'POST'|'PATCH'} method
+   * @param {string} path  以 `/` 开头；**变量段必须已经过 `seg()`**
+   * @param {object} [o]
+   * @param {object} [o.body]
+   * @param {number[]} [o.okStatus]  允许的状态码；默认 2xx
+   * @param {number[]} [o.softStatus] 不抛错、原样返回的状态码（如 404 探测）
+   */
+  async function request(method, path, { body = undefined, softStatus = [] } = {}) {
+    const url = new URL(path, API_ORIGIN);
+    // 🔴 **构造完之后**再断言 origin。在拼接之前断言等于没断言：
+    //    `path` 若是 `https://evil.example/x`，`new URL` 会**整个换掉** origin。
+    //    这一条不是理论上的 —— 分支名、login 都进路径，而它们来自远端响应。
+    if (url.origin !== API_ORIGIN) {
+      throw new ApiNetworkError(`拒绝向 ${url.origin} 发请求 —— publish 的 API host 固定为 ${API_ORIGIN}`);
+    }
+
+    const headers = {
+      // 🔴 Authorization 只在这里出现一次，且这个对象**绝不进任何错误/日志**。
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+      'User-Agent': userAgent,
+    };
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+
+    const ac = new AbortController();
+    const t = setTimeout(() => ac.abort(), timeoutMs);
+    let res;
+    try {
+      res = await fetchImpl(url.href, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        // 🔴 `manual`，且下面对任何 3xx 都抛 —— **不跟随，一步都不跟**。
+        //    跟随会把 `Authorization` 带去一个我们没有断言过的 host。
+        //    `redirect:'error'` 也行，但 `manual` 让我们能把状态码报出来。
+        redirect: 'manual',
+        signal: ac.signal,
+      });
+    } catch (e) {
+      if (ac.signal.aborted) {
+        // 🔴 超时是**特殊的**：POST 可能已经在服务端生效了。
+        //    调用方必须先查询结果再决定是否重试 —— 所以这里把 `timedOut` 标出来。
+        throw new ApiNetworkError(
+          `${method} ${path} 超时（${timeoutMs} ms）—— 🔴 若这是一次写操作，`
+          + '它**可能已经生效**；请先查询结果再决定是否重试。',
+          { timedOut: true, method, path },
+        );
+      }
+      // undici 抛的永远是 `TypeError: fetch failed`，真因在 cause 上。
+      const cause = e?.cause?.code ?? e?.cause?.message ?? e?.message ?? '未知';
+      throw new ApiNetworkError(scrub(`${method} ${path} 失败：${cause}`, token), { method, path });
+    } finally {
+      clearTimeout(t);
+    }
+
+    // 🔴 3xx 一律抛。**同 host 的重定向也抛** —— GitHub 会对改过名的仓库发 301，
+    //    而"上游改名了"是一件必须让人看见的事，不是可以静默跟随的细节。
+    if (res.status >= 300 && res.status < 400) {
+      throw new ApiNetworkError(
+        `${method} ${path} 返回了 ${res.status} 重定向 —— 拒绝跟随。\n`
+        + '  🔴 跟随重定向会把 Authorization 头带去一个没被断言过的 host。\n'
+        + '  常见成因：上游仓库改过名。请核对 `geoly-ai/skills-hub` 是否仍然有效。',
+        { method, path },
+      );
+    }
+
+    const text = await res.text().catch(() => '');
+    let json = null;
+    if (text !== '') { try { json = JSON.parse(text); } catch { json = null; } }
+
+    if (res.ok || softStatus.includes(res.status)) {
+      return { status: res.status, json, headers: res.headers, ok: res.ok };
+    }
+
+    // 🔴 错误文案里**只**放 status / method / path / 响应体的 `message` 与 `documentation_url`。
+    //    不放 request headers，不放整个响应体（它可能回显了我们发过去的内容）。
+    //    再过一遍 `scrub` —— 那是最后一道，不是第一道。
+    const apiMsg = typeof json?.message === 'string' ? json.message : `HTTP ${res.status}`;
+    const errs = Array.isArray(json?.errors)
+      ? json.errors.map((x) => (typeof x?.message === 'string' ? x.message : x?.code)).filter(Boolean)
+      : [];
+    throw new ApiHttpError(
+      scrub(`${method} ${path} → ${res.status}：${apiMsg}${errs.length ? `（${errs.join('；')}）` : ''}`, token),
+      {
+        status: res.status,
+        method,
+        path,
+        docUrl: typeof json?.documentation_url === 'string' ? json.documentation_url : null,
+      },
+    );
+  }
+
+  return {
+    request,
+    get: (p, o) => request('GET', p, o),
+    post: (p, body, o) => request('POST', p, { ...o, body }),
+  };
+}
+
+/**
+ * 分页取全部页。
+ *
+ * 🔴 `maxPages` 到顶时**不静默截断**：抛 `TruncatedError`，由调用方决定怎么说。
+ *    一个"取了前 3 页就当作全部"的重复检测，正是那种「看起来在查、其实查不全」的门。
+ */
+export class TruncatedError extends Error {
+  constructor(message, extra = {}) {
+    super(message); this.name = 'TruncatedError'; this.exitCode = 6; Object.assign(this, extra);
+  }
+}
+
+export async function getAllPages(client, pathWithoutPage, { perPage = 100, maxPages = 10 } = {}) {
+  const out = [];
+  const sepChar = pathWithoutPage.includes('?') ? '&' : '?';
+  for (let page = 1; page <= maxPages; page += 1) {
+    const r = await client.get(`${pathWithoutPage}${sepChar}per_page=${perPage}&page=${page}`);
+    // 🔴 200 但不是数组 → **抛**。把它当成空数组，等于把「响应形状不对」
+    //    翻译成「这一页什么都没有」，而后者会让"没有重复投稿"这个结论成立。
+    if (!Array.isArray(r.json)) {
+      throw new TruncatedError(
+        `${pathWithoutPage} 第 ${page} 页返回的不是数组 —— 拒绝把它当成"这一页是空的"`,
+        { path: pathWithoutPage, page },
+      );
+    }
+    const arr = r.json;
+    out.push(...arr);
+    if (arr.length < perPage) return out;
+  }
+  throw new TruncatedError(
+    `${pathWithoutPage} 的分页超过 ${maxPages} 页（每页 ${perPage}）—— 拒绝把"取了前 ${maxPages} 页"`
+    + '当成"全部"。',
+    { path: pathWithoutPage, maxPages, perPage, got: out.length },
+  );
+}

package/src/publish/payload.mjs

@@ -0,0 +1,241 @@
+// `publish` 的**本地**预检 —— 载荷冻结、暂存、跑既有的投稿门。
+//
+// ── 🔴 这一层是 UX，不是信任门 ────────────────────────────────────────────
+//
+// 真正的判定在服务端的 PR gate（`.github/workflows/validate-pr.yml` 从 **base**
+// 那棵树跑 `base-tools/scripts/submission/*`）。这里做的事只有一个目的：
+// **让投稿者在开 PR 之前就看到会红的地方**，而不是开完 PR 再被 CI 打回来。
+//
+// 因此本模块的纪律是：**一条自己的校验规则都不写。** 全部调 `scripts/submission/`
+// 与 `src/` 里现成的那几个。另写一套的结局只有两个 —— 「本地绿、CI 红」，
+// 或者两套规则各自演化然后分叉，而分叉点正好是绕过点（R-11 反复出现的形状）。
+
+import { readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { parseStrict } from '../canonical-json.mjs';
+import { parseArtifactId } from '../pack.mjs';
+import { collectTree } from '../packer.mjs';
+import { treeDigest } from '../tree-digest.mjs';
+import { createIsolatedDir, writeEntries } from '../artifact.mjs';
+import { runGates } from '../../scripts/submission/run-gates.mjs';
+import { scanTree, format as formatScan } from '../../scripts/submission/scan-text.mjs';
+import { assertArtifactPath } from '../untar.mjs';
+
+export class PayloadError extends Error {
+  /** 「你的投稿不合规」是**用法错误**，不是制品完整性问题 —— 09-cli.md §6。 */
+  constructor(message, extra = {}) {
+    super(message); this.name = 'PayloadError'; this.exitCode = 1; Object.assign(this, extra);
+  }
+}
+
+/** `submissions/<ns>/<name>@<ver>/`。**唯一**允许写的前缀。 */
+export const submissionPrefix = (ns, name, version) => `submissions/${ns}/${name}@${version}/`;
+
+/**
+ * 读 manifest，定 kind / namespace / name / version。
+ *
+ * 🔴 `skill.json` 与 `pack.json` **恰好有一个** —— 两个都在时「这是什么制品」
+ *    有两个答案，而下游每个校验器只读其中一个。这与 `run-gates.mjs` ③ 处
+ *    以及 `packer.packArtifact` 的判据是同一条，这里提前报，好让错误指向源目录
+ *    而不是暂存目录。
+ */
+export function readIdentity(payloadDir) {
+  const has = (f) => { try { return readFileSync(join(payloadDir, f), 'utf8'); } catch { return null; } };
+  const skill = has('skill.json');
+  const pack = has('pack.json');
+  if ((skill === null) === (pack === null)) {
+    throw new PayloadError(
+      `载荷根必须**恰好**有 skill.json 或 pack.json 其中一个`
+      + `（现在 skill.json=${skill !== null}、pack.json=${pack !== null}）——\n`
+      + '  两个都在时「这是什么制品」有两个答案；一个都没有时 publish 不知道该投什么。',
+    );
+  }
+  const kind = skill !== null ? 'skill' : 'pack';
+  let doc;
+  try {
+    // 🔴 `parseStrict` 不是 `JSON.parse`：11-wire-contract.md §2 要求拒绝重复 key。
+    //    `{"version":"1.0.0","version":"9.9.9"}` 在 JSON.parse 下静默取最后一个 ——
+    //    于是本地看到的版本与服务端看到的可以不是同一个。
+    doc = parseStrict(kind === 'skill' ? skill : pack);
+  } catch (e) {
+    throw new PayloadError(`${kind}.json 解析失败：${e.message}`);
+  }
+  for (const k of ['namespace', 'name', 'version']) {
+    if (typeof doc[k] !== 'string' || doc[k] === '') {
+      throw new PayloadError(`${kind}.json 缺少字符串字段 ${k} —— publish 靠它决定投到哪个路径。`);
+    }
+  }
+  // 🔴🔴 **ns / name / version 的 grammar 必须在这里就钉死**，而且要用**共享**的
+  //    那一份（`pack.parseArtifactId` = 01-artifacts.md §3 的 RE_NAMESPACE /
+  //    RE_NAME + 禁 `+build` 的 semver）。
+  //
+  //    为什么这条不是可有可无的整洁：这三个字段是**投稿者完全可控**的，而它们
+  //    接下来会走进
+  //      · 仓库路径前缀 `submissions/<ns>/<name>@<ver>/`
+  //      · **分支名**，而分支名会被拼进我们自己发出去的 API URL。
+  //    一个 `version: "1.0.0?x="` 或 `"1.0.0#y"` 经 `encodeURI` **不会**被转义
+  //    （`?` `#` `&` 都是 encodeURI 的保留字符），于是它能往我们的请求里注入
+  //    query / fragment —— 那是一次实打实的请求伪造，而载荷里每个文件的相对
+  //    路径看起来都完全正常。
+  //    ⚠️ 光靠"路径逐段校验"抓不到它：`?` 与 `#` 在路径里是合法字符。
+  let parsed;
+  try {
+    parsed = parseArtifactId(`${kind}:${doc.namespace}/${doc.name}@${doc.version}`, `${kind}.json`);
+  } catch (e) {
+    throw new PayloadError(
+      `${kind}.json 的 namespace / name / version 不合 grammar（01-artifacts.md §3）：${e.message}`,
+    );
+  }
+  return {
+    kind, namespace: parsed.namespace, name: parsed.name, version: parsed.version,
+    manifest: doc, id: parsed.id,
+  };
+}
+
+/**
+ * 目标仓库路径的逐段校验。
+ *
+ * 🔴 **`collectTree` 已经对载荷内的相对路径跑过 `assertArtifactPath` 了，
+ *    这里查的是别的东西**：拼接之后的**完整仓库相对路径**。
+ *    namespace / name / version 来自 manifest（投稿者完全可控），它们没经过
+ *    载荷路径的 grammar —— 一个 `version: "../../.github"` 会让前缀跑出
+ *    `submissions/` 之外，而载荷里每个文件的相对路径看起来都完全正常。
+ *
+ * 🔴 百分号解码这一格：GitHub 的 tree API 收的是**字面路径**，不做 URL 解码，
+ *    所以 `%2F` 在 git 里就是三个普通字符、不构成目录分隔。但我们仍然拒 ——
+ *    理由不是 git 会误解，而是**下游会**：PR 页面、workflow 里的 shell、
+ *    `git diff --name-only` 的消费者各自有各自的解码习惯，而路径白名单是按
+ *    前缀字符串判的。一个解码后含 `/` 的段，是在给"这条路径到底是几层"留两个答案。
+ */
+export function assertRepoPath(repoPath, { prefix }) {
+  if (!repoPath.startsWith(prefix)) {
+    throw new PayloadError(`路径 ${JSON.stringify(repoPath)} 不在允许的前缀 ${prefix} 之下`);
+  }
+  const segs = repoPath.split('/');
+  for (const s of segs) {
+    if (s === '') throw new PayloadError(`路径 ${JSON.stringify(repoPath)} 含空段（前导/尾随/连续斜杠）`);
+    if (s === '.' || s === '..') throw new PayloadError(`路径 ${JSON.stringify(repoPath)} 含 ${JSON.stringify(s)} 段`);
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1f\x7f]/.test(s)) throw new PayloadError(`路径 ${JSON.stringify(repoPath)} 含控制字符`);
+    if (s.includes('\\')) throw new PayloadError(`路径 ${JSON.stringify(repoPath)} 含反斜杠`);
+    let decoded;
+    try {
+      decoded = decodeURIComponent(s);
+    } catch {
+      // 🔴 解不开也**拒**，不是"用原样继续查"。一个含 `%` 却不是合法转义的段
+      //    （`%zz`、`%e0%a4`）在不同消费者手里会得到不同结果，而这道门的全部
+      //    意义就是不留"两个答案"。
+      throw new PayloadError(
+        `路径段 ${JSON.stringify(s)} 含无法解码的百分号转义 —— 拒绝。`,
+      );
+    }
+    if (decoded.includes('/') || decoded.includes('\\') || decoded === '..') {
+      throw new PayloadError(
+        `路径段 ${JSON.stringify(s)} 百分号解码之后是 ${JSON.stringify(decoded)} —— 拒绝。\n`
+        + '  🔴 一条解码后含分隔符的路径段，是在给「这条路径到底是几层」留两个答案，\n'
+        + '     而下游的路径白名单是按前缀字符串判的。',
+      );
+    }
+  }
+  if (repoPath.startsWith('/')) throw new PayloadError(`路径 ${JSON.stringify(repoPath)} 是绝对路径`);
+  return true;
+}
+
+/**
+ * 冻结载荷 → 暂存成 `submissions/<ns>/<name>@<ver>/` → 跑既有的门。
+ *
+ * 🔴 **只读一次盘。** `collectTree` 的产物（path/mode/data）就是我们**唯一**的
+ *    那份字节；之后算摘要、跑门、传 blob 全用它。
+ *    直接在源目录上算摘要、然后再从源目录读一次去上传，是两次读 ——
+ *    两次之间源文件被改（编辑器保存、另一个进程在跑），产出的 `tree_digest`
+ *    与实际上传的字节就是两棵树，而这要到安装端重算摘要时才会被发现。
+ *
+ * @param {object} [o]
+ * @param {function} [o.afterFreeze]
+ *   🔴 **测试注入点，生产路径永远不传。** 在载荷冻结（`collectTree` 返回）之后、
+ *   算摘要之前调用一次。它存在的唯一理由是：让「冻结之后源目录再怎么变都影响不到
+ *   我们要上传的那份字节」这条**可以被测试证明**，而不是只能靠读代码相信。
+ *   没有它的话，「摘要从暂存树算」与「摘要从源目录算」这两种写法在所有正常输入下
+ *   结果相同 —— 于是把它改坏也不会有任何测试变红（Codex 2026-09-05 指出，
+ *   我当时误判成"等价变异"）。
+ *
+ * @returns {{entries, treeDigest, prefix, files, gateProblems, scanLines, staging}}
+ */
+export function stagePayload(payloadDir, identity, { parent = undefined, afterFreeze = null } = {}) {
+  const entries = collectTree(payloadDir);          // ← 唯一一次读盘
+  const prefix = submissionPrefix(identity.namespace, identity.name, identity.version);
+
+  // 前缀本身要先过一遍：ns/name/version 是投稿者可控的
+  for (const s of prefix.slice(0, -1).split('/')) {
+    if (s === '' || s === '.' || s === '..') {
+      throw new PayloadError(
+        `投稿目录前缀 ${JSON.stringify(prefix)} 不合法 —— 它由 manifest 的 `
+        + 'namespace / name / version 拼成，请检查这三个字段。',
+      );
+    }
+  }
+
+  const files = entries.map((e) => {
+    const repoPath = prefix + e.path;
+    assertRepoPath(repoPath, { prefix });
+    // 载荷内相对路径的 grammar 再跑一遍（`collectTree` 跑过；这里是纵深，
+    // 且它覆盖的是"我们即将发出去的那个字符串"，不是"我们读进来的那个"）。
+    assertArtifactPath(e.path, `publish:${repoPath}`);
+    return { repoPath, relPath: e.path, mode: e.mode, data: e.data };
+  });
+
+  // 🔴 冻结完成。从这里往下**再也不碰 `payloadDir`** —— 摘要、门、上传全用
+  //    上面那份 `entries`。测试用 `afterFreeze` 在这一刻改动源目录来证明这一点。
+  if (typeof afterFreeze === 'function') afterFreeze();
+
+  // 暂存：把**这份字节**写成一棵真的 `submissions/` 树，然后让现成的门去跑它。
+  const staging = createIsolatedDir(parent);
+  try {
+    writeEntries(staging, files.map((f) => ({ path: f.repoPath, mode: f.mode, data: f.data })));
+  } catch (e) {
+    rmSync(staging, { recursive: true, force: true });
+    throw e;
+  }
+  return {
+    entries, files, prefix, staging,
+    payloadDir: join(staging, prefix.slice(0, -1)),
+    // 🔴 摘要算的是**暂存树**（= 我们即将上传的那棵），不是源目录。
+    //    与 `packer.packDirectory` 同一条纪律：判据必须落在我们手上的那份字节上。
+    treeDigest: treeDigest(join(staging, prefix.slice(0, -1))),
+  };
+}
+
+/**
+ * 跑既有的结构门 + 字符扫描。**一条规则都不在这里写。**
+ *
+ * @param {object} a
+ * @param {string} a.staging          `stagePayload` 的暂存根（里面是 `submissions/…`）
+ * @param {object} a.baseline         从上游 base 树派生的事实（见 `remote.mjs`）
+ * @returns {{problems:string[], scanLines:string[], scanErrors:number}}
+ */
+export function runLocalGates({ staging, baseline }) {
+  const { checked, problems } = runGates({
+    submissionsRoot: join(staging, 'submissions'),
+    reserved: baseline.reserved,
+    existingIds: baseline.existingIds,
+    existingNamesByNs: baseline.existingNamesByNs,
+    registeredNamespaces: baseline.registeredNamespaces,
+    // 🔴 **恒为 false**：「是不是维护者」是 PR 侧的事实，本地无从证明。
+    //    传 true 会让保留 namespace 在本地被放行、然后在 CI 上被拒 ——
+    //    正是「本地绿、CI 红」。fail-closed 与服务端默认值一致。
+    byMaintainer: false,
+  });
+  if (checked !== 1) {
+    throw new PayloadError(`内部错误：暂存树里应当恰好有 1 个投稿，实际 ${checked} 个`);
+  }
+  const scan = scanTree(join(staging, 'submissions'));
+  return {
+    problems,
+    scanLines: formatScan(scan),
+    // 🔴 `forbidden` 是**服务端会拒**的那一档（不可见字符 / bidi / symlink）；
+    //    `suspicious` / `mixedScript` / `compatibility` 只是要人看一眼。
+    //    两者分开数，不要混成一个"有几条告警"。
+    scanErrors: scan.forbidden.length,
+  };
+}