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。

18.0 KB
Raw Blame
/**
 * effortResolution —— 「选中模型 / 切换来源后应落到哪一档 effort」的纯逻辑(跨端共享)。
 *
 * 从 apps/desktop renderer 的 sourceSwitch.ts 原样下沉:桌面 ModelSelector / ChatInput 与
 * 手机版模型选择列表都要用同一套落档优先级,避免两端各写一套后口径发散(手机对齐桌面的
 * 「逻辑完全相同」承诺依赖这里的单一实现)。语义与函数签名保持与桌面历史版本逐字一致。
 *
 * 类型注:参数用 `string` 而非本包的 `Effort` 字面量联合 —— 桌面 renderer 的 Effort 就是
 * `string` 别名(userPreferences.types),catalog 侧才是严格联合;两端都要直接消费本函数,
 * 取二者的公共形状。运行时语义只依赖「候选值 ∈ efforts」的成员判断,与联合收窄无关。
 */

type Effort = string;

/** Model-level intent, independent of the consuming harness. Old catalogs sometimes put
 * their defaults inside perAgent; promote their shared value or the lowest declared
 * depth on conflict. This keeps legacy members usable without picking a harness or
 * silently increasing effort. An explicit model-level null also wins.
 */
export function modelDefaultEffort(model: {
  defaultEffort?: Effort | null;
  perAgent?: Partial<Record<string, { defaultEffort?: Effort | null }>>;
}): Effort | null | undefined {
  if (model.defaultEffort !== undefined) return model.defaultEffort;
  const legacy = [...new Set(Object.values(model.perAgent ?? {})
    .flatMap((override) => override?.defaultEffort !== undefined ? [override.defaultEffort] : []))];
  if (legacy.length <= 1) return legacy[0];
  return lowestEffort(legacy.filter((effort): effort is string => effort !== null));
}

/** Default for a newly discovered model with no Cindy declaration. This is product
 * policy, not a clamp for explicit user choices: prefer medium and never invent support.
 */
export function defaultEffortForCapabilities<T extends string>(efforts: readonly T[]): T | null {
  for (const preferred of ['medium', 'high', 'low', 'xhigh', 'max', 'minimal', 'ultra']) {
    const supported = efforts.find((effort) => effort === preferred);
    if (supported !== undefined) return supported;
  }
  return efforts[0] ?? null;
}

/**
 * 解析「选中某模型后应落到哪一档 effort」—— 纯函数,集中 effort 优先级策略。
 *
 * 优先级(高 → 低),每一档都要求候选值仍在 `efforts` 列表里(不同模型 effort 档不同,旧值可能非法):
 *   0. 模型无 effort 档(efforts 为空)→ 'low'(占位,UI 不显示 effort segmented)。
 *   1. preferred:切来源时由 resolveSourceSwitch 带回的落点 hint(目标来源 lastModel 的 effort)。
 *   2. providerEffort:调用方提供的模型预设(桌面端现为 (agent, model) 全局预设;参数名为兼容保留)。
 *   3. rememberedEffort:per-model 记忆(provider 无关,跨来源兜底;手机端无此存储,恒不传)。
 *   4. activeEffort:当前 effort 仍被目标模型支持 → 沿用(切模型时少打扰用户)。
 *   5. 模型默认 defaultEffort(仍需 ∈ efforts;非法/缺失时落 efforts 首档)。
 *
 * 注:之所以用代码而非 prompt 固化这套优先级(规则 9),是为了让「选回来恢复上次选择」可预测、
 * 可单测。本函数只负责「在给定 efforts 下挑哪一档」,模型 efforts 由调用方按 catalog 提供。
 */
export function resolveEffort(args: {
  efforts: readonly Effort[];
  defaultEffort: Effort | null;
  activeEffort: Effort;
  preferred?: Effort;
  providerEffort?: Effort;
  rememberedEffort?: Effort;
}): Effort {
  const { efforts, defaultEffort, activeEffort, preferred, providerEffort, rememberedEffort } = args;
  if (efforts.length === 0) return 'low';
  const ok = (e: Effort | undefined): e is Effort => !!e && efforts.includes(e);
  if (ok(preferred)) return preferred;
  if (ok(providerEffort)) return providerEffort;
  if (ok(rememberedEffort)) return rememberedEffort;
  if (efforts.includes(activeEffort)) return activeEffort;
  // defaultEffort 同样要求 ∈ efforts(catalog 病态数据防御):非法/缺失时落 efforts 首档,
  // efforts.length === 0 已在上方 early return,这里 efforts[0] 必然存在。
  if (ok(defaultEffort ?? undefined)) return defaultEffort as Effort;
  return efforts[0];
}

/**
 * 面板 / 收藏交出来的**显式档** vs 本端再查一遍目录。
 *
 * `resolveEffort` 在 efforts 为空时回落占位 `'low'`。那是「模型不可调档」的 UI 占位,
 * 不能拿来消化一次查找失败:统一选择器已经按目标引擎解析过这一档(收藏副本、行上
 * 显示的 high),本端若因 wire id 形态(Pi `grok-4.6` vs 订阅 `xai/grok-4.6`)查空,
 * 再走 `resolveEffort` 就会把用户点的 high 写成 low。
 *
 * 面板只在 `config.effort` 非空时才把档交出来(不可调档行传空串,进不了 requested),
 * 所以查空时信任 requested 不会给「真的没有档位的模型」塞一个假档。
 *
 * 目录非空且不含 requested → 不硬塞,回落 `resolveEffort`(目标引擎词表里没有这一档,
 * 例如 xhigh 落到只有 high 的模型)。
 */
export function resolveRequestedEffort(args: {
  requested?: Effort;
  efforts: readonly Effort[];
  defaultEffort: Effort | null;
  activeEffort: Effort;
  preferred?: Effort;
  providerEffort?: Effort;
  rememberedEffort?: Effort;
}): Effort {
  const { requested, efforts, ...rest } = args;
  if (requested && (efforts.length === 0 || efforts.includes(requested))) {
    return requested;
  }
  return resolveEffort({ efforts, ...rest });
}

/**
 * 远程(device-link)切模时的**展示档**:目录未知时不要展示占位档。
 *
 * `resolveRequestedEffort` 在目录为空时给 UI 占位 `'low'`(模型不可调档)。但远程切模时
 * 目录为空还有第二种解释:被控端 `provider:list` 尚未回流、旧被控端不支持该通道、或控制端
 * 镜像只聚合 cc+codex(pi 常查空)。此时把占位档当真实选择会直接渲染成「低」。
 * 目录未知就展示会话当前档,等投影回流后自然收敛。
 *
 * 注意:这是显示/记忆语义,**不要**把返回值当显式档发给被控端——被控端对显式档
 * 按目标目录硬校验(`effort-unavailable`),当前档不在目标目录里会让整个切模失败。
 */
export function resolveRemoteSwitchEffort(args: {
  efforts: readonly Effort[];
  requested: Effort;
  currentEffort: Effort;
}): Effort {
  return args.efforts.length > 0 ? args.requested : args.currentEffort;
}

/**
 * 点选时交给 SET_MODEL 的原子快照。
 *
 * `resolveEffort` 在无档模型上会给 UI 占位 `'low'`。那一档不能写进运行时:
 * 目录 `efforts` 为空的模型运行时语义是 `effort: null`,塞 low 会让胶囊显示
 * thinking low/high,实际模型却没有思考档。Fast 同样:不支持就必须是 false,
 * 不能把上一模型的插队状态带到新模型上。
 */
export function composeAtomicModelSelection(args: {
  efforts: readonly Effort[];
  effort: Effort;
  fastSupported: boolean;
  requestedFast: boolean | 'ultrafast';
}): { effort: Effort | null; fastMode: boolean | 'ultrafast' } {
  return {
    effort: args.efforts.length === 0 ? null : args.effort,
    fastMode: args.fastSupported && args.requestedFast,
  };
}

/**
 * 意图期内改选模型/来源时,面板交出来的档 vs 旧意图档。
 *
 * ModelSelector 对无思考档的行传空串(`rowEffortOf ?? ''`)。空串是「目标明确没有可调档」,
 * 不能当成 falsy 再回落到旧意图的 high —— 否则会把目标不支持的档登记进意图、下次发送应用。
 * 调用方没给新档(`undefined`)时才继承旧意图。
 */
export function resolveIntentReselectEffort(
  selectedEffort: string | undefined,
  intentEffort?: string,
): string | undefined {
  if (typeof selectedEffort === 'string') {
    return selectedEffort || undefined;
  }
  return intentEffort || undefined;
}

/**
 * 「同模型只切来源」时落档。与 resolveEffort 的关键区别是没有 activeEffort 沿用档:
 * 有显式模型预设就按目标来源支持范围恢复;没有预设则回落模型默认,避免把当前会话 live 值
 * 意外写成全局默认。
 *
 * 优先级(高 → 低,每档都要求仍在 efforts 内):
 *   1. preferred:来源切换 hint(resolveSourceSwitch 带回的目标来源记忆档);当前 picker 行点击
 *      不传,保留以兼容未来带 hint 的调用方。
 *   2. providerEffort:调用方提供的模型预设(桌面端跨来源共享,再由 efforts 校验是否合法)。
 *   3. 模型默认 defaultEffort。
 *   4. efforts 首档。
 *   5. fallbackEffort:efforts 为空等极端兜底(通常 = 当前 activeEffort,该模型无 effort 档、UI 不显示)。
 */
export function resolveProviderSwitchEffort(args: {
  efforts: readonly Effort[];
  defaultEffort: Effort | null;
  providerEffort?: Effort;
  preferred?: Effort;
  fallbackEffort: Effort;
}): Effort {
  const { efforts, defaultEffort, providerEffort, preferred, fallbackEffort } = args;
  if (efforts.length === 0) return fallbackEffort;
  const ok = (e: Effort | undefined): e is Effort => !!e && efforts.includes(e);
  if (ok(preferred)) return preferred;
  if (ok(providerEffort)) return providerEffort;
  if (ok(defaultEffort ?? undefined)) return defaultEffort as Effort;
  return efforts[0];
}

/**
 * effort 全档位的**单一来源**(序即强弱序,低 → 高)。types.ts 的 `Effort` 字面量联合与此
 * 逐项对应,由下方类型级断言在包内锁死双向一致(改任一边不改另一边 → 编译失败)。
 * 历史上这份枚举在 imDefaultSettings / title-one-shot(EFFORT_RANK)/ active-catalog
 * (VALID_EFFORTS)等处有 6 份字面量副本,P2-P4 分期改为从这里派生。
 */
export const EFFORT_VALUES = [
  'minimal',
  'low',
  'medium',
  'high',
  'xhigh',
  'max',
  'ultra',
] as const;

// 类型级双向锁: EFFORT_VALUES ⊆ types.Effort 且 types.Effort ⊆ EFFORT_VALUES。
// (本文件的运行时 Effort 故意是 string 别名 —— 见文件头;锁只针对目录侧联合。)
type CatalogEffort = import('./types.js').Effort;
type _EffortValuesCoverUnion = CatalogEffort extends (typeof EFFORT_VALUES)[number]
  ? true
  : ['EFFORT_VALUES 缺少 types.Effort 的档位', CatalogEffort];
type _EffortValuesNoExtra = (typeof EFFORT_VALUES)[number] extends CatalogEffort
  ? true
  : ['EFFORT_VALUES 含 types.Effort 没有的档位'];
const _effortEnumLock: [_EffortValuesCoverUnion, _EffortValuesNoExtra] = [true, true];
void _effortEnumLock;

const EFFORT_ORDER: readonly Effort[] = EFFORT_VALUES;

/** effort 强弱序名次(低 → 高);未知档排在最高之上(保守不上调)。 */
export function effortRank(e: Effort): number {
  const i = EFFORT_ORDER.indexOf(e);
  return i === -1 ? EFFORT_ORDER.length : i;
}

/** 取一组 effort 里的最低档;空 → null。(title-one-shot 的 EFFORT_RANK/lowestEffort 收口。) */
export function lowestEffort(efforts: readonly Effort[]): Effort | null {
  if (!efforts.length) return null;
  // 线性取最小(严格小于:平级保留先出现者,与原 copy+稳定 sort 语义一致,省 O(n log n)+拷贝)。
  let best = efforts[0];
  for (const e of efforts) {
    if (effortRank(e) < effortRank(best)) best = e;
  }
  return best;
}

/**
 * 把请求的 effort clamp 到某模型「实际声明支持」的档位 —— 供**未门控入口**(定时任务
 * fire、跨 agent worker 创建等)在发到运行时前做安全 reconcile,避免把模型不支持的档
 * (如 gpt-5.5 + max/ultra)透给上游被拒(issue #456)。
 *
 * 口径与交互式 UI 一致:**模型已声明支持的档原样保留**(不降级 —— 保 issue #352「不静默
 * 降级用户在支持模型上的显式选择」);只有不受支持时才 clamp 到最高兼容档。
 *
 * 规则:
 *   - `effort` 为空(null/undefined/空串)→ 原样返回(调用方语义:留空 = 不改)。
 *   - `efforts` 空/缺失 → 原样返回(模型未声明 effort 门控,不动它,no-break)。
 *   - `effort ∈ efforts` → 原样(支持则不动)。
 *   - 否则 clamp 到「rank ≤ 请求档 的最高受支持档」。
 *   - 请求档低于全部受支持档 → 最低受支持档(floor;绝不上调,见下方注释)。
 */
export function clampEffortToSupported(
  effort: Effort | null | undefined,
  efforts: readonly Effort[] | undefined,
): Effort | null | undefined {
  // falsy(null / undefined / 空串)一律透传:空串不在 EFFORT_ORDER 内,若不在此拦下会被
  // 当成"未知档"(rank 最高)clamp 到模型最高受支持档 —— 与"留空 = 不改"的语义相反(#456 review)。
  if (!effort) return effort;
  if (!efforts || efforts.length === 0) return effort;
  if (efforts.includes(effort)) return effort;

  const wantRank = effortRank(effort);
  // 受支持档里挑「rank ≤ 请求档」的最高档(clamp down 到最高兼容档)。
  let best: Effort | undefined;
  let bestRank = -1;
  for (const e of efforts) {
    const r = effortRank(e);
    if (r <= wantRank && r > bestRank) {
      best = e;
      bestRank = r;
    }
  }
  if (best !== undefined) return best;

  // 请求档低于全部受支持档(如 minimal 落在只支持 low+ 的模型)→ clamp 到最低受支持档(floor)。
  // 绝不上调到模型默认:请求档比 floor 还低时上调 = 违背用户"尽量便宜"的意图,且会把存量
  // 定时任务里存的 minimal 静默升成 default(通常 high)—— codex 旧行为是 minimal→low,
  // reconcile 不该反而把它升级(#456 review)。
  let lowest: Effort = efforts[0];
  for (const e of efforts) {
    if (effortRank(e) < effortRank(lowest)) lowest = e;
  }
  return lowest;
}

/**
 * 跨引擎词表的「就近档」翻译 —— Orca lead → worker 语义(与 clampEffortToSupported 是
 * **两种并立的正当语义**,不是二选一):
 *
 *   - `clampEffortToSupported`(上方): **绝不上调**。用于「用户显式存过的档必须只降不升」的
 *     场景(定时任务省钱意图,issue #456)。
 *   - `nearestSupportedEffort`(本函数): **双向就近**。用于「把一个引擎的 effort 意图翻译到
 *     另一个引擎的词表」——GPT 的 xhigh ≈ Claude 的 max,lead 用 Claude(max)开 GPT worker 时
 *     落 xhigh 是翻译,不是降级;反向 xhigh→max 是**上调**,在这个语义里同样正确。
 *
 * 行为与 orcaWorkerCreationService.normalizeResolvedEffort 的非显式分支逐字节一致
 * (minimal→low、ultra→max→xhigh、max→xhigh、xhigh→max;命不中级联映射 → null,由调用方
 * 决定回落模型默认还是报错)。历史上这套级联只存在于 orca 一处且与 clamp 的方向"冲突",
 * 收口成有名字有测试的标准函数后,冲突变成两个可显式选择的语义。
 */
export function nearestSupportedEffort(
  effort: Effort,
  efforts: readonly Effort[],
): Effort | null {
  if (efforts.includes(effort)) return effort;
  if (effort === 'minimal' && efforts.includes('low')) return 'low';
  if (effort === 'ultra' && efforts.includes('max')) return 'max';
  // ultra 但模型无 max(只到 xhigh)时,级联到 xhigh,别掉回默认档丢掉最高兼容档。
  if (effort === 'ultra' && efforts.includes('xhigh')) return 'xhigh';
  if (effort === 'max' && efforts.includes('xhigh')) return 'xhigh';
  if (effort === 'xhigh' && efforts.includes('max')) return 'max';
  return null;
}

/**
 * 无人值守派发场景(IM 新会话 / hook 建会话 / mobile 草稿 reconcile)的「请求档 → 实际落档」
 * 统一回落链(2026-07 对抗审查两轮修正后的定稿)。
 *
 * 模型**有** effort 档时,链是唯一的一份(方向与 IM defaultSessionSettings.resolveEffort
 * 逐分支对齐 —— 初版曾把 override 排在 requested 之前,会让运营表压过用户显式选择;
 * override 是 requested 非法时的回落,不是覆盖):
 *
 *   1. 显式请求档 ∈ 支持档 → 用它(用户/协议显式意图最高);
 *   2. per-model override(如 IM_DEFAULT_EFFORT_OVERRIDES)∈ 支持档 → 用它;
 *   3. 模型默认档 ∈ 支持档 → 用它;
 *   4. 支持档首项。
 *
 * 模型**未知或无档**时,三份历史实现的行为是三种,且都是各自 wire 契约的一部分,
 * **不能拉平**,故显式参数化(`noEffortsBehavior`,默认最保守的 'fallback-only'):
 *   - 'fallback-only'    → 恒 noEffortFallback(hook defaults.ts: 无档就不传,显式档也不传
 *                          —— 模型不支持,传了会被上游拒);
 *   - 'requested-first'  → requested(truthy)|| noEffortFallback(IM resolveEffort 的
 *                          `requested || 'high'`: 目录暂缺时别丢用户选择);
 *   - 'override-first'   → override(truthy)|| noEffortFallback(IM getImDefaultEffortFor:
 *                          该场景 requested 恒空,元数据缺失时运营 override 仍生效)。
 */
export function reconcileInvocationEffort<TFallback extends Effort | null | undefined>(args: {
  requested: Effort | null | undefined;
  model: { efforts: readonly Effort[]; defaultEffort: Effort | null } | undefined;
  overrides?: Readonly<Partial<Record<string, Effort>>>;
  modelId?: string;
  noEffortFallback: TFallback;
  noEffortsBehavior?: 'fallback-only' | 'requested-first' | 'override-first';
}): Effort | TFallback {
  const { requested, model, overrides, modelId, noEffortFallback } = args;
  // Object.hasOwn: model id 可能来自用户可输入的自定义供应商('constructor' 等原型键
  // 会从 Object.prototype 取到函数)。原 IM 实现同病,标准化时一并修。
  const override =
    modelId !== undefined && overrides !== undefined && Object.hasOwn(overrides, modelId)
      ? overrides[modelId]
      : undefined;
  if (!model || model.efforts.length === 0) {
    const behavior = args.noEffortsBehavior ?? 'fallback-only';
    if (behavior === 'requested-first' && requested) return requested;
    if (behavior === 'override-first' && override) return override;
    return noEffortFallback;
  }
  const ok = (e: Effort | null | undefined): e is Effort => !!e && model.efforts.includes(e);
  if (ok(requested)) return requested;
  if (ok(override)) return override;
  if (ok(model.defaultEffort)) return model.defaultEffort;
  return model.efforts[0];
}