@bolloon/bolloon-agent 0.5.0 → 0.5.2

package/dist/llm/tool-name.js

@@ -0,0 +1,220 @@
+/**
+ * tool-name.ts — 工具名「出网前的唯一净化边界」(2026-09-26)
+ *
+ * 为什么要这个文件:
+ *   OpenAI 兼容 API 对 `tools[i].function.name` 有硬约束 —— 必须匹配
+ *   `^[a-zA-Z0-9_-]{1,64}$`. 只要**第 121 个**工具的名字里有一个非法字符 (`.` `:` `/`
+ *   空格 / 中文 ...), 整个请求就被 400 拒掉:
+ *
+ *     Invalid 'tools[120].function.name': string does not match pattern.
+ *     Expected a string that matches the pattern '^[a-zA-Z0-9_-]+$'.
+ *
+ *   表现是「网页端明明配好了 API, 一跑就失败」—— 根因在**发包形状**, 不在凭据。
+ *   本仓曾注册 6 个带点的工具名 (`contact.list_authorized` 一族), 命中这个坑。
+ *
+ * 设计铁律:
+ *   1. **唯一边界**: 净化只在 `pi-ai.ts` 的 `generateText()` 里做一次 (那里是全仓唯一
+ *      产出 wire 形状 tools 数组的地方). 业务代码一个都不许自己做净化 —— 否则同一次改动
+ *      要有 N 个调用点跟着改, 迟早漏一个.
+ *   2. **确定性, 不是随机**: 非法字符 → `_`; 超长 → 前 55 字符 + `_` + 原名 sha256 前 8 位
+ *      (同一次运行里同一原名永远得到同一个 API 名).
+ *   3. **派发不断**: 净化时把 `原名 → API 名` 同时反向登记 (原名 ↔ API 名双射), 回程
+ *      (`resolveApiToolName`) 把 LLM 回吐的 API 名还原成原名, 再交给 `this.tools.get()`.
+ *      LLM 也可能照 system prompt 里的原名回吐 —— 原名在表里就直接穿透.
+ *   4. **碰撞不许静默**: 两个**不同**原名净化后同名 → 抛 `ToolNameCollisionError`, 消息里
+ *      把两个原名都点名. 绝不悄悄合并或悄悄改名 (那会让 LLM 调到的工具和它以为的不是一个).
+ *   5. **不猜**: 没有名字 / 空名字的工具也是非法形状 → 抛错点名, 不静默丢掉.
+ *
+ * 真正「覆盖所有入口」的依据: CLI / Web / MCP / 技能 / 子 Agent / 长期任务全都走
+ * `getMinimax().chat(..., tools)` → `PiAIModel.generateText()` → `callOpenAI()`,
+ * 全仓只有这一条产出 tools 的路径 (见 `scripts/verify-tool-names.ts` 的源码级断言).
+ */
+import * as crypto from 'crypto';
+/** OpenAI 兼容 API 对 function.name 的硬约束 */
+export const TOOL_NAME_MAX_LENGTH = 64;
+/** 允许的字符集: 字母 / 数字 / 下划线 / 连字符 */
+export const TOOL_NAME_CHAR_CLASS = 'a-zA-Z0-9_-';
+/** 完整形状约束 (1..64, 只含安全字符) */
+export const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+/** 太长时的截断长度: 55 + '_' + 8 位 hash = 64, 正好贴着上限 */
+const TRUNCATE_KEEP = 55;
+/** 严格形状校验 (不做任何修补) */
+export function isValidToolName(name) {
+    return typeof name === 'string' && TOOL_NAME_PATTERN.test(name);
+}
+/** 名字里的非法字符 (去重, 按出现顺序) —— 给探针/门报「违规字符是什么」用 */
+export function illegalCharsOf(name) {
+    const out = [];
+    for (const ch of String(name ?? '')) {
+        if (!/[a-zA-Z0-9_-]/.test(ch) && !out.includes(ch))
+            out.push(ch);
+    }
+    return out;
+}
+/** 原名指纹 (sha256 前 8 位 hex) —— 超长截断的去碰撞后缀 */
+export function toolNameFingerprint(name) {
+    return crypto.createHash('sha256').update(String(name), 'utf8').digest('hex').slice(0, 8);
+}
+/**
+ * 纯函数净化: 非法字符 → `_`; 超长 → 截断 + 稳定 hash 后缀.
+ * 已经是合法名的原样返回 (幂等, 再跑一次不变).
+ */
+export function sanitizeToolName(name) {
+    const raw = String(name ?? '');
+    let s = raw.replace(new RegExp(`[^${TOOL_NAME_CHAR_CLASS}]`, 'g'), '_');
+    if (s.length > TOOL_NAME_MAX_LENGTH) {
+        s = `${s.slice(0, TRUNCATE_KEEP)}_${toolNameFingerprint(raw)}`;
+    }
+    // 空名 / 全非法字符且被清空 (理论上不会, 上面都是替换成 '_') —— 兜底成可派发的稳定名
+    if (s.length === 0)
+        s = `tool_${toolNameFingerprint(raw)}`;
+    return s;
+}
+/** 两个不同原名净化后撞名 —— 点名两方, 拒绝发包 */
+export class ToolNameCollisionError extends Error {
+    apiName;
+    names;
+    constructor(apiName, names) {
+        super(`工具名净化后撞名: ${names.map((n) => `"${n}"`).join(' 与 ')} 都会净化为 "${apiName}" —— ` +
+            `拒绝发包 (两个不同工具共用一个 API 名会让 LLM 调到的实现不可知). ` +
+            `请给其中一个改名, 只剩安全字符 [${TOOL_NAME_CHAR_CLASS}] 且 ≤64 字符.`);
+        this.name = 'ToolNameCollisionError';
+        this.apiName = apiName;
+        this.names = names;
+    }
+}
+/**
+ * 原名 ↔ API 名 双射表.
+ *   正向: 出网时把原名登记进来拿 API 名 (碰撞 → 抛错, 不静默).
+ *   反向: 回程把 LLM 回吐的 API 名还原成原名 (未知名原样穿透, 由业务侧报「未知工具」).
+ */
+export class ToolNameRouteTable {
+    byApi = new Map();
+    byOriginal = new Map();
+    /** 登记一个原名, 返回它的 API 名. 撞名 → ToolNameCollisionError. */
+    register(original) {
+        const orig = String(original ?? '');
+        if (isValidToolName(orig)) {
+            // 合法名不动: 但也要防「另一个原名净化成它」的撞名 (下面 byApi 会处理)
+            const api = orig;
+            const holder = this.byApi.get(api);
+            if (holder !== undefined && holder !== orig) {
+                throw new ToolNameCollisionError(api, [holder, orig]);
+            }
+            this.byApi.set(api, orig);
+            this.byOriginal.set(orig, api);
+            return api;
+        }
+        const api = sanitizeToolName(orig);
+        const holder = this.byApi.get(api);
+        if (holder !== undefined && holder !== orig) {
+            throw new ToolNameCollisionError(api, [holder, orig]);
+        }
+        this.byApi.set(api, orig);
+        this.byOriginal.set(orig, api);
+        return api;
+    }
+    /** 批量登记 */
+    registerAll(originals) {
+        return originals.map((n) => this.register(n));
+    }
+    /** 原名 → API 名 (没登记过就现算, 不登记 —— 给纯查询用) */
+    apiNameOf(original) {
+        const known = this.byOriginal.get(String(original ?? ''));
+        if (known !== undefined)
+            return known;
+        return isValidToolName(original) ? original : sanitizeToolName(original);
+    }
+    /**
+     * API 名 → 原名 (回程派发用).
+     * 不在表里 (LLM 照 system prompt 里的原名回吐 / 编了个名字) → 原样返回,
+     * 交给业务侧 `tools.get()` 走「未知工具」分支 — 不在这里吞掉.
+     */
+    resolveToOriginal(apiName) {
+        const hit = this.byApi.get(String(apiName ?? ''));
+        return hit !== undefined ? hit : String(apiName ?? '');
+    }
+    /** 是否知道这个 API 名 */
+    knows(apiName) {
+        return this.byApi.has(String(apiName ?? ''));
+    }
+    /** 全部映射 (原名 → API 名), 按登记顺序 */
+    get mappings() {
+        const seen = new Set();
+        const out = [];
+        for (const [api, original] of this.byApi.entries()) {
+            if (seen.has(original))
+                continue;
+            seen.add(original);
+            out.push({ original, api, changed: original !== api });
+        }
+        return out;
+    }
+    /** 被改写过的部分 (改名清单) */
+    get changed() {
+        return this.mappings.filter((m) => m.changed);
+    }
+    /** 表里已知的原名个数 */
+    get size() {
+        return this.byApi.size;
+    }
+    /** 清空 (测试用; 业务路径不该调) */
+    clear() {
+        this.byApi.clear();
+        this.byOriginal.clear();
+    }
+}
+/**
+ * 进程级单例: 出网净化与回程派发共用同一张表.
+ * (出网在 pi-ai.ts, 派发在 pi-sdk.ts / workflow-pivot-loop.ts —— 只有共享一份才保证还原得到真名)
+ */
+export const globalToolNameRoutes = new ToolNameRouteTable();
+/**
+ * **唯一**的出网净化入口: 把 wire 形状的 tools 数组里的 `function.name` 逐个净化,
+ * 顺便把映射登记进 `globalToolNameRoutes` 供回程派发还原.
+ *
+ * - 不改入参 (返回新数组 / 新对象), 调用方拿去发包即可;
+ * - 没名字 / 空名字 → 抛错 (说不出名字的工具本来就是坏形状, 不许静默丢);
+ * - 撞名 → ToolNameCollisionError (点名两个原名).
+ */
+export function sanitizeToolsForApi(tools, table = globalToolNameRoutes) {
+    if (!Array.isArray(tools))
+        return tools;
+    const out = new Array(tools.length);
+    for (let i = 0; i < tools.length; i++) {
+        const tool = tools[i];
+        const original = tool?.function?.name;
+        if (typeof original !== 'string' || original.length === 0) {
+            throw new Error(`工具 #${i} 没有可用的 function.name (拿到 ${JSON.stringify(original)}) —— 拒绝发包: ` +
+                `OpenAI 兼容 API 要求每个工具都有 name 且匹配 /^[a-zA-Z0-9_-]{1,64}$/`);
+        }
+        const api = table.register(original);
+        out[i] = api === original ? tool : { ...tool, function: { ...tool.function, name: api } };
+    }
+    return out;
+}
+/** 回程: LLM 回吐的名字 → 注册表真名 (未知名原样穿透) */
+export function resolveApiToolName(apiName, table = globalToolNameRoutes) {
+    return table.resolveToOriginal(apiName);
+}
+/**
+ * 给「文本解析」路径用的已知名集合: 原名 + 它们的 API 名.
+ * LLM 在文本里回吐的可能是净化后的名字 (prompt/工具面里给的是 API 名),
+ * 只用原名集合过滤会把这类调用直接丢掉.
+ */
+export function expandKnownToolNames(names, table = globalToolNameRoutes) {
+    const out = new Set();
+    for (const n of names) {
+        out.add(n);
+        const api = table.apiNameOf(n);
+        out.add(api);
+        // 预登记, 保证回程还原得到
+        try {
+            table.register(n);
+        }
+        catch {
+            // 撞名: 交给出网时的 sanitizeToolsForApi 抛 (那里能给出「拒绝发包」的上下文)
+        }
+    }
+    return out;
+}

package/dist/setup/onboard.js

@@ -104,9 +104,9 @@ const stepProvider = {
         }
         try {
             await store.updateProvider(picked, { enabled: true });
-            // setup 模式直接激活; reconfigure 要等测试通过才切换 active (失败不破坏旧配置)
-            if (c.mode !== 'reconfigure')
-                await store.setActiveProvider(picked);
+            // 2026-09-26 (P6): 这里**不再**直接 `setActiveProvider` —— 激活是"切换", 只能走统一入口,
+            //   而且必须等 key/模型齐了、连通实测过了才切 (见 stepConnectivity 的成功分支)。
+            //   早切的问题: 那时还没有 key, 切过去等于把 effective 配置指到一个用不了的供应商。
         }
         catch (err) {
             return { ok: false, errorClass: 'io', message: `写配置失败: ${String(err?.message || err).slice(0, 120)}` };
@@ -114,7 +114,7 @@ const stepProvider = {
         return {
             ok: true,
             patch: { inputs: { provider: picked }, checks: { providerSelected: true } },
-            note: `${picked} 已 ${c.mode === 'reconfigure' ? '标记为候选 (测试通过后切换)' : '激活'}`,
+            note: `${picked} 已 ${c.mode === 'reconfigure' ? '标记为候选 (测试通过后切换)' : '标记为待启用 (连通实测通过后由统一入口切换)'}`,
         };
     },
 };
@@ -202,7 +202,30 @@ const stepConnectivity = {
         c.io.print(`用最终保存的 provider/key/baseUrl/model 真实测试 ${provider} …`);
         const res = await store.testProvider(provider);
         if (res?.success) {
-            return { ok: true, patch: { checks: { connectivityOk: true, connectivityAt: new Date().toISOString(), connectivityErrorClass: undefined } }, note: `通过 (${res.latency ?? '?'}ms)` };
+            // 2026-09-26 (P6): 测试通过之后**才**真正切换 —— 而且只有一处实现: 统一入口 `selectModel()`。
+            //   此前 setup 模式在 stepProvider 里直接 `setActiveProvider` (那时还没有 key, 也没探测过),
+            //   reconfigure 模式则根本不切换 —— 两个都不算"同一语义"。
+            //   这里 `verify:false`: 刚在上面真测过一次, 入口不用再打一次上游 (重复探测是浪费, 不是严谨)。
+            try {
+                const { selectModel } = await import('../llm/model-selection.js');
+                const sw = await selectModel({ provider, model: c.state.inputs.model, scope: 'global', verify: false });
+                if (!sw.ok) {
+                    return {
+                        ok: false,
+                        errorClass: sw.failureClass === 'missing_api_key' ? 'auth' : 'config',
+                        message: `连接是通的, 但切换没有落盘 [${sw.failureClass}]: ${sw.message}`,
+                        retryable: false,
+                    };
+                }
+                return {
+                    ok: true,
+                    patch: { checks: { connectivityOk: true, connectivityAt: new Date().toISOString(), connectivityErrorClass: undefined } },
+                    note: `通过 (${res.latency ?? '?'}ms) · 已由统一入口切到 ${sw.effective.provider}/${sw.effective.model}`,
+                };
+            }
+            catch (err) {
+                return { ok: false, errorClass: 'runtime', message: `连通但切换失败: ${String(err?.message || err).slice(0, 160)}` };
+            }
         }
         const raw = String(res?.error || '未知错误');
         const cls = /401|403|key/i.test(raw) ? 'auth' : /429|限流/i.test(raw) ? 'network' : /404|端点|baseUrl/i.test(raw) ? 'config' : /timeout|超时/i.test(raw) ? 'timeout' : /fetch|network|ECONN/i.test(raw) ? 'network' : 'unknown';
@@ -220,11 +243,14 @@ const stepRuntime = {
         const details = [];
         try {
             const mod = await import('../llm/pi-ai.js');
-            mod.initMinimax?.();
+            // 2026-09-26 (P6): 运行时**只由统一入口装配** —— `installRuntime` 是唯一那个 initMinimax 调用点,
+            //   这里不再自己 `initMinimax()` (那会让"按配置文件装配"和"按有效配置装配"分叉成两条)。
+            const { applyEffectiveToRuntime } = await import('../llm/model-selection.js');
+            const eff = await applyEffectiveToRuntime();
             const model = mod.getMinimax?.() || mod.getModel?.();
             if (!model)
-                return { ok: false, errorClass: 'runtime', message: 'initMinimax 之后仍拿不到模型对象' };
-            details.push('initMinimax ✓');
+                return { ok: false, errorClass: 'runtime', message: '统一入口装配之后仍拿不到模型对象' };
+            details.push(`统一入口装配 ✓ (${eff.provider}/${eff.model})`);
             const chat = model.chat || model.generate || model.complete || model.call;
             if (typeof chat !== 'function') {
                 return { ok: false, errorClass: 'runtime', message: '运行时对象没有可调用的 chat/generate 接口 —— 只有 singleton 不算 ready' };

package/dist/utils/dual-source-facts.js

@@ -0,0 +1,223 @@
+/**
+ * dual-source-facts.ts — 双源的**语义核心** (2026-09-26, update-protocol §12)
+ *
+ * 为什么从 `dual-source.ts` 里抽出这一半: 手机端 WebView **没有 node:**, 但手机端双源更新
+ * 必须用**和桌面同一份**交叉校验 / 错误分类 / dev 快照比较 —— 否则同一件事在电脑上和手机上
+ * 会长出两套说法 (而"两个源指向不同版本就拒绝"这种事, 两套说法迟早有一处是错的)。
+ *
+ * 这里只放**纯函数与类型** (不 import 任何 `node:*`, 不在顶层读 `process.env`):
+ *   · GitHub 侧错误分类 `classifyGithubError` (§12.3, 与 registry 侧并列不合并)
+ *   · stable 的交叉校验 `crossCheckStable` (§12.1)
+ *   · dev 的按 sha 比较 `compareDevSnapshots` (§12.1)
+ *   · 事实/报告的紧凑视图 `toGithubReport` / `renderGithubReportLine`
+ *
+ * 需要网络与子进程的那一半 (真调 api.github.com / codeload 下载 / 现场构建 dev 快照)
+ * 仍在 `dual-source.ts` —— 它在这份纯模块之上, 且把这些名字原样再导出。
+ *
+ * 硬口径 (§12.5, 验收核心, 两边共用):
+ *   - 源不可达 / 版本不存在 → **拒绝并说清** (带具体分类), 绝不静默装回旧版
+ *   - 不编造不存在的路径: 本仓 GitHub 上**真的没有 Release** (0 个), 所以 "Release 缺" 时
+ *     如实报 "发布记录缺 Tag / Release" (提醒级), **不是** fake 一个 Release 出来
+ */
+import { GITHUB_UPSTREAM_SLUG, DEV_BRANCH, DEV_CHANNEL_WARNING } from './version-identity.js';
+export { DEV_CHANNEL_WARNING };
+// ── 类型 ────────────────────────────────────────────────────────────────────
+/**
+ * GitHub 侧错误的分类 (§12.3) —— 与 registry 的分类**并列且不合并**:
+ *   offline       网络不可达 (ENOTFOUND/EAI_AGAIN/ECONNREFUSED/超时)
+ *   rate_limited  HTTP 403/429 (限流; 带重试时间)
+ *   not_found     HTTP 404 (没有 Release / 没有 master 分支 / 仓库不存在)
+ *   http_error    其它 HTTP 状态 (5xx 等) —— 不塞进上面三类, 免得把"服务有问题"说成"网不通"
+ *   parse_error   拿到了内容但解析不了
+ */
+export const GITHUB_REASONS = ['offline', 'rate_limited', 'not_found', 'http_error', 'parse_error'];
+export function toGithubReport(r) {
+    if (!r.ok) {
+        return {
+            reachable: false, reason: r.reason, detail: r.detail, retryAt: r.retryAt,
+            headSha: r.facts?.headSha ?? null, ref: r.facts?.ref ?? `refs/heads/${DEV_BRANCH}`,
+            releases: r.facts?.releases.length, tags: r.facts?.tags.length,
+            newestVersion: r.facts ? newestGithubVersion(r.facts) : null,
+            partial: r.facts?.partial, fetchedAt: r.facts?.fetchedAt,
+        };
+    }
+    return {
+        reachable: true, headSha: r.facts.headSha, ref: r.facts.ref,
+        releases: r.facts.releases.length, tags: r.facts.tags.length,
+        newestVersion: newestGithubVersion(r.facts), partial: r.facts.partial, fetchedAt: r.facts.fetchedAt,
+    };
+}
+export function renderGithubReportLine(g) {
+    if (!g)
+        return 'GitHub 源: 未查询';
+    if (!g.reachable) {
+        const retry = g.retryAt ? `, 限流重试时间 ${g.retryAt}` : '';
+        return `GitHub 源: 不可达 — github_unavailable(${g.reason}) ${g.detail || ''}${retry}`;
+    }
+    return `GitHub 源: 可达 · master HEAD ${g.headSha ? g.headSha.slice(0, 7) : '未知'} · Release ${g.releases ?? 0} 个 · Tag ${g.tags ?? 0} 个 · 最新版本标签 ${g.newestVersion || '无'}${g.partial ? ' (部分请求失败)' : ''}`;
+}
+// ── 错误分类 ────────────────────────────────────────────────────────────────
+export const OFFLINE_CODES = new Set(['ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EHOSTUNREACH', 'ENETUNREACH', 'ENETDOWN', 'EAI_FAIL', 'UND_ERR_CONNECT_TIMEOUT', 'CERT_HAS_EXPIRED']);
+/**
+ * 从**错误链**里挖网络类证据。
+ *
+ * 为什么不能只看 `err.code`: `fetch()` 抛出来的是 `TypeError: fetch failed`, 真正的 socket 错误挂在
+ * `err.cause.code` (undici)。只看 `err.code` ⇒ 连不上的端口会被判成 http_error / registry_unavailable,
+ * 于是"源不可达"这一条在真跑里变成**分类错误**(真跑抓到过: 死端口 → registry_unavailable)。
+ * 浏览器侧则是 `message: 'Failed to fetch'` / `'Load failed'`。
+ */
+export function collectNetEvidence(err) {
+    const codes = [];
+    const msgs = [];
+    let cur = err;
+    for (let depth = 0; cur && depth < 6; depth++) {
+        // AggregateError (多地址并发失败) 的成员各带一个 code
+        const inner = Array.isArray(cur.errors) ? cur.errors : [];
+        for (const e of inner) {
+            if (e?.code)
+                codes.push(String(e.code));
+            if (e?.message)
+                msgs.push(String(e.message));
+        }
+        if (cur.code)
+            codes.push(String(cur.code));
+        if (cur.errno)
+            codes.push(String(cur.errno));
+        if (cur.message)
+            msgs.push(String(cur.message));
+        cur = cur.cause;
+    }
+    const code = codes.find((c) => OFFLINE_CODES.has(c)) || codes[0] || '';
+    const message = msgs.join(' · ');
+    const offline = codes.some((c) => OFFLINE_CODES.has(c))
+        || /timeout|timed out|ENOTFOUND|getaddrinfo|network|socket hang up|超时|Failed to fetch|fetch failed|NetworkError|Load failed|ECONNREFUSED|ECONNRESET/i.test(message);
+    return { code, message, offline };
+}
+/** 网络类 → offline; 403/429 → rate_limited; 404 → not_found; 其它 → http_error。 */
+export function classifyGithubError(err, httpStatus, headers = {}) {
+    const retryAt = headers['x-ratelimit-reset']
+        ? new Date(Number(headers['x-ratelimit-reset']) * 1000).toISOString()
+        : null;
+    const net = collectNetEvidence(err);
+    if (net.offline) {
+        return { kind: 'github_unavailable', reason: 'offline', detail: `${net.code || net.message || '网络不可达'}`, retryAt: null };
+    }
+    if (httpStatus === 403 || httpStatus === 429) {
+        return { kind: 'github_unavailable', reason: 'rate_limited', detail: `GitHub 返回 HTTP ${httpStatus} (限流/权限)`, retryAt };
+    }
+    if (httpStatus === 404) {
+        return { kind: 'github_unavailable', reason: 'not_found', detail: `GitHub 上没有 ${GITHUB_UPSTREAM_SLUG} 的该项记录 (HTTP 404)`, retryAt: null };
+    }
+    if (httpStatus && httpStatus >= 400) {
+        return { kind: 'github_unavailable', reason: 'http_error', detail: `GitHub 返回 HTTP ${httpStatus}`, retryAt };
+    }
+    return { kind: 'github_unavailable', reason: 'http_error', detail: net.code || net.message || '未知错误', retryAt: null };
+}
+/** registry 侧错误的分类 (§3) —— 与 `classifyGithubError` **并列, 不合并**。 */
+export function classifyRegistryError(err, httpStatus) {
+    const net = collectNetEvidence(err);
+    if (net.offline) {
+        return { kind: 'offline', detail: `${net.code || net.message || '网络不可达'}` };
+    }
+    if (httpStatus && httpStatus >= 500)
+        return { kind: 'registry_unavailable', detail: `registry 返回 HTTP ${httpStatus}` };
+    if (httpStatus === 404)
+        return { kind: 'registry_unavailable', detail: `registry 上没有该包 (HTTP 404)` };
+    if (httpStatus && httpStatus >= 400)
+        return { kind: 'registry_unavailable', detail: `registry 返回 HTTP ${httpStatus}` };
+    return { kind: 'registry_unavailable', detail: net.code || net.message || '未知错误' };
+}
+// ── 版本标签比较 ────────────────────────────────────────────────────────────
+/** GitHub 上出现过的最高版本号 (Release ∪ Tag, 去掉 v 前缀)。没有 → null。 */
+export function newestGithubVersion(facts) {
+    const all = [...facts.releases, ...facts.tags.map((t) => t.name)]
+        .map((n) => String(n).trim().replace(/^v/, ''))
+        .filter((n) => /^\d+\.\d+\.\d+/.test(n));
+    if (all.length === 0)
+        return null;
+    return all.sort((a, b) => (numericCompare(a, b) < 0 ? 1 : -1))[0];
+}
+/** 只比数值段 (与 version-identity 的 compareVersions 同语义, 这里不再反向依赖它)。 */
+export function numericCompare(a, b) {
+    const p = (v) => v.split('-')[0].split('.').map((x) => parseInt(x.replace(/\D.*$/, ''), 10) || 0);
+    const pa = p(a);
+    const pb = p(b);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x < y)
+            return -1;
+        if (x > y)
+            return 1;
+    }
+    return 0;
+}
+function hasName(names, v) {
+    const set = new Set(names.map((n) => String(n).trim().replace(/^v/, '')));
+    return set.has(v.replace(/^v/, ''));
+}
+/**
+ * stable 的交叉校验 (§12.1/§12.5): npm 仍是权威, GitHub 只回答"这次发布的记录在不在"。
+ *
+ *   agree            npm 的 latest 在 GitHub 上有同名 tag/Release → 两条记录指向同一版
+ *   mismatch         GitHub 记录了**更新的**版本而 registry 上没有 → 拒绝 (不许按 tag 去装)
+ *   missing_record   registry 有该版本但 GitHub 缺这条记录 → **提醒级, 不阻塞** (§12.5 原文:
+ *                    "报发布记录缺 Tag (提醒级, 不阻塞 stable 更新)")
+ *   no_record_at_all GitHub 上一条版本记录都没有 → 如实报"暂无 tag 可交叉校验"(不编造路径)
+ */
+export function crossCheckStable(registryLatest, facts) {
+    const common = {
+        registryLatest, githubVersion: newestGithubVersion(facts),
+        releases: facts.releases.length, tags: facts.tags.length,
+    };
+    if (!registryLatest) {
+        return { ...common, kind: 'no_record_at_all', hasTag: false, hasRelease: false, blocking: false, detail: 'npm 没有给出 latest, 无从交叉校验' };
+    }
+    const allNames = [...facts.releases, ...facts.tags.map((t) => t.name)];
+    const hasTag = hasName(facts.tags.map((t) => t.name), registryLatest);
+    const hasRelease = hasName(facts.releases, registryLatest);
+    const ghNewest = common.githubVersion;
+    /**
+     * **先判"GitHub 记录了比 registry 更新的发布"** —— 这是 §12.5 的 "Release 存在但 registry 上没有该版本 → cross_check_mismatch"。
+     * 放在 agree 之前: 即使 registry 的 latest 自己也有 tag, 只要 GitHub 上还多出一条更新的发布记录, 两个源对
+     * "当前最新是哪一版"就是不一致的 —— 这种不一致必须拦住, 不能因为"latest 有 tag"就宣布一致。
+     */
+    if (ghNewest && numericCompare(ghNewest, registryLatest) > 0) {
+        return {
+            ...common, kind: 'mismatch', hasTag, hasRelease, blocking: true,
+            detail: `GitHub 上有 ${ghNewest} 的发布记录, 但 npm registry 的 latest 还是 ${registryLatest} — 拒绝按 GitHub 的记录安装`,
+        };
+    }
+    if (hasTag || hasRelease) {
+        return {
+            ...common, kind: 'agree', hasTag, hasRelease, blocking: false,
+            detail: `npm latest=${registryLatest} 在 GitHub 上有同名记录 (${hasRelease ? `Release v${registryLatest}` : `Tag v${registryLatest}`}) — 两个源指向同一版`,
+        };
+    }
+    if (allNames.length === 0) {
+        return {
+            ...common, kind: 'no_record_at_all', hasTag: false, hasRelease: false, blocking: false,
+            detail: `GitHub 上暂无任何 tag / Release (0 个) — 暂无可交叉校验的记录, npm 仍是权威 (latest=${registryLatest})`,
+        };
+    }
+    return {
+        ...common, kind: 'missing_record', hasTag, hasRelease, blocking: false,
+        detail: `npm latest=${registryLatest} 在 GitHub 上没有对应记录 (GitHub 最新版本标签 ${ghNewest || '无'}; Release ${facts.releases.length} 个 / Tag ${facts.tags.length} 个) — 发布记录缺 Tag, 不阻塞 stable 更新`,
+    };
+}
+export function compareDevSnapshots(installedSha, headSha, ref = `refs/heads/${DEV_BRANCH}`) {
+    const short = (s) => (s ? s.slice(0, 7) : '未知');
+    if (!headSha) {
+        return { ref, headSha, installedSha, same: false, behind: false, detail: `${ref} 的 HEAD 读不到 — 无法判定 dev 快照新旧` };
+    }
+    if (!installedSha) {
+        return { ref, headSha, installedSha, same: false, behind: false, detail: `当前不是 dev 快照 (stable 安装) — 切到 dev 将得到 ${ref} @ ${short(headSha)}` };
+    }
+    const same = installedSha.slice(0, 7) === headSha.slice(0, 7);
+    return {
+        ref, headSha, installedSha, same, behind: !same,
+        detail: same
+            ? `已是最新的 dev 快照 (${ref} @ ${short(headSha)}) — 同一个 commit`
+            : `dev 快照落后: 已装 ${short(installedSha)} → master HEAD ${short(headSha)} (按 commit sha 判定, 不看版本号)`,
+    };
+}