@bolloon/bolloon-agent 0.5.0 → 0.5.2

package/dist/utils/dual-source.js

@@ -9,6 +9,11 @@
  *   - 错误分类 `classifyGithubError` 与 §3 的 `classifyRegistryError` **并列, 不合并**
  *   - dev 快照的**取源与构建**也在这里 (update-manager 只负责"切换 + 验证 + 回滚", 不另造一套)
  *
+ * 2026-09-26 拆分 (手机端要复用同一份语义): **纯语义那一半**去 `dual-source-facts.ts`
+ * (分类 / 交叉校验 / dev 快照比较 —— 无 `node:`, 因此能打进手机端 WebView bundle);
+ * 本文件只留**需要网络与子进程**的那一半 (真调 api.github.com / codeload / 现场构建),
+ * 并把纯那一半的名字原样再导出 —— 既有 `from './dual-source.js'` 的 import 一行不用改。
+ *
  * 硬口径 (§12.5, 验收核心):
  *   - 源不可达 / 版本不存在 → **拒绝并说清** (带具体分类), 绝不静默装回旧版
  *   - 不编造不存在的路径: 本仓 GitHub 上**真的没有 Release** (0 个), 所以 "Release 缺" 时
@@ -21,34 +26,13 @@ import * as http from 'http';
 import * as https from 'https';
 import { spawnSync } from 'child_process';
 import { GITHUB_API_BASE, GITHUB_UPSTREAM_SLUG, DEV_BRANCH, devIdentity, baseVersionOf, readPackageAt, DEV_CHANNEL_WARNING, } from './version-info.js';
-export { DEV_CHANNEL_WARNING };
-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 ? ' (部分请求失败)' : ''}`;
-}
-// ── HTTP ────────────────────────────────────────────────────────────────────
-const OFFLINE_CODES = new Set(['ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EHOSTUNREACH', 'ENETUNREACH', 'ENETDOWN', 'EAI_FAIL', 'UND_ERR_CONNECT_TIMEOUT', 'CERT_HAS_EXPIRED']);
+import { classifyGithubError, } from './dual-source-facts.js';
+/**
+ * 纯语义那一半 (错误分类 / 交叉校验 / dev 快照比较 / 报告渲染) —— **唯一一份在
+ * `dual-source-facts.ts`** (桌面与手机端共用)。这里原样再导出: 桌面既有 import 路径不变,
+ * 手机端 WebView 直接 import 那份纯模块 (没有 `node:` ⇒ 能进 bundle)。
+ */
+export { GITHUB_REASONS, OFFLINE_CODES, classifyGithubError, classifyRegistryError, newestGithubVersion, numericCompare, toGithubReport, renderGithubReportLine, crossCheckStable, compareDevSnapshots, DEV_CHANNEL_WARNING, } from './dual-source-facts.js';
 /** 可选 GitHub token (只为提配额: 匿名 60 次/小时, 认证 5000 次/小时)。**永不打印、永不入库**。 */
 function githubToken(env = process.env) {
     const t = env.GITHUB_TOKEN || env.GH_TOKEN || env.BOLLOON_GITHUB_TOKEN;
@@ -74,26 +58,6 @@ function httpGetRaw(url, timeoutMs, token) {
         req.on('timeout', () => { req.destroy(new Error('timeout')); });
     });
 }
-/** 网络类 → 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 code = String(err?.code || '');
-    if (OFFLINE_CODES.has(code) || /timeout|timed out|ENOTFOUND|getaddrinfo|network|socket hang up|超时/i.test(String(err?.message || ''))) {
-        return { kind: 'github_unavailable', reason: 'offline', detail: `${code || err?.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: code || err?.message || '未知错误', retryAt: null };
-}
 /**
  * 查 GitHub 的三个事实: Releases / Tags / master HEAD。
  * **任何一个请求失败 → 整条 `github_unavailable`** (带分类), 但把已拿到的那部分 facts 一起带回去
@@ -172,99 +136,6 @@ export async function fetchGithubFacts(opts = {}) {
     }
     return { ok: true, facts };
 }
-/** 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];
-}
-/** 只比数值段 (与 update-manager 的 compareVersions 同语义, 这里不反向依赖它)。 */
-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 判定, 不看版本号)`,
-    };
-}
 function defaultRunNpm(args, cwd) {
     const r = spawnSync('npm', args, { cwd, encoding: 'utf-8', timeout: 900_000, maxBuffer: 32 * 1024 * 1024 });
     return { code: r.status ?? 1, stdout: r.stdout || '', stderr: r.stderr || '' };

package/dist/utils/update-manager.js

@@ -25,10 +25,16 @@ import * as https from 'https';
 import * as http from 'http';
 import { spawnSync } from 'child_process';
 import { PKG_NAME, CONSTRAINT_PKG_NAME, NPM_REGISTRY_BASE, resolveUpdateChannel, distTagForChannel, detectInstallation, readPackageAt, channelKindOf, isDevIdentity, devShaFromIdentity, devIdentity, baseVersionOf, DEV_CHANNEL_WARNING, DEV_BACK_TO_STABLE_HINT, } from './version-info.js';
+import { parseVersion, compareVersions, isKnownVersion, checkExitCode, REFUSED_STATUSES, } from './version-identity.js';
+// registry 侧的错误分类也在纯那一半 (手机端要用同一份分类) —— 定义在 dual-source-facts.ts。
+import { classifyRegistryError } from './dual-source-facts.js';
 import { fetchGithubFacts, toGithubReport, crossCheckStable, compareDevSnapshots, prepareDevSnapshot, renderGithubReportLine, } from './dual-source.js';
 import { readUpdateState, writeUpdateState, appendUpdateHistory, readUpdateHistory, acquireUpdateLock, releaseUpdateLock, readUpdateLock, lockIsStale, readUpdatePrefs, } from './update-state.js';
 export { DEV_CHANNEL_WARNING, DEV_BACK_TO_STABLE_HINT };
-// ── 版本比较 (唯一一份) ─────────────────────────────────────────────────────
+// 版本比较 / 结论→退出码 / 拒绝语义: **唯一一份在 `version-identity.ts`** (桌面与手机共用)。
+// 这里原样再导出, 避免出现第二套实现 (手机端 WebView 里也要判同一批结论)。
+export { parseVersion, compareVersions, isKnownVersion, checkExitCode, REFUSED_STATUSES };
+// ── 版本比较 (唯一一份在 version-identity.ts; 上面已再导出) ────────────────
 /**
  * 从子进程 stdout 里取 JSON —— **不要**按"行首是否 { "过滤:
  * `JSON.stringify(x, null, 2)` 是**多行**的, 只留第一行 `{` 会解析失败
@@ -56,28 +62,6 @@ export function parseJsonFromStdout(stdout) {
         return null;
     }
 }
-export function parseVersion(v) {
-    const clean = String(v || '').trim().replace(/^v/, '').split('-')[0];
-    const parts = clean.split('.').map((p) => parseInt(p.replace(/\D.*$/, ''), 10));
-    return parts.map((n) => (Number.isFinite(n) ? n : 0));
-}
-/** -1 = a<b, 0 = 相等, 1 = a>b (只比数值段, 忽略预发布标签) */
-export function compareVersions(a, b) {
-    const pa = parseVersion(a);
-    const pb = parseVersion(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;
-}
-export function isKnownVersion(v) {
-    return !!v && v !== 'unknown' && /^\d/.test(String(v).trim().replace(/^v/, ''));
-}
 function httpGetJson(url, timeoutMs = 10000) {
     return new Promise((resolve, reject) => {
         const client = url.startsWith('https') ? https : http;
@@ -90,21 +74,11 @@ function httpGetJson(url, timeoutMs = 10000) {
         req.on('timeout', () => { req.destroy(new Error('timeout')); });
     });
 }
-const OFFLINE_CODES = new Set(['ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EHOSTUNREACH', 'ENETUNREACH', 'ENETDOWN', 'EAI_FAIL', 'UND_ERR_CONNECT_TIMEOUT']);
-/** 网络类错误 → offline; 其它 (HTTP 5xx / 解析失败 / 包不存在) → registry_unavailable。 */
-export function classifyRegistryError(err, httpStatus) {
-    const code = String(err?.code || '');
-    if (OFFLINE_CODES.has(code) || /timeout|timed out|ENOTFOUND|getaddrinfo|network|socket hang up|超时/i.test(String(err?.message || ''))) {
-        return { kind: 'offline', detail: `${code || err?.message || '网络不可达'}` };
-    }
-    if (httpStatus && httpStatus >= 500)
-        return { kind: 'registry_unavailable', detail: `registry 返回 HTTP ${httpStatus}` };
-    if (httpStatus === 404)
-        return { kind: 'registry_unavailable', detail: `registry 上没有 ${PKG_NAME} (HTTP 404)` };
-    if (httpStatus && httpStatus >= 400)
-        return { kind: 'registry_unavailable', detail: `registry 返回 HTTP ${httpStatus}` };
-    return { kind: 'registry_unavailable', detail: code || err?.message || '未知错误' };
-}
+/**
+ * 网络类错误 → offline; 其它 (HTTP 5xx / 解析失败 / 包不存在) → registry_unavailable。
+ * **唯一一份在 `dual-source-facts.ts`** (上面已 import+再导出) —— 桌面与手机端同一个分类器。
+ */
+export { classifyRegistryError };
 export async function queryRegistryDoc(pkg = PKG_NAME, timeoutMs = 10000) {
     const url = `${NPM_REGISTRY_BASE}/${encodeURIComponent(pkg).replace('%40', '@')}`;
     try {
@@ -136,28 +110,11 @@ export async function queryRegistryDoc(pkg = PKG_NAME, timeoutMs = 10000) {
     }
 }
 /**
- * 检查结论 → 退出码 (稳定约定, §2): 0 正常 / 2 检查不可用。
- *
+ * 检查结论 → 退出码 / "源不可达必拒" 的这一组结论:
+ * **唯一一份在 `version-identity.ts`** (上面已 import+再导出)。
  * §12.5 的核心就是这一句: **源不可达 / 版本不存在 → 拒绝并说清 (退出码 2)**,
- * 不许静默装回旧版, 也不许打印"✅ 已是最新"。
- */
-export function checkExitCode(status) {
-    switch (status) {
-        case 'offline':
-        case 'registry_unavailable':
-        case 'local_version_unknown':
-        case 'github_unavailable':
-        case 'cross_check_mismatch':
-            return 2;
-        default:
-            return 0;
-    }
-}
-/**
- * "源不可达 / 版本不存在" 这一组结论 —— 它们必须**拒绝执行并说清**。
- * 这是 §12.5 那一条的代码落点: 不许静默装回旧版, 也不许打印"已是最新"。
+ * 不许静默装回旧版, 也不许打印"✅ 已是最新"。桌面与手机共用同一份。
  */
-export const REFUSED_STATUSES = ['offline', 'registry_unavailable', 'local_version_unknown', 'github_unavailable', 'cross_check_mismatch'];
 /**
  * 检查更新。**这是唯一的检查入口** —— CLI / 启动后台 / Python 检查器 / 安装脚本都走它。
  *
@@ -775,7 +732,7 @@ export async function applyUpdate(opts = {}) {
     if (!lock.ok) {
         const held = lock.heldBy;
         await stage('blocked', `已有更新进程 (pid ${held?.pid})`);
-        return record({ stage: 'blocked', ok: false, from, to, durationMs: Date.now() - started, reason: `已有更新进程持有锁 (pid ${held?.pid}, ${held?.at})`, needsRestart: false }, 'blocked');
+        return record({ stage: 'blocked', ok: false, from, to, durationMs: Date.now() - started, reason: `另一个更新进程持有锁 (pid ${held?.pid}, ${held?.at})`, needsRestart: false }, 'blocked');
     }
     const tmpRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'bolloon-update-'));
     const runNpm = opts.runNpm || defaultRunNpm;

package/dist/utils/update-state.js

@@ -17,25 +17,13 @@ import * as path from 'path';
 import * as fs from 'fs';
 import * as fsp from 'fs/promises';
 import { resolveBolloonHome } from '../setup/setup-store.js';
+import { CHECK_STATUSES } from './version-identity.js';
 // ── 枚举 (冻结: 出口/状态都不许临时造词) ────────────────────────────────────
-/**
- * 一次"检查"的结论。**9 个值就是全部**, 不认识的一律落进 registry_unavailable 并带原因。
- *
- * 2026-09-25 (update-protocol §12.3, 双源): **只增不改** —— 新增 2 个, 错误分类**不合并**:
- *   github_unavailable     GitHub 不可达 / 403·429 限流 / 没有 Release / 没有 master
- *   cross_check_mismatch   stable 下 npm 与 GitHub 指向不同版本 (两个源的事实都摆出来)
- */
-export const CHECK_STATUSES = [
-    'up_to_date', // 确认最新
-    'update_available', // 有新版本
-    'check_skipped', // 节流/显式跳过, 结论来自缓存
-    'offline', // 网络不可达 (≠ 最新)
-    'registry_unavailable', // 可达但拿不到有效数据 (5xx / 包不存在 / 无 dist-tags)
-    'local_version_unknown', // 读不到本地版本 (不猜 0.0.0)
-    'unsupported_installation', // 认得出本地版本, 但这种安装方式不支持自动更新
-    'github_unavailable', // GitHub 源不可用 (offline / rate_limited / not_found / http_error)
-    'cross_check_mismatch', // npm 与 GitHub 两个源不一致 → 拒绝更新
-];
+//
+// 2026-09-26: 结论枚举与 UpdatePrefs 的结构定义抽到 `version-identity.ts` (纯模块, 无 node:)。
+// **只有一个原因**: 手机端 WebView 里没有 `fs`/`os`, 但手机端必须用**同一份**结论语义
+// (9 个结论 + REFUSED_STATUSES 的拒绝口径)。这里原样再导出, 既有 import 路径不变。
+export { CHECK_STATUSES };
 /** 一次"更新执行"的流水线状态。 */
 export const UPDATE_RUN_STATUSES = [
     'planned', 'downloading', 'staged', 'switching', 'verifying',

package/dist/utils/version-identity.js

@@ -0,0 +1,176 @@
+/**
+ * version-identity.ts — 版本身份 / 通道 / 结论分类的**纯词汇表** (2026-09-26)
+ *
+ * 为什么要从 `version-info.ts` 里抽出来 (抽出 ≠ 改写): 手机端 WebView **没有 node:**
+ * (`fs`/`os`/`path`/`child_process` 都没有), 而手机端双源更新必须用**和桌面同一份**
+ * 身份与结论语义 —— 否则同一台机器上的 `bolloon update status` 和手机上的"当前源"
+ * 会长出两套说法。所以:
+ *
+ *   本模块 = **不碰 node 的那一半** (纯函数 + 常量), 桌面与手机都 import 它;
+ *   `version-info.ts` = 本模块 + 需要 node 的探测 (安装识别 / git / npm / python / VersionInfo)
+ *
+ * 纪律 (改这里之前先读):
+ *   · 不许 import 任何 `node:*` / 不许在模块顶层直读 `process.env` (浏览器里会 ReferenceError);
+ *     环境变量一律走 `envValue()` (`typeof process` 守卫)。
+ *   · 版本比较语义与结论枚举**只此一份** (§12.1 / §3): stable 比 semver, dev 比 commit sha。
+ */
+// ── 包与上游 ────────────────────────────────────────────────────────────────
+export const PKG_NAME = '@bolloon/bolloon-agent';
+export const CONSTRAINT_PKG_NAME = '@bolloon/constraint-runtime';
+export const UPSTREAM_REPO = 'https://github.com/logos-42/bolloon';
+/** GitHub 上游 (owner/repo) —— 与 UPSTREAM_REPO 同一处, 这里给 API 用。 */
+export const GITHUB_UPSTREAM_SLUG = 'logos-42/bolloon';
+/**
+ * 环境变量读取 (浏览器安全的唯一入口)。
+ * `process` 在 WebView 里不存在 —— 直接写 `process.env.X` 会在**模块求值期**抛,
+ * 表现为整页 JS 不执行 (那样的红只有真浏览器能看见)。这里用 `typeof` 守卫。
+ */
+export function envValue(key) {
+    try {
+        // ① 壳层/页面的配置通道 (浏览器没有 process.env; 手机端由原生壳或验收 harness 注入)
+        const cfg = globalThis?.__bolloonUpdateConfig;
+        if (cfg && cfg[key] !== undefined && cfg[key] !== null)
+            return String(cfg[key]);
+        // ② 进程环境 (桌面 CLI / Node 验收)
+        const env = typeof process !== 'undefined' ? process?.env : null;
+        const v = env ? env[key] : undefined;
+        return v === undefined || v === null ? undefined : String(v);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** npm registry (可用 BOLLOON_NPM_REGISTRY 指向镜像/内网; 末尾斜杠统一去掉) */
+export const NPM_REGISTRY_BASE = (envValue('BOLLOON_NPM_REGISTRY') || 'https://registry.npmjs.org').replace(/\/+$/, '');
+/** GitHub API 根 (可被 BOLLOON_GITHUB_API 覆盖 → 受控假 API / 企业实例)。 */
+export const GITHUB_API_BASE = (envValue('BOLLOON_GITHUB_API') || 'https://api.github.com').replace(/\/+$/, '');
+/** dev 通道盯的分支 (冻结: master)。 */
+export const DEV_BRANCH = 'master';
+export const DEV_REF = `refs/heads/${DEV_BRANCH}`;
+// ── 安装方式 / 来源 / 通道 ──────────────────────────────────────────────────
+export const INSTALL_METHODS = [
+    'npm-global', 'npm-local', 'source-git', 'release-binary', 'development', 'unknown',
+];
+export const UPDATE_SOURCES = ['npm', 'github-release', 'git', 'unknown'];
+export const UPDATE_CHANNELS = ['stable', 'beta', 'dev'];
+/** 发行通道: 环境变量 > 配置 > stable。npm 只有 `latest` (stable) 一个 dist-tag, beta/dev 暂走同一标签。 */
+export function resolveUpdateChannel(explicit, env) {
+    const raw = (explicit || (env ? env.BOLLOON_UPDATE_CHANNEL : envValue('BOLLOON_UPDATE_CHANNEL')) || '').trim().toLowerCase();
+    if (raw === 'stable' || raw === 'beta' || raw === 'dev')
+        return raw;
+    return 'stable';
+}
+/** dist-tag 映射: stable → latest; beta/dev 暂与 stable 同源 (明说, 不假装有独立通道)。 */
+export function distTagForChannel(channel) {
+    return channel === 'beta' ? 'beta' : 'latest';
+}
+// ── 身份 (dev 用 commit sha, 不用 semver) ───────────────────────────────────
+/**
+ * 版本比较语义 (显式, 不是隐含约定):
+ *   semver  —— stable: 按 semver 数值段比大小
+ *   git-ref —— dev: **不用 semver**, 只判"是否同一 commit / 是否落后"
+ */
+export const CHANNEL_KINDS = ['semver', 'git-ref'];
+export function channelKindOf(channel) {
+    return channel === 'dev' ? 'git-ref' : 'semver';
+}
+/** dev 快照身份里的后缀标记 (`0.4.33+dev.a1b2c3d`)。 */
+export const DEV_IDENTITY_SEP = '+dev.';
+/** dev 快照身份 —— 用 commit sha (不是 semver) 当身份, 版本号只作参考展示。 */
+export function devIdentity(baseVersion, sha) {
+    return `${baseVersionOf(baseVersion)}${DEV_IDENTITY_SEP}${String(sha).slice(0, 7)}`;
+}
+/** 去掉 `+dev.<sha>` 后缀, 拿到基础版本号 (stable 目标的比对基准)。 */
+export function baseVersionOf(v) {
+    return String(v || '').split(DEV_IDENTITY_SEP)[0].trim();
+}
+/** 这个版本号是不是一个 dev 快照身份。 */
+export function isDevIdentity(v) {
+    return String(v || '').includes(DEV_IDENTITY_SEP);
+}
+/** 从 dev 身份里取 commit sha (前 7 位); 不是 dev 身份返回 null。 */
+export function devShaFromIdentity(v) {
+    if (!isDevIdentity(v))
+        return null;
+    const sha = String(v).split(DEV_IDENTITY_SEP)[1]?.trim();
+    return sha ? sha : null;
+}
+/**
+ * dev 通道的**唯一一句警告** (§12.4 硬约束 1) —— 检查 / 计划 / 执行 / 手机端四处打印同一句话。
+ * 定义在这里 (唯一事实层), 由 dual-source / update-manager / CLI / 手机端复用, 不允许各处自己造一句。
+ */
+export const DEV_CHANNEL_WARNING = '⚠️ dev 通道 = GitHub master HEAD 的即时快照 (未走发布门): 可能中断正在跑的 Goal/Run, 且不保证可回滚到上一个 dev 版。';
+/** 一键回 stable 的提示语 (同一份措辞)。 */
+export const DEV_BACK_TO_STABLE_HINT = '一键回稳定版: bolloon update now --channel stable';
+/** 手机端同一件事的说法 (原生层规则不同: 手机走 web 层 OTA, 不是 npm 全局安装)。 */
+export const DEV_BACK_TO_STABLE_HINT_MOBILE = '一键回稳定版: 手机端「更新」页 → 切回 stable';
+// ── 版本比较 (唯一一份) ─────────────────────────────────────────────────────
+export function parseVersion(v) {
+    const clean = String(v || '').trim().replace(/^v/, '').split('-')[0];
+    const parts = clean.split('.').map((p) => parseInt(p.replace(/\D.*$/, ''), 10));
+    return parts.map((n) => (Number.isFinite(n) ? n : 0));
+}
+/** -1 = a<b, 0 = 相等, 1 = a>b (只比数值段, 忽略预发布标签) */
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(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;
+}
+export function isKnownVersion(v) {
+    return !!v && v !== 'unknown' && /^\d/.test(String(v).trim().replace(/^v/, ''));
+}
+// ── 检查结论 + 拒绝语义 (§3 / §12.3 / §12.5) ────────────────────────────────
+/**
+ * 一次"检查"的结论。**9 个值就是全部** (桌面侧), 不认识的一律落进 registry_unavailable 并带原因。
+ *
+ * 2026-09-25 (update-protocol §12.3, 双源): **只增不改** —— 新增 2 个, 错误分类**不合并**:
+ *   github_unavailable     GitHub 不可达 / 403·429 限流 / 没有 Release / 没有 master
+ *   cross_check_mismatch   stable 下 npm 与 GitHub 指向不同版本 (两个源的事实都摆出来)
+ */
+export const CHECK_STATUSES = [
+    'up_to_date', // 确认最新
+    'update_available', // 有新版本
+    'check_skipped', // 节流/显式跳过, 结论来自缓存
+    'offline', // 网络不可达 (≠ 最新)
+    'registry_unavailable', // 可达但拿不到有效数据 (5xx / 包不存在 / 无 dist-tags)
+    'local_version_unknown', // 读不到本地版本 (不猜 0.0.0)
+    'unsupported_installation', // 认得出本地版本, 但这种安装方式不支持自动更新
+    'github_unavailable', // GitHub 源不可用 (offline / rate_limited / not_found / http_error)
+    'cross_check_mismatch', // npm 与 GitHub 两个源不一致 → 拒绝更新
+];
+/**
+ * "源不可达 / 版本不存在" 这一组结论 —— 它们必须**拒绝执行并说清**。
+ * 这是 §12.5 那一条的代码落点: 不许静默装回旧版, 也不许打印"已是最新"。
+ *
+ * **桌面与手机共用同一份** —— 手机上这几个状态同样会让 apply 直接 blocked, 一个字节都不下载。
+ */
+export const REFUSED_STATUSES = ['offline', 'registry_unavailable', 'local_version_unknown', 'github_unavailable', 'cross_check_mismatch'];
+/** 检查结论 → 退出码 (稳定约定, §2): 0 正常 / 2 检查不可用。 */
+export function checkExitCode(status) {
+    switch (status) {
+        case 'offline':
+        case 'registry_unavailable':
+        case 'local_version_unknown':
+        case 'github_unavailable':
+        case 'cross_check_mismatch':
+            return 2;
+        default:
+            return 0;
+    }
+}
+// ── 身份那一行的渲染 (§12.5: 桌面与手机同一份措辞) ──────────────────────────
+/** 双源身份那一行 (谁装的 / 哪个 sha / 能切回哪) —— 桌面 `--version`/`update status` 与手机端共用同一份措辞。 */
+export function describeSourceIdentity(info) {
+    const src = info.installedDevSha ? 'dev (GitHub master 快照)' : 'stable (npm registry)';
+    const ident = info.installedDevSha ? `commit ${info.installedDevSha}` : baseVersionOf(info.packageVersion);
+    const back = info.switchableTo ? ` · 可切回 ${info.switchableTo.channel} (${info.switchableTo.source})` : '';
+    return `当前安装源: ${src} · 版本/commit: ${ident} · 比较语义: ${info.channelKind}${back}`;
+}

package/dist/utils/version-info.js

@@ -26,79 +26,13 @@ import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { resolveBolloonHome } from '../setup/setup-store.js';
 import { renderRuntimeLines } from './runtime-bootstrap.js';
-export const PKG_NAME = '@bolloon/bolloon-agent';
-export const CONSTRAINT_PKG_NAME = '@bolloon/constraint-runtime';
-/** npm registry (可用 BOLLOON_NPM_REGISTRY 指向镜像/内网; 末尾斜杠统一去掉) */
-export const NPM_REGISTRY_BASE = (process.env.BOLLOON_NPM_REGISTRY || 'https://registry.npmjs.org').replace(/\/+$/, '');
-export const UPSTREAM_REPO = 'https://github.com/logos-42/bolloon';
-export const INSTALL_METHODS = [
-    'npm-global', 'npm-local', 'source-git', 'release-binary', 'development', 'unknown',
-];
-export const UPDATE_SOURCES = ['npm', 'github-release', 'git', 'unknown'];
-export const UPDATE_CHANNELS = ['stable', 'beta', 'dev'];
-/** 发行通道: 环境变量 > 配置 > stable。npm 只有 `latest` (stable) 一个 dist-tag, beta/dev 暂走同一标签。 */
-export function resolveUpdateChannel(explicit) {
-    const raw = (explicit || process.env.BOLLOON_UPDATE_CHANNEL || '').trim().toLowerCase();
-    if (raw === 'stable' || raw === 'beta' || raw === 'dev')
-        return raw;
-    return 'stable';
-}
-/** dist-tag 映射: stable → latest; beta/dev 暂与 stable 同源 (明说, 不假装有独立通道)。 */
-export function distTagForChannel(channel) {
-    return channel === 'beta' ? 'beta' : 'latest';
-}
-// ── 双源 (update-protocol §12, 2026-09-25) ──────────────────────────────────
-//
-// stable: npm registry (`dist-tags.latest`) 是**权威**, GitHub Release/Tag 是**交叉校验源**;
-// dev   : GitHub `master` HEAD 是**唯一源**, 版本身份 = `<package.json 版本>+dev.<commit sha 前 7>`。
-//
-// 两条硬口径 (从这里开始, 全局只有这一份):
-//   ① 两套版本比较语义**显式分开** —— stable 比 semver, dev 比 commit sha (`ChannelKind`)
-//   ② 源不可达 / 版本不存在 → **拒绝并说清**, 不许静默装回旧版 (§12.5)
-/** GitHub 上游 (owner/repo) —— 与 UPSTREAM_REPO 同一处, 这里给 API 用。 */
-export const GITHUB_UPSTREAM_SLUG = 'logos-42/bolloon';
-/** GitHub API 根 (可被 BOLLOON_GITHUB_API 覆盖 → 受控假 API / 企业实例)。 */
-export const GITHUB_API_BASE = (process.env.BOLLOON_GITHUB_API || 'https://api.github.com').replace(/\/+$/, '');
-/** dev 通道盯的分支 (冻结: master)。 */
-export const DEV_BRANCH = 'master';
-export const DEV_REF = `refs/heads/${DEV_BRANCH}`;
+import { PKG_NAME, CONSTRAINT_PKG_NAME, UPSTREAM_REPO, GITHUB_UPSTREAM_SLUG, INSTALL_METHODS, UPDATE_SOURCES, UPDATE_CHANNELS, CHANNEL_KINDS, DEV_BRANCH, DEV_REF, DEV_IDENTITY_SEP, DEV_CHANNEL_WARNING, DEV_BACK_TO_STABLE_HINT, NPM_REGISTRY_BASE, GITHUB_API_BASE, resolveUpdateChannel, distTagForChannel, channelKindOf, devIdentity, baseVersionOf, isDevIdentity, devShaFromIdentity, parseVersion, compareVersions, isKnownVersion, checkExitCode, REFUSED_STATUSES, CHECK_STATUSES, describeSourceIdentity, } from './version-identity.js';
 /**
- * 版本比较语义 (显式, 不是隐含约定):
- *   semver  —— stable: 按 semver 数值段比大小
- *   git-ref —— dev: **不用 semver**, 只判"是否同一 commit / 是否落后"
+ * 版本身份 / 通道 / 结论分类的**纯词汇表**已抽到 `version-identity.ts` (2026-09-26),
+ * 这里原样再导出 —— 既有 import 路径 (`from './version-info.js'`) 一行都不用改,
+ * 手机端 (无 node:) 直接 import 那份纯模块即可, 两边共用同一套语义。
  */
-export const CHANNEL_KINDS = ['semver', 'git-ref'];
-export function channelKindOf(channel) {
-    return channel === 'dev' ? 'git-ref' : 'semver';
-}
-/** dev 快照身份里的后缀标记 (`0.4.33+dev.a1b2c3d`)。 */
-export const DEV_IDENTITY_SEP = '+dev.';
-/** dev 快照身份 —— 用 commit sha (不是 semver) 当身份, 版本号只作参考展示。 */
-export function devIdentity(baseVersion, sha) {
-    return `${baseVersionOf(baseVersion)}${DEV_IDENTITY_SEP}${String(sha).slice(0, 7)}`;
-}
-/**
- * dev 通道的**唯一一句警告** (§12.4 硬约束 1) —— 检查 / 计划 / 执行三处打印同一句话。
- * 定义在这里 (唯一事实层), 由 dual-source / update-manager / CLI 复用, 不允许各处自己造一句。
- */
-export const DEV_CHANNEL_WARNING = '⚠️ dev 通道 = GitHub master HEAD 的即时快照 (未走发布门): 可能中断正在跑的 Goal/Run, 且不保证可回滚到上一个 dev 版。';
-/** 一键回 stable 的提示语 (同一份措辞)。 */
-export const DEV_BACK_TO_STABLE_HINT = '一键回稳定版: bolloon update now --channel stable';
-/** 去掉 `+dev.<sha>` 后缀, 拿到基础版本号 (stable 目标的比对基准)。 */
-export function baseVersionOf(v) {
-    return String(v || '').split(DEV_IDENTITY_SEP)[0].trim();
-}
-/** 这个版本号是不是一个 dev 快照身份。 */
-export function isDevIdentity(v) {
-    return String(v || '').includes(DEV_IDENTITY_SEP);
-}
-/** 从 dev 身份里取 commit sha (前 7 位); 不是 dev 身份返回 null。 */
-export function devShaFromIdentity(v) {
-    if (!isDevIdentity(v))
-        return null;
-    const sha = String(v).split(DEV_IDENTITY_SEP)[1]?.trim();
-    return sha ? sha : null;
-}
+export { PKG_NAME, CONSTRAINT_PKG_NAME, UPSTREAM_REPO, GITHUB_UPSTREAM_SLUG, INSTALL_METHODS, UPDATE_SOURCES, UPDATE_CHANNELS, CHANNEL_KINDS, DEV_BRANCH, DEV_REF, DEV_IDENTITY_SEP, DEV_CHANNEL_WARNING, DEV_BACK_TO_STABLE_HINT, NPM_REGISTRY_BASE, GITHUB_API_BASE, resolveUpdateChannel, distTagForChannel, channelKindOf, devIdentity, baseVersionOf, isDevIdentity, devShaFromIdentity, parseVersion, compareVersions, isKnownVersion, checkExitCode, REFUSED_STATUSES, CHECK_STATUSES, describeSourceIdentity, };
 // ── 包根定位 ────────────────────────────────────────────────────────────────
 /**
  * 从当前模块 URL 定位**运行中的**包根。
@@ -509,13 +443,10 @@ export function describeUpdateLine(info) {
         default: return `更新检查: ${u.lastCheckStatus}`;
     }
 }
-/** 双源身份那一行 (谁装的 / 哪个 sha / 能切回哪) —— `--version` 与 `update status` 共用同一份措辞。 */
-export function describeSourceIdentity(info) {
-    const src = info.installedDevSha ? 'dev (GitHub master 快照)' : 'stable (npm registry)';
-    const ident = info.installedDevSha ? `commit ${info.installedDevSha}` : baseVersionOf(info.packageVersion);
-    const back = info.switchableTo ? ` · 可切回 ${info.switchableTo.channel} (${info.switchableTo.source})` : '';
-    return `当前安装源: ${src} · 版本/commit: ${ident} · 比较语义: ${info.channelKind}${back}`;
-}
+/**
+ * 双源身份那一行 (谁装的 / 哪个 sha / 能切回哪) —— 已在 `version-identity.ts` (唯一一份,
+ * 桌面 `--version` 与 `update status` 共用同一份措辞)。这里只留注释, 避免出现第二份实现。
+ */
 export function renderVersionText(info, opts = {}) {
     if (opts.verbose) {
         const lines = [

package/dist/web/bolloon-web.json

@@ -0,0 +1,10 @@
+{
+  "schema": "bolloon-mobile-web/1",
+  "version": "0.5.2",
+  "channel": "stable",
+  "build": "stable",
+  "commit": "0f98f0fc9bbcd60f04105402a5163b85c58bc785",
+  "builtAt": "2026-09-28T08:27:37.768Z",
+  "layer": "web",
+  "note": "web 资源层构建戳 (手机端 OTA 的身份第 ③ 级回退; 装机后以 OTA state.json 为准)"
+}