@geoly-ai/skills-hub 0.1.0

package/src/canonical-json.mjs

@@ -0,0 +1,147 @@
+// canonical JSON —— 规范见 docs/m0/11-wire-contract.md §3
+// CLI 与 CI 共用同一份实现（§11 要求）。
+
+const ESC = { '"': '\\"', '\\': '\\\\', '\b': '\\b', '\f': '\\f', '\n': '\\n', '\r': '\\r', '\t': '\\t' };
+
+/** 字符串按 §3.4：非 ASCII 一律 \uXXXX 小写 hex；BMP 外用代理对；未配对代理 → 抛错 */
+export function encodeString(str) {
+  let out = '"';
+  for (let i = 0; i < str.length; i++) {
+    const ch = str[i];
+    const code = str.charCodeAt(i);
+    if (ESC[ch]) { out += ESC[ch]; continue; }
+    if (code < 0x20) { out += '\\u' + code.toString(16).padStart(4, '0'); continue; }
+    if (code < 0x7f) { out += ch; continue; }
+    // 代理对完整性
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = str.charCodeAt(i + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) {
+        throw new Error(`canonical-json: 未配对的高位代理 at ${i}`);
+      }
+      out += '\\u' + code.toString(16).padStart(4, '0');
+      out += '\\u' + next.toString(16).padStart(4, '0');
+      i++; continue;
+    }
+    if (code >= 0xdc00 && code <= 0xdfff) {
+      throw new Error(`canonical-json: 未配对的低位代理 at ${i}`);
+    }
+    out += '\\u' + code.toString(16).padStart(4, '0');
+  }
+  return out + '"';
+}
+
+function keyOrder(a, b) {
+  // §3.1：schema 强制置首，其余按 UTF-8 字节序
+  if (a === 'schema') return -1;
+  if (b === 'schema') return 1;
+  const ba = Buffer.from(a, 'utf8'), bb = Buffer.from(b, 'utf8');
+  return Buffer.compare(ba, bb);
+}
+
+function enc(value, indent, path) {
+  const pad = '  '.repeat(indent), padIn = '  '.repeat(indent + 1);
+  if (value === null) return 'null';
+  const t = typeof value;
+  if (t === 'boolean') return value ? 'true' : 'false';
+  if (t === 'number') {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new Error(`canonical-json: ${path} 只允许 [0, 2^53-1] 的非负整数，得到 ${value}`);
+    }
+    return String(value);
+  }
+  if (t === 'string') return encodeString(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    const items = value.map((v, i) => padIn + enc(v, indent + 1, `${path}[${i}]`));
+    return '[\n' + items.join(',\n') + '\n' + pad + ']';
+  }
+  if (t === 'object') {
+    const keys = Object.keys(value).sort(keyOrder);
+    if (keys.length === 0) return '{}';
+    const items = keys.map(k => padIn + encodeString(k) + ': ' + enc(value[k], indent + 1, `${path}.${k}`));
+    return '{\n' + items.join(',\n') + '\n' + pad + '}';
+  }
+  throw new Error(`canonical-json: ${path} 不支持的类型 ${t}`);
+}
+
+/** canonical 序列化，结尾恰好一个 \n */
+export function stringify(value) { return enc(value, 0, '$') + '\n'; }
+
+/** canonical 字节 */
+export function toBytes(value) { return Buffer.from(stringify(value), 'utf8'); }
+
+/**
+ * 严格解析：拒绝重复 key。
+ * 标准 JSON.parse 会静默取最后一个 —— §3.2 要求报错。
+ */
+export function parseStrict(text) {
+  const result = JSON.parse(text);   // 先让它做语法校验
+  detectDuplicateKeys(text);
+  return result;
+}
+
+/**
+ * 🔴 把 JSON 字符串字面量解码成实际的 key。
+ *
+ * 重复 key 的判据必须是**解码后**的值：`{"a":1,"\u0061":2}` 里两个 key
+ * 都是 `a`，是重复的，但它们的原文完全不同。早先直接比原文，于是这种写法
+ * 被静默放行、JSON.parse 取最后一个 —— 一个可以用来绕过任何「按 key 校验」的口子。
+ *
+ * ⚠️ 这与埋点那次是同一类错误：**比较未归一化的形式**。
+ * 凡是「同一个东西有多种写法」的地方，比之前先归一。
+ */
+function decodeJsonString(raw) {
+  let out = '';
+  for (let i = 0; i < raw.length; i++) {
+    if (raw[i] !== '\\') { out += raw[i]; continue; }
+    const c = raw[++i];
+    switch (c) {
+      case '"': out += '"'; break;
+      case '\\': out += '\\'; break;
+      case '/': out += '/'; break;
+      case 'b': out += '\b'; break;
+      case 'f': out += '\f'; break;
+      case 'n': out += '\n'; break;
+      case 'r': out += '\r'; break;
+      case 't': out += '\t'; break;
+      case 'u':
+        out += String.fromCharCode(parseInt(raw.slice(i + 1, i + 5), 16));
+        i += 4;
+        break;
+      default: out += c;   // JSON.parse 已经验过语法，走不到这里
+    }
+  }
+  return out;
+}
+
+/** 独立扫描原文，发现同一对象内的重复 key（按**解码后**的 key 比对） */
+export function detectDuplicateKeys(text) {
+  const stack = [];
+  let i = 0;
+  const n = text.length;
+  while (i < n) {
+    const c = text[i];
+    if (c === '"') {
+      let j = i + 1, buf = '';
+      while (j < n) {
+        if (text[j] === '\\') { buf += text[j] + text[j + 1]; j += 2; continue; }
+        if (text[j] === '"') break;
+        buf += text[j]; j++;
+      }
+      i = j + 1;
+      // 跳过空白，看是不是 key（后面跟冒号）
+      let k = i; while (k < n && /\s/.test(text[k])) k++;
+      if (text[k] === ':' && stack.length && stack[stack.length - 1].type === 'obj') {
+        const top = stack[stack.length - 1];
+        const key = decodeJsonString(buf);
+        if (top.keys.has(key)) throw new Error(`canonical-json: 重复 key ${JSON.stringify(key)}`);
+        top.keys.add(key);
+      }
+      continue;
+    }
+    if (c === '{') { stack.push({ type: 'obj', keys: new Set() }); i++; continue; }
+    if (c === '[') { stack.push({ type: 'arr' }); i++; continue; }
+    if (c === '}' || c === ']') { stack.pop(); i++; continue; }
+    i++;
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,208 @@
+// 命令分发与顶层错误处理 —— 09-cli.md §1 / §2 / §6 / §7。
+//
+// 🔴 §7 的输出契约在这里兜底，不在各命令里各写一遍：
+//    `--json` 时 stdout **只有一个 JSON 对象** —— 成功、用法错误、解析失败、
+//    锁被占用、内部错误，**每一条路径都是**。只在成功路径上给对象，等于让脚本
+//    在失败时读到空 stdout 然后自己去猜。
+//
+// 🔴 `--offline` 在 `makeContext()` 里就置位（它要早于任何可能出网的代码求值），
+//    埋点上报继承这条边界（`telemetry.offline()` 读的是同一个变量）。
+
+import { acquire } from './lock.mjs';
+import { parseGlobals, makeContext } from './commands/context.mjs';
+import { Output } from './commands/output.mjs';
+import { createCacheRegistry } from './commands/registry.mjs';
+import { EXIT, classify, UsageError } from './exit-codes.mjs';
+
+const HELP = `skills-hub —— geoly skill 分发（M1）
+
+命令：
+  install <spec>…                    装制品（direct；pack 与 --all 在 M2）
+  list [--packs|--installed|--outdated]
+  search <kw>…
+  check                              两阶段校验（字节 / 现在还该不该用）
+  why <name>                         谁请求装的
+  sync-lock                          在 repo 锁下重算 geoly-skills.lock.json
+  recover [--continue|--rollback|--reinstall] [--from-generation N [--only x]…]
+          [--reset-generation N] [--resume-cleanup]
+
+  stats [--json] [--export <file>]   本地埋点报表
+  telemetry <status|flush>           埋点/上报开关与队列
+
+全局 flag（09-cli.md §2）：
+  --clients <list>            默认 = 本机已存在的全部；含未安装 client 是硬错误
+  --create-missing <client|all>
+  --project [path]            装到仓库内，维护 geoly-skills.lock.json
+  --shadow-global             全局已有同名时，项目级安装才允许继续
+  --snapshot <N>              钉快照复现
+  --offline                   只用缓存；未命中即失败。禁止一切网络出口
+  --allow-stale               timestamp 过期时才允许继续，输出持续标注 stale
+  --allow-yanked              仅取证；大声告警并写进账本（不放行 degraded）
+  --replace <name>            点名替换未被账本认领的同名目录
+  --no-bundled / --pre / --json / --yes
+  --keep-generations <N>      attic 保留代数，默认 3
+
+🔴 没有 --no-verify、--insecure、--force、--force-unlock、--assume-idle。
+   验签与摘要校验不可关闭；替换必须点名；陈旧/yank/全量各有独立开关。
+
+退出码（§6）：0 成功 · 1 用法 · 2 完整性 · 3 冲突 · 4 部分失败 · 5 需 recover/锁忙
+              6 网络 · 7 认证 · 8 陈旧 · 9 平台/文件系统 · 10 不可写 · 11 CLI 版本过低
+`;
+
+/** 需要完整运行时上下文（快照、锁、target）的命令。 */
+const COMMANDS = {
+  install: () => import('./commands/install.mjs').then((m) => m.cmdInstall),
+  list: () => import('./commands/query.mjs').then((m) => m.cmdList),
+  search: () => import('./commands/query.mjs').then((m) => m.cmdSearch),
+  why: () => import('./commands/query.mjs').then((m) => m.cmdWhy),
+  check: () => import('./commands/check.mjs').then((m) => m.cmdCheck),
+  'sync-lock': () => import('./commands/sync-lock.mjs').then((m) => m.cmdSyncLock),
+  recover: () => import('./commands/recover.mjs').then((m) => m.cmdRecover),
+};
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps]  🔴 **只有进程内的调用方给得了** —— argv 与环境变量都到不了这里。
+ *        生产入口 `bin/skills-hub.mjs` 一个 dep 都不传，所以生产路径上
+ *        验签器一定是真的、registry 一定是缓存适配器。
+ */
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+
+  // ── 内部探针（测试用；不进 --help） ──────────────────────────────────────
+  if (argv[0] === '--warn-probe') return warnProbe(stdout);
+  if (argv[0] === '--fault-probe') return faultProbe(stdout);
+
+  // 🔴 全局 flag 要**先**解析：`--json` 决定失败时怎么输出。
+  //    解析本身失败时只能按非 JSON 报 —— 那时我们还不知道用户要不要 JSON。
+  //    🔴 解析**本身**失败时也必须给 JSON —— 那时 `parseGlobals` 还没跑完，
+  //    所以先做一次廉价预扫。少了这一步，`--json` 下的用法错误会让 stdout 全空，
+  //    脚本读到 0 字节只能去猜。
+  let parsed;
+  const preJson = argv.includes('--json') || argv.includes('--json=true');
+  try {
+    parsed = parseGlobals(argv);
+  } catch (err) {
+    const plain = new Output({ json: preJson, stdout, stderr });
+    return plain.emitError(argv[0] ?? 'skills-hub', classify(err), err);
+  }
+  const { globals, rest } = parsed;
+  // 🔴 `--offline` 必须在**任何**可能出网的分流之前置位。
+  //    早先它只在 `makeContext()` 里置位，而 `telemetry flush` 走的是下面那条
+  //    不经过 makeContext 的捷径 —— 于是 `skills-hub --offline telemetry flush`
+  //    会照常 POST 出去（upload.flush 的一票否决读的正是这个变量）。
+  //    这是 §2「离线模式禁止任何网络出口」的**直接违反**，不是边角情况。
+  if (globals.offline) {
+    // 🔴 两个都要设，缺一不可：
+    //   · `deps.env`  —— ctx 与 adapter 读的是它；
+    //   · `process.env` —— **telemetry / upload 读的是它**（telemetry.offline()）。
+    //     只设注入的那个，`--offline` 就管不住上报 —— 而 `--offline` 承诺的是
+    //     「整个 CLI 不得有任何网络出口」，那是一条**进程级**保证。
+    // ⚠️ 这是**进程级且粘住**的：一个 CLI 进程只跑一条命令，
+    //    「置位之后不再撤销」正是「整个 CLI 不得有任何网络出口」该有的形状。
+    process.env.GEOLY_OFFLINE = '1';
+    if (deps.env && deps.env !== process.env) deps.env.GEOLY_OFFLINE = '1';
+  }
+  const out = new Output({ json: globals.json, stdout, stderr });
+  const cmd = rest[0];
+
+  if (cmd === undefined || cmd === '-h' || cmd === '--help' || cmd === 'help') {
+    if (globals.json) return out.emit('help', { help: HELP }, EXIT.OK);
+    stdout.write(HELP);
+    return EXIT.OK;
+  }
+
+  // 埋点两个子命令是纯本地的，不需要快照/锁/target
+  if (cmd === 'stats') return cmdStats(rest.slice(1), globals, stdout, stderr);
+  if (cmd === 'telemetry') return cmdTelemetry(rest.slice(1), stdout, stderr);
+
+  const load = COMMANDS[cmd];
+  if (!load) {
+    const err = new UsageError(`未知命令：${cmd}\n可用：${Object.keys(COMMANDS).sort().join(' / ')}`);
+    return out.emitError(cmd, classify(err), err);
+  }
+
+  try {
+    const base = makeContext(globals, deps);
+    const registry = base.registryFactory
+      ? base.registryFactory({ cacheDir: base.cacheDir, offline: base.offline })
+      : createCacheRegistry({ cacheDir: base.cacheDir, offline: base.offline });
+    const record = base.record ?? (await import('./telemetry.mjs')).record;
+    const ctx = Object.freeze({ ...base, record, registry });
+    const run = await load();
+    return await run(ctx, rest.slice(1), out);
+  } catch (err) {
+    const cls = classify(err);
+    return out.emitError(cmd, cls, err);
+  }
+}
+
+// ── 内部探针 ─────────────────────────────────────────────────────────────────
+
+async function warnProbe(stdout) {
+  const { mkdtempSync } = await import('node:fs');
+  const { tmpdir } = await import('node:os');
+  const { join } = await import('node:path');
+  acquire(join(mkdtempSync(join(tmpdir(), 'probe-')), 'l.db'))();
+  stdout.write('PROBE_OK\n');
+  return EXIT.OK;
+}
+
+async function faultProbe(stdout) {
+  const fi = await import('./fault-inject.mjs');
+  const leaked = Object.keys(process.env).filter((k) => k.startsWith('GEOLY_FAULT'));
+  const s = fi.state();
+  stdout.write(`leaked=${leaked.join(',')} locked=${s.LOCKED} armed=${s.ARMED} active=${s.ACTIVE}\n`);
+  return EXIT.OK;
+}
+
+// ── 埋点子命令（M0 命令面之外，保留原有行为） ───────────────────────────────
+
+async function cmdStats(args, globals, stdout, stderr) {
+  const { stats, textReport } = await import('./stats.mjs');
+  const { exportJson } = await import('./telemetry.mjs');
+  const { agg, events } = stats();
+
+  const exportIdx = args.indexOf('--export');
+  if (exportIdx !== -1) {
+    const dest = args[exportIdx + 1];
+    if (!dest) { stderr.write('--export 需要一个文件路径\n'); return EXIT.USAGE; }
+    const { writeAtomic } = await import('./atomic-fs.mjs');
+    writeAtomic(dest, exportJson(events));
+    stderr.write(`已导出 ${events.length} 条事件到 ${dest}\n`);
+    return EXIT.OK;
+  }
+  if (globals.json) { stdout.write(`${JSON.stringify(agg, null, 2)}\n`); return EXIT.OK; }
+  stdout.write(textReport(agg));
+  return EXIT.OK;
+}
+
+async function cmdTelemetry(args, stdout, stderr) {
+  const tm = await import('./telemetry.mjs');
+  const up = await import('./upload.mjs');
+  switch (args[0]) {
+    case 'status': {
+      let ep;
+      try { ep = up.endpoint(); } catch (e) { ep = `无效（${e.message}）`; }
+      const uploadOff = !tm.enabled() ? '关（埋点整体已关）'
+        : tm.offline() ? '关（--offline）'
+          : '关（GEOLY_TELEMETRY_UPLOAD=0）';
+      stdout.write(`埋点      ${tm.enabled() ? '开' : '关（GEOLY_TELEMETRY=0）'}\n`);
+      stdout.write(`上报      ${tm.uploadEnabled() ? '开' : uploadOff}\n`);
+      stdout.write(`端点      ${ep ?? '未配置 —— 纯本地'}\n`);
+      stdout.write(`待上报    ${tm.readAll().length} 条\n`);
+      stdout.write(`报表历史  ${tm.readHistory().length} 条（上报不消费它）\n`);
+      stdout.write(`状态目录  ${tm.stateDir()}\n`);
+      return EXIT.OK;
+    }
+    case 'flush': {
+      const r = await up.flush();
+      stdout.write(r.skipped ? `未上报：${r.reason}\n` : `已上报 ${r.sent} 条\n`);
+      return r.skipped && r.reason?.startsWith('error:') ? EXIT.USAGE : EXIT.OK;
+    }
+    default:
+      stderr.write('用法：skills-hub telemetry <status|flush>\n');
+      return EXIT.USAGE;
+  }
+}

package/src/commands/check.mjs

@@ -0,0 +1,295 @@
+// `check` —— 09-cli.md §4「两阶段」。
+//
+// | 问题 | 依据 |
+// |---|---|
+// | 磁盘上的字节对不对 | 账本记录的**安装时快照**（按 02-registry.md §6.1 的历史读取路径取回并验签），重算树摘要比对 |
+// | 这东西现在还该不该用 | **当前 timestamp 指向的快照**里的 `status` / `yanked` / advisory |
+//
+// 🔴 `--offline` 时第二问**答不了** → 输出标注
+//    `状态未知（离线，最后验证于 <时间>）`，**不得默认为「正常」**。
+//    这不是「降级成乐观」，是「明说没查」。两者在自动化里差别巨大：
+//    前者会让 CI 绿灯放行一个已经被 yank 的制品。
+//
+// 🔴 还必须如实报告项目级/全局并存，**不声称哪份生效**（04-install.md §8.2）。
+//
+// 🔴 check **只读**：不取 repo 锁、不取 target 锁（§5.1 的取锁表）。
+//    因此它看到的是一个**可能正在被别人改**的现场 —— 报告里如实带上这一点。
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { treeDigest } from '../tree-digest.mjs';
+import { layout } from '../ledger.mjs';
+import { listJournalGenerations, readJournal } from '../journal.mjs';
+import { readLockfile, projectLockfile } from '../lockfile.mjs';
+import { stringify } from '../canonical-json.mjs';
+import { REPO } from '../trust.mjs';
+import { UsageError, EXIT } from '../exit-codes.mjs';
+import { getVerifier, historicalReader, resolveSnapshotForCommand, isDegradable } from './snapshot-access.mjs';
+import { annotations, annotationSuffix } from './output.mjs';
+import { targetsFor, ledgerOf, shadowMap } from './query.mjs';
+import { LOCKFILE_NAME } from './sync-lock.mjs';
+
+/** 第二问答不上来时的**固定**措辞。测试直接断言这个串。 */
+export const UNKNOWN_STATUS = (lastVerifiedAt) =>
+  `状态未知（离线，最后验证于 ${lastVerifiedAt ?? '从未验证'}）`;
+
+/**
+ * 第一问：磁盘字节 vs 账本记录的**安装时快照**。
+ *
+ * 🔴 「重算树摘要比对」不是「和账本里的 tree_digest 比」就完了 ——
+ *    账本是本机文件，能改账本的人也能改目录。判据必须回到**已验签的历史快照**：
+ *      磁盘实测摘要 == 历史快照 record 的 tree_digest，
+ *    并且账本记的那一份也要等于它（三方一致），否则就是账本被改过。
+ */
+export function checkBytes(target, name, entry, readHistorical) {
+  const dir = join(target, name);
+  if (!existsSync(dir)) {
+    return { ok: false, name, why: 'missing', message: `${dir} 不存在，但账本记着它` };
+  }
+  let actual;
+  try { actual = treeDigest(dir); } catch (e) {
+    return { ok: false, name, why: 'unreadable', message: `${dir} 算不出树摘要：${e.message}` };
+  }
+  let expected = null;
+  let source = 'ledger';
+  try {
+    const snap = readHistorical(entry.snapshot);
+    const rec = snap.artifacts.find((r) => r.id === entry.artifact);
+    if (rec) { expected = rec.tree_digest; source = `snapshot:${entry.snapshot}`; }
+  } catch (e) {
+    // 取不回安装时快照 → **不能**退回去只信账本然后报「一切正常」。
+    // 如实报「未证明」，并且不算通过。
+    return {
+      actual,
+      ok: false,
+      name,
+      why: 'unproven',
+      message: `取不回安装时快照 ${entry.snapshot}（${e.message.split('\n')[0]}）——`
+        + '字节对不对**无法证明**，不按通过处理',
+    };
+  }
+  if (expected === null) {
+    return {
+      actual,
+      ok: false,
+      name,
+      why: 'unproven',
+      message: `安装时快照 ${entry.snapshot} 里没有 ${entry.artifact} 的 record —— 无法证明`,
+    };
+  }
+  if (entry.tree_digest !== expected) {
+    return {
+      actual, expected, ok: false, name, why: 'ledger-mismatch',
+      message: `账本记的 tree_digest 与已验签快照里的不符（账本 ${entry.tree_digest} != 快照 ${expected}）`,
+    };
+  }
+  if (actual !== expected) {
+    return {
+      actual, expected, ok: false, name, why: 'digest-mismatch',
+      message: `磁盘实测 ${actual} != 已验签快照记录的 ${expected}`,
+    };
+  }
+  return { actual, expected, ok: true, name, source, why: null };
+}
+
+/** 第二问：当前快照里的 `status` / `yanked` / advisory。 */
+export function checkStatus(entry, current) {
+  if (current === null) return { answered: false, status: null, advisory: null };
+  const rec = current.artifacts.find((r) => r.id === entry.artifact);
+  if (!rec) {
+    return {
+      answered: true,
+      status: 'absent',
+      advisory: null,
+      message: `${entry.artifact} 不在当前快照里（可能已被移除）`,
+    };
+  }
+  const y = current.yanked.find((x) => x.id === rec.id);
+  return {
+    advisory: y?.advisory ?? null,
+    answered: true,
+    message: y ? `已被 yank：${y.reason}` : null,
+    status: rec.status,
+    superseded_by: y?.superseded_by ?? null,
+  };
+}
+
+export async function cmdCheck(ctx, argv, out) {
+  for (const a of argv) throw new UsageError(`check 不认得参数 ${a}`);
+  const tplan = targetsFor(ctx, out);
+  const shadowed = shadowMap(ctx, tplan);
+  const verifier = await getVerifier(ctx);
+  const readHistorical = historicalReader(ctx, verifier);
+
+  // 当前快照 —— 第二问的**唯一**依据。取不到就答不了，绝不用历史快照冒充。
+  let current = null;
+  let stale = false;
+  let lastVerifiedAt = null;
+  let currentError = null;
+  try {
+    const r = await resolveSnapshotForCommand(ctx);
+    current = r.snapshot;
+    stale = r.stale;
+    lastVerifiedAt = r.floor?.last_verified_at ?? null;
+  } catch (e) {
+    // 🔴 同 list：只有「取不到」可以降级成「第二问答不了」。
+    //    stale / 完整性 / min-cli 各有自己的退出码，吞掉它们就等于伪造了一次通过。
+    if (!isDegradable(e)) throw e;
+    currentError = e;
+    try {
+      const { readTrustFloor } = await import('../trust.mjs');
+      lastVerifiedAt = readTrustFloor(ctx.stateDir)?.last_verified_at ?? null;
+    } catch { lastVerifiedAt = null; }
+    out.warn(`第二问答不了：${e.message.split('\n')[0]}`);
+  }
+  if (stale) out.warn('timestamp 已过期：以下每一行都按 stale 处理');
+
+  const rows = [];
+  const targetsOut = [];
+  for (const t of tplan.selected) {
+    const L = ledgerOf(t.target);
+    // 未恢复事务：check 要报出来（它会让第一问的比对结果没有意义）
+    const P = layout(t.target);
+    const unfinished = [];
+    if (existsSync(P.state)) {
+      for (const g of listJournalGenerations(P.journalDir)) {
+        const J = readJournal(layout(t.target, g).journal);
+        if (J.phase !== 'completed') unfinished.push({ generation: g, phase: J.phase });
+      }
+      if (existsSync(P.repairIntent)) unfinished.push({ generation: null, phase: 'repair-intent' });
+    }
+    targetsOut.push({
+      // 🔴 §7：标注挂在**每一个** target / entry 对象上，不是只挂 entry 那一层
+      annotations: annotations({ offline: ctx.offline, stale }),
+      client: t.client,
+      entries: L ? Object.keys(L.entries).length : 0,
+      has_ledger: L !== null,
+      scope: t.scope,
+      target: t.target,
+      unfinished_transactions: unfinished,
+    });
+    if (!L) continue;
+    for (const [name, e] of Object.entries(L.entries)) {
+      const bytes = checkBytes(t.target, name, e, readHistorical);
+      const status = checkStatus(e, current);
+      rows.push({
+        annotations: annotations({
+          stale,
+          offline: ctx.offline || currentError !== null,
+          yanked: status.status === 'yanked',
+          degraded: status.status === 'degraded',
+          shadowed: shadowed.has(name),
+        }),
+        artifact: e.artifact,
+        bytes,
+        client: t.client,
+        name,
+        scope: t.scope,
+        // 🔴 答不了就是答不了 —— **不得默认为「正常」**
+        status: status.answered ? status.status : null,
+        status_advisory: status.advisory ?? undefined,
+        status_message: status.answered
+          ? (status.message ?? undefined)
+          : UNKNOWN_STATUS(lastVerifiedAt),
+        status_known: status.answered,
+        target: t.target,
+      });
+    }
+  }
+
+  // lockfile 过时（§8.1：`check` 发现不符则报「lockfile 过时」，提示 sync-lock）
+  let lockfileState = null;
+  if (ctx.scope === 'project') lockfileState = checkLockfile(ctx, tplan, readHistorical, out);
+
+  // ── 输出 ────────────────────────────────────────────────────────────────
+  out.line(`check（${rows.length} 条 entry）：`);
+  for (const r of rows) {
+    const first = r.bytes.ok ? 'bytes-ok  ' : `bytes-BAD `;
+    const second = r.status_known ? `status=${r.status}` : r.status_message;
+    out.line(`  ${first}${r.client}/${r.scope}  ${r.name}  ${second}${annotationSuffix(r.annotations)}`);
+    if (!r.bytes.ok) out.line(`            ${r.bytes.message}`);
+    if (r.status_advisory) out.line(`            advisory: ${r.status_advisory}`);
+  }
+  for (const t of targetsOut) {
+    for (const u of t.unfinished_transactions) {
+      out.line(`  [!] ${t.client}/${t.scope} 有未完成事务（${u.phase}）——`
+        + '请先 `skills-hub recover`；在那之前上面的比对结果只反映一个中间态');
+    }
+  }
+  for (const [name, hits] of shadowed) {
+    out.line(`  [!] ${name} 项目级与全局并存（全局在 ${hits[0].globalTarget}）——`
+      + '生效者取决于客户端，本工具不做判断（04-install.md §8.2）');
+  }
+  if (lockfileState && !lockfileState.ok) {
+    out.line(`  [!] ${lockfileState.message}`);
+  }
+
+  const badBytes = rows.filter((r) => !r.bytes.ok);
+  const unfinishedAny = targetsOut.some((t) => t.unfinished_transactions.length > 0);
+  let exit = EXIT.OK;
+  // 🔴 优先级：有未完成事务 → 5（先去 recover，其它结论都只反映中间态）；
+  //    否则字节不符 → 2（完整性失败）。
+  if (unfinishedAny) exit = EXIT.NEEDS_RECOVER;
+  else if (badBytes.length) exit = EXIT.INTEGRITY;
+
+  if (ctx.record) {
+    ctx.record({
+      kind: 'check',
+      reason: exit === EXIT.OK ? undefined : (exit === EXIT.INTEGRITY ? 'digest-mismatch' : 'journal-corrupt'),
+      result: exit === EXIT.OK ? 'ok' : 'failed',
+      scope: ctx.scope,
+    });
+  }
+
+  return out.emit('check', {
+    entries: rows,
+    lockfile: lockfileState ?? undefined,
+    second_question_answered: current !== null,
+    second_question_unknown_reason: current === null ? UNKNOWN_STATUS(lastVerifiedAt) : undefined,
+    shadowed: [...shadowed.keys()].sort(),
+    snapshot: current ? current.snapshot : undefined,
+    targets: targetsOut,
+  }, exit);
+}
+
+/** §8.1：lockfile 与账本投影不符 → 报「过时」，提示 `sync-lock`。**只报不写**。 */
+function checkLockfile(ctx, tplan, readHistorical, out) {
+  const path = join(ctx.projectRoot, LOCKFILE_NAME);
+  if (!existsSync(path)) {
+    return { message: `${path} 不存在（项目级安装应当维护它）—— 跑 \`skills-hub sync-lock\` 生成`, ok: false, path };
+  }
+  let onDisk;
+  try { onDisk = readLockfile(path); } catch (e) {
+    return { message: `${path} 解析失败：${e.message}`, ok: false, path };
+  }
+  // 重算一份**在内存里**的投影去比 —— 🔴 check 不写盘
+  const targets = [];
+  for (const t of tplan.selected) {
+    const L = ledgerOf(t.target);
+    if (!L) continue;
+    if (Object.keys(L.entries).length === 0 && Object.keys(L.roots).length === 0) continue;
+    const assetSha256 = {};
+    let missing = false;
+    for (const [name, e] of Object.entries(L.entries)) {
+      try {
+        const snap = readHistorical(e.snapshot);
+        const rec = snap.artifacts.find((r) => r.id === e.artifact);
+        if (!rec) { missing = true; break; }
+        assetSha256[name] = rec.asset.sha256;
+      } catch { missing = true; break; }
+    }
+    if (missing) {
+      out.warn('取不回某些安装时快照，lockfile 的「是否过时」无法证明 —— 如实报未证明，不报「一致」');
+      return { message: 'lockfile 是否过时**未证明**（取不回安装时快照里的 asset_sha256）', ok: false, path, unproven: true };
+    }
+    targets.push({ assetSha256, client: t.client, ledger: L, path: `${t.adapter.dirName}/skills`, scope: 'project' });
+  }
+  let want;
+  try { want = projectLockfile({ registry: REPO, targets }); } catch (e) {
+    return { message: `账本投影算不出来：${e.message}`, ok: false, path };
+  }
+  if (stringify(want) !== stringify(onDisk)) {
+    return { message: `${path} **已过时**（与账本投影不符）—— 跑 \`skills-hub sync-lock\``, ok: false, path };
+  }
+  return { ok: true, path };
+}