@bolloon/bolloon-agent 0.5.1 → 0.5.3

package/dist/cli/x402-seller-command.js

@@ -0,0 +1,289 @@
+/**
+ * x402-seller-command.ts — `bolloon x402 pending list|show|sign|auth-init|key`
+ *
+ * 薄包装: 业务逻辑一律在 `agents/x402/seller-signing.ts`, 本文件只做
+ *   ① 参数解析 ② 人类可读输出 ③ 失败时的可操作提示。
+ *
+ * 红线 (与 docs/wiki/x402-seller-signing.md 一致):
+ *   · 私钥**只在本进程内存里**用于签名; 绝不打印、绝不落日志、绝不进命令行、绝不上服务器
+ *   · 共享密钥只出现在 0600 文件与请求头里; 输出里只有 keyId 与指纹
+ *   · 签名只走既有 `buildSignedEnvelope` → `ed25519Sign` (不新写一套签名实现)
+ *   · 卖方不在线 ⇒ 如实报 "已付款待签名", 不假装能交付
+ */
+import { sellerApiPaths, sellerAuthPath, sellerAuthFingerprint, generateSellerAuth, loadSellerAuth, saveSellerAuth, sellerHome, sellerClientRequest, pendingView, signPending, resolveSellerKey, paidInfoRetrievePath, } from '../agents/x402/seller-signing.js';
+import { canonicalize, ed25519Verify } from '../agents/x402/paid-info-protocol.js';
+const USAGE = `
+bolloon x402 pending —— 卖方本机签名交付 (私钥不离开本机)
+
+  bolloon x402 pending list [--endpoint <url>] [--status awaiting_signature] [--json]
+  bolloon x402 pending show <pendingId> [--endpoint <url>] [--json]
+  bolloon x402 pending sign <pendingId> [--endpoint <url>] [--agent <agentId>] [--json]
+  bolloon x402 pending auth-init [--endpoint <url>] [--force]
+  bolloon x402 pending key [--agent <agentId>] [--json]
+
+  auth-init   生成 0600 共享密钥 (~/.bolloon/x402-seller-auth.json), 打印 keyId/指纹/安装提示
+  key         打印本机卖方公钥 (给服务器钉住; **只有公钥**, 私钥永不出机)
+  list/show   带 HMAC 认证拉取待办 (服务器只持公钥, 签不了信封 ⇒ 必须本机签)
+  sign        读本机内容 → 既有 ed25519Sign 签信封 → 回传服务器 → 本机自检验签
+
+选项: --endpoint <url> (也可在 auth 文件里存 endpoint) · --agent <agentId> · --json
+`;
+function flagValue(args, name) {
+    const i = args.indexOf(name);
+    if (i >= 0 && i + 1 < args.length && !args[i + 1].startsWith('--'))
+        return args[i + 1];
+    const eq = args.find((a) => a.startsWith(`${name}=`));
+    return eq ? eq.slice(name.length + 1) : undefined;
+}
+function firstPositional(args) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--')) {
+            if (!a.includes('='))
+                i++;
+            continue;
+        }
+        return a;
+    }
+    return undefined;
+}
+/** endpoint: --endpoint > auth 文件 > env */
+async function resolveEndpoint(args) {
+    const explicit = flagValue(args, '--endpoint') || process.env.BOLLOON_X402_SELLER_ENDPOINT;
+    if (explicit)
+        return explicit;
+    const cfg = await loadSellerAuth();
+    if (cfg?.endpoint)
+        return cfg.endpoint;
+    throw new Error('没有端点: 给 --endpoint <url>, 或先跑 `bolloon x402 pending auth-init --endpoint <url>` 把它存进 auth 文件');
+}
+function short(s, n = 20) {
+    const v = String(s ?? '');
+    return v.length > n ? `${v.slice(0, n)}…` : v;
+}
+// ─────────────────────────────────────────────────────────── 子命令
+async function cmdList(args) {
+    const json = args.includes('--json');
+    const endpoint = await resolveEndpoint(args);
+    const auth = await loadSellerAuth();
+    if (!auth) {
+        console.error('❌ 本机没有共享密钥 (~/.bolloon/x402-seller-auth.json) — 先跑 `bolloon x402 pending auth-init --endpoint <url>`');
+        return 1;
+    }
+    const status = flagValue(args, '--status');
+    const urlPath = status ? `${sellerApiPaths().list}?status=${encodeURIComponent(status)}` : sellerApiPaths().list;
+    // 被签的只有 pathname (查询串不参与)
+    const r = await sellerClientRequest({ endpoint, auth }, { method: 'GET', path: sellerApiPaths().list, urlPath });
+    if (!r.ok) {
+        console.error(`❌ 拉取失败 (HTTP ${r.status}): ${r.json?.code || ''} ${r.json?.error || r.text.slice(0, 200)}`);
+        if (r.json?.hint)
+            console.error(`   ${r.json.hint}`);
+        return 1;
+    }
+    if (json) {
+        console.log(JSON.stringify(r.json, null, 2));
+        return 0;
+    }
+    const items = r.json.pending || [];
+    console.log(`卖方待办 (${endpoint}) — 共 ${r.json.total ?? items.length} 条, 待签名 ${r.json.awaitingSignature ?? '?'} 条`);
+    if (!items.length) {
+        console.log('  (空) 没有待签名的付款 —— 卖方不在线时买方只会拿到「已付款待签名」');
+        return 0;
+    }
+    for (const p of items) {
+        const v = pendingView(p);
+        console.log(`  ${v.pendingId}  [${v.status}]  ${v.itemId}  ${v.payment.amount} ${v.payment.currency}@${v.payment.network}  ${v.createdAt}`);
+        console.log(`      内容哈希 ${v.contentHash} · 付款凭据哈希 ${v.payment.receiptHash} · mode=${v.payment.mode}`);
+    }
+    console.log('  下一步: bolloon x402 pending show <pendingId> → sign <pendingId>');
+    return 0;
+}
+async function cmdShow(args) {
+    const json = args.includes('--json');
+    const id = firstPositional(args);
+    if (!id) {
+        console.error('用法: bolloon x402 pending show <pendingId>');
+        return 1;
+    }
+    const endpoint = await resolveEndpoint(args);
+    const auth = await loadSellerAuth();
+    if (!auth) {
+        console.error('❌ 本机没有共享密钥 — 先跑 auth-init');
+        return 1;
+    }
+    const r = await sellerClientRequest({ endpoint, auth }, { method: 'GET', path: sellerApiPaths().show(id) });
+    if (!r.ok) {
+        console.error(`❌ 取不到 (HTTP ${r.status}): ${r.json?.code || ''} ${r.json?.error || r.text.slice(0, 200)}`);
+        return 1;
+    }
+    if (json) {
+        console.log(JSON.stringify(r.json, null, 2));
+        return 0;
+    }
+    const p = r.json.pending;
+    console.log(`待办 ${p.pendingId}  [${p.status}]`);
+    console.log(`  item          ${p.itemId}  (${p.title})`);
+    console.log(`  卖方 DID      ${p.providerDid}`);
+    console.log(`  内容哈希      ${p.contentHash}${p.contentCid ? `  cid=${p.contentCid}` : ''}`);
+    console.log(`  来源声明      kind=${p.source?.kind} refs=${(p.source?.refs || []).length}`);
+    console.log(`  价格          ${p.price.amount} ${p.price.currency}@${p.price.network} → ${p.price.payTo}`);
+    console.log(`  付款          mode=${p.payment.mode}  ${p.payment.amount} ${p.payment.currency}@${p.payment.network}`);
+    console.log(`  付款凭据哈希  ${p.payment.receiptHash}   ← 签名会绑定它`);
+    console.log(`  付款凭据原文  ${short(p.payment.receipt, 48)}   (回执原文, 本机要用它重建哈希)`);
+    if (p.payment.txHash)
+        console.log(`  链上 txHash   ${p.payment.txHash}`);
+    if (p.payment.payer)
+        console.log(`  付款方        ${p.payment.payer}`);
+    console.log(`  创建/过期     ${p.createdAt} → ${p.expiresAt}`);
+    if (p.envelopeHash)
+        console.log(`  已签信封哈希  ${p.envelopeHash}`);
+    console.log(`  下一步: bolloon x402 pending sign ${p.pendingId}`);
+    return 0;
+}
+async function cmdSign(args) {
+    const json = args.includes('--json');
+    const id = firstPositional(args);
+    if (!id) {
+        console.error('用法: bolloon x402 pending sign <pendingId> [--agent <agentId>]');
+        return 1;
+    }
+    const endpoint = await resolveEndpoint(args);
+    const auth = await loadSellerAuth();
+    if (!auth) {
+        console.error('❌ 本机没有共享密钥 — 先跑 auth-init');
+        return 1;
+    }
+    // ① 拉这条待办 (服务器是待办的事实来源)
+    const r = await sellerClientRequest({ endpoint, auth }, { method: 'GET', path: sellerApiPaths().show(id) });
+    if (!r.ok) {
+        console.error(`❌ 取不到待办 (HTTP ${r.status}): ${r.json?.code || ''} ${r.json?.error || r.text.slice(0, 200)}`);
+        return 1;
+    }
+    const pending = r.json.pending;
+    if (pending.status !== 'awaiting_signature') {
+        console.error(`❌ 这条待办状态是 ${pending.status} — 不能签 (已签过/已过期都不许重签)`);
+        return 1;
+    }
+    // ② 本机内容 (签名要绑内容哈希 ⇒ 没有内容就签不出来, 如实报错)
+    const { getStoredInfo } = await import('../agents/x402/paid-info-store.js');
+    const stored = await getStoredInfo(pending.itemId, sellerHome());
+    if (!stored) {
+        console.error(`❌ 本机没有 item ${pending.itemId} 的内容 (~/.bolloon/x402-info/) — 没法签 (签一个对不上的信封等于假交付)`);
+        return 1;
+    }
+    // ③ 本机钥匙: 必须是这条 item 的卖方 DID (**不新建钥匙**)
+    const agentId = flagValue(args, '--agent');
+    const key = await resolveSellerKey(pending.providerDid, { agentId });
+    if (!key) {
+        console.error(`❌ 本机找不到能给 ${pending.providerDid} 签名的私钥 (查过 ~/.bolloon/agent-keys/*.json 与 ~/.bolloon/identity.json)`);
+        return 1;
+    }
+    // ④ 签 (既有 ed25519Sign), ⑤ 本机自检验签 —— 不信"我签好了", 用公钥验一遍
+    const envelope = await signPending({ pending, item: stored.item, content: stored.content, keypair: { did: key.did, publicKey: key.publicKeyHex, privateKey: Buffer.from(key.privateKeyHex, 'hex') } });
+    const selfCheck = await ed25519Verify(envelope.proof.publicKeyHex, canonicalize(envelope.proof.payload), envelope.proof.signature);
+    // ⑥ 回传 (服务器会用钉住的公钥再验一次)
+    const post = await sellerClientRequest({ endpoint, auth }, { method: 'POST', path: sellerApiPaths().envelope(pending.pendingId), body: JSON.stringify({ envelope }) });
+    if (json) {
+        console.log(JSON.stringify({
+            ok: post.ok && selfCheck,
+            pendingId: pending.pendingId,
+            itemId: pending.itemId,
+            contentHash: envelope.proof.payload.contentHash,
+            receiptHash: envelope.proof.payload.receiptHash,
+            publicKeyHex: envelope.proof.publicKeyHex,
+            did: envelope.proof.did,
+            keySource: key.source,
+            selfCheckSignature: selfCheck,
+            server: { status: post.status, ok: post.ok, code: post.json?.code, envelopeHash: post.json?.envelopeHash },
+            envelope: post.ok ? undefined : envelope,
+        }, null, 2));
+        return post.ok && selfCheck ? 0 : 1;
+    }
+    console.log(`签名自检: ${selfCheck ? '✅ ed25519Verify 通过' : '❌ 验签不通过 (绝不回传这种信封)'}`);
+    console.log(`  签名        ${short(envelope.proof.signature, 28)}  (base64, 完整值用 --json)`);
+    console.log(`  签名公钥    ${envelope.proof.publicKeyHex}`);
+    console.log(`  钥匙来源    ${key.source} (DID ${envelope.proof.did})`);
+    console.log(`  载荷绑定    itemId=${envelope.proof.payload.itemId} · contentHash=${short(envelope.proof.payload.contentHash, 24)} · receiptHash=${short(envelope.proof.payload.receiptHash, 24)}`);
+    if (!post.ok) {
+        console.error(`❌ 回传失败 (HTTP ${post.status}): ${post.json?.code || ''} ${post.json?.error || post.text.slice(0, 200)}`);
+        return 1;
+    }
+    if (!selfCheck)
+        return 1;
+    console.log(`✅ 已回传并收下 — pendingId=${pending.pendingId} envelopeHash=${post.json?.envelopeHash}`);
+    console.log(`   买方下一步: 用取件 token 取 (不要重放付款凭据 —— 会再跑一遍结算):`);
+    console.log(`     GET ${paidInfoRetrievePath(pending.itemId, pending.pendingId)}   → 200 + 信封, 然后 ed25519Verify / verifyEnvelope 离线验签`);
+    return 0;
+}
+async function cmdAuthInit(args) {
+    const endpoint = flagValue(args, '--endpoint') || process.env.BOLLOON_X402_SELLER_ENDPOINT;
+    const force = args.includes('--force');
+    const existing = await loadSellerAuth();
+    if (existing && !force) {
+        console.log(`已存在共享密钥 (keyId=${existing.keyId} 指纹 ${sellerAuthFingerprint(existing)}) — 换新密钥要显式 --force`);
+        console.log(`  endpoint: ${existing.endpoint || '(未设置)'} · 文件 ${sellerAuthPath()}`);
+        return 0;
+    }
+    const cfg = generateSellerAuth(endpoint);
+    const file = await saveSellerAuth(cfg);
+    console.log('✅ 已生成共享密钥 (0600 文件, 值不打印)');
+    console.log(`  keyId     ${cfg.keyId}`);
+    console.log(`  指纹      ${sellerAuthFingerprint(cfg)}   ← 核对两端是不是同一把就用它`);
+    console.log(`  endpoint  ${cfg.endpoint || '(未设置, 用 --endpoint 指定)'}`);
+    console.log(`  文件      ${file}`);
+    console.log('');
+    console.log('安装到服务器 (值只走 stdin, 不进命令行/不进日志/不进会话):');
+    console.log(`  ssh <server> 'install -m600 -o bolloonpay -g bolloonpay /dev/stdin /opt/bolloon-pay/.bolloon/${'x402-seller-auth.json'}' < ${file}`);
+    console.log('卖方公钥钉钉子 (只有公钥):');
+    console.log('  bolloon x402 pending key > /tmp/seller-key.json   # 再 scp 到服务器 /opt/bolloon-pay/.bolloon/seller-key.json');
+    return 0;
+}
+async function cmdKey(args) {
+    const json = args.includes('--json');
+    const agentId = flagValue(args, '--agent');
+    // 不指定 agent 时用身份文件 (与 routes-x402-info.ts 的 loadProviderKeypair 同源)
+    const did = process.env.BOLLOON_SELLER_DID || '';
+    const key = await resolveSellerKey(did, { agentId });
+    if (!key) {
+        console.error('❌ 本机找不到卖方身份 (~/.bolloon/identity.json 或 agent-keys/)');
+        return 1;
+    }
+    const out = { protocol: 'bolloon-x402-seller/1', did: key.did, publicKeyHex: key.publicKeyHex, note: '这是公钥 (可放服务器)。私钥不在此输出中。' };
+    if (json) {
+        console.log(JSON.stringify(out, null, 2));
+        return 0;
+    }
+    console.log(`卖方 DID    ${out.did}`);
+    console.log(`公钥 (hex)  ${out.publicKeyHex}`);
+    console.log(`来源        ${key.source}`);
+    console.log(`钉到服务器: /opt/bolloon-pay/.bolloon/seller-key.json`);
+    return 0;
+}
+// ─────────────────────────────────────────────────────────── 入口
+export async function x402PendingCommand(args) {
+    const sub = args[0];
+    const rest = args.slice(1);
+    try {
+        switch (sub) {
+            case 'list': return await cmdList(args);
+            case 'show': return await cmdShow(rest);
+            case 'sign': return await cmdSign(rest);
+            case 'auth-init': return await cmdAuthInit(rest);
+            case 'key': return await cmdKey(rest);
+            case undefined:
+            case '--help':
+            case '-h':
+                console.log(USAGE.trim());
+                return sub === undefined ? 1 : 0;
+            default:
+                console.error(`未知 x402 pending 子命令: ${sub}`);
+                console.log(USAGE.trim());
+                return 1;
+        }
+    }
+    catch (e) {
+        console.error(`❌ ${String(e?.message || e).slice(0, 300)}`);
+        return 1;
+    }
+}
+export { USAGE as X402_PENDING_USAGE };

package/dist/cli-entry.js

@@ -68,7 +68,9 @@ ${BOLD}命令:${RESET}
   bolloon setup                     初始化向导 (你的称呼 + 模型供应商 + API key + 连通性测试)
   bolloon identity init             非交互建本机身份 (~/.bolloon/identity.json, 0600, 幂等; 新机器/第二实例用)
   bolloon identity show             看本机身份 (只出 DID/指纹, 绝不打印私钥)
-  bolloon update [plan|status|history|now]   检查更新 / 计划 / 状态 / 历史 / 执行 (默认只检查)
+  bolloon identity bind-address     登记「地址 ↔ DID」绑定 (链下登记·双侧签名·可离线验签)
+  bolloon identity bindings         绑定库: list | show <file> | verify <file> | publish --out <path>
+  bolloon update [wait|force|--dry-run|status|history]   直接执行更新 (先打印计划与风险检查; 只看计划用 --dry-run)
   bolloon doctor                    安装入口 + 版本事实 + 更新状态自洽性诊断
   bolloon runtime [plan|install]    运行时 (Node/npm/Git/Python) 检查与安装
   bolloon model [name] [model]      列出 / 切换模型供应商 (如: bolloon model deepseek deepseek-v4-flash)
@@ -84,6 +86,7 @@ ${BOLD}命令:${RESET}
   bolloon engine run <prompt>       委派任务给智能体
   bolloon x402 fetch <url>          x402 自动支付 HTTP 请求
   bolloon x402 balance <address>    查询 x402 钱包余额
+  bolloon x402 pay <endpoint>       买方自己发 EIP-3009 授权转账 (--with-memo 带订单标识)
   bolloon mcp serve                 MCP server (stdio) —— 给 MCP 客户端接本机 Agent 能力
   bolloon mcp tools                 列出 MCP 暴露的 tools/resources (只读清单)
 
@@ -94,9 +97,8 @@ ${BOLD}示例:${RESET}
   bolloon --web              # 启动 Web UI
   bolloon --cli              # 命令行模式
   bolloon model              # 查看当前模型供应商
-  bolloon update             # 检查更新 (只读, 不改任何东西)
-  bolloon update plan        # 看更新计划与风险检查
-  bolloon update now         # 真正执行更新
+  bolloon update             # 直接执行更新 (先打印计划与风险检查)
+  bolloon update --dry-run   # 只看计划, 不动任何东西
   bolloon doctor             # 我这台机器的 Bolloon 是否自洽
   bolloon network join --json         # 入网 (失败也结构化: ok:false + code + next_action)
   bolloon task --request-id <id> "…"  # 用给定幂等键跑 M1 任务 (同一 requestId 不会付两次)
@@ -247,12 +249,14 @@ function firstPositional(args) {
     }
     return undefined;
 }
-/** x402 子命令: fetch / balance */
+/** x402 子命令: fetch / balance / pending (卖方本机签名交付) */
 async function handleX402Command(x402Args) {
     if (x402Args.length === 0) {
         console.log(`${BOLD}用法:${RESET}`);
         console.log('  bolloon x402 fetch <url> [options]        # 自动处理 402 Payment Required');
         console.log('  bolloon x402 balance <address> [options]  # 查询钱包余额');
+        console.log('  bolloon x402 pay <endpoint> [--with-memo] # 买方自己发 EIP-3009 授权转账 (nonce 带订单标识 BOL1)');
+        console.log('  bolloon x402 pending list|show|sign       # 卖方本机签名交付 (私钥不离开本机)');
         console.log('');
         console.log(`${BOLD}选项:${RESET}`);
         console.log('  --private-key <0x...>  自动支付钱包私钥，也可用 X402_PRIVATE_KEY');
@@ -266,6 +270,18 @@ async function handleX402Command(x402Args) {
     }
     const sub = x402Args[0];
     const rest = x402Args.slice(1);
+    // 2026-09-28: 卖方本机签名交付 —— 待办队列 (list/show/sign/auth-init/key)
+    if (sub === 'pending') {
+        const { x402PendingCommand } = await import('./cli/x402-seller-command.js');
+        process.exit(await x402PendingCommand(rest));
+        return;
+    }
+    // 2026-09-29: 买方自己发 EIP-3009 transferWithAuthorization (nonce 带订单标识 BOL1)
+    if (sub === 'pay') {
+        const { x402PayCommand } = await import('./cli/x402-buyer-command.js');
+        process.exit(await x402PayCommand(rest));
+        return;
+    }
     if (sub === 'fetch') {
         const url = firstPositional(rest);
         if (!url) {

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';