@geoly-ai/skills-hub 0.3.5 → 0.3.7

package/scripts/submission/structural-gates.mjs

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+// 投稿的结构门（§6 那张表里**尚无实现**的那几条）—— 06-submission.md §6。
+//
+// 🔴 **只写还不存在的那几条。** §6 的表里大半已经有实现了，本模块不重写它们：
+//   · 载荷规则（文件类型 / mode / 上限 / 无 PAX 扩展头）→ `packer.collectTree` + `packEntries`
+//   · 六（七）项绑定                                    → `artifact.assertManifestBinding`
+//   · 路径 grammar                                      → `untar` / `safe-fs` 的 parseSafeRelPath
+//   · pack lock / pack 兼容性                            → `pack.resolvePackInstall` / `checkPackCompat`
+//   · namespace 所有权                                   → `promote/build-inputs.resolveOwner`
+//   同一个不变量有两个校验器，就是 R-11 反复出现的形状。
+//
+// 本模块新写四条：
+//   ① 保留 **namespace**（`registry/reserved.json`；05-lifecycle.md §1.1）
+//   ② 归一化重名（NFKC + 小写 + 去连字符，**同 namespace 内**）
+//   ③ 版本未占用（**含已 yank** —— 制品不可变，yank 不释放版本号）
+//   ④ capability 一致性（声明 `none` 却含 `0755` / 脚本 → 拒；外部 URL → **只告警**）
+
+import { readFileSync, existsSync } from 'node:fs';
+
+import { parseStrict } from '../../src/canonical-json.mjs';
+
+export const RESERVED_SCHEMA = 'geoly.skills.reserved/1';
+
+class GateError extends Error {
+  constructor(code, msg) { super(msg); this.name = 'GateError'; this.code = code; }
+}
+const bad = (code, msg) => { throw new GateError(code, msg); };
+
+// ── ② 归一化重名 ───────────────────────────────────────────────────────────
+
+/**
+ * §6：「NFKC + 小写 + 去连字符后不与**同 namespace 内**已有 name 撞」。
+ *
+ * ⚠️ **诚实边界：今天只有「去连字符」这一步真的会触发。**
+ *    name 的 grammar 是 `[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?`（01-artifacts.md §3）
+ *    —— 全小写 ASCII。于是对任何**已经过 grammar 门**的名字：
+ *      · NFKC 是恒等变换（没有可归一化的兼容字符）；
+ *      · `toLowerCase()` 也是恒等变换。
+ *    三步照写是为了**grammar 将来放宽时这道门仍然正确**，不是因为它们现在有用。
+ *    `test/submission-gates.test.mjs` 里有一条断言钉住这个事实 ——
+ *    哪天 grammar 放宽了，那条断言会变，改的人就会看到这段说明。
+ */
+export function normalizeName(name) {
+  return name.normalize('NFKC').toLowerCase().split('-').join('');
+}
+
+/**
+ * @param {object} a
+ * @param {string} a.name        本次投稿的 name
+ * @param {string[]} a.existing  **同 namespace 内**已有的 name（含已 yank 的）
+ */
+export function assertNoNormalizedCollision({ name, existing }) {
+  const target = normalizeName(name);
+  const hit = existing.filter((e) => e !== name && normalizeName(e) === target);
+  if (hit.length) {
+    bad('E_NAME_COLLIDE',
+      `${name} 归一化后是 ${JSON.stringify(target)}，与同 namespace 内已有的 ${hit.join(', ')} 相撞。\n`
+      + '  §6：归一化重名一律拒绝 —— 两个只差连字符的名字，agent 的路由判定分不开，'
+      + '而人也看不出来。');
+  }
+  return true;
+}
+
+// ── ① 保留 namespace ───────────────────────────────────────────────────────
+
+// ── 同形折叠（confusable fold）—— **只服务于保留清单比对** ──────────────────
+//
+// 🔴 **为什么只在这一层。** `normalizeName` 那套（NFKC + 小写 + 去连字符）挡得住
+//    `GEOLY` / `ｇeoly` / `g-e-o-l-y`，却**挡不住数字替字母**：
+//    `ge0ly`、`geo1y`、`anthrop1c` 原来全部放行 —— 而防仿冒正是保留
+//    `anthropic` / `claude` / `openai` / `geoly` 的**全部理由**。
+//
+// 🔴 **攻击面是可枚举的，不是无底洞。** namespace 的 grammar 是
+//    `[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?`（01-artifacts.md §3）—— 攻击者手里
+//    **只有** a–z、0–9、连字符。连字符已被 `normalizeName` 去掉，非 ASCII 已被
+//    NFKC + grammar 拦在门外。于是残余的同形手段**只剩两类**：
+//      ① 数字冒充字母（`0`/`o`、`1`/`l`/`i`、`5`/`s` …）
+//      ② 小写 ASCII 字母冒充另一个字母或字母序列（`rn`/`m`、`vv`/`w`、`cl`/`d`）
+//    本模块把这两类都折掉，然后**全串相等**比对。
+//
+// ⚠️ **明确不覆盖的层（不要以为这道门是「防仿冒」的完备实现）：**
+//    · **子串 / 前后缀包含**：`geoly-ai`、`my-claude-helper`、`claudes` 一律放行。
+//      这是**有意的** —— `geoly-ai` / `prompts-map` / `plaud-theme` 已在
+//      `registry/owners.json` 里且有线上制品，包含式判定会当场把它们杀掉。
+//    · **编辑距离 / 模糊相似**：`anthropi`、`anthropicc`、`caludе`（转置）不管。
+//    · **语音相似**：`fasebook` 这一路不管。
+//    · 🔴 **`l`/`i` 之外的字母↔字母替换**：`qeoly`、`beoly`、`qithub`、`bithub`、
+//      `reqistry`、`githug` **全部放行**。这不是漏了，是**算过账之后不做**：
+//      要挡住它们就得把 `b`/`g`/`q` 并成一个字母等价类，而那立刻推出 `b ≡ g` ——
+//      正常名字 `hug` 当场被判成冒充 `hub`（Codex 2026-09-03 实测给的）。
+//      **数字**之所以能按歧义处理（`hu6` 拦、`hug` 放行），是因为「名字里出现数字」
+//      本身就是可用的信号；两个都是普通字母时没有这个信号，只能二选一。
+//      `l`/`i` 是唯一一对强到值得付这个代价的 —— 无衬线字体里它们**完全同形**。
+//    · **`li`→`h`、`ci`→`a`、`nn` 之外的更弱多字符对**：见下面 MULTI 的注释，
+//      逐条写了为什么不做。
+//    真正兜住这些的是 §8 的人工门，不是这道结构门。
+
+/** 小写 ASCII 里真正的**字母↔字母**同形对。`l` 与 `i` 归一到 `i`。 */
+const LETTER_CLASS = { l: 'i' };
+
+/**
+ * 数字 → 它能冒充的字母。**只有一个候选的**在折叠时就地替换掉。
+ * 🔴 `6` 与 `9` 有**两个**候选（`6` 既像 `b` 又像 `g`，`9` 既像 `g` 又像 `q`），
+ *    **不能**把它们并进同一个等价类 —— 那会让 `b ≡ g`，于是 `hug` 被判成
+ *    冒充 `hub`（Codex 2026-09-03 给的误伤例）。它们**原样保留**，
+ *    在 `confusableEquals` 里按「候选集合有交集」逐位判 —— 那个关系
+ *    **故意不是传递的**：`b ~ 6 ~ g` 但 `b ≁ g`。
+ *    因为比对永远是「候选 vs 保留名」的单向两两比，不传递不构成问题。
+ */
+const DIGIT_SOLE = { 0: 'o', 1: 'i', 2: 'z', 3: 'e', 4: 'a', 5: 's', 7: 't', 8: 'b' };
+const DIGIT_AMBIG = { 6: ['b', 'g'], 9: ['g', 'q'] };
+
+/**
+ * 多字符同形对。**在单字符折叠之后**施加，且模式写的是**折叠后的字母表**。
+ *
+ * 🔴 顺序是判据的一部分，不是实现细节。Codex 2026-09-03 指出：若按
+ *    「先多字符、后单字符」，`cl`→`d` 只认字面 `cl`，而 `l` 又会折成 `i` ——
+ *    于是 `claude`→`daude` 但 `c1aude`→`ciaude`，**等价关系不闭包，`c1aude` 直接绕过**。
+ *    改成「先单字符、后多字符 + 模式用折叠后字母」就由构造保证闭包：
+ *    `cl` / `c1` / `ci` 都先变成 `ci`，再统一折成 `d`。
+ *
+ * 🔴 四条规则的**首字符两两不同**（r / n / v / c），所以同一位置最多命中一条 ——
+ *    不存在「贪心顺序依赖」这种可被利用的非合流。输出字符（m / w / d）也都不是
+ *    任何规则的首字符或次字符，所以**单趟左到右扫描就是不动点**。有测试钉住这两条。
+ *
+ * ⚠️ 没做的：`li`→`h`（会把 `liub` 判成 `hub`，而那可能是正常名字）、
+ *    `ci`→`a`（与这里的 `ci`→`d` 直接冲突，二选一）、`vv` 之外的 `w` 变体。
+ */
+const MULTI = [['rn', 'm'], ['nn', 'm'], ['vv', 'w'], ['ci', 'd']];
+
+/**
+ * 把名字折成「同形规范形」。结果里可能仍留有 `6` / `9` —— 它们是**歧义占位符**，
+ * 由 `confusableEquals` 处理，见 `DIGIT_AMBIG`。
+ */
+export function foldConfusables(name) {
+  let s = '';
+  for (const ch of normalizeName(name)) s += LETTER_CLASS[ch] ?? DIGIT_SOLE[ch] ?? ch;
+  let out = '';
+  for (let i = 0; i < s.length;) {
+    const rule = MULTI.find(([pat]) => s.startsWith(pat, i));
+    if (rule) { out += rule[1]; i += rule[0].length; } else { out += s[i]; i += 1; }
+  }
+  return out;
+}
+
+/** 一个折叠后字符能代表的字母集合。 */
+const charAlts = (c) => DIGIT_AMBIG[c] ?? [c];
+
+/** 两个**已折叠**的名字是否同形。⚠️ 故意不传递，见 `DIGIT_AMBIG`。 */
+export function confusableEquals(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) {
+    if (!charAlts(a[i]).some((x) => charAlts(b[i]).includes(x))) return false;
+  }
+  return true;
+}
+
+/**
+ * 🔴 **保留清单管的是 `namespace`，不是制品 `name`。**
+ *    05-lifecycle.md §1.1：「以下 **namespace** 只能由 hub 维护者使用：
+ *    `geoly`、`hub`、`official`、`skills`、`registry`、`anthropic`、`claude`、
+ *    `cursor`、`codex`、`openai`、`github`、`npm`、`system`、`admin`、`security`、
+ *    `test`、`example`、`local`」。
+ *
+ *    ⚠️ 第一版我按 `name` 查（Codex 2026-08-31 指出）—— 那道门等于没设：
+ *    一个 `namespace: geoly` 的投稿会**直接放行**，而那正是它要拦的东西。
+ *
+ * 🔴 而且它**不是**一刀切禁用：维护者可以用。所以判据是
+ *    「保留 namespace **且** 投稿者不是维护者」。「是不是维护者」是 PR 侧的事实，
+ *    由调用方传进来 —— 同 `promote/build-inputs.mjs` 的分工。
+ */
+export function readReserved(path) {
+  if (!existsSync(path)) return { schema: RESERVED_SCHEMA, namespaces: [] };
+  // 🔴 用 `parseStrict` 不用 `JSON.parse`：11-wire-contract.md §1 把
+  //    `registry/reserved.json` 列进了适用对象，而 §2 的解析规则要求**拒绝重复 key**。
+  //    `JSON.parse` 对重复 key 静默取最后一个 —— `{"namespaces":[…],"namespaces":[]}`
+  //    就能把整张保留清单清空，而文件看起来完全正常（Codex 2026-08-31）。
+  const doc = parseStrict(readFileSync(path, 'utf8'));
+  if (doc.schema !== RESERVED_SCHEMA) {
+    bad('E_RESERVED_SCHEMA', `reserved.json 的 schema 应为 ${RESERVED_SCHEMA}，得到 ${JSON.stringify(doc.schema)}`);
+  }
+  if (!Array.isArray(doc.namespaces) || doc.namespaces.some((n) => typeof n !== 'string')) {
+    bad('E_RESERVED_SCHEMA', 'reserved.json.namespaces 必须是字符串数组');
+  }
+  // 🔴 **同形折叠必须在保留清单内部保持单射 —— 否则 fail-closed**（Codex 2026-09-03）。
+  //    这是给「折叠表将来被放宽」准备的告警器：哪天有人往 `LETTER_CLASS` / `MULTI` 里
+  //    加一条，把两个**本来互不相同的真实单词**折到一起了，这里会当场红 ——
+  //    而不是等到某个正常投稿被莫名其妙判成仿冒才发现。
+  const folds = doc.namespaces.map((n) => ({ n, f: foldConfusables(n) }));
+  for (let i = 0; i < folds.length; i += 1) {
+    for (let j = i + 1; j < folds.length; j += 1) {
+      if (confusableEquals(folds[i].f, folds[j].f)) {
+        bad('E_RESERVED_AMBIGUOUS',
+          `保留清单内部自撞：${folds[i].n} 与 ${folds[j].n} 同形折叠后无法区分`
+          + `（${JSON.stringify(folds[i].f)} / ${JSON.stringify(folds[j].f)}）。\n`
+          + '  三种可能：① 其中一条是笔误；② 其中一条是**冗余别名**'
+          + '（如 `openai` 之外再列 `open-ai` —— 归一化后本就相同，直接删掉那条即可）；'
+          + '③ structural-gates.mjs 的折叠表放得太宽 —— 宽到能把两个正常单词合并，'
+          + '就一定会误伤正常投稿。');
+      }
+    }
+  }
+  return doc;
+}
+
+/**
+ * @param {object} a
+ * @param {string} a.namespace
+ * @param {object} a.reserved
+ * @param {boolean} a.byMaintainer  投稿者是不是 hub 维护者（PR 侧的事实）
+ */
+export function assertReservedNamespaceAllowed({ namespace, reserved, byMaintainer = false }) {
+  const target = normalizeName(namespace);
+  const hit = reserved.namespaces.filter((r) => normalizeName(r) === target);
+  // 🔴 归一化相等之外，再查一层**同形折叠**（`ge0ly` / `geo1y` / `anthrop1c`）——
+  //    见上面那段「攻击面是可枚举的」。折叠只用在**这一层**（与 18 条固定清单
+  //    比全串相等），**不用在 `assertNoNormalizedCollision`**：那边比的是
+  //    同 namespace 内的**开放集合**，折叠会让两个正常名字互撞，
+  //    且撞的对数随注册量二次增长，而它挡的不是仿冒、是「人和 agent 分不开」。
+  const folded = foldConfusables(namespace);
+  const lookalike = reserved.namespaces.filter(
+    (r) => !hit.includes(r) && confusableEquals(foldConfusables(r), folded),
+  );
+  if (hit.length === 0 && lookalike.length === 0) return true;
+  if (byMaintainer) return true;                    // §1.1：维护者可以用
+  if (hit.length) {
+    bad('E_RESERVED',
+      `namespace ${namespace} 命中保留清单（${hit.join(', ')}，归一化后相同）——`
+      + '05-lifecycle.md §1.1：这些 namespace 只能由 hub 维护者使用。');
+  }
+  bad('E_RESERVED',
+    `namespace ${namespace} 与保留 namespace ${lookalike.join(', ')} **同形**`
+    + `（数字/字母同形折叠后都是 ${JSON.stringify(folded)}）——`
+    + '05-lifecycle.md §1.1：这些 namespace 只能由 hub 维护者使用，'
+    + '而「数字替字母」正是保留它们要防的那种仿冒。\n'
+    + '  ⚠️ 这道门只比**全串**：名字里带数字本身没问题（`web3`、`s3`、`i18n` 都放行），'
+    + '包含保留词也没问题（`geoly-ai` 放行）—— 只有整个名字折叠后与保留名相同才拒。'
+    + '要是你确实不是在仿冒，换一个不会折叠到保留名上的写法即可。');
+}
+
+// ── ③ 版本未占用 ───────────────────────────────────────────────────────────
+
+/**
+ * §6：「semver 合法、**未占用**、无 `+build`」。§3 又特别写明「版本号在该
+ * `<ns>/<name>` 下**从未被使用过（含已 yank）**」。
+ *
+ * 🔴 **yank 不释放版本号。** 制品不可变（01-artifacts.md §1）：yank 只是标记
+ *    「别再用了」，文件仍在。放行重用等于让同一个 ArtifactId 指向两份不同的字节 ——
+ *    而 ArtifactId 是整个信任链的主键。
+ *
+ * @param {string} a.id            本次投稿的 ArtifactId
+ * @param {string[]} a.existingIds 已有的全部 ArtifactId（**含已 yank**）
+ */
+export function assertVersionUnused({ id, existingIds }) {
+  if (existingIds.includes(id)) {
+    bad('E_VERSION_TAKEN',
+      `${id} 已经存在 —— 版本号不可重用，**yank 也不释放它**（06-submission.md §3、01-artifacts.md §1）。\n`
+      + '  要改内容就发新版本。');
+  }
+  return true;
+}
+
+// ── ④ capability 一致性 ────────────────────────────────────────────────────
+
+/** 看起来像脚本的扩展名。**不是白名单，是启发式** —— 见下面的诚实边界。 */
+export const SCRIPT_EXT = /\.(sh|bash|zsh|py|rb|pl|js|mjs|cjs|ts|ps1)$/i;
+
+/**
+ * 载荷里**看得见的**可执行迹象：可执行位、脚本扩展名、shebang。
+ * 🔴 单独导出，因为 `tier-gate.mjs` 也要用它 —— 那里判的是
+ *    「审查等级能不能只信投稿者自己填的 capabilities」。
+ *    两处用同一条判据，不会分叉。
+ */
+export function executableEvidence(entries) {
+  const out = [];
+  for (const e of entries) {
+    if ((e.mode & 0o111) !== 0) { out.push(`${e.path}：mode 0${e.mode.toString(8)} 带可执行位`); continue; }
+    if (SCRIPT_EXT.test(e.path)) { out.push(`${e.path}：看起来是脚本（按扩展名）`); continue; }
+    if (e.data.toString('utf8').startsWith('#!')) out.push(`${e.path}：以 shebang 开头`);
+  }
+  return out;
+}
+/** `http://` / `https://`；不含 `https://` 出现在纯文本说明里的情况 —— 分不开，见下。 */
+const RE_EXTERNAL_URL = /\bhttps?:\/\/[^\s)"'<>]+/i;
+
+/**
+ * §6：「声明 `none` 却含 `0755` / 外部 URL / 脚本 → 拒绝」。
+ *
+ * ⚠️ **这条门天生是启发式的，不要把它当成安全保证。**
+ *    · `0755` 是**确定**信号：可执行位就是可执行位；
+ *    · 「脚本」按扩展名 + shebang 判 —— 一个没扩展名、没 shebang 的脚本躲得过去；
+ *    · 「外部 URL」最粗：一条指向文档的链接与一条「去这里取指令」在字节上没有区别。
+ *      §8 的人工门第 6 条（间接指令）才是真正处理它的地方，本门只能拦住最直白的。
+ *    🔴 **外部 URL 这一项只告警、不拒绝**，理由见下面 `warnings` 那段 ——
+ *    它是本模块唯一一处**偏离 §6 字面表述**的地方，已记进交付汇报。
+ *    漏报的代价由 §8 的人来兜。
+ *
+ * @param {string[]} a.capabilities
+ * @param {Array<{path:string, mode:number, data:Buffer}>} a.entries  packer.collectTree 的产物
+ */
+export function assertCapabilityConsistency({ capabilities, entries }) {
+  // 🔴 **先去重再比。** 早先写的是 `length === 1 && [0] === 'none'`，于是
+  //    `['none','none']` 会让 `declaredNone` 为假、整道门被跳过 —— 一个纯粹靠
+  //    写两遍就能绕过的门（Codex 2026-08-31）。schema 那边没有 uniqueItems。
+  const uniqCaps = Array.isArray(capabilities) ? [...new Set(capabilities)] : null;
+  const declaredNone = uniqCaps !== null && uniqCaps.length === 1 && uniqCaps[0] === 'none';
+  if (!declaredNone) return { checked: false, reason: '未声明 none，本门不适用' };
+
+  const problems = executableEvidence(entries);
+  const warnings = [];
+  for (const e of entries) {
+    const m = RE_EXTERNAL_URL.exec(e.data.toString('utf8'));
+    if (m) warnings.push(`${e.path}：含外部 URL ${m[0].slice(0, 60)}`);
+  }
+  if (warnings.length) {
+    // 🔴 **外部 URL 只告警，不拒绝** —— 这一条**偏离** §6 的字面表述，理由写在这里。
+    //    §6 把「外部 URL」与「0755 / 脚本」并列成拒绝条件，但两者性质不同：
+    //    `SKILL.md` 里放一条参考文档的链接**极其常见**，而「引用外部资料」
+    //    不等于「运行时访问外部网络」。按字面实现的话，几乎每个声明 `none` 的
+    //    正常 skill 都会被拒 —— 而逼人去掉链接、或改声明 `network`（那会错误地
+    //    抬高审查 Tier 与安装确认要求），两条出路都是错的（Codex 2026-08-31）。
+    //    ⚠️ 一道几乎总在报红的门，两周之内就会被关掉 —— 那时它一条都拦不住了。
+    //    真正处理它的是 §8 人工门第 6 条（间接指令：「引用外部文档，按那里说的做」）。
+    //    这条偏离已记进交付汇报，等规格侧确认。
+    for (const w of warnings) process.stderr.write(`⚠️ capability 一致性（仅告警）：${w}\n`);
+  }
+  if (problems.length) {
+    bad('E_CAPABILITY_INCONSISTENT',
+      `声明了 capabilities: ["none"]，但载荷里有：\n`
+      + problems.map((p) => `  · ${p}`).join('\n')
+      + '\n  §6：声明不实视为恶意投稿（§7 末段）。要么去掉，要么如实声明对应的 capability。');
+  }
+  return { checked: true, problems: [], warnings };
+}
+
+export { GateError };

package/src/artifact.mjs

@@ -181,7 +181,25 @@ export function verifyAndExtract({ bytes, record, parent = tmpdir() }) {
 
 const SKILL_MANIFEST_KEYS = {
   required: ['schema', 'kind', 'namespace', 'name', 'version', 'description', 'license',
-    'clients', 'capabilities', 'replaces', 'conflicts', 'provenance'],
+    'clients', 'capabilities', 'replaces', 'conflicts'],
+  // 🔴 **`provenance` 从必填改成可选**（2026-09-05 用户拍板）。
+  //
+  //    原因是它构成一个**时间循环**：`submitted_by_pr` 必须等于真实 PR 号，
+  //    而 PR 号只有开了 PR 才知道 —— 于是投稿者被要求在开 PR **之前**
+  //    写进一个开 PR 之后才存在的值。实际做法是「先开 PR → 回填 → 强推同一分支」，
+  //    而漏回填的投稿会**先进 main、再在 promote 卡死**。
+  //
+  //    ⚠️ 更能说明问题的是它与 `PROMOTION.json` **自相矛盾**：那边明确
+  //    **拒绝**投稿者声明 `author_github_id` / `submitted_by_pr`
+  //    （理由：投稿者只能声明只有他知道的事），而这边却要求他自己写同样两个字段。
+  //    同一个仓库里两套相反的规则 —— 我自己在两天里踩了它两次。
+  //
+  //    现在：缺省即由 promote 填（与 pack 一致）；**若投稿者写了，仍然逐字核对**
+  //    （`assertProvenanceMatchesPr`）—— 不静默改写，写错了要有人看见。
+  //
+  // 🔴 改成 optional 而不是删掉：已发布的 5 张快照里的制品**都带着这个字段**，
+  //    删掉会让它们验不过。可选是唯一向后兼容的形状。
+  optional: ['provenance'],
 };
 
 const PACK_MANIFEST_KEYS = {

package/src/cli.mjs

@@ -29,6 +29,12 @@ const HELP = `skills-hub —— geoly skill 分发（M1 + M2 的命令面）
                                      把 pack 与全部成员物化成一棵目录树（不走安装账本）
   update [<spec>…] | --all           重解析账本里的 root：展示 diff、确认后在一个事务里应用
   remove <name>                      减引用；🔴 **引用归零才删目录**（why <name> 看谁在要它）
+  publish [path] [--dry-run]         投稿：本地过一遍服务端那批门 → 建 fork → 开 PR
+                                     🔴 用你**已有**的 GitHub token（GEOLY_GITHUB_TOKEN /
+                                     GH_TOKEN / GITHUB_TOKEN / \`gh auth token\`），CLI
+                                     **不持有、不存储**它，也没有 login / logout。
+                                     动手前会把 token 的权限面摆给你看并要求确认 ——
+                                     \`--yes\` 只表示**确认了那个风险**，不跳过任何校验。
 
   stats [--json] [--export <file>]   本地埋点报表
   telemetry <status|flush>           埋点/上报开关与队列
@@ -46,9 +52,16 @@ const HELP = `skills-hub —— geoly skill 分发（M1 + M2 的命令面）
   --no-bundled / --pre / --json / --yes
   --yes-i-really-want-everything  仅 --all 在非交互下使用（--yes 不够）
   --keep-generations <N>      attic 保留代数，默认 3
+  --scan-max-depth <N>        嵌套 target 预检的扫描深度预算，默认 64（硬顶 1024）
+  --scan-max-dirs <N>         同上，目录数预算，默认 100000（硬顶 5000000）
+     报 target.nested-scan-incomplete 时，错误里会点名撞的是**哪一个**上限；
+     只有那一条说「深度上限到顶」/「目录数上限用尽」时抬这里才有用。
+     说「读不进去」的那种是权限问题，抬预算没有用。
 
-🔴 没有 --no-verify、--insecure、--force、--force-unlock、--assume-idle。
-   验签与摘要校验不可关闭；替换必须点名；陈旧/yank/全量各有独立开关。
+🔴 没有 --no-verify、--insecure、--force、--force-unlock、--assume-idle、
+   --skip-nested-scan。验签与摘要校验不可关闭；替换必须点名；
+   陈旧/yank/全量各有独立开关；扫描预算只能**抬高**，不能关掉 ——
+   关掉它就是把「无法证明没有嵌套 target」改写成「假设没有」（04-install.md §3.5）。
 
 埋点（docs/telemetry/00-spec.md）：
   🔴 上报**默认开**（有内置默认端点）。**install 成功收尾后**会静默发一次
@@ -76,6 +89,7 @@ const COMMANDS = {
   remove: () => import('./commands/remove.mjs').then((m) => m.cmdRemove),
   update: () => import('./commands/update.mjs').then((m) => m.cmdUpdate),
   vendor: () => import('./commands/vendor.mjs').then((m) => m.cmdVendor),
+  publish: () => import('./commands/publish.mjs').then((m) => m.cmdPublish),
 };
 
 /**

package/src/commands/context.mjs

@@ -16,6 +16,7 @@ import { homedir, platform } from 'node:os';
 import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, resolve as resolvePath } from 'node:path';
 import { UsageError, UnsupportedError } from '../exit-codes.mjs';
+import { SCAN_CEILINGS } from '../target.mjs';
 
 /** §2 那张表。`arg: true` = 后面跟一个值。 */
 const GLOBAL_FLAGS = Object.freeze({
@@ -31,6 +32,8 @@ const GLOBAL_FLAGS = Object.freeze({
   '--no-bundled': { arg: false },
   '--freeze-attic': { arg: true },
   '--keep-generations': { arg: true },
+  '--scan-max-depth': { arg: true },
+  '--scan-max-dirs': { arg: true },
   '--json': { arg: false },
   '--yes': { arg: false },
   '--yes-i-really-want-everything': { arg: false },
@@ -51,6 +54,12 @@ const REMOVED_FLAGS = Object.freeze({
   '--clear-lock': '同 --force-unlock：协议里没有任何 unlink，也就没有可清的东西（§5.1）。',
   '--assume-idle':
     '本工具**不检测也不阻断**正在运行的 agent（D5，04-install.md §9），所以没有可假设的东西。',
+  '--skip-nested-scan':
+    '嵌套 target 扫描**不能关闭**（04-install.md §3.5）。关掉它是把「无法证明没有嵌套」'
+    + '改写成「假设没有嵌套」，而外层替换会连内层的 .geoly/ 一起搬走、两把锁互不相识。\n'
+    + '扫描超预算时报错里会点名撞的是哪个上限：深度/目录数用 `--scan-max-depth <N>` / '
+    + '`--scan-max-dirs <N>` 抬高（仍然是真扫描、仍然 fail-closed）；'
+    + '说「读不进去」的那种是权限问题，抬预算没有用。',
   '--allow-pending':
     'Q12 是阻塞门，不是建议。要开某一格就补那一格的实测证据（docs/m1/01-residual-risks.md R-4）。',
 });
@@ -152,6 +161,18 @@ function applyGlobal(g, name, val) {
     case '--no-bundled': g.noBundled = true; break;
     case '--freeze-attic': g.freezeAttic = val; break;
     case '--keep-generations': g.keepGenerations = uintArg(name, val); break;
+    // 🔴 预检的**预算旋钮**，不是关闭开关。抬高它仍然是一次真扫描、仍然 fail-closed；
+    //    抬到硬顶还不够就照旧拒绝。故意**不提供** `--skip-nested-scan`：
+    //    那会把「无法证明没有嵌套」改成「假设没有嵌套」，正是 §3.5 要防的事
+    //    （同 REMOVED_FLAGS 里 --force / --no-verify 的理由）。
+    //    上界由 target.mjs 的 SCAN_CEILINGS 兜底，超了报错而不是静默截断。
+    //    🔴 硬顶要在**解析期**就拒，不能等到预检里才抛：那时 install 已经
+    //    建过 target/.geoly、取过锁，而 target.mjs 抛的是普通 Error ——
+    //    会被 classify 判成 unclassified（退出码 2「完整性失败」），
+    //    把一个「参数超上限」说成「制品坏了」。解析期拒 = 零磁盘副作用 + 退出码 1。
+    //    （target.mjs 里那道保留为纵深防御：库调用方不经过本文件。）
+    case '--scan-max-depth': g.scanMaxDepth = scanArg(name, val, 'maxDepth'); break;
+    case '--scan-max-dirs': g.scanMaxDirs = scanArg(name, val, 'maxDirs'); break;
     case '--json': g.json = true; break;
     case '--yes': g.yes = true; break;
     case '--yes-i-really-want-everything': g.yesEverything = true; break;
@@ -160,6 +181,22 @@ function applyGlobal(g, name, val) {
   }
 }
 
+/**
+ * 扫描预算旋钮：非负整数 **且** 不超过 `target.mjs` 的硬顶。
+ * 🔴 硬顶的**唯一出处**是 `SCAN_CEILINGS` —— 这里不复制一份数字，
+ *    复制的那份迟早会跟本体漂。
+ */
+function scanArg(name, val, key) {
+  const n = uintArg(name, val);
+  if (n > SCAN_CEILINGS[key]) {
+    throw new UsageError(
+      `${name} 超过硬顶 ${SCAN_CEILINGS[key]}（收到 ${n}）。`
+      + '预算旋钮不是关闭开关：无上限的遍历等于没有资源闸（04-install.md §3.5.1）。',
+    );
+  }
+  return n;
+}
+
 /** 11-wire-contract.md §2：数字只允许非负整数，不允许前导零、浮点、指数、`-0`。 */
 export function uintArg(name, val) {
   if (!/^(0|[1-9]\d*)$/.test(val)) {
@@ -263,6 +300,14 @@ export function makeContext(globals, deps = {}) {
      *    照样可读，但那不是「用户正坐在终端前逐条看名单」。
      */
     stdin: deps.stdin ?? process.stdin,
+    /**
+     * 预检的扫描预算，直接喂给 `precheckTarget({ scan })`。
+     * 🔴 没给旋钮时这两项是 `undefined` —— `normalizeScan` 把 `undefined` 读成
+     *    「用默认值」。**不要**在这里填上默认值：填了以后默认值就有了两个出处
+     *    （这里一份、target.mjs 一份），改一处漏一处的那种漂移正好发生在
+     *    「上限是多少」这个用户会照着报错去调的数上。
+     */
+    scan: Object.freeze({ maxDepth: globals.scanMaxDepth, maxDirs: globals.scanMaxDirs }),
   });
   return ctx;
 }

package/src/commands/install.mjs

@@ -684,7 +684,13 @@ export async function cmdInstall(ctx, argv, out) {
         const t = byPath.get(o.path);
         const started = Date.now();
         try {
-          const r = installOneTarget(ctx, t, perClient.get(t.client), { snap, floor, pinned, out, verifier });
+          const r = installOneTarget(ctx, t, perClient.get(t.client), {
+            snap, floor, pinned, out, verifier,
+            // 🔴 §3.5 识别范围 ① 是「本次命令的**全部** target」，不是「自己」。
+            //    只传自己会漏掉「两个 target 互相嵌套、但内层还没有 .geoly 状态」——
+            //    那正是首次安装时的形状（内层的状态目录还没建出来）。
+            targetSet: selected.map((s) => s.target),
+          });
           results.push({
             ...r, client: t.client, scope: t.scope, target: t.target, ok: true, ms: Date.now() - started,
           });
@@ -754,7 +760,7 @@ export async function cmdInstall(ctx, argv, out) {
 }
 
 /** 单个 target 的第 2–10 步。 */
-function installOneTarget(ctx, t, { units, rootSpecs, packInfos }, { snap, floor, out, verifier }) {
+function installOneTarget(ctx, t, { units, rootSpecs, packInfos }, { snap, floor, out, verifier, targetSet }) {
   const target = t.target;
   const P0 = layout(target);
   const onLedgerChanged = makeLockfileHook(ctx, { snap, verifier });
@@ -764,7 +770,11 @@ function installOneTarget(ctx, t, { units, rootSpecs, packInfos }, { snap, floor
   if (rec.outcome !== 'nothing') out.note(`${t.client}：入口分流 —— ${rec.outcome}`);
 
   // ── 第 3 步：预检（🔴 assertPrecheckOk 必须调）─────────────────────────
-  const pre = precheckTarget(target, { base: t.base, targetSet: [target] });
+  const pre = precheckTarget(target, {
+    base: t.base,
+    targetSet: targetSet ?? [target],
+    scan: ctx.scan,
+  });
   assertPrecheckOk(pre);
 
   // ── 第 4 步：取字节 → 验签/验资产/解包/manifest 绑定 ────────────────────

package/src/commands/output.mjs

@@ -116,8 +116,14 @@ export class Output {
         message,
         unclassified: cls.unclassified,
         // 预检聚合错带全部违规项 —— 🔴 JSON 里**始终保留全部**，不只报优先级最高那条
+        // 🔴 `detail` 必须一起出：它是**给机器读的那一半**（嵌套 target 的 relation/via、
+        //    扫描没跑完时撞的是哪个上限、实际值、样例路径）。只留 message 等于逼
+        //    调用方去正则解析中文文案 —— 那正是 `detail` 存在的理由。
+        //    ⚠️ 白名单式挑字段是对的，别改成整个 `...v` 透传。
         violations: Array.isArray(err?.violations)
-          ? err.violations.map((v) => ({ code: v.code, message: v.message, path: v.path }))
+          ? err.violations.map((v) => pruneUndefined({
+            code: v.code, message: v.message, path: v.path, detail: v.detail,
+          }))
           : undefined,
         candidates: Array.isArray(err?.candidates) ? err.candidates : undefined,
       }),