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。

20.0 KB
Raw Blame
/**
 * invocation —— 「无人值守派发的调用请求合成」标准(纯逻辑,跨端共享)。
 *
 * 背景(2026-07 全仓盘点): 「按 (显式偏好, 场景默认, 目录可用性) 合成新会话的
 * agent/model/effort/providerId/permissionMode/fastMode」这件事在 desktop main 里被独立实现
 * 了 6+ 份(IM defaultSessionSettings / hook-control defaults / scheduler runner / orca
 * workerCreation / IM cardActionHandler / newMakerDraft),每份回落链略有差异、硬编码默认
 * 互不一致,并且已经产生过真实事故(hook 权限档回落方向写反 → 显示最严实际最宽)。
 *
 * 本模块收口回落链本体;**场景默认全部由调用方传入**(ScenarioDefaults),共享包内零模型 id
 * 字面量 —— scheduler 想默认 Sonnet、IM 想默认 Opus,那是场景决策,不是标准的一部分。
 *
 * 安全语义(适用于一切无人值守入口):
 *   - permissionMode: 显式档不被该 agent 支持时回落该 agent 的**最严**档(permissionModes
 *     按从严到宽声明,取 [0]),绝不回落场景默认(场景默认往往是 bypass)。用户填过显式档
 *     = 表达过「不要默认的完全访问」,不支持时只能更严不能更宽。
 *     注意这对 upstream/main 的 hook 现行实现(defaults.ts: 非法档回落 bypass)是**刻意
 *     收紧**,与 PR #403(32b8edf)的修正同语义;P3 把 hook 迁到本函数时,若 #403 未先合并,
 *     迁移 PR 必须把该收紧作为行为变更显式声明,不许当"无行为变化"混过。
 *   - providerId: 必须收敛到「已连接且真实提供最终模型」的来源,否则回 null(默认路由),
 *     不落一个路由层解析不了、或与 model 错配的 id。
 */

import type { AgentKind, CatalogModel } from './types.js';
import { isModelSelectableForNewRoute } from './classification.js';
import {
  connectedProvidersForAgent,
  nativeDefaultSourceId,
  type ProviderView,
} from './registry.js';
import { reconcileInvocationEffort } from './effortResolution.js';

/** 显式偏好(用户设置 / 协议 override),全可空;null/undefined = 该字段无显式意图。 */
export interface InvocationPreferences {
  agentKind?: string | null;
  model?: string | null;
  effort?: string | null;
  providerId?: string | null;
  permissionMode?: string | null;
  fastMode?: boolean | 'ultrafast' | null;
}

/** 场景默认 —— 每个派发面自己的产品决策,作为参数传入,不散落硬编码。 */
export interface ScenarioDefaults {
  agentKind: AgentKind;
  /** 场景默认模型(scheduler=Sonnet、IM=渠道草稿…)。返回值仍要过可用性校验。 */
  modelFor: (agent: AgentKind) => string;
  /** 场景默认 effort(如 IM 渠道草稿档);缺省 = 直接走模型默认档。 */
  effortFor?: (agent: AgentKind, modelId: string) => string | null;
  /** per-model effort 运营 override(如 IM_DEFAULT_EFFORT_OVERRIDES)。 */
  effortOverrides?: Readonly<Partial<Record<string, string>>>;
  /** 模型无 effort 档时的返回值 —— 各面 wire 契约的一部分(IM='high'、hook=undefined)。 */
  noEffortFallback: string | null | undefined;
  /** 模型未知/无档时对 requested/override 的取舍(三种历史语义,见 reconcileInvocationEffort)。 */
  noEffortsBehavior?: 'fallback-only' | 'requested-first' | 'override-first';
  /** 场景默认权限档(hook='bypassPermissions'、card='acceptEdits'…),仅在无显式档时使用。 */
  permissionMode: string;
  /** 场景默认来源(如 IM 草稿的 providerId);与显式值同样要过收敛校验。 */
  providerIdFor?: (agent: AgentKind, modelId: string) => string | null;
  fastMode?: boolean | 'ultrafast';
  /**
   * 显式模型经目录/caps 校验确认不可用时的策略:
   *   - 'fallback'(默认)= 落场景默认链继续派发 —— IM/hook 无人值守历史语义(宁可换模型
   *     也要把会话建起来);
   *   - 'reject' = 在返回值标记 `rejected`,调用方**不得**用合成结果开工 —— Orca
   *     resolveWorkerConfig 语义(用户点名模型跑 worker,静默换模型 = 花错钱,必须拒绝)。
   * 仅在目录/caps 可用且显式模型确实不在清单时生效;目录全不可用时显式值未经校验直接
   * 采纳('model:explicit-unverified'),不触发 reject。
   */
  explicitModelPolicy?: 'fallback' | 'reject';
}

/** 目录上下文。providers=null = 目录不可用 → capabilities 兜底 + providerId 透传降级。 */
export interface InvocationCatalogContext {
  providers: readonly ProviderView[] | null;
  /** 目录不可用时的模型清单兜底(agent capabilities 冻结快照)。 */
  getCapabilityModels?: (
    agent: AgentKind,
  ) => readonly { id: string; efforts: readonly string[]; defaultEffort: string | null }[];
  /** 该 agent 支持的权限档(**从严到宽**声明;permissionMode 校验与最严档回落依赖此序)。 */
  getPermissionModes?: (agent: AgentKind) => readonly string[];
  /** 可见性过滤(决定「可用模型」是否剔除用户隐藏项);缺省 = 不过滤。 */
  isVisible?: (providerId: string, model: CatalogModel) => boolean;
}

export interface ResolvedInvocation {
  agentKind: AgentKind;
  model: string;
  effort: string | null | undefined;
  providerId: string | null;
  permissionMode: string;
  fastMode: boolean | 'ultrafast';
  /**
   * 诊断轨迹: 各字段命中了哪级回落(如 'model:scenario-default'、
   * 'permission:strictest-fallback')。调用方打日志用,不参与任何逻辑。
   */
  fallbacksApplied: readonly string[];
  /**
   * `explicitModelPolicy: 'reject'` 且显式模型经校验不可用时置位。置位时其余字段仍按
   * 回落链合成(纯诊断价值,便于日志说明"本来会跑什么"),但调用方**不得**据此开工。
   */
  rejected?: { field: 'model'; value: string; reason: 'explicit-model-unavailable' };
}

interface AvailableModel {
  id: string;
  efforts: readonly string[];
  defaultEffort: string | null;
}

function availableModelsFor(
  agent: AgentKind,
  ctx: InvocationCatalogContext,
): AvailableModel[] | null {
  if (ctx.providers !== null) {
    const seen = new Set<string>();
    const out: AvailableModel[] = [];
    for (const provider of connectedProvidersForAgent([...ctx.providers], agent)) {
      for (const m of provider.models[agent] ?? []) {
        if (seen.has(m.id)) continue;
        // 候选清单本身必须先过 chat 准入(issue #882 第 3 点,2026-07 review 第 20
        // 轮):这里是 model 字段(显式偏好校验 / 场景默认 / 首个可用兜底)唯一的
        // 数据源,不过滤的话非聊天模型会被 has()/fromNative/available[0] 选中当成
        // model,而后面的 providerId 步骤只能校验"选中的来源",无法撤销已经选错
        // 的模型 —— 那时再挡为时已晚。
        if (!isModelSelectableForNewRoute(m, { userProvider: provider.source === 'user' }))
          continue;
        if (ctx.isVisible && !ctx.isVisible(provider.id, m)) continue;
        seen.add(m.id);
        out.push({ id: m.id, efforts: m.efforts, defaultEffort: m.defaultEffort });
      }
    }
    return out;
  }
  const caps = ctx.getCapabilityModels?.(agent);
  return caps ? [...caps] : null;
}

function isKnownAgent(v: string | null | undefined): v is AgentKind {
  return v === 'claude-code' || v === 'codex' || v === 'pi';
}

/**
 * 标准调用合成。回落链每一级都要求候选值可用;`fallbacksApplied` 记录实际命中级。
 *
 * model 链: 显式∈可用 > 场景默认∈可用 > 该 agent 首个可用 > 场景默认裸值(目录/caps 全
 * 不可用时的兼容兜底 —— 与 IM/hook 历史行为一致,宁可发一个可能非法的 id 也不发空串)。
 */
export function resolveModelInvocation(
  prefs: InvocationPreferences,
  scenario: ScenarioDefaults,
  ctx: InvocationCatalogContext,
): ResolvedInvocation {
  const fallbacks: string[] = [];

  // 1. agentKind: 显式合法 > 场景默认。
  let agentKind: AgentKind;
  if (isKnownAgent(prefs.agentKind)) {
    agentKind = prefs.agentKind;
  } else {
    agentKind = scenario.agentKind;
    if (prefs.agentKind != null) fallbacks.push('agent:scenario-default');
  }

  // 1b. 显式 agent 合法但目录/caps 证实它**一个可用模型都没有**,而场景默认 agent 有 →
  //     回落到能跑的 agent。这是 IM resolveImSessionDefaults.pickModel 的现行语义(codex
  //     review):不回落的话会合成一个「无可执行来源」的会话,比换 agent 更糟。
  //     清单为 null(能力数据不可用)时不猜,维持显式选择。
  let available = availableModelsFor(agentKind, ctx);
  // model/effort/providerId 显式偏好经局部变量参与后续链:agent 回落时置空(见下),不改 prefs 入参。
  let modelPref = prefs.model ?? null;
  let effortPref = prefs.effort ?? null;
  let providerPref = prefs.providerId ?? null;
  if (
    isKnownAgent(prefs.agentKind) &&
    agentKind !== scenario.agentKind &&
    available !== null &&
    available.length === 0
  ) {
    const scenarioAvailable = availableModelsFor(scenario.agentKind, ctx);
    if (scenarioAvailable !== null && scenarioAvailable.length > 0) {
      agentKind = scenario.agentKind;
      available = scenarioAvailable;
      fallbacks.push('agent:model-less-fallback');
      // 显式 model/effort/providerId 是与**原 agent 配对**的偏好,跨 agent 全部作废
      // (IM 换 agent 后读 raw.agents[新agent] 的整组配置,defaultSessionSettings.ts)。
      // model/effort 不作废会让恰好同 id 的模型(gpt-5.5 双 agent 目录都有)被当作新
      // agent 的显式选择采纳,还会绕过 explicitModelPolicy: 'reject';providerId 不作废
      // 会把原 agent 的路由/计费选择(如 xd)强加给回落 agent,压掉场景为新 agent 配置
      // 的 providerIdFor(codex review 两轮)。
      modelPref = null;
      effortPref = null;
      providerPref = null;
    }
  }

  // 2. model。
  const has = (id: string | null | undefined): id is string =>
    !!id && (available === null || available.some((m) => m.id === id));
  const scenarioModel = scenario.modelFor(agentKind);
  let model: string;
  let rejected: ResolvedInvocation['rejected'];
  if (has(modelPref)) {
    model = modelPref;
    // 目录与 caps 全不可用时 has() 放行一切 —— 值被采纳但未经校验,记入诊断轨迹。
    if (available === null) fallbacks.push('model:explicit-unverified');
  } else {
    // 显式模型经校验确认不可用(available 必非 null,否则上分支已放行):按策略标记拒绝。
    // 其余字段照常合成 —— rejected 是给调用方的硬信号,不是让链条中断。
    if (modelPref != null && scenario.explicitModelPolicy === 'reject') {
      rejected = { field: 'model', value: modelPref, reason: 'explicit-model-unavailable' };
      fallbacks.push('model:explicit-rejected');
    }
    if (has(scenarioModel)) {
      model = scenarioModel;
      if (modelPref != null) fallbacks.push('model:scenario-default');
      if (available === null) fallbacks.push('model:scenario-default-unverified');
    } else if (available !== null && available.length > 0) {
      // 「首个可用」的口径与 IM 现行兜底一致:优先 **native 默认源**(claude-code 优先
      // 'xd'、codex 优先 'openai')上的首个可见模型,该源无可选才退 rail 序首个 ——
      // raw 目录序首个会把兜底模型换到不同来源/计费路由(codex review)。
      let fromNative: string | null = null;
      if (ctx.providers !== null) {
        const rail = connectedProvidersForAgent([...ctx.providers], agentKind);
        const nativeId = nativeDefaultSourceId(rail, agentKind);
        const native = rail.find((p) => p.id === nativeId);
        const availableIds = new Set(available.map((m) => m.id));
        // 可见性 / chat 准入都按 **native 源上的那一行**判,不能只看联合清单:某 id
        // 在 native 源被隐藏或是非聊天类型的具体条目、他源可见且聊天可用时,选它会让
        // provider 步骤路由去他源(或选中一个实际不能聊天的 id)—— 跳过了 native 源
        // 后面还有的可见/聊天模型,订阅/计费路由被悄悄换掉(codex review 五轮;mode
        // 校验补于 issue #882 第 3 点,2026-07 review 第 20 轮:availableIds 只证明该
        // id 在**某个**来源聊天可用,不能代表 native 这一份具体条目也是)。
        fromNative =
          native?.models[agentKind]?.find(
            (m) =>
              availableIds.has(m.id) &&
              isModelSelectableForNewRoute(m, { userProvider: native.source === 'user' }) &&
              (!ctx.isVisible || ctx.isVisible(native.id, m)),
          )?.id ?? null;
      }
      model = fromNative ?? available[0].id;
      fallbacks.push('model:first-available');
    } else {
      model = scenarioModel;
      // 诊断标记区分两种「硬发场景默认裸值」:available === null 是数据不可用未经校验;
      // 空数组是数据可用但**确认零可选**(Copilot review:混用 unverified 会误导排查)。
      fallbacks.push(
        available === null
          ? 'model:scenario-default-unverified'
          : 'model:no-available-models',
      );
    }
  }

  // 3. effort。requested 槽位是**两级候选**: 显式档非法时先试场景默认档(hook 的
  //    「显式 > 草稿 > 模型默认」历史链;初版 `prefs.effort ?? scenarioEffort` 会在显式档
  //    非法时直接跳过草稿档,2026-07 对抗审查修正),再交给统一回落链。
  const descriptor = available?.find((m) => m.id === model);
  const scenarioEffort = scenario.effortFor?.(agentKind, model) ?? null;
  let requestedEffort: string | null | undefined;
  if (descriptor && descriptor.efforts.length > 0) {
    requestedEffort =
      [effortPref, scenarioEffort].find((c) => !!c && descriptor.efforts.includes(c)) ??
      effortPref;
  } else {
    requestedEffort = effortPref ?? scenarioEffort;
  }
  const effort = reconcileInvocationEffort({
    requested: requestedEffort,
    model: descriptor,
    overrides: scenario.effortOverrides,
    modelId: model,
    noEffortFallback: scenario.noEffortFallback,
    ...(scenario.noEffortsBehavior !== undefined
      ? { noEffortsBehavior: scenario.noEffortsBehavior }
      : {}),
  });
  if (effortPref != null && effort !== effortPref) fallbacks.push('effort:reconciled');

  // 4. providerId: 显式 / 场景值收敛到「已连接且真实提供最终模型」的来源,失败回 null。
  //    目录不可用时透传原值(路由层仍有兜底)—— 与 IM/hook 历史降级一致。
  const requestedProvider = providerPref ?? scenario.providerIdFor?.(agentKind, model) ?? null;
  let providerId: string | null = null;
  if (ctx.providers === null) {
    if (requestedProvider) {
      providerId = requestedProvider;
      fallbacks.push('provider:unverified-passthrough');
    }
  } else if (requestedProvider || ctx.isVisible) {
    // 「真实提供」必须含 per-provider 可见性:同一模型在 B 可见、在 A 被用户隐藏时,
    // 显式点名 A 不能只靠「已连接 + 目录含该模型」就放行 —— 那会绕过 isVisible 的
    // 来源级契约,路由到用户明确排除的来源(codex review)。
    const rail = connectedProvidersForAgent([...ctx.providers], agentKind);
    // 「真实提供」还必须含 mode 准入(issue #882 第 3 点,2026-07 review 第 18 轮):
    // providerOffersModel 只看 id 是否存在,不看 mode——同一 id 在这个来源下若是
    // 非聊天类型的具体条目,无人值守派发会把请求发进 image/audio/embedding 端点。
    // 取出该来源自己的这份条目校验 isChatEligible,是下面 visiblyOffers 的基础。
    const chatModelOn = (p: (typeof rail)[number]): CatalogModel | undefined => {
      const cm = p.models[agentKind]?.find((m) => m.id === model);
      return cm !== undefined &&
        isModelSelectableForNewRoute(cm, { userProvider: p.source === 'user' })
        ? cm
        : undefined;
    };
    const visiblyOffers = (p: (typeof rail)[number]): boolean => {
      const cm = chatModelOn(p);
      if (cm === undefined) return false;
      if (!ctx.isVisible) return true;
      return ctx.isVisible(p.id, cm);
    };
    const named = requestedProvider ? rail.find((p) => p.id === requestedProvider) : undefined;
    if (requestedProvider && named !== undefined && visiblyOffers(named)) {
      providerId = requestedProvider;
    } else if (requestedProvider) {
      // 点名源不可用(断开/不提供/被隐藏)。回 null 不足以执行可见性决定 —— 下游默认
      // 路由(nativeDefaultSourceId)不看可见性,可能又选回同一个被隐藏的源:这里直接
      // 收敛到 native 优先的**可见**替代源;完全没有可见源才回 null 默认路由
      // (codex review, 2026-07)。
      const alternatives = rail.filter(visiblyOffers);
      if (alternatives.length > 0) {
        providerId = nativeDefaultSourceId(alternatives, agentKind) ?? alternatives[0].id;
        fallbacks.push('provider:visible-fallback');
      } else {
        providerId = null;
        fallbacks.push('provider:default-route');
      }
    } else {
      // 无点名但可见性过滤激活:下游把 null 解析成 nativeDefaultSourceId 时**不看可见性**
      // (registry.ts effectiveSourceIdForModel),若 native 源上该模型恰被隐藏、他源可见,
      // null 会路由进被隐藏的源 —— 仅在这种「下游默认落点不可见」的情况下显式收敛到
      // 可见源;默认落点本就可见(绝大多数)时维持 null,不改「null=默认路由」契约
      // (codex review 三轮补全)。
      const offering = rail.filter((p) => chatModelOn(p) !== undefined);
      const downstream = offering.find((p) => p.id === nativeDefaultSourceId(offering, agentKind));
      if (downstream !== undefined && !visiblyOffers(downstream)) {
        const alternatives = rail.filter(visiblyOffers);
        if (alternatives.length > 0) {
          providerId = nativeDefaultSourceId(alternatives, agentKind) ?? alternatives[0].id;
          fallbacks.push('provider:visible-fallback');
        }
      }
    }
  }

  // 5. permissionMode: 显式且支持 > 显式但不支持时回落该 agent **最严**档 > 场景默认。
  //    (安全方向硬要求,见文件头;permissionModes 未注入时无从校验,显式值原样放行。)
  //    **空档位表 = 能力数据异常,同「未注入」处理,显式值原样保留** —— 此前空表会落
  //    scenario.permissionMode(常为 bypass),把显式限制静默放宽,与本函数的安全保证
  //    正相反(Greptile + codex review 同点)。
  const supportedModes = ctx.getPermissionModes?.(agentKind);
  let permissionMode: string;
  if (prefs.permissionMode != null) {
    if (!supportedModes || supportedModes.length === 0) {
      permissionMode = prefs.permissionMode;
      if (supportedModes) fallbacks.push('permission:modes-unavailable');
    } else if (supportedModes.includes(prefs.permissionMode)) {
      permissionMode = prefs.permissionMode;
    } else {
      permissionMode = supportedModes[0];
      fallbacks.push('permission:strictest-fallback');
    }
  } else {
    permissionMode = scenario.permissionMode;
    // 场景默认档同样要对**最终 agent** 校验:Claude 场景默认 acceptEdits + 显式 Codex
    // agent 会合成 Codex 不支持的档,无人值守派发直接被运行时拒绝或误解 —— 不支持时
    // 与显式分支同方向回落该 agent 最严档(codex review);空表/未注入 = 数据缺失,原样。
    if (
      supportedModes !== undefined &&
      supportedModes.length > 0 &&
      !supportedModes.includes(permissionMode)
    ) {
      permissionMode = supportedModes[0];
      fallbacks.push('permission:scenario-strictest-fallback');
    }
  }

  // 6. fastMode: 请求值直传(per-provider 的 supportsFastMode 门控需要来源上下文,
  //    由派发端在确定最终 (providerId, model) 后另行叠加 —— 本函数不越权猜)。
  const fastMode = prefs.fastMode ?? scenario.fastMode ?? false;

  return {
    agentKind,
    model,
    effort,
    providerId,
    permissionMode,
    fastMode,
    fallbacksApplied: fallbacks,
    ...(rejected !== undefined ? { rejected } : {}),
  };
}