ai-helper-agent 2.2.0 → 2.3.1

package/src/memory/embedding-config.js

@@ -0,0 +1,95 @@
+// agent/src/memory/embedding-config.js - 记忆语义召回的 embedding 配置读写与脱敏
+// 单一配置出口：只读写 agent config.json 的 memoryEmbedding 字段，请求体永不回显明文 key。
+// 缺省 enabled=false：recall 只走关键词通道（Tier A），不新增任何默认网络调用。
+
+import { loadConfig, updateConfigField } from '../config.js';
+
+export const DEFAULT_MEMORY_EMBEDDING_CONFIG = {
+  enabled: false,
+  mode: 'openai-compat',
+  baseUrl: '',
+  modelName: '',
+  apiKey: '',
+  dimensions: 0,
+  queryPrefix: ''
+};
+
+// mode 白名单：远端 OpenAI 兼容端点（零依赖）与本地 transformers 模型（需 RAG 依赖）
+export const MEMORY_EMBEDDING_MODES = ['openai-compat', 'local'];
+
+/** 原始配置（含 apiKey 明文，仅进程内使用，绝不出响应体） */
+export function getMemoryEmbeddingConfig() {
+  const cfg = loadConfig().memoryEmbedding || {};
+  return { ...DEFAULT_MEMORY_EMBEDDING_CONFIG, ...cfg };
+}
+
+/** 对外响应形态：隐藏明文 key，附 hasApiKey 供前端「已配置」提示（沿用 rag/routes.js 约定） */
+export function maskMemoryEmbeddingConfig(cfg = getMemoryEmbeddingConfig()) {
+  const { apiKey, ...rest } = cfg;
+  return { ...rest, apiKey: '', hasApiKey: Boolean(apiKey) };
+}
+
+/**
+ * 保存配置：mode 白名单校验；空白 apiKey 表示不修改（前端表单不回填明文时不能抹掉已存 key）；
+ * clearApiKey===true 是唯一显式清除通道，且优先于同传的 apiKey；
+ * dimensions 规整为非负整数；enabled 只认真 true（字符串/数字一律视为关闭）。
+ * @param {object} input
+ * @returns {Promise<object>} 脱敏后的最新配置
+ * @throws {Error} message = 'invalid_embedding_mode'
+ */
+export async function saveMemoryEmbeddingConfig(input = {}) {
+  const current = getMemoryEmbeddingConfig();
+  const next = { ...current };
+
+  if (input.mode !== undefined) {
+    if (!MEMORY_EMBEDDING_MODES.includes(input.mode)) {
+      throw new Error('invalid_embedding_mode');
+    }
+    next.mode = input.mode;
+  }
+  if (input.enabled !== undefined) next.enabled = input.enabled === true;
+  if (typeof input.baseUrl === 'string') next.baseUrl = input.baseUrl.trim();
+  if (typeof input.modelName === 'string') next.modelName = input.modelName.trim();
+  if (typeof input.queryPrefix === 'string') next.queryPrefix = input.queryPrefix;
+  if (typeof input.apiKey === 'string' && input.apiKey.trim()) next.apiKey = input.apiKey.trim();
+  // L1（评审）：明文不回显 + 空白=不修改 ⇒ 用户没有清除路径。clearApiKey 放在赋值之后：
+  // 清除是显式动作，赢过同传的新 key（界面不会同传，但 API 语义不能含糊）。
+  if (input.clearApiKey === true) next.apiKey = '';
+  if (input.dimensions !== undefined) {
+    const n = Number(input.dimensions);
+    next.dimensions = Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+  }
+
+  await updateConfigField('memoryEmbedding', next);
+  return maskMemoryEmbeddingConfig(next);
+}
+
+/**
+ * 探活/向量派生用的 provider 配置：请求体可覆盖尚未保存的草稿值，
+ * 但明文 key 缺省时回落到已保存的 key（前端不会回传明文）。
+ * @param {object} [override]
+ */
+export function resolveMemoryEmbeddingConfig(override = {}) {
+  const saved = getMemoryEmbeddingConfig();
+  const merged = { ...saved, ...(override || {}) };
+  if (!merged.apiKey) merged.apiKey = saved.apiKey;
+  return merged;
+}
+
+/**
+ * 转成 rag/embedding provider 需要的形态：配置面统一叫 baseUrl（与扩展端表单一致），
+ * 而 OpenAI 兼容后端读的是 endpoint。缺这一映射会让远端档永远 fetch('/embeddings')。
+ * 单一出口：所有把记忆 embedding 配置交给 provider 的地方都必须过这里。
+ * @param {object} [cfg]
+ */
+export function toEmbeddingProviderConfig(cfg = {}) {
+  const baseUrl = cfg.baseUrl || '';
+  const endpoint = cfg.endpoint || '';
+  const out = { ...cfg, endpoint: endpoint || baseUrl, baseUrl: baseUrl || endpoint };
+  // 空串在本配置面表示「未设置」（DEFAULT_MEMORY_EMBEDDING_CONFIG.queryPrefix 就是 ''），
+  // 而 provider 用 `??` 判回落——空串不是 nullish，原样交出会让本地 BGE 的查询前缀永远加不上
+  // （实测：mode=local 时 provider 日志 queryPrefix: off）。非对称检索漏前缀对中文召回是实质质量损失，
+  // 所以这里交出「不带这个键」，把回落权还给 provider。显式非空前缀照常透传。
+  if (!String(out.queryPrefix || '').trim()) delete out.queryPrefix;
+  return out;
+}

package/src/memory/fusion.js

@@ -0,0 +1,60 @@
+// agent/src/memory/fusion.js - 语义采信门与排名融合（纯函数，无 IO）
+//
+// 【2026-10-14 计划五：记忆语义档转「纯 top-K」，删掉查询级绝对地板】
+// 本模块原有三道采信门，现只剩后两道（都是**相对量**，随模型自动平移，无需标定）：
+//  ② 条目级相对落差：cos ≥ top1 - margin，砍高分查询的长尾。
+//  ③ 条数封顶 maxTake：防止一次语义命中填满 limit。
+// 第①道「查询级绝对地板」（原 SEMANTIC_QUERY_FLOOR=0.48，top1<floor 整通道否决）**已移除**。
+// 移除理由：那个地板是在 BAAI/bge-m3 上标定的绝对值，不可跨模型平移；而记忆向量允许用户任选
+// 远端/本地任意模型，套同一个 0.48 会在别的模型上失配（本地档实测：噪声 top1=0.5599 逃过地板
+// 被误返、真相关 top1=0.4888 被地板绞杀）。绝对值判「本库有无答案」这件事绕不开按模型标定，与
+// 「用户不必懂向量、开箱即用」根本冲突 —— 故放弃「无匹配空返」能力，换取任意模型开箱可用。
+// 代价（已知并被接受）：与全库无关的查询也会返回至多 maxTake 条语义头部。护栏随之从「空返」
+// 降级为「至多 maxTake 条、不填满 limit」，由评测集守住。
+//
+// 【两个仍然成立的结论，不要回退】
+//  • 条目级绝对值不可用：问「这条记忆算不算命中」用绝对阈值放过的太多（≥0.45 仍放过 20/41），
+//    所以条目级只看相对落差。
+//  • 分离度（top1-top2）不可加回：它不可跨库规模外推（库越大无关查询 top1-top2 越可能偶然变大），
+//    且真实库目标查询 Q1 的 gap 0.0214 低于无关查询的 0.0361/0.0397，在 gap 轴上分不开。
+//
+// SEMANTIC_QUERY_FLOOR 常量保留仅供离线标定/参考（换模型时可用 test/eval/recalibrate-semantic-floor.mjs
+// 量一个地板），**但线上 selectSemanticHits 不再施加它**——本文件的采信门里没有绝对值。
+
+export const SEMANTIC_QUERY_FLOOR = 0.48;  // 【离线参考】仅供标定脚本；线上 selectSemanticHits 不施加
+export const SEMANTIC_MARGIN = 0.05;       // 条目级相对落差：只采信距 top1 不超过此值的头部
+export const SEMANTIC_MAX_TAKE = 2;        // 每次查询最多采信几条语义命中
+export const RRF_K = 60;                   // 排名融合的平滑常数（业界默认值，本计划不重调）
+
+/**
+ * 语义通道采信哪些条目（纯 top-K：只按相对远近取头部，不含任何随模型漂移的绝对值）。
+ * 两道门：① 条目级相对落差 cos ≥ top1 - margin（砍高分查询的长尾）；② 条数封顶 maxTake。
+ * 与全库无关的查询也会返回至多 maxTake 条头部 —— 这是「纯 top-K 换任意模型开箱即用」的已知代价。
+ * 注意：**既不看绝对地板、也不看 top1-top2 分离度**（理由见文件头）。
+ * @param {Array<[string, number]>} pairs [id, cos]，顺序任意
+ * @param {{margin:number, maxTake:number}} gate
+ * @returns {Array<[string, number]>} 按 cos 降序的采信结果（候选为空时返回空表）
+ */
+export function selectSemanticHits(pairs = [], gate = { margin: SEMANTIC_MARGIN, maxTake: SEMANTIC_MAX_TAKE }) {
+  const ranked = [...pairs].filter(([, c]) => Number.isFinite(c)).sort((a, b) => b[1] - a[1]);
+  if (!ranked.length) return [];
+  const floor = ranked[0][1] - gate.margin;
+  return ranked.filter(([, c]) => c >= floor).slice(0, gate.maxTake);
+}
+
+/**
+ * Reciprocal Rank Fusion：只消费名次，不消费分数，因此两路刻度不可比也不再是问题。
+ * @param {Array<Array<[string, number]>>} lists 每路的 [id, rank]（rank 从 1 起）
+ * @param {number} k
+ * @returns {Array<[string, number]>} [id, 融合分] 降序
+ */
+export function rrfFuse(lists = [], k = RRF_K) {
+  const acc = new Map();
+  for (const list of lists) {
+    for (const [id, rank] of list || []) {
+      if (!id || !(rank >= 1)) continue;
+      acc.set(id, (acc.get(id) || 0) + 1 / (k + rank));
+    }
+  }
+  return [...acc.entries()].sort((a, b) => b[1] - a[1]);
+}

package/src/memory/injection.js

@@ -0,0 +1,118 @@
+// agent/src/memory/injection.js - 记忆分级注入策略（纯函数、零依赖，便于单测）
+// 三级加载：
+//   Tier1 常驻   importance ≥ alwaysInjectImportance 无条件注入（不占预算）
+//   Tier2 预算内 其余按 calcMemoryValue 降序在预算内填充（装不下的跳过继续尝试）
+//   Tier3 按需   未注入的转由系统提示词索引行引导 agent_memory recall 检索
+
+export const MEMORY_INJECTION_CONFIG = {
+  alwaysInjectImportance: 8, // Tier1 常驻阈值（importance ≥ 此值不占预算）
+  budgetChars: 1500,         // Tier2 字符预算（content + 标签 + 渲染开销近似）
+  budgetCount: 12,           // Tier2 条数预算
+  itemOverheadChars: 50,     // 每条渲染开销近似（序号、[重要性: N]、(标签: ...)）
+  maxTopicTags: 8,           // 索引提示最多展示的主题标签数
+  maxTagLength: 12,          // 单个主题标签最大长度（超出截断）
+};
+
+/**
+ * 计算记忆价值分数（用于淘汰判断与注入排序）
+ * 迁移自 tool-memory.js（单一来源），行为不变：
+ * value = importance × (1 + ln(访问次数 + 1)) × 时间衰减
+ */
+export function calcMemoryValue(memory, now) {
+  const importance = memory.importance || 5;
+  const accessCount = memory.accessCount || 0;
+  const createdAt = new Date(memory.createdAt).getTime();
+  const ageDays = (now - createdAt) / (1000 * 60 * 60 * 24);
+
+  // 时间衰减因子
+  let decay;
+  if (ageDays <= 7) decay = 1.0;
+  else if (ageDays <= 30) decay = 0.8;
+  else if (ageDays <= 90) decay = 0.5;
+  else decay = 0.2;
+
+  return importance * (1 + Math.log(accessCount + 1)) * decay;
+}
+
+/**
+ * 单条记忆注入成本近似（字符）
+ */
+function estimateInjectionCost(memory, config) {
+  const contentLen = typeof memory.content === 'string' ? memory.content.length : 0;
+  const tagsLen = Array.isArray(memory.tags) ? memory.tags.join(', ').length : 0;
+  return contentLen + tagsLen + config.itemOverheadChars;
+}
+
+/**
+ * 收集未注入记忆的主题标签索引：
+ * 去重 → 频率降序（同频按首现顺序）→ 截断数量与单标签长度
+ */
+function collectRemainingTags(remainingFacts, summaries, config) {
+  const counts = new Map();
+  const firstSeen = new Map();
+  let seq = 0;
+  const addTags = (item) => {
+    if (!Array.isArray(item.tags)) return;
+    for (const raw of item.tags) {
+      const tag = String(raw ?? '').trim();
+      if (!tag) continue;
+      if (!counts.has(tag)) {
+        counts.set(tag, 0);
+        firstSeen.set(tag, seq++);
+      }
+      counts.set(tag, counts.get(tag) + 1);
+    }
+  };
+  for (const m of remainingFacts) addTags(m);
+  for (const m of summaries) addTags(m);
+
+  return [...counts.keys()]
+    .sort((a, b) => (counts.get(b) - counts.get(a)) || (firstSeen.get(a) - firstSeen.get(b)))
+    .slice(0, config.maxTopicTags)
+    .map(tag => (tag.length > config.maxTagLength ? tag.slice(0, config.maxTagLength) : tag));
+}
+
+/**
+ * 三级筛选：选出注入系统提示词的记忆
+ * @param {Array} facts - 事实记忆数组（原文件顺序）
+ * @param {Array} summaries - 摘要记忆数组（永不注入，仅计入按需召回）
+ * @param {object} [config] - 注入配置
+ * @param {number} [now] - 当前时间戳（测试注入用）
+ * @returns {{injected: Array, remainingCount: number, remainingTags: string[]}}
+ */
+export function selectMemoriesForInjection(facts, summaries, config = MEMORY_INJECTION_CONFIG, now = Date.now()) {
+  const factList = Array.isArray(facts) ? facts : [];
+  const summaryList = Array.isArray(summaries) ? summaries : [];
+  const threshold = config.alwaysInjectImportance;
+
+  // Tier1：常驻（不占预算），内部按价值降序
+  const tier1 = factList
+    .filter(m => (m.importance || 5) >= threshold)
+    .sort((a, b) => calcMemoryValue(b, now) - calcMemoryValue(a, now));
+  const tier1Set = new Set(tier1);
+
+  // Tier2：剩余按价值降序，在预算内贪心填充（装不下的跳过，继续尝试后续小条目）
+  const tier2Pool = factList
+    .filter(m => !tier1Set.has(m))
+    .sort((a, b) => calcMemoryValue(b, now) - calcMemoryValue(a, now));
+
+  const injected = [...tier1];
+  let usedChars = 0;
+  let usedCount = 0;
+  for (const m of tier2Pool) {
+    if (usedCount >= config.budgetCount) break;
+    const cost = estimateInjectionCost(m, config);
+    if (usedChars + cost > config.budgetChars) continue;
+    injected.push(m);
+    usedChars += cost;
+    usedCount++;
+  }
+
+  // Tier3：未注入的 facts + 全部 summaries 转按需召回
+  const injectedSet = new Set(injected);
+  const remainingFacts = factList.filter(m => !injectedSet.has(m));
+  const remainingCount = remainingFacts.length + summaryList.length;
+  const remainingTags = collectRemainingTags(remainingFacts, summaryList, config);
+
+  return { injected, remainingCount, remainingTags };
+}

package/src/memory/routes.js

@@ -0,0 +1,193 @@
+// agent/src/memory/routes.js - /api/memory/* 业务端点（认证与语言解析由 server.js 完成后转发）
+// 零外部依赖：与 service 同进程，文件锁、session 召回缓存复用进程级单例。
+
+import { createMemoryService } from './service.js';
+import {
+  resolveMemoryEmbeddingConfig,
+  maskMemoryEmbeddingConfig,
+  saveMemoryEmbeddingConfig,
+  toEmbeddingProviderConfig
+} from './embedding-config.js';
+import { createEmbeddingProvider } from '../rag/embedding/index.js';
+
+// 探活超时上限：语义通道绝不能拖垮调用方
+const DEFAULT_EMBEDDING_TIMEOUT_MS = 8000;
+
+// 进程级单例（默认路径 MEMORY_DIR/global-memory.json）
+const defaultService = createMemoryService();
+
+// 子路径 → service 方法映射
+const ROUTE_METHODS = {
+  store: 'store',
+  recall: 'recall',
+  manage: 'manage',
+  inject: 'injectSelect',
+  // 重建向量缓存：派生缓存的显式重建入口（模型变更/首次启用语义通道后调一次）
+  reindex: 'backfillVectors'
+};
+
+/**
+ * 判断请求来源是否允许跨域读取响应（与 server.js 的 getAllowedOrigin 行为一致）
+ */
+function getAllowedOrigin(req) {
+  const origin = req?.headers?.origin;
+  if (typeof origin === 'string' && origin.startsWith('chrome-extension://')) {
+    return origin;
+  }
+  return null;
+}
+
+/**
+ * JSON 响应辅助（与 server.js 的 jsonResponse 行为一致）
+ */
+function jsonResponse(res, status, data) {
+  const headers = {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS'
+  };
+  const allowedOrigin = getAllowedOrigin(res.req);
+  if (allowedOrigin) {
+    headers['Access-Control-Allow-Origin'] = allowedOrigin;
+    headers['Vary'] = 'Origin';
+  }
+  res.writeHead(status, headers);
+  res.end(JSON.stringify(data));
+}
+
+/**
+ * embed 调用超时保护。到期后必须 clearTimeout：否则 daemon 里每调一次就多挂一个定时器，
+ * 测试进程也会因为残留句柄延迟退出。
+ */
+function withTimeout(promise, ms) {
+  let timer = null;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error('embedding_timeout')), ms);
+    })
+  ]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * 记忆 embedding 的配置/探活端点。配置类不走 ROUTE_METHODS，也不受「非 POST 即 404」约束
+ * （GET 是合法读操作）；返回 true 表示已响应，false 则继续走业务分发/404。
+ * @param {{createProvider?: Function, embeddingTimeoutMs?: number}} [options] 测试接缝：注入假 provider
+ */
+async function handleEmbeddingEndpoints(req, res, key, t, requestBody, options = {}) {
+  const body = requestBody || {};
+
+  if (key === 'embedding-config') {
+    if (req.method === 'GET') {
+      jsonResponse(res, 200, { success: true, config: maskMemoryEmbeddingConfig() });
+      return true;
+    }
+    if (req.method === 'POST') {
+      try {
+        const config = await saveMemoryEmbeddingConfig(body);
+        jsonResponse(res, 200, { success: true, config });
+      } catch (err) {
+        const error = err.message === 'invalid_embedding_mode'
+          ? t('memory.invalidEmbeddingMode')
+          : (err.message || 'embedding_config_error');
+        jsonResponse(res, 400, { success: false, error });
+      }
+      return true;
+    }
+    return false;
+  }
+
+  if (key === 'test-embedding') {
+    if (req.method !== 'POST') return false;
+    // 允许用请求体覆盖尚未保存的草稿配置，明文 key 缺省时回落已存 key
+    const cfg = resolveMemoryEmbeddingConfig(body);
+    const createProvider = options.createProvider || createEmbeddingProvider;
+    const timeoutMs = Number(options.embeddingTimeoutMs) > 0
+      ? Number(options.embeddingTimeoutMs)
+      : DEFAULT_EMBEDDING_TIMEOUT_MS;
+    try {
+      const provider = createProvider(toEmbeddingProviderConfig(cfg));
+      const vec = await withTimeout(Promise.resolve(provider.embedQuery('ping')), timeoutMs);
+      jsonResponse(res, 200, { success: true, dimensions: Array.isArray(vec) ? vec.length : 0 });
+    } catch (err) {
+      jsonResponse(res, 400, { success: false, error: err.message || 'embedding_test_failed' });
+    }
+    return true;
+  }
+
+  // 只读状态：条数 + 指纹陈旧。走 GET（配置类端点同例，不受「非 POST 即 404」约束）。
+  // 放在这里而不是 ROUTE_METHODS：后者只收 POST 业务动作，且需要请求体。
+  if (key === 'vector-status') {
+    if (req.method !== 'GET') return false;
+    const service = options.service || defaultService;
+    try {
+      const data = await service.vectorStatus();
+      if (data && data.success === false) {
+        jsonResponse(res, 400, data);
+      } else {
+        jsonResponse(res, 200, { success: true, ...data });
+      }
+    } catch (err) {
+      jsonResponse(res, 400, { success: false, error: err.message || 'vector_status_failed' });
+    }
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * /api/memory/* 分发
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ * @param {string} pathname 形如 /api/memory/store
+ * @param {URL} url
+ * @param {(key: string, params?: object) => string} t 请求级翻译函数
+ * @param {object} requestBody 已解析的请求体
+ * @param {{service?: object}} [options] 可注入 service 实例（测试用），缺省使用进程级单例
+ */
+export async function memoryDispatch(req, res, pathname, url, t, requestBody = {}, options = {}) {
+  const service = options.service || defaultService;
+  const key = pathname.slice('/api/memory/'.length).replace(/\/+$/, '');
+  const method = ROUTE_METHODS[key];
+
+  // 配置与探活端点先分流（GET 合法，且不进业务 404 判定）
+  if (await handleEmbeddingEndpoints(req, res, key, t, requestBody, options)) return;
+
+  // 404 仅表示路径/方法不匹配（扩展端据此探测旧版本 agent 无记忆端点）
+  if (!method || req.method !== 'POST') {
+    return jsonResponse(res, 404, { success: false, error: t('error.unknownApiPath') });
+  }
+
+  const body = requestBody || {};
+
+  try {
+    let data;
+    if (method === 'recall') {
+      data = await service.recall(body, body.sessionId ?? null, t);
+    } else if (method === 'injectSelect') {
+      data = await service.injectSelect(t);
+    } else if (method === 'backfillVectors') {
+      // 不接受请求体：只做「按当前配置把全部记忆补进向量缓存」，t 用于渲染跳过原因
+      data = await service.backfillVectors(t);
+    } else {
+      data = await service[method](body, t);
+    }
+
+    // 业务失败（参数缺失、文件读写失败）：HTTP 400 + 原样 error，扩展端仍读 body
+    if (data && data.success === false) {
+      return jsonResponse(res, 400, data);
+    }
+    return jsonResponse(res, 200, { success: true, ...data });
+  } catch (err) {
+    console.error('[Memory] route error:', err);
+    return jsonResponse(res, 400, { success: false, error: err.message || 'memory_error' });
+  }
+}
+
+/**
+ * server.js 接线入口（签名与 ragRouter 一致）
+ */
+export async function memoryRouter(req, res, pathname, url, t, requestBody) {
+  return memoryDispatch(req, res, pathname, url, t, requestBody);
+}