@bolloon/bolloon-agent 0.5.1 → 0.5.2

package/dist/llm/pi-ai.js

@@ -1,15 +1,253 @@
 import * as path from 'path';
 import * as fs from 'fs';
+import { createHash } from 'crypto';
 import { request, Agent } from 'undici';
 import { sanitizeToolsForApi } from './tool-name.js';
+/** 本地 llama.cpp 的声明 id / 默认端点 / 默认模型名 (都能被 env 或显式 config 覆盖) */
+export const LLAMACPP_PROVIDER_ID = 'llamacpp';
+export const LLAMACPP_DEFAULT_BASE_URL = 'http://localhost:8080/v1';
+export const LLAMACPP_DEFAULT_MODEL = 'local';
+/** 唯一的重路径用途 */
+export const MAIN_AGENT_PURPOSE = 'main-agent';
+/** 轻量前缀的 system 上限 (字符). 只对**自动装配部分 + 调用方自带短提示**做兜底截断, 正常调用远低于它 */
+export const LIGHTWEIGHT_SYSTEM_MAX_CHARS = 2000;
+/**
+ * 这条请求走不走轻量前缀. **只有 `main-agent` 是重路径** —— 其余 (含没写 purpose 的老调用方)
+ * 一律轻量: 未知用途名按轻量处理 (宁可少给前缀, 也不让探针抢掉主对话的 KV slot).
+ */
+export function isLightweightPurpose(purpose) {
+    return (purpose || 'chat') !== MAIN_AGENT_PURPOSE;
+}
+/**
+ * 要不要在请求体里带 `cache_prompt` (llama.cpp 的前缀 KV 复用开关).
+ *
+ * **仅 `main-agent` 为 true**; `BOLLOON_DISABLE_CACHE_PROMPT=1` 彻底关 (含主对话).
+ * 纯函数: 门可以逐 purpose 断言, 不需要发请求.
+ */
+export function shouldUseCachePrompt(purpose, env = process.env) {
+    if (env.BOLLOON_DISABLE_CACHE_PROMPT === '1')
+        return false;
+    return (purpose || 'chat') === MAIN_AGENT_PURPOSE;
+}
+/** 本机 endpoint 判定 (`cache_prompt` 是自建服务的扩展字段, 云端不认 —— 只在本机才带) */
+export function isLocalEndpoint(baseUrl) {
+    try {
+        const host = new URL(baseUrl).hostname.replace(/^\[|\]$/g, '').toLowerCase();
+        return host === 'localhost' || host === '127.0.0.1' || host === '0.0.0.0' || host === '::1' || host.endsWith('.local');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * CURRENT TURN 动态区的标记 —— 注入幂等的唯一判据 (已含标记 → 跳过, 不重复注入、不追加多余 user 消息).
+ * 名字里的 runtime/git/p2p 就是这一区的三类内容: 运行时状态 / git 状态 / P2P reserve.
+ */
+export const CURRENT_TURN_MARKER = '<!-- current-turn: runtime/git/p2p -->';
+/** CURRENT TURN 区块自身的预算 (字符) —— 防止动态区反过来把用户原话挤出上层的历史窗口 */
+export const CURRENT_TURN_BUDGET_CHARS = 2400;
+/**
+ * 按预算组装 CURRENT TURN 区块 (**从后往前**填: 越靠后的段越优先保住).
+ *
+ * 为什么是"从后往前": 段落顺序是 `registry 动态层 → P2P reserve → 调用方易变段(循环进度/改进提示)`,
+ *   最后那段是**最可操作**的指令 (循环进度丢了 LLM 会重复劳动); 而 registry 动态层与 system 里的
+ *   项目上下文高度重复, 被截掉损失最小. 所以超预算时先压前面的段.
+ */
+export function assembleCurrentTurn(parts, budget = CURRENT_TURN_BUDGET_CHARS) {
+    const kept = [];
+    let used = 0;
+    let dropped = false;
+    for (let i = parts.length - 1; i >= 0; i--) {
+        const p = String(parts[i] ?? '').trim();
+        if (!p)
+            continue;
+        const remain = budget - used;
+        if (remain < 50) {
+            dropped = true;
+            continue;
+        }
+        if (p.length <= remain) {
+            kept.unshift(p);
+            used += p.length;
+        }
+        else {
+            kept.unshift(`${p.slice(0, remain)}\n[… CURRENT TURN 超预算截断]`);
+            used = budget;
+        }
+    }
+    if (dropped)
+        kept.unshift('[… CURRENT TURN 区块超预算: 靠前的段被丢弃]');
+    return kept.join('\n\n');
+}
+/** 系统提示词装配缓存的 TTL (10 分钟) */
+export const SYSTEM_PROMPT_CACHE_TTL_MS = 10 * 60 * 1000;
+/**
+ * 2026-09-28: `canonicalizeJson` — 递归对**对象 key 排序**, **数组保序**.
+ *
+ * 为什么: 工具 schema (`parameters.properties` / 嵌套对象) 的 key 顺序若由调用方动态生成,
+ * 每轮可能不同; 语义相同但 JSON.stringify 出的字节不同 → chat template 渲染出的 token 前缀
+ * 不同 → 服务端前缀 KV 命中失败. 规范化后同一份 schema 永远序列化成同一个字符串.
+ */
+export function canonicalizeJson(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeJson); // 数组有序语义, 保序
+    if (value && typeof value === 'object') {
+        const sorted = {};
+        for (const k of Object.keys(value).sort())
+            sorted[k] = canonicalizeJson(value[k]);
+        return sorted;
+    }
+    return value;
+}
+/**
+ * 2026-09-28: 工具定义规范化 —— 递归 key 排序 + **按 `function.name` 排序**.
+ *
+ * 跨轮前缀稳定前提: 工具集合相同, 但顺序不同 (`read,write,grep` vs `read,grep,write`) 或
+ * schema 内 key 顺序不同, 都会让 token 前缀断裂. 这里把两种抖动都消掉.
+ */
+export function canonicalizeTools(tools) {
+    if (!Array.isArray(tools))
+        return tools;
+    return tools
+        .map((t) => canonicalizeJson(t))
+        .sort((a, b) => String(a?.function?.name || '').localeCompare(String(b?.function?.name || '')));
+}
+/** 运行前缀哈希序列 (逐消息累积, sha256[:12]) —— 诊断用, 只出 hash 不出内容 */
+export function prefixHashes(wire) {
+    const out = [];
+    let acc = '';
+    for (const m of wire) {
+        acc += JSON.stringify({ role: m?.role, content: m?.content ?? '' });
+        out.push(createHash('sha256').update(acc).digest('hex').slice(0, 12));
+    }
+    return out;
+}
+/** 工具面的 hash (诊断用, 只出 hash) */
+export function toolsHashOf(tools) {
+    if (!tools || tools.length === 0)
+        return '-';
+    // 先规范化再 hash: 这个数字回答的是"**上到线上的那份** tools 段变了吗", 而不是"调用方这次传的顺序变了吗"
+    return createHash('sha256').update(JSON.stringify(canonicalizeTools(tools))).digest('hex').slice(0, 12);
+}
+/**
+ * 从响应里取用量 (只取数字, 出处逐条可指认):
+ *   - OpenAI/DeepSeek: `usage.prompt_tokens_details.cached_tokens` / `usage.prompt_tokens`;
+ *   - llama.cpp: `timings.cache_n` (复用的 token 数) / `timings.prompt_n`.
+ */
+export function extractUsage(data) {
+    const t = data?.timings || {};
+    return {
+        promptTokens: Number(data?.usage?.prompt_tokens ?? t.prompt_n ?? 0) || 0,
+        cachedTokens: Number(data?.usage?.prompt_tokens_details?.cached_tokens ?? data?.usage?.prompt_cache_hit_tokens ?? t.cache_n ?? 0) || 0,
+        completionTokens: Number(data?.usage?.completion_tokens ?? t.predicted_n ?? 0) || 0,
+    };
+}
+/** `[kv-server]` 诊断行 (纯函数: 只拼数字与百分比, 门可以断言形状) */
+export function formatKvServerLine(purpose, usage, opts = {}) {
+    const hit = usage.promptTokens > 0 ? `${((usage.cachedTokens / usage.promptTokens) * 100).toFixed(1)}%` : '?';
+    return `[kv-server] purpose=${purpose}${opts.stream ? ' stream' : ''} cached=${usage.cachedTokens} prompt=${usage.promptTokens} hit=${hit}`;
+}
+/**
+ * 把动态区注入「最后一条 user 消息」前部 (CURRENT TURN 区), **原地改**.
+ *
+ * 幂等: 目标消息已含 `CURRENT_TURN_MARKER` → 跳过 (多 iteration / 重试 / 重复调用都不重复注入).
+ * 位置: 只找最后一条 user (= 当前轮), 不碰 assistant/tool —— 往那些注入会污染历史;
+ *   整段没有 user → 返回 `no-user-message` 交给调用方决定 (chat() 会明确追加一条, 绝不写回 system).
+ */
+export function injectCurrentTurn(messages, dynamicText) {
+    if (!dynamicText || !dynamicText.trim())
+        return { injected: false, index: -1, reason: 'no-dynamic-text' };
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (!m || m.role !== 'user')
+            continue;
+        if (typeof m.content === 'string' && m.content.includes(CURRENT_TURN_MARKER)) {
+            return { injected: false, index: i, reason: 'already' };
+        }
+        const body = dynamicText.length > CURRENT_TURN_BUDGET_CHARS + 400
+            ? `${dynamicText.slice(0, CURRENT_TURN_BUDGET_CHARS + 400)}\n[… CURRENT TURN 区块超预算截断]`
+            : dynamicText;
+        m.content = `${CURRENT_TURN_MARKER}\n${body}\n\n---\n\n${m.content ?? ''}`;
+        return { injected: true, index: i, reason: 'injected' };
+    }
+    return { injected: false, index: -1, reason: 'no-user-message' };
+}
+/** 用途 → 中文名 (轻量前缀里给人看的那一行, 也是日志口径) */
+const PURPOSE_ZH = {
+    'main-agent': '主对话',
+    summarize: '摘要',
+    improve: '文档改进',
+    'auto-compact': '上下文压缩',
+    social: '社交心跳',
+    health: '健康探针',
+    p2p: 'P2P 协作',
+    cron: '定时任务',
+    judgment: '判断力评估',
+    probe: '能力探测',
+    chat: '一次性调用',
+};
+/**
+ * 轻量 system —— 非主对话请求用. 结构:
+ *   `<一行身份/用途说明>` + (调用方自带的短提示原样保留)
+ * **不带**完整 IMMUTABLE PREFIX (layer 装配) / 工具全集 / CURRENT TURN 动态区.
+ * 调用方自带提示超上限时截断 (并写明截断), 避免一次性探针把大前缀带出去.
+ */
+export function buildLightweightSystem(purpose, source, callerSystem) {
+    const head = `你是 Bolloon Agent 的轻量调用助手 (用途: ${PURPOSE_ZH[purpose] || purpose}${source ? ` · 来源: ${source}` : ''})。只完成下面这一件事, 直接输出结果; 不要调用工具。`;
+    const caller = String(callerSystem || '').trim();
+    if (!caller)
+        return head;
+    const capped = caller.length > LIGHTWEIGHT_SYSTEM_MAX_CHARS
+        ? `${caller.slice(0, LIGHTWEIGHT_SYSTEM_MAX_CHARS)}\n[… 轻量请求 system 超上限截断]`
+        : caller;
+    return `${head}\n\n${capped}`;
+}
+/**
+ * 2026-09-28: 把装配好的系统提示词按 layer 标记拆成「稳定段」与「动态段」.
+ *
+ * 动态段 = registry 里 `source === 'function'` 的那几层 (本仓目前只有 `dynamic.project-context`:
+ *   它会随 cwd / git 状态变化). 这几层从 system 里移出 → system 逐字节稳定 → 服务端前缀 KV 能复用.
+ *
+ * 拆法: 装配器给每层写了 `<!-- id@version -->` 头 (见 system-prompt/registry.ts),
+ *   按这些标记切块; 标记之间的内容归它前面那个 id. 找不到任何标记 → 整段算稳定段 (不抛错).
+ */
+export function splitLayerBlocks(text, dynamicIds) {
+    const re = /<!--\s*([A-Za-z0-9_.\-]+)@([A-Za-z0-9_.\-]+)\s*-->/g;
+    const marks = [];
+    let m;
+    while ((m = re.exec(text)) !== null)
+        marks.push({ id: m[1], start: m.index, end: m.index + m[0].length });
+    if (marks.length === 0)
+        return { stableText: text.trim(), dynamicText: '' };
+    const stable = [];
+    const dynamic = [];
+    const head = text.slice(0, marks[0].start).trim();
+    if (head)
+        stable.push(head);
+    for (let i = 0; i < marks.length; i++) {
+        const from = marks[i].end;
+        const to = i + 1 < marks.length ? marks[i + 1].start : text.length;
+        const content = text.slice(from, to).trim();
+        (dynamicIds.has(marks[i].id) ? dynamic : stable).push(content);
+    }
+    return {
+        stableText: stable.filter(Boolean).join('\n\n').trim(),
+        dynamicText: dynamic.filter(Boolean).join('\n\n').trim(),
+    };
+}
 /**
  * 外部 system 注入钩子.
  * 调用方 (e.g. auto-evolve-loop) 用 setSystemPrependProvider() 注册一个返回字符串的函数,
- * generateText 在拼 finalMessages 时, 把返回的字符串作为最前一个 system message.
+ * chat() 在拼好 messages 后, 把返回的字符串作为 **CURRENT TURN 动态区**的一部分, 注入到最后一条
+ * user 消息前部 (位于 IMMUTABLE PREFIX + CONVERSATION HISTORY 之后)。
  *
  * 用途: P2P 协作时把"行级 reserve 状态"实时塞给 LLM,
  *       让 LLM 主动避开对方正在改的代码行.
  *
+ * ⚠️ 2026-09-28: 只在 chat() 路径生效 (只注入主对话的当前轮), 不进 system ——
+ *   这份 reserve 状态每轮都在变, 写回 system 就等于把 IMMUTABLE PREFIX 打碎, 前缀 KV 永远 miss。
+ *   summarize/improve 这类一次性请求也不再注入它 (不污染探针的 prompt 前缀)。
+ *
  * 返回 '' / null / undefined → 不注入.
  */
 let _prependProvider = null;
@@ -19,6 +257,66 @@ export function setSystemPrependProvider(p) {
 export function getSystemPrependProvider() {
     return _prependProvider;
 }
+let _systemPromptCache = null;
+/** 清空系统提示词缓存 (配置/provider 变更、layer 文件热更时调用) */
+export function clearSystemPromptCache() {
+    _systemPromptCache = null;
+}
+/** 诊断/门用: 缓存条目的 key 与写入时间 (**只给数字与键名, 不给内容**) */
+export function systemPromptCacheStamp() {
+    return _systemPromptCache ? { key: _systemPromptCache.key, at: _systemPromptCache.at } : null;
+}
+/** 诊断/门用: 稳定段的 sha256[:12] (不是内容) —— 门用它断言 system 段跨轮逐字节稳定 */
+export function systemPromptStableHash() {
+    if (!_systemPromptCache)
+        return null;
+    return createHash('sha256').update(_systemPromptCache.stableText).digest('hex').slice(0, 12);
+}
+/** DEBUG_PROMPT_PREFIX=1 时逐消息打前缀哈希用; 记上一轮, 好报"第几条开始分叉" */
+let _lastPrefixHashes = [];
+/**
+ * 2026-09-28 诊断 (只打数字与 hash, 不打内容也不打 key):
+ *   `[kv-debug] msg=i role=… prefixHash=… chars=…` 逐消息的**累积前缀**哈希
+ *   `[kv-debug] tools count=… hash=…`
+ *   `[kv-debug] 对比: 与上一次请求在第 N 条分叉 / 前缀逐条一致`
+ * ⚠️ 这是 HTTP JSON 层的前缀哈希, 不是 chat template 渲染后的 token 前缀哈希;
+ *   用途是快速定位"应用层 messages 前缀在哪一条断裂", 缩小排查范围。
+ */
+function debugDumpPromptPrefix(wire, tools) {
+    const hashes = prefixHashes(wire);
+    let chars = 0;
+    for (let i = 0; i < wire.length; i++) {
+        chars += JSON.stringify({ role: wire[i]?.role, content: wire[i]?.content ?? '' }).length;
+        console.log(`[kv-debug] msg=${i} role=${wire[i]?.role} prefixHash=${hashes[i]} chars=${chars}`);
+    }
+    console.log(`[kv-debug] tools count=${tools?.length ?? 0} hash=${toolsHashOf(tools)}`);
+    if (_lastPrefixHashes.length > 0) {
+        let diverged = -1;
+        const n = Math.max(hashes.length, _lastPrefixHashes.length);
+        for (let i = 0; i < n; i++) {
+            if (hashes[i] !== _lastPrefixHashes[i]) {
+                diverged = i;
+                break;
+            }
+        }
+        if (diverged < 0)
+            console.log(`[kv-debug] 对比上一次请求: 前缀逐条一致 (共 ${hashes.length} 条)`);
+        else
+            console.log(`[kv-debug] 对比上一次请求: 第 ${diverged} 条起分叉 (上一次 ${_lastPrefixHashes.length} 条 → 本次 ${hashes.length} 条)`);
+    }
+    _lastPrefixHashes = hashes;
+}
+/**
+ * BOLLOON_PROMPT_PROFILE=1 时每次调用打一行 prompt 分部体积 (**只打数字与 hash**),
+ * 用来回答"这次请求到底是哪一段在膨胀 / 哪一段在抖动"。
+ */
+function logPromptProfile(info) {
+    if (process.env.BOLLOON_PROMPT_PROFILE !== '1')
+        return;
+    console.log(`[prompt-profile] purpose=${info.purpose} source=${info.source || '-'} profile=${info.profile}` +
+        ` systemCache=${info.cached ? 'hit' : 'miss'} stable=${info.stableChars} dynamic=${info.dynamicChars}` +
+        ` history=${info.historyChars} msgs=${info.messageCount} tools=${info.toolsCount} toolsHash=${info.toolsHash}`);
+}
 export class PiAIModel {
     config;
     provider;
@@ -98,25 +396,120 @@ export class PiAIModel {
      *   LLM 看不到 tool 调用的真实结果,导致 CLI loop 卡死.
      *   现在 messages 数组版本保留 role 语义, LLM 能正确看到工具返回.
      */
-    async chat(messageOrMessages, contextOrSystemPrompt, signal, tools) {
-        const systemPrompt = await this.buildSystemPromptAsync(contextOrSystemPrompt);
+    /**
+     * ⚠️ 参数顺序 (2026-09-28 起): `(messages, system, signal?, tools?, purpose?, source?, onToken?, currentTurnContext?)`
+     *   - `purpose` 决定重/轻前缀与 cache_prompt (只有 'main-agent' 是重路径);
+     *   - `currentTurnContext` = 调用方自己的**当前轮易变段** (如 pi-sdk 的循环进度/改进提示):
+     *     它进 CURRENT TURN 动态区, **绝不进 system** —— 每轮都在变的东西放 system 会把
+     *     IMMUTABLE PREFIX 打碎, 服务端前缀 KV 就永远命不中 (文本一字未改, 只换位置).
+     */
+    async chat(messageOrMessages, contextOrSystemPrompt, signal, tools, purpose, source, onToken, currentTurnContext) {
+        const _purpose = purpose || 'chat';
+        const light = isLightweightPurpose(_purpose);
+        const callerArr = Array.isArray(messageOrMessages) ? messageOrMessages : null;
         let messages;
-        if (Array.isArray(messageOrMessages)) {
-            messages = [{ role: 'system', content: systemPrompt }, ...messageOrMessages];
+        /** CURRENT TURN 动态区内容 (registry 的 function 层 + P2P reserve); 轻量请求不带 */
+        const currentTurnParts = [];
+        let stableChars = 0;
+        let systemCacheHit = false;
+        if (light) {
+            // ── 轻量路径 (2026-09-28): 非主对话请求不带完整 IMMUTABLE PREFIX / 工具全集 / CURRENT TURN ──
+            // 目的 (leo): 本地单 slot 服务上, 探针/摘要/心跳不该把主对话的 KV 顶掉, 也不该为一次性调用付大前缀.
+            const lightSystem = buildLightweightSystem(_purpose, source, contextOrSystemPrompt);
+            stableChars = lightSystem.length;
+            messages = callerArr
+                ? [{ role: 'system', content: lightSystem }, ...callerArr]
+                : [{ role: 'system', content: lightSystem }, { role: 'user', content: messageOrMessages }];
+            if (tools && tools.length > 0) {
+                // 不静默丢: 打一行数字, 让"为什么工具没被调用"可诊断
+                console.warn(`[pi-ai] 轻量请求丢弃工具集 (purpose=${_purpose}, tools=${tools.length}) —— 需要工具请用 purpose='main-agent'`);
+                tools = undefined;
+            }
+        }
+        else if (Array.isArray(messageOrMessages)) {
+            if (contextOrSystemPrompt && contextOrSystemPrompt.length > 2000) {
+                // pivot loop 兼容: 第二参 >2K = system prompt 覆盖 → 接在稳定段之后 (**仍在 system 里, 位置与旧版一致**:
+                //   旧版 = 装配文本 + '\n\n' + 覆盖文本). 只有 registry 的动态层被移出 system.
+                const parts = await this.buildSystemPromptParts(undefined);
+                systemCacheHit = parts.cached;
+                stableChars = parts.stableText.length + contextOrSystemPrompt.length;
+                if (parts.dynamicText)
+                    currentTurnParts.push(parts.dynamicText);
+                messages = [
+                    { role: 'system', content: `${parts.stableText}\n\n${contextOrSystemPrompt}` },
+                    ...messageOrMessages
+                ];
+            }
+            else {
+                const parts = await this.buildSystemPromptParts(contextOrSystemPrompt);
+                systemCacheHit = parts.cached;
+                stableChars = parts.stableText.length;
+                if (parts.dynamicText)
+                    currentTurnParts.push(parts.dynamicText);
+                messages = [{ role: 'system', content: parts.stableText }, ...messageOrMessages];
+            }
         }
         else if (contextOrSystemPrompt && contextOrSystemPrompt.length > 2000) {
-            const baseSystem = await this.buildSystemPromptAsync(undefined);
+            const parts = await this.buildSystemPromptParts(undefined);
+            systemCacheHit = parts.cached;
+            stableChars = parts.stableText.length + contextOrSystemPrompt.length;
+            if (parts.dynamicText)
+                currentTurnParts.push(parts.dynamicText);
             messages = [
-                { role: 'system', content: baseSystem + '\n\n' + contextOrSystemPrompt },
+                { role: 'system', content: `${parts.stableText}\n\n${contextOrSystemPrompt}` },
                 { role: 'user', content: messageOrMessages }
             ];
         }
         else {
+            const parts = await this.buildSystemPromptParts(contextOrSystemPrompt);
+            systemCacheHit = parts.cached;
+            stableChars = parts.stableText.length;
+            if (parts.dynamicText)
+                currentTurnParts.push(parts.dynamicText);
             messages = [
-                { role: 'system', content: systemPrompt },
+                { role: 'system', content: parts.stableText },
                 { role: 'user', content: messageOrMessages }
             ];
         }
+        // 2) 外部 prepend (P2P 行级 reserve 状态) —— 与动态层一起进 CURRENT TURN 区, 不进 system
+        if (!light && _prependProvider) {
+            try {
+                const pre = await _prependProvider();
+                if (pre && typeof pre === 'string' && pre.trim())
+                    currentTurnParts.push(pre);
+            }
+            catch (err) {
+                console.warn('[pi-ai] systemPrepend 失败:', err?.message?.slice(0, 100));
+            }
+        }
+        // 3) 调用方自己的"当前轮易变段" (pi-sdk 的循环进度 / 改进提示 / 错误提示) —— 同样进 CURRENT TURN 区.
+        //    它们每 iteration 都在变; 留在 system 里 = 把 IMMUTABLE PREFIX 打碎 = 前缀 KV 永远 miss.
+        if (!light && currentTurnContext && currentTurnContext.trim())
+            currentTurnParts.push(currentTurnContext);
+        // 4) 注入 CURRENT TURN 区到最后一条 user 消息前部 (幂等: 已含标记则跳过)
+        const dynamicText = assembleCurrentTurn(currentTurnParts);
+        if (!light && dynamicText.trim()) {
+            const inj = injectCurrentTurn(messages, dynamicText);
+            if (inj.reason === 'no-user-message') {
+                // 一条 user 都没有 (纯 assistant 历史) → 明确追加一条, **绝不写回 system**
+                const extra = { role: 'user', content: '' };
+                injectCurrentTurn([extra], dynamicText);
+                messages.push(extra);
+                if (callerArr)
+                    callerArr.push(extra); // 回写调用方数组, 保证下一轮不重复追加
+                console.log('[pi-ai] CURRENT TURN 追加独立 user 消息 (历史里没有 user)');
+            }
+            else if (inj.reason === 'injected') {
+                console.log(`[pi-ai] CURRENT TURN 注入 msg=${inj.index} dynamic=${dynamicText.length}chars`);
+            }
+        }
+        const historyChars = messages.reduce((n, m) => n + (typeof m.content === 'string' ? m.content.length : 0), 0) - stableChars;
+        logPromptProfile({
+            purpose: _purpose, source, profile: light ? 'light' : 'full',
+            stableChars, dynamicChars: dynamicText.length, historyChars: Math.max(0, historyChars),
+            messageCount: messages.length, toolsCount: tools?.length ?? 0,
+            toolsHash: toolsHashOf(tools), cached: systemCacheHit,
+        });
         try {
             const response = await this.generateText({
                 messages,
@@ -124,8 +517,17 @@ export class PiAIModel {
                 maxTokens: 16384, // 2026-06-17: 提到 16384 — agent 注入 16K+ system prompt + 8K tool defs 时, 8K 撞上限返回空 content (见 memory: bolloon-llm-empty-large-prompt)
                 signal,
                 tools, // pass through for native tool calling
+                onToken,
+                purpose: _purpose,
+                source,
             });
-            return { reply: response.reply, toolCalls: response.toolCalls };
+            return {
+                reply: response.reply,
+                reasoningContent: response.reasoningContent,
+                toolCalls: response.toolCalls,
+                messages, // 回带最终 wire messages: 调用方据此把当前轮写回自己的 history
+                usage: response.usage,
+            };
         }
         catch (error) {
             // abort 不当作错误, 透传一个 sentinel 让上层能识别
@@ -150,14 +552,24 @@ export class PiAIModel {
                 console.warn(`[llm-recovery] ${classified.category} attempt ${attempt + 1}/${MAX_RECOVERY_ATTEMPTS}, 退避 ${backoffMs}ms 重试`);
                 await new Promise((r) => setTimeout(r, backoffMs));
                 try {
+                    // 重试带着**同一份已注入的 messages** (幂等标记保证不会二次注入)
                     const response = await this.generateText({
                         messages,
                         temperature: 0.8,
                         maxTokens: 16384,
                         signal,
                         tools,
+                        onToken,
+                        purpose: _purpose,
+                        source,
                     });
-                    return { reply: response.reply, toolCalls: response.toolCalls };
+                    return {
+                        reply: response.reply,
+                        reasoningContent: response.reasoningContent,
+                        toolCalls: response.toolCalls,
+                        messages,
+                        usage: response.usage,
+                    };
                 }
                 catch (retryErr) {
                     if (signal?.aborted || retryErr?.name === 'AbortError')
@@ -186,7 +598,9 @@ export class PiAIModel {
                     { role: 'system', content: 'You are a professional document summarizer.' },
                     { role: 'user', content: prompt }
                 ],
-                temperature: 0.7
+                temperature: 0.7,
+                purpose: 'summarize',
+                source: 'pi-ai',
             });
             const qualityScore = this.estimateQuality(text, response.reply);
             return { summary: response.reply, qualityScore };
@@ -207,7 +621,9 @@ export class PiAIModel {
                     { role: 'system', content: 'You are a professional document editor and improver.' },
                     { role: 'user', content: prompt }
                 ],
-                temperature: 0.8
+                temperature: 0.8,
+                purpose: 'improve',
+                source: 'pi-ai',
             });
             return response.reply;
         }
@@ -217,21 +633,11 @@ export class PiAIModel {
         }
     }
     async generateText(options) {
-        const { messages, temperature = 0.7, maxTokens = 4096, signal, tools } = options;
+        const { messages, temperature = 0.7, maxTokens = 4096, signal, tools, onToken, purpose, source } = options;
         // 工具清单: 代码侧 schema → 进 system prompt (作为额外 system message)
         let finalMessages = messages;
-        // 1) 外部 prepend (e.g. P2P 行级 reserve 状态), 拼到最前
-        if (_prependProvider) {
-            try {
-                const pre = await _prependProvider();
-                if (pre && typeof pre === 'string' && pre.trim()) {
-                    finalMessages = [{ role: 'system', content: pre }, ...finalMessages];
-                }
-            }
-            catch (err) {
-                console.warn('[pi-ai] systemPrepend 失败:', err?.message?.slice(0, 100));
-            }
-        }
+        // 注 (2026-09-28): 外部 prepend (_prependProvider) 已上移到 chat() —— 它进 CURRENT TURN 动态区,
+        //   不再作为最前面的 system message (那份 reserve 状态每轮都在变, 放 system 会打碎 IMMUTABLE PREFIX).
         let openaiTools;
         if (tools && tools.length > 0) {
             // 预格式化的 tools (含参数 schema) → 直接使用
@@ -242,7 +648,9 @@ export class PiAIModel {
                 //   会让整个请求 400: Invalid 'tools[120].function.name': string does not match pattern.
                 //   净化同时把「原名 ↔ API 名」登记进 globalToolNameRoutes, 回程派发靠它还原成真名.
                 //   撞名/无名 → 抛错点名, 不许静默.
-                openaiTools = sanitizeToolsForApi(tools);
+                // 2026-09-28: 净化之后再做 `canonicalizeTools` (按 function.name 排序 + 递归 key 排序) ——
+                //   顺序与嵌套 key 顺序都不再抖动, 同一份工具集的 token 前缀跨轮逐字节一致.
+                openaiTools = canonicalizeTools(sanitizeToolsForApi(tools));
                 const toolDescriptions = openaiTools.map(t => `- ${t.function.name}: ${t.function.description || ''} ${Object.keys(t.function.parameters?.properties || {}).length > 0 ? `(${Object.keys(t.function.parameters.properties).join(', ')})` : ''}`).join('\n');
                 finalMessages = [{ role: 'system', content: `可用工具:\n${toolDescriptions}` }, ...messages];
             }
@@ -256,7 +664,7 @@ export class PiAIModel {
             case 'qwen':
             case 'mimo':
             case 'grok':
-                return this.callOpenAI(finalMessages, temperature, maxTokens, signal, openaiTools);
+                return this.callOpenAI(finalMessages, temperature, maxTokens, signal, openaiTools, onToken, purpose, source);
             case 'anthropic':
                 return this.callAnthropic(finalMessages, temperature, maxTokens, signal);
             case 'ollama':
@@ -272,6 +680,11 @@ export class PiAIModel {
         }
     }
     getApiKey() {
+        // 2026-09-28: llama.cpp (本地 OpenAI 兼容服务) —— 声明 id 单独接 key, key 可空
+        //   (llama-server 默认不校验 Authorization; 也支持 `--api-key` → 用 LLAMACPP_API_KEY 传)
+        if (this.config.providerId === LLAMACPP_PROVIDER_ID) {
+            return this.config.apiKey || process.env.LLAMACPP_API_KEY || '';
+        }
         return this.config.apiKey || this.getEnvApiKey();
     }
     getEnvApiKey() {
@@ -296,6 +709,11 @@ export class PiAIModel {
         if (this.config.baseUrl) {
             return this.config.baseUrl;
         }
+        // 2026-09-28: llama.cpp (本地 OpenAI 兼容服务) 的默认端点 —— 它按声明 id 单独接,
+        //   不混进下面那张「内置 13 家」的表 (那张表被源码级门钉着, 见 provider-registry.test.ts)。
+        if (this.config.providerId === LLAMACPP_PROVIDER_ID) {
+            return process.env.LLAMACPP_BASE_URL || LLAMACPP_DEFAULT_BASE_URL;
+        }
         // 允许通过 OPENAI_BASE_URL 等环境变量覆盖默认 base URL
         const baseUrls = {
             openai: process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1',
@@ -316,6 +734,11 @@ export class PiAIModel {
         return baseUrls[this.provider];
     }
     mapModel() {
+        // 2026-09-28: llama.cpp 的模型名 = 服务端加载的那份 (名字随 `-m` 走, 客户端不自造):
+        //   显式 config.model > LLAMACPP_MODEL > 'local' (占位, 服务端通常忽略未知 model 名)
+        if (this.config.providerId === LLAMACPP_PROVIDER_ID) {
+            return this.config.model || process.env.LLAMACPP_MODEL || LLAMACPP_DEFAULT_MODEL;
+        }
         // 2026-08-04: 型号全面更新 (官方文档确认):
         //   OpenAI gpt-5.6 (alias→Sol) / Anthropic claude-sonnet-5 / Gemini gemini-3.5-flash (pro 线最新, 3.5 仅 flash)
         //   Grok grok-4.5 / Kimi kimi-k3 / GLM glm-5.2 / Qwen qwen3-max
@@ -360,9 +783,12 @@ export class PiAIModel {
             ? { role: 'assistant', content: m.content ?? '', reasoning_content: m.reasoningContent ?? '' }
             : m);
     }
-    async callOpenAI(messages, temperature, maxTokens, signal, tools) {
+    async callOpenAI(messages, temperature, maxTokens, signal, tools, onToken, purpose, source) {
+        const _purpose = purpose || 'chat';
         const apiKey = this.getApiKey();
-        if (!apiKey) {
+        // 2026-09-28: 本地自建服务 (llama.cpp) 允许空 key —— `allowEmptyKey` 由 initPiAI 按声明 id 置位.
+        //   云端分支缺 key 仍然抛错 (老行为一字不变).
+        if (!apiKey && !this.config.allowEmptyKey) {
             throw new Error('OPENAI_API_KEY not set');
         }
         const requestBody = {
@@ -371,11 +797,32 @@ export class PiAIModel {
             temperature,
             max_tokens: maxTokens
         };
+        // 2026-09-28: 前缀 KV 复用开关 `cache_prompt`. 两处都卡住:
+        //   (1) 只对本机 endpoint 带这个字段 —— 它是自建服务 (llama.cpp) 的扩展, 云端不认,
+        //       白带一个未知字段有 400 风险; 换句话说云端分支的请求体与旧版逐字节相同.
+        //   (2) **只有 purpose='main-agent' 为 true**. 单 slot 的本地服务上, 探针/摘要/心跳
+        //       若也带 true, 会去抢 slot 0 驱逐主对话的 KV —— 那正是"主对话缓存无法命中"的一层根因.
+        //   `BOLLOON_DISABLE_CACHE_PROMPT=1` 彻底关 (见 shouldUseCachePrompt).
+        const localEndpoint = isLocalEndpoint(this.getBaseUrl());
+        if (localEndpoint) {
+            requestBody.cache_prompt = shouldUseCachePrompt(_purpose);
+        }
+        // 2026-09-28: 流式必须显式要 usage —— 否则 SSE 末帧不带 usage, 命中率测不到.
+        if (onToken) {
+            requestBody.stream = true;
+            requestBody.stream_options = { include_usage: true };
+        }
         // Bug 3: 传入原生 tools 参数 + tool_choice auto, LLM 返回结构化 tool_calls
         if (tools && tools.length > 0) {
             requestBody.tools = tools;
             requestBody.tool_choice = 'auto';
         }
+        // 2026-09-28: 出网前一行"这次请求长什么样" (**只打数字与 hash, 不打内容**)
+        const _promptChars = messages.reduce((n, m) => n + (typeof m.content === 'string' ? m.content.length : 0), 0);
+        console.log(`[pi-ai] ▶ purpose=${_purpose} source=${source || '-'} model=${this.mapModel()} messages=${requestBody.messages.length} promptChars=${_promptChars} tools=${tools?.length ?? 0} toolsHash=${toolsHashOf(tools)} cache_prompt=${localEndpoint ? requestBody.cache_prompt : '-'}${onToken ? ' stream' : ''}`);
+        if (process.env.DEBUG_PROMPT_PREFIX === '1') {
+            debugDumpPromptPrefix(requestBody.messages, tools);
+        }
         let lastFinishReason = '';
         const _t0 = Date.now();
         // 2026-08-04 (二修): 弃用全局 fetch — node 内置 fetch 的 keep-alive 连接池会积累"僵尸连接"
@@ -383,15 +830,16 @@ export class PiAIModel {
         //   会静默忽略 npm undici Agent 的 dispatcher (实测 localPort 不变), 导致重试仍在复用坏连接.
         //   改用 npm undici 的 request(): 独立连接池 + 重试传 dispatcher 真正生效 (新 TCP 连接).
         let retryAgent = null;
-        // 认证头走注册表 (拿不到注册表 → 退回本分支原来的 `Authorization: Bearer <key>`)
+        // 认证头走注册表 (拿不到注册表 → 退回本分支原来的 Bearer 头)
         const regAuth = await this.registryAuth();
         const authHeaders = regAuth
             ? regAuth.headers
-            : { 'Authorization': `Bearer ${apiKey}` };
+            : (apiKey ? { 'Authorization': `Bearer ${apiKey}` } : {}); // 空 key (本地服务) → 不带鉴权头
         for (let attempt = 0; attempt < 4; attempt++) {
             const _tFetch = Date.now();
             let statusCode = 0;
             let body;
+            let _ctype = '';
             try {
                 const reqInit = {
                     method: 'POST',
@@ -406,6 +854,7 @@ export class PiAIModel {
                     reqInit.dispatcher = retryAgent;
                 const res = await request(`${this.getBaseUrl()}/chat/completions`, reqInit);
                 statusCode = res.statusCode;
+                _ctype = String(res.headers?.['content-type'] || ''); // 流式判定用 (SSE)
                 body = res.body;
             }
             catch (err) {
@@ -444,8 +893,19 @@ export class PiAIModel {
                 retryAgent?.destroy().catch(() => { });
                 throw new Error(`OpenAI API error: ${statusCode} ${String(errBody).slice(0, 300)}`);
             }
+            // 2026-09-28: 流式 (SSE) 分支 —— 只有调用方要 onToken 且服务端真回了 event-stream 才走;
+            //   末帧 usage 由 `stream_options.include_usage: true` 保证 (见请求体那一段).
+            if (onToken && _ctype.includes('text/event-stream')) {
+                const streamed = await this.consumeStream(body, onToken, _purpose, _t0);
+                retryAgent?.destroy().catch(() => { });
+                return streamed;
+            }
             const data = await body.json();
             const _tParse = Date.now();
+            // 2026-09-28: KV 命中率诊断 (**只打数字与百分比**): 取自
+            //   usage.prompt_tokens_details.cached_tokens (OpenAI/DeepSeek) 或 timings.cache_n (llama.cpp)
+            const usage = extractUsage(data);
+            console.log(formatKvServerLine(_purpose, usage));
             const choice = data.choices?.[0];
             const content = choice?.message?.content || '';
             const toolCalls = choice?.message?.tool_calls;
@@ -461,7 +921,7 @@ export class PiAIModel {
                 const promptBytes = JSON.stringify(messages).length;
                 console.log(`[pi-ai timing] total=${_tAfter - _t0}ms attempt=${attempt + 1} fetch=${_tResp - _tFetch}ms parse=${_tParse - _tResp}ms reply=${content.length}B toolCalls=${toolCalls?.length ?? 0} model=${this.mapModel()} prompt=${promptBytes}B`);
                 retryAgent?.destroy().catch(() => { });
-                return { reply: content, toolCalls: toolCalls && toolCalls.length > 0 ? toolCalls : undefined, reasoningContent };
+                return { reply: content, toolCalls: toolCalls && toolCalls.length > 0 ? toolCalls : undefined, reasoningContent, usage };
             }
             console.warn(`[pi-ai] attempt ${attempt + 1}/3: 空 content (finish_reason=${lastFinishReason}), 退避 1.5s 重试`);
             const _tSleep = Date.now();
@@ -472,6 +932,75 @@ export class PiAIModel {
         retryAgent?.destroy().catch(() => { });
         return { reply: '' };
     }
+    /**
+     * 2026-09-28: 消费 SSE 流 (`stream: true`).
+     *
+     * 逐条 `data: {…}` 累积 delta → content / reasoning_content / tool_calls;
+     * `usage` 只在**末帧**出现 (且只有带 `stream_options.include_usage: true` 才给) ——
+     * 少了它就没法算 KV 命中率, 所以请求体那边是强制带上的。
+     *
+     * 注: 这里不做逐 token 的回调节奏保证 (Node 侧一次性读完 body 再切片) —— onToken 的语义是
+     *   "把增量交给调用方", 不是"背压感知的实时流"。真要逐 token 背压, 得换 fetch 的 ReadableStream
+     *   并按 chunk 解析 (本仓当前没有这个需求)。
+     */
+    async consumeStream(body, onToken, purpose, t0) {
+        const raw = await body.text().catch(() => '');
+        let reply = '';
+        let reasoning = '';
+        const acc = [];
+        let usage;
+        for (const line of String(raw).split('\n')) {
+            const s = line.trim();
+            if (!s.startsWith('data:'))
+                continue;
+            const payload = s.slice(5).trim();
+            if (!payload || payload === '[DONE]')
+                continue;
+            let frame;
+            try {
+                frame = JSON.parse(payload);
+            }
+            catch {
+                continue;
+            }
+            if (frame?.usage || frame?.timings)
+                usage = extractUsage(frame);
+            const delta = frame?.choices?.[0]?.delta;
+            if (!delta)
+                continue;
+            if (typeof delta.content === 'string' && delta.content.length > 0) {
+                reply += delta.content;
+                try {
+                    onToken(delta.content);
+                }
+                catch (err) {
+                    console.warn('[pi-ai] onToken 抛错, 已忽略:', err?.message?.slice(0, 80));
+                }
+            }
+            if (typeof delta.reasoning_content === 'string')
+                reasoning += delta.reasoning_content;
+            for (const tc of delta.tool_calls || []) {
+                const idx = Number(tc?.index ?? acc.length);
+                acc[idx] = acc[idx] || { id: tc?.id, type: 'function', function: { name: '', arguments: '' } };
+                if (tc?.id)
+                    acc[idx].id = tc.id;
+                if (tc?.function?.name)
+                    acc[idx].function.name += tc.function.name;
+                if (tc?.function?.arguments)
+                    acc[idx].function.arguments += tc.function.arguments;
+            }
+        }
+        if (usage)
+            console.log(formatKvServerLine(purpose, usage, { stream: true }));
+        const toolCalls = acc.filter(Boolean);
+        console.log(`[pi-ai timing] total=${Date.now() - t0}ms stream reply=${reply.length}B toolCalls=${toolCalls.length}`);
+        return {
+            reply,
+            reasoningContent: reasoning || undefined,
+            toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+            usage,
+        };
+    }
     async callAnthropic(messages, temperature, maxTokens, signal) {
         const apiKey = this.getApiKey();
         if (!apiKey) {
@@ -604,27 +1133,64 @@ export class PiAIModel {
         return this.callOllama(messages, temperature, signal);
     }
     // 注: callLocal 直接代理 ollama. 工具清单由 generateText 在外层拼到 messages, 这里 messages 已是 finalMessages.
-    async buildSystemPromptAsync(context) {
+    /**
+     * 2026-09-28: 装配系统提示词并拆成「稳定段 / 动态段」, 按 working dir 缓存 (TTL 10 分钟)。
+     *
+     * 返回: `{ stableText, dynamicText, cached }`
+     *   - `stableText` 进 system (逐字节稳定 → 服务端前缀 KV 可复用);
+     *   - `dynamicText` 由 chat() 注入 CURRENT TURN 区 (最后一轮 user 消息前部)。
+     *
+     * 为什么缓存: 旧版每轮都跑 25 次 fs.readFile + 装配; 缓存后同一次会话内只装一次,
+     *   且装配结果逐字节相同 (缓存本身也是"前缀稳定"的必要条件 —— 每次重装都可能因动态层
+     *   内容变化而抖动)。
+     */
+    async buildSystemPromptParts(context) {
+        const key = context || process.cwd();
+        const now = Date.now();
+        if (_systemPromptCache && _systemPromptCache.key === key && now - _systemPromptCache.at < SYSTEM_PROMPT_CACHE_TTL_MS) {
+            return { stableText: _systemPromptCache.stableText, dynamicText: _systemPromptCache.dynamicText, cached: true };
+        }
+        const parts = await this.assembleSystemPromptPartsText(key);
+        _systemPromptCache = { key, at: now, ...parts };
+        return { ...parts, cached: false };
+    }
+    /**
+     * 真正跑一遍 layer registry 装配 + 拆段 (不含缓存逻辑)。
+     *
+     * 拆段依据: 装配器给每层写的 `<!-- id@version -->` 头 + registry 里 `source === 'function'` 的层集合
+     * (本仓目前只有 `dynamic.project-context`: 它随 cwd/git 状态变 → 必须逐轮新鲜, 但不能待在 system 里)。
+     */
+    async assembleSystemPromptPartsText(workingDir) {
         // 走 layer registry: 装配所有相关 layer (身份/行为/工具/角色/渠道)
         try {
             const { assembleSystemPrompt, SYSTEM_PROMPT_VERSION } = await import('./system-prompt/registry.js').catch(() => import('./system-prompt/registry.js'));
             // channel = 本机 (PI SDK 直接调就是 local)
             // role = 由 prompt context 决定 (默认 expert)
-            const ctx = context ? { channel: 'local', role: 'expert' } : { channel: 'local', role: 'expert' };
+            const ctx = { channel: 'local', role: 'expert' };
             const result = await assembleSystemPrompt(ctx);
-            return `${result.text}\n\n## User Working Directory\n${context || process.cwd()}\n\n## bolloon-runtime\n${SYSTEM_PROMPT_VERSION} · layers: ${result.layerIds.join(',')}`;
+            // 动态层 = registry 里 source==='function' 的那几层 (resolver 动态求值)
+            const dynamicIds = new Set(result.layers
+                .filter((l) => l.source === 'function')
+                .map((l) => l.id));
+            const { stableText, dynamicText } = splitLayerBlocks(result.text, dynamicIds);
+            const suffix = `\n\n## User Working Directory\n${workingDir}\n\n## bolloon-runtime\n${SYSTEM_PROMPT_VERSION} · layers: ${result.layerIds.join(',')}`;
+            return { stableText: `${stableText}${suffix}`, dynamicText, layerIds: result.layerIds };
         }
         catch (err) {
-            // 降级: 旧硬编码 (layer registry 不可用时不挂)
+            // 降级: 旧硬编码 (layer registry 不可用时不挂) —— 注意**不写缓存**: 故障态别钉 10 分钟
             console.warn('[pi-ai] layer registry 不可用, 降级:', err.message?.slice(0, 100));
             const envDetails = this.getEnvironmentDetails();
-            return `You are a friendly AI assistant in a P2P document collaboration network.
+            return {
+                stableText: `You are a friendly AI assistant in a P2P document collaboration network.
 
 ## User Working Directory
-${context || process.cwd()}
+${workingDir}
 
 ## Environment
-${envDetails}`;
+${envDetails}`,
+                dynamicText: '',
+                layerIds: [],
+            };
         }
     }
     // 同步版: 旧调用点 (buildSystemPrompt 是同步)
@@ -714,6 +1280,32 @@ ${prompt}`;
     }
 }
 let modelInstance = null;
+/** 建这个实例时用的指纹 (provider/providerId/model/baseUrl/apiKey 的 sha256[:8]) —— 指纹一致就复用, 不重建 */
+let _instanceFingerprint = '';
+/**
+ * 2026-09-28: provider/model/baseUrl/apiKey 的**指纹**.
+ *
+ * apiKey 只进 sha256 的前 8 位 —— **绝不打印 key**, 也绝不落盘/入报告.
+ * 用途: `initPiAI` 幂等 —— 同一份配置重复 init (CLI 每轮、web 每次请求、脚本里多次调用)
+ *   不再新建实例、不再清系统提示词缓存 (清缓存 = 下轮重装 = 前缀抖动 = KV 白丢)。
+ */
+export function modelFingerprint(cfg) {
+    const keyHash = cfg.apiKey ? createHash('sha256').update(String(cfg.apiKey)).digest('hex').slice(0, 8) : '';
+    return createHash('sha256')
+        .update(JSON.stringify({ p: cfg.provider || '', pid: cfg.providerId || '', m: cfg.model || '', u: cfg.baseUrl || '', k: keyHash }))
+        .digest('hex')
+        .slice(0, 16);
+}
+/** 当前实例的指纹 (诊断/门用: 只出 hex, 不含任何配置值) */
+export function currentModelFingerprint() {
+    return _instanceFingerprint;
+}
+/** 2026-09-28: 本地 llama.cpp 的探测提示 —— 显式设了 LLAMACPP_* 就把声明 provider 定为 llamacpp */
+function detectLlamacppHint() {
+    if (process.env.LLAMACPP_BASE_URL || process.env.LLAMACPP_MODEL || process.env.LLAMACPP_API_KEY)
+        return LLAMACPP_PROVIDER_ID;
+    return null;
+}
 /** 2026-08-07: bolloon-config.json 优先, 旧 llm-config.json 兜底 (迁移期兼容) */
 function resolveConfigPath() {
     const home = process.env.HOME || '/tmp';
@@ -789,35 +1381,62 @@ function detectModel(provider) {
     return defaults[provider];
 }
 export function initPiAI(config = {}) {
-    const provider = config.provider || detectProvider();
-    const model = config.model || detectModel(provider);
+    // 2026-09-28: llama.cpp = 声明 id `llamacpp` + `openai` 协议分支 (与本仓 providerId/provider 两分法一致)
+    const declared = config.provider || detectLlamacppHint() || detectProvider();
+    const isLlamacpp = declared === LLAMACPP_PROVIDER_ID;
+    const provider = isLlamacpp ? 'openai' : declared;
+    const providerId = config.providerId || (isLlamacpp ? LLAMACPP_PROVIDER_ID : undefined);
+    const model = config.model
+        || (isLlamacpp ? (process.env.LLAMACPP_MODEL || LLAMACPP_DEFAULT_MODEL) : detectModel(provider));
+    let baseUrl = config.baseUrl || (isLlamacpp ? (process.env.LLAMACPP_BASE_URL || LLAMACPP_DEFAULT_BASE_URL) : undefined);
     console.log('[PiAIModel] Initializing with provider:', provider, 'model:', model);
     // 如果没有提供 apiKey，从配置文件读取
     let apiKey = config.apiKey;
+    // 2026-09-28: llama.cpp 的 key 从 env 兜底取一次 (getApiKey 本来也会读 env, 但指纹需要它 ——
+    //   否则"换 key"这种真变化不会重建实例, 指纹就失去意义)
+    if (!apiKey && isLlamacpp)
+        apiKey = process.env.LLAMACPP_API_KEY || undefined;
     if (!apiKey) {
         try {
             const configPath = resolveConfigPath();
             if (configPath) {
                 const configData = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-                const providerConfig = configData.providers[provider];
+                const providerConfig = configData.providers[declared];
                 if (providerConfig?.apiKey) {
                     apiKey = providerConfig.apiKey;
-                    console.log('[PiAIModel] Loaded apiKey from config for', provider);
+                    console.log('[PiAIModel] Loaded apiKey from config for', declared);
                 }
+                // 2026-09-28: 本地服务 (llamacpp) 的 baseUrl 常写在配置里 → 只对这一家多读一个字段
+                //   (别人保持"只读 apiKey"的老行为: 让 model/baseUrl 的优先级变动会牵连 llm-config 那条线)
+                if (isLlamacpp && !baseUrl && providerConfig?.baseUrl)
+                    baseUrl = providerConfig.baseUrl;
             }
         }
         catch (e) {
             console.log('[PiAIModel] Error reading apiKey from config:', e);
         }
     }
+    // ── 2026-09-28: 按指纹幂等 ──────────────────────────────────────────────
+    //   同一份配置重复 init (CLI 每轮 / web 每次请求 / 脚本多入口) **不再重建实例、不再清装配缓存**.
+    //   之前每次 init 都清缓存 → 每轮重装 system → 前缀抖动 → 服务端前缀 KV 永远用不上.
+    //   真变化 (provider/model/baseUrl/key) → 清缓存 + 重建 (旧行为).
+    const fingerprint = modelFingerprint({ provider, providerId, model, baseUrl, apiKey });
+    if (modelInstance && _instanceFingerprint === fingerprint) {
+        console.log('[PiAIModel] 指纹一致, 复用现有实例 (不重建, 不清装配缓存):', fingerprint.slice(0, 8));
+        return modelInstance;
+    }
+    clearSystemPromptCache();
     modelInstance = new PiAIModel({
         provider,
-        providerId: config.providerId,
+        providerId,
         apiKey,
-        baseUrl: config.baseUrl,
-        model
+        baseUrl,
+        model,
+        // 本地自建服务: 允许空 key + 无 key 不带鉴权头
+        allowEmptyKey: isLlamacpp,
     });
-    console.log('[PiAIModel] Model instance created, provider:', provider);
+    _instanceFingerprint = fingerprint;
+    console.log('[PiAIModel] Model instance created, provider:', provider, 'fingerprint:', fingerprint.slice(0, 8));
     return modelInstance;
 }
 export function getModel() {