paseo-plugin-zcode-provider 0.0.0-stage → 0.2.0

package/server/vendor/zcode/packages/shared/src/localTtft.ts

@@ -0,0 +1,192 @@
+import { z } from "zod";
+
+export const LOCAL_TTFT_STAGES = [
+  "renderer_prepare",
+  "command_admission",
+  "execution_wait",
+  "request_prepare",
+  "model_request",
+  "output_return",
+] as const;
+export const LOCAL_TTFT_BUCKETS_MS = [
+  1, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 30000, 60000, 300000,
+];
+export const LOCAL_TTFT_MAX_DETAILS = 64;
+export const LOCAL_TTFT_PREPARATION_STAGES = [
+  "context",
+  "hooks",
+  "persistence",
+  "compaction",
+  "mcp",
+  "tools",
+  "request_assembly",
+] as const;
+const diagnosticTime = z.number().finite().nonnegative();
+export const localTtftDetailSchema = z
+  .object({
+    id: z.string().min(1).max(128),
+    stage: z.enum([...LOCAL_TTFT_PREPARATION_STAGES, "attempt", "retry_wait", "user_confirmation"]),
+    start: diagnosticTime,
+    end: diagnosticTime.optional(),
+    outcome: z.enum(["completed", "failed", "cancelled", "first_output"]).optional(),
+    requestId: z.string().min(1).max(128).optional(),
+    logicalCallId: z.string().min(1).max(128).optional(),
+    role: z.enum(["response", "preparation"]).optional(),
+    source: z.enum(["renderer", "cli"]),
+  })
+  .strict()
+  .refine((value) => value.end === undefined || value.end >= value.start);
+export type LocalTtftDetail = z.infer<typeof localTtftDetailSchema>;
+export const LOCAL_TTFT_MAX_PENDING = 128;
+export const LOCAL_TTFT_TTL_MS = 300_000;
+export const LOCAL_TTFT_CLOCK_MAX_ERROR_MS = 10;
+export const LOCAL_TTFT_CLOCK_TTL_MS = 60_000;
+const time = z.number().finite().nonnegative();
+const identifier = z.string().min(1).max(128);
+export const localTtftContextSchema = z
+  .object({ version: z.literal(1), observationId: z.string().uuid() })
+  .strict();
+export type LocalTtftContext = z.infer<typeof localTtftContextSchema>;
+export const localTtftClockSchema = z
+  .object({ instanceId: identifier, receivedAt: time, sentAt: time })
+  .strict();
+export type LocalTtftClock = z.infer<typeof localTtftClockSchema>;
+export interface LocalTtftCalibration {
+  instanceId: string;
+  offsetMs: number;
+  errorMs: number;
+  measuredAt: number;
+}
+export function calibrateLocalTtftClock(
+  start: number,
+  end: number,
+  clock: LocalTtftClock,
+): LocalTtftCalibration | undefined {
+  const networkMs = end - start - (clock.sentAt - clock.receivedAt);
+  if (
+    ![start, end, clock.receivedAt, clock.sentAt].every(Number.isFinite) ||
+    end < start ||
+    clock.sentAt < clock.receivedAt ||
+    networkMs < 0 ||
+    networkMs / 2 > LOCAL_TTFT_CLOCK_MAX_ERROR_MS
+  )
+    return undefined;
+  return {
+    instanceId: clock.instanceId,
+    offsetMs: (start + end - clock.receivedAt - clock.sentAt) / 2,
+    errorMs: networkMs / 2,
+    measuredAt: end,
+  };
+}
+export const localTtftOutputKindSchema = z.enum(["text", "reasoning", "tool"]);
+export type LocalTtftOutputKind = z.infer<typeof localTtftOutputKindSchema>;
+export const localTtftFactsSchema = z
+  .object({
+    ...localTtftContextSchema.shape,
+    instanceId: identifier,
+    commandId: identifier,
+    sessionId: identifier.optional(),
+    turnId: identifier.optional(),
+    productTurnId: identifier.optional(),
+    queryId: identifier.optional(),
+    requestId: identifier.optional(),
+    logicalCallId: identifier.optional(),
+    cliVersion: identifier.optional(),
+    provider: identifier.optional(),
+    model: identifier.optional(),
+    details: z.array(localTtftDetailSchema).max(LOCAL_TTFT_MAX_DETAILS).optional(),
+    truncated: z.boolean().optional(),
+    revision: z.number().int().nonnegative().optional(),
+    sendMode: z.enum(["idle", "queued", "guided"]).optional(),
+    clockInvalid: z.boolean().optional(),
+    receivedAt: time,
+    admittedAt: time.optional(),
+    executionAt: time.optional(),
+    requestAt: time.optional(),
+    outputAt: time.optional(),
+    outputKind: localTtftOutputKindSchema.optional(),
+    terminal: z.enum(["completed", "failed", "cancelled", "rejected", "interrupted"]).optional(),
+    excluded: z.enum(["busy", "retry", "unsupported", "failed", "capacity"]).optional(),
+  })
+  .strict();
+export type LocalTtftFacts = z.infer<typeof localTtftFactsSchema>;
+export const localTtftIntervalSchema = z
+  .object({
+    stage: z.enum(LOCAL_TTFT_STAGES),
+    start: time,
+    end: time,
+    source: z.enum(["renderer", "cli", "aligned"]),
+  })
+  .strict()
+  .refine((interval) => interval.end >= interval.start);
+export const localTtftRecordSchema = z
+  .object({
+    version: z.literal(1),
+    observationId: z.string().uuid(),
+    commandId: identifier.optional(),
+    sessionId: identifier.optional(),
+    turnId: identifier.optional(),
+    productTurnId: identifier.optional(),
+    queryId: identifier.optional(),
+    requestId: identifier.optional(),
+    logicalCallId: identifier.optional(),
+    cliVersion: identifier.optional(),
+    cliInstanceId: identifier.optional(),
+    kind: z.enum(["start", "first_output", "first_text", "no_text", "excluded", "checkpoint"]),
+    outcome: z.enum([
+      "success",
+      "busy",
+      "retry",
+      "unsupported",
+      "failed",
+      "cancelled",
+      "background",
+      "expired",
+      "capacity",
+      "recovery",
+      // 桌面 continuous 缓冲溢出/投影重建后的 online snapshot；不是手机 replayable 恢复。
+      "resync",
+      "clock_invalid",
+      "rejected",
+      "interrupted",
+      "guided",
+      "unclosed",
+    ]),
+    start: time,
+    end: time,
+    firstOutputKind: localTtftOutputKindSchema.optional(),
+    quality: z.enum(["complete", "missing", "clock_invalid"]),
+    clockErrorMs: time.optional(),
+    intervals: z.array(localTtftIntervalSchema).max(6),
+    checkpointId: identifier.optional(),
+    details: z.array(localTtftDetailSchema).max(LOCAL_TTFT_MAX_DETAILS).optional(),
+    truncated: z.boolean().optional(),
+    sendMode: z.enum(["idle", "queued", "guided"]).optional(),
+    visibility: z.enum(["foreground", "background", "background_returned"]).optional(),
+    visibilityChanges: z
+      .array(z.object({ at: time, foreground: z.boolean() }).strict())
+      .max(32)
+      .optional(),
+    userWaitMs: time.optional(),
+    executionMs: time.optional(),
+    timingReliable: z.boolean().optional(),
+    cliTimingReliable: z.boolean().optional(),
+    provider: identifier.optional(),
+    model: identifier.optional(),
+  })
+  .strict()
+  .refine((record) => record.end >= record.start);
+export type LocalTtftRecord = z.infer<typeof localTtftRecordSchema>;
+export const localTtftBatchSchema = z
+  .object({
+    version: z.literal(1),
+    rendererInstanceId: identifier,
+    sequence: z.number().int().nonnegative(),
+    records: z.array(localTtftRecordSchema).max(32),
+    dropped: z.number().int().nonnegative(),
+  })
+  .strict();
+export type LocalTtftBatch = z.infer<typeof localTtftBatchSchema>;
+export function localTtftNow(): number {
+  return performance.timeOrigin + performance.now();
+}

package/server/vendor/zcode/packages/shared/src/model-config.ts

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import { compileModelOptionMap } from "../../model-option-map/src/index.js";
+import { sparseShape } from "./config-schema.js";
+
+function optionMapSchema(variableName: "reasoningLevel" | "maxOutputTokens") {
+  return z
+    .string()
+    .min(1)
+    .superRefine((source, context) => {
+      try {
+        compileModelOptionMap(source, variableName);
+      } catch (error) {
+        context.addIssue({
+          code: "custom",
+          message: error instanceof Error ? error.message : "Option map 无法编译",
+        });
+      }
+    });
+}
+
+export const completeEnumOptionSpecDataSchema = z
+  .object({
+    /** 按语义强度从低到高排列；首项是辅助调用可选的最低公开档位。 */
+    values: z
+      .array(
+        z
+          .string()
+          .refine((value) => value.trim().length > 0, "reasoningLevel.values 必须是非空字符串"),
+      )
+      .min(1, "reasoningLevel.values 不能为空")
+      .refine((values) => new Set(values).size === values.length, "reasoningLevel.values 不能重复")
+      .readonly(),
+    map: optionMapSchema("reasoningLevel"),
+  })
+  .strict();
+
+export const completeLimitOptionSpecDataSchema = z
+  .object({
+    max: z.number().int().positive(),
+    map: optionMapSchema("maxOutputTokens"),
+  })
+  .strict();
+
+export const enumOptionSpecDataSchema = z
+  .object(sparseShape(completeEnumOptionSpecDataSchema.shape))
+  .strict();
+export const limitOptionSpecDataSchema = z
+  .object(sparseShape(completeLimitOptionSpecDataSchema.shape))
+  .strict();
+
+export const completeModelInputFormatDataSchema = z
+  .object({
+    supportsText: z.boolean(),
+    supportsImage: z.boolean(),
+    supportsVideo: z.boolean(),
+    supportsAudio: z.boolean(),
+    supportsPdf: z.boolean(),
+  })
+  .strict();
+export const completeModelOutputFormatDataSchema = z.object({ supportsText: z.boolean() }).strict();
+export const modelInputFormatDataSchema = z
+  .object(sparseShape(completeModelInputFormatDataSchema.shape))
+  .strict();
+export const modelOutputFormatDataSchema = z
+  .object(sparseShape(completeModelOutputFormatDataSchema.shape))
+  .strict();
+
+export const completeModelPropertiesDataSchema = z
+  .object({
+    requiresMfjsToolSchema: z.boolean(),
+    contextWindow: z.number().int().positive(),
+    inputFormat: completeModelInputFormatDataSchema,
+    outputFormat: completeModelOutputFormatDataSchema,
+    supportsToolCall: z.boolean(),
+    supportsJsonSchemaOutput: z.boolean(),
+    supportsNativeWebSearch: z.boolean(),
+    supportsMidConversationSystem: z.boolean(),
+  })
+  .strict();
+export const modelPropertiesDataSchema = z
+  .object({
+    ...sparseShape(completeModelPropertiesDataSchema.shape),
+    inputFormat: modelInputFormatDataSchema.nullable().optional(),
+    outputFormat: modelOutputFormatDataSchema.nullable().optional(),
+  })
+  .strict();
+
+export const completeModelOptionSpecsDataSchema = z
+  .object({
+    reasoningLevel: completeEnumOptionSpecDataSchema,
+    maxOutputTokens: completeLimitOptionSpecDataSchema,
+  })
+  .strict();
+export const modelOptionSpecsDataSchema = z
+  .object({
+    ...sparseShape(completeModelOptionSpecsDataSchema.shape),
+    reasoningLevel: enumOptionSpecDataSchema.nullable().optional(),
+    maxOutputTokens: limitOptionSpecDataSchema.nullable().optional(),
+  })
+  .strict();
+
+export const completeModelConfigDataSchema = z
+  .object({
+    enabled: z.boolean(),
+    properties: completeModelPropertiesDataSchema,
+    optionSpecs: completeModelOptionSpecsDataSchema,
+  })
+  .strict();
+export const modelConfigDataSchema = z
+  .object({
+    ...sparseShape(completeModelConfigDataSchema.shape),
+    properties: modelPropertiesDataSchema.nullable().optional(),
+    optionSpecs: modelOptionSpecsDataSchema.nullable().optional(),
+  })
+  .strict();
+
+// 跨层只共享数据合同；Provider 行为类与 IO 不进入公共 Schema。
+export type ModelInputFormatData = z.infer<typeof completeModelInputFormatDataSchema>;
+export type ModelOutputFormatData = z.infer<typeof completeModelOutputFormatDataSchema>;
+export type ModelPropertiesData = z.infer<typeof completeModelPropertiesDataSchema>;
+export type EnumOptionSpecData = z.infer<typeof completeEnumOptionSpecDataSchema>;
+export type LimitOptionSpecData = z.infer<typeof completeLimitOptionSpecDataSchema>;
+export type ModelOptionSpecsData = z.infer<typeof completeModelOptionSpecsDataSchema>;

package/server/vendor/zcode/packages/shared/src/model-execution.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+/** 文本与附件发送共用执行约束，凭据只属于单次执行，不进入 Session 配置。 */
+export const modelExecutionSchema = z
+  .object({
+    memoryExtraction: z.literal("skip").optional(),
+    selectionScope: z.literal("execution"),
+    requestAuth: z
+      .object({
+        apiKey: z.string().min(1).optional(),
+        headers: z.record(z.string().min(1), z.string().min(1)).optional(),
+      })
+      .strict()
+      .optional(),
+    subagents: z
+      .object({
+        foregroundModel: z.literal("submission"),
+        background: z.literal("deny"),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();

package/server/vendor/zcode/packages/shared/src/model-provider-family.ts

@@ -0,0 +1,171 @@
+import { BIGMODEL_PROVIDER_ID, type OAuthProviderId, ZAI_PROVIDER_ID } from "./oauth.js";
+import { BUILTIN_MODEL_PROVIDER_IDS, type BuiltinModelProviderId } from "./model-provider-types.js";
+import { ZCODE_ENV } from "./env.js";
+import { buildBigModelCodingPlanTeamManageUrl } from "./zcodeEndpoint.js";
+
+export type ModelProviderFamilyId = "zai" | "bigmodel";
+export type ProviderFamilyDomain = ModelProviderFamilyId;
+
+export interface ModelProviderFamilySpec {
+  id: ModelProviderFamilyId;
+  label: string;
+  rootDomain: string;
+  oauthProviderId: typeof ZAI_PROVIDER_ID | typeof BIGMODEL_PROVIDER_ID;
+  startPlanProviderId:
+    | typeof BUILTIN_MODEL_PROVIDER_IDS.zaiStartPlan
+    | typeof BUILTIN_MODEL_PROVIDER_IDS.bigmodelStartPlan;
+  individualCodingPlanProviderId:
+    | typeof BUILTIN_MODEL_PROVIDER_IDS.zaiIndividualCodingPlan
+    | typeof BUILTIN_MODEL_PROVIDER_IDS.bigmodelIndividualCodingPlan;
+  teamCodingPlanProviderId:
+    | typeof BUILTIN_MODEL_PROVIDER_IDS.zaiTeamCodingPlan
+    | typeof BUILTIN_MODEL_PROVIDER_IDS.bigmodelTeamCodingPlan;
+  teamCodingPlanManageUrl: string;
+}
+
+export const MODEL_PROVIDER_FAMILY_SPECS = [
+  {
+    id: "zai",
+    label: "Z.ai",
+    rootDomain: "z.ai",
+    oauthProviderId: ZAI_PROVIDER_ID,
+    startPlanProviderId: BUILTIN_MODEL_PROVIDER_IDS.zaiStartPlan,
+    individualCodingPlanProviderId: BUILTIN_MODEL_PROVIDER_IDS.zaiIndividualCodingPlan,
+    teamCodingPlanProviderId: BUILTIN_MODEL_PROVIDER_IDS.zaiTeamCodingPlan,
+    teamCodingPlanManageUrl: "https://z.ai/manage-apikey/subscription",
+  },
+  {
+    id: "bigmodel",
+    label: "BigModel",
+    rootDomain: "bigmodel.cn",
+    oauthProviderId: BIGMODEL_PROVIDER_ID,
+    startPlanProviderId: BUILTIN_MODEL_PROVIDER_IDS.bigmodelStartPlan,
+    individualCodingPlanProviderId: BUILTIN_MODEL_PROVIDER_IDS.bigmodelIndividualCodingPlan,
+    teamCodingPlanProviderId: BUILTIN_MODEL_PROVIDER_IDS.bigmodelTeamCodingPlan,
+    teamCodingPlanManageUrl: buildBigModelCodingPlanTeamManageUrl({ ZCODE_ENV }),
+  },
+] as const satisfies readonly ModelProviderFamilySpec[];
+
+const MODEL_PROVIDER_FAMILY_SPEC_BY_ID = new Map<ModelProviderFamilyId, ModelProviderFamilySpec>(
+  MODEL_PROVIDER_FAMILY_SPECS.map((spec) => [spec.id, spec]),
+);
+
+const MODEL_PROVIDER_FAMILY_ID_BY_PROVIDER_ID = new Map<
+  BuiltinModelProviderId,
+  ModelProviderFamilyId
+>(
+  MODEL_PROVIDER_FAMILY_SPECS.flatMap((spec) =>
+    [
+      spec.startPlanProviderId,
+      spec.individualCodingPlanProviderId,
+      spec.teamCodingPlanProviderId,
+    ].map((providerId) => [providerId, spec.id] as const),
+  ),
+);
+
+export function getModelProviderFamilySpec(
+  familyId: ModelProviderFamilyId,
+): ModelProviderFamilySpec {
+  return MODEL_PROVIDER_FAMILY_SPEC_BY_ID.get(familyId)!;
+}
+
+export function resolveModelProviderFamilyIdByProviderId(
+  providerId: string,
+): ModelProviderFamilyId | null {
+  return MODEL_PROVIDER_FAMILY_ID_BY_PROVIDER_ID.get(providerId as BuiltinModelProviderId) ?? null;
+}
+
+export function resolveModelProviderFamilyIdByBaseURL(
+  baseURL: string | null | undefined,
+): ModelProviderFamilyId | null {
+  const trimmed = baseURL?.trim();
+  if (!trimmed) {
+    return null;
+  }
+  let hostname: string;
+  try {
+    hostname = new URL(trimmed).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+  for (const spec of MODEL_PROVIDER_FAMILY_SPECS) {
+    if (hostname === spec.rootDomain || hostname.endsWith(`.${spec.rootDomain}`)) {
+      return spec.id;
+    }
+  }
+  return null;
+}
+
+export function resolveModelProviderFamilySpecByProviderId(
+  providerId: string,
+): ModelProviderFamilySpec | null {
+  const familyId = resolveModelProviderFamilyIdByProviderId(providerId);
+  return familyId ? getModelProviderFamilySpec(familyId) : null;
+}
+
+export function resolveModelProviderFamilyLabelByProviderId(providerId: string): string | null {
+  return resolveModelProviderFamilySpecByProviderId(providerId)?.label ?? null;
+}
+
+export function normalizeProviderFamilyDomain(
+  value: string | null | undefined,
+): ProviderFamilyDomain | null {
+  return value === "zai" || value === "bigmodel" ? value : null;
+}
+
+export function resolveProviderFamilyDomainFromOAuthProvider(
+  provider: OAuthProviderId | string | null | undefined,
+): ProviderFamilyDomain | null {
+  if (provider === ZAI_PROVIDER_ID) {
+    return "zai";
+  }
+  if (provider === BIGMODEL_PROVIDER_ID) {
+    return "bigmodel";
+  }
+  return null;
+}
+
+export function shouldShowModelProviderFamilyForDomain(params: {
+  familyId: ModelProviderFamilyId;
+  providerFamilyDomain: ProviderFamilyDomain | null | undefined;
+}): boolean {
+  const providerFamilyDomain = normalizeProviderFamilyDomain(params.providerFamilyDomain);
+  if (!providerFamilyDomain) {
+    return true;
+  }
+  return params.familyId === providerFamilyDomain;
+}
+
+export function shouldShowModelProviderFamilyForActiveOAuth(params: {
+  familyId: ModelProviderFamilyId;
+  activeOAuthProvider: OAuthProviderId | null | undefined;
+}): boolean {
+  return shouldShowModelProviderFamilyForDomain({
+    familyId: params.familyId,
+    providerFamilyDomain: resolveProviderFamilyDomainFromOAuthProvider(params.activeOAuthProvider),
+  });
+}
+
+export function shouldShowBuiltinModelProviderForDomain(params: {
+  providerId: string;
+  providerFamilyDomain: ProviderFamilyDomain | null | undefined;
+}): boolean {
+  const familyId = resolveModelProviderFamilyIdByProviderId(params.providerId);
+  if (!familyId) {
+    return true;
+  }
+  return shouldShowModelProviderFamilyForDomain({
+    familyId,
+    providerFamilyDomain: params.providerFamilyDomain,
+  });
+}
+
+export function shouldShowBuiltinModelProviderForActiveOAuth(params: {
+  providerId: string;
+  activeOAuthProvider: OAuthProviderId | null | undefined;
+}): boolean {
+  return shouldShowBuiltinModelProviderForDomain({
+    providerId: params.providerId,
+    providerFamilyDomain: resolveProviderFamilyDomainFromOAuthProvider(params.activeOAuthProvider),
+  });
+}

package/server/vendor/zcode/packages/shared/src/model-provider-types.ts

@@ -0,0 +1,81 @@
+/* eslint-disable max-lines -- 模型供应商 schema、迁移和运行时投影 helper 需要共享同一套类型边界，暂时集中在单文件避免契约分散。 */
+export const BUILTIN_PROVIDER_TEMPLATE_IDS = {
+  zai: "zai-api",
+  bigmodel: "bigmodel-api",
+} as const;
+
+export const BUILTIN_MODEL_PROVIDER_IDS = {
+  zaiIndividualCodingPlan: "account:zai-individual-coding-plan",
+  zaiTeamCodingPlan: "account:zai-team-coding-plan",
+  zaiStartPlan: "account:zai-start-plan",
+  bigmodelIndividualCodingPlan: "account:bigmodel-individual-coding-plan",
+  bigmodelTeamCodingPlan: "account:bigmodel-team-coding-plan",
+  bigmodelStartPlan: "account:bigmodel-start-plan",
+} as const;
+
+export type BuiltinOAuthProviderId = keyof typeof BUILTIN_MODEL_PROVIDER_IDS;
+
+export type BuiltinModelProviderId = (typeof BUILTIN_MODEL_PROVIDER_IDS)[BuiltinOAuthProviderId];
+
+export function isBuiltinModelProviderId(id: string): id is BuiltinModelProviderId {
+  return (
+    id === BUILTIN_MODEL_PROVIDER_IDS.zaiIndividualCodingPlan ||
+    id === BUILTIN_MODEL_PROVIDER_IDS.zaiTeamCodingPlan ||
+    id === BUILTIN_MODEL_PROVIDER_IDS.zaiStartPlan ||
+    id === BUILTIN_MODEL_PROVIDER_IDS.bigmodelIndividualCodingPlan ||
+    id === BUILTIN_MODEL_PROVIDER_IDS.bigmodelTeamCodingPlan ||
+    id === BUILTIN_MODEL_PROVIDER_IDS.bigmodelStartPlan
+  );
+}
+
+export function isZaiCodingPlanProviderId(id: string): boolean {
+  return (
+    id === BUILTIN_MODEL_PROVIDER_IDS.zaiIndividualCodingPlan ||
+    id === BUILTIN_MODEL_PROVIDER_IDS.zaiTeamCodingPlan ||
+    id === BUILTIN_MODEL_PROVIDER_IDS.zaiStartPlan
+  );
+}
+
+export function isBigModelStartPlanProviderId(id: string): boolean {
+  return id === BUILTIN_MODEL_PROVIDER_IDS.bigmodelStartPlan;
+}
+
+export function isStartPlanModelProviderId(id: string): boolean {
+  return (
+    id === BUILTIN_MODEL_PROVIDER_IDS.zaiStartPlan ||
+    id === BUILTIN_MODEL_PROVIDER_IDS.bigmodelStartPlan
+  );
+}
+
+/**
+ * 个人版 Coding Plan（不含 Start Plan 与 Team Plan）。
+ * Start Plan 用 disconnected 展示领取/付费卡，Team Plan 有独立文案，
+ * "服务端明确无权益"只对个人版需要区分成"未开通"。
+ */
+export function isIndividualCodingPlanModelProviderId(id: string): boolean {
+  return (
+    id === BUILTIN_MODEL_PROVIDER_IDS.zaiIndividualCodingPlan ||
+    id === BUILTIN_MODEL_PROVIDER_IDS.bigmodelIndividualCodingPlan
+  );
+}
+
+export function isCodingPlanModelProviderId(id: string): boolean {
+  return (
+    isZaiCodingPlanProviderId(id) ||
+    id === BUILTIN_MODEL_PROVIDER_IDS.bigmodelIndividualCodingPlan ||
+    id === BUILTIN_MODEL_PROVIDER_IDS.bigmodelTeamCodingPlan ||
+    id === BUILTIN_MODEL_PROVIDER_IDS.bigmodelStartPlan
+  );
+}
+
+/** 一个正式 Model 的连通性测试结果。 */
+export type ModelConnectivityResult =
+  | { readonly success: true }
+  | {
+      readonly success: false;
+      readonly error: {
+        readonly message: string;
+        /** 设置连接测试边界已确认的资格失败；其他执行错误保留原消息。 */
+        readonly code?: "provider-unavailable" | "model-unavailable";
+      };
+    };

package/server/vendor/zcode/packages/shared/src/model-selection.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+
+/** 用户对后续模型执行的完整选择；不表达已经创建的 Active Model。 */
+export const modelSelectionSchema = z
+  .object({
+    providerId: z.string().trim().min(1),
+    modelId: z.string().trim().min(1),
+    options: z
+      .object({
+        reasoningLevel: z.string().trim().min(1).optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+export type ModelSelection = z.infer<typeof modelSelectionSchema>;
+
+/** 公共解析结果。页面可以展示不完整选择，执行入口必须同时检查 selectionIssue。 */
+export interface EffectiveModelSelectionResult {
+  readonly effectiveSelection: ModelSelection | null;
+  readonly selectionIssue?:
+    | "selection-missing"
+    | "account-connection-unavailable"
+    | "provider-not-found"
+    | "model-not-found"
+    | "reasoning-level-missing"
+    | "reasoning-level-not-supported";
+}
+
+export const ZCODE_MODEL_REASONING_SEPARATOR = "$";
+
+/** UI Picker/legacy CLI 的展示值；不是可逆的 ModelSelection 序列化格式。 */
+export function formatModelPickerValue(selection: ModelSelection | undefined): string {
+  // 只在显示边界把未绑定表示为空；实际执行仍校验完整 ModelSelection。
+  if (!selection) return "";
+  const base = `${selection.providerId}/${selection.modelId}`;
+  const reasoningLevel = selection.options?.reasoningLevel;
+  return reasoningLevel ? `${base}${ZCODE_MODEL_REASONING_SEPARATOR}${reasoningLevel}` : base;
+}
+
+/** 只解析 Picker/legacy 字符串边界；领域状态与协议必须直接保存 ModelSelection。 */
+export function parseModelPickerValue(value: string): ModelSelection {
+  const normalized = value.trim();
+  const providerSeparatorIndex = normalized.indexOf("/");
+  if (providerSeparatorIndex <= 0) {
+    throw new Error(`模型选择缺少 Provider: ${normalized}`);
+  }
+  const providerId = normalized.slice(0, providerSeparatorIndex);
+  const rawModelId = normalized.slice(providerSeparatorIndex + 1);
+  const reasoningSeparatorIndex = rawModelId.indexOf(ZCODE_MODEL_REASONING_SEPARATOR);
+  if (reasoningSeparatorIndex <= 0 || reasoningSeparatorIndex >= rawModelId.length - 1) {
+    return modelSelectionSchema.parse({ providerId, modelId: rawModelId });
+  }
+  return modelSelectionSchema.parse({
+    providerId,
+    modelId: rawModelId.slice(0, reasoningSeparatorIndex),
+    options: { reasoningLevel: rawModelId.slice(reasoningSeparatorIndex + 1) },
+  });
+}