@bolloon/bolloon-agent 0.5.0 → 0.5.2

package/dist/cli-entry.js

@@ -22,6 +22,9 @@ import { discoverEngines, delegateToEngine } from './external-engines/index.js';
 import { x402CheckBalance, x402Fetch } from './agents/x402/x402Pay.js';
 import { runVersionCommand, runUpdateCommand, runDoctorCommand, runRuntimeCommand, UPDATE_HELP } from './cli/update-commands.js';
 import { collectVersionInfo } from './utils/version-info.js';
+// 2026-09-27: 启动前言的默认静默 + 显式查询命令 (与 `src/index.ts` 同一套判断)
+import { startupPreambleVisible } from './cli/startup-notice.js';
+import { logStartupLine } from './cli/log-gate.js';
 // 2026-09-21 (P3): 统一 JSON 信封 + 命令组 (network/agent/task/wallet/payment/trade)
 import { runServiceGroup, GROUPS_HELP } from './cli/commands/index.js';
 // 2026-09-21 (P4): MCP 适配层 (`bolloon mcp serve` = stdio, 只调 P3 服务层)
@@ -71,6 +74,9 @@ ${BOLD}命令:${RESET}
   bolloon model [name] [model]      列出 / 切换模型供应商 (如: bolloon model deepseek deepseek-v4-flash)
   bolloon model key <name>          配置某供应商的 API key (隐藏输入, 不回显)
   bolloon model test [name]         测试供应商连通性
+  bolloon model list [name]         看模型发现目录 (P5)
+  bolloon model refresh [name]      重取上游模型目录 (--clear 清缓存)
+  bolloon model admit <name> <model>  手输一个目录里没有的模型名
   bolloon read <file>               读取文档
   bolloon summarize <file>          总结文档
   bolloon improve <file> <req>      改进文档
@@ -568,36 +574,121 @@ async function handleP2pCommand(p2pArgs) {
     // 那是常驻模块, 句柄不会自己关 → 不显式退出会"输出完了还挂着"。
     process.exit(info.ok ? 0 : 1);
 }
+/** 真终端判定: stdin 与 stdout 都是 TTY 才算交互 (管道 / 重定向 = 脚本可读输出) */
+function isRealTty() {
+    return !!process.stdin.isTTY && !!process.stdout.isTTY;
+}
+/**
+ * `bolloon model [...]` — 模型供应商/模型切换的唯一命令行入口。
+ *
+ * leo 2026-09-27 口径: **`bolloon model` 就是"切换"的启动命令** —— 真终端里敲完直接就是选择界面
+ * (与 `bolloon model pick` 同一实现, 只是用户不必知道 pick 这个词), 第一屏就是带序号/状态/当前项
+ * 标记的供应商列表, 选完往下走; **不许**先刷一坨供应商清单+用法再问。
+ * 管道/非 TTY 才退回清单+用法 (脚本可读, 不会卡在等待输入)。
+ * `pick` / `list` 两个子命令都保留 (pick 是显式写法, list 只读列表)。
+ */
 async function handleModelCommand(modelArgs) {
-    const { llmConfigStore, PROVIDER_INFO } = await import('./llm/config-store.js');
+    const { llmConfigStore } = await import('./llm/config-store.js');
+    const { effectiveModelConfig, formatEffectiveModel } = await import('./llm/model-selection.js');
     await llmConfigStore.initialize();
-    // 无参: 列出所有供应商 + 当前 active
+    const tty = isRealTty();
+    // ── 真终端 + 裸敲: 直接进选择器 (第一屏 = 供应商列表) ──────────
+    if (modelArgs.length === 0 && tty) {
+        const { runModelCommand, modelTtyIO, askHiddenLineEof, askLineEof } = await import('./cli/setup-wizard.js');
+        const out = await runModelCommand('pick', await useTui() ? modelTtyIO() : {
+            live: true, // 每一步当场打到终端 (不是等整轮结束才一次性回显)
+            print: (l) => process.stdout.write(l + '\n'),
+            askHidden: async (q) => { const r = await askHiddenLineEof(q); return r.eof ? null : r.value; },
+            ask: async (q, opts) => { const r = await askLineEof(q, opts); return r.eof ? null : r.value; },
+        });
+        for (const line of String(out).split('\n'))
+            if (line !== '')
+                console.log(line);
+        return;
+    }
+    // ── 无参 + 非终端 (管道/脚本): 列出**全部**供应商 (分组带家数) + 当前**真实生效**的那一份 + 用法 ──
     if (modelArgs.length === 0) {
-        const config = await llmConfigStore.getConfig();
-        console.log(`\n${BOLD}模型供应商${RESET} (当前: ${config.activeProvider})\n`);
+        const eff = await effectiveModelConfig({}).catch(() => null);
+        const mc = await import('./llm/model-catalog.js');
+        const summaries = await mc.buildProviderSummaries({});
+        const pc = await import('./llm/provider-catalog.js');
+        await pc.initializeProviderCatalog();
+        console.log(`\n${BOLD}模型供应商${RESET} (当前生效: ${eff ? `${eff.provider}/${eff.model}` : '读不出来'})\n`);
+        if (eff)
+            console.log(`  ${formatEffectiveModel(eff)}`);
         console.log('─'.repeat(58));
-        for (const [name, p] of Object.entries(config.providers)) {
-            const info = PROVIDER_INFO[name] || {};
-            const active = name === config.activeProvider ? '●' : '○';
-            const keyState = p.apiKey ? '🔑' : p.requiresApiKey ? '⚠ 无 key' : '';
-            const model = p.model || (info.models && info.models[0]) || '';
-            console.log(`  ${active} ${name.padEnd(10)} ${String(info.name || '').padEnd(16)} ${keyState.padEnd(8)} model: ${model}`);
+        // 非终端里没有"固定高度视窗 + 折叠"那套交互 (那是全屏 TUI 的事), 所以这里**整份列全**:
+        //   内置 13 + 自定义 + 目录全部 逐行出, 分组标题带家数。只给"分组计数"是这条线要修的病 ——
+        //   脚本要能 grep 到任何一家 (含"需专用鉴权 (未支持)""无基址"的那些)。
+        const ordered = mc.orderProvidersForMenu(summaries);
+        let lastGroup = '';
+        for (const s of ordered) {
+            const tier = mc.providerTierOf(s);
+            const g = mc.PROVIDER_GROUPS[tier];
+            if (g !== lastGroup) {
+                lastGroup = g;
+                const n = ordered.filter((x) => mc.providerTierOf(x) === tier).length;
+                console.log(`  ── ${g} (${n} 家)${mc.providerTierCollapsedByDefault(tier) ? ' · 交互界面里默认收起, 空格/→ 展开' : ''}`);
+            }
+            console.log(`  ${mc.formatProviderMenuRow(s)}`);
         }
+        console.log(`  ${mc.providerGroupSummary(summaries)}`);
+        console.log(`  ${pc.catalogStatusLine()}`);
+        console.log(`  ${pc.catalogGroupLine()}`);
         console.log(`\n${BOLD}用法:${RESET}`);
+        console.log(`  bolloon model                    # 终端里直接进选择界面 (固定高度视窗 + 分组折叠; 上面这份全量列表是管道/脚本的可读输出)`);
+        console.log(`  bolloon model pick               # 同上, 显式写法 (供应商→凭证→模型→参数→作用域→测试→确认)`);
         console.log(`  bolloon model <name>             # 切换到该供应商`);
         console.log(`  bolloon model <name> <model>     # 切换并指定模型`);
+        console.log(`  bolloon model list [name]        # 看模型发现目录 (只读)`);
+        console.log(`  bolloon model refresh [name]     # 重取上游目录 (--clear 清缓存)`);
+        console.log(`  bolloon model admit <name> <m>   # 手输一个目录里没有的模型名`);
+        console.log(`  bolloon model catalog            # 供应商目录: 是几号的/新鲜度/族分布 (只读)`);
+        console.log(`  bolloon model catalog list [词]  # 逐家看 (**默认全量**, 含"需专用鉴权/无基址"并标原因; --usable 只看能用的)`);
+        console.log(`  bolloon model catalog refresh    # 运行期真拉最新目录 (落盘 0600, 记来源与时间)`);
         console.log(`  示例: bolloon model deepseek deepseek-v4-flash`);
         return;
     }
-    // 有参: 统一交给 setup-wizard 的 runModelCommand
-    //   (切换 / <provider> <model> / key <provider> / test / status 一套语义, 与 CLI 会话内 /model 完全一致)
-    const { runModelCommand, askHiddenLine } = await import('./cli/setup-wizard.js');
-    const out = await runModelCommand(modelArgs.join(' '), {
-        // 正常终端里可以安全收 key (隐藏输入, 不回显)
-        askHidden: (q) => askHiddenLine(q),
+    // ── 有参: 统一交给 setup-wizard 的 runModelCommand ───────────
+    //   (pick 分步选择 / 切换 / <provider> <model> / key <provider> / test / status 一套语义,
+    //    与 CLI 会话内 /model 完全一致 —— 写配置与重建运行时的逻辑只有 selectModel 一处)
+    const { runModelCommand, modelTtyIO, askHiddenLineEof, askLineEof } = await import('./cli/setup-wizard.js');
+    // `--verbose` 交给界面层决定"打不打内部细节", 不进参数解析 (解析器不认识这个词会被当值)
+    const wantVerbose = modelArgs.includes('--verbose');
+    const args = modelArgs.filter((a) => a !== '--verbose');
+    const out = await runModelCommand(args.join(' '), (await useTui()) && tty ? {
+        ...modelTtyIO(),
+        ...(wantVerbose ? { verbose: true } : {}),
+    } : {
+        // 非 TTY (管道/脚本) / 显式关掉 TUI: 逐行问答 —— 输出可读、不卡死、行为与以前一致
+        live: tty,
+        print: (l) => process.stdout.write(l + '\n'),
+        askHidden: async (q) => { const r = await askHiddenLineEof(q); return r.eof ? null : r.value; },
+        ask: async (q, opts) => { const r = await askLineEof(q, opts); return r.eof ? null : r.value; },
+        ...(wantVerbose ? { verbose: true } : {}),
     });
     for (const line of String(out).split('\n'))
-        console.log(line);
+        if (line !== '')
+            console.log(line);
+}
+/**
+ * 这个环境要不要用全屏 TUI 选择器。
+ * 三判据: ① 用户没显式关 (`BOLLOON_NO_TUI=1`); ② 真 TTY; ③ `tuiCapable()` (终端够高/能拿 raw mode)。
+ * 任何一条不满足 → 退回逐行问答 (**不静默变样子**: 管道输出仍是可读清单+用法)。
+ */
+function useTui() {
+    return (async () => {
+        if (process.env.BOLLOON_NO_TUI)
+            return false;
+        try {
+            // 同步判据在 tui-select 里 (它不许在非 TTY 里抢输入)
+            const { tuiCapable } = await import('./cli/tui-select.js');
+            return !!tuiCapable();
+        }
+        catch {
+            return false;
+        }
+    })();
 }
 /** `bolloon setup` — 首次运行初始化向导 (用户身份 + 模型供应商 + API key + 连通性测试) */
 async function handleSetupCommand(setupArgs) {
@@ -615,6 +706,7 @@ async function handleSetupCommand(setupArgs) {
         console.log(`${BOLD}bolloon setup${RESET} — 初始化 Bolloon (用户身份 + 模型供应商 + API key)`);
         console.log('');
         console.log('  无参数            交互式向导 (推荐)');
+        console.log('  status            只读: 看初始化状态/门禁/就绪度全量 (启动面板那一行"详情"指的就是它)');
         console.log('  --provider <名>   指定供应商 (deepseek / minimax / openai / anthropic / ...)');
         console.log('  --api-key <key>   直接给 key (脚本用; 交互模式会隐藏输入)');
         console.log('  --model <名>      指定模型');
@@ -623,6 +715,15 @@ async function handleSetupCommand(setupArgs) {
         console.log('  repair-runtime    检查并补装缺失运行时 (Node/npm/Git/Python)');
         return;
     }
+    // 2026-09-27: `bolloon setup status` —— **启动前言搬去的地方**。
+    //   启动时那一整段 (初始化状态/就绪度/已完成/配置来源/已存输入/缺什么/下一步) 默认不上屏,
+    //   要看全量就显式敲这条 (只读, 不写任何文件; 退出码 0 = ready, 1 = 未就绪 —— 脚本可用)。
+    if (setupArgs[0] === 'status' || setupArgs.includes('--status')) {
+        const { evaluateSetup, describeSetup } = await import('./setup/setup-store.js');
+        const ev = await evaluateSetup();
+        process.stdout.write(describeSetup(ev) + '\n');
+        process.exit(ev.gate === 'ready' ? 0 : 1);
+    }
     const apiKey = val('--api-key');
     const needsInteractive = !apiKey;
     const r = await runSetupWizard({
@@ -801,7 +902,13 @@ async function startWebServer(additionalArgs) {
 }
 // 启动 CLI
 async function startCLI(additionalArgs) {
-    log('启动命令行界面...', CYAN);
+    // 2026-09-27 (leo 口径: 打完 `bolloon --cli` 直接看到面板): 这句"启动命令行界面..."属于**启动前言**,
+    //   默认不上屏 (照落启动日志); `--verbose` / `BOLLOON_VERBOSE=1` / `BOLLOON_STARTUP_PREAMBLE=1` 逐字回来。
+    //   (gui/web 那两个面的 banner 不动 —— 它们没有"面板", 输出就是交付物。)
+    if (startupPreambleVisible())
+        log('启动命令行界面...', CYAN);
+    else
+        logStartupLine('启动命令行界面...');
     try {
         const mainPath = getMainScript();
         const cliArgs = [...additionalArgs];

package/dist/efficode/compress.js

@@ -0,0 +1,78 @@
+/**
+ * efficode/compress - 可插拔压缩层
+ *
+ * 三个算法 (数据块第一字节 = 算法 id):
+ *   0 none     原样 (小消息用 —— 头上开箱代价为 0)
+ *   1 lz77     本仓实现, 纯 JS 可跑任何运行面 (含手机 WebView)
+ *   2 deflate  node:zlib deflateRaw (真压缩, 真数字)
+ *
+ * 默认策略 `pickAlgo`: 先按内容选, 选完**真压一遍**, 压不小就退回 `none`
+ * (小消息硬压一定更贵 —— 这是实测结论, 见 wiki §"更高效吗")。
+ */
+import { deflateRawSync, inflateRawSync } from 'node:zlib';
+import { lz77Compress, lz77Decompress } from './lz77.js';
+import { COMPRESSION_IDS, COMPRESSION_BY_ID, EfficodeError } from './types.js';
+export const COMPRESSION_ALGOS = ['none', 'lz77', 'deflate'];
+/** 压缩。返回 [1B 算法 id][载荷] 的完整数据块体 */
+export function compressBlock(raw, algo) {
+    const body = compressPayload(raw, algo);
+    const out = new Uint8Array(body.length + 1);
+    out[0] = COMPRESSION_IDS[algo];
+    out.set(body, 1);
+    return out;
+}
+function compressPayload(raw, algo) {
+    switch (algo) {
+        case 'none':
+            return raw;
+        case 'lz77':
+            return lz77Compress(raw);
+        case 'deflate':
+            return new Uint8Array(deflateRawSync(raw));
+        default:
+            throw new EfficodeError('EFFICODE_UNKNOWN_COMPRESSION', `未知压缩算法 ${String(algo)}`);
+    }
+}
+/** 解压 [1B 算法 id][载荷]。未知算法 id → 报错, 绝不"跳过解压直接给原文" */
+export function decompressBlock(block) {
+    if (block.length < 1)
+        throw new EfficodeError('EFFICODE_TRUNCATED', '数据块空 (缺算法 id)');
+    const algo = COMPRESSION_BY_ID[block[0]];
+    if (!algo) {
+        throw new EfficodeError('EFFICODE_UNKNOWN_COMPRESSION', `数据块声明未知压缩算法 id=${block[0]}`, 0);
+    }
+    const payload = block.subarray(1);
+    switch (algo) {
+        case 'none':
+            return { algo, data: payload.slice() };
+        case 'lz77':
+            return { algo, data: lz77Decompress(payload) };
+        case 'deflate': {
+            try {
+                return { algo, data: new Uint8Array(inflateRawSync(payload)) };
+            }
+            catch (e) {
+                throw new EfficodeError('EFFICODE_TRUNCATED', `deflate 解压失败: ${String(e?.message ?? e).slice(0, 120)}`);
+            }
+        }
+        default:
+            throw new EfficodeError('EFFICODE_UNKNOWN_COMPRESSION', `未知压缩算法 ${String(algo)}`);
+    }
+}
+/**
+ * 默认算法选择: 结构化文本 (重复多) 用 deflate; 其余先用 lz77 试;
+ * 压缩后**不小于**原长就退回 none (省下的不该是负数)。
+ */
+export function pickAlgo(raw, preferred = 'deflate') {
+    if (raw.length < 32)
+        return 'none'; // 小消息: 头上开箱代价 > 收益
+    const got = compressPayload(raw, preferred);
+    return got.length < raw.length ? preferred : 'none';
+}
+/** 真测: 三个算法分别压出来的字节数 (给门和 wiki 用真实数字, 不许估) */
+export function measureAll(raw) {
+    const out = {};
+    for (const a of COMPRESSION_ALGOS)
+        out[a] = compressPayload(raw, a).length + 1; // +1 = 算法 id 字节
+    return out;
+}

package/dist/efficode/crc32.js

@@ -0,0 +1,38 @@
+/**
+ * efficode/crc32 - 包尾 CRC32 (IEEE 802.3, 多项式 0xEDB88320)
+ *
+ * 为什么自己写而不是用 zlib.crc32: 包层要能在**任何**运行面 (含手机 WebView 的
+ * 纯 JS 上下文) 真算同一个校验值, 所以这里是不依赖 node:zlib 的纯实现。
+ * 自证向量写在 src/test/efficode.test.ts: crc32("123456789") === 0xCBF43926 (规范值)。
+ */
+const TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+/** 算 CRC32, 返回无符号 32 位整数 */
+export function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** 打包成 4 字节大端 */
+export function crc32Bytes(buf) {
+    const v = crc32(buf);
+    const out = new Uint8Array(4);
+    out[0] = (v >>> 24) & 0xff;
+    out[1] = (v >>> 16) & 0xff;
+    out[2] = (v >>> 8) & 0xff;
+    out[3] = v & 0xff;
+    return out;
+}
+/** 从 4 字节大端读回 */
+export function readCrc32Bytes(b, offset = 0) {
+    return (((b[offset] << 24) | (b[offset + 1] << 16) | (b[offset + 2] << 8) | b[offset + 3]) >>> 0);
+}

package/dist/efficode/did.js

@@ -0,0 +1,66 @@
+/**
+ * efficode/did - DID 验证段 (固定 32B)
+ *
+ * 布局 (32 字节):
+ *   [0]      algo id (= 1, sha256-截断)
+ *   [1..3]   原始身份串字节数 (24 位大端, 上限 16MB)
+ *   [4..31]  sha256(身份串) 的**前 28 字节**
+ *
+ * 诚实边界 (必须写进 wiki, 不许含糊):
+ *   - 32B **装不下**一个 DID / 公钥, 所以本段是**摘要**, 只能做"是不是同一个身份"的比对,
+ *     **不能**从段里还原身份, 也**不能**独立证明持有私钥;
+ *   - 真正的"链上签名验证 + ECC 临时会话密钥"属**规范中/未实现** —— 本模块没有签名函数,
+ *     也没有密钥交换函数 (不写假实现)。签名校验的接线点在 packet 层的 `verifyDid` 回调,
+ *     现成可用的只有摘要比对这一条。
+ */
+import { createHash } from 'node:crypto';
+import { DID_SEGMENT_BYTES, EfficodeError } from './types.js';
+export const DID_ALGO_SHA256_TRUNC28 = 1;
+/** 编: 身份串 → 32B 段 */
+export function encodeDidSegment(did) {
+    const raw = Buffer.from(String(did), 'utf-8');
+    if (raw.length === 0)
+        throw new EfficodeError('EFFICODE_DID_SEGMENT_BAD', '身份串为空');
+    if (raw.length > 0xffffff)
+        throw new EfficodeError('EFFICODE_DID_SEGMENT_BAD', `身份串过长 (${raw.length}B > 16MB)`);
+    const full = createHash('sha256').update(raw).digest();
+    const seg = new Uint8Array(DID_SEGMENT_BYTES);
+    seg[0] = DID_ALGO_SHA256_TRUNC28;
+    seg[1] = (raw.length >>> 16) & 0xff;
+    seg[2] = (raw.length >>> 8) & 0xff;
+    seg[3] = raw.length & 0xff;
+    seg.set(full.subarray(0, DID_SEGMENT_BYTES - 4), 4);
+    return seg;
+}
+/** 解: 32B 段 → 结构。长度不足 / algo 未知 → 抛 */
+export function decodeDidSegment(seg) {
+    if (seg.length !== DID_SEGMENT_BYTES) {
+        throw new EfficodeError('EFFICODE_DID_SEGMENT_BAD', `DID 段应为 ${DID_SEGMENT_BYTES}B, 实得 ${seg.length}B`);
+    }
+    const algo = seg[0];
+    if (algo !== DID_ALGO_SHA256_TRUNC28) {
+        throw new EfficodeError('EFFICODE_DID_SEGMENT_BAD', `未知 DID 摘要算法 id=${algo}`, 0);
+    }
+    const origLen = (seg[1] << 16) | (seg[2] << 8) | seg[3];
+    return { algo, origLen, digest: seg.slice(4) };
+}
+/** 摘要段的稳定文本形式: `algo1:<56 hex>` —— 可安全落日志 (单向, 不可还原身份) */
+export function didDigestString(seg) {
+    return `algo${seg.algo}:${Buffer.from(seg.digest).toString('hex')}`;
+}
+/**
+ * 校验一条身份声明是否与段匹配。
+ * 这是**明文比对** (拿原身份串再算一遍摘要), 不是签名验证 —— 返回值里如实标出方式。
+ */
+export function matchesDidSegment(did, seg) {
+    const expected = encodeDidSegment(did);
+    let match = expected.length === seg.length;
+    if (match) {
+        for (let i = 0; i < seg.length; i++)
+            if (expected[i] !== seg[i]) {
+                match = false;
+                break;
+            }
+    }
+    return { match, method: 'digest', signed: false };
+}

package/dist/efficode/index.js

@@ -0,0 +1,24 @@
+/**
+ * efficode - AI 专用交流语言的**参考实现** (v0.1.0)
+ *
+ * 模块划分:
+ *   types.ts      公共类型 / 失败码
+ *   ops.ts        指令集与词典 (符号 ↔ 二进制操作码, 前缀表达式)
+ *   crc32.ts      包尾 CRC32 (纯 JS, 任何运行面可算)
+ *   lz77.ts       自解压数据块用的轻量 LZ77 (真实实现)
+ *   compress.ts   可插拔压缩层 (none / lz77 / deflate)
+ *   did.ts        DID 验证段 (32B 摘要段)
+ *   packet.ts     包封装: [Header 2B]|[DID 32B]|[指令段]|[数据块]|[CRC32 4B]
+ *   negotiate.ts  智能体"用哪种语言"的声明/协商/回落与记录
+ *
+ * 状态的**唯一事实源**在 docs/wiki/efficode.md 的逐节标注 (已实现 / 规范中 / 未实现);
+ * 本目录只提供代码, 代码里的注释只写"这段代码真做了什么"。
+ */
+export * from './types.js';
+export * from './ops.js';
+export * from './crc32.js';
+export * from './lz77.js';
+export * from './compress.js';
+export * from './did.js';
+export * from './packet.js';
+export * from './negotiate.js';

package/dist/efficode/lz77.js

@@ -0,0 +1,170 @@
+/**
+ * efficode/lz77 - 自解压数据块用的轻量 LZ77 (真实实现, 不是占位)
+ *
+ * 数据块布局 (自解压头 + 码流):
+ *   [varint origLen][varint compLen][token stream]
+ *
+ *   token stream = 控制字节 + 载荷, 每控制字节管 8 个 token, MSB 在前:
+ *     控制位 0 → 后接 1 字节字面量
+ *     控制位 1 → 后接 2 字节匹配 (12 位 offset, 4 位 length-3)
+ *
+ *   origLen 在头里 ⇒ 解码器**不需要**猜结束位置 (靠输出长度收敛), 尾随多余码流一律报错。
+ *
+ * 匹配查找用 deflate 那套**哈希链**: 3 字节前缀哈希 → 链上回溯 (最多 MAX_CHAIN 个候选).
+ * 第一版是"从 pos-1 逐个往前比"的朴素写法, 在 `...\n` 这种周期 > 16 的重复文本上**找不到匹配**
+ * (300 行重复文本压完反而膨胀 1538B —— 实测出来的, 已换掉)。
+ *
+ * 诚实边界 (写进 wiki 时按实测数字):
+ *   - 参考实现: 窗口 4095B / 最短匹配 3B / 最长匹配 18B, **没有**哈夫曼那一层;
+ *   - 对重复度高的结构化文本有效, 对**随机字节**会膨胀 (控制位占 1/8);
+ *   - 真实压缩率对比见 scripts/verify-efficode.ts 的真测输出, 不许在文档里编。
+ */
+import { EfficodeError } from './types.js';
+const WINDOW = 4095; // 12 位 offset (0 保留为非法)
+const MIN_MATCH = 3; // length-3 存 4 位 ⇒ 3..18
+const MAX_MATCH = 18;
+const MAX_CHAIN = 16; // 哈希链回溯上限 (控制最坏耗时)
+const HASH_SIZE = 1 << 16; // 3 字节前缀哈希表大小
+function writeVarint(out, n) {
+    let v = n >>> 0;
+    while (v >= 0x80) {
+        out.push((v & 0x7f) | 0x80);
+        v >>>= 7;
+    }
+    out.push(v & 0xff);
+}
+function readVarint(buf, pos) {
+    let value = 0;
+    let shift = 0;
+    let i = pos;
+    for (;;) {
+        if (i >= buf.length)
+            throw new EfficodeError('EFFICODE_TRUNCATED', 'varint 未读完就到底', i);
+        const b = buf[i++];
+        value |= (b & 0x7f) << shift;
+        if ((b & 0x80) === 0)
+            break;
+        shift += 7;
+        if (shift > 28)
+            throw new EfficodeError('EFFICODE_TRUNCATED', 'varint 超过 32 位上限', i);
+    }
+    return { value: value >>> 0, next: i };
+}
+/** 压缩。返回 [varint origLen][varint compLen][tokens] */
+export function lz77Compress(input) {
+    const out = [];
+    writeVarint(out, input.length);
+    const bodyStart = out.length;
+    out.push(0); // 占位 (1B, varint(0)); 最后整体重拼, 不依赖占位宽度
+    const head = new Int32Array(HASH_SIZE).fill(-1);
+    const prev = new Int32Array(input.length).fill(-1);
+    const insertAt = (pos) => {
+        if (pos + MIN_MATCH > input.length)
+            return;
+        const h = hash3(input, pos);
+        prev[pos] = head[h];
+        head[h] = pos;
+    };
+    const findMatch = (pos) => {
+        if (pos + MIN_MATCH > input.length)
+            return null;
+        const h = hash3(input, pos);
+        const maxLen = Math.min(MAX_MATCH, input.length - pos);
+        let cand = head[h];
+        let chain = 0;
+        let bestLen = 0;
+        let bestOff = 0;
+        while (cand >= 0 && chain < MAX_CHAIN) {
+            const distance = pos - cand;
+            if (distance > WINDOW)
+                break;
+            let len = 0;
+            while (len < maxLen && input[cand + len] === input[pos + len])
+                len++;
+            if (len > bestLen) {
+                bestLen = len;
+                bestOff = distance;
+                if (len === maxLen)
+                    break;
+            }
+            cand = prev[cand];
+            chain++;
+        }
+        return bestLen >= MIN_MATCH ? { offset: bestOff, length: bestLen } : null;
+    };
+    let i = 0;
+    while (i < input.length) {
+        const controlIdx = out.length;
+        let control = 0;
+        out.push(0);
+        for (let bit = 7; bit >= 0 && i < input.length; bit--) {
+            const match = findMatch(i);
+            if (match) {
+                control |= 1 << bit;
+                const v = ((match.offset & 0xfff) << 4) | ((match.length - MIN_MATCH) & 0xf);
+                out.push((v >>> 8) & 0xff, v & 0xff);
+                for (let k = 0; k < match.length; k++)
+                    insertAt(i + k);
+                i += match.length;
+            }
+            else {
+                out.push(input[i]);
+                insertAt(i);
+                i += 1;
+            }
+        }
+        out[controlIdx] = control;
+    }
+    // compLen = 码流字节数 (= 占位字节之后的所有字节); 之前这里把占位字节也算进去了 ⇒ 声明比实际多 1 ⇒ 解码必报截断
+    const body = out.slice(bodyStart + 1);
+    const filled = [];
+    writeVarint(filled, input.length);
+    writeVarint(filled, body.length);
+    filled.push(...body);
+    return Uint8Array.from(filled);
+}
+function hash3(b, i) {
+    return (((b[i] << 10) ^ (b[i + 1] << 5) ^ b[i + 2]) & (HASH_SIZE - 1)) >>> 0;
+}
+/** 解压 (严格)。码流不足 / 长度对不上 / 超长一律抛, 不做任何"尽量解" */
+export function lz77Decompress(block) {
+    const head = readVarint(block, 0);
+    const origLen = head.value;
+    const head2 = readVarint(block, head.next);
+    const compLen = head2.value;
+    const bodyEnd = head2.next + compLen;
+    if (bodyEnd > block.length) {
+        throw new EfficodeError('EFFICODE_TRUNCATED', `LZ77 码流声明 ${compLen}B 但只剩 ${block.length - head2.next}B`, head2.next);
+    }
+    const out = [];
+    let pos = head2.next;
+    while (out.length < origLen) {
+        if (pos >= bodyEnd) {
+            throw new EfficodeError('EFFICODE_TRUNCATED', `LZ77 码流提前结束 (期望 ${origLen}B, 实得 ${out.length}B)`, pos);
+        }
+        const control = block[pos++];
+        for (let bit = 7; bit >= 0 && out.length < origLen; bit--) {
+            if (control & (1 << bit)) {
+                if (pos + 2 > bodyEnd) {
+                    throw new EfficodeError('EFFICODE_TRUNCATED', 'LZ77 匹配 token 缺字节', pos);
+                }
+                const v = (block[pos] << 8) | block[pos + 1];
+                pos += 2;
+                const offset = (v >>> 4) & 0xfff;
+                const length = (v & 0xf) + MIN_MATCH;
+                if (offset === 0 || offset > out.length) {
+                    throw new EfficodeError('EFFICODE_TRUNCATED', `LZ77 匹配 offset=${offset} 越界 (已解 ${out.length}B)`, pos);
+                }
+                for (let k = 0; k < length; k++)
+                    out.push(out[out.length - offset]);
+            }
+            else {
+                if (pos >= bodyEnd) {
+                    throw new EfficodeError('EFFICODE_TRUNCATED', 'LZ77 字面量 token 缺字节', pos);
+                }
+                out.push(block[pos++]);
+            }
+        }
+    }
+    return Uint8Array.from(out);
+}