Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

17.6 KB
Raw Blame
/**
 * recentModels —— 统一模型选择器的「最近」视图存储(model-selector-unified §1.2):
 * 用户在**对话**里用过的**配置副本**(模型 + 引擎 + 深度 + Fast),按最近一次使用时间倒序。
 *
 * 语义边界:
 *   - 收藏是**用户钉住**的配置副本(手动添加 / 删除,长期保留);
 *   - 最近是**自动记录**的配置副本(选择成功即记录,超出容量自动淘汰)。
 *   两者是同一套「配置副本」语义(归一化 / 身份规则共用 modelConfigCopy),所以:
 *   - 同一模型用不同深度 / 引擎 / Fast 各占**一行**(和收藏一致,不是按模型去重);
 *   - 星标(面板绘制)按**完全一致的副本**匹配收藏 —— 该条副本已在收藏里就点亮,
 *     没有则点星把这份副本存进收藏;匹配与去重都走同一份身份(modelConfigCopyIdentity)。
 *   与收藏的区别只在生命周期与入口:最近不能手动编辑(它是流水账,不是用户整理的清单),
 *   由记录点自动写入、超过容量自动淘汰。
 *
 * 记录点只有一个:对话入口里「选择真的应用成功」的那一下(useUnifiedRowActions.selectRow;
 * 草稿 / 会话 / 跨引擎三条链路都在那里收口),记的是**那一刻生效的整份配置**。
 * 定时任务、IM 默认、Bot、Hook、Worker、子代理与设置页共用的同一面板**不记**(那些是配置
 * 动作,不是「用这个模型跑过活」);远程(SSH / device-link)会话与草稿也不记:模型来自被控端
 * 目录,写进本机列表只会得到一行永远不可路由的记录(与「远程模型不写入本机记忆」同向)。
 *
 * 持久化:localStorage,owner 分区(与 modelFavorites / modelEnginePrefs 同形)。写频率极低
 * (用户选一次模型写一次),**同步写** —— 热更 relaunch 走 app.exit() 强退,异步写会丢最近
 * 一次改动。写失败静默吞,内存态照常生效。
 *
 * 并发写(多窗口):沿用 storageOpReplay 的「同步乐观写 + 会话 op-log + 事件驱动的持续调和」
 * (机制正文在那个文件头,那里是唯一权威)。这里只记本 store 的落地方式:
 *   - 每个写入表达成一个可重放的 op(`record`:一次「这份配置在此时被用过」的断言);
 *   - `applyOp(state, op)` 按副本身份取 max(usedAt) 并入,无变化时返回原对象;
 *   - 整条 log 的重放要保持幂等:`compactRecentOps` 把同一副本身份的历史 op 折成一条,
 *     否则重放会拿旧 usedAt 去顶掉后来的记录;
 *   - 没有删除类 op(用户不能「删掉最近用过」),所以不设 tombstone。
 *   与收藏相比残余边界更温和:即使调和完全失效,最坏也只是少一条快捷方式,不丢用户手存的数据。
 */

import { useSyncExternalStore } from 'react';

import {
  modelConfigCopyIdentity,
  normalizeModelConfigCopy,
  type ModelConfigCopy,
} from './modelConfigCopy';
import { createStorageReconciler } from './storageOpReplay';

const STORAGE_KEY = 'xdt:recentModels:v1';

/**
 * 本机保留的流水条数。刻意大于展示条数:最近几条恰好指向不可路由的模型(来源断开 / 目录
 * 下架)时,面板能往后补足 5 条,而不是显示成「最近只用过 2 个」。
 */
export const RECENT_MODELS_KEEP = 20;

/** 落盘 / 消费的一条记录:配置副本 + 最近一次使用时间。 */
export interface RecentModelItem extends ModelConfigCopy {
  /** 最近一次使用时间(epoch ms);排序与跨窗口合并都以它为准。 */
  usedAt: number;
}

interface RecentModelsState {
  /** 按 usedAt 倒序。 */
  items: RecentModelItem[];
}

let activeDataOwnerId: string | null = null;

function storageKey(): string {
  return activeDataOwnerId ? `${STORAGE_KEY}:${encodeURIComponent(activeDataOwnerId)}` : STORAGE_KEY;
}

function emptyState(): RecentModelsState {
  return { items: [] };
}

/**
 * 严格校验一条记录:配置字段走与收藏同一套归一化(见 modelConfigCopy),时间不合法 → null。
 * 模型身份或引擎不合法整条丢弃;effort 非法只丢该字段。
 */
function normalizeItem(raw: {
  providerId?: unknown;
  modelId?: unknown;
  agent?: unknown;
  effort?: unknown;
  fast?: unknown;
  usedAt?: unknown;
}): RecentModelItem | null {
  const config = normalizeModelConfigCopy(raw);
  if (!config) return null;
  if (typeof raw.usedAt !== 'number' || !Number.isFinite(raw.usedAt) || raw.usedAt <= 0) {
    return null;
  }
  return { ...config, usedAt: raw.usedAt };
}

/**
 * 严格校验 + 归一化。老版本 / 手改 localStorage 损坏时静默回退空表,不抛。
 *   - 形状非法的条目整条丢弃;
 *   - 同一**副本身份**出现多条时只保 usedAt 最新的那条;
 *   - 按 usedAt 倒序,并裁到 RECENT_MODELS_KEEP 条。
 */
function sanitize(raw: unknown): RecentModelsState {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return emptyState();
  const rawItems = Array.isArray((raw as { items?: unknown }).items)
    ? ((raw as { items: unknown[] }).items)
    : [];
  const byKey = new Map<string, RecentModelItem>();
  for (const entry of rawItems) {
    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
    const item = normalizeItem(entry as Record<string, unknown>);
    if (!item) continue;
    const key = modelConfigCopyIdentity(item);
    const existing = byKey.get(key);
    if (!existing || item.usedAt > existing.usedAt) byKey.set(key, item);
  }
  return {
    items: [...byKey.values()].sort((a, b) => b.usedAt - a.usedAt).slice(0, RECENT_MODELS_KEEP),
  };
}

// 进程内缓存(惰性加载)。读多写少,避免每次读都 parse localStorage。
let cache: RecentModelsState | null = null;

/**
 * 按**给定 key** 读原始 localStorage(不碰缓存)。key 可能不是当前 active 分区 ——
 * 登出 / 切号之后旧分区的调和仍要按它自己的 key 读写(机制见 storageOpReplay 文件头)。
 */
function loadFromKey(key: string): RecentModelsState {
  if (typeof window === 'undefined') return emptyState();
  try {
    const raw = window.localStorage.getItem(key);
    return raw ? sanitize(JSON.parse(raw)) : emptyState();
  } catch {
    return emptyState();
  }
}

function loadFromStorage(): RecentModelsState {
  return loadFromKey(storageKey());
}

function load(): RecentModelsState {
  if (!cache) cache = loadFromStorage();
  return cache;
}

/**
 * **写路径的基底** —— 每次写入前重读 localStorage,拿到的是此刻的共享真相,而不是本窗口的
 * 内存快照(理由与 modelFavorites.freshState 逐字相同:storage 事件是异步的,整表写回用陈旧
 * 基底会抹掉另一窗口刚记的那条)。读不出来时退回内存缓存,不退回空表 —— 私密窗口 / 写满时
 * setItem 静默失败、getItem 恒 null,拿空表当基底会把本次会话已记的全部抹掉。
 */
function freshState(): RecentModelsState {
  if (typeof window === 'undefined') return load();
  let raw: string | null = null;
  try {
    raw = window.localStorage.getItem(storageKey());
  } catch {
    return load();
  }
  if (raw === null) return load();
  try {
    return sanitize(JSON.parse(raw));
  } catch {
    return load();
  }
}

/** 两份状态在用户可见语义上是否一致(副本身份 + 时间 + 顺序)。 */
function sameState(a: RecentModelsState, b: RecentModelsState): boolean {
  return (
    a.items.length === b.items.length &&
    a.items.every((item, i) => {
      const other = b.items[i];
      return (
        other !== undefined &&
        modelConfigCopyIdentity(item) === modelConfigCopyIdentity(other) &&
        item.usedAt === other.usedAt
      );
    })
  );
}

// ── 可重放的写操作(见文件头「并发写」)────────────────────────────────────

/** 一次「这份配置在此时被用过」的断言。只依赖自身 + 目标状态,重放才成立。 */
type RecentModelsOp = RecentModelItem;

/**
 * 把一条记录并入状态:同副本身份取 max(usedAt),移到队首,按时间倒序并裁剪。
 * **无实际变化时返回入参对象本身**(引用判等决定要不要落盘 / 这一轮是否真的断言了什么)。
 */
function applyOp(state: RecentModelsState, op: RecentModelsOp): RecentModelsState {
  const item = normalizeItem(op);
  if (!item) return state;
  const key = modelConfigCopyIdentity(item);
  const existing = state.items.find((entry) => modelConfigCopyIdentity(entry) === key);
  const usedAt = existing ? Math.max(existing.usedAt, item.usedAt) : item.usedAt;
  const rest = state.items.filter((entry) => modelConfigCopyIdentity(entry) !== key);
  const next: RecentModelsState = {
    items: [{ ...item, usedAt }, ...rest]
      .sort((a, b) => b.usedAt - a.usedAt)
      .slice(0, RECENT_MODELS_KEEP),
  };
  return sameState(state, next) ? state : next;
}

/**
 * op-log 的归并:同一副本身份的历史 op 折成一条 —— 否则整条 log 重放时,先录的旧 usedAt
 * 会被再次并入(虽然取 max 不会把时间改小,但会让「这次记录」在 log 里出现两遍,
 * 无谓地占用 TTL / 断言次数)。
 * 时间更旧的 op(时钟回拨 / 跨窗口乱序)直接放弃:重放不能把已有记录的时间往回拧。
 */
function compactRecentOps(
  log: readonly RecentModelsOp[],
  op: RecentModelsOp,
): readonly RecentModelsOp[] {
  const key = modelConfigCopyIdentity(op);
  const existing = log.find((entry) => modelConfigCopyIdentity(entry) === key);
  if (existing && existing.usedAt > op.usedAt) return log;
  return [...log.filter((entry) => modelConfigCopyIdentity(entry) !== key), op];
}

const reconciler = createStorageReconciler<RecentModelsState, RecentModelsOp>({
  // active 分区走 freshState(带「读不出来就退回内存缓存」的兜底);其它分区(登出 / 切号后的
  // 旧 key)按 key 直读。
  read: (key) => (key === storageKey() ? freshState() : loadFromKey(key)),
  apply: applyOp,
  persist: (key, state) => persistTo(key, state),
  adopt: (key, state) => {
    if (key !== storageKey()) return;
    if (sameState(cache ?? emptyState(), state)) return;
    cache = state;
    emit();
  },
  compact: compactRecentOps,
});

/**
 * 两份状态取并集:同一副本身份取 max(usedAt),按时间倒序并裁到 KEEP 条。
 * 只增不减(本 store 没有删除类 op)—— 把「本窗已记但没落盘」的条目并回写基底。
 * 没有新身份 / 时间没前进时**返回入参对象本身**,调用方据此判断要不要落盘。
 */
function mergeState(base: RecentModelsState, extra: RecentModelsState | null): RecentModelsState {
  if (!extra || extra.items.length === 0) return base;
  const byKey = new Map(base.items.map((item) => [modelConfigCopyIdentity(item), item]));
  let changed = false;
  for (const item of extra.items) {
    const key = modelConfigCopyIdentity(item);
    const existing = byKey.get(key);
    if (!existing) {
      byKey.set(key, item);
      changed = true;
      continue;
    }
    if (item.usedAt > existing.usedAt) {
      byKey.set(key, item);
      changed = true;
    }
  }
  if (!changed) return base;
  return {
    items: [...byKey.values()].sort((a, b) => b.usedAt - a.usedAt).slice(0, RECENT_MODELS_KEEP),
  };
}

/**
 * 一次写入 = **同步乐观写**(热更强退不丢)+ 把 op 记进**当时那个 key** 的会话 op-log 并调度
 * 一次锁内调和。owner 随后被切走也不放弃调和 —— 调和按捕获的 key 自洽运行。
 *
 * 写基底 = **磁盘真相 ∪ 本窗内存态**(2026-09-16 review P2):上一次写若失败(配额 / 私密
 * 窗口),那条记录只活在本窗内存里,而 `freshState()` 只按 key 读回磁盘 —— 拿它当基底再写一次
 * 会把「刚记下但没落盘」的那条顺手抹掉(磁盘上有旧快照时尤其明显)。并集只增不减,重复写无害。
 */
function commitOp(op: RecentModelsOp): void {
  const base = mergeState(freshState(), cache);
  const next = applyOp(base, op);
  if (next !== base) persist(next);
  const key = storageKey();
  reconciler.record(key, op);
  reconciler.schedule(key);
}

// ── 订阅(供 useSyncExternalStore)──────────────────────────────────────────
const listeners = new Set<() => void>();

function emit(): void {
  for (const listener of listeners) listener();
}

/**
 * 落盘到**指定 key**。缓存与通知只在该 key 恰是当前 active 分区时才做(调和可能发生在
 * 登出 / 切号之后的旧分区上)。
 */
function persistTo(key: string, next: RecentModelsState): void {
  if (typeof window !== 'undefined') {
    try {
      // 同步写:见文件头(热更 relaunch 走 app.exit() 强退)。
      window.localStorage.setItem(key, JSON.stringify(next));
    } catch {
      // localStorage 满 / 私密窗口禁写 —— 静默吞,内存态仍生效。
    }
  }
  if (key !== storageKey()) return;
  cache = next;
  emit();
}

function persist(next: RecentModelsState): void {
  persistTo(storageKey(), next);
}

function subscribe(listener: () => void): () => void {
  listeners.add(listener);
  return () => {
    listeners.delete(listener);
  };
}

function getItemsSnapshot(): readonly RecentModelItem[] {
  return load().items;
}

let removeStorageListener: (() => void) | null = null;

/**
 * 把 storage 事件订阅绑到**当前** window 上。模块导入时绑一次;
 * `__resetForTest` 里解绑后重绑 —— 测试会在模块导入后才替换 window stub,
 * 不重绑的话监听器永远挂在旧 stub 上,跨窗口用例收不到事件。
 */
function bindStorageListener(): void {
  if (removeStorageListener) return;
  if (typeof window === 'undefined' || typeof window.addEventListener !== 'function') return;
  // 绑定时捕获 window:解绑必须对**同一对象**;测试的 stub window 不一定有 removeEventListener。
  const boundWindow: Window = window;
  /** 本 owner 分区的内存态跟外来写入对齐(重读真相,不采信 event.newValue)。 */
  const refreshActive = (): void => {
    const next = loadFromStorage();
    if (sameState(cache ?? emptyState(), next)) return;
    cache = next;
    emit();
  };
  const onStorage = (event: StorageEvent): void => {
    if (event.storageArea && event.storageArea !== window.localStorage) return;
    // key === null 表示 storage.clear():本分区刷新,并让所有还有 op-log 的分区各自调和。
    if (event.key === null) {
      refreshActive();
      for (const key of reconciler.loggedKeys()) reconciler.schedule(key);
      return;
    }
    if (event.key === storageKey()) {
      refreshActive();
      // 外来写入可能正是「别窗用旧基底做的迟到覆盖」,抹掉了本窗刚记的 op:
      // 在锁内把本分区的整条 op-log 重新断言一遍,无差异即终止。
      reconciler.schedule(event.key);
      return;
    }
    // 非 active 分区:只要 op-log 里还有它的记录就照样调和。
    if (reconciler.hasOps(event.key)) reconciler.schedule(event.key);
  };
  boundWindow.addEventListener('storage', onStorage);
  removeStorageListener = () => {
    if (typeof boundWindow.removeEventListener === 'function') {
      boundWindow.removeEventListener('storage', onStorage);
    }
  };
}

bindStorageListener();

if (import.meta.hot) {
  import.meta.hot.dispose(() => {
    removeStorageListener?.();
    removeStorageListener = null;
  });
}

/** 读全部记录(usedAt 倒序,含当前不可路由的条目 —— 过滤是面板的事)。数组视为只读。 */
export function listRecentModels(): readonly RecentModelItem[] {
  return getItemsSnapshot();
}

/**
 * 记一次「用了这份配置」。非法入参静默 no-op(与收藏同一条防线)。
 * `now` 只给测试注入用:生产路径一律取当前时刻。
 */
export function recordRecentModel(config: ModelConfigCopy, now: number = Date.now()): void {
  const item = normalizeItem({ ...config, usedAt: now });
  if (!item) return;
  commitOp(item);
}

/** 订阅变更(非 React 调用方)。 */
export function subscribeRecentModels(listener: () => void): () => void {
  return subscribe(listener);
}

/**
 * React hook —— 记录列表快照。数组身份只在真正写入 / 跨窗口同步时变化,
 * 可直接进 useMemo 依赖(useSyncExternalStore 保证 StrictMode 双 render 安全)。
 */
export function useRecentModels(): readonly RecentModelItem[] {
  return useSyncExternalStore(subscribe, getItemsSnapshot, getItemsSnapshot);
}

/** 随当前数据归属账号切换持久化命名空间(与 setModelFavoritesOwner 同形)。 */
export function setRecentModelsOwner(ownerId: string | null): void {
  const normalized = typeof ownerId === 'string' && ownerId.trim().length > 0 ? ownerId : null;
  if (activeDataOwnerId === normalized) return;
  activeDataOwnerId = normalized;
  cache = null;
  emit();
}

/**
 * 当前分区归属(可能为 null = 未登录 / 本地模式)。调用方在**发起异步选择时**捕获它,回调落地
 * 前再比一次 —— 归属变了就不能把记录写进新分区(`xdt:recentModels:v1:<dataOwnerId>`)。
 */
export function getRecentModelsOwner(): string | null {
  return activeDataOwnerId;
}

/** 测试用 —— 重置缓存 / owner / 订阅者 / op-log + 清 localStorage(其它代码不应调用)。 */
export function __resetForTest(): void {
  const keyBeforeReset = storageKey();
  cache = null;
  listeners.clear();
  reconciler.__resetForTest();
  if (typeof window !== 'undefined') {
    try {
      window.localStorage.removeItem(keyBeforeReset);
      window.localStorage.removeItem(STORAGE_KEY);
    } catch {
      // ignore
    }
  }
  activeDataOwnerId = null;
  // 解绑后重绑到当前 window:测试在导入后才换 window stub,不重绑跨窗口用例收不到事件。
  removeStorageListener?.();
  removeStorageListener = null;
  bindStorageListener();
}

export const __STORAGE_KEY = STORAGE_KEY;