lume-dsh-plugin 0.6.1 → 0.7.0

package/lib/index.js

@@ -18,7 +18,7 @@ import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
 import { BlockAssembler, createUserMessage, ReasoningEffortId } from "@deepseek-ai/dsh-llm";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import z from "@deepseek-ai/schemastery";
-import { buildPersonaSection } from "./host/injection.js";
+import { buildPersonaContractSection, buildPersonaRuntimeSection } from "./host/injection.js";
 import { loadPersonalities, NONE_PERSONA } from "./host/personalities.js";
 import { createLumeRpcHandler } from "./host/rpc.js";
 import { FilePersonaStore, migrateLegacyState, PersonaStore } from "./host/store.js";
@@ -27,6 +27,7 @@ import { PersonaRegistry } from "./host/registry.js";
 import { buildCorrectionPrompt, buildExtractionPrompt, extractNaming, isCoolingDown, isDuplicateFact, mergeNewFacts, parseCorrectionRule, parseFacts, resolveAuxRoute, shouldCaptureCorpus, shouldConsider, shouldConsiderCorrection } from "./host/extraction.js";
 import { DistillJobRunner, DISTILL_ALGORITHM_VERSION, runDistill } from "./host/distill.js";
 import { jaccard } from "./core/retrieval.js";
+import { fnv1a32 } from "./core/sampling.js";
 import { detectLeak } from "./core/leak-detector.js";
 import { messageText } from "./core/text.js";
 import { composeBoundary } from "./host/boundary.js";
@@ -34,9 +35,14 @@ import { SessionRuntimeStore } from "./host/session-runtime.js";
 import { isCompactionCheckpoint } from "./host/compaction.js";
 import { LUME_REFLECTION_SPEC, ReflectionStore, buildReflectionPrompt, parseReflectionScore } from "./host/reflection.js";
 import { appendLumeLog } from "./host/diag.js";
-import { advancePhase, buildAlignmentCorrection, buildCompactionNotice, buildInteractionDirective, buildLongSessionGuard, buildSessionAnchor, buildTaskPhaseDirective, buildToolFailureNotice, classifyInteraction, isUserAuthored, taskPhaseForMode } from "./host/protocol.js";
+import { advancePhase, buildAlignmentCorrection, buildCasualDirective, buildCompactionNotice, buildInteractionDirective, buildLongSessionGuard, buildSessionAnchor, buildTaskPhaseDirective, buildToolFailureNotice, classifyInteraction, isUserAuthored, taskPhaseForMode } from "./host/protocol.js";
 import { buildDocumentDirective, probeDocumentCapabilities } from "./host/documents.js";
-import { REASONING_MODEL_RE, TASK_SIGNAL_RE, selectThinkingProtocol } from "./host/thinking.js";
+import { REASONING_MODEL_RE, TASK_SIGNAL_RE, selectStableThinkingProtocol } from "./host/thinking.js";
+import { normalizeChange, normalizeContract, normalizeHypothesis, normalizeProjectFact, projectKeyOf, renderChangeLedger, renderContract, renderHypotheses, renderProjectFacts } from "./core/ledger.js";
+import { classifyTool, readResultSignals } from "./core/signals.js";
+import { buildContractMethodDirective, buildDocumentMethodDirective, buildImpactDirective, buildStructureHint, composeBlocks } from "./host/methods.js";
+import { LUME_PROJECT_SPEC, ProjectStore } from "./host/project.js";
+import { DEFAULT_TRIGGER_THRESHOLDS, applyToolSignal, applyVerifyOutcome, cooldownOk, evaluateToolTrigger, evaluateTurnTrigger } from "./host/triggers.js";
 /** schemastery → domainTable 形参的桥接（与 identity.ts 同款）。 */
 const recordSchema = zodLike;
 /** 会话人设选择的持久层（键 = sessionId）。 */
@@ -56,16 +62,38 @@ const LLM_DUMP_PATH = process.env.DSH_HOME
 const LUME_PERSONA_SECTION = "lume:persona";
 const LUME_THINKING_SECTION = "lume:thinking";
 const LUME_THINKING_ORDER = 1;
-/** 人设段与播报段的 order：取 10000+/10100——真正的 system prompt 末尾。
- * 宿主的段落布局是：身份声明 -1000（最前，"你是 AI 助手"的来源）、策略 500-900、
- * 工具定义 1000-5000、结构化输出 9900。人设若按惯例放 order 2，会被压在头部
- * 身份声明与近万 token 工具内容之间——实测模型会无视中段的人设契约、直接以
- * "AI 助手"自居。放在最末尾（紧贴对话历史、注意力最强）后，人格合规才成立。 */
+/** 人设契约段（会话恒定）的 order：取 10000——真正的 system prompt 末尾。
+ * 宿主的段落布局是：身份声明 -1000（最前，"你是 AI 助手"的来源）、部署 persona 前缀 0、
+ * 策略 500-900、工具定义 1000-5000、结构化输出 9900。人设若按惯例放 order 2，会被压在
+ * 头部身份声明与近万 token 工具内容之间——实测模型会无视中段的人设契约、直接以
+ * "AI 助手"自居。放在最末尾（紧贴对话历史、注意力最强）后，人格合规才成立。
+ * 该段在一个会话内必须逐字节恒定：见 LUME_RUNTIME_CONTEXT 的说明。 */
 const LUME_PERSONA_ORDER = 10000;
-const LUME_BOUNDARY_SECTION = "lume:boundary";
+/**
+ * 易变注入段（记忆 top-k、风格约定、语料示例、切换播报、路由/阶段/护栏/锚点、
+ * 压缩重锚、文档指引）——走宿主 runtime-context 通道，渲染成对话尾部的一条快照消息。
+ *
+ * 为什么不能留在 system 段：system 串排在消息序列最前面，而前缀缓存只认「从第一个
+ * 不同的字节起，之后全部失效」。只要 system 串每步变一次，它后面的工具定义、结构化
+ * 输出和**整段对话历史**就全部按全价重算。实测（deepseek-v4-flash，2026-09-11 某会话
+ * 282 个请求）：cacheRead 恒定 384 token、命中率中位数 0.2%；当日全站命中率 18%。
+ * 而宿主内置的 `systemPromptUpdate: "in-history"`（把系统提示词变化以追加方式落在
+ * 历史尾部）只在 `deepseek-flash` 一个内置模型条目上声明，v4 系没有——所以这层拆分
+ * 是插件侧唯一能拿回缓存的手段。
+ *
+ * 宿主的 runtime-context 语义正好对症：assemble 时求值、append 到消息尾部，且文案声明
+ * "supersedes earlier runtime-context snapshots"（新快照取代旧快照，不堆叠进历史），
+ * 因此它每一次变化只花自己那几百 token。
+ */
+const LUME_RUNTIME_CONTEXT = "lume:runtime";
+const LUME_RUNTIME_ORDER = 10000;
+/** 人设易变段（记忆 top-k / 风格约定 / 语料示例）：同走 runtime-context，排在任务指令之后。 */
+const LUME_PERSONA_RUNTIME_CONTEXT = "lume:persona-runtime";
+const LUME_PERSONA_RUNTIME_ORDER = 10050;
+/** 人设切换播报：独立成段（只在切换窗口内有内容），便于单独观测与测试。 */
+const LUME_BOUNDARY_CONTEXT = "lume:boundary";
 const LUME_BOUNDARY_ORDER = 10100;
-/** 工具失败提示：走 runtime-context 通道（渲染成对话尾部的一条消息），
- * 不进 system 串——避免会变的内容每步作废前缀缓存。 */
+/** 工具失败提示：同走 runtime-context 通道，排在易变段之后。 */
 const LUME_TOOL_NOTICE_CONTEXT = "lume:tool-notice";
 const LUME_TOOL_NOTICE_ORDER = 10150;
 const MAX_SESSIONS = 200;
@@ -90,6 +118,14 @@ export function apply(ctx, config = {}) {
     const distillRouteOverride = { provider: config.distillProvider, model: config.distillModel };
     const reflectionEnabled = config.reflectionEnabled ?? true;
     const boundaryTurns = config.switchBoundaryTurns ?? SWITCH_BOUNDARY_TURNS;
+    const layeredInjection = config.layeredInjection ?? true;
+    /** 宿主是否提供 runtime-context 通道（0.1.5 起的 API）。 */
+    const runtimeContextSupported = typeof ctx.systemPrompt?.context === "function";
+    /** 是否真的走分层：用户没关掉、且宿主支持。否则易变段并回 system 段（旧行为）。 */
+    const layeredOn = layeredInjection && runtimeContextSupported;
+    if (layeredInjection && !runtimeContextSupported) {
+        ctx.logger?.warn?.("lume: 当前宿主不支持 systemPrompt.context，易变注入段并回系统提示词（前缀缓存收益消失，功能不受影响）");
+    }
     const defaultName = builtins[NONE_PERSONA] ? NONE_PERSONA : null;
     const legacyStatePath = join(assetsDir, "persona-state.json");
     // ── 存储就绪：会话选择域（必有）+ 身份域（失败降级为无档案功能）──
@@ -155,9 +191,38 @@ export function apply(ctx, config = {}) {
         }
     })();
     void reflectionReady.then((s) => { reflectionStore = s; });
+    // ── 项目域：任务契约 / 改动台账 / 假设台账 / 项目知识（失败降级为无载具功能）──
+    const projectMemoryOn = config.projectMemory ?? true;
+    const behaviorTriggersOn = config.behaviorTriggers ?? true;
+    const triggerThresholds = {
+        ...DEFAULT_TRIGGER_THRESHOLDS,
+        inspectStreak: config.triggerInspectStreak ?? DEFAULT_TRIGGER_THRESHOLDS.inspectStreak,
+        changeStreak: config.triggerChangeStreak ?? DEFAULT_TRIGGER_THRESHOLDS.changeStreak,
+        deadPathFails: config.triggerDeadPathFails ?? DEFAULT_TRIGGER_THRESHOLDS.deadPathFails,
+    };
+    let project = null;
+    const projectReady = (async () => {
+        if (!projectMemoryOn)
+            return null;
+        try {
+            const domain = await ctx.storageDomain.open(LUME_PROJECT_SPEC);
+            ctx.effect(() => async () => { await domain.close(); }, "lume: close project domain");
+            return new ProjectStore({
+                contract: domain.table("contract"),
+                ledger: domain.table("ledger"),
+                hypotheses: domain.table("hypotheses"),
+                facts: domain.table("facts"),
+            });
+        }
+        catch (error) {
+            ctx.logger?.warn?.("lume: 项目域不可用，任务契约/台账/项目知识降级", error);
+            return null;
+        }
+    })();
+    void projectReady.then((s) => { project = s; });
     const registry = new PersonaRegistry(builtins, () => identity);
     ctx.logger?.warn?.(`lume: 已加载（builtins=${Object.keys(builtins).join(",") || "空!"}，assets=${assetsDir}）`);
-    ctx.logger?.warn?.(`lume: 版本 0.3.3 — llmRoute 初始化策略：agentDefaultModel → settings → 回退`);
+    ctx.logger?.warn?.(`lume: llmRoute 初始化策略：agentDefaultModel → settings → 回退`);
     // ── 每会话运行时状态（内存，重启即弃，LRU 上限兜底）──
     const runtime = new SessionRuntimeStore();
     // ── 模型路由缓存（request/context，会话过程中由 agent-loop 更新）──
@@ -480,6 +545,9 @@ export function apply(ctx, config = {}) {
                 st.toolCalls++;
                 if (st.interactionMode === "execute")
                     st.taskPhase = advancePhase(st.taskPhase, "execute");
+                // 行为类别在调用阶段记账（连击），成败到结果阶段才结算。
+                st.toolKind = classifyTool(event.data?.name);
+                applyToolSignal(st.triggerCounters, st.toolKind, null);
                 break;
             }
             case "tool/result": {
@@ -495,6 +563,30 @@ export function apply(ctx, config = {}) {
                     st.toolSuccesses++;
                 if (st.interactionMode === "execute")
                     st.taskPhase = advancePhase(st.taskPhase, unknownResult || explicitError ? "diagnose" : "verify");
+                // 行为信号 → 计数器 → 触发器提醒。提醒只在这一步之后可见（尾部快照），
+                // 且每类触发器有轮级冷却：提示一多就变噪音，模型会学会忽略。
+                const signals = readResultSignals(resultText, explicitError);
+                applyVerifyOutcome(st.triggerCounters, st.toolKind, signals);
+                if (behaviorTriggersOn) {
+                    const fire = evaluateToolTrigger(st.triggerCounters, {
+                        turnIndex: st.turnIndex,
+                        isTask: isTaskQuery(st),
+                        diagnosing: st.interactionMode === "diagnosis",
+                        hasContract: contractOf(sid) !== null,
+                        hasHypotheses: hypothesesOf(sid).length > 0,
+                        hypothesesTouched: st.hypothesesTouched,
+                    }, triggerThresholds);
+                    if (fire && cooldownOk(st.triggerFiredAt[fire.id], st.turnIndex)) {
+                        st.triggerFiredAt[fire.id] = st.turnIndex;
+                        st.triggerNudge = fire.text;
+                        ctx.logger?.warn?.(`lume: [${sid}] 行为触发器 ${fire.id}（steps=${st.triggerCounters.steps}，inspect=${st.triggerCounters.inspectStreak}，mutate=${st.triggerCounters.mutateStreak}，verifyFail=${st.triggerCounters.verifyFailStreak}）`);
+                        // 环境性死路自动落成项目知识：下次会话不必重踩。
+                        if (fire.id === "dead-path" && signals.env && project) {
+                            const key = projectKeyFor(sid, session);
+                            void project.addFact(key, normalizeProjectFact({ kind: "deadend", text: `本环境验证受阻（${st.triggerCounters.verifyFailStreak} 次连续失败，环境/依赖类）：换降级阶梯，不要重复同一命令` }, Date.now()), (candidate, existing) => existing.some((fact) => fact.text === candidate));
+                        }
+                    }
+                }
                 break;
             }
             case "compaction/summary": {
@@ -509,6 +601,43 @@ export function apply(ctx, config = {}) {
             }
             case "turn/end": {
                 st.turnIndex++;
+                // 切换窗口的消耗只发生在轮边界（渲染函数只读状态，不再就地清零）：
+                // 同一步里 prompt 会被构建多次，若在渲染里消耗窗口，第二次构建就会
+                // 丢掉接班招呼——那是「注入随构建次数漂移」，正是本版要消灭的东西。
+                st.switchGreetingPending = false;
+                if (st.switchTurn !== null && st.turnIndex - st.switchTurn >= boundaryTurns)
+                    st.switchTurn = null;
+                // ── 行为触发器（轮边界）──
+                // 连击按轮清零：新一轮是新请求，上一轮的「撒网」不该继续累加；死路连击
+                // 跨轮保留（同一环境不可用是会话级事实）。上轮的提醒到这里失效。
+                st.triggerCounters.inspectStreak = 0;
+                st.triggerCounters.mutateStreak = 0;
+                st.triggerNudge = null;
+                st.turnNudge = null;
+                st.hypothesesTouched = false;
+                if (behaviorTriggersOn && project) {
+                    const fire = evaluateTurnTrigger({
+                        turnIndex: st.turnIndex,
+                        hasContract: contractOf(sid) !== null,
+                        compactionTurn: st.compaction?.turnIndex ?? null,
+                        lastDriftTurn: st.lastDriftTurn,
+                        counters: st.triggerCounters,
+                        knowledgePrompted: st.knowledgePrompted,
+                    }, triggerThresholds);
+                    if (fire && cooldownOk(st.triggerFiredAt[fire.id], st.turnIndex)) {
+                        st.triggerFiredAt[fire.id] = st.turnIndex;
+                        if (fire.id === "criteria-drift") {
+                            // 契约对账用「交付口径」渲染原始判据：防判据随进展漂移。
+                            st.lastDriftTurn = st.turnIndex;
+                            st.turnNudge = renderContract(contractOf(sid), true);
+                        }
+                        else {
+                            st.knowledgePrompted = true;
+                            st.turnNudge = fire.text;
+                        }
+                        ctx.logger?.warn?.(`lume: [${sid}] 轮触发器 ${fire.id}（turn=${st.turnIndex}）`);
+                    }
+                }
                 // 低成本会话内纠偏：只处理明确的错误/失败信号，且要求连续轮次用户请求相同。
                 const failed = /失败|报错|错误|exception|traceback|cannot|unable|permission denied|timed out|找不到|不存在/i.test(st.assistantText);
                 const queryKey = st.userText.trim().replace(/\s+/g, " ").slice(0, 240);
@@ -565,6 +694,8 @@ export function apply(ctx, config = {}) {
         const st = runtime.get(sid);
         const turns = [...st.recentTurns];
         runtime.delete(sid);
+        // 任务载具是会话态：任务结束即无意义，清掉避免无界增长（项目知识在另一张表，不受影响）。
+        void projectReady.then((store) => store?.clearSession(sid));
         // 反思日志：会话结束后空闲时间跑一次小模型，零用户感知 token。
         // 历史不够长（< 4 条消息）或路由不可用时静默跳过。
         if (reflectionEnabled && turns.length >= 4) {
@@ -583,10 +714,89 @@ export function apply(ctx, config = {}) {
                 if (!score)
                     return;
                 await store.log(sid, score);
-                ctx.logger?.warn?.(`lume: 反思日志 ${sid} context=${score.context} planning=${score.planning} verification=${score.verification} review=${score.review}「${score.note}」`);
+                ctx.logger?.warn?.(`lume: 反思日志 ${sid} context=${score.context} planning=${score.planning} verification=${score.verification} review=${score.review} diagnosis=${score.diagnosis}「${score.note}」`);
             })();
         }
     }), "lume: session disposal");
+    // ── 载具与项目知识的读取入口（事件处理器 / 工具 / 注入三处共用）──
+    /** 项目键：优先取会话工作目录（跨会话共享同一仓库的知识）。 */
+    function projectKeyFor(sid, source) {
+        const st = runtime.get(sid);
+        if (st.projectKey)
+            return st.projectKey;
+        // 三种调用来源：提示词 context（{agent:{session}}）、工具 exec（{agent:{session}}）、
+        // 会话事件（session 本身）。统一取到 session 再读 cwd。
+        const session = source?.agent?.session ?? source?.session ?? source;
+        const cwd = session?.cwd ?? "";
+        const key = projectKeyOf(cwd);
+        // 只有拿到真实工作目录才缓存：否则一次无 cwd 的调用会把 "unknown" 固化下来。
+        if (cwd)
+            st.projectKey = key;
+        return key;
+    }
+    function isTaskQuery(st) {
+        return TASK_SIGNAL_RE.test(st.intent?.text ?? st.userText ?? "");
+    }
+    function contractOf(sid) {
+        return project?.getContract(sid) ?? null;
+    }
+    function changesOf(sid) {
+        return project?.getChanges(sid) ?? [];
+    }
+    function hypothesesOf(sid) {
+        return project?.getHypotheses(sid) ?? [];
+    }
+    function factsOf(sid, context) {
+        return project ? project.getFacts(projectKeyFor(sid, context)) : [];
+    }
+    /** 环境里是否有符号级结构分析工具：有就让模型用它替代通篇 read。 */
+    function structureToolName(context) {
+        try {
+            const schemas = ctx.get("tools")?.schemas?.(context?.agent);
+            if (!Array.isArray(schemas))
+                return null;
+            for (const schema of schemas) {
+                const name = String(schema?.name ?? "");
+                if (/analy|tree|symbol|lsp|reference|code_map|outline/i.test(name))
+                    return name;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 任务载具块：契约 / 改动台账 / 假设台账 / 项目知识 + 方法块 + 触发器提醒。
+     *
+     * 全部落在尾部快照（易变层）——这正是「载具」现在才做得起的原因：0.6.2 之前每步
+     * 注入一份会变的状态等于每步作废整段前缀，而快照只在内容变化时才付费（实测 58 步
+     * 只产生 9 条快照）。顺序上把「此刻最该做的一件事」（触发器提醒）放在最后。
+     */
+    function carrierBlocks(sid, context, st, query, mode) {
+        if (!projectMemoryOn)
+            return [];
+        const isTask = TASK_SIGNAL_RE.test(query);
+        const contract = contractOf(sid);
+        const changes = changesOf(sid);
+        const docDirective = buildDocumentDirective({ query, capabilities: probeDocumentCapabilities(ctx.get("tools"), context?.agent) });
+        return [
+            // 契约：有就回显（交付轮切成对账口径），没有且是任务轮就先教它写一份。
+            { text: renderContract(contract, st.taskPhase === "deliver") },
+            { text: !contract && isTask ? buildContractMethodDirective() : null, droppable: true },
+            // 台账与假设：存在就回显——让模型「看见」自己的计划，而不是记在脑子里。
+            { text: changes.length > 0 ? renderChangeLedger(changes) : null },
+            { text: renderHypotheses(hypothesesOf(sid)) },
+            // 项目知识：只在与项目相关的轮次出现（闲聊不该背仓库事实）。
+            { text: isTask ? renderProjectFacts(factsOf(sid, context)) : null, droppable: true },
+            // 方法块：按任务形态出现；文档方法论只在判定为文档任务时出现。
+            { text: isTask && mode !== "question" ? buildImpactDirective() : null, droppable: true },
+            { text: docDirective ? buildDocumentMethodDirective() : null },
+            { text: mode === "execute" || mode === "diagnosis" ? buildStructureHint(structureToolName(context)) : null, droppable: true },
+            { text: st.turnNudge },
+            { text: st.triggerNudge },
+        ];
+    }
     // ── 模型可调用工具（主写入通道）──
     // 工具 output schema 的 const 语义要求成功值恒为 { ok: true }；失败一律抛错交由框架呈现。
     // as const 让 defineTool 从字面量推断 O，三个工具共用同一份成功形状。
@@ -657,6 +867,152 @@ export function apply(ctx, config = {}) {
                 return { ok: true };
             },
         }));
+        // ── 任务载具工具（第二组写入通道）──
+        // 与人格工具一样是「模型主动调用、零额外 LLM 调用」，区别在写入对象：契约/台账/假设
+        // 属于当前任务（会话态），项目知识按工作目录跨会话累积。列表类参数统一用字符串
+        // 分隔（分号或换行），不引入数组 schema——省 schema token，也少一层校验风险。
+        const splitList = (value) => String(value ?? "")
+            .split(/[；;\n]/)
+            .map((item) => item.trim())
+            .filter(Boolean);
+        ctx.effect(() => {
+            ctx.tools.register(defineTool({
+                name: "lume_contract",
+                description: "写下或更新本任务的任务契约（需求量化的落点）：目标、范围、数量、完成判据、非目标、待确认。任务型请求开工前调用一次；探索后回填实际数量；之后只传变化的字段即可（局部更新）。",
+                parameters: {
+                    goal: { type: "string", description: "目标：一句话、可观察的结果" },
+                    scope: { type: "string", description: "范围：路径/模块/章节，分号或换行分隔" },
+                    expectCount: { type: "number", description: "预计数量（探索前先估）" },
+                    actualCount: { type: "number", description: "实际数量（探索后回填）" },
+                    criteria: { type: "string", description: "完成判据：可执行、可核对，分号或换行分隔" },
+                    nonGoals: { type: "string", description: "非目标：明确不动的东西，分号分隔" },
+                    open: { type: "string", description: "待确认：只列真正阻塞的（≤2 个），分号分隔" },
+                },
+                output: { schema: OK_OUTPUT_SCHEMA, render: () => [{ type: "text", text: "已记录任务契约" }] },
+                execute: async (args, exec) => {
+                    if (!project)
+                        throw new Error("lume project store is unavailable");
+                    const sid = String(exec?.agent?.session?.id ?? "");
+                    if (!sid)
+                        throw new Error("lume_contract requires an active session");
+                    const st = runtime.get(sid);
+                    const normalized = normalizeContract({
+                        goal: args.goal,
+                        scope: splitList(args.scope),
+                        expectCount: args.expectCount,
+                        actualCount: args.actualCount,
+                        criteria: splitList(args.criteria),
+                        nonGoals: splitList(args.nonGoals),
+                        open: splitList(args.open),
+                    }, Date.now(), st.turnIndex);
+                    const existing = project.getContract(sid);
+                    if (existing) {
+                        // 局部更新：未传的字段保持原值（回填数量时不该把判据清空）。
+                        const patch = {};
+                        if (args.goal !== undefined)
+                            patch.goal = normalized.goal;
+                        if (args.scope !== undefined)
+                            patch.scope = normalized.scope;
+                        if (args.expectCount !== undefined)
+                            patch.expectCount = normalized.expectCount;
+                        if (args.actualCount !== undefined)
+                            patch.actualCount = normalized.actualCount;
+                        if (args.criteria !== undefined)
+                            patch.criteria = normalized.criteria;
+                        if (args.nonGoals !== undefined)
+                            patch.nonGoals = normalized.nonGoals;
+                        if (args.open !== undefined)
+                            patch.open = normalized.open;
+                        await project.patchContract(sid, patch);
+                    }
+                    else {
+                        if (!normalized.goal)
+                            throw new Error("lume_contract requires a goal on first write");
+                        await project.setContract(sid, normalized);
+                    }
+                    return { ok: true };
+                },
+            }));
+            ctx.tools.register(defineTool({
+                name: "lume_change",
+                description: "改动台账：记录/更新一处将要改或已改的位置（文件/符号/文档章节 → 改什么 → 怎么验 → 状态）。动手前先列计划项，改完推进状态；只推进状态时可只传 target + status。文档任务用章节名当 target，形成分节记账。",
+                parameters: {
+                    target: { type: "string", required: true, description: "目标位置：文件路径 / 符号 / 文档章节" },
+                    change: { type: "string", description: "改什么（一句话）" },
+                    why: { type: "string", description: "为什么改（对齐契约的哪一条）" },
+                    verify: { type: "string", description: "怎么验（命令 / 回读 / 对照）" },
+                    status: { type: "string", description: "planned | done | verified | skipped" },
+                },
+                output: { schema: OK_OUTPUT_SCHEMA, render: () => [{ type: "text", text: "已更新改动台账" }] },
+                execute: async (args, exec) => {
+                    if (!project)
+                        throw new Error("lume project store is unavailable");
+                    const sid = String(exec?.agent?.session?.id ?? "");
+                    if (!sid)
+                        throw new Error("lume_change requires an active session");
+                    const target = String(args.target ?? "").trim();
+                    if (!target)
+                        throw new Error("lume_change requires a target");
+                    const status = args.status;
+                    const allowed = status === "planned" || status === "done" || status === "verified" || status === "skipped" ? status : undefined;
+                    if (args.change === undefined && allowed !== undefined) {
+                        const hit = await project.setChangeStatus(sid, target, allowed);
+                        if (!hit)
+                            throw new Error(`lume_change: no ledger entry for ${target}`);
+                        return { ok: true };
+                    }
+                    const item = normalizeChange({ target, change: args.change, why: args.why, verify: args.verify, status: allowed }, Date.now());
+                    if (!item)
+                        throw new Error("lume_change requires target and change");
+                    await project.upsertChange(sid, item);
+                    return { ok: true };
+                },
+            }));
+            ctx.tools.register(defineTool({
+                name: "lume_hypothesis",
+                description: "假设台账：记录一条正在验证的假设及其证据与状态（open/testing/confirmed/excluded）。排查类任务里每验证一次就更新状态；已排除的假设不要再重复尝试。",
+                parameters: {
+                    text: { type: "string", required: true, description: "假设内容，一句话" },
+                    evidence: { type: "string", description: "支持或推翻它的观察（含命令输出/时间戳摘要）" },
+                    status: { type: "string", description: "open | testing | confirmed | excluded" },
+                },
+                output: { schema: OK_OUTPUT_SCHEMA, render: () => [{ type: "text", text: "已更新假设台账" }] },
+                execute: async (args, exec) => {
+                    if (!project)
+                        throw new Error("lume project store is unavailable");
+                    const sid = String(exec?.agent?.session?.id ?? "");
+                    if (!sid)
+                        throw new Error("lume_hypothesis requires an active session");
+                    const item = normalizeHypothesis({ text: args.text, evidence: args.evidence, status: args.status }, Date.now());
+                    if (!item)
+                        throw new Error("lume_hypothesis requires text");
+                    await project.upsertHypothesis(sid, item);
+                    runtime.get(sid).hypothesesTouched = true;
+                    return { ok: true };
+                },
+            }));
+            ctx.tools.register(defineTool({
+                name: "lume_project_note",
+                description: "记录一条**稳定的项目事实**（按工作目录跨会话累积）：构建/测试命令、模块数据流、仓库约定、或一条死路（试过但行不通的做法）。只记可复用、已验证的事实，不要记一次性进展。",
+                parameters: {
+                    kind: { type: "string", required: true, description: "build | test | module | convention | deadend" },
+                    text: { type: "string", required: true, description: "事实本身，一句话，≤200 字" },
+                },
+                output: { schema: OK_OUTPUT_SCHEMA, render: () => [{ type: "text", text: "已记入项目知识" }] },
+                execute: async (args, exec) => {
+                    if (!project)
+                        throw new Error("lume project store is unavailable");
+                    const sid = String(exec?.agent?.session?.id ?? "");
+                    if (!sid)
+                        throw new Error("lume_project_note requires an active session");
+                    const fact = normalizeProjectFact({ kind: args.kind, text: args.text }, Date.now());
+                    if (!fact)
+                        throw new Error("lume_project_note requires text");
+                    await project.addFact(projectKeyFor(sid, { agent: exec?.agent }), fact, (candidate, existing) => existing.some((entry) => jaccard(entry.text, candidate) >= 0.7));
+                    return { ok: true };
+                },
+            }));
+        }, "lume: carrier tools");
     }, "lume: persona tools");
     // ── 人设五段式注入 + 切换播报 ──
     /**
@@ -702,10 +1058,37 @@ export function apply(ctx, config = {}) {
         }
         return { text: st.intent?.text ?? st.lastQuery ?? "", mode: st.interactionMode };
     }
-    function buildSessionText(sid, context) {
-        if (!currentStore)
-            return "";
+    function computeTurn(sid, context) {
         const st = runtime.get(sid);
+        // 意图取自会话权威历史（resolveIntent），不再读事件缓存里的最新文本：
+        // 后者会被注入消息覆盖，且首步可能还带着上一轮的值，导致模式在轮内漂移。
+        const { text: query, mode } = resolveIntent(context, st);
+        // 协议正文按模型能力冻结（不随 query 切变体）：切变体会让系统提示词每轮改写，
+        // 代价远超省下的几百 token。见 selectStableThinkingProtocol。
+        const thinkingStable = selectStableThinkingProtocol({
+            isReasoningModel: typeof llmRoute?.model === "string" && REASONING_MODEL_RE.test(llmRoute.model),
+        }).trim();
+        // 易变的任务指令：路由、阶段、闲聊声明、长会话护栏、目标锚点、即时对齐、
+        // 交付复核、压缩重锚、文档能力指引、失败纠偏、反思提醒——全部每步可变。
+        // 载具与方法块（契约/台账/假设/项目知识/影响面/文档方法/触发器提醒）排在最后：
+        // 它们是「此刻最该看的」，紧贴尾部注意力最强位；超预算时先丢可丢块（composeBlocks）。
+        const thinkingRuntime = composeBlocks([
+            { text: buildInteractionDirective(mode) },
+            { text: buildTaskPhaseDirective(st.taskPhase) },
+            { text: buildCasualDirective(TASK_SIGNAL_RE.test(query)) },
+            { text: buildLongSessionGuard(st.turnIndex) },
+            { text: buildSessionAnchor(st.turnIndex, mode, query, st.recentTurns) },
+            { text: st.alignmentCorrection },
+            { text: st.postTurnReview },
+            { text: st.compaction ? buildCompactionNotice(st.compaction, st.turnIndex) : null },
+            { text: st.protocolCorrection },
+            { text: reflectionStore?.getFeedback() ?? null, droppable: true },
+            ...carrierBlocks(sid, context, st, query, mode),
+        ]);
+        // 会话选择尚未就绪（启动竞态）：只出任务协议，人设段留空——与旧实现一致，
+        // 也避免把「尚未选择」误记成一次人设切换。
+        if (!currentStore)
+            return { thinkingStable, thinkingRuntime, personaStable: "", personaData: "", boundary: "" };
         const selected = currentStore.get(sid);
         const personaName = selected ?? defaultName;
         const previous = st.lastInjected;
@@ -726,57 +1109,51 @@ export function apply(ctx, config = {}) {
         const boundaryText = inWindow && st.switchTurn !== null
             ? composeBoundary({ registry, previous: st.prevPersona, current: personaName, greeting, escalated: st.leakEscalated })
             : null;
-        // 播报改由独立的尾部 section 渲染（LUME_BOUNDARY_SECTION），人设段不再内联
-        st.activeBoundary = boundaryText;
-        const memories = personaName ? identity?.getMemory(personaName) ?? [] : [];
-        const styleRules = personaName ? identity?.getStyleRules(personaName) ?? [] : [];
-        const corpusPins = personaName ? identity?.getCorpusPins(personaName) ?? [] : [];
-        const { text: query } = resolveIntent(context, st);
-        // 一轮一算：注入段按查询做 top-k 检索，查询或记忆每步抖动会让整段改写，
-        // 系统提示词随之在轮内变化（实测一轮产生 28 份），前缀缓存每步作废。
-        // 指纹覆盖 persona、查询、记忆/风格/语料与注入配置；人设切换、边界窗口、
-        // 记忆写入都会改变指纹而自动失效。
-        const last = (list, field) => list.length > 0 ? list[list.length - 1]?.[field] : "";
-        const key = [
-            String(personaName),
-            String(persona?.name ?? ""),
+        st.lastInjected = personaName;
+        // 恒定段：只依赖「谁在当值 + 契约正文 + 身份名」。检索结果、示例、播报都进易变段。
+        const profileName = personaName ? registry.profileNameOf(personaName) : null;
+        const personaStable = buildPersonaContractSection({ persona, profileName });
+        const personaData = buildPersonaRuntimeSection({
+            persona,
+            memories: personaName ? identity?.getMemory(personaName) ?? [] : [],
+            styleRules: personaName ? identity?.getStyleRules(personaName) ?? [] : [],
+            corpusPins: personaName ? identity?.getCorpusPins(personaName) ?? [] : [],
             query,
-            String(st.turnIndex),
-            String(memories.length),
-            String(last(memories, "text")),
-            String(styleRules.length),
-            String(last(styleRules, "rule")),
-            String(corpusPins.length),
-            String(last(corpusPins, "assistant")),
-            String(boundaryText ?? ""),
-            String(sampleCount),
-            String(sampleMin),
-            String(memoryInject),
-            String(styleInject),
-            strategy,
-        ].join("\u0001");
-        let text = st.personaCache !== null && st.personaCache.key === key ? st.personaCache.text : null;
-        if (text === null) {
-            text = buildPersonaSection({
-                persona,
-                profileName: personaName ? registry.profileNameOf(personaName) : null,
-                memories,
-                styleRules,
-                corpusPins,
-                query,
-                turnIndex: st.turnIndex,
-                sessionKey: sid,
-                boundaryText: null,
-                config: { sampleCount, sampleMin, memoryInject, styleInject, strategy },
-            });
-            st.personaCache = { turnIndex: st.turnIndex, key, text };
+            turnIndex: st.turnIndex,
+            sessionKey: sid,
+            // 播报单独成段（lume:boundary），不混进数据段——便于单独观测与测试
+            boundaryText: null,
+            config: { sampleCount, sampleMin, memoryInject, styleInject, strategy },
+        });
+        // 现场可观测：恒定段指纹每变一次写一行诊断。健康会话只会留下 1-2 行
+        // （首次 + 人设切换）；若长会话里反复出现，说明又有东西混进了 system 段。
+        const digest = fnv1a32(`${thinkingStable}\u0001${personaStable}`).toString(16);
+        if (st.stableDigest !== digest) {
+            st.stableDigest = digest;
+            appendLumeLog(`[${sid}] 系统段指纹 ${digest}（当值=${String(personaName)}，身份=${String(profileName)}，通道=${layeredOn ? "runtime-context" : "system（降级）"}）`);
         }
-        st.lastInjected = personaName;
-        if (greeting)
-            st.switchGreetingPending = false;
-        if (st.switchTurn !== null && st.turnIndex - st.switchTurn >= boundaryTurns)
-            st.switchTurn = null; // 窗口关闭
-        return text;
+        return { thinkingStable, thinkingRuntime, personaStable, personaData, boundary: boundaryText ?? "" };
+    }
+    /**
+     * system 段取文：恒定段 +（宿主不支持 runtime-context 时）易变段。
+     * 降级时并回 system 是刻意的取舍——宁可丢前缀缓存，也不能丢记忆与播报注入。
+     */
+    function systemSectionText(sid, context, part) {
+        const turn = computeTurn(sid, context);
+        if (layeredOn)
+            return part === "thinking" ? turn.thinkingStable : turn.personaStable;
+        const stable = part === "thinking" ? turn.thinkingStable : turn.personaStable;
+        const dynamic = part === "thinking"
+            ? turn.thinkingRuntime
+            : [turn.personaData, turn.boundary].filter(Boolean).join("\n\n");
+        return [stable, dynamic].filter(Boolean).join("\n\n");
+    }
+    /** 易变段取文：任务指令 / 人设数据 / 切换播报三段各自成 context，由宿主按 order 归并成一条尾部快照。 */
+    function runtimeContextText(sid, context, part) {
+        const turn = computeTurn(sid, context);
+        if (part === "thinking")
+            return turn.thinkingRuntime;
+        return part === "persona" ? turn.personaData : turn.boundary;
     }
     // ── RPC 通道 ──
     const handleEndpoint = createLumeRpcHandler({
@@ -795,6 +1172,29 @@ export function apply(ctx, config = {}) {
         get distill() {
             return distillRunner;
         },
+        getProjectState(sessionId) {
+            // 诊断视图：任务载具 + 项目知识（供排查"模型到底看到了什么"）。
+            if (!project)
+                return null;
+            const st = runtime.get(sessionId);
+            return {
+                projectKey: st.projectKey,
+                contract: project.getContract(sessionId),
+                changes: project.getChanges(sessionId),
+                hypotheses: project.getHypotheses(sessionId),
+                facts: st.projectKey ? project.getFacts(st.projectKey) : [],
+                triggers: { ...st.triggerCounters, fired: st.triggerFiredAt },
+            };
+        },
+        async clearProjectFacts(sessionId) {
+            if (!project)
+                return false;
+            const st = runtime.get(sessionId);
+            if (!st.projectKey)
+                return false;
+            await project.clearFacts(st.projectKey);
+            return true;
+        },
     });
     ctx.effect(() => ctx.connection.rpc.handle(LUME_CHANNEL, async (endpoint, payload) => {
         currentStore ??= await storesReady;
@@ -811,57 +1211,36 @@ export function apply(ctx, config = {}) {
         order: personaOrder,
         text: (context) => {
             const sid = context.agent?.session?.id ?? context.agent?.id;
-            return sid ? buildSessionText(String(sid), context) : "";
+            return sid ? systemSectionText(String(sid), context, "persona") : "";
         },
     }), "lume.persona-section()");
-    ctx.effect(() => ctx.systemPrompt.section({
-        name: LUME_BOUNDARY_SECTION,
-        order: LUME_BOUNDARY_ORDER,
-        text: (context) => {
-            const sid = context.agent?.session?.id ?? context.agent?.id;
-            // section 按 order 升序逐个求值：人设段（10000）先跑状态机，
-            // 播报段（10100）读到的 activeBoundary 必是本轮最新值。
-            return sid ? runtime.get(String(sid)).activeBoundary ?? "" : "";
-        },
-    }), "lume.boundary-section()");
+    // 易变段走 runtime-context 通道：宿主把它渲染成对话尾部的一条快照消息（文案自带
+    // "supersedes earlier runtime-context snapshots"，新快照取代旧快照，不堆叠进历史），
+    // 因此它的每一次变化只花自己那几百 token，不作废前面的任何前缀。
+    // 宿主不支持该 API 时 layeredOn=false，易变段已并回 system 段（见 systemSectionText）。
+    if (layeredOn) {
+        const dynamicContexts = [
+            { name: LUME_RUNTIME_CONTEXT, order: LUME_RUNTIME_ORDER, part: "thinking" },
+            { name: LUME_PERSONA_RUNTIME_CONTEXT, order: LUME_PERSONA_RUNTIME_ORDER, part: "persona" },
+            { name: LUME_BOUNDARY_CONTEXT, order: LUME_BOUNDARY_ORDER, part: "boundary" },
+        ];
+        for (const entry of dynamicContexts) {
+            ctx.effect(() => ctx.systemPrompt.context({
+                name: entry.name,
+                order: entry.order,
+                text: (context) => {
+                    const sid = context.agent?.session?.id ?? context.agent?.id;
+                    return sid ? runtimeContextText(String(sid), context, entry.part) : "";
+                },
+            }), `lume.runtime-context(${entry.name})`);
+        }
+    }
     ctx.effect(() => ctx.systemPrompt.section({
         name: LUME_THINKING_SECTION,
         order: LUME_THINKING_ORDER,
         text: (context) => {
             const sid = context.agent?.session?.id ?? context.agent?.id;
-            const st = sid ? runtime.get(String(sid)) : null;
-            // 意图取自会话权威历史（resolveIntent），不再读事件缓存里的最新文本：
-            // 后者会被注入消息覆盖，且首步可能还带着上一轮的值，导致模式在轮内漂移。
-            const intent = st !== null && sid ? resolveIntent(context, st) : null;
-            const query = intent?.text ?? "";
-            // 已知推理型模型具备计划能力，任务轮只保留变更、验证、归因和复核约束；
-            // 路由未知时使用完整版，避免误判造成能力退化。
-            const base = selectThinkingProtocol({
-                isTask: TASK_SIGNAL_RE.test(query),
-                isReasoningModel: typeof llmRoute?.model === "string" && REASONING_MODEL_RE.test(llmRoute.model),
-            });
-            // 纠偏与反思提醒属于任务协议，跟人设无关——挂在 thinking 段
-            // 才能在「不使用人设」的纯任务会话里也生效。
-            const correction = st?.protocolCorrection;
-            const reflectionHint = reflectionStore?.getFeedback() ?? null;
-            const mode = intent?.mode ?? "question";
-            const route = buildInteractionDirective(mode);
-            const longSession = buildLongSessionGuard(st?.turnIndex ?? 0);
-            const anchor = buildSessionAnchor(st?.turnIndex ?? 0, mode, query, st?.recentTurns ?? []);
-            const alignment = st?.alignmentCorrection;
-            const postTurnReview = st?.postTurnReview;
-            const phase = buildTaskPhaseDirective(st?.taskPhase ?? "answer");
-            // 文档能力感知：DSH 本身不带 Office/PDF 读写能力，第三方文档工具插件
-            // 装与不装由用户决定。按探测结果分叉——有工具就约束走工具与回读验证，
-            // 没工具就约束「如实说明边界、不要硬解二进制」。只在文档任务轮注入，
-            // 且判据取自冻结的意图文本，因此轮内稳定，不会在轮中作废前缀缓存。
-            const document = buildDocumentDirective({ query, capabilities: probeDocumentCapabilities(ctx.tools, context.agent) });
-            // 工具失败提示已移到 runtime-context 通道（见 lume.tool-notice-context）：
-            // 它一出现就固定不变，但会变的内容不该待在 system 串里——那会作废前缀缓存。
-            // 压缩重锚：宿主的 preset 隔离域负责压缩，Lume 只能观察事件；
-            // 在压缩后一轮提醒「摘要不是完整历史」。
-            const compactionNotice = st?.compaction ? buildCompactionNotice(st.compaction, st.turnIndex) : null;
-            return [base, route, phase, document, longSession, anchor, alignment, postTurnReview, compactionNotice, correction, reflectionHint].filter(Boolean).join("\n\n");
+            return sid ? systemSectionText(String(sid), context, "thinking") : "";
         },
     }), "lume.thinking-section()");
     // 工具失败提示走 runtime-context 通道：宿主把它渲染成对话尾部的一条消息，