@bolloon/bolloon-agent 0.4.32 → 0.5.0

package/dist/utils/dual-source.js

@@ -0,0 +1,426 @@
+/**
+ * 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 只负责"切换 + 验证 + 回滚", 不另造一套)
+ *
+ * 硬口径 (§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';
+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']);
+/** 可选 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')); });
+    });
+}
+/** 网络类 → 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 一起带回去
+ * (上层因此能说清"哪些拿到了、哪些没拿到", 而不是一句"更新失败")。
+ */
+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 };
+}
+/** 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 || '' };
+}
+/** 从 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;
     }
 }

package/dist/utils/update-health.js

@@ -20,6 +20,8 @@ import { spawnSync } from 'child_process';
 import { detectInstallation, readPackageAt, PKG_NAME } from './version-info.js';
 import { readUpdateState, readUpdateLock, lockIsStale, reclaimStaleLockIfAny, IN_FLIGHT_RUN_STATUSES, } from './update-state.js';
 import { queryRegistryDoc, parseJsonFromStdout } from './update-manager.js';
+import { fetchGithubFacts, toGithubReport, renderGithubReportLine } from './dual-source.js';
+import { devShaFromIdentity, channelKindOf, DEV_CHANNEL_WARNING } from './version-info.js';
 import { detectRuntimeReport, verifyRuntimesDeep, evaluateCapabilities, RUNTIME_MIN, readIncompleteMarker, } from './runtime-bootstrap.js';
 function worst(items) {
     if (items.some((i) => i.grade === 'failed'))
@@ -333,6 +335,25 @@ export async function runDoctor(opts) {
     }
     // 6. 上次更新是否异常中断
     const st = await readUpdateState(home);
+    // 6.5 双源身份 (§12.5): doctor 也必须能回答"我装的是哪个源 / 哪个 commit / 能切回哪"
+    {
+        const devSha = devShaFromIdentity(version);
+        const prefsChannel = st.channel || 'stable';
+        checks.push(devSha
+            ? {
+                id: 'update_source', label: '安装来源 (双源)', grade: 'degraded',
+                detail: `dev 快照: GitHub master ${st.devRef || 'refs/heads/master'} @ commit ${devSha} (比较语义 ${channelKindOf('dev')}, 非 semver)`
+                    + `${st.switchableTo ? ` · 可切回 stable (${st.switchableTo.source}${st.switchableTo.target ? ` @ ${st.switchableTo.target}` : ''})` : ''}`
+                    + ` · ${DEV_CHANNEL_WARNING}`,
+                action: 'bolloon update now --channel stable',
+            }
+            : {
+                id: 'update_source', label: '安装来源 (双源)', grade: 'ok',
+                detail: `stable: npm registry 权威 (比较语义 ${channelKindOf('stable')})`
+                    + `${st.devSha ? ` · 上次用过 dev 快照 commit ${st.devSha}${st.devCheckedAt ? ` (${st.devCheckedAt})` : ''}, 已切回` : ''}`
+                    + ` · 默认通道 ${prefsChannel} · 切 dev 用: bolloon update now --channel dev`,
+            });
+    }
     const inFlight = st.lastUpdate && IN_FLIGHT_RUN_STATUSES.includes(st.lastUpdate.status);
     checks.push(inFlight
         ? { id: 'last_update', label: '上次更新', grade: 'degraded', detail: `上次更新停在 ${st.lastUpdate.status} (${st.lastUpdate.at}) — 异常中断, 建议 bolloon update --plan 后再更新一次`, action: 'bolloon update --plan' }
@@ -342,15 +363,24 @@ export async function runDoctor(opts) {
     if (st.needsRestart) {
         checks.push({ id: 'needs_restart', label: '待重启', grade: 'degraded', detail: '新版本已就位但还没重启, 当前进程仍在跑旧代码', action: '重启 bolloon' });
     }
-    // 7. 版本检查源是否可达 (可跳过)
+    // 7. 版本检查源是否可达 (可跳过) —— 双源: npm 是权威, GitHub 是交叉校验/dev 的源
     if (opts.skipNetwork) {
         checks.push({ id: 'version_source', label: '版本源可达', grade: 'ok', detail: '已跳过 (离线)' });
     }
     else {
-        const reg = await queryRegistryDoc();
-        checks.push(reg.ok
-            ? { id: 'version_source', label: '版本源可达', grade: 'ok', detail: `npm registry 可达, latest=${reg.doc.latest}` }
-            : { id: 'version_source', label: '版本源可达', grade: 'degraded', detail: `${reg.kind}: ${reg.detail}` });
+        const [reg, ghRes] = await Promise.all([queryRegistryDoc(), fetchGithubFacts()]);
+        const gh = toGithubReport(ghRes);
+        const npmPart = reg.ok
+            ? `npm registry 可达, latest=${reg.doc.latest}`
+            : `npm ${reg.kind}: ${reg.detail}`;
+        checks.push({
+            id: 'version_source', label: '版本源可达 (双源)',
+            // npm 是 stable 的权威 (坏了就是 degraded); GitHub 坏了只影响交叉校验与 dev 通道 → 也只 degraded
+            grade: reg.ok ? (gh.reachable ? 'ok' : 'degraded') : 'degraded',
+            detail: `${npmPart} · ${renderGithubReportLine(gh)}`,
+            action: !reg.ok ? '检查网络/代理后重跑 bolloon doctor'
+                : (!gh.reachable ? 'GitHub 交叉校验不可用 (stable 仍以 npm 为权威); dev 通道此时会直接拒绝' : undefined),
+        });
     }
     // 7.5 安装完整性标记 (postinstall 发现缺 Git/Python 时留下的)
     const marker = await readIncompleteMarker(home).catch(() => null);