lume-dsh-plugin 0.6.1 → 0.7.0

package/lib/core/ledger.js

@@ -0,0 +1,211 @@
+/**
+ * 任务载具的纯逻辑层：任务契约、改动台账、假设台账、项目知识。
+ *
+ * 为什么是「载具」而不是再写协议条款：模型在长任务里丢的通常不是「不知道要量化」，
+ * 而是**没有一个地方放量化结果**。这四类结构化状态正好补上：
+ * - 由模型自己写（工具调用），所以与它的真实理解一致，而不是外部猜测；
+ * - 存在项目域里，跨轮次、跨压缩、跨会话存活（协议文本只能活在上下文里）；
+ * - 每轮按状态渲染回尾部快照，让「原始判据」不会随进展漂移——这是可靠性最关键的
+ *   一环：交付时对照的必须是**开工时写下的判据**，而不是模型现在记的版本。
+ *
+ * 本模块只做纯逻辑（类型/解析/归一/渲染/上限），IO 在 host/project.ts。
+ */
+import { fnv1a32 } from "./sampling.js";
+/** 契约字段长度上限：契约是「一屏能看完」的东西，写长了自己也不看。 */
+export const CONTRACT_TEXT_CAP = 240;
+export const CONTRACT_LIST_CAP = 8;
+export const CONTRACT_ITEM_CAP = 120;
+/** 台账条目上限：超了先挤掉「计划中」的旧条目，保留已改动过的（那是交付依据）。 */
+export const CHANGE_CAP = 60;
+export const CHANGE_TEXT_CAP = 160;
+export const HYPOTHESIS_CAP = 20;
+/** 项目知识上限：按时间挤旧，死路记录优先保留（它最省时间）。 */
+export const PROJECT_FACT_CAP = 40;
+export const FACT_TEXT_CAP = 200;
+const FACT_LABEL = {
+    build: "构建",
+    test: "测试",
+    module: "模块链路",
+    convention: "约定",
+    deadend: "死路（不要重复）",
+};
+function clip(value, cap) {
+    return String(value ?? "").trim().replace(/\s+/g, " ").slice(0, cap);
+}
+function clipList(value, cap = CONTRACT_LIST_CAP) {
+    const list = Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+    const out = [];
+    for (const item of list) {
+        const text = clip(item, CONTRACT_ITEM_CAP);
+        if (text && !out.includes(text))
+            out.push(text);
+        if (out.length >= cap)
+            break;
+    }
+    return out;
+}
+function asCount(value) {
+    const n = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
+    return Number.isFinite(n) && n >= 0 ? Math.trunc(n) : null;
+}
+/** 项目键：跨会话共享的项目知识按工作目录归属（同一仓库的多个会话共用一份）。 */
+export function projectKeyOf(cwd) {
+    const normalized = clip(cwd, 240).replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+    if (!normalized)
+        return "unknown";
+    return fnv1a32(normalized).toString(16).padStart(8, "0");
+}
+/** 从工具入参归一化契约（截断 + 去重 + 上限）。 */
+export function normalizeContract(input, at, turn) {
+    return {
+        goal: clip(input.goal, CONTRACT_TEXT_CAP),
+        scope: clipList(input.scope),
+        expectCount: asCount(input.expectCount),
+        actualCount: asCount(input.actualCount),
+        criteria: clipList(input.criteria),
+        nonGoals: clipList(input.nonGoals),
+        open: clipList(input.open, 4),
+        at,
+        turn,
+    };
+}
+export function normalizeChange(input, at) {
+    const target = clip(input.target, CONTRACT_ITEM_CAP);
+    const change = clip(input.change, CHANGE_TEXT_CAP);
+    if (!target || !change)
+        return null;
+    const status = input.status;
+    return {
+        target,
+        change,
+        why: clip(input.why, CHANGE_TEXT_CAP),
+        verify: clip(input.verify, CHANGE_TEXT_CAP),
+        status: status === "done" || status === "verified" || status === "skipped" ? status : "planned",
+        at,
+    };
+}
+export function normalizeHypothesis(input, at) {
+    const text = clip(input.text, CHANGE_TEXT_CAP);
+    if (!text)
+        return null;
+    const status = input.status;
+    return {
+        text,
+        evidence: clip(input.evidence, CHANGE_TEXT_CAP),
+        status: status === "testing" || status === "confirmed" || status === "excluded" ? status : "open",
+        at,
+    };
+}
+export function normalizeProjectFact(input, at) {
+    const text = clip(input.text, FACT_TEXT_CAP);
+    if (!text)
+        return null;
+    const kind = input.kind;
+    return {
+        kind: kind === "test" || kind === "module" || kind === "convention" || kind === "deadend" ? kind : "build",
+        text,
+        at,
+    };
+}
+/** 台账计数：渲染与触发器都要用（"x 项已改未验" 是增量验证的判据）。 */
+export function countByStatus(items) {
+    const out = { planned: 0, done: 0, verified: 0, skipped: 0 };
+    for (const item of items)
+        out[item.status]++;
+    return out;
+}
+/** 超限时挤掉最旧的「计划中」条目；已改动过的条目是交付依据，先保留。 */
+export function trimChanges(items, cap = CHANGE_CAP) {
+    if (items.length <= cap)
+        return items;
+    const planned = items.filter((item) => item.status === "planned");
+    const rest = items.filter((item) => item.status !== "planned");
+    const keepPlanned = planned.slice(-Math.max(0, cap - rest.length));
+    return [...rest, ...keepPlanned].sort((a, b) => a.at - b.at).slice(-cap);
+}
+export function trimFacts(facts, cap = PROJECT_FACT_CAP) {
+    if (facts.length <= cap)
+        return facts;
+    const deadends = facts.filter((fact) => fact.kind === "deadend");
+    const rest = facts.filter((fact) => fact.kind !== "deadend");
+    const keepRest = rest.slice(-Math.max(0, cap - deadends.length));
+    return [...keepRest, ...deadends.slice(-cap)].sort((a, b) => a.at - b.at).slice(-cap);
+}
+/**
+ * 渲染契约。`delivery=true` 时切换成**对账口径**——这是防「判据漂移」的关键：
+ * 交付前看到的是开工时写下的原始判据，而不是模型此刻的记忆版本。
+ */
+export function renderContract(contract, delivery = false) {
+    if (!contract || !contract.goal)
+        return null;
+    const lines = [];
+    lines.push(delivery ? "〔契约对账〕交付前逐项对账（以下是开工时写下的原始判据，不是你现在的记忆版本）：" : `〔任务契约｜第 ${contract.turn} 轮写入〕`);
+    lines.push(`目标：${contract.goal}`);
+    if (contract.scope.length > 0)
+        lines.push(`范围：${contract.scope.join("；")}`);
+    if (contract.expectCount !== null || contract.actualCount !== null) {
+        const expect = contract.expectCount === null ? "?" : contract.expectCount;
+        const actual = contract.actualCount === null ? "未回填" : contract.actualCount;
+        lines.push(`数量：预计 ${expect} → 实际 ${actual}`);
+    }
+    if (contract.criteria.length > 0)
+        lines.push(`完成判据：${contract.criteria.map((item, i) => `${i + 1}. ${item}`).join(" ")}`);
+    if (contract.nonGoals.length > 0)
+        lines.push(`非目标（不动）：${contract.nonGoals.join("；")}`);
+    if (contract.open.length > 0)
+        lines.push(`待确认：${contract.open.join("；")}`);
+    if (delivery) {
+        lines.push("逐项标注：已验证 / 未验证 / 偏离；数量对不上或判据没验的，直接说没做到，不要把动作完成说成判据达成。");
+    }
+    return lines.join("\n");
+}
+/** 渲染改动台账：计数在前（完整性可核对），明细在后（超长时只列未完成项）。 */
+export function renderChangeLedger(items, limit = 12) {
+    if (items.length === 0)
+        return null;
+    const counts = countByStatus(items);
+    const head = `〔改动台账〕共 ${items.length} 项：已验证 ${counts.verified} / 已改未验 ${counts.done} / 计划中 ${counts.planned}${counts.skipped > 0 ? ` / 跳过 ${counts.skipped}` : ""}`;
+    const open = items.filter((item) => item.status !== "verified" && item.status !== "skipped");
+    const shown = (open.length > 0 ? open : items).slice(-limit);
+    const lines = shown.map((item) => {
+        const mark = item.status === "verified" ? "[已验证]" : item.status === "done" ? "[已改未验]" : item.status === "skipped" ? "[跳过]" : "[计划]";
+        const verify = item.verify ? `（验：${item.verify}）` : "";
+        return `- ${mark} ${item.target} — ${item.change}${verify}`;
+    });
+    const foot = counts.planned > 0 || counts.done > 0 ? "\n台账里仍有未验证项：继续之前先补齐验证，或明确标注为未验证。" : "";
+    return `${head}\n${lines.join("\n")}${foot}`;
+}
+/** 渲染假设台账：已排除项照常显示——它们的作用就是「不要再试一遍」。 */
+export function renderHypotheses(list, limit = 8) {
+    if (list.length === 0)
+        return null;
+    const lines = list.slice(-limit).map((item) => {
+        const mark = item.status === "excluded" ? "[已排除]" : item.status === "confirmed" ? "[已证实]" : item.status === "testing" ? "[验证中]" : "[待验证]";
+        const evidence = item.evidence ? `（证据：${item.evidence}）` : "";
+        return `- ${mark} ${item.text}${evidence}`;
+    });
+    const excluded = list.filter((item) => item.status === "excluded").length;
+    const foot = excluded > 0 ? "\n已排除的假设不要重提；要推翻它必须给出新的证据。" : "";
+    return `〔假设台账〕\n${lines.join("\n")}${foot}`;
+}
+/** 渲染项目知识：按类别归组；死路单独成节（它最省时间）。 */
+export function renderProjectFacts(facts, limit = 14) {
+    if (facts.length === 0)
+        return null;
+    const order = ["build", "test", "convention", "module", "deadend"];
+    const picked = facts.slice(-limit);
+    const lines = [];
+    for (const kind of order) {
+        const group = picked.filter((fact) => fact.kind === kind);
+        if (group.length === 0)
+            continue;
+        lines.push(`${FACT_LABEL[kind]}：`);
+        for (const fact of group)
+            lines.push(`- ${fact.text}`);
+    }
+    return `〔项目知识｜本目录，跨会话累积〕\n${lines.join("\n")}`;
+}
+/** 台账/契约是否存在未验证项——触发器「连写不验」与交付对账都要用。 */
+export function hasUnverified(items) {
+    return items.some((item) => item.status === "done" || item.status === "planned");
+}

package/lib/core/signals.js

@@ -0,0 +1,64 @@
+const PLAN_TOKENS = new Set(["todo", "plan", "contract", "change", "ledger", "hypothesis", "note"]);
+const LUME_TOKENS = new Set(["lume"]);
+const VERIFY_TOKENS = new Set([
+    "bash", "shell", "pwsh", "powershell", "cmd", "terminal", "run", "exec", "job", "make", "mvn", "gradle",
+    "npm", "pnpm", "yarn", "bun", "deno", "node", "tsc", "tsdown", "vite", "vitest", "jest", "pytest", "cargo",
+    "go", "dotnet", "msbuild", "compile", "build", "test", "lint", "typecheck", "check", "verify",
+]);
+const MUTATE_TOKENS = new Set(["edit", "write", "multiedit", "patch", "apply", "replace", "create", "delete", "remove", "rename", "move", "append", "insert", "mkdir", "apply_patch"]);
+const INSPECT_TOKENS = new Set(["read", "view", "cat", "grep", "search", "glob", "find", "ls", "list", "tree", "analyze", "symbol", "reference", "web", "fetch", "browser", "screenshot", "image", "git", "status", "diff", "log", "show", "stat", "head", "tail", "query", "sql", "map"]);
+/** 把工具名切成小写词元：`lume_contract` → [lume, contract]；`mcp__fs__read_file` → [mcp, fs, read, file]。 */
+function tokens(name) {
+    return String(name ?? "")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+export function classifyTool(name) {
+    const parts = tokens(name);
+    if (parts.length === 0)
+        return "other";
+    const has = (set) => parts.some((part) => set.has(part));
+    const isLume = has(LUME_TOKENS);
+    // lume 自家工具单独归类：载具（契约/台账/假设/项目知识）＝ plan；人格工具（记忆/风格/人设）
+    // ＝ other——它们写的是人格数据，不该被算成「文件改动」，否则会污染增量验证的连击。
+    if (isLume)
+        return has(PLAN_TOKENS) ? "plan" : "other";
+    // todo_write 的 write 是「写清单」不是「改文件」，因此 plan 判定在 mutate 之前。
+    if (parts.includes("todo") || parts.includes("plan"))
+        return "plan";
+    if (has(VERIFY_TOKENS))
+        return "verify";
+    if (has(MUTATE_TOKENS))
+        return "mutate";
+    if (has(INSPECT_TOKENS))
+        return "inspect";
+    return "other";
+}
+/** 通用失败迹象：工具结果里出现这些词，就当这一步没成功。 */
+const FAILURE_RE = /失败|报错|错误|异常|无法|找不到|不存在|没找到|\berror\b|\bfailed\b|\bfailure\b|\bexception\b|traceback|\bpanic\b|\bcannot\b|\bunable\b|permission denied|timed out|timeout|超时/i;
+const UNKNOWN_RE = /结果未知|outcome unknown|tool_not_started|tool_outcome_unknown|仍在运行|still running|no output/i;
+/**
+ * 环境故障迹象（区别于「代码写错了」）：依赖解析不了、命令不存在、离线仓库、
+ * 网络/权限受阻。命中它才给「验证降级阶梯」——普通编译错误该归因到代码，
+ * 给环境阶梯反而会误导。
+ */
+const ENV_FAILURE_RE = /could not resolve dependencies|could not find artifact|cannot find module|module_not_found|command not found|not recognized as an internal|不是内部或外部命令|系统找不到指定的路径|no such file or directory|enoent|offline mode|cannot access .* in offline|本地仓库|repository.*(?:empty|missing)|network is unreachable|econnrefused|etimedout|proxy|self-signed certificate|eacces/i;
+/** 从工具结果文本判定成败。`explicitError` 为宿主上报的错误字段。 */
+export function readResultSignals(text, explicitError = false) {
+    const body = String(text ?? "");
+    const unknown = UNKNOWN_RE.test(body);
+    if (unknown)
+        return { failure: false, unknown: true, env: false };
+    // 环境故障本身就是失败：单独判定，避免「命令不存在」这类英文输出因通用失败词表
+    // 不含 "not found" 而被漏掉（实测 mvn: command not found 就踩过这个洞）。
+    const env = ENV_FAILURE_RE.test(body);
+    const failure = explicitError || env || FAILURE_RE.test(body);
+    return { failure, unknown: false, env: failure && env };
+}
+/** 连续失败序列的归类：环境故障占多数时才给降级阶梯。 */
+export function deadPathKind(envHits, failStreak) {
+    if (failStreak < 3)
+        return null;
+    return envHits >= 2 ? "env" : "retry";
+}

package/lib/host/injection.js

@@ -1,9 +1,24 @@
 /**
- * 人设注入组装（纯函数）：五段式 + Token 优化算法。
+ * 人设注入组装（纯函数）：按「会话恒定段 + 易变段」两层拆开。
  *
- * 段序遵循缓存友好分层：稳定内容在前（契约），易变内容在后（检索结果、播报）。
- * 语料示例按少样本衰减注入；记忆/风格按与当前用户消息的相关度取 top-k，
- * core 记忆（身份称呼类）恒注入。
+ * ## 为什么要拆
+ *
+ * 系统提示词在消息序列的最前面，而前缀缓存只认「从第一个不同的字节起全部失效」。
+ * 原实现把记忆 top-k、语料少样本衰减、切换播报和基础契约拼在同一段里，于是
+ * **每一步**（不只是每一轮）这段文本都会变——宿主只能就地改写头部 system 节点，
+ * 之后整段对话历史全部按全价重算。实测：某会话 282 个请求的 cacheRead 恒定
+ * 384 token，命中率 0.2%。
+ *
+ * 拆分后：
+ * - `buildPersonaContractSection` —— 只依赖人设身份（契约 / 身份名 / 纪律），
+ *   一个会话内逐字节不变，可以安全地待在 system 段吃前缀缓存；
+ * - `buildPersonaRuntimeSection` —— 记忆、风格、语料、播报，全部随轮次/查询变化，
+ *   交给宿主的 runtime-context 通道（渲染成对话尾部的一条快照消息，见 README
+ *   「分层注入」），改它不会作废前面的任何 token。
+ *
+ * 段内序仍遵循缓存友好分层：稳定内容在前（契约），易变内容在后（检索结果、播报）。
+ * 语料示例按少样本衰减注入；记忆/风格按与当前用户消息的相关度取 top-k，core 记忆
+ * （身份称呼类）恒注入。
  */
 import { decaySampleCount, topKByRelevance } from "../core/retrieval.js";
 import { sampleForSession } from "../core/sampling.js";
@@ -14,11 +29,26 @@ import { sampleForSession } from "../core/sampling.js";
 export function isCoreMemory(text) {
     return /名字|叫|称呼|昵称|爱称|自称|身份|小[A-Za-z]/.test(text) && text.length <= 30;
 }
-/** 组装人设注入文本；无人设（none/未选）时若带边界播报，仍单独输出播报。 */
-export function buildPersonaSection(input) {
-    const { persona, config, query } = input;
+/**
+ * 会话恒定的行为纪律：只在真实人设激活时（有契约或身份名）随契约一起注入，
+ * 且该判据**只取稳定输入**——否则「本步有没有检索到记忆」会让它忽隐忽现，
+ * 稳定段就白拆了。「不使用人设」（promptText 为空、无身份名）保持零注入。
+ */
+const PERSONA_DISCIPLINES = [
+    "〔连贯性规则〕语气与风格的连贯以你当前人设的任期为界：会话历史中其他人设或默认助手的表达都不构成连贯性义务，不要为了延续历史语气而偏离当前人设。",
+    "〔口吻纪律〕你现在是人设在说话，不是通用助手：第一句就必须是这个人会说的话，禁止用「好的」「当然可以」「没问题」这类助手套话开头，全程禁用「希望对你有所帮助」「还有其他需要吗」等助手腔收尾。",
+    "〔频率规则〕口头禅、语气词、emoji 按人设约定里的频率与触发条件使用——不句句都用满，但平淡话题里也要保持这个人的断句、用词和口头习惯，不能因为话题普通就退回默认助手口吻。",
+    "〔篇幅纪律〕像发微信一样说话：单条回复简短，通常是 1-3 句、几十字以内，一次只回应一个重点。人设契约里若写明了典型长度，以契约为准。只有对方明确要求详细展开（写代码、写文档、深入解释）时才允许长回复；闲聊场景写小作文就是失真。",
+];
+/**
+ * 会话恒定段：基础契约 + 身份 + 行为纪律。
+ * 只依赖 persona 与 profileName，同一会话内多次调用必须产出逐字节相同的文本
+ * （回归测试锁死：见 test/injection-layering.test.ts）。
+ */
+export function buildPersonaContractSection(input) {
+    const { persona } = input;
     if (!persona)
-        return input.boundaryText ?? "";
+        return "";
     const parts = [];
     // 1. 基础契约（基本盘）
     const promptText = persona.promptText.trim();
@@ -29,23 +59,38 @@ export function buildPersonaSection(input) {
         const who = input.profileName ?? persona.displayName;
         parts.push(`〔说话人切换〕现在起你不是通用助手，你是「${who}」。你的每一句话——包括解释、提问、拒绝——都要从「${who}」嘴里说出来，用 TA 的口吻、TA 的用词、TA 的断句。下面的人设契约是唯一标准，任何与它冲突的默认助手习惯一律作废。\n\n${promptText}`);
     }
-    // 2. 习得的风格约定（覆盖语义：与基础盘冲突时以此为准）
+    // 2. 身份
+    if (input.profileName) {
+        parts.push(`【你是谁】你的名字是「${input.profileName}」。这是你自己的身份，跨会话、跨项目不变；用户在任何地方叫这个名字都是在叫你。`);
+    }
+    if (parts.length === 0)
+        return "";
+    parts.push(...PERSONA_DISCIPLINES);
+    return parts.join("\n\n");
+}
+/**
+ * 易变段：习得风格 + 记忆 + 切换播报 + 语料示例。
+ * 全部随轮次或当前查询变化，必须走 runtime-context 通道（宿主渲染成对话尾部的
+ * 快照消息），否则每步都会作废 system 段之后的前缀。
+ */
+export function buildPersonaRuntimeSection(input) {
+    const { persona, config, query } = input;
+    if (!persona)
+        return "";
+    const parts = [];
+    // 1. 习得的风格约定（覆盖语义：与基础盘冲突时以此为准）
     const styles = input.styleRules;
     if (styles.length > 0) {
         const chosen = config.strategy === "full"
             ? styles.slice(-config.styleInject)
             : topKByRelevance(styles, (r) => r.rule, query, config.styleInject);
         if (chosen.length > 0) {
-            parts.push(`【习得的风格约定】以下是你在对话中学到的最新要求，与上方基础风格冲突时以此为准：\n${chosen
+            parts.push(`【习得的风格约定】以下是你在对话中学到的最新要求，与基础风格冲突时以此为准：\n${chosen
                 .map((r) => `- ${r.rule}`)
                 .join("\n")}`);
         }
     }
-    // 3. 身份
-    if (input.profileName) {
-        parts.push(`【你是谁】你的名字是「${input.profileName}」。这是你自己的身份，跨会话、跨项目不变；用户在任何地方叫这个名字都是在叫你。`);
-    }
-    // 4. 记忆：core 恒注入 + 其余按相关度 top-k
+    // 2. 记忆：core 恒注入 + 其余按相关度 top-k
     const facts = input.memories;
     if (facts.length > 0) {
         const core = facts.filter((f) => isCoreMemory(f.text)).slice(-3);
@@ -59,10 +104,10 @@ export function buildPersonaSection(input) {
             parts.push(`【你记得】这些是你与这位用户长期相处的记忆：\n${chosen.map((f) => `- ${f.text}`).join("\n")}`);
         }
     }
-    // 5. 接班播报（仅切换窗口）
+    // 3. 接班播报（仅切换窗口）
     if (input.boundaryText)
         parts.push(input.boundaryText);
-    // 6. 语料示例：少样本衰减 + 会话级稳定采样。摘录语料（对话中被用户认可的
+    // 4. 语料示例：少样本衰减 + 会话级稳定采样。摘录语料（对话中被用户认可的
     // 真实回复）优先占位——它们比蒸馏语料更贴近当前使用中的语气。
     const sampleCount = decaySampleCount(config.sampleCount, input.turnIndex, config.sampleMin);
     const pins = (input.corpusPins ?? []).map((p) => ({ user: p.user, assistant: p.assistant }));
@@ -87,14 +132,16 @@ export function buildPersonaSection(input) {
         if (lines)
             parts.push(`参考对话示例：\n（只模仿说话方式，不要把示例中的时间、地点、正在做什么或其他事实当成当前事实）\n${lines}`);
     }
-    // 7. 连贯性原则：连贯以人设任期为界，而非以会话为界——切换人设时，
-    // 历史中前任与默认助手的表达不构成语气连贯性义务（对抗模型的惯性连贯先验）。
-    // 仅在真实人设激活时输出；「不使用人设」保持零注入。
-    if (parts.length > 0) {
-        parts.push("〔连贯性规则〕语气与风格的连贯以你当前人设的任期为界：会话历史中其他人设或默认助手的表达都不构成连贯性义务，不要为了延续历史语气而偏离当前人设。");
-        parts.push("〔口吻纪律〕你现在是人设在说话，不是通用助手：第一句就必须是这个人会说的话，禁止用「好的」「当然可以」「没问题」这类助手套话开头，全程禁用「希望对你有所帮助」「还有其他需要吗」等助手腔收尾。");
-        parts.push("〔频率规则〕口头禅、语气词、emoji 按人设约定里的频率与触发条件使用——不句句都用满，但平淡话题里也要保持这个人的断句、用词和口头习惯，不能因为话题普通就退回默认助手口吻。");
-        parts.push("〔篇幅纪律〕像发微信一样说话：单条回复简短，通常是 1-3 句、几十字以内，一次只回应一个重点。人设契约里若写明了典型长度，以契约为准。只有对方明确要求详细展开（写代码、写文档、深入解释）时才允许长回复；闲聊场景写小作文就是失真。");
-    }
     return parts.filter(Boolean).join("\n\n");
 }
+/**
+ * 兼容组合：稳定段 + 易变段（旧调用方的单一入口）。
+ * 新版宿主接线请分别取 `buildPersonaContractSection`（system 段）与
+ * `buildPersonaRuntimeSection`（runtime-context 通道）。
+ * 无人设（none/未选）时若带边界播报，仍单独输出播报。
+ */
+export function buildPersonaSection(input) {
+    if (!input.persona)
+        return input.boundaryText ?? "";
+    return [buildPersonaContractSection(input), buildPersonaRuntimeSection(input)].filter(Boolean).join("\n\n");
+}

package/lib/host/methods.js

@@ -0,0 +1,64 @@
+/**
+ * 方法层：把「怎么做得聪明」写成可注入的短块。
+ *
+ * 与协议正文（thinking.ts）的分工：
+ * - 协议正文＝**纪律**（不越权、要验证、要复核），会话恒定、吃前缀缓存、对所有任务生效；
+ * - 本模块＝**方法**（怎么量化需求、怎么改文档、怎么评估影响面），只在对应形态的任务轮
+ *   出现——文档方法论不该出现在调试会话里，影响面清单也不该出现在闲聊里。
+ *
+ * 成本模型：这些都注入到尾部快照，因此只在**内容变化时**付费（实测 58 步只产生 9 条快照），
+ * 每轮多几百字是可接受的；真正要避免的是把它们塞进 system 段（那会作废整段前缀）。
+ */
+/** 任务型请求且尚无契约时注入：把「先量化」变成一次具体的产出。 */
+export function buildContractMethodDirective() {
+    return [
+        "〔先量化后动手〕本轮是任务型请求。开工前先写任务契约（lume_contract）：",
+        "- 目标：一句话，可观察的结果（不是「优化一下」这种动词）",
+        "- 范围：精确到路径 / 模块 / 章节 / 表",
+        "- 数量：先估一个数，探索后回填实际值——交付时要用实际数量对账",
+        "- 完成判据：可执行、可核对（命令 / 回读 / 对照），不是「改完」",
+        "- 非目标：明确不动什么，防止范围蔓延",
+        "- 待确认：只列真正阻塞的（≤2 个）；不阻塞的按默认假设前进并写明假设",
+    ].join("\n");
+}
+/** 文档任务轮注入：文档的失败模式是静默内容丢失，所以方法围绕「结构 + 最小编辑 + 回读」。 */
+export function buildDocumentMethodDirective() {
+    return [
+        "〔文档编辑方法〕",
+        "1. 先取结构：标题层级、表格/图表清单、编号体系，复述一遍再动；长文档按大纲逐节记账（lume_change 的 target 用章节名），避免漏节或反复处理同一节。",
+        "2. 最小编辑：只改目标区域，保留原有格式、编号、交叉引用与样式——不要整份重写。",
+        "3. 术语与称谓全文一致：改一个术语前先全文检索它的全部出现位置，否则会留下半新半旧。",
+        "4. 交付前回读改动区域，列出「改了什么 / 没动什么 / 未核对什么」；没有回读证据不要说已改好。",
+    ].join("\n");
+}
+/** 执行轮注入：改动之前的影响面清单，治「边写边想」。 */
+export function buildImpactDirective() {
+    return [
+        "〔改动影响面〕动手前列出：要改的符号 → 谁调用它、它实现或被实现于谁、配置或 SQL 映射、前端/模板引用；并标出「不打算改但需一并确认」的位置。",
+        "每处改动写明验证方式；同一文件的相关改动一次做完，不要反复回来改同一个文件。",
+    ].join("\n");
+}
+/** 环境里有结构分析/符号工具时的一句提示：用符号级定位替代通篇 read。 */
+export function buildStructureHint(toolName) {
+    if (!toolName)
+        return null;
+    return `〔定位工具〕当前环境有结构分析工具（${toolName}）：优先用它做符号级定位（谁调用、被谁调用、结构概览），比通篇 read 更省 token 也更准。`;
+}
+/**
+ * 拼装尾部快照块：超预算时优先丢掉**可丢**的块（从后往前），而不是截断中间的句子。
+ * 预算存在的意义是防止"载具越积越多，把注意力挤没"——实测尾部快照约 1.8-2k 字符时
+ * 命中率与合规都健康，这里给到 4200 字符仍有充足余量。
+ */
+export function composeBlocks(blocks, budgetChars = 4200) {
+    const present = blocks.filter((block) => Boolean(block.text));
+    let out = present.map((block) => block.text).join("\n\n");
+    if (out.length <= budgetChars)
+        return out;
+    for (let i = present.length - 1; i >= 0 && out.length > budgetChars; i--) {
+        if (!present[i].droppable)
+            continue;
+        present.splice(i, 1);
+        out = present.map((block) => block.text).join("\n\n");
+    }
+    return out.length > budgetChars ? out.slice(0, budgetChars) : out;
+}