ai-helper-agent 2.2.0 → 2.3.1

package/src/memory/tags.js

@@ -0,0 +1,62 @@
+// agent/src/memory/tags.js - 标签在记忆检索里的角色（单一来源）
+//
+// 2026-10-14 口径变更（用户定的检索取向）：tags 从「打分前的硬过滤」降为「名次加成」。
+// 原缺陷：标签过滤发生在任何打分之前，于是它与「词面命中门槛」「语义地板」构成三个硬门槛的
+// AND 叠加——一条内容正确、语义也正确的记忆，只因为没打上请求里的标签就被整条抹掉。
+// 现在的分工：
+//   1) 有 query 时标签不再剔除候选，只按重叠比例把条目往上抬有限几名（见 applyTagRankLift）；
+//   2) 无 query 时标签是唯一选择器，属枚举语义，保持硬过滤（见 filterByTags 的调用方）；
+//   3) 本模块不得参与词面通道的 df 统计池：df 的判据是 `d > 0 && d <= limit`，一个只出现在
+//      非标签条目里的词在标签子集上 d 为 undefined 会被直接拒——那等于新方案想捞回的条目
+//      只能靠与标签子集共享的词才能命中，跟硬过滤差不了多少。df 继续走全候选池（已标定口径）。
+
+/**
+ * 全量标签命中最多上抬的名次数。
+ * 1 位太弱（几乎抬不动），3 位以上接近「标签命中一律排前」——那正是本次要避免的形态。
+ */
+export const TAG_RANK_LIFT = 2;
+
+/** 标签大小写/空白不敏感，与迁移前的比较口径保持一致 */
+function normalizeTag(value) {
+  return String(value ?? '').trim().toLowerCase();
+}
+
+/** 调用方是否提出了标签请求（非数组、空数组都视为没有） */
+export function hasTagRequest(requestedTags) {
+  return Array.isArray(requestedTags) && requestedTags.length > 0;
+}
+
+/**
+ * 重叠比例：命中的请求标签数 / 请求标签总数，值域 [0,1]。
+ * 分母取请求数而不是命中数，这样「请求三个只中一个」弱于「请求三个中三个」。
+ */
+export function tagOverlapRatio(memoryTags, requestedTags) {
+  const requested = (Array.isArray(requestedTags) ? requestedTags : []).map(normalizeTag).filter(Boolean);
+  const owned = new Set((Array.isArray(memoryTags) ? memoryTags : []).map(normalizeTag).filter(Boolean));
+  if (requested.length === 0 || owned.size === 0) return 0;
+  let hits = 0;
+  for (const tag of requested) if (owned.has(tag)) hits += 1;
+  return hits / requested.length;
+}
+
+/** 标签至少沾一个才算命中（与迁移前的 some() 语义逐字等价） */
+export function filterByTags(candidates = [], requestedTags) {
+  // 无标签请求时返回全量而不是空集：调用方一旦漏了前置判断，也不能把整个结果集抹掉
+  if (!hasTagRequest(requestedTags)) return candidates.slice();
+  return candidates.filter(m => tagOverlapRatio(m?.tags, requestedTags) > 0);
+}
+
+/**
+ * 按标签重叠比例上抬名次。输入必须是已经排好名的列表（词面单通道序或 RRF 融合序）。
+ * 不修改入参：调用方还要用原名次做别的判定。
+ */
+export function applyTagRankLift(ranked = [], requestedTags) {
+  if (!hasTagRequest(requestedTags)) return ranked.slice();
+  const moved = ranked.map((memory, index) => {
+    const lift = Math.round(TAG_RANK_LIFT * tagOverlapRatio(memory?.tags, requestedTags));
+    return { memory, index, lift, key: index - lift };
+  });
+  // 同 key 时优先被抬上来的那条：否则抬 1 位会与它让开的那条并列，按稳定序纹丝不动，加成等于没生效
+  moved.sort((a, b) => (a.key - b.key) || (b.lift - a.lift) || (a.index - b.index));
+  return moved.map(m => m.memory);
+}

package/src/memory/tier.js

@@ -0,0 +1,37 @@
+// agent/src/memory/tier.js - 记忆召回通道分级决策（纯函数，无 IO）
+// none = 只走关键词通道（与下推完成后的历史行为逐字一致，默认档）；
+// remote/local = 走双通道排名融合（关键词名次 + 语义名次，见 fusion.js）。
+// 判定只看配置 + RAG 依赖是否就位。本模块不管采信条件：逐条候选的绝对余弦阈值已被实测否定，
+// 采信规则单点在 fusion.js，不在这里留任何常量。
+
+/**
+ * 决定当前配置能用到哪一档召回通道。
+ * @param {object} cfg memoryEmbedding 配置（getMemoryEmbeddingConfig() 的形态）
+ * @param {boolean} ragAvailable 本地模型依赖（transformers/vectra）是否已安装
+ * @returns {'none'|'remote'|'local'}
+ */
+export function resolveMemoryTier(cfg = null, ragAvailable = false) {
+  const c = cfg || {};
+  // enabled 只认真 true：saveMemoryEmbeddingConfig 也按同一口径落盘
+  if (c.enabled !== true) return 'none';
+
+  if (c.mode === 'openai-compat') {
+    const hasKey = String(c.apiKey || '').trim().length > 0;
+    const hasModel = String(c.modelName || '').trim().length > 0;
+    // 远端模式不依赖 RAG 包，只要有端点配置就能开向量通道
+    return hasKey && hasModel ? 'remote' : 'none';
+  }
+
+  if (c.mode === 'local') {
+    // 本地模型需要 RAG 依赖；依赖缺失时静默降级，不报错、不提示（UI 侧自行展示当前档位）
+    // 取“真值”而非 === true：调用方是 isRagAvailable()（布尔），但允许包装层传回其它真值而不被误降级
+    return ragAvailable ? 'local' : 'none';
+  }
+
+  return 'none';
+}
+
+/** 是否需要计算/使用向量 */
+export function isVectorTier(tier) {
+  return tier === 'remote' || tier === 'local';
+}

package/src/memory/tokens.js

@@ -0,0 +1,158 @@
+// agent/src/memory/tokens.js - 记忆关键词通道的分词与计分（单一来源）
+//
+// 2026-10-13 口径变更：从「把 query 炸成最多 30 个碎 bigram、每个命中 +3」改为
+// 「最长命中片段的单元制」，并与知识库共用同一份匹配实现（rag/keyword-match.js）。
+// 变更动机（实测于真实记忆库，见 2026-10-13-memory-keyword-parity.md）：
+//   碎 bigram 下「写网」「个国」「我查」这类随机 2 字块几乎必然命中某些长条目，
+//   于是任何 query 都能捞回一堆无关记忆；且命中 4 个随机碎块（+12）高于命中一个
+//   4 字整词（+3），排序方向是反的。知识库侧 2026-09 已修掉这两点。
+// 停用词表随之删除：单元数按命中长度分层后，虚词无法单独构成足够长的片段，
+// 而两侧共用一份切段口径比记忆侧再叠一层词表更不容易漂移。
+
+import { extractQueryTerms, matchLatin, matchCjk, KEYWORD_MAX_HITS } from '../rag/keyword-match.js';
+
+/** 字段权重：正文 > 标题 = 标签（整数刻度，与向量分融合时同为「分」这一单位） */
+export const FIELD_WEIGHT = { content: 3, title: 2, tags: 2 };
+
+/** 整句原样命中的额外加分：正文 +5、标题 +3（沿用迁移前的权重） */
+export const ORIGINAL_QUERY_CONTENT_BONUS = 5;
+export const ORIGINAL_QUERY_TITLE_BONUS = 3;
+export const ORIGINAL_QUERY_MIN_LENGTH = 2;
+
+/** 高频单元剔除：与知识库同参数——命中过半条目的单元无区分度，df ≤ 2 恒保留 */
+export const KEYWORD_MAX_DF_RATIO = 0.5;
+export const KEYWORD_DF_EXEMPT = 2;
+
+/**
+ * 命中门槛：单元数 ≥ 2，或存在一个「完整单元」命中。
+ * 单元身份是**查询单元**（拉丁词 / 中文连续段），其单元数取它在任一字段里达到的最强值；
+ * 不得按字段累加——同一个 2 字片段在正文和标签各命中一次就凑出 2，会把这个门槛旁路掉（实测缺陷）。
+ * 实测于 Task 2 评测集（计划 Task 3 Step 3）：只看 score > 0 时 3 条零重叠查询仍会
+ * 捣回仅命中 2 字碎块的长条目；纯要求 units ≥ 2 能抹平噪声，但会把「单个英文词」
+ * 「单个 2 字中文词」这类短查询误杀。加 full 分支后两者兼得，10/10 全绿。
+ */
+export const KEYWORD_MIN_UNITS = 2;
+
+/** 参与词面匹配的字段面（也是参与 embedding 的字段面，两侧口径必须一致） */
+export function memorySearchText(m) {
+  return [m?.content, m?.title, (m?.tags || []).join(' ')].filter(Boolean).join('\n');
+}
+
+/** 逐字段文本（小写）：字段权重按此分别计算 */
+function fieldTexts(m) {
+  return {
+    content: String(m?.content || '').toLowerCase(),
+    title: String(m?.title || '').toLowerCase(),
+    tags: (m?.tags || []).join(' ').toLowerCase()
+  };
+}
+
+/** 查询拆段：拉丁整词 + 中文连续段（与知识库同一实现） */
+export function extractMemoryTerms(query) {
+  return extractQueryTerms(query);
+}
+
+/**
+ * 单字段内的逐查询单元命中明细：词边界拉丁命中 + 中文最长片段。
+ * unit 是稳定的单元身份（拉丁按词、中文按连续段），前缀 l:/c: 防止两种形态互相撞车；
+ * 它是**查询单元**而不是命中片段——按片段计会把「检索」「方案」两个随机 2 字块当成两个单元，
+ * 正是 2026-10-13 碎块噪声要消除的东西，所以这里不能改。
+ */
+function fieldUnitHits(text, terms, dfFilter) {
+  if (!text) return [];
+  const out = [];
+  for (const term of matchLatin(text, terms.latin)) {
+    if (!dfFilter(term)) continue;
+    // 拉丁命中本身就是整词命中（词边界已保证），不是碎块
+    out.push({ unit: 'l:' + term, units: 1, full: true });
+  }
+  for (const seg of terms.cjk) {
+    const hit = matchCjk(text, seg);
+    if (!hit || !hit.keys.some(k => dfFilter(k))) continue;
+    out.push({ unit: 'c:' + seg, units: hit.units, full: seg.length === hit.keys[0].length });
+  }
+  return out;
+}
+
+/**
+ * 构建文档频率过滤器：统计每个命中单元出现在多少条候选里，过半者判为无区分度。
+ * 必须在计分前对全候选扫一遍——单条记忆自身无法判断某词是否常见。
+ * @param {Array} candidates 本次召回的候选记忆
+ * @param {{latin: string[], cjk: string[]}} terms
+ * @returns {{keep: (key: string) => boolean, hasDiscriminative: boolean}}
+ *   keep 该单元是否具备区分度；hasDiscriminative 是否**至少有一个**单元具备区分度
+ *   （全塌信号：整个查询的词形区分度都不成立，调用方据此决定是否忽略 df）
+ */
+export function buildDocFreqFilter(candidates = [], terms = { latin: [], cjk: [] }) {
+  const df = new Map();
+  for (const m of candidates) {
+    const hay = memorySearchText(m).toLowerCase();
+    if (!hay) continue;
+    for (const term of matchLatin(hay, terms.latin)) df.set(term, (df.get(term) || 0) + 1);
+    for (const seg of terms.cjk) {
+      const hit = matchCjk(hay, seg);
+      if (hit) for (const k of hit.keys) df.set(k, (df.get(k) || 0) + 1);
+    }
+  }
+  const limit = Math.max(KEYWORD_DF_EXEMPT, candidates.length * KEYWORD_MAX_DF_RATIO);
+  // d > 0：未被任何候选碰过的单元不参与判定；d ≤ limit：过半者剔除
+  const keep = (key) => {
+    const d = df.get(key);
+    return d > 0 && d <= limit;
+  };
+  // 全塌判定：df 表里一个幸存单元都没有。df 的键只会在被某条候选碰到时才写入，所以 d > 0 恒成立，
+  // 这里等价于「有没有任何一个键没过 limit」。注意「查询词全库无人碰」也算全塌——那个词本来就不具备区分度。
+  let hasDiscriminative = false;
+  for (const d of df.values()) {
+    if (d <= limit) { hasDiscriminative = true; break; }
+  }
+  return { keep, hasDiscriminative };
+}
+
+/**
+ * 记忆关键词分：字段内命中单元和（封顶 KEYWORD_MAX_HITS）× 字段权重，跨字段累加；
+ * 另加整句原样命中分。
+ * 与旧实现的差别即本次变更的目的——碎块不再与整词等价，长命中不再被拆成多次加分。
+ * full 标识「命中了某个完整单元」（整个拉丁词或整个中文连续段），供调用方区分
+ * 「整词命中」与「只碰了 2 字碎块」——后者的分数必须过 KEYWORD_MIN_UNITS 门槛才能算命中。
+ * @param {object} m 记忆条目
+ * @param {{latin: string[], cjk: string[]}} terms extractMemoryTerms 的结果
+ * @param {string} originalQuery 原始查询（小写 trim 后传入）
+ * @param {(key: string) => boolean} [dfFilter] buildDocFreqFilter 的结果，默认全通过
+ * @returns {{score: number, units: number, full: boolean, best: number}}
+ *   units 命中强度（跨单元累加，同单元跨字段取最强），0 表示词面不沾；
+ *   best 单个查询单元自己达到的最强单元数——区分「一次深命中」与「多次浅碎块」，
+ *   score 只反映出现在几个字段，判名次时必须有这根深度轴。
+ */
+export function keywordScore(m, terms, originalQuery, dfFilter = () => true) {
+  const texts = fieldTexts(m);
+  const perUnit = new Map();   // 单元身份 -> 各字段里的最强单元数
+  let score = 0;
+  let full = false;
+  for (const field of Object.keys(FIELD_WEIGHT)) {
+    // 字段级封顶（与原实现一致）：同一字段内的命中单元和先封顶再乘权重——不封顶的话，
+    // 长文档碰多个碎块会被按单元线性放大，正是本轮要压制的噪声形态。
+    // 跨字段仍各自累加：一个词既在正文又在标签出现，本来就是更强的排序信号。
+    let fieldUnits = 0;
+    for (const h of fieldUnitHits(texts[field], terms, dfFilter)) {
+      fieldUnits += h.units;
+      const prev = perUnit.get(h.unit);
+      if (prev === undefined || h.units > prev) perUnit.set(h.unit, h.units);
+      if (h.full) full = true;
+    }
+    score += FIELD_WEIGHT[field] * Math.min(fieldUnits, KEYWORD_MAX_HITS);
+  }
+  let units = 0;
+  let best = 0;
+  for (const u of perUnit.values()) {
+    units += u;
+    if (u > best) best = u;
+  }
+  units = Math.min(units, KEYWORD_MAX_HITS);   // 门槛轴同样封顶：去重后的单元和也不得超过 KEYWORD_MAX_HITS
+  const query = String(originalQuery || '');
+  if (query.length >= ORIGINAL_QUERY_MIN_LENGTH) {
+    if (texts.content.includes(query)) score += ORIGINAL_QUERY_CONTENT_BONUS;
+    if (texts.title.includes(query)) score += ORIGINAL_QUERY_TITLE_BONUS;
+  }
+  return { score, units, full, best };
+}

package/src/memory/vectors.js

@@ -0,0 +1,128 @@
+// agent/src/memory/vectors.js - 记忆向量的派生缓存
+// 原则：global-memory.json 是唯一真源，本文件只缓存派生向量。文件可丢、可坏、可整目录删除，
+// 任何异常都必须被吞掉当成空缓存（召回随之回落关键词通道），绝不能把 recall 带崩或带抛。
+// 跨模型向量不可比：modelKey（mode|modelName|dimensions）任一变化即整体作废旧向量。
+
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { dirname, join } from 'path';
+import { MEMORY_DIR } from '../config.js';
+
+export const VECTORS_FILE = join(MEMORY_DIR, 'memory-vectors.json');
+
+/** 模型标识：mode|model|dimensions。缺字段也拼成稳定串，不留 undefined 参与比较。 */
+export function memoryModelKey(cfg = {}) {
+  const c = cfg || {};
+  return `${c.mode || ''}|${c.modelName || ''}|${Number(c.dimensions) > 0 ? Math.floor(Number(c.dimensions)) : 0}`;
+}
+
+/**
+ * 余弦相似度。零向量、长度不一致、非有限数一律返回 0（不可比 ≠ 相似）。
+ */
+export function cosine(a = [], b = []) {
+  if (!Array.isArray(a) || !Array.isArray(b) || !a.length || a.length !== b.length) return 0;
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return 0;
+    dot += x * y;
+    na += x * x;
+    nb += y * y;
+  }
+  if (!na || !nb) return 0;
+  // 合并开方：分开写 sqrt(na)*sqrt(nb) 会带出浮点误差（sqrt(2)*sqrt(2)=2.0000000000000004），
+  // 自相似度算出 0.9999999999999998，阀值比较与展示都会飘。
+  const denom = Math.sqrt(na * nb);
+  return denom ? dot / denom : 0;
+}
+
+/** 只接受「非空 + 全有限数」的向量入库，NaN/Infinity 一旦落盘会污染整个相似度排序 */
+function isUsableVector(vec) {
+  return Array.isArray(vec) && vec.length > 0 && vec.every((n) => Number.isFinite(n));
+}
+
+/**
+ * 缓存门面（filePath 可注入，便于单测与临时 HOME 冒烟；进程内可创建多个实例互不干扰）
+ */
+export function createVectorStoreFacade({ filePath = VECTORS_FILE } = {}) {
+  // 串行链：读-改-写不能交叉，否则并发 upsert 会互相覆盖（与 service 的写锁同一思路）
+  let chain = Promise.resolve();
+  const serialized = (task) => {
+    const run = chain.then(task);
+    chain = run.catch(() => {});
+    return run;
+  };
+
+  async function readRaw() {
+    try {
+      const raw = await readFile(filePath, 'utf-8');
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== 'object' || !parsed.vectors || typeof parsed.vectors !== 'object') {
+        return { modelKey: '', vectors: {} };
+      }
+      return {
+        modelKey: typeof parsed.modelKey === 'string' ? parsed.modelKey : '',
+        vectors: parsed.vectors
+      };
+    } catch {
+      // 文件缺失 / JSON 损坏 / 权限问题：派生缓存视为空，下次使用时重建
+      return { modelKey: '', vectors: {} };
+    }
+  }
+
+  async function writeRaw(payload) {
+    try {
+      await mkdir(dirname(filePath), { recursive: true });
+      await writeFile(filePath, JSON.stringify(payload), 'utf-8');
+      return { success: true };
+    } catch (err) {
+      console.warn('[Memory] vectors write failed:', err?.message);
+      return { success: false, error: err?.message || 'vectors_write_failed' };
+    }
+  }
+
+  return {
+    filePath,
+    read: () => serialized(readRaw),
+    write: (payload) => serialized(() => writeRaw(payload)),
+
+    /** 批量写入向量；modelKey 与已存不同时整体作废 */
+    upsertVectors: (entries, modelKey) => serialized(async () => {
+      const cur = await readRaw();
+      const vectors = cur.modelKey === modelKey ? cur.vectors : {};
+      for (const [id, vec] of entries || []) {
+        if (isUsableVector(vec)) vectors[id] = vec;
+      }
+      return writeRaw({ modelKey, vectors });
+    }),
+
+    /** 摘除指定 id（记忆删除/淘汰时同步调用，避免留下孤儿向量） */
+    dropVectors: (ids) => serialized(async () => {
+      const cur = await readRaw();
+      let touched = false;
+      for (const id of ids || []) {
+        if (id in cur.vectors) {
+          delete cur.vectors[id];
+          touched = true;
+        }
+      }
+      if (!touched) return { success: true, skipped: true };
+      return writeRaw(cur);
+    }),
+
+    /** 整体作废（reindex 端点用） */
+    clear: () => serialized(() => writeRaw({ modelKey: '', vectors: {} })),
+  };
+}
+
+// ==================== 默认路径便捷出口（进程级单例） ====================
+
+const defaultStore = createVectorStoreFacade();
+
+export const readVectors = () => defaultStore.read();
+export const writeVectors = (payload) => defaultStore.write(payload);
+export const upsertVectors = (entries, modelKey) => defaultStore.upsertVectors(entries, modelKey);
+export const dropVectors = (ids) => defaultStore.dropVectors(ids);
+export const clearVectors = () => defaultStore.clear();

package/src/rag/embedding/index.js

@@ -27,6 +27,13 @@ export class EmbeddingProvider {
       ? new OpenAICompatEmbedding(resolved)
       : new LocalEmbedding(resolved);
 
+    // 长度可观测能力：只有本地档能拿到自己的 tokenizer。
+    // 远端档置 null（而非“猜一个窗口”）：厂商何时截断、截在哪，返回的向量里看不出来，
+    // 所以下游必须能区分「没有超窗」与「无从判断」。
+    this.tokenCounter = typeof this.backend.countTokens === 'function'
+      ? (texts) => this.backend.countTokens(texts)
+      : null;
+
     console.log(`[RAG] embedding mode: ${this.mode}, model: ${this.modelName}, queryPrefix: ${this.queryPrefix ? 'on' : 'off'}`);
   }
 

package/src/rag/embedding/local.js

@@ -42,6 +42,31 @@ export class LocalEmbedding {
     return output.tolist();
   }
 
+  /**
+   * 统计文本的真实 token 长度与模型上下文窗口（供调用方发现「会被截多」）。
+   *
+   * 必须 `truncation: false`：feature-extraction pipeline 内部用的是 `truncation: true`，
+   * 实测在 `model_max_length`（本模型 512）处静默砍尾——跟着它的口径数只会永远数到窗口值，
+   * 看不见损失了多少。也不走 `embed()` 的反推：tolist 只给向量，给不出长度。
+   * 纯 tokenization 不跑推理，成本远低于嵌入本身。
+   * @param {string[]} texts
+   * @returns {Promise<{counts: number[], window: number}>} counts 与入参同序
+   */
+  async countTokens(texts) {
+    if (!Array.isArray(texts) || texts.length === 0) return { counts: [], window: 0 };
+
+    const extractor = await this._getPipeline();
+    const tokenizer = extractor.tokenizer;
+    // 窗口值以 tokenizer 为准（实测 = tokenizer_config.model_max_length = 512），不自己写常量
+    const window = Number(tokenizer.model_max_length) || 0;
+    const counts = texts.map((t) => {
+      const encoded = tokenizer(String(t ?? ''), { padding: false, truncation: false });
+      const dims = encoded?.input_ids?.dims;
+      return Array.isArray(dims) && dims.length ? Number(dims[dims.length - 1]) : 0;
+    });
+    return { counts, window };
+  }
+
   /**
    * 获取（或加载）pipeline 单例
    */

package/src/rag/keyword-match.js

@@ -0,0 +1,112 @@
+// agent/src/rag/keyword-match.js - 关键词片段化匹配的纯函数（知识库与长期记忆共用）
+// 拆出本模块的原因：两侧原本各写一套匹配。知识库在 2026-09 就修掉了「英文子串误伤」
+// （rag 命中 storage）与「中文整段失配」两类缺陷，而记忆侧一直沿用更早的碎 bigram 方案，
+// 于是同一条 query 在两个子系统里的命中口径完全不同。共用一份实现，杜绝再次漂移。
+//
+// 语义约束（改动前必读）：
+//   - 英文/数字按词边界判定，CJK 相邻视为边界；
+//   - 中文取「最长命中片段」，且 2 字片段命中必蕴含更长片段的命中，故先做 2 字预检；
+//   - 单元数只按长度分层（L=2 → 1，L=3 → 2，L≥4 → 3 顶格），不做出现次数累加；
+//   - 本模块只负责「匹配」，df 统计与抬分属各调用方自己的刻度（知识库 [0,1]、记忆整数），不在此处。
+
+export const KEYWORD_MIN_LEN = 2;          // 命中单元最小长度（单字符匹配噪声过大）
+export const KEYWORD_MAX_FRAGMENT_LEN = 4; // 中文最长匹配窗口（≥4 字命中已顶格 3 单元，无需更长窗口）
+export const KEYWORD_MAX_HITS = 3;         // 计分单元总数上限（防止长查询过度加分）
+
+/**
+ * 从查询中提取关键词（英文/数字按分隔符成段；中文取连续段）
+ * 说明：不引入分词依赖——中文长段由 matchCjk 按最长命中片段降级匹配，
+ * 本函数只负责切段与小写去重
+ * @param {string} query
+ * @returns {string[]} 小写去重后的关键词
+ */
+export function extractKeywords(query) {
+  const parts = String(query || '').toLowerCase().split(/[^a-z0-9\u4e00-\u9fff]+/);
+  const seen = new Set();
+  const keywords = [];
+  for (const p of parts) {
+    if (p.length >= KEYWORD_MIN_LEN && !seen.has(p)) {
+      seen.add(p);
+      keywords.push(p);
+    }
+  }
+  return keywords;
+}
+
+/**
+ * 将关键词段拆分为带类型的命中单元：英文/数字段与中文段分开处理
+ * 段内非 [a-z0-9] 的字符必为汉字（切分阶段已剔除其他字符），无需引入 Unicode 转义
+ * @param {string} query
+ * @returns {{latin: string[], cjk: string[]}} 小写去重后的单元列表
+ */
+export function extractQueryTerms(query) {
+  const latin = [];
+  const cjk = [];
+  const seenLatin = new Set();
+  const seenCjk = new Set();
+  for (const seg of extractKeywords(query)) {
+    for (const run of seg.match(/[a-z0-9]+|[^a-z0-9]+/g) || []) {
+      if (run.length < KEYWORD_MIN_LEN) continue;
+      if (/^[a-z0-9]+$/.test(run)) {
+        if (!seenLatin.has(run)) {
+          seenLatin.add(run);
+          latin.push(run);
+        }
+      } else if (!seenCjk.has(run)) {
+        seenCjk.add(run);
+        cjk.push(run);
+      }
+    }
+  }
+  return { latin, cjk };
+}
+
+/**
+ * 英文/数字：词边界匹配（前后须为非字母数字；CJK 相邻视为边界）
+ * @param {string} text 已小写的待匹配文本
+ * @param {string[]} latin 拉丁/数字单元
+ * @returns {string[]} 命中的单元
+ */
+export function matchLatin(text, latin) {
+  if (!latin || latin.length === 0) return [];
+  const bounded = ' ' + String(text || '').toLowerCase().replace(/[^a-z0-9]+/g, ' ') + ' ';
+  return latin.filter(term => bounded.includes(' ' + term + ' '));
+}
+
+/**
+ * 中文：文本内此段的最长命中片段
+ * @param {string} text 已小写的待匹配文本
+ * @param {string} seg 一个连续中文段
+ * @returns {{keys: string[], units: number} | null} 无 2 字片段命中时为 null；
+ *          units = min(bestLen - 1, KEYWORD_MAX_HITS)
+ */
+export function matchCjk(text, seg) {
+  const hay = String(text || '').toLowerCase();
+  if (!hay || !seg || seg.length < KEYWORD_MIN_LEN) return null;
+
+  // 2 字片段预检：更长片段的命中必蕴含其 2 字子串命中，全未命中即可跳过
+  const keys2 = new Set();
+  for (let i = 0; i + 2 <= seg.length; i++) {
+    const frag = seg.slice(i, i + 2);
+    if (hay.includes(frag)) keys2.add(frag);
+  }
+  if (keys2.size === 0) return null;
+
+  const maxLen = Math.min(seg.length, KEYWORD_MAX_FRAGMENT_LEN);
+  let bestKeys = keys2;
+  let bestLen = 2;
+  for (let len = maxLen; len >= 3; len--) {
+    const keys = new Set();
+    for (let i = 0; i + len <= seg.length; i++) {
+      const frag = seg.slice(i, i + len);
+      if (hay.includes(frag)) keys.add(frag);
+    }
+    if (keys.size > 0) {
+      bestKeys = keys;
+      bestLen = len;
+      break;
+    }
+  }
+  // 命中越长计分单元越多（L=2 → 1 单元；L≥4 顶格 3 单元）
+  return { keys: [...bestKeys], units: Math.min(bestLen - 1, KEYWORD_MAX_HITS) };
+}

package/src/rag/manager.js

@@ -25,6 +25,7 @@ import { RagError } from './errors.js';
 import { checkPath } from '../security.js';
 import { fetchUrlGuarded, decodeBytes } from './url-guard.js';
 import { loadConfig } from '../config.js';
+import { encodeSecret, decodeSecret } from '../crypto-lite.js';
 
 // 知识库 ID 格式校验（防路径穿越）
 const COLLECTION_ID_RE = /^kb_[a-z0-9]+$/;
@@ -189,6 +190,12 @@ export class RagManager {
       const raw = await readFile(COLLECTIONS_REGISTRY, 'utf-8');
       const reg = JSON.parse(raw);
       if (!Array.isArray(reg.collections)) reg.collections = [];
+      // 磁盘密文 → 内存明文（兼容旧版无 enc: 前缀的明文）
+      for (const col of reg.collections) {
+        if (col.embeddingConfig?.apiKey) {
+          col.embeddingConfig = { ...col.embeddingConfig, apiKey: decodeSecret(col.embeddingConfig.apiKey) };
+        }
+      }
       return reg;
     } catch {
       return { version: 1, collections: [] };
@@ -204,6 +211,14 @@ export class RagManager {
       const reg = await this._loadRegistry();
       const out = mutator(reg) || reg;
       await mkdir(RAG_ROOT, { recursive: true });
+      // 落盘前混淆各库的 apiKey（内存保持明文）
+      if (Array.isArray(out.collections)) {
+        for (const col of out.collections) {
+          if (col.embeddingConfig?.apiKey) {
+            col.embeddingConfig = { ...col.embeddingConfig, apiKey: encodeSecret(col.embeddingConfig.apiKey) };
+          }
+        }
+      }
       // 注册表含远端向量服务密钥：创建即 0600，并对历史遗留的宽松权限文件显式收紧
       await writeFile(COLLECTIONS_REGISTRY, JSON.stringify(out, null, 2), { encoding: 'utf-8', mode: 0o600 });
       await chmod(COLLECTIONS_REGISTRY, 0o600).catch(() => {}); // Windows 无 POSIX 权限位，忽略