weaver-e9-assistant-cli 1.1.4 → 1.1.11

package/dist/memory.js

@@ -0,0 +1,968 @@
+/**
+ * 用户记忆模块：千人千面的流程快捷方式 + 字段默认值 + 三层记忆。
+ *
+ * 设计原则：
+ *   - 按环境 + 用户双层隔离：`~/.e9/user_memory_<envkey>_<selfId>.json`
+ *   - 换环境/workflowId 不同 → 隔离；换人/习惯不同 → 隔离
+ *   - 写入 fail-soft：写失败不阻断业务
+ *   - 三层记忆模型（借鉴 E10）：
+ *     user      — 用户画像（展示/沟通偏好）
+ *     shortcuts — 全局别名→工作流映射（跨流程通用，所属 memory.md 层）
+ *     fieldDefaults / formCache — 工作流维度（所属 workflow:{id} 层）
+ *   - 冲突规则：记忆与当前系统解析结果冲突时以当前系统为准
+ *
+ * 文件结构（v2，向后兼容 v1）：
+ *   {
+ *     selfId, selfName, updatedAt,
+ *     available: true,                              // 记忆是否可用
+ *     user: { preferences },                        // 用户画像（三层之 user）
+ *     shortcuts: { "<关键词>": { ... } },            // 全局别名映射（三层之 memory.md）
+ *     fieldDefaults: { "<wfId>": { ... } },          // 字段默认值（三层之 workflow:{id}）
+ *     autoSubmit: ["<关键词>"],
+ *     formCache: { "<wfId>": { ... } }               // 表单结构缓存
+ *   }
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { profileNameFromBaseUrl } from './config.js';
+import { getCurrentUser } from './wfuser.js';
+
+/** 缓存目录（测试可用 E9_MEMORY_CACHE_DIR 覆盖）。 */
+export function memoryCacheDir() {
+    return process.env.E9_MEMORY_CACHE_DIR || path.join(os.homedir(), '.e9');
+}
+
+/** 缓存文件路径：~/.e9/user_memory_<envkey>_<selfId>.json */
+export function memoryCachePath(cfg, selfId) {
+    const envkey = profileNameFromBaseUrl(cfg.baseUrl);
+    return path.join(memoryCacheDir(), `user_memory_${envkey}_${selfId}.json`);
+}
+
+/** 解析 cookie 里的 userId（兜底）。 */
+function parseUserIdFromCookie(cookie) {
+    if (!cookie) return '';
+    const m = cookie.match(/(?:^|;\s*)loginidweaver=([^;]+)/);
+    if (!m) return '';
+    return m[1] || '';
+}
+
+// ─── 读取 ──────────────────────────────────────
+
+/**
+ * 读记忆文件；文件不存在/损坏/selfId 不匹配 → 返回空记忆。
+ * v2 格式新字段（user/formCache）不存在时自动补默认值，保证向后兼容。
+ */
+export function readMemory(cfg, selfId) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(memoryCachePath(cfg, selfId), 'utf8'));
+        if (!raw || raw.selfId !== selfId) return emptyMemory(selfId, '');
+        return {
+            selfId: raw.selfId || selfId,
+            selfName: raw.selfName || '',
+            updatedAt: raw.updatedAt || '',
+            lastCacheCheck: raw.lastCacheCheck || null,
+            available: raw.available !== false, // 默认 true（兼容 v1 文件无此字段）
+            user: raw.user || {},
+            shortcuts: raw.shortcuts || {},
+            fieldDefaults: raw.fieldDefaults || {},
+            autoSubmit: raw.autoSubmit || [],
+            formCache: raw.formCache || {},
+            workflowListCache: raw.workflowListCache || {},
+        };
+    } catch {
+        return emptyMemory(selfId, '');
+    }
+}
+
+/** 写记忆文件（失败不抛，不阻断业务）。 */
+export function writeMemory(cfg, mem) {
+    const p = memoryCachePath(cfg, mem.selfId);
+    // ★ 原子写：先写临时文件再 rename 替换（同卷 rename 原子），并发读方永远不会看到半写文件，
+    //   避免 JSON 撕裂/损坏导致 readMemory 拿空记忆。（跨进程 last-writer-wins 仍在，但不再产生损坏缓存。）
+    const tmp = `${p}.${process.pid}.tmp`;
+    try {
+        fs.mkdirSync(memoryCacheDir(), { recursive: true });
+        fs.writeFileSync(tmp, JSON.stringify({
+            selfId: mem.selfId,
+            selfName: mem.selfName,
+            updatedAt: new Date().toISOString(),
+            lastCacheCheck: mem.lastCacheCheck || null,
+            available: mem.available !== false,
+            user: mem.user || {},
+            shortcuts: mem.shortcuts || {},
+            fieldDefaults: mem.fieldDefaults || {},
+            autoSubmit: mem.autoSubmit || [],
+            formCache: mem.formCache || {},
+            workflowListCache: mem.workflowListCache || {},
+        }, null, 2) + '\n', 'utf8');
+        fs.renameSync(tmp, p);
+    } catch {
+        // 写失败不阻断业务；顺带清理可能残留的临时文件
+        try { fs.rmSync(tmp, { force: true }); } catch { /* 清理失败忽略 */ }
+    }
+}
+
+/** 空记忆模板。 */
+function emptyMemory(selfId, selfName) {
+    return {
+        selfId, selfName, updatedAt: '', lastCacheCheck: null,
+        available: true,
+        user: {},
+        shortcuts: {}, fieldDefaults: {}, autoSubmit: [],
+        formCache: {},
+        workflowListCache: {},
+    };
+}
+
+/**
+ * 加载当前用户的记忆（带 selfId 解析）。
+ * 返回 { mem, selfId, selfName }。
+ */
+export async function loadMemory(cfg) {
+    let selfId = '';
+    let selfName = '';
+    try {
+        const u = await getCurrentUser(cfg);
+        selfId = String(u?.userid ?? '');
+        selfName = String(u?.username ?? '');
+    } catch { /* 走 cookie 兜底 */ }
+    if (!selfId) selfId = parseUserIdFromCookie(cfg?.cookie);
+    if (!selfId) {
+        return { mem: emptyMemory('', ''), selfId: '', selfName: '' };
+    }
+    const mem = readMemory(cfg, selfId);
+    mem.selfName = selfName || mem.selfName;
+
+    // ★ 后台缓存巡检：24h 内未检查过则异步触发（fire-and-forget，不阻塞当前命令）
+    const now = Date.now();
+    const lastCheck = mem.lastCacheCheck ? new Date(mem.lastCacheCheck).getTime() : 0;
+    if (now - lastCheck >= CACHE_CHECK_INTERVAL_MS) {
+        const shortcuts = Object.keys(mem.shortcuts || {});
+        if (shortcuts.length > 0) {
+            // 不 await——后台静默跑完，下次命令就能用新鲜缓存
+            refreshStaleFormCaches(cfg, selfId).catch(() => {});
+        }
+    }
+
+    return { mem, selfId, selfName };
+}
+
+// ─── 快捷方式（别名→工作流映射）────────────────
+
+/**
+ * 保存一个快捷方式。
+ */
+export function saveShortcut(cfg, selfId, selfName, keyword, workflowId, workflowName) {
+    const mem = readMemory(cfg, selfId);
+    const existing = mem.shortcuts[keyword];
+    mem.shortcuts[keyword] = {
+        workflowId: String(workflowId),
+        workflowName: workflowName || existing?.workflowName || '',
+        hitCount: (existing?.hitCount || 0) + 1,
+        lastUsed: new Date().toISOString(),
+        createdAt: existing?.createdAt || new Date().toISOString(),
+    };
+    mem.selfName = selfName || mem.selfName;
+    writeMemory(cfg, mem);
+    return mem.shortcuts[keyword];
+}
+
+/**
+ * 查找快捷方式（精确匹配关键词）。
+ */
+export function findShortcut(cfg, selfId, keyword) {
+    const mem = readMemory(cfg, selfId);
+    return mem.shortcuts[keyword] || null;
+}
+
+// ─── 模糊匹配 ──────────────────────────────────
+
+/**
+ * 编辑距离（Levenshtein）。
+ * 阈值：≤1 认为可匹配（"请假"↔"休假" 距离=1，"请假"↔"请个假" 距离=1）。
+ * >1 的不认（"打卡"↔"请假" 距离=2 不匹配）。
+ */
+function levenshtein(a, b) {
+    const m = a.length, n = b.length;
+    if (m === 0) return n;
+    if (n === 0) return m;
+    let prev = Array.from({ length: n + 1 }, (_, j) => j);
+    let curr = new Array(n + 1);
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            curr[j] = a[i - 1] === b[j - 1] ? prev[j - 1] : 1 + Math.min(prev[j], curr[j - 1], prev[j - 1]);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}
+
+/** 去除常见后缀，提高匹配召回率。 */
+const COMMON_SUFFIXES = ['流程', '申请', '单', '审批', '表'];
+
+function stripCommonSuffixes(s) {
+    let result = s;
+    for (const suffix of COMMON_SUFFIXES) {
+        if (result.endsWith(suffix) && result.length > suffix.length + 1) {
+            result = result.slice(0, -suffix.length);
+        }
+    }
+    return result;
+}
+
+/**
+ * 规范化关键词（小写、去空格、去常见后缀）。
+ */
+function normalizeKeyword(kw) {
+    return stripCommonSuffixes(kw.trim().toLowerCase()).trim();
+}
+
+/**
+ * 模糊查找快捷方式。
+ *
+ * 匹配策略（按优先级）：
+ *   1. 精确匹配 → 直接返回
+ *   2. 规范化精确匹配（去空格去后缀）→ 返回
+ *   3. 规范化后互相包含（"请个假" contains "请假"）→ 返回
+ *   4. 编辑距离 ≤2 → 返回
+ *   5. 都不命中 → 返回 null
+ *
+ * 多候选时按 hitCount 降序、lastUsed 降序取最佳。
+ *
+ * @returns {{ shortcut, matchedBy: 'exact'|'normalized'|'contains'|'fuzzy', keyword: string } | null}
+ */
+export function findShortcutFuzzy(cfg, selfId, keyword) {
+    const mem = readMemory(cfg, selfId);
+    const keys = Object.keys(mem.shortcuts);
+    if (keys.length === 0) return null;
+
+    const input = (keyword || '').trim();
+    if (!input) return null;
+
+    // 1. 精确匹配
+    const exact = mem.shortcuts[input];
+    if (exact) return { shortcut: exact, matchedBy: 'exact', keyword: input };
+
+    const inputNorm = normalizeKeyword(input);
+
+    // 2. 规范化精确匹配
+    for (const key of keys) {
+        if (normalizeKeyword(key) === inputNorm) {
+            return { shortcut: mem.shortcuts[key], matchedBy: 'normalized', keyword: key };
+        }
+    }
+
+    // 3. 规范化后互相包含
+    const containsMatches = [];
+    for (const key of keys) {
+        const keyNorm = normalizeKeyword(key);
+        if (keyNorm && inputNorm && (inputNorm.includes(keyNorm) || keyNorm.includes(inputNorm))) {
+            containsMatches.push({ key, s: mem.shortcuts[key] });
+        }
+    }
+    if (containsMatches.length === 1) {
+        return { shortcut: containsMatches[0].s, matchedBy: 'contains', keyword: containsMatches[0].key };
+    }
+    if (containsMatches.length > 1) {
+        containsMatches.sort((a, b) => {
+            const hc = (b.s.hitCount || 0) - (a.s.hitCount || 0);
+            if (hc !== 0) return hc;
+            return new Date(b.s.lastUsed || 0).getTime() - new Date(a.s.lastUsed || 0).getTime();
+        });
+        return { shortcut: containsMatches[0].s, matchedBy: 'contains', keyword: containsMatches[0].key };
+    }
+
+    // 4. 编辑距离 ≤1
+    const fuzzyMatches = [];
+    for (const key of keys) {
+        const keyNorm = normalizeKeyword(key);
+        if (keyNorm && inputNorm) {
+            const dist = levenshtein(inputNorm, keyNorm);
+            if (dist <= 1) fuzzyMatches.push({ key, s: mem.shortcuts[key], dist });
+        }
+    }
+    if (fuzzyMatches.length > 0) {
+        fuzzyMatches.sort((a, b) => a.dist - b.dist || (b.s.hitCount || 0) - (a.s.hitCount || 0));
+        return { shortcut: fuzzyMatches[0].s, matchedBy: 'fuzzy', keyword: fuzzyMatches[0].key };
+    }
+
+    return null;
+}
+
+/**
+ * 记录快捷方式命中（更新 hitCount + lastUsed）。
+ * keyword 必须是用 findShortcutFuzzy 返回的 keyword（存储的实际 key），
+ * 否则模糊匹配的命中可能写入错误的键。
+ */
+export function hitShortcut(cfg, selfId, keyword) {
+    const mem = readMemory(cfg, selfId);
+    const s = mem.shortcuts[keyword];
+    if (!s) return;
+    s.hitCount = (s.hitCount || 0) + 1;
+    s.lastUsed = new Date().toISOString();
+    mem.updatedAt = new Date().toISOString();
+    writeMemory(cfg, mem);
+}
+
+/** 快捷方式清理默认阈值：90 天未使用。 */
+export const SHORTCUT_EXPIRY_DAYS = 90;
+
+/**
+ * 清理过期快捷方式（超过 maxAgeDays 天未使用）。
+ * 返回清理掉的快捷方式列表（供展示）。
+ */
+export function cleanupShortcuts(cfg, selfId, maxAgeDays = SHORTCUT_EXPIRY_DAYS) {
+    const mem = readMemory(cfg, selfId);
+    const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+    const removed = [];
+    for (const [keyword, s] of Object.entries(mem.shortcuts)) {
+        const lastUsed = new Date(s.lastUsed || s.createdAt || 0).getTime();
+        if (lastUsed < cutoff) {
+            removed.push({ keyword, workflowId: s.workflowId, workflowName: s.workflowName, lastUsed: s.lastUsed });
+            delete mem.shortcuts[keyword];
+        }
+    }
+    if (removed.length > 0) {
+        writeMemory(cfg, mem);
+    }
+    return removed;
+}
+
+/**
+ * 查找过期快捷方式（不删除，仅列出）。
+ */
+export function findExpiredShortcuts(cfg, selfId, maxAgeDays = SHORTCUT_EXPIRY_DAYS) {
+    const mem = readMemory(cfg, selfId);
+    const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+    const expired = [];
+    for (const [keyword, s] of Object.entries(mem.shortcuts)) {
+        const lastUsed = new Date(s.lastUsed || s.createdAt || 0).getTime();
+        if (lastUsed < cutoff) {
+            expired.push({ keyword, workflowId: s.workflowId, workflowName: s.workflowName, lastUsed: s.lastUsed, hitCount: s.hitCount });
+        }
+    }
+    return expired.sort((a, b) => new Date(a.lastUsed || 0).getTime() - new Date(b.lastUsed || 0).getTime());
+}
+
+/**
+ * 删除快捷方式。
+ */
+export function forgetShortcut(cfg, selfId, keyword) {
+    const mem = readMemory(cfg, selfId);
+    if (!mem.shortcuts[keyword]) return false;
+    delete mem.shortcuts[keyword];
+    writeMemory(cfg, mem);
+    return true;
+}
+
+// ─── 字段默认值（工作流维度）───────────────
+
+/** 值历史最大保留条数。 */
+const MAX_VALUE_HISTORY = 10;
+
+/**
+ * 保存字段默认值（同时更新值频率历史）。
+ * history 按使用频次降序排列，最多保留 MAX_VALUE_HISTORY 条。
+ */
+export function saveFieldDefault(cfg, selfId, selfName, workflowId, fieldId, label, value) {
+    const mem = readMemory(cfg, selfId);
+    if (!mem.fieldDefaults[workflowId]) mem.fieldDefaults[workflowId] = {};
+    const entry = mem.fieldDefaults[workflowId][fieldId] || {};
+    const now = new Date().toISOString();
+
+    // 更新频率历史
+    const history = Array.isArray(entry.history) ? [...entry.history] : [];
+    const existing = history.find(h => h.value === value);
+    if (existing) {
+        existing.count += 1;
+        existing.lastUsed = now;
+    } else {
+        history.push({ value, count: 1, firstUsed: now, lastUsed: now });
+    }
+    // 按使用频次降序，截断
+    history.sort((a, b) => b.count - a.count || new Date(b.lastUsed).getTime() - new Date(a.lastUsed).getTime());
+    if (history.length > MAX_VALUE_HISTORY) history.length = MAX_VALUE_HISTORY;
+
+    mem.fieldDefaults[workflowId][fieldId] = {
+        label: label || entry.label || '',
+        default: value,
+        savedAt: now,
+        history,
+    };
+    mem.selfName = selfName || mem.selfName;
+    writeMemory(cfg, mem);
+}
+
+/**
+ * 获取某流程的字段默认值（向后兼容：返回 {label, default, savedAt, history?}）。
+ */
+export function getFieldDefaults(cfg, selfId, workflowId) {
+    const mem = readMemory(cfg, selfId);
+    return mem.fieldDefaults[workflowId] || {};
+}
+
+/**
+ * 获取某字段的值频率历史（按使用次数降序）。
+ * 返回 [{value, count, firstUsed, lastUsed}] 或 []（无历史时回退到单个 default 值）。
+ */
+export function getFieldValueHistory(cfg, selfId, workflowId, fieldId) {
+    const defaults = getFieldDefaults(cfg, selfId, workflowId);
+    const entry = defaults[fieldId];
+    if (!entry) return [];
+    if (Array.isArray(entry.history) && entry.history.length > 0) {
+        return entry.history;
+    }
+    // v1 兼容：无 history 时用 default 值构造单条历史
+    if (entry.default !== undefined && entry.default !== '') {
+        return [{ value: String(entry.default), count: 1, lastUsed: entry.savedAt }];
+    }
+    return [];
+}
+
+// ─── 自动提交 ──────────────────────────────────
+
+export function setAutoSubmit(cfg, selfId, keyword, enabled) {
+    const mem = readMemory(cfg, selfId);
+    if (enabled && !mem.autoSubmit.includes(keyword)) {
+        mem.autoSubmit.push(keyword);
+    } else if (!enabled) {
+        mem.autoSubmit = mem.autoSubmit.filter(k => k !== keyword);
+    }
+    writeMemory(cfg, mem);
+}
+
+// ─── 清空 ──────────────────────────────────────
+
+export function clearMemory(cfg, selfId) {
+    try {
+        const p = memoryCachePath(cfg, selfId);
+        if (fs.existsSync(p)) fs.unlinkSync(p);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+// ─── 表单结构缓存 ──────────────────────────────
+
+/** 表单缓存默认 TTL：30 天（毫秒）。 */
+export const FORM_CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * 表单缓存结构版本。递增后旧缓存一律失效重拉：
+ * v2 起缓存 linkageCfg（公式/联动），旧缓存可能缺少后来新增的公式配置。
+ */
+export const FORM_CACHE_SCHEMA_VERSION = 2;
+
+/**
+ * 计算表单字段级签名（供后台巡检对比）。
+ *
+ * 只比 totalFields 数量检测不到「字段数不变但属性变」（改 label/htmltype/isedit/isview/viewattr）。
+ * 签名覆盖每个字段的可编辑性与类型属性，字段数量或任一属性变化即产生不同签名。
+ * 字段顺序无关（loadForm 返回顺序可能变化），FNV-1a 32 位哈希十六进制。
+ */
+export function computeFormSignature(tables) {
+    if (!Array.isArray(tables)) return '';
+    const parts = [];
+    for (const t of tables) {
+        for (const fld of (t?.fields ?? [])) {
+            parts.push([
+                String(fld?.id ?? ''),
+                String(fld?.htmltype ?? ''),
+                String(fld?.isonlyshow ?? ''),
+                String(fld?.isedit ?? ''),
+                String(fld?.isview ?? ''),
+                String(fld?.viewattr ?? ''),
+                String(fld?.name ?? ''),
+            ].join('|'));
+        }
+    }
+    parts.sort();
+    const s = parts.join('~');
+    let h = 0;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = (h * 0x01000193) >>> 0;
+    }
+    return h.toString(36);
+}
+
+export function cacheFormFields(cfg, selfId, workflowId, formData) {
+    try {
+        const mem = readMemory(cfg, selfId);
+        if (!mem.formCache) mem.formCache = {};
+        const now = new Date().toISOString();
+        mem.formCache[String(workflowId)] = {
+            schemaVersion: FORM_CACHE_SCHEMA_VERSION,
+            cachedAt: now,
+            lastValidatedAt: now,
+            workflowName: formData.workflowName,
+            tables: formData.tables,
+            totalFields: formData.totalFields,
+            verifyRight: formData.verifyRight,
+            submitParams: formData.submitParams,
+            params: formData.params,
+            linkageCfg: formData.raw?.linkageCfg,
+            formSignature: computeFormSignature(formData.tables),
+        };
+        writeMemory(cfg, mem);
+    } catch { /* 写失败不阻断业务 */ }
+}
+
+export function getCachedFormFields(cfg, selfId, workflowId, maxAgeMs = FORM_CACHE_TTL_MS) {
+    try {
+        const mem = readMemory(cfg, selfId);
+        const entry = mem.formCache?.[String(workflowId)];
+        if (!entry) return null;
+        if (Number(entry.schemaVersion) !== FORM_CACHE_SCHEMA_VERSION) return null;
+        if (Date.now() - new Date(entry.cachedAt).getTime() > maxAgeMs) return null;
+        return entry;
+    } catch {
+        return null;
+    }
+}
+
+export function clearFormCache(cfg, selfId, workflowId) {
+    const mem = readMemory(cfg, selfId);
+    if (!mem.formCache?.[String(workflowId)]) return false;
+    delete mem.formCache[String(workflowId)];
+    writeMemory(cfg, mem);
+    return true;
+}
+
+// ─── 字段映射缓存（formCache 便捷访问）─────────
+
+/**
+ * 从缓存的表单结构中构建字段查找映射。
+ *
+ * 内部调 getCachedFormFields，复用其 TTL；过期/缺失/无 tables 时返回 null。
+ *
+ * @returns {{ byName: Map<string, object>, byId: Map<string, object> } | null}
+ */
+export function getCachedFieldMap(cfg, selfId, workflowId, maxAgeMs = FORM_CACHE_TTL_MS) {
+    try {
+        const entry = getCachedFormFields(cfg, selfId, workflowId, maxAgeMs);
+        if (!entry || !Array.isArray(entry.tables) || entry.tables.length === 0) return null;
+        const byName = new Map();
+        const byId = new Map();
+        for (const table of entry.tables) {
+            if (!Array.isArray(table.fields)) continue;
+            for (const f of table.fields) {
+                if (f.id) byId.set(f.id, f);
+                if (f.name) byName.set(f.name, f);
+            }
+        }
+        return { byName, byId };
+    } catch {
+        return null;
+    }
+}
+
+// ─── 浏览框选项缓存（formCache 子模块）─────────
+
+/**
+ * 浏览框选项缓存 TTL：24 小时。
+ * 选项（组织架构/人员/成本中心等）变动频率远高于表单结构，不能用 30 天——长时间 TTL 会拿到
+ * 已离职人员、已撤销部门的选项。与表单结构（FORM_CACHE_TTL_MS=30天）分离。
+ */
+export const BROWSE_OPTIONS_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * 缓存某流程某字段的浏览框选项（id+name 对）。
+ * 浏览框选项极少变化，与表单结构共享 TTL。
+ */
+export function cacheBrowseOptions(cfg, selfId, workflowId, fieldId, options) {
+    try {
+        const mem = readMemory(cfg, selfId);
+        if (!mem.formCache) mem.formCache = {};
+        const wf = mem.formCache[String(workflowId)] || (mem.formCache[String(workflowId)] = { cachedAt: new Date().toISOString() });
+        if (!wf.browseOptions) wf.browseOptions = {};
+        wf.browseOptions[String(fieldId)] = {
+            cachedAt: new Date().toISOString(),
+            options: options.map(o => ({ id: o.id, name: o.name })),
+        };
+        writeMemory(cfg, mem);
+    } catch { /* 写失败不阻断业务 */ }
+}
+
+/**
+ * 取缓存的浏览框选项。返回 [{id, name}] 或 null（未缓存/过期）。
+ * 默认 24 小时 TTL（BROWSE_OPTIONS_CACHE_TTL_MS）——比表单结构短，选项变动更频繁。
+ */
+export function getCachedBrowseOptions(cfg, selfId, workflowId, fieldId, maxAgeMs = BROWSE_OPTIONS_CACHE_TTL_MS) {
+    try {
+        const mem = readMemory(cfg, selfId);
+        const entry = mem.formCache?.[String(workflowId)]?.browseOptions?.[String(fieldId)];
+        if (!entry) return null;
+        if (Date.now() - new Date(entry.cachedAt).getTime() > maxAgeMs) return null;
+        return entry.options;
+    } catch {
+        return null;
+    }
+}
+
+// ─── 用户画像（三层之 user）───────────────────
+
+/**
+ * 设置记忆可用性（enable/disable）。
+ */
+export function setMemoryAvailable(cfg, selfId, enabled) {
+    const mem = readMemory(cfg, selfId);
+    mem.available = !!enabled;
+    writeMemory(cfg, mem);
+}
+
+/**
+ * 保存用户偏好。
+ * @param {string} key - 偏好键（如 communicationStyle / showRequestId）
+ * @param {*} value - 偏好值
+ */
+export function saveUserPreference(cfg, selfId, key, value) {
+    const mem = readMemory(cfg, selfId);
+    if (!mem.user) mem.user = {};
+    if (!mem.user.preferences) mem.user.preferences = {};
+    mem.user.preferences[key] = value;
+    writeMemory(cfg, mem);
+}
+
+/**
+ * 获取用户偏好。
+ */
+export function getUserPreferences(cfg, selfId) {
+    const mem = readMemory(cfg, selfId);
+    return mem.user?.preferences || {};
+}
+
+// ─── 列出 ─────────────────────────────────────
+
+/**
+ * 列出全部快捷方式（按 lastUsed 降序）。
+ */
+export function listShortcuts(cfg, selfId) {
+    const mem = readMemory(cfg, selfId);
+    return Object.entries(mem.shortcuts)
+        .map(([keyword, s]) => ({ keyword, ...s }))
+        .sort((a, b) => new Date(b.lastUsed || 0).getTime() - new Date(a.lastUsed || 0).getTime());
+}
+
+// ─── 工作流列表缓存 ────────────────────────────
+
+/** 工作流列表缓存 TTL：1 天（比表单结构短，新增/权限变更需较快生效）。 */
+export const WORKFLOW_LIST_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * 缓存新建流程列表（按 tab 分键）。
+ * categories: [{id, name, workflows: [{id, name, typeId, ...}]}]
+ */
+export function cacheWorkflowList(cfg, selfId, tab, categories) {
+    try {
+        const mem = readMemory(cfg, selfId);
+        if (!mem.workflowListCache) mem.workflowListCache = {};
+        mem.workflowListCache[String(tab)] = {
+            cachedAt: new Date().toISOString(),
+            categories,
+        };
+        writeMemory(cfg, mem);
+    } catch { /* 写失败不阻断 */ }
+}
+
+/**
+ * 取缓存的工作流列表。返回 categories 或 null。
+ */
+export function getCachedWorkflowList(cfg, selfId, tab, maxAgeMs = WORKFLOW_LIST_CACHE_TTL_MS) {
+    try {
+        const mem = readMemory(cfg, selfId);
+        const entry = mem.workflowListCache?.[String(tab)];
+        if (!entry) return null;
+        if (Date.now() - new Date(entry.cachedAt).getTime() > maxAgeMs) return null;
+        return entry.categories;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * 按名在缓存的工作流列表中查找（客户端过滤，不走 API）。
+ * 返回 [{id, name, ...}] 或 null（缓存未命中）。
+ */
+export function findWorkflowByNameInCache(categories, name) {
+    if (!categories || !name) return null;
+    const kw = name.trim().toLowerCase();
+    const hits = [];
+    for (const c of categories) {
+        for (const w of c.workflows || []) {
+            if ((w.name || '').toLowerCase().includes(kw)) {
+                hits.push(w);
+            }
+        }
+    }
+    return hits.length > 0 ? hits : null;
+}
+
+/**
+ * 清除工作流列表缓存。
+ */
+export function clearWorkflowListCache(cfg, selfId, tab) {
+    const mem = readMemory(cfg, selfId);
+    if (!mem.workflowListCache) return false;
+    if (tab) {
+        if (!mem.workflowListCache[String(tab)]) return false;
+        delete mem.workflowListCache[String(tab)];
+    } else {
+        mem.workflowListCache = {};
+    }
+    writeMemory(cfg, mem);
+    return true;
+}
+
+// ─── 导出/导入（跨环境迁移）─────────────────────
+
+/**
+ * 导出当前用户完整记忆（JSON 字符串，可直接写文件或 stdout）。
+ * 包含：shortcuts、fieldDefaults、autoSubmit、formCache、workflowListCache、user.preferences。
+ */
+export function exportMemory(cfg, selfId) {
+    const mem = readMemory(cfg, selfId);
+    const exportData = {
+        exportedAt: new Date().toISOString(),
+        selfId: mem.selfId,
+        selfName: mem.selfName,
+        shortcuts: mem.shortcuts || {},
+        fieldDefaults: mem.fieldDefaults || {},
+        autoSubmit: mem.autoSubmit || [],
+        formCache: mem.formCache || {},
+        workflowListCache: mem.workflowListCache || {},
+        user: mem.user || {},
+    };
+    return JSON.stringify(exportData, null, 2);
+}
+
+/**
+ * 导入记忆（合并模式：已有保留，新增加入）。返回 { addedShortcuts, addedFields, skippedShortcuts }。
+ * input 为 JSON 字符串（exportMemory 的输出格式）。
+ */
+export function importMemory(cfg, selfId, selfName, input) {
+    let importData;
+    try {
+        importData = JSON.parse(input);
+    } catch (e) {
+        throw new Error(`导入文件 JSON 解析失败: ${e.message}`);
+    }
+    if (!importData || typeof importData !== 'object') {
+        throw new Error('导入文件格式不正确');
+    }
+
+    const mem = readMemory(cfg, selfId);
+    const addedShortcuts = [];
+    const skippedShortcuts = [];
+    let addedFields = 0;
+
+    // 1. 合并快捷方式：已有保留，只加新的
+    for (const [keyword, s] of Object.entries(importData.shortcuts || {})) {
+        if (mem.shortcuts[keyword]) {
+            skippedShortcuts.push(keyword);
+        } else {
+            mem.shortcuts[keyword] = {
+                ...s,
+                createdAt: s.createdAt || importData.exportedAt || new Date().toISOString(),
+                lastUsed: null, // 导入的不算使用过
+                hitCount: 0,
+            };
+            addedShortcuts.push(keyword);
+        }
+    }
+
+    // 2. 合并字段默认值：逐字段合并，已有保留
+    for (const [wfId, fields] of Object.entries(importData.fieldDefaults || {})) {
+        if (!mem.fieldDefaults[wfId]) mem.fieldDefaults[wfId] = {};
+        for (const [fieldId, f] of Object.entries(fields)) {
+            if (!mem.fieldDefaults[wfId][fieldId]) {
+                mem.fieldDefaults[wfId][fieldId] = f;
+                addedFields++;
+            }
+        }
+    }
+
+    // 3. 合并自动提交：已有关键字保留，新关键字加入
+    const existingAuto = new Set(mem.autoSubmit || []);
+    if (Array.isArray(importData.autoSubmit)) {
+        for (const k of importData.autoSubmit) {
+            if (!existingAuto.has(k)) {
+                (mem.autoSubmit || (mem.autoSubmit = [])).push(k);
+                existingAuto.add(k);
+            }
+        }
+    }
+
+    // 4. 合并用户偏好：已有保留，新 key 加入
+    const existingPrefs = mem.user?.preferences || {};
+    const importPrefs = importData.user?.preferences || {};
+    for (const [k, v] of Object.entries(importPrefs)) {
+        if (!(k in existingPrefs)) {
+            if (!mem.user) mem.user = {};
+            if (!mem.user.preferences) mem.user.preferences = {};
+            mem.user.preferences[k] = v;
+        }
+    }
+
+    // 5. formCache / workflowListCache 不合并——环境不同表单结构可能不同，保留现有
+
+    mem.updatedAt = new Date().toISOString();
+    writeMemory(cfg, mem);
+    return { addedShortcuts, addedFields, skippedShortcuts };
+}
+
+// ─── 联动字段结果缓存 ──────────────────────────
+
+/** 联动结果缓存 TTL：1 小时（毫秒）。联动数据（组织架构/成本中心等）有变化可能性。 */
+export const LINKAGE_CACHE_TTL_MS = 60 * 60 * 1000;
+
+/** 单流程联动缓存最大条目数。key 含字段值，组合几乎每次不同，无上限会无限膨胀。 */
+export const MAX_LINKAGE_CACHE_ENTRIES = 200;
+
+/**
+ * 缓存联动解析结果。
+ * key 由 workflowId + configId + triggerFieldId + triggerValue 组成，确保相同输入直接命中。
+ *
+ * ★ 淘汰：写入前先清 TTL 已过期的条目，再超上限删最旧——防止缓存文件随字段值组合无限增长
+ *   （旧实现只按 TTL 读不删，过期条目永久残留，整文件每次 stringify/parse 越来越慢）。
+ */
+export function cacheLinkageResult(cfg, selfId, workflowId, configId, triggerFieldId, triggerValue, changeValue) {
+    try {
+        const mem = readMemory(cfg, selfId);
+        if (!mem.formCache) mem.formCache = {};
+        if (!mem.formCache[String(workflowId)]) mem.formCache[String(workflowId)] = {};
+        if (!mem.formCache[String(workflowId)].linkageResults) {
+            mem.formCache[String(workflowId)].linkageResults = {};
+        }
+        const lr = mem.formCache[String(workflowId)].linkageResults;
+        // 1. 清过期（TTL 内的才可能被复用）
+        const now = Date.now();
+        for (const [k, entry] of Object.entries(lr)) {
+            if (now - new Date(entry.cachedAt).getTime() > LINKAGE_CACHE_TTL_MS) delete lr[k];
+        }
+        // 2. 仍超上限则删最旧（留出一个空位给新条目）
+        const entries = Object.entries(lr);
+        if (entries.length >= MAX_LINKAGE_CACHE_ENTRIES) {
+            entries.sort((a, b) => new Date(a[1].cachedAt).getTime() - new Date(b[1].cachedAt).getTime());
+            const toRemove = entries.length - MAX_LINKAGE_CACHE_ENTRIES + 1;
+            for (let i = 0; i < toRemove; i++) delete lr[entries[i][0]];
+        }
+        const key = `${configId}:${triggerFieldId}:${triggerValue}`;
+        lr[key] = {
+            cachedAt: new Date().toISOString(),
+            changeValue,
+        };
+        writeMemory(cfg, mem);
+    } catch { /* 写失败不阻断 */ }
+}
+
+/**
+ * 取缓存的联动结果。返回 changeValue 或 null。
+ */
+export function getCachedLinkageResult(cfg, selfId, workflowId, configId, triggerFieldId, triggerValue, maxAgeMs = LINKAGE_CACHE_TTL_MS) {
+    try {
+        const mem = readMemory(cfg, selfId);
+        const key = `${configId}:${triggerFieldId}:${triggerValue}`;
+        const entry = mem.formCache?.[String(workflowId)]?.linkageResults?.[key];
+        if (!entry) return null;
+        if (Date.now() - new Date(entry.cachedAt).getTime() > maxAgeMs) return null;
+        return entry.changeValue;
+    } catch {
+        return null;
+    }
+}
+
+// ─── 后台缓存刷新（自动巡检）────────────────────
+
+/** 两次全量缓存检查的最小间隔（24 小时）。 */
+export const CACHE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * 后台巡检所有 shortcut 对应流程的表单缓存，有变化自动更新。
+ *
+ * - 距上次全量检查 > CACHE_CHECK_INTERVAL_MS 才执行
+ * - 逐个流程调 describeFormFields 对比 totalFields，不同则更新缓存
+ * - 无变化则只更新 lastValidatedAt
+ * - 异步执行、静默完成，调用方不应 await（fire-and-forget）
+ *
+ * 返回 { checked, updated, errors, details } 供 CLI manual refresh 展示。
+ */
+export async function refreshStaleFormCaches(cfg, selfId) {
+    const result = { checked: 0, updated: 0, errors: 0, details: [] };
+    try {
+        const mem = readMemory(cfg, selfId);
+        const now = Date.now();
+
+        // 节流：24h 内已经检查过则跳过
+        if (mem.lastCacheCheck) {
+            const lastCheck = new Date(mem.lastCacheCheck).getTime();
+            if (now - lastCheck < CACHE_CHECK_INTERVAL_MS) {
+                return result;
+            }
+        }
+
+        // 收集所有 shortcut 对应的 workflowId（去重）
+        const wfIds = [...new Set(Object.values(mem.shortcuts || {}).map(s => s.workflowId).filter(Boolean))];
+        if (wfIds.length === 0) {
+            mem.lastCacheCheck = new Date().toISOString();
+            writeMemory(cfg, mem);
+            return result;
+        }
+
+        // 动态导入避免循环依赖
+        const { describeFormFields } = await import('./wfform.js');
+
+        for (const wfId of wfIds) {
+            const cached = mem.formCache?.[String(wfId)];
+            if (!cached) continue;
+            const lastValidated = new Date(cached.lastValidatedAt || cached.cachedAt || 0).getTime();
+            if (now - lastValidated < CACHE_CHECK_INTERVAL_MS) continue;
+
+            result.checked++;
+            try {
+                const fresh = await describeFormFields(cfg, wfId);
+                if (fresh.verifyRight === false) {
+                    result.details.push({ workflowId: wfId, name: cached.workflowName, status: 'no-right' });
+                    continue;
+                }
+                // ★ 对比字段级签名（不只 totalFields）：字段数不变但改 label/htmltype/isedit/isview/viewattr 也能检出。
+                //   老缓存无签名时用自身 tables 现算，保证旧文件也能被升级。
+                const freshSig = computeFormSignature(fresh.tables);
+                const cachedSig = cached.formSignature || computeFormSignature(cached.tables);
+                const changed = fresh.totalFields !== cached.totalFields
+                    || (freshSig && cachedSig && freshSig !== cachedSig);
+                if (changed) {
+                    mem.formCache[String(wfId)] = {
+                        ...cached,
+                        cachedAt: new Date().toISOString(),
+                        lastValidatedAt: new Date().toISOString(),
+                        tables: fresh.tables,
+                        totalFields: fresh.totalFields,
+                        verifyRight: fresh.verifyRight,
+                        submitParams: fresh.submitParams,
+                        params: fresh.params,
+                        linkageCfg: fresh.raw?.linkageCfg,
+                        formSignature: freshSig,
+                    };
+                    result.updated++;
+                    result.details.push({ workflowId: wfId, name: cached.workflowName, status: 'updated',
+                        oldCount: cached.totalFields, newCount: fresh.totalFields });
+                } else {
+                    mem.formCache[String(wfId)].lastValidatedAt = new Date().toISOString();
+                    mem.formCache[String(wfId)].formSignature = cachedSig; // 升级老缓存签名
+                    result.details.push({ workflowId: wfId, name: cached.workflowName, status: 'ok' });
+                }
+            } catch (e) {
+                result.errors++;
+                result.details.push({ workflowId: wfId, name: cached?.workflowName || wfId, status: 'error', error: e.message });
+            }
+        }
+
+        mem.lastCacheCheck = new Date().toISOString();
+        writeMemory(cfg, mem);
+    } catch { /* 巡检失败不阻断任何业务 */ }
+    return result;
+}