@bolloon/bolloon-agent 0.4.33 → 0.5.1

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 判定, 不看版本号)`,
+    };
+}

package/dist/utils/dual-source.js

@@ -0,0 +1,297 @@
+/**
+ * dual-source.ts — 双源 (npm registry + GitHub) 的**源事实** (2026-09-25, update-protocol §12)
+ *
+ * 为什么单独一个模块: §1.4 冻结的是 "npm 是唯一稳定渠道", §12 把它改成**双源但权威顺序不变**。
+ * 这件事不该塞进 update-manager (那会让"唯一决策者"同时变成"网络客户端"), 也不该让
+ * CLI / 健康检查各自造一份 GitHub 事实。所以:
+ *
+ *   - 源事实 (GitHub 可达性 / tag / Release / master HEAD) 只在本模块查
+ *   - 错误分类 `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 缺" 时
+ *     如实报 "发布记录缺 Tag / Release" (提醒级), **不是** fake 一个 Release 出来
+ */
+import * as fs from 'fs';
+import * as fsp from 'fs/promises';
+import * as path from 'path';
+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';
+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;
+    return t && String(t).trim() ? String(t).trim() : null;
+}
+function httpGetRaw(url, timeoutMs, token) {
+    return new Promise((resolve, reject) => {
+        const client = url.startsWith('https') ? https : http;
+        const req = client.get(url, {
+            timeout: timeoutMs,
+            headers: {
+                Accept: 'application/vnd.github+json, application/json',
+                'User-Agent': 'bolloon-update',
+                // token 只进请求头, 不进日志/状态/输出 (凭证红线)
+                ...(token ? { Authorization: `Bearer ${token}` } : {}),
+            },
+        }, (res) => {
+            let data = '';
+            res.on('data', (c) => { data += c; });
+            res.on('end', () => resolve({ status: res.statusCode || 0, body: data, headers: (res.headers || {}) }));
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(new Error('timeout')); });
+    });
+}
+/**
+ * 查 GitHub 的三个事实: Releases / Tags / master HEAD。
+ * **任何一个请求失败 → 整条 `github_unavailable`** (带分类), 但把已拿到的那部分 facts 一起带回去
+ * (上层因此能说清"哪些拿到了、哪些没拿到", 而不是一句"更新失败")。
+ */
+export async function fetchGithubFacts(opts = {}) {
+    const base = (opts.apiBase || GITHUB_API_BASE).replace(/\/+$/, '');
+    const slug = opts.slug || GITHUB_UPSTREAM_SLUG;
+    const timeout = opts.timeoutMs ?? 10000;
+    // 有 token 就用 (配额 60/h → 5000/h); 没有也能跑, 只是可能 403 限流
+    const token = opts.token !== undefined ? opts.token : githubToken();
+    const missing = [];
+    let releases = [];
+    let tags = [];
+    let headSha = null;
+    /** 失败累积 (第一个失败决定分类, 但所有失败都记进 missing) */
+    const failures = [];
+    const note = (e, what) => {
+        missing.push(what);
+        failures.push({ reason: e.reason, detail: `${what}: ${e.detail}`, retryAt: e.retryAt });
+    };
+    // 1. Releases (本仓真的没有 → 200 + [] , 不是错误)
+    try {
+        const r = await httpGetRaw(`${base}/repos/${slug}/releases?per_page=100`, timeout, token);
+        if (r.status >= 200 && r.status < 300) {
+            const arr = JSON.parse(r.body);
+            releases = Array.isArray(arr) ? arr.map((x) => String(x?.tag_name || '')).filter(Boolean) : [];
+        }
+        else {
+            note(classifyGithubError(null, r.status, r.headers), 'releases');
+        }
+    }
+    catch (e) {
+        note(classifyGithubError(e), 'releases');
+    }
+    // 2. Tags
+    try {
+        const r = await httpGetRaw(`${base}/repos/${slug}/tags?per_page=100`, timeout, token);
+        if (r.status >= 200 && r.status < 300) {
+            const arr = JSON.parse(r.body);
+            tags = Array.isArray(arr)
+                ? arr.map((x) => ({ name: String(x?.name || ''), sha: x?.commit?.sha ? String(x.commit.sha) : null })).filter((t) => t.name)
+                : [];
+        }
+        else {
+            note(classifyGithubError(null, r.status, r.headers), 'tags');
+        }
+    }
+    catch (e) {
+        note(classifyGithubError(e), 'tags');
+    }
+    // 3. master HEAD (dev 通道的身份来源)
+    try {
+        const r = await httpGetRaw(`${base}/repos/${slug}/commits/${DEV_BRANCH}`, timeout, token);
+        if (r.status >= 200 && r.status < 300) {
+            const j = JSON.parse(r.body);
+            headSha = j?.sha ? String(j.sha) : null;
+            if (!headSha)
+                note({ reason: 'parse_error', detail: 'commits/master 没有 sha 字段', retryAt: null }, 'head');
+        }
+        else {
+            // 404 在这里的语义就是"没有 master 分支"(§12.3)
+            note(classifyGithubError(null, r.status, r.headers), 'head');
+        }
+    }
+    catch (e) {
+        note(classifyGithubError(e), 'head');
+    }
+    const facts = {
+        slug, ref: `refs/heads/${DEV_BRANCH}`, headSha, releases, tags,
+        fetchedAt: new Date().toISOString(), partial: missing.length > 0, missing,
+    };
+    if (failures.length > 0) {
+        const first = failures[0];
+        return { ok: false, kind: 'github_unavailable', reason: first.reason, detail: first.detail, retryAt: first.retryAt, facts };
+    }
+    return { ok: true, facts };
+}
+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 || '' };
+}
+/** 从 GitHub 取 master 的源码快照 (codeload tarball); 解到 destParent。 */
+async function downloadGithubSnapshot(sha, destParent, env, timeoutMs) {
+    const template = env.BOLLOON_DEV_TARBALL_URL
+        || `https://codeload.github.com/${GITHUB_UPSTREAM_SLUG}/tar.gz/{sha}`;
+    const url = template.replace('{sha}', sha).replace('{branch}', DEV_BRANCH);
+    await fsp.mkdir(destParent, { recursive: true });
+    const file = path.join(destParent, `dev-${sha.slice(0, 7)}.tar.gz`);
+    try {
+        const buf = await new Promise((resolve, reject) => {
+            const client = url.startsWith('https') ? https : http;
+            const tk = githubToken(env);
+            const req = client.get(url, { timeout: timeoutMs, headers: { 'User-Agent': 'bolloon-update', ...(tk ? { Authorization: `Bearer ${tk}` } : {}) } }, (res) => {
+                if ((res.statusCode || 0) >= 400) {
+                    reject(classifyGithubError(null, res.statusCode, res.headers));
+                    return;
+                }
+                const chunks = [];
+                res.on('data', (c) => chunks.push(c));
+                res.on('end', () => resolve(Buffer.concat(chunks)));
+            });
+            req.on('error', reject);
+            req.on('timeout', () => { req.destroy(new Error('timeout')); });
+        });
+        await fsp.writeFile(file, buf);
+    }
+    catch (e) {
+        const cls = e?.kind === 'github_unavailable' ? e : classifyGithubError(e);
+        return { ok: false, kind: 'github_unavailable', reason: cls.reason, detail: `取 ${url} 失败: ${cls.detail}` };
+    }
+    const extract = path.join(destParent, 'src');
+    await fsp.mkdir(extract, { recursive: true });
+    const tar = spawnSync('tar', ['-xzf', file, '-C', extract], { encoding: 'utf-8', timeout: 300_000 });
+    if (tar.status !== 0)
+        return { ok: false, kind: 'github_unavailable', reason: 'http_error', detail: `解压快照失败: ${String(tar.stderr || '').slice(0, 200)}` };
+    const kids = (await fsp.readdir(extract)).filter((f) => !f.startsWith('.'));
+    if (kids.length !== 1)
+        return { ok: false, kind: 'github_unavailable', reason: 'http_error', detail: `快照解压后目录数不是 1 (${kids.length})` };
+    return { ok: true, dir: path.join(extract, kids[0]), source: 'github-tarball' };
+}
+/**
+ * 把 master HEAD 的一个 commit 变成**可安装的 dev 快照 tarball**:
+ *   取源码 → 校验 sha (本地源码树必须对得上) → 版本改成 `<base>+dev.<sha7>` → 需要时构建 → npm pack
+ *
+ * 复用原则 (§5 的刻意偏差): **不另造一套替换机制** —— 产物仍是 tarball, 仍交给 npm 替换,
+ * 仍然"切换后验证 + 失败回滚"。这里只负责"从哪个源取、装出来是什么身份"。
+ */
+export async function prepareDevSnapshot(opts) {
+    const env = opts.env ?? process.env;
+    const runNpm = opts.runNpm || defaultRunNpm;
+    const stage = (s, d) => { try {
+        opts.onStage?.(s, d);
+    }
+    catch { /* 回调不许影响流程 */ } };
+    const sha = String(opts.sha || '').trim();
+    if (!/^[0-9a-f]{7,40}$/i.test(sha)) {
+        return { ok: false, kind: 'github_unavailable', reason: 'not_found', detail: `master HEAD 的 sha 不合法 (${sha || '空'}) — 拒绝按未知 commit 安装` };
+    }
+    let dir = '';
+    let source = '';
+    const envDir = env.BOLLOON_DEV_SOURCE_DIR;
+    if (envDir) {
+        if (!fs.existsSync(path.join(envDir, 'package.json'))) {
+            return { ok: false, kind: 'dev_source_failed', reason: 'source_dir_missing', detail: `BOLLOON_DEV_SOURCE_DIR=${envDir} 下没有 package.json` };
+        }
+        // 本地源码树必须**真的**是这个 commit —— 否则不许把它当 master HEAD 的快照
+        const local = spawnSync('git', ['-C', envDir, 'rev-parse', 'HEAD'], { encoding: 'utf-8', timeout: 10_000, stdio: ['ignore', 'pipe', 'ignore'] });
+        const localSha = (local.stdout || '').trim();
+        if (local.status !== 0 || !localSha) {
+            if (env.BOLLOON_DEV_ALLOW_UNVERIFIED_SOURCE !== '1') {
+                return { ok: false, kind: 'dev_source_failed', reason: 'sha_unverifiable', detail: `${envDir} 不是 git 检出, 无法核对 sha=${sha.slice(0, 7)} (要强制使用请设 BOLLOON_DEV_ALLOW_UNVERIFIED_SOURCE=1)` };
+            }
+        }
+        else if (!localSha.startsWith(sha.slice(0, 7)) && !sha.startsWith(localSha.slice(0, 7))) {
+            return { ok: false, kind: 'dev_source_failed', reason: 'sha_mismatch', detail: `${envDir} 的 HEAD 是 ${localSha.slice(0, 7)}, 与 master HEAD ${sha.slice(0, 7)} 不是同一个 commit — 拒绝用错的源码做 dev 快照` };
+        }
+        dir = envDir;
+        source = `local-tree@${(localSha || sha).slice(0, 7)}`;
+    }
+    else {
+        stage('downloading', `取 GitHub master @ ${sha.slice(0, 7)}`);
+        const dl = await downloadGithubSnapshot(sha, opts.workDir, env, opts.timeoutMs ?? 120_000);
+        if (!dl.ok)
+            return dl;
+        dir = dl.dir;
+        source = dl.source;
+    }
+    // 身份 = 源码树自己的版本号 + dev.<sha>
+    const pkg = readPackageAt(dir);
+    if (!pkg?.version)
+        return { ok: false, kind: 'dev_source_failed', reason: 'no_version', detail: `${dir}/package.json 读不到版本` };
+    const baseVersion = baseVersionOf(String(pkg.version));
+    const identity = devIdentity(baseVersion, sha);
+    stage('staged', `打上 dev 身份 ${identity}`);
+    // 需要时构建 (GitHub tarball 里没有 dist/; 本地树通常已构建)
+    let built = false;
+    if (!fs.existsSync(path.join(dir, 'dist', 'cli-entry.js'))) {
+        stage('staged', '源码树缺少 dist/, 先装依赖再构建 (npm run build:main)');
+        if (!fs.existsSync(path.join(dir, 'node_modules'))) {
+            /**
+             * 验收加速开关: 把已有 node_modules 直接软链进来, 跳过 `npm install` (本仓依赖 889MB)。
+             * **只省"装依赖"这一步**, 构建与打包仍然真跑 —— 刻意留给验收脚本用, 别在生产路径上设。
+             */
+            const reuse = env.BOLLOON_DEV_REUSE_NODE_MODULES;
+            if (reuse && fs.existsSync(path.join(reuse, '.bin'))) {
+                stage('staged', `复用现成依赖 (${reuse}) 跳过 npm install`);
+                try {
+                    fs.symlinkSync(reuse, path.join(dir, 'node_modules'), 'dir');
+                }
+                catch { /* 已存在就跳过 */ }
+            }
+            else {
+                const inst = runNpm(['install', '--no-audit', '--no-fund', '--loglevel=error', '--fetch-retries=5'], dir);
+                if (inst.code !== 0) {
+                    return { ok: false, kind: 'dev_source_failed', reason: 'npm_install_failed', detail: `dev 快照装依赖失败: ${(inst.stderr || inst.stdout).slice(0, 400)}` };
+                }
+            }
+        }
+        /**
+         * 从 git 源码树构建要**两步** (真跑踩到的坑):
+         *   ① `npm run build --workspaces --if-present` —— 先建 workspace 依赖 (@bolloon/constraint-runtime),
+         *      否则根包 tsc 会因为 `../constraint-runtime/dist/tools/...` 不存在而直接报 TS2307;
+         *   ② `npm run build:main` —— 再建根包 (tsc + copy-constraint-runtime)。
+         * 原来只跑 ②, 在**干净源码树**上必失败 —— 这个坑只有真从 git 建一次才会暴露。
+         */
+        const buildWs = runNpm(['run', 'build', '--workspaces', '--if-present', '--loglevel=error'], dir);
+        if (buildWs.code !== 0) {
+            return { ok: false, kind: 'dev_source_failed', reason: 'build_failed', detail: `dev 快照构建 workspace 依赖失败: ${(buildWs.stderr || buildWs.stdout).slice(0, 400)}` };
+        }
+        const build = runNpm(['run', 'build:main'], dir);
+        if (build.code !== 0) {
+            return { ok: false, kind: 'dev_source_failed', reason: 'build_failed', detail: `dev 快照构建失败: ${(build.stderr || build.stdout).slice(0, 400)}` };
+        }
+        built = true;
+    }
+    // 写身份 (改 package.json 的版本身份 + 一个可核对的标记文件)
+    const pkgPath = path.join(dir, 'package.json');
+    const raw = JSON.parse(await fsp.readFile(pkgPath, 'utf8'));
+    raw.version = identity;
+    await fsp.writeFile(pkgPath, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+    await fsp.writeFile(path.join(dir, '.bolloon-dev-snapshot.json'), JSON.stringify({
+        channel: 'dev', ref: `refs/heads/${DEV_BRANCH}`, sha, identity, source, built,
+        builtAt: new Date().toISOString(),
+        warning: DEV_CHANNEL_WARNING,
+    }, null, 2) + '\n', 'utf8');
+    // 打包 (产物仍是 tarball → 交给 npm 替换, 不另造一套)
+    const pack = runNpm(['pack', dir, '--pack-destination', opts.workDir, '--loglevel=error'], opts.workDir);
+    if (pack.code !== 0) {
+        return { ok: false, kind: 'dev_source_failed', reason: 'pack_failed', detail: `dev 快照打包失败: ${(pack.stderr || pack.stdout).slice(0, 400)}` };
+    }
+    const tgzs = (await fsp.readdir(opts.workDir)).filter((f) => f.endsWith('.tgz') && f.includes('bolloon-agent'));
+    if (tgzs.length === 0)
+        return { ok: false, kind: 'dev_source_failed', reason: 'no_tarball', detail: 'npm pack 没有产出 tarball' };
+    const tarball = path.join(opts.workDir, tgzs.sort()[tgzs.length - 1]);
+    return { ok: true, dir, tarball, identity, sha, baseVersion, source, built };
+}

package/dist/utils/update-cli.js

@@ -15,8 +15,8 @@
  * 退出码与 `bolloon update` 完全一致: 0 正常 / 1 执行失败 / 2 检查不可用。
  */
 import { resolveBolloonHome } from '../setup/setup-store.js';
-import { checkForUpdate, readUpdateStatus } from './update-manager.js';
-import { renderCheckResult, runDoctorCommand, runUpdateCommand, runVersionCommand } from '../cli/update-commands.js';
+import { checkForUpdate, readUpdateStatus, checkExitCode } from './update-manager.js';
+import { renderCheckResult, renderStatusReport, runDoctorCommand, runUpdateCommand, runVersionCommand, parseChannelArg } from '../cli/update-commands.js';
 import { runDoctor, renderDoctor } from './update-health.js';
 function out(s) { process.stdout.write(s + '\n'); }
 async function main() {
@@ -25,11 +25,17 @@ async function main() {
     const args = argv.slice(1);
     const json = args.includes('json') || args.includes('--json');
     const home = resolveBolloonHome();
+    // 双源: `--channel stable|dev` 只覆盖本次进程 (§12.2); 给了不认识的值就直接拒
+    const ch = parseChannelArg(args);
+    if (ch.error) {
+        process.stderr.write(`✗ ${ch.error}\n`);
+        return 2;
+    }
     switch (cmd) {
         case 'check': {
-            const force = args.includes('force') || args.includes('--force') || args.includes('--fresh');
+            const force = args.includes('force') || args.includes('--force') || args.includes('--fresh') || !!ch.channel;
             const offline = args.includes('offline') || args.includes('--offline');
-            const r = await checkForUpdate({ home, force, offline });
+            const r = await checkForUpdate({ home, force, offline, channel: ch.channel });
             if (json)
                 out(JSON.stringify(r, null, 2));
             else if (r.status === 'up_to_date' || r.status === 'check_skipped') {
@@ -40,28 +46,17 @@ async function main() {
             else {
                 out(renderCheckResult(r));
             }
-            return (r.status === 'offline' || r.status === 'registry_unavailable' || r.status === 'local_version_unknown') ? 2 : 0;
+            return checkExitCode(r.status);
         }
         case 'status': {
-            const s = await readUpdateStatus({ home });
+            const s = await readUpdateStatus({ home, channel: ch.channel });
             if (json)
                 out(JSON.stringify(s, null, 2));
-            else {
-                const L = [
-                    `当前版本: ${s.currentVersion}`,
-                    `最新版本: ${s.latestVersion || '未知'}`,
-                    `检查结论: ${s.lastCheckStatus || '尚未检查'}${s.lastCheckReason ? ` (${s.lastCheckReason})` : ''}`,
-                    `最近检查: ${s.lastCheckAt || '从未'}`,
-                    `安装方式: ${s.installMethod}`,
-                    `安装目录: ${s.installDir}`,
-                    `最近更新: ${s.lastUpdate ? `${s.lastUpdate.at} ${s.lastUpdate.from} → ${s.lastUpdate.to} [${s.lastUpdate.status}]` : '无记录'}`,
-                    `需要重启: ${s.needsRestart ? '是' : '否'}`,
-                ];
-                out(L.join('\n'));
-            }
+            else
+                out(renderStatusReport(s));
             return 0;
         }
-        case 'plan': return runUpdateCommand(['plan', ...(json ? ['json'] : [])]);
+        case 'plan': return runUpdateCommand(['plan', ...(ch.channel ? ['--channel', ch.channel] : []), ...(json ? ['json'] : [])]);
         case 'history': return runUpdateCommand(['history', ...args.filter((a) => /^\d+$/.test(a)), ...(json ? ['json'] : [])]);
         case 'version': return runVersionCommand(args);
         case 'doctor': {
@@ -72,7 +67,7 @@ async function main() {
             return rep.grade === 'failed' ? 1 : 0;
         }
         default:
-            process.stderr.write(`未知子命令: ${cmd}\n用法: update-cli check|status|plan|history|version|doctor [json]\n`);
+            process.stderr.write(`未知子命令: ${cmd}\n用法: update-cli check|status|plan|history|version|doctor [json] [--channel stable|dev]\n`);
             return 64;
     }
 }