@bolloon/bolloon-agent 0.5.1 → 0.5.2

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);
+}

package/dist/efficode/negotiate.js

@@ -0,0 +1,187 @@
+/**
+ * efficode/negotiate - 智能体"用哪种语言交流"的声明与协商
+ *
+ * 三条硬规则 (照 leo 的要求):
+ *   ① 只有**双方都声明** efficode 才用 Efficode;
+ *   ② 单方声明 / 对端不支持 / 对端声明了本机不认识的字符串 ⇒ **明确回落自然语言**, 并记一笔;
+ *   ③ 声明语言**不是** efficode 的载荷, **绝不去解析它** (不猜、不试解) ——
+ *      `decodeFromPeer` 里那条 `EFFICODE_LANG_UNSUPPORTED` 就是这条的落地处。
+ *
+ * 记录: 每次裁决写 ~/.bolloon/efficode-lang.jsonl (只记语言名与原因, **不记正文/DID**)。
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { EfficodeError } from './types.js';
+import { buildPacket, parsePacket } from './packet.js';
+import { instructionsToSymbolic } from './ops.js';
+export const AGENT_LANGS = ['natural', 'efficode'];
+/** 把任意外来声明归一成两个已知值之一; 其他一律 null (= 未知语言, **不是** natural) */
+export function normalizeLang(v) {
+    if (typeof v === 'string') {
+        const s = v.trim();
+        if (s === 'natural' || s === 'efficode')
+            return s;
+        return null;
+    }
+    if (Array.isArray(v)) {
+        // manifest 里的 supportedLangs 形态: 优先 efficode (更专的声明优先)
+        if (v.some((x) => x === 'efficode'))
+            return 'efficode';
+        if (v.some((x) => x === 'natural'))
+            return 'natural';
+        return null;
+    }
+    return null;
+}
+/** 声明里出现了哪些**本机不认识**的语言字符串 (用于如实标注, 不当成 natural) */
+export function unknownLangNames(v) {
+    const arr = Array.isArray(v) ? v : v == null ? [] : [v];
+    return arr
+        .map((x) => (typeof x === 'string' ? x.trim() : ''))
+        .filter((s) => s && !AGENT_LANGS.includes(s));
+}
+/**
+ * 协商。`mine`/`theirs` 可以是 'natural' | 'efficode' | 字符串数组 | undefined | 任意外来值。
+ * 任何"不是恰好双方 efficode"的情形都落到 natural。
+ */
+export function negotiateLang(mine, theirs) {
+    const m = normalizeLang(mine);
+    const t = normalizeLang(theirs);
+    const mUnknown = unknownLangNames(mine);
+    const tUnknown = unknownLangNames(theirs);
+    const declared = {
+        mine: Array.isArray(mine) ? mine.join('|') : mine == null ? null : String(mine),
+        theirs: Array.isArray(theirs) ? theirs.join('|') : theirs == null ? null : String(theirs),
+    };
+    const unknownSide = mUnknown.length && tUnknown.length ? 'both' : mUnknown.length ? 'mine' : tUnknown.length ? 'theirs' : null;
+    if (m === 'efficode' && t === 'efficode') {
+        return { lang: 'efficode', fallback: false, reason: '双方都声明 efficode', declared, unknownSide };
+    }
+    const wanted = m === 'efficode' || t === 'efficode';
+    let reason;
+    if (!m && !t) {
+        reason = unknownSide ? '双方都没有可识别的语言声明' : '双方都没声明语言';
+    }
+    else if (m === 'efficode') {
+        reason = unknownSide
+            ? `对端声明了本机不认识的语言 (${tUnknown.join(',')}) → 回落自然语言`
+            : '对端没声明 efficode → 回落自然语言';
+    }
+    else if (t === 'efficode') {
+        reason = '本机没声明 efficode → 回落自然语言';
+    }
+    else {
+        reason = unknownSide ? '声明里只有本机不认识的语言 → 回落自然语言' : '双方都只声明 natural';
+    }
+    return { lang: 'natural', fallback: wanted, reason, declared, unknownSide };
+}
+/**
+ * 出站: **双方都声明** efficode 才编码; 否则原文直发 (声明 natural)。
+ * 走的是文本模式 (整个包 Base64), 所以线上仍是可打印文本, 任何文本通道都能带。
+ *
+ * 指令构造 (照规范的前缀表达式): `@DID:<身份> <op> !SEND`
+ *   —— 正文进**数据块**, 指令段只放"这是什么"。
+ */
+export function encodeForPeer(opts) {
+    const decision = negotiateLang(opts.mine, opts.theirs);
+    if (decision.lang !== 'efficode') {
+        return { text: opts.text, lang: 'natural', decision, bytes: 0, note: decision.reason, symbolic: '' };
+    }
+    const instructions = [];
+    if (opts.from)
+        instructions.push({ op: '@DID:', value: opts.from });
+    instructions.push({ op: opts.op ?? '#DATA:', value: '' });
+    instructions.push({ op: '!SEND' });
+    const packed = buildPacket({
+        from: opts.from,
+        instructions,
+        data: opts.text,
+        mode: 'text',
+        compression: 'deflate',
+    });
+    return {
+        text: Buffer.from(packed).toString('base64'),
+        lang: 'efficode',
+        decision,
+        bytes: packed.length,
+        note: '',
+        symbolic: instructionsToSymbolic(instructions),
+    };
+}
+/**
+ * 入站:**严格**按对端声明的语言分派。
+ * - 声明 efficode 且本机也声明支持 → 真解包 (畸形/CRC 不符 → 抛, 不许"解一半");
+ * - 声明不是 efficode (含未知字符串) → 原样返回, **不进解码器**。
+ */
+export function decodeFromPeer(opts) {
+    const raw = Array.isArray(opts.declaredLang)
+        ? opts.declaredLang.join('|')
+        : opts.declaredLang == null
+            ? null
+            : String(opts.declaredLang);
+    const declared = normalizeLang(opts.declaredLang);
+    const mineOk = normalizeLang(opts.mine) === 'efficode';
+    if (declared !== 'efficode') {
+        return {
+            text: opts.payload,
+            declaredLang: declared,
+            declaredRaw: raw,
+            decoded: false,
+            note: raw && declared === null
+                ? `对端声明的语言「${raw}」本机不认识 → 不解析, 原样呈现`
+                : '对端未声明 efficode → 原样呈现',
+            bytes: 0,
+        };
+    }
+    if (!mineOk) {
+        throw new EfficodeError('EFFICODE_LANG_UNSUPPORTED', '对端声明 efficode, 但本机未声明支持 → 拒绝解码 (不许硬解)');
+    }
+    const p = parsePacket(opts.payload);
+    return { text: p.data, declaredLang: declared, declaredRaw: raw, decoded: true, note: '', bytes: p.bytes };
+}
+/** 本机默认声明哪种语言 (没给 = natural; 声明不变量绝不会"猜"成 efficode) */
+export function defaultDeclaredLang(env = process.env) {
+    const v = String(env.BOLLOON_EFFICODE_LANG ?? '').trim();
+    return normalizeLang(v) ?? 'natural';
+}
+// ============== 裁决记录 (只记语言与原因, 不记正文) ==============
+export function langDecisionLogPath(env = process.env) {
+    const home = env.BOLLOON_HOME || path.join(os.homedir() || '/tmp', '.bolloon');
+    return path.join(home, 'efficode-lang.jsonl');
+}
+/** 记一笔 (失败绝不打断主路径 —— 记录是旁路) */
+export function recordLangDecision(decision, meta) {
+    try {
+        const file = langDecisionLogPath();
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const line = JSON.stringify({
+            ts: new Date().toISOString(),
+            channel: meta.channel,
+            peer: meta.peer ? String(meta.peer).slice(0, 64) : null,
+            lang: decision.lang,
+            fallback: decision.fallback,
+            reason: decision.reason,
+            unknownSide: decision.unknownSide,
+            declared: decision.declared,
+        });
+        fs.appendFileSync(file, line + '\n', 'utf-8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 读回记录 (门用来断言"真记了一笔") */
+export function readLangDecisionLog(env = process.env) {
+    try {
+        return fs
+            .readFileSync(langDecisionLogPath(env), 'utf-8')
+            .split('\n')
+            .filter(Boolean)
+            .map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/efficode/ops.js

@@ -0,0 +1,87 @@
+/**
+ * efficode/ops - 指令集 / 词典 (符号 ↔ 二进制操作码)
+ *
+ * 照 leo 的规范: 符号化指令集 + 前缀表达式。
+ *   @DID:  身份      1  载荷 = 身份串
+ *   #DATA: 数据      2  载荷 = 数据正文
+ *   #REQ:  请求      3  载荷 = 请求内容
+ *   !ACK   确认      4  无载荷
+ *   !SEND  发送      5  无载荷
+ *   !END   结束      6  无载荷
+ *
+ * 指令段二进制形状 (逐条): [1B opcode][varint payloadLen][payload UTF-8]
+ * 末尾**没有**隐式终止符 —— 靠 payloadLen 自描述; 少一个字节就报截断。
+ *
+ * 严格性: 任何不在表里的 opcode 一律抛 EFFICODE_UNKNOWN_OPCODE。
+ * (变异 M1 会把这里改成"宽容跳过", 门必须变红 —— 这就是那条断言存在的意义。)
+ */
+import { EfficodeError } from './types.js';
+export const OP_TABLE = [
+    { symbol: '@DID:', code: 1, hasPayload: true, prefix: '@DID:' },
+    { symbol: '#DATA:', code: 2, hasPayload: true, prefix: '#DATA:' },
+    { symbol: '#REQ:', code: 3, hasPayload: true, prefix: '#REQ:' },
+    { symbol: '!ACK', code: 4, hasPayload: false, prefix: '!ACK' },
+    { symbol: '!SEND', code: 5, hasPayload: false, prefix: '!SEND' },
+    { symbol: '!END', code: 6, hasPayload: false, prefix: '!END' },
+];
+const BY_SYMBOL = new Map(OP_TABLE.map((d) => [d.symbol, d]));
+const BY_CODE = new Map(OP_TABLE.map((d) => [d.code, d]));
+export function opBySymbol(symbol) {
+    const d = BY_SYMBOL.get(symbol);
+    if (!d)
+        throw new EfficodeError('EFFICODE_UNKNOWN_OPCODE', `未知符号 ${String(symbol)}`);
+    return d;
+}
+/** 按 opcode 取定义; 未知一律抛 (不返回 undefined 让上层"随便处理") */
+export function opByCode(code, offset = -1) {
+    const d = BY_CODE.get(code);
+    if (!d)
+        throw new EfficodeError('EFFICODE_UNKNOWN_OPCODE', `操作码 ${code} 不在指令表内`, offset);
+    return d;
+}
+export function isKnownOpCode(code) {
+    return BY_CODE.has(code);
+}
+/** 指令序列 → 前缀表达式文本 (调试/文本模式可读形态) */
+export function instructionsToSymbolic(instructions) {
+    return instructions
+        .map((ins) => {
+        const def = opBySymbol(ins.op);
+        return def.hasPayload ? `${def.prefix}${ins.value ?? ''}` : def.prefix;
+    })
+        .join(' ');
+}
+/**
+ * 前缀表达式文本 → 指令序列。
+ *
+ * 解析规则 (写死, 免得被当成"随便切"):
+ *   ① 按空白切词;
+ *   ② 词首是 sigil 字符 (@ / # / !) → 必须匹配一条**已知**前缀, 否则抛 UNKNOWN_OPCODE;
+ *   ③ 不带 sigil 的词 → 追加到**上一条**指令的载荷后面 (没有上一条 → 抛);
+ *   ④ 控制指令 (!ACK/!SEND/!END) 后面不许跟载荷。
+ */
+export function symbolicToInstructions(text) {
+    const out = [];
+    const words = String(text || '').trim().split(/\s+/).filter(Boolean);
+    for (const token of words) {
+        const isSigil = /^[@#!]/.test(token);
+        if (!isSigil) {
+            const last = out[out.length - 1];
+            if (!last || !opBySymbol(last.op).hasPayload) {
+                throw new EfficodeError('EFFICODE_UNKNOWN_OPCODE', `前缀表达式含未知指令: ${token.slice(0, 24)}`);
+            }
+            last.value = `${last.value ?? ''} ${token}`.trim();
+            continue;
+        }
+        const def = OP_TABLE.find((d) => token.startsWith(d.prefix));
+        if (!def)
+            throw new EfficodeError('EFFICODE_UNKNOWN_OPCODE', `前缀表达式含未知指令: ${token.slice(0, 24)}`);
+        if (def.hasPayload)
+            out.push({ op: def.symbol, value: token.slice(def.prefix.length) });
+        else if (token === def.prefix)
+            out.push({ op: def.symbol });
+        else
+            throw new EfficodeError('EFFICODE_UNKNOWN_OPCODE', `控制指令 ${def.prefix} 不接受载荷: ${token.slice(0, 24)}`);
+    }
+    return out;
+}