@bolloon/bolloon-agent 0.5.1 → 0.5.2

package/README.md

@@ -91,6 +91,32 @@ npm start
 
 ---
 
+## Docker
+
+不想在本机装 Node 与依赖, 可以直接跑容器 (多阶段镜像 · 非 root 用户 uid 1001 · 状态全部落在卷里):
+
+```bash
+docker build -t bolloon-agent:0.5.1 .
+docker run -d --name bolloon-agent \
+  -p 127.0.0.1:54188:54188 \
+  -v bolloon-data:/home/bolloon/.bolloon \
+  bolloon-agent:0.5.1 --web
+# → http://127.0.0.1:54188
+
+docker compose up -d                            # 同上的 compose 写法
+docker compose run --rm bolloon-cli --version   # 一次性 CLI (不用起服务)
+```
+
+- **密钥别写进 compose**: 复制 `.env.example` → `.env.docker` (已在 `.gitignore`), 或者把本机
+  0600 的 `llm-config.json` **只读挂载**进容器 (更安全: 不进环境变量、不进 `docker inspect`)。
+- **数据卷里有身份私钥与 API key 配置** (`/home/bolloon/.bolloon`): 别导出、别提交、别 `docker commit`。
+- 端口只认环境变量 `PORT` (默认 `54188`); `--port` 参数无效。
+
+完整说明 (镜像怎么搭的 · 卷与 uid 权限 · HEALTHCHECK 探什么/不探什么 · 常见问题) 见
+[docs/wiki/docker-deployment.md](./docs/wiki/docker-deployment.md)。
+
+---
+
 ## 环境变量
 
 | 变量 | 说明 |
@@ -136,6 +162,19 @@ bolloon --help     # All commands
 
 Requires Node.js ≥ 18 and an LLM API key (`OPENAI_API_KEY` or `DEEPSEEK_API_KEY`).
 
+### Docker
+
+Run it in a container instead (multi-stage image, non-root user, state in a volume):
+
+```bash
+docker build -t bolloon-agent:0.5.1 .
+docker run -d --name bolloon-agent -p 127.0.0.1:54188:54188 \
+  -v bolloon-data:/home/bolloon/.bolloon bolloon-agent:0.5.1 --web
+```
+
+Copy `.env.example` to `.env.docker` (gitignored) for keys, or mount your `llm-config.json` read-only
+(safer). Full guide: [docs/wiki/docker-deployment.md](./docs/wiki/docker-deployment.md).
+
 ### License
 
 This project is released under the [MIT License](./LICENSE). You are free to use, modify, and distribute this project, provided that you retain the copyright and permission notices. See the [LICENSE](./LICENSE) file for details.

package/dist/agents/agent-lang.js

@@ -0,0 +1,101 @@
+/**
+ * agents/agent-lang - 智能体交流语言的**声明层**与消息封装层接线
+ *
+ * 这一层只做三件事:
+ *   ① 声明: manifest 里带上 `supportedLangs` (本机支持哪些语言);
+ *   ② 出站: 拿"本机声明 + 对端声明"裁决 → 要么真编 (双方 efficode), 要么原文直发;
+ *   ③ 入站: 只按对端**声明**的语言分派 —— 声明不是 efficode 的载荷一律不进解码器。
+ *
+ * 不支持的场景怎么处理 (照 leo 的要求, 不许静默):
+ *   - 对端没声明 / 只声明 natural → 自然语言, 记一笔 `fallback=false`
+ *   - 本机想要 efficode 但对端没声明 → 回落, 记一笔 `fallback=true` + 原因
+ *   - 对端声明了本机不认识的语言字符串 → 回落, 原样呈现, 记 `unknownSide`
+ *   - 对端声明 efficode 但本机没声明支持 → 拒绝解码并抛 (绝不硬解)
+ */
+import { decodeFromPeer, encodeForPeer, defaultDeclaredLang, negotiateLang, recordLangDecision, unknownLangNames, } from '../efficode/negotiate.js';
+import { normalizeLang } from '../efficode/index.js';
+/** 本机支持的语言声明 (进程内, 由 manifest 装配处设置) */
+let localLangs = [];
+/** 本机默认声明 (env 可覆盖; 默认 natural) */
+let defaultLang = null;
+export function setLocalSupportedLangs(langs) {
+    const arr = Array.isArray(langs) ? langs : langs == null ? [] : [langs];
+    localLangs = arr.map((x) => String(x).trim()).filter(Boolean);
+    return localLangs;
+}
+export function getLocalSupportedLangs() {
+    return [...localLangs];
+}
+/** 本机声明 (没显式设置就回落到 env/默认; 声明不变量绝不"猜"成 efficode) */
+export function localDeclaredLang(env = process.env) {
+    if (defaultLang)
+        return defaultLang;
+    return defaultDeclaredLang(env);
+}
+export function setLocalDeclaredLang(lang) {
+    defaultLang = normalizeLang(lang);
+    return defaultLang ?? 'natural';
+}
+/** 本机要写进 manifest 的声明: 显式语言列表优先, 否则 [默认声明] */
+export function manifestLangDeclaration(env = process.env) {
+    if (localLangs.length)
+        return [...localLangs];
+    return [localDeclaredLang(env)];
+}
+/** 从 manifest 里读对端声明 (老 manifest 没这个字段 → 空数组 = 没声明) */
+export function peerLangsOf(manifest) {
+    const raw = manifest?.supportedLangs;
+    const arr = Array.isArray(raw) ? raw : raw == null ? [] : [raw];
+    return arr.map((x) => String(x).trim()).filter(Boolean);
+}
+/**
+ * 出站消息: 双方声明都是 efficode 才编码, 否则原文直发并在帧里如实声明 `lang: 'natural'`。
+ */
+export function buildAgentMessage(opts) {
+    const mine = opts.mine ?? manifestLangDeclaration(opts.env);
+    const enc = encodeForPeer({ text: opts.text, mine, theirs: opts.theirs, from: opts.from, op: opts.op });
+    const frame = {
+        type: 'agent_message',
+        payload: { text: enc.text, lang: enc.lang },
+        ts: Date.now(),
+        fromDid: opts.from ?? '',
+        ...(opts.to ? { toDid: opts.to } : {}),
+    };
+    recordLangDecision(enc.decision, { channel: 'agent_message', peer: opts.to });
+    return { frame: JSON.stringify(frame), lang: enc.lang, decision: enc.decision, bytes: enc.bytes, encoded: enc.lang === 'efficode' };
+}
+/** 解析线上帧 (非 agent_message / 坏 JSON → null; 不抛, 调用方按"不是我的帧"处理) */
+export function parseAgentMessageFrame(text) {
+    try {
+        const v = JSON.parse(text);
+        if (!v || v.type !== 'agent_message' || !v.payload || typeof v.payload.text !== 'string')
+            return null;
+        return v;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 入站消息: 严格按帧里 `lang` 分派。
+ * - `lang: 'efficode'` 且本机也声明 efficode → 真解包 (畸形包抛 EfficodeError)
+ * - 其它一切 (含缺字段 / 未知字符串) → 原样文本 + 明确 note, **不进解码器**
+ */
+export function readAgentMessage(frameText, opts = {}) {
+    const frame = parseAgentMessageFrame(frameText);
+    if (!frame)
+        return null;
+    const mine = opts.mine ?? manifestLangDeclaration(opts.env);
+    const declared = frame.payload.lang;
+    const inc = decodeFromPeer({ payload: frame.payload.text, declaredLang: declared, mine });
+    const decision = negotiateLang(mine, declared);
+    recordLangDecision(decision, { channel: 'agent_message_recv' });
+    return {
+        ...inc,
+        declared: inc.declaredRaw,
+        unknownLangs: unknownLangNames(declared),
+        fromDid: frame.fromDid ?? '',
+        toDid: frame.toDid,
+        decision,
+    };
+}

package/dist/agents/agent-manifest-protocol.js

@@ -54,6 +54,10 @@ export function setLocalManifest(m) {
         localManifest.exportments = [];
     if (!('sciences' in m))
         localManifest.sciences = [];
+    // 2026-09-28: 交流语言声明同规矩 —— 不给就显式清空, 免得旧的 efficode 声明在对端已经不支持时还留着.
+    // (老 manifest 语义不变: 没有 supportedLangs = 没声明 = 自然语言)
+    if (!('supportedLangs' in m))
+        localManifest.supportedLangs = [];
     // 2026-09-18: 网络脉冲 (只记公开统计; 不落 DID/正文; 统计失败绝不影响主路径)
     try {
         const did = String(localManifest.ownerPublicKey || '');

package/dist/agents/gateway-group.js

@@ -18,6 +18,8 @@
 import * as os from 'os';
 import * as path from 'path';
 import { getCIDDatabase } from '../orbitdb/cid-database.js';
+// 2026-09-28: 交流语言 (Efficode 是可选项, 不是默认项) —— 只有双方都声明才用
+import { decodeFromPeer, encodeForPeer, recordLangDecision } from '../efficode/negotiate.js';
 // ============ 依赖注入 (测试用, 避免单测起真实 OrbitDB 节点) ============
 let _dbOverride = null;
 /** 测试用: 注入 fake CIDDatabase */
@@ -281,7 +283,11 @@ export async function groupMessages(groupId, limit = 50) {
     for (const entry of all) {
         const v = entry.value;
         if (v && typeof v.text === 'string' && typeof v.from === 'string') {
-            msgs.push({ from: v.from, text: v.text, ts: typeof v.ts === 'number' ? v.ts : 0 });
+            const m = { from: v.from, text: v.text, ts: typeof v.ts === 'number' ? v.ts : 0 };
+            // 只透传字符串形态的语言声明; 别的形状一律当"没声明"(不让脏值进到解码分派)
+            if (typeof v.lang === 'string' && v.lang.trim())
+                m.lang = v.lang.trim();
+            msgs.push(m);
         }
     }
     msgs.sort((a, b) => a.ts - b.ts);
@@ -293,7 +299,7 @@ export async function groupMembers(groupId) {
     return Array.from(new Set(msgs.map((m) => m.from)));
 }
 /** 发送群消息 (广播给所有成员) */
-export async function groupSend(groupId, text, from) {
+export async function groupSend(groupId, text, from, opts) {
     const msg = String(text || '').trim();
     if (!msg)
         return { ok: false, error: '消息不能为空' };
@@ -309,13 +315,48 @@ export async function groupSend(groupId, text, from) {
         }
     }
     try {
-        await store.add({ from: String(from || 'anonymous'), text: msg, ts: Date.now() });
+        const record = { from: String(from || 'anonymous'), text: msg, ts: Date.now() };
+        // 只有显式给了合法声明才写字段 —— 不给就不写 (老读者读到的东西一字不变)
+        const lang = typeof opts?.lang === 'string' ? opts.lang.trim() : '';
+        if (lang)
+            record.lang = lang;
+        await store.add(record);
         return { ok: true };
     }
     catch (e) {
         return { ok: false, error: `发送失败: ${String(e?.message || e).slice(0, 160)}` };
     }
 }
+/**
+ * 2026-09-28: 按语言裁决发群消息 —— 真可走的那条路。
+ *
+ * 双方都声明 efficode ⇒ 正文真编成 Efficode 包 (文本模式 Base64), `lang: 'efficode'` 一起落库;
+ * 否则**原文直发** + `lang: 'natural'` (或干脆不写字段, 由调用方定), 并记一笔回落原因。
+ * 裁决/编码/落库各自失败都有结构化结果, 不静默。
+ */
+export async function groupSendWithLang(groupId, text, from, opts = { mine: undefined, theirs: undefined }) {
+    const enc = encodeForPeer({ text, mine: opts.mine, theirs: opts.theirs, from, op: opts.op });
+    recordLangDecision(enc.decision, { channel: `group:${groupId}`, peer: from });
+    const wantLang = enc.lang === 'efficode' || opts.record === 'always' ? enc.lang : '';
+    const r = await groupSend(groupId, enc.text, from, wantLang ? { lang: wantLang } : undefined);
+    return {
+        ok: r.ok,
+        error: r.error,
+        lang: enc.lang,
+        bytes: enc.bytes,
+        fallback: enc.decision.fallback,
+        reason: enc.decision.reason,
+        symbolic: enc.symbolic,
+    };
+}
+/**
+ * 2026-09-28: 读一条群消息 —— 严格按它自己声明的 `lang` 分派。
+ * 声明不是 efficode (含未知字符串 / 没声明) ⇒ 原样返回, **不进解码器**。
+ * 声明 efficode 且本机也声明支持 ⇒ 真解包 (畸形包抛, 由调用方如实报失败)。
+ */
+export function readGroupMessage(msg, mine) {
+    return decodeFromPeer({ payload: msg.text, declaredLang: msg.lang, mine });
+}
 /** 群组邀请链接 */
 export async function groupLink(groupId) {
     const groups = await loadGroups();

package/dist/agents/pi-sdk.js

@@ -33,6 +33,8 @@ import { createGoal, attachRun, findActiveGoal } from './goal-store.js';
 import { captureRunModelConfig } from '../llm/model-selection.js';
 // 2026-09-26: 工具名出网净化 (pi-ai.ts 唯一边界) + 回程派发还原 (原名 ↔ API 名)
 import { resolveApiToolName, expandKnownToolNames } from '../llm/tool-name.js';
+// 2026-09-28 (前缀 KV 可命中): CURRENT TURN 注入标记 —— "当前轮是否已注入"的唯一判据
+import { CURRENT_TURN_MARKER } from '../llm/pi-ai.js';
 import { PiAgentHarness } from './pi-harness.js';
 import { DiscoveredAgentsManager, createSocialHeartbeat } from '../social/heartbeat.js';
 import { SkillRegistry } from '@bolloon/constraint-runtime';
@@ -79,6 +81,55 @@ import { DEFAULT_MAX_REVIEWS } from './loop-review.js';
  *   循环内: 注入 system 提示强制 LLM 收尾; 运行层 (M3): 熔断 → needs_human (交人)。
  */
 const MAX_SAME_TOOL_FAILURES = 3;
+/**
+ * 2026-09-28 (前缀 KV 可命中): 把 chat() 回带的「当前轮已注入」内容写回调用方自己的 history.
+ *
+ * 谁是调用方: ReAct 循环每轮用 `buildMessages()` **重建全新对象** —— 注入只活在那一份里.
+ *   不写回的话下一轮那条 user 就退回注入前, 前缀从它起分叉:
+ *     第 1 次 `S H [D1 U1]`   第 2 次 `S H U1 U2`   ← U1 丢了 D1
+ *   正确形态: `S H [D1 U1] U2` (D1 成了 U1 的一部分, 于是成为后续轮的稳定前缀).
+ *
+ * 为什么是纯函数 (不塞进类里): 门 `scripts/verify-kv-prefix.ts` 要能**直接驱它**断言,
+ *   而不是绕一整条 ReAct 循环才验到"写回"这一下.
+ *
+ * 匹配判据 (只做加法, 绝不乱改历史):
+ *   1. wire 最后一条 content 必须以 CURRENT TURN 标记开头 (没注入过 → 0, 不动);
+ *   2. 从 history **末尾往前**找第一条 `content` 是它后缀的条目 ——
+ *      去掉后缀剩下的那截必须仍以标记开头 (证明"注入是前部加了一段");
+ *   3. 命中就整段写回 (tool 条目拿到的是含 `[工具结果]\n` 前缀 + 注入的整段),
+ *      写回后该条 `content` 已等于 wire → 第二次调用前缀为空, 自然返回 0 (幂等).
+ *
+ * @returns 真写回的条数 (0 = 没注入过 / 匹配不上 / 已经写回过)
+ */
+export function writeBackCurrentTurnInto(history, wire) {
+    try {
+        if (!Array.isArray(history) || history.length === 0)
+            return 0;
+        if (!Array.isArray(wire) || wire.length === 0)
+            return 0;
+        const last = wire[wire.length - 1];
+        const wireContent = typeof last?.content === 'string' ? last.content : '';
+        if (!wireContent.startsWith(CURRENT_TURN_MARKER))
+            return 0; // 没注入过 → 不动
+        for (let i = history.length - 1; i >= 0; i--) {
+            const entry = history[i];
+            const inner = typeof entry?.content === 'string' ? entry.content : '';
+            if (!inner)
+                continue;
+            if (!wireContent.endsWith(inner))
+                continue;
+            const prefix = wireContent.slice(0, wireContent.length - inner.length);
+            if (!prefix || !prefix.startsWith(CURRENT_TURN_MARKER))
+                continue;
+            entry.content = wireContent;
+            return 1;
+        }
+        return 0;
+    }
+    catch {
+        return 0; // 写回失败绝不影响对话本身
+    }
+}
 export class PiAgentSession {
     cwd;
     peerId;
@@ -1775,12 +1826,14 @@ ${PiAgentSession.TOOL_SELECTION_GUIDE}
                     .join('\n');
                 loopProgressSection = `\n【本轮循环进度】你已完成以下 ${loopActionLog.length} 个动作, 这是连续执行的同一轮任务:\n${actionLines}\n请基于已有结果继续推进, 不要重复执行上面已成功的动作. 全部完成后用 <final gen> 结束.\n`;
             }
+            // 2026-09-28 (前缀 KV 可命中): `refineContext` / `loopProgressSection` 是**每轮都在变**的段
+            //   (质量分 / 连续错误数 / 本轮已完成动作). 留在 system 里 = 每轮把 IMMUTABLE PREFIX 打碎 =
+            //   服务端前缀 KV 永远 miss. 移到 CURRENT TURN 区 (注入到最后一条 user 前部) —— 文本一字未改, 只换位置.
+            const currentTurnContext = `${refineContext}${loopProgressSection}`;
             const systemPrompt = `${this.bootstrapAddition}你是 ${this.identity.name}，基于ReAct (Reasoning + Acting)模式工作。${personaSection}
 当前工作目录: ${this.cwd}
 当前身份: ${this.identity.name} (${this.identity.did})
-${refineContext}
 ${this.currentIntentHint}
-${loopProgressSection}
 
 ${toolDefs}
 
@@ -1830,7 +1883,11 @@ ${PiAgentSession.TOOL_SELECTION_GUIDE}
             // 2026-09-16 (Milestone 1-B): 模型调用前后走唯一门面 (扩展点 + 计数留痕; 默认不加新 hook 事件, 避免改变现有触发次数)
             this.piHarness().beforeModelCall(this.harnessCtx());
             const _modelCallT0 = Date.now();
-            const response = await this.callLlmWithRecovery(llm, messages, systemPrompt, signal, onStream, openaiFormattedTools);
+            const response = await this.callLlmWithRecovery(llm, messages, systemPrompt, signal, onStream, openaiFormattedTools, currentTurnContext);
+            // 2026-09-28 (前缀 KV 可命中): 把注入了 CURRENT TURN 的当前轮**原样写回自己的 messageHistory** ——
+            //   buildMessages() 每轮重建全新对象, 不写回的话下一轮那条 user 就退回注入前, 前缀从那里分叉.
+            //   用 chat() 回带的 wire (真正发出去的那一份), 而不是把 messages 再拼一遍.
+            this.writeBackCurrentTurn(response.messages);
             this.piHarness().afterModelCall(this.harnessCtx(), { ms: Date.now() - _modelCallT0 });
             const reply = (response.reply || '').trim();
             // 2026-06-30: OpenAI 协议 native tool_calls (LLM 真产了 tool_call 时, minimax/M3 会返回 id)
@@ -2571,6 +2628,11 @@ ${PiAgentSession.TOOL_SELECTION_GUIDE}
             const source = this.projectedHistory ?? this.messageHistory;
             const WINDOW = 15;
             const out = [];
+            // 2026-09-28 (前缀 KV 可命中): 带 CURRENT TURN 注入的条目要**原样回带**.
+            // 两个理由: (1) 注入块是"当前轮的前缀", 重渲染 (重加 `[工具结果]` 前缀 / 再 slice 截断)
+            //   会改字节 → 下一轮前缀从这条起分叉; (2) 已注入的 tool 条目在 wire 上已经是 user 形状,
+            //   再套一次前缀就是双前缀, 连内容都变了.
+            const isInjectedEntry = (m) => typeof m.content === 'string' && m.content.includes(CURRENT_TURN_MARKER);
             // 早期历史压缩: 超过窗口时, 不直接丢弃 — 提取前段用户意图摘要注入 (同步, 无 LLM).
             // 结构对齐 Context OS: System Prompt(persona) + 压缩摘要 + 最近消息.
             if (source.length > WINDOW) {
@@ -2586,6 +2648,10 @@ ${PiAgentSession.TOOL_SELECTION_GUIDE}
                 });
                 for (const m of slice) {
                     const r = m.role;
+                    if (isInjectedEntry(m)) {
+                        out.push({ role: 'user', content: String(m.content) });
+                        continue;
+                    }
                     if (r === 'tool') {
                         out.push({ role: 'user', content: `[工具结果]\n${(m.content || '').slice(0, 2000)}` });
                         continue;
@@ -2608,6 +2674,10 @@ ${PiAgentSession.TOOL_SELECTION_GUIDE}
             const slice = source.slice(-WINDOW);
             for (const m of slice) {
                 const r = m.role;
+                if (isInjectedEntry(m)) {
+                    out.push({ role: 'user', content: String(m.content) });
+                    continue;
+                }
                 if (r === 'tool') {
                     out.push({ role: 'user', content: `[工具结果]\n${m.content || ''}` });
                     continue;
@@ -2631,6 +2701,20 @@ ${PiAgentSession.TOOL_SELECTION_GUIDE}
             return [{ role: 'user', content: this.buildContext() }];
         }
     }
+    /**
+     * 2026-09-28 (前缀 KV 可命中): 把 chat() 回带的当前轮写回自己的 messageHistory.
+     * 逻辑在模块级 `writeBackCurrentTurnInto` (纯函数, 门可以直接驱它断言);
+     * 这里只负责接到 `this.messageHistory` 上, 并保证任何异常都静默 (写回失败不影响对话).
+     */
+    writeBackCurrentTurn(wire) {
+        try {
+            return writeBackCurrentTurnInto(this.messageHistory, wire);
+        }
+        catch (err) {
+            console.warn('[PiAgent] writeBackCurrentTurn failed (silent):', err);
+            return 0;
+        }
+    }
     /**
      * 估算 messageHistory 的 token 数 (4 字符 ≈ 1 token, 与 context-compaction 同步).
      * 失败静默: 任何异常 → 0 (不阻塞)
@@ -2652,7 +2736,9 @@ ${PiAgentSession.TOOL_SELECTION_GUIDE}
      *
      * 失败静默: 全部失败 → 返回空 reply, 让上层 no-tool_use 终止
      */
-    async callLlmWithRecovery(llm, contextOrMessages, systemPrompt, signal, onStream, tools) {
+    async callLlmWithRecovery(llm, contextOrMessages, systemPrompt, signal, onStream, tools, 
+    /** 2026-09-28: 当前轮易变段 (循环进度/改进提示) —— 进 CURRENT TURN 区, 不进 system */
+    currentTurnContext) {
         // Reactive compaction 预检: 估算 token 超 80% 阈值, 跑一次
         const estimated = this.estimateHistoryTokens();
         if (estimated > this.maxContextTokens() * 0.8) {
@@ -2706,9 +2792,13 @@ ${PiAgentSession.TOOL_SELECTION_GUIDE}
                 // M3.5 (2026-06-17): 传 messages 数组 (如果 contextOrMessages 是数组) 或字符串
                 //   数组版让 LLM 看到结构化的 user/assistant/tool role, 而不是把 history 拼成单字符串
                 // Bug 5: pass tool IDs for native OpenAI tool calling
-                const response = await llm.chat(contextOrMessages, systemPrompt, signal, tools);
+                // 2026-09-28 (前缀 KV 可命中): 显式 purpose/source —— pi-sdk 的 ReAct 循环**就是主对话**
+                //   (完整 IMMUTABLE PREFIX + 工具全集 + CURRENT TURN, 也只有它带 cache_prompt);
+                //   currentTurnContext 是调用方自己的当前轮易变段 (循环进度/改进提示), 走 CURRENT TURN 区.
+                // 2026-09-28: 回带最终 wire messages (含注入后的当前轮) → 上层据此写回 messageHistory.
+                const response = await llm.chat(contextOrMessages, systemPrompt, signal, tools, 'main-agent', 'react-loop', undefined, currentTurnContext);
                 // 2026-06-30: 透传 toolCalls (OpenAI 协议 native) 给上层, 让 assistant message 能 emit 真 id
-                return { reply: response.reply || '', toolCalls: response.toolCalls };
+                return { reply: response.reply || '', toolCalls: response.toolCalls, messages: response.messages };
             }
             catch (err) {
                 // 用户主动 abort: 不重试, 立即抛
@@ -2816,7 +2906,9 @@ ${PiAgentSession.TOOL_SELECTION_GUIDE}
         // 给 Context Collapse (虚拟投影) 和 Auto-Compact (摘要) 共用
         const llm = getMinimax();
         const llmChat = async (systemPrompt, userPrompt) => {
-            const r = await llm.chat(userPrompt, systemPrompt, signal);
+            // 2026-09-28 (前缀 KV 可命中): 压缩摘要是**非主对话的一次性调用** → 轻量前缀
+            //   (它不该拖满 IMMUTABLE PREFIX, 更不该把主对话的 KV slot 顶掉).
+            const r = await llm.chat(userPrompt, systemPrompt, signal, undefined, 'auto-compact', 'pi-sdk-compact');
             return r.reply;
         };
         // 2026-08-06: 预算 = ContextManager 配置 (1M * 55% ≈ 550K), 不再写死 8000.
@@ -3082,7 +3174,8 @@ ${this.extractOperationsFromRef(operationsRef)}
         const conversation = messages.map(m => `${m.type === 'user' ? '用户' : '助手'}: ${m.content}`).join('\n');
         const llm = getMinimax();
         try {
-            const response = await llm.chat(`根据以下对话内容，为这个对话生成一个简短的名称（不超过20个字）：\n\n${conversation}\n\n直接输出名称，不要其他解释。`, '命名建议');
+            const response = await llm.chat(`根据以下对话内容，为这个对话生成一个简短的名称（不超过20个字）：\n\n${conversation}\n\n直接输出名称，不要其他解释。`, '命名建议', undefined, undefined, 'chat', 'session-namer' // 非主对话: 轻量前缀, 不抢主对话的 KV slot
+            );
             const name = response.reply.trim();
             // 拒绝错误回退串 (LLM 不可用时返回的占位文本)
             if (!name)

package/dist/agents/workflow-pivot-loop.js

@@ -329,7 +329,9 @@ export class WorkflowPivotLoop {
                 // 2026-08-02: 传原生 OpenAI tools — deepseek 返回结构化 tool_calls,
                 //   UI 才能显示真实的工具执行 step (之前靠文本 JSON 猜格式, LLM 编造 result)
                 const openAITools = this.buildOpenAITools();
-                const llmResponse = await llm.chat(context, headerForThisIter, signal, openAITools);
+                // 2026-09-28: pivot loop 就是主对话循环 → purpose='main-agent'
+                //   (完整 IMMUTABLE PREFIX + 工具全集 + CURRENT TURN; 也只有它带 cache_prompt)
+                const llmResponse = await llm.chat(context, headerForThisIter, signal, openAITools, 'main-agent', 'pivot-loop');
                 const reply = (llmResponse.reply || '').trim();
                 this.vlog(`[pivot] iter=${this.state.iteration} LLM took=${Date.now() - t0}ms reply=${reply.length} nativeToolCalls=${llmResponse.toolCalls?.length ?? 0} head=${reply.substring(0, 80).replace(/\n/g, ' ')}`);
                 this.emit({ type: 'token', content: reply });

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