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。

13.4 KB
Raw Blame
/**
 * botSettingsAutosave — Bot 设置页「静默自动保存」的纯逻辑内核。
 *
 * 背景:设置页原本是「改完自己点底部保存条」,实测里用户根本不知道有保存这回事,
 * 改了好几轮全部丢掉。裁决是**用户不该知道有保存这回事**:改动自动落库,保存条删除。
 *
 * 本文件只负责调度与脏检查语义,不碰 React,也不碰 IPC —— 这样可以用 fake timers
 * 直接测「burst 合并成一次」「无变化不发 IPC」「离开时冲刷」「失败可重试」,而不必
 * 挂载整个设置页。React 侧的粘合在 useBotSettingsAutosave.ts。
 *
 * 核心语义:
 *  - schedule('text'):文本输入,防抖(每次调用重置计时)。连续打字期间永不提交。
 *  - schedule('instant'):开关 / 下拉 / 头像等离散选择,**走同一条合并通道**但用极短
 *    窗口(默认 0ms),同一 tick 的连续切换仍并成一次提交。已有 instant 在等时,
 *    后续的 'text' 不再把计时推后 —— 离散选择要求尽快落库,顺路带上刚打的字即可。
 *  - 脏检查:提交前把「当前归一化快照」与「上次成功保存的快照」深比较,相等直接
 *    返回 idle,不发 IPC。主进程侧虽然内容未变不会升版本,但白发一次 IPC 仍是噪音。
 *  - 串行化:同一时刻只有一次提交在途。计时到期撞上在途提交时**等它结束再重判脏**
 *    (trailing save),而不是丢弃 —— 否则最后一批修改会悬挂到用户下次输入。
 *  - flush():显式边界(blur / 返回聊天)冲刷,返回可 await 的 Promise。
 *  - flushDetached():卸载 / 切 bot 时冲刷。同步发出 IPC 后立刻返回,并停止一切状态
 *    回调(组件已经不在了)。
 */

import type { BotCapabilities, BotProfileUpdatePatch } from './botStore';
import { reconcileBotCapabilityList } from '../../../shared/botCapabilitySelection';

/** 提交给 `updateBotProfile` 的字段集合(与手动保存时的载荷完全一致)。 */
export interface BotSettingsPayload {
  name: string;
  description: string;
  identitySource: string;
  userContextSource: string;
  avatar: string;
  avatarColor: string;
  capabilities: BotCapabilities;
  skills: string[];
}

/** 设置页里被编辑的原始表单值(未做 trim / 兜底)。 */
export interface BotSettingsDraft {
  name: string;
  description: string;
  identitySource: string;
  userContextSource: string;
  avatar: string;
  avatarColor: string;
  capabilities: BotCapabilities;
  skills: string[];
}

/**
 * 归一化成待提交载荷。
 *
 * `fallbackName` 沿用手动保存时的兜底:名字被清空时提交 bot 现有名字,而不是空串。
 * 归一化必须是「基线」与「当前值」共用的同一个函数 —— 否则挂载瞬间
 * `description` 前后有空格就会被判成脏,页面一打开就白写一次(归档 bot 尤其不能写)。
 */
export function normalizeBotSettingsPayload(
  draft: BotSettingsDraft,
  fallbackName: string,
): BotSettingsPayload {
  // The host trims every profile text; compare the same way so a space or line
  // break still being typed is neither a change nor a reason to save again.
  return {
    name: draft.name.trim() || fallbackName,
    description: draft.description.trim(),
    identitySource: draft.identitySource.trim(),
    userContextSource: draft.userContextSource.trim(),
    avatar: draft.avatar,
    avatarColor: draft.avatarColor,
    capabilities: draft.capabilities,
    skills: draft.skills,
  };
}

function stringListEqual(a: readonly unknown[], b: readonly unknown[]): boolean {
  if (a.length !== b.length) return false;
  for (let index = 0; index < a.length; index += 1) {
    if (!capabilityValueEqual(a[index], b[index])) return false;
  }
  return true;
}

function capabilityValueEqual(a: unknown, b: unknown): boolean {
  if ((a ?? null) === (b ?? null)) return true;
  if (Array.isArray(a) || Array.isArray(b)) {
    return Array.isArray(a) && Array.isArray(b) && stringListEqual(a, b);
  }
  if (
    typeof a === 'object'
    && a !== null
    && typeof b === 'object'
    && b !== null
  ) {
    const left = a as Record<string, unknown>;
    const right = b as Record<string, unknown>;
    const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
    for (const key of keys) {
      if (!capabilityValueEqual(left[key], right[key])) return false;
    }
    return true;
  }
  return false;
}

/**
 * 比较 capabilities。按 key 并集遍历而不是逐字段写死:`BotCapabilities` 后续加字段
 * 时脏检查会自动覆盖,否则新字段会静默永远「不脏」,改了不保存 —— 正是本次要修的病。
 * `providerId` 允许 `null` 与 `undefined` 混用,两者视为同一个「没有」,避免仅因
 * 来源不同(store 归一化 vs 本地 state)产生幻影脏。
 */
export function botCapabilitiesEqual(a: BotCapabilities, b: BotCapabilities): boolean {
  const keys = new Set<string>([...Object.keys(a), ...Object.keys(b)]);
  for (const key of keys) {
    const left = (a as unknown as Record<string, unknown>)[key];
    const right = (b as unknown as Record<string, unknown>)[key];
    if (!capabilityValueEqual(left, right)) return false;
  }
  return true;
}

export function botSettingsPayloadEqual(a: BotSettingsPayload, b: BotSettingsPayload): boolean {
  return (
    a.name === b.name &&
    a.description === b.description &&
    a.identitySource === b.identitySource &&
    a.userContextSource === b.userContextSource &&
    a.avatar === b.avatar &&
    a.avatarColor === b.avatarColor &&
    stringListEqual(a.skills, b.skills) &&
    botCapabilitiesEqual(a.capabilities, b.capabilities)
  );
}

/** Send only edited fields, preserving capabilities joined concurrently by the companion. */
export function botSettingsChanges(previous: BotSettingsPayload, next: BotSettingsPayload, includeCapabilityBaseline = false): BotProfileUpdatePatch {
  const { capabilities, ...values } = next;
  const changed = Object.fromEntries(Object.entries(values).filter(([key, value]) =>
    !capabilityValueEqual(value, previous[key as keyof typeof values])));
  const capabilityChanges = Object.fromEntries(Object.entries(capabilities).filter(([key, value]) =>
    !capabilityValueEqual(value, previous.capabilities[key as keyof BotCapabilities])));
  const capabilityBaseline = {
    ...('skills' in changed ? { skills: previous.skills } : {}),
    ...('mcpServers' in capabilityChanges ? { mcpServers: previous.capabilities.mcpServers } : {}),
    ...('toolsets' in capabilityChanges ? { toolsets: previous.capabilities.toolsets } : {}),
  };
  return {
    ...changed,
    ...(Object.keys(capabilityChanges).length ? { capabilities: capabilityChanges } : {}),
    ...(includeCapabilityBaseline && Object.keys(capabilityBaseline).length ? { capabilityBaseline } : {}),
  };
}

const BOT_SETTINGS_TEXT_FIELDS = ['name', 'description', 'identitySource', 'userContextSource'] as const;

/** Advance untouched fields to a live profile without discarding pending local edits. */
export function reconcileBotSettingsDraft(
  baseline: BotSettingsPayload,
  draft: BotSettingsDraft,
  incoming: BotSettingsPayload,
): BotSettingsDraft {
  const normalized = normalizeBotSettingsPayload(draft, baseline.name);
  const changes = botSettingsChanges(baseline, normalized);
  // Text that only differs from the saved copy by surrounding whitespace is the
  // user mid-typing (a trailing space or new line); keep it instead of the trimmed copy.
  const typedWhitespace = Object.fromEntries(BOT_SETTINGS_TEXT_FIELDS
    .filter((key) => draft[key] !== incoming[key] && draft[key].trim() === incoming[key])
    .map((key) => [key, draft[key]]));
  return {
    ...incoming,
    ...typedWhitespace,
    ...Object.fromEntries(Object.keys(changes)
      .filter((key) => key !== 'capabilities')
      .map((key) => [key, draft[key as keyof BotSettingsDraft]])),
    skills: reconcileBotCapabilityList(baseline.skills, draft.skills, incoming.skills),
    capabilities: {
      ...incoming.capabilities,
      ...changes.capabilities,
      mcpServers: reconcileBotCapabilityList(baseline.capabilities.mcpServers, draft.capabilities.mcpServers, incoming.capabilities.mcpServers),
      toolsets: reconcileBotCapabilityList(baseline.capabilities.toolsets, draft.capabilities.toolsets, incoming.capabilities.toolsets),
    },
  };
}

/** 自动保存对用户可见的状态。`saved` 由 UI 侧短暂显示后淡出,不常驻。 */
export type BotAutosaveStatus = 'idle' | 'saving' | 'saved' | 'error';

/** 触发来源:文本输入走防抖,离散选择(开关 / 下拉 / 头像)走即时合并窗口。 */
export type BotAutosaveTrigger = 'text' | 'instant';

export interface BotSettingsAutosaveOptions {
  /** 文本输入的防抖窗口,默认 1200ms。 */
  textDelayMs?: number;
  /** 离散选择的合并窗口,默认 0ms(同一 tick 的连续切换仍并成一次)。 */
  instantDelayMs?: number;
  /** 读取当前归一化快照。 */
  readPayload: () => BotSettingsPayload;
  /** 读取上次成功保存的快照(基线)。成功提交后由 commit 侧推进。 */
  readBaseline: () => BotSettingsPayload;
  /** 真正提交(IPC)。resolve = 已落库(此时 commit 侧应已推进基线);reject = 失败。 */
  commit: (payload: BotSettingsPayload) => Promise<void>;
  /** 状态变化回调。dispose 之后不再触发。 */
  onStatusChange?: (status: BotAutosaveStatus) => void;
}

export interface BotSettingsAutosaveHandle {
  /** 字段变化时调用,把这次变化并入待提交 burst。 */
  schedule(trigger: BotAutosaveTrigger): void;
  /** 显式边界冲刷(blur / 返回聊天)。无变化时是 no-op。 */
  flush(): Promise<void>;
  /** 失败后重发。等价于一次立即 flush。 */
  retry(): Promise<void>;
  /** 卸载 / 切 bot:同步发出未落的提交并停止状态回调。幂等。 */
  flushDetached(): void;
  /** 取消未触发的计时,不提交。 */
  cancel(): void;
  /** 是否有已改但未落库的内容。 */
  isDirty(): boolean;
}

export function createBotSettingsAutosave(
  options: BotSettingsAutosaveOptions,
): BotSettingsAutosaveHandle {
  const textDelayMs = options.textDelayMs ?? 1200;
  const instantDelayMs = options.instantDelayMs ?? 0;

  let timer: ReturnType<typeof setTimeout> | null = null;
  /** 是否有「离散选择」在等 —— 它不允许被后续文本输入推后。 */
  let instantPending = false;
  let inFlight: Promise<void> | null = null;
  let detached = false;

  const emit = (status: BotAutosaveStatus): void => {
    if (detached) return;
    options.onStatusChange?.(status);
  };

  const clearTimer = (): void => {
    if (timer !== null) {
      clearTimeout(timer);
      timer = null;
    }
    instantPending = false;
  };

  const isDirty = (): boolean =>
    !botSettingsPayloadEqual(options.readPayload(), options.readBaseline());

  const runNow = async (): Promise<void> => {
    clearTimer();
    while (inFlight) {
      // 撞上在途提交:等它结束再重判脏(trailing save),不丢这一批修改。
      // 多个 blur/flush 同时等待时,先醒来的调用可能已开始下一次保存。
      await inFlight.catch(() => undefined);
    }
    if (detached) return;
    const payload = options.readPayload();
    if (botSettingsPayloadEqual(payload, options.readBaseline())) {
      // 无实际变化 —— 不发 IPC。
      return;
    }
    emit('saving');
    // 从这里到 `inFlight = attempt` 之间没有 await,不会有第二个 runNow 插进来
    // 看到 inFlight 为 null 而重复提交同一份 payload。
    const attempt = (async () => {
      try {
        await options.commit(payload);
        emit(isDirty() ? 'idle' : 'saved');
      } catch {
        emit('error');
      }
    })();
    inFlight = attempt;
    await attempt;
    if (inFlight === attempt) inFlight = null;
  };

  const fire = (): void => {
    timer = null;
    instantPending = false;
    void runNow();
  };

  return {
    schedule(trigger) {
      if (detached) return;
      if (trigger === 'instant') {
        if (timer !== null) clearTimeout(timer);
        instantPending = true;
        timer = setTimeout(fire, instantDelayMs);
        return;
      }
      // 已有离散选择在等:让它按原定时刻提交,顺路带上刚输入的文本。
      if (instantPending) return;
      if (timer !== null) clearTimeout(timer);
      timer = setTimeout(fire, textDelayMs);
    },
    flush() {
      if (detached) return Promise.resolve();
      return runNow();
    },
    retry() {
      if (detached) return Promise.resolve();
      return runNow();
    },
    flushDetached() {
      if (detached) return;
      clearTimer();
      const payload = options.readPayload();
      const dirty = !botSettingsPayloadEqual(payload, options.readBaseline());
      // 先断开状态回调:组件正在卸载,任何 setState 都是无主的。
      detached = true;
      if (!dirty) return;
      if (inFlight) {
        // 在途提交发的是更早的快照,不能拿它当「已落库」。等它结束后补发一次,
        // 否则「改完立刻返回聊天」这一下正好撞上在途保存就会丢最后一批修改。
        void inFlight
          .catch(() => undefined)
          .then(() => {
            const trailing = options.readPayload();
            if (botSettingsPayloadEqual(trailing, options.readBaseline())) return;
            return options.commit(trailing).catch(() => undefined);
          });
        return;
      }
      void options.commit(payload).catch(() => undefined);
    },
    cancel() {
      clearTimer();
    },
    isDirty,
  };
}