lume-dsh-plugin 0.7.3 → 0.8.0

package/lib/host/backfill.js

@@ -0,0 +1,218 @@
+/**
+ * 会话补蒸馏（backfill）：把**已经发生过**的会话（含已经撑满、再也聊不动的那些）榨成跨会话知识。
+ *
+ * 为什么需要它：上下文撑满 → 宿主 compaction 会失败（现场日志：
+ * `compaction/end … error: "pi-ai detected context overflow"`）→ 会话再也产不出事件 →
+ * **凡是在此之前没被沉淀的内容就永久丢失**。但会话记录本身**还在硬盘上**
+ * （`<DSH_HOME>/harness/sessions/<workspace>/<sid>/session.v3.jsonl.zstd`），所以可以离线补。
+ *
+ * 设计约束（都是被现场教出来的）：
+ * - **不能阻塞宿主**：插件与宿主同进程，解压大会话要几十~几百毫秒 → 分片执行（每次一个会话，其间让出事件循环）。
+ * - **必须幂等**：同一批会话反复扫不能重复写（靠 addFact 的相似度去重 + 本轮已收集文本集）。
+ * - **只认最近一段**：默认回看 7 天，避免每次启动扫全部历史。
+ * - **失败静默降级**：宿主内部目录结构变了就什么都不做（只记一行日志），绝不影响启动。
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { zstdDecompressSync } from "node:zlib";
+/**
+ * 定位 DSH 数据目录（补蒸馏要找 `<base>/harness/sessions`）。
+ *
+ * 现场教训（2026-09-24）：最初只认 `DSH_HOME`，而宿主进程里它可能**不存在**（实测 null），
+ * 于是 `startSessionBackfill` 直接静默返回 —— **重启后一条知识都没沉淀，且没有任何日志**。
+ * 现在按候选探测（`%APPDATA%\dsh-desktop` 是现成路径），并且**无论成功失败都留痕**。
+ */
+export function resolveDsHome(env = process.env) {
+    const candidates = [];
+    if (env.DSH_HOME)
+        candidates.push(env.DSH_HOME);
+    if (env.LUME_DS_HOME)
+        candidates.push(env.LUME_DS_HOME);
+    if (env.APPDATA)
+        candidates.push(join(env.APPDATA, "dsh-desktop"));
+    if (env.LOCALAPPDATA)
+        candidates.push(join(env.LOCALAPPDATA, "dsh-desktop"));
+    for (const candidate of candidates) {
+        try {
+            if (existsSync(join(candidate, "harness", "sessions")))
+                return candidate;
+        }
+        catch {
+            /* 探测失败就试下一个 */
+        }
+    }
+    return null;
+}
+const SESSION_FILE = "session.v3.jsonl.zstd";
+const DEFAULT_DAYS = 7;
+const DEFAULT_PER_SESSION = 12;
+/** 解压多帧 zstd 会话日志（宿主按帧追加写）。 */
+function readSessionEvents(file) {
+    const buf = readFileSync(file);
+    const frames = [];
+    let cur = 0;
+    for (let i = 4; i < buf.length - 3; i++) {
+        if (buf[i] === 0x28 && buf[i + 1] === 0xb5 && buf[i + 2] === 0x2f && buf[i + 3] === 0xfd) {
+            frames.push(buf.subarray(cur, i));
+            cur = i;
+        }
+    }
+    frames.push(buf.subarray(cur));
+    let text = "";
+    for (const frame of frames) {
+        try {
+            text += zstdDecompressSync(frame).toString("utf8");
+        }
+        catch {
+            /* 尾部半帧忽略 */
+        }
+    }
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (!line)
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            /* 跳过坏行 */
+        }
+    }
+    return out;
+}
+/** 列出最近 N 天内有改动的会话文件（按 mtime 升序，旧的先处理）。 */
+export function recentSessionFiles(dsHome, days = DEFAULT_DAYS) {
+    const root = join(dsHome, "harness", "sessions");
+    const out = [];
+    const cutoff = Date.now() - days * 86_400_000;
+    let workspaces = [];
+    try {
+        workspaces = readdirSync(root);
+    }
+    catch {
+        return out;
+    }
+    for (const ws of workspaces) {
+        let sessions = [];
+        try {
+            sessions = readdirSync(join(root, ws));
+        }
+        catch {
+            continue;
+        }
+        for (const sid of sessions) {
+            const file = join(root, ws, sid, SESSION_FILE);
+            try {
+                const stat = statSync(file);
+                if (stat.isFile() && stat.mtimeMs >= cutoff)
+                    out.push({ file, mtime: stat.mtimeMs });
+            }
+            catch {
+                /* 没有该文件 */
+            }
+        }
+    }
+    return out.sort((a, b) => a.mtime - b.mtime);
+}
+/**
+ * 分片执行补蒸馏：每次处理一个会话，`chunkMs` 后处理下一个（不阻塞宿主）。
+ * 返回停止函数（会话被销毁/插件卸载时调用）。
+ */
+export function startBackfill(deps, options = {}) {
+    const perSession = deps.perSession ?? DEFAULT_PER_SESSION;
+    const maxSessions = options.maxSessions ?? 60;
+    const chunkMs = options.chunkMs ?? 150;
+    const files = recentSessionFiles(deps.dsHome, options.days ?? DEFAULT_DAYS);
+    if (files.length === 0)
+        return () => {
+            /* 无可补 */
+        };
+    let index = 0;
+    let stopped = false;
+    let totalAdded = 0;
+    let timer = null;
+    const step = async () => {
+        if (stopped)
+            return;
+        const item = files[index++];
+        if (!item) {
+            deps.log(`lume: 会话补蒸馏完成：扫描 ${Math.min(files.length, maxSessions)} 个会话，新增 ${totalAdded} 条跨会话知识`);
+            return;
+        }
+        try {
+            const events = readSessionEvents(item.file);
+            // 会话标题：作用域判定要用（需求级知识只给同一需求看）
+            let sessionTitle = "";
+            for (const scan of events) {
+                if (scan.type !== "session/title")
+                    continue;
+                sessionTitle = String(scan.data?.title ?? "").slice(0, 60);
+                if (sessionTitle)
+                    break;
+            }
+            let cwd = null;
+            for (const event of events) {
+                if (event.type !== "user/message")
+                    continue;
+                cwd = deps.workspaceOf(deps.messageText(event.data?.message ?? event.data));
+                if (cwd)
+                    break;
+            }
+            const key = cwd ? deps.projectKeyOf(cwd) : null;
+            if (key) {
+                let added = 0;
+                const seen = [];
+                for (const event of events) {
+                    if (added >= perSession)
+                        break;
+                    let candidates = [];
+                    if (event.type === "tool/result")
+                        candidates = deps.extract(deps.messageText(event.data?.message), "tool");
+                    else if (event.type === "assistant/message") {
+                        const visible = deps.visibleText(event.data?.message);
+                        if (visible)
+                            candidates = deps.extract(visible, "assistant");
+                    }
+                    else if (event.type === "user/message") {
+                        const text = deps.messageText(event.data?.message ?? event.data);
+                        if (text && !text.includes("Current runtime context"))
+                            candidates = deps.extract(text, "user");
+                    }
+                    for (const candidate of candidates) {
+                        if (added >= perSession)
+                            break;
+                        if (deps.looksSensitive(candidate.text))
+                            continue;
+                        if (seen.some((prior) => prior === candidate.text))
+                            continue;
+                        const fact = deps.normalizeFact({ kind: candidate.kind, text: candidate.text }, Number(event.time) || Date.now(), {
+                            taskTitle: sessionTitle,
+                            requirementHints: deps.requirementHintsOf(cwd),
+                        });
+                        if (!fact)
+                            continue;
+                        seen.push(candidate.text);
+                        if (await deps.addFact(key, fact))
+                            added++;
+                    }
+                }
+                totalAdded += added;
+                if (added > 0)
+                    deps.log(`lume: 会话补蒸馏：${item.file.split(/[\\/]/).slice(-2)[0]?.slice(0, 18)} → ${key} 新增 ${added} 条`);
+            }
+        }
+        catch (error) {
+            deps.log(`lume: 会话补蒸馏跳过（${String(error).slice(0, 80)}）`);
+        }
+        if (index < files.length && index < maxSessions)
+            timer = setTimeout(() => void step(), chunkMs);
+        else
+            deps.log(`lume: 会话补蒸馏收尾：共扫描 ${index} 个会话，新增 ${totalAdded} 条`);
+    };
+    timer = setTimeout(() => void step(), chunkMs);
+    return () => {
+        stopped = true;
+        if (timer)
+            clearTimeout(timer);
+    };
+}

package/lib/host/bootstrap.js

@@ -0,0 +1,130 @@
+import { IdentityStore, LUME_IDENTITY_SPEC } from "./identity.js";
+import { LUME_PROJECT_SPEC, ProjectStore } from "./project.js";
+import { LUME_REFLECTION_SPEC, ReflectionStore } from "./reflection.js";
+import { FilePersonaStore, PersonaStore } from "./store.js";
+export function initStores(input) {
+    // ── 存储就绪：会话选择域（必有）+ 身份域（失败降级为无档案功能）──
+    let currentStore = null;
+    let identity = null;
+    const storesReady = (async () => {
+        try {
+            const domain = await input.ctx.storageDomain.open(input.personaDomainSpec);
+            input.ctx.effect(() => async () => {
+                await domain.close();
+            }, "lume: close state domain");
+            const store = new PersonaStore(domain.table(input.sessionPersonaTable), { maxSessions: input.maxSessions });
+            const migrated = await input.migrateLegacyState(store, input.legacyStatePath);
+            if (migrated)
+                input.ctx.logger?.warn?.("lume: 已从 assets/persona-state.json 迁移旧的人设记忆");
+            return store;
+        }
+        catch (error) {
+            input.ctx.logger?.warn?.("lume: storageDomain 不可用，降级为 assets 文件存储", error);
+            return new FilePersonaStore(input.legacyStatePath, { maxSessions: input.maxSessions });
+        }
+    })();
+    const identityReady = (async () => {
+        try {
+            const domain = await input.ctx.storageDomain.open(LUME_IDENTITY_SPEC);
+            input.ctx.effect(() => async () => {
+                await domain.close();
+            }, "lume: close identity domain");
+            return new IdentityStore({
+                profile: domain.table("profile"),
+                memory_facts: domain.table("memory_facts"),
+                style_rules: domain.table("style_rules"),
+                corpus_pins: domain.table("corpus_pins"),
+                custom_personas: domain.table("custom_personas"),
+            });
+        }
+        catch (error) {
+            input.ctx.logger?.warn?.("lume: 身份域不可用，档案/记忆/自定义人设功能降级", error);
+            return null;
+        }
+    })();
+    // 已吞异常：内部 try/catch 后返回降级值，句柄赋值不会 reject
+    void storesReady.then((store) => {
+        currentStore = store;
+    });
+    // 已吞异常：内部 try/catch 后返回降级值，句柄赋值不会 reject
+    void identityReady.then((store) => {
+        identity = store;
+    });
+    // ── 反思域（会话结束后打分，失败降级为无反思功能）──
+    let reflectionStore = null;
+    let project = null;
+    const reflectionReady = (async () => {
+        try {
+            const domain = await input.ctx.storageDomain.open(LUME_REFLECTION_SPEC);
+            input.ctx.effect(() => async () => {
+                await domain.close();
+            }, "lume: close reflection domain");
+            const store = new ReflectionStore(domain.table("logs"));
+            const migrated = await store.migrateLegacy();
+            if (migrated > 0)
+                input.ctx.logger?.warn?.(`lume: 已迁移 ${migrated} 条旧版反思日志`);
+            return store;
+        }
+        catch (error) {
+            input.ctx.logger?.warn?.("lume: 反思域不可用，反思日志降级", error);
+            return null;
+        }
+    })();
+    // 已吞异常：内部 try/catch 后返回降级值，句柄赋值不会 reject
+    void reflectionReady.then((s) => {
+        reflectionStore = s;
+    });
+    function projectTask(sid, label, run) {
+        void projectReady
+            .then((store) => {
+            if (!store)
+                return;
+            return Promise.resolve(run(store));
+        })
+            .catch((error) => input.ctx.logger?.warn?.(`lume: [${sid}] ${label} 失败：${input.describeError(error)}`));
+    }
+    const projectReady = (async () => {
+        if (!input.projectMemoryOn)
+            return null;
+        try {
+            const domain = await input.ctx.storageDomain.open(LUME_PROJECT_SPEC);
+            input.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"),
+                design: domain.table("design"),
+                requirements: domain.table("requirements"),
+                taskMemory: domain.table("task_memory"),
+            });
+        }
+        catch (error) {
+            input.ctx.logger?.warn?.("lume: 项目域不可用，任务契约/台账/项目知识降级", error);
+            return null;
+        }
+    })();
+    // 已吞异常：内部 try/catch 后返回降级值，句柄赋值不会 reject
+    void projectReady.then((s) => {
+        project = s;
+    });
+    /** RPC 等入口可能在存储兑现前被调用：等一次并回填句柄。 */
+    async function ensureReady() {
+        currentStore ??= await storesReady;
+        identity ??= await identityReady;
+    }
+    return {
+        ensureReady,
+        storesReady,
+        identityReady,
+        reflectionReady,
+        projectReady,
+        currentStore: () => currentStore,
+        identity: () => identity,
+        reflectionStore: () => reflectionStore,
+        project: () => project,
+        projectTask,
+    };
+}

package/lib/host/boundary.js

@@ -20,9 +20,7 @@ export function composeBoundary(input) {
     const divider = current
         ? `第一件事：本条回复的第一行，一字不改地单独输出这一行：\n── 「${labelOf(registry, current)}」接手 ──\n这一行是给用户的切换提示，不算出戏；从第二行起再进入正文。`
         : "";
-    const takeover = greeting
-        ? `${divider}正文第一句用简短的接手招呼，让用户明确听到换人了。`
-        : divider;
+    const takeover = greeting ? `${divider}正文第一句用简短的接手招呼，让用户明确听到换人了。` : divider;
     const correction = escalated
         ? "特别纠偏：上一条回复仍在沿用旧人设的语气，这是偏差。本条回复必须完全按当前人设的契约说话——称呼、自称、口头禅、句式全部切换，不残留任何旧痕迹。"
         : "";

package/lib/host/clauses.js

@@ -0,0 +1,180 @@
+import { ROUTE_CORRECTION_RE } from "./protocol.js";
+import { THINKING_TEXT } from "./thinking.js";
+/**
+ * 标题 → 稳定键。用**显式映射**而不是按顺序编号：正文里插一条、删一条都不该让
+ * 历史度量里的键集体错位（那种「改了顺序，去年的统计全变意思」的坑很贵）。
+ */
+const CLAUSE_ID_BY_TITLE = {
+    身份分工: "identity",
+    上下文管理: "context",
+    阶段门控: "phase-gate",
+    任务分解: "decompose",
+    自适应投入: "effort",
+    意图对齐: "align",
+    信息路由: "routing",
+    变更纪律: "change-discipline",
+    验证闭环: "verify",
+    证据时效: "evidence-recency",
+    独立判断: "independent",
+    证据来源纪律: "evidence-source",
+    事实优先: "facts-first",
+    提问纪律: "question-discipline",
+    达成标准: "done-criteria",
+    振荡预防: "oscillation",
+    结果复核: "review",
+    工具与安全: "tool-safety",
+    代码任务: "code-task",
+    对话任务: "chat-task",
+    隐私与事实边界: "fact-boundary",
+};
+/** 条款行形如 `**P1 验证闭环**：正文…`；无级别前缀的（工具与安全 / 代码任务…）也认。 */
+const CLAUSE_LINE_RE = /^\*\*(?:P([0-3])\s+)?([^*]+)\*\*[：:]\s*(.+)$/;
+/**
+ * 从协议正文里切条款。切不出来就返回空表（调用方按「没有重点」处理）——
+ * 宁可少一条加权，也不要凭猜测编一条不存在的条款。
+ */
+export function parseProtocolClauses(fullText) {
+    const out = [];
+    for (const line of fullText.split("\n")) {
+        const hit = CLAUSE_LINE_RE.exec(line.trim());
+        if (!hit)
+            continue;
+        const title = hit[2].trim();
+        const text = hit[3].trim();
+        if (!title || !text)
+            continue;
+        out.push({
+            id: CLAUSE_ID_BY_TITLE[title] ?? title,
+            tier: hit[1] ? `P${hit[1]}` : "core",
+            title,
+            text,
+        });
+    }
+    return out;
+}
+/** 完整版协议切出来的条款表（短版/推理版是压缩文本，不参与加权）。 */
+export const PROTOCOL_CLAUSES = parseProtocolClauses(THINKING_TEXT);
+/** 每轮重述的条款上限：三条。四条以上就等于把「全给」搬到了尾部，稀释照旧。 */
+export const FOCUS_CLAUSE_LIMIT = 3;
+export function clauseById(id) {
+    return PROTOCOL_CLAUSES.find((clause) => clause.id === id) ?? null;
+}
+/**
+ * 按「当前形态」选最相关的三条。
+ *
+ * 判定顺序 = 紧急度：**纠正 > 压缩 > 模式**。纠正与压缩都会让「上一轮的上下文」
+ * 不再是可靠前提，此时模式类条款反而是次要的。
+ */
+export function selectFocusClauses(input) {
+    const ids = focusClauseIds(input);
+    return ids
+        .map((id) => clauseById(id))
+        .filter((clause) => clause !== null)
+        .slice(0, FOCUS_CLAUSE_LIMIT);
+}
+/** 选中条款的稳定键（度量用：记录「这轮加权了哪三条」，才能回头看出效果）。 */
+export function focusClauseIds(input) {
+    return applyCorrectionClosedLoop(input, baseClauseIds(input));
+}
+/**
+ * 闭环：度量里采到了「哪个模式在被纠正」就必须有人消费它（2026-09-24 审核指出：
+ * correctionsByMode 采了却没有任何消费方，等于白采）。
+ *
+ * 规则保守：**本模式**被纠正 ≥2 次才动，只把「对齐纠偏」插到最前面，条数上限不变。
+ * 注意它只改变加权顺序，不改模式判定——判错模式该修判定，不该靠加一条提醒掩盖。
+ *
+ * **有冷却**（二审指出：上一版是单调、永久、无冷却的，别的机制都有 NOTICE_CAPS 兜着、这条没有）：
+ * 只认「近期」纠正——最后一次纠正距今超过 CORRECTION_LOOP_TURNS 轮，就不再加权。
+ * 否则某个模式被纠两次之后，这个会话此后每一轮都挂着 align，把提醒变成背景噪音。
+ */
+function applyCorrectionClosedLoop(input, ids) {
+    const corrections = input.correctionModes?.[input.mode] ?? 0;
+    if (corrections < 2 || input.correction || ids[0] === "align")
+        return ids;
+    const last = input.lastCorrectionTurnByMode?.[input.mode];
+    if (last === undefined || input.turnIndex - last > CORRECTION_LOOP_TURNS)
+        return ids;
+    return ["align", ...ids].slice(0, FOCUS_CLAUSE_LIMIT);
+}
+/** 闭环的记忆窗口（轮）：超过就不再加权，避免「沾上就摘不掉」。 */
+export const CORRECTION_LOOP_TURNS = 6;
+function baseClauseIds(input) {
+    if (input.correction)
+        return ["align", "question-discipline", "independent"];
+    if (input.compactionRecent)
+        return ["context", "evidence-recency", "facts-first"];
+    switch (input.mode) {
+        case "question":
+            return ["facts-first", "question-discipline", "evidence-source"];
+        case "research":
+            return ["evidence-source", "facts-first", "evidence-recency"];
+        case "discussion":
+            return ["independent", "align", "effort"];
+        case "diagnosis":
+            return ["evidence-recency", "align", "independent"];
+        case "execute": {
+            // 已经动过东西：先保「改一处验一处」，其次才是变更纪律与完成判据。
+            if ((input.unverifiedChanges ?? 0) > 0 || (input.mutations ?? 0) > 0)
+                return ["verify", "change-discipline", "done-criteria"];
+            // 还没写契约：先把「阶段门控 + 任务分解」顶上，避免直接动手。
+            if (!input.hasContract)
+                return ["phase-gate", "decompose", "done-criteria"];
+            return ["change-discipline", "verify", "code-task"];
+        }
+        default:
+            return ["facts-first", "align", "done-criteria"];
+    }
+}
+/** 条款正文压成一句话：重述只给「抓手」，正文仍在系统提示里，不在这里复制全文。 */
+function oneLine(text, cap = 110) {
+    const first = text.split("。")[0] ?? text;
+    const trimmed = first.endsWith("。") ? first : `${first}。`;
+    return trimmed.length > cap ? `${trimmed.slice(0, cap)}…` : trimmed;
+}
+/**
+ * 渲染「本轮重点」。返回 null = 本轮不加权（没有可选项时宁可不发）。
+ * 文本刻意写明「完整协议已在系统提示」——否则模型会以为条款被缩减了，反而放宽行为。
+ */
+export function buildFocusClauseDirective(input) {
+    const clauses = selectFocusClauses(input);
+    if (clauses.length === 0)
+        return null;
+    const lines = clauses.map((clause, i) => {
+        const tier = clause.tier === "core" ? "" : `${clause.tier} `;
+        return `${i + 1}. ${tier}${clause.title}：${oneLine(clause.text)}`;
+    });
+    return [`〔本轮重点〕完整协议已在系统提示中（条款一条都没少）；这里只按本轮形态加权最相关的 ${clauses.length} 条：`, ...lines].join("\n");
+}
+/**
+ * 装配入口（给 prompt-blocks 用）：与 focusIdsFor 共用 focusInputFor——
+ * 选择政策只有一处，改规则不会漏掉记录侧（否则度量测的不是真正注入的东西）。
+ */
+export function focusDirectiveFor(st, mode, query, state) {
+    return buildFocusClauseDirective(focusInputFor(st, mode, query, state));
+}
+/** 度量入口（给 index 记「本轮到底加权了哪几条」用）：同源，不是另算一遍。 */
+export function focusIdsFor(st, mode, query, state) {
+    return focusClauseIds(focusInputFor(st, mode, query, state));
+}
+/**
+ * 从会话态构造选择输入：装配块与度量记录**共用这一处**，避免两处口径漂移。
+ * 契约/未验证条数由调用方（index，只有它拿得到 store）传入——`taskPhase` 当不了判据，
+ * 因为模式一旦判成执行，阶段就已经是 execute 了。
+ */
+export function focusInputFor(st, mode, query, state) {
+    return {
+        mode,
+        phase: st.taskPhase,
+        turnIndex: st.turnIndex,
+        correctionModes: state.correctionModes,
+        lastCorrectionTurnByMode: state.lastCorrectionTurnByMode,
+        correction: ROUTE_CORRECTION_RE.test(String(query ?? "")),
+        compactionRecent: st.compaction !== null && st.turnIndex - st.compaction.turnIndex <= 1,
+        unverifiedChanges: state.unverifiedChanges,
+        hasContract: state.hasContract,
+        mutations: st.triggerCounters.mutations,
+    };
+}
+// 纠正语用**直接复用** protocol 的那一份常量（曾经这里抄了一份，少了 9 个词——
+// 「谁说让你」能重算路由却选不出「对齐」条款，是典型的口径漂移）。
+// 判错代价只是多给/少给一条加权条款；真正决定重算模式的是 classifyWithTrajectory。

package/lib/host/config.js

@@ -0,0 +1,7 @@
+/**
+ * 插件配置的类型（架构整理 ①：从 index.ts 抽出）。
+ *
+ * 为什么单独成模块：deps 边界要引用它（`config: LumeConfig`），而 host 模块不能 import index.ts
+ * （index 是装配点，反向依赖会成环）。放这里两边都能用，且改配置字段时 tsc 会指出所有受影响处。
+ */
+export {};

package/lib/host/diag.js

@@ -7,19 +7,56 @@
  *
  * 宿主未提供 DSH_HOME 时静默跳过；任何写失败都不影响功能。
  */
-import { appendFileSync } from "node:fs";
+import { appendFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 /** 诊断文件名（位于 DSH_HOME 下）。 */
 export const LUME_LOG_FILE = "lume-compaction.log";
-/** 追加一行诊断；失败静默。 */
-export function appendLumeLog(message) {
+/**
+ * 解析诊断日志目录：`DSH_HOME` → `%APPDATA%\dsh-desktop` → `%LOCALAPPDATA%\dsh-desktop`。
+ *
+ * 现场教训（2026-09-24）：宿主进程里**没有** `DSH_HOME`（实测 null），于是所有走这条通道的
+ * 诊断日志**写了等于没写** —— 补蒸馏"跑了却零日志"、映射命中日志也看不见，只能靠行为反推。
+ * 现在按候选探测，落到第一个存在的目录。
+ */
+export function lumeLogHome() {
+    const candidates = [
+        process.env.DSH_HOME,
+        process.env.APPDATA ? join(process.env.APPDATA, "dsh-desktop") : null,
+        process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "dsh-desktop") : null,
+    ];
+    for (const candidate of candidates) {
+        if (!candidate)
+            continue;
+        try {
+            if (existsSync(candidate))
+                return candidate;
+        }
+        catch {
+            /* 探测失败就试下一个 */
+        }
+    }
+    return null;
+}
+/** 追加一行到**指定目录**（测试与自检要指定落点，否则会把假数据写进真实指标文件）。 */
+export function appendLumeLineAt(home, file, message) {
     try {
-        const home = process.env.DSH_HOME;
-        if (!home)
-            return;
-        appendFileSync(join(home, LUME_LOG_FILE), `${new Date().toISOString()} ${message}\n`, "utf8");
+        appendFileSync(join(home, file), `${message}\n`, "utf8");
     }
     catch {
         /* 诊断失败不阻断功能 */
     }
 }
+/**
+ * 追加一行到指定诊断文件（自动探测落点）。
+ * 度量另开一个文件：压缩日志只在压缩时写、量小；度量每轮都写，混在一起会把压缩记录冲淡。
+ */
+export function appendLumeLine(file, message) {
+    const home = lumeLogHome();
+    if (!home)
+        return;
+    appendLumeLineAt(home, file, message);
+}
+/** 追加一行诊断；失败静默。 */
+export function appendLumeLog(message) {
+    appendLumeLine(LUME_LOG_FILE, `${new Date().toISOString()} ${message}`);
+}