@downcity/city 1.1.4 → 1.1.6

package/src/cli/model/ModelReadCommand.ts

@@ -0,0 +1,207 @@
+/**
+ * `city model` 查询与绑定命令。
+ *
+ * 关键点（中文）
+ * - 这里只处理不修改平台模型池状态的命令。
+ * - `use` 虽然会写项目配置，但不会改动 console store，因此也归在这里。
+ */
+
+import type { Command } from "commander";
+import { PlatformStore } from "@downcity/agent";
+import { printResult } from "@/utils/cli/CliOutput.js";
+import {
+  discoverProviderModels,
+  resolveProjectRoot,
+  setProjectPrimaryModel,
+} from "./ModelSupport.js";
+import {
+  parseBooleanOption,
+  runStoreCommand,
+  toSafeProviderView,
+} from "./ModelCommandShared.js";
+
+/**
+ * 注册 `list/get/discover/use` 命令。
+ */
+export function registerModelReadCommands(model: Command): void {
+  registerListCommand(model);
+  registerGetCommands(model);
+  registerDiscoverCommand(model);
+  registerUseCommand(model);
+}
+
+function registerListCommand(model: Command): void {
+  model
+    .command("list")
+    .description("列出 provider 与 model")
+    .option("--json [enabled]", "以 JSON 输出", parseBooleanOption, true)
+    .helpOption("--help", "display help for command")
+    .action(async (options: { json?: boolean }) => {
+      await runStoreCommand(options, async (store) => {
+        const providers = (await store.listProviders()).map((item) => toSafeProviderView(item));
+        const models = store.listModels();
+        return {
+          title: "platform models listed",
+          payload: {
+            providers,
+            models,
+            providerIds: providers.map((item) => item.id),
+            modelIds: models.map((item) => item.id),
+          },
+        };
+      });
+    });
+}
+
+function registerGetCommands(model: Command): void {
+  const get = model
+    .command("get")
+    .description("读取 provider/model 详情")
+    .helpOption("--help", "display help for command");
+
+  get
+    .command("provider <providerId>")
+    .description("读取 provider 详情")
+    .option("--json [enabled]", "以 JSON 输出", parseBooleanOption, true)
+    .helpOption("--help", "display help for command")
+    .action(async (providerId: string, options: { json?: boolean }) => {
+      await runStoreCommand(options, async (store) => {
+        const id = String(providerId || "").trim();
+        if (!id) throw new Error("providerId cannot be empty");
+        const provider = await store.getProvider(id);
+        if (!provider) throw new Error(`Provider not found: ${id}`);
+        return {
+          title: "provider loaded",
+          payload: {
+            providerId: id,
+            provider: toSafeProviderView(provider),
+          },
+        };
+      });
+    });
+
+  get
+    .command("model <modelId>")
+    .description("读取 model 详情")
+    .option("--json [enabled]", "以 JSON 输出", parseBooleanOption, true)
+    .helpOption("--help", "display help for command")
+    .action(async (modelId: string, options: { json?: boolean }) => {
+      await runStoreCommand(options, async (store) => {
+        const id = String(modelId || "").trim();
+        if (!id) throw new Error("modelId cannot be empty");
+        const modelConfig = store.getModel(id);
+        if (!modelConfig) throw new Error(`Model not found: ${id}`);
+        return {
+          title: "model loaded",
+          payload: {
+            modelId: id,
+            model: modelConfig,
+          },
+        };
+      });
+    });
+}
+
+function registerDiscoverCommand(model: Command): void {
+  model
+    .command("discover <providerId>")
+    .description("发现 provider 可用模型（非交互）")
+    .option("--auto-add [enabled]", "自动写入发现到的模型", parseBooleanOption, false)
+    .option("--prefix <prefix>", "自动添加时的 modelId 前缀（默认不加前缀）")
+    .option("--json [enabled]", "以 JSON 输出", parseBooleanOption, true)
+    .helpOption("--help", "display help for command")
+    .action(async (
+      providerId: string,
+      options: { autoAdd?: boolean; prefix?: string; json?: boolean },
+    ) => {
+      await runStoreCommand(options, async (store) => {
+        const id = String(providerId || "").trim();
+        if (!id) throw new Error("providerId cannot be empty");
+        const provider = await store.getProvider(id);
+        if (!provider) throw new Error(`Provider not found: ${id}`);
+        const discovery = await discoverProviderModels({
+          providerId: id,
+          providerType: provider.type,
+          baseUrl: provider.baseUrl,
+          apiKey: provider.apiKey,
+        });
+        if (!discovery.ok) {
+          throw new Error(discovery.error || `provider discover failed (${discovery.status || "n/a"})`);
+        }
+
+        const autoAdded: Array<{ modelId: string; modelName: string }> = [];
+        if (options.autoAdd === true) {
+          const prefix = String(options.prefix || "").trim();
+          for (const remoteModelName of discovery.models) {
+            const modelName = String(remoteModelName || "").trim();
+            if (!modelName) continue;
+            const modelId = prefix ? `${prefix}${modelName}` : modelName;
+            if (store.getModel(modelId)) continue;
+            store.upsertModel({
+              id: modelId,
+              providerId: id,
+              name: modelName,
+            });
+            autoAdded.push({ modelId, modelName });
+          }
+        }
+
+        return {
+          title: "provider models discovered",
+          payload: {
+            providerId: id,
+            providerType: provider.type,
+            discoveredModels: discovery.models,
+            modelCount: discovery.models.length,
+            autoAdded,
+          },
+        };
+      });
+    });
+}
+
+function registerUseCommand(model: Command): void {
+  model
+    .command("use <modelId>")
+    .description("把项目 execution.modelId 绑定到指定模型（非交互）")
+    .option("--path <path>", "目标项目根目录（默认当前目录）", ".")
+    .option("--json [enabled]", "以 JSON 输出", parseBooleanOption, true)
+    .helpOption("--help", "display help for command")
+    .action(async (modelId: string, options: { path?: string; json?: boolean }) => {
+      const asJson = options.json !== false;
+      try {
+        const store = new PlatformStore();
+        try {
+          const id = String(modelId || "").trim();
+          if (!id) throw new Error("modelId cannot be empty");
+          const exists = store.getModel(id);
+          if (!exists) throw new Error(`Model not found in platform pool: ${id}`);
+        } finally {
+          store.close();
+        }
+        const projectRoot = resolveProjectRoot(options.path);
+        const changed = setProjectPrimaryModel(projectRoot, modelId);
+        printResult({
+          asJson,
+          success: true,
+          title: "project execution.modelId updated",
+          payload: {
+            projectRoot,
+            shipJsonPath: changed.shipJsonPath,
+            previousPrimary: changed.previousPrimary,
+            nextPrimary: changed.nextPrimary,
+          },
+        });
+      } catch (error) {
+        printResult({
+          asJson,
+          success: false,
+          title: "platform model use failed",
+          payload: {
+            error: error instanceof Error ? error.message : String(error),
+          },
+        });
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/model/ModelSupport.ts

@@ -0,0 +1,223 @@
+/**
+ * `city model` 支撑工具。
+ *
+ * 关键点（中文）
+ * - 收敛“路径处理、provider 模型发现、项目 model 绑定写入”等可复用逻辑。
+ * - 让命令编排文件保持在可维护规模内。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import type { LlmProviderType } from "@downcity/agent";
+import { getDowncityJsonPath } from "@/config/Paths.js";
+import type { DowncityConfig } from "@downcity/agent";
+
+const OPENAI_COMPAT_PROVIDER_TYPES = new Set<LlmProviderType>([
+  "openai",
+  "deepseek",
+  "moonshot-cn",
+  "moonshot-ai",
+  "kimi-code",
+  "xai",
+  "huggingface",
+  "openrouter",
+  "open-compatible",
+  "open-responses",
+]);
+
+export type ProviderDiscoveryResult = {
+  providerId: string;
+  providerType: LlmProviderType;
+  ok: boolean;
+  status?: number;
+  models: string[];
+  error?: string;
+};
+
+export function resolveEnvPlaceholder(value: string | undefined): string | undefined {
+  const raw = String(value || "").trim();
+  if (!raw) return undefined;
+  const matched = raw.match(/^\$\{([A-Z0-9_]+)\}$/);
+  if (!matched) return raw;
+  return process.env[matched[1]];
+}
+
+export function resolveProviderDefaultBaseUrl(
+  providerType: LlmProviderType,
+): string | undefined {
+  if (providerType === "deepseek") return "https://api.deepseek.com/v1";
+  if (providerType === "moonshot-cn") return "https://api.moonshot.cn/v1";
+  if (providerType === "moonshot-ai") return "https://api.moonshot.ai/v1";
+  if (providerType === "kimi-code") return "https://api.kimi.com/coding/v1";
+  if (providerType === "xai") return "https://api.x.ai/v1";
+  if (providerType === "openrouter") return "https://openrouter.ai/api/v1";
+  if (providerType === "open-compatible") return "https://api.openai.com/v1";
+  if (providerType === "open-responses") return "https://api.openai.com/v1";
+  return undefined;
+}
+
+export function normalizeBaseUrl(value: string | undefined): string | undefined {
+  const raw = String(value || "").trim().replace(/\/+$/, "");
+  return raw || undefined;
+}
+
+export function extractModelIdsFromPayload(payload: unknown): string[] {
+  if (!payload || typeof payload !== "object") return [];
+  const data = (payload as { data?: unknown }).data;
+  if (!Array.isArray(data)) return [];
+  const ids: string[] = [];
+  for (const item of data) {
+    if (!item || typeof item !== "object") continue;
+    const id = String((item as { id?: unknown; name?: unknown }).id || "").trim();
+    if (id) {
+      ids.push(id);
+      continue;
+    }
+    const name = String((item as { name?: unknown }).name || "").trim();
+    if (name) ids.push(name);
+  }
+  return [...new Set(ids)];
+}
+
+export async function discoverProviderModels(params: {
+  providerId: string;
+  providerType: LlmProviderType;
+  baseUrl?: string;
+  apiKey?: string;
+}): Promise<ProviderDiscoveryResult> {
+  const providerId = String(params.providerId || "").trim();
+  const providerType = params.providerType;
+  const baseUrl = normalizeBaseUrl(params.baseUrl) || resolveProviderDefaultBaseUrl(providerType);
+  const apiKey = resolveEnvPlaceholder(params.apiKey);
+  if (!apiKey) {
+    return {
+      providerId,
+      providerType,
+      ok: false,
+      models: [],
+      error: "Missing apiKey (or unresolved ${ENV_VAR})",
+    };
+  }
+
+  try {
+    if (providerType === "gemini") {
+      const url = `https://generativelanguage.googleapis.com/v1beta/models?key=${encodeURIComponent(apiKey)}`;
+      const response = await fetch(url, { method: "GET" });
+      const payload = (await response.json().catch(() => ({}))) as {
+        models?: Array<{ name?: unknown }>;
+      };
+      const models = Array.isArray(payload.models)
+        ? payload.models
+            .map((x) => String(x?.name || "").trim())
+            .filter(Boolean)
+            .map((x) => x.replace(/^models\//, ""))
+        : [];
+      return {
+        providerId,
+        providerType,
+        ok: response.ok,
+        status: response.status,
+        models: [...new Set(models)],
+        ...(response.ok ? {} : { error: `HTTP ${response.status}` }),
+      };
+    }
+
+    if (providerType === "anthropic") {
+      const url = "https://api.anthropic.com/v1/models";
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "x-api-key": apiKey,
+          "anthropic-version": "2023-06-01",
+        },
+      });
+      const payload = (await response.json().catch(() => ({}))) as unknown;
+      const models = extractModelIdsFromPayload(payload);
+      return {
+        providerId,
+        providerType,
+        ok: response.ok,
+        status: response.status,
+        models,
+        ...(response.ok ? {} : { error: `HTTP ${response.status}` }),
+      };
+    }
+
+    if (OPENAI_COMPAT_PROVIDER_TYPES.has(providerType)) {
+      const endpointBase = baseUrl || "https://api.openai.com/v1";
+      const response = await fetch(`${endpointBase}/models`, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+        },
+      });
+      const payload = (await response.json().catch(() => ({}))) as unknown;
+      const models = extractModelIdsFromPayload(payload);
+      return {
+        providerId,
+        providerType,
+        ok: response.ok,
+        status: response.status,
+        models,
+        ...(response.ok ? {} : { error: `HTTP ${response.status}` }),
+      };
+    }
+
+    return {
+      providerId,
+      providerType,
+      ok: false,
+      models: [],
+      error: `Model discovery is not implemented for provider type: ${providerType}`,
+    };
+  } catch (error) {
+    return {
+      providerId,
+      providerType,
+      ok: false,
+      models: [],
+      error: String(error),
+    };
+  }
+}
+
+export { resolveProjectRoot } from "../service/ServiceCommandSupport.js";
+
+/**
+ * 设置项目 `downcity.json.execution.modelId`。
+ *
+ * 关键点（中文）
+ * - 仅更新绑定字段，不触碰其他运行配置。
+ * - 该操作用于把“模型池中的模型 ID”绑定到具体 agent 项目。
+ */
+export function setProjectPrimaryModel(projectRoot: string, modelId: string): {
+  shipJsonPath: string;
+  previousPrimary: string;
+  nextPrimary: string;
+} {
+  const shipJsonPath = getDowncityJsonPath(projectRoot);
+  if (!fs.existsSync(shipJsonPath)) {
+    throw new Error(`downcity.json not found at ${shipJsonPath}`);
+  }
+  const raw = fs.readJsonSync(shipJsonPath) as Partial<DowncityConfig>;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`Invalid downcity.json: expected object (${shipJsonPath})`);
+  }
+  const previousPrimary =
+    String(raw.execution?.type === "api" ? raw.execution.modelId || "" : "").trim();
+  const nextPrimary = String(modelId || "").trim();
+  if (!nextPrimary) throw new Error("modelId cannot be empty");
+  const nextConfig: DowncityConfig = {
+    ...(raw as DowncityConfig),
+    execution: {
+      type: "api",
+      modelId: nextPrimary,
+    },
+  };
+  fs.writeJsonSync(shipJsonPath, nextConfig, { spaces: 2 });
+  return {
+    shipJsonPath,
+    previousPrimary,
+    nextPrimary,
+  };
+}

package/src/cli/model/preset/ModelPresetManager.ts

@@ -0,0 +1,242 @@
+/**
+ * ModelPresetManager：LLM 模型预设管理器。
+ *
+ * 关键点（中文）
+ * - 统一管理 init 场景的“模型预设清单 + providerType 映射 + 自定义模型标记”。
+ * - 避免命令层直接依赖硬编码常量，提升可维护性与一致性。
+ */
+
+import type { LlmProviderType } from "@downcity/agent";
+
+/**
+ * 单个模型预设定义。
+ */
+export type ModelPreset = {
+  /**
+   * 预设 ID（同时作为模型名称写入 `llm.models.<active>.name`，除自定义模型外）。
+   */
+  id: string;
+
+  /**
+   * 预设标题（用于 CLI 交互显示）。
+   */
+  title: string;
+
+  /**
+   * 对应 provider 类型（用于生成 `llm.providers.<id>.type`）。
+   */
+  providerTypes: readonly LlmProviderType[];
+
+  /**
+   * 是否属于“模型名由环境变量注入”的自定义模型类型。
+   */
+  useCustomModelName: boolean;
+};
+
+const CUSTOM_MODEL_IDS = new Set<string>(["open-compatible", "open-responses"]);
+
+const MODEL_PRESETS: ModelPreset[] = [
+  // Claude 系列
+  {
+    id: "claude-sonnet-4-5",
+    title: "Claude Sonnet 4",
+    providerTypes: ["anthropic"],
+    useCustomModelName: false,
+  },
+  {
+    id: "claude-haiku",
+    title: "Claude Haiku",
+    providerTypes: ["anthropic"],
+    useCustomModelName: false,
+  },
+  {
+    id: "claude-3-5-sonnet-20241022",
+    title: "Claude 3.5 Sonnet",
+    providerTypes: ["anthropic"],
+    useCustomModelName: false,
+  },
+  {
+    id: "claude-3-opus-20240229",
+    title: "Claude 3 Opus",
+    providerTypes: ["anthropic"],
+    useCustomModelName: false,
+  },
+  // OpenAI GPT 系列
+  {
+    id: "gpt-4",
+    title: "GPT-4",
+    providerTypes: ["openai"],
+    useCustomModelName: false,
+  },
+  {
+    id: "gpt-4-turbo",
+    title: "GPT-4 Turbo",
+    providerTypes: ["openai"],
+    useCustomModelName: false,
+  },
+  {
+    id: "gpt-4o",
+    title: "GPT-4o",
+    providerTypes: ["openai"],
+    useCustomModelName: false,
+  },
+  {
+    id: "gpt-3.5-turbo",
+    title: "GPT-3.5 Turbo",
+    providerTypes: ["openai"],
+    useCustomModelName: false,
+  },
+  // DeepSeek
+  {
+    id: "deepseek-chat",
+    title: "DeepSeek Chat",
+    providerTypes: ["deepseek"],
+    useCustomModelName: false,
+  },
+  // Gemini
+  {
+    id: "gemini-2.5-pro",
+    title: "Gemini 2.5 Pro",
+    providerTypes: ["gemini"],
+    useCustomModelName: false,
+  },
+  {
+    id: "gemini-2.5-flash",
+    title: "Gemini 2.5 Flash",
+    providerTypes: ["gemini"],
+    useCustomModelName: false,
+  },
+  // xAI
+  {
+    id: "grok-3",
+    title: "xAI Grok 3",
+    providerTypes: ["xai"],
+    useCustomModelName: false,
+  },
+  // HuggingFace Router
+  {
+    id: "meta-llama/Llama-3.1-8B-Instruct",
+    title: "HF Llama 3.1 8B",
+    providerTypes: ["huggingface"],
+    useCustomModelName: false,
+  },
+  // OpenRouter
+  {
+    id: "openrouter/auto",
+    title: "OpenRouter Auto",
+    providerTypes: ["openrouter"],
+    useCustomModelName: false,
+  },
+  // Moonshot(Kimi)
+  {
+    id: "kimi-k2.5",
+    title: "Kimi K2.5",
+    providerTypes: ["moonshot-cn", "moonshot-ai"],
+    useCustomModelName: false,
+  },
+  {
+    id: "kimi-for-coding",
+    title: "Kimi For Coding",
+    providerTypes: ["kimi-code"],
+    useCustomModelName: false,
+  },
+  // OpenAI-compatible（Chat Completions）
+  {
+    id: "open-compatible",
+    title: "Open-compatible model",
+    providerTypes: ["open-compatible"],
+    useCustomModelName: true,
+  },
+  // OpenAI-compatible（Responses）
+  {
+    id: "open-responses",
+    title: "Open-responses model",
+    providerTypes: ["open-responses"],
+    useCustomModelName: true,
+  },
+];
+
+const DEFAULT_MODEL_PRESET_ID = "claude-sonnet-4-5";
+const FALLBACK_MODEL_PRESET_ID = "open-compatible";
+
+/**
+ * init 模型选择解析结果。
+ */
+export type ResolvedInitModelPreset = {
+  /**
+   * 规范化后的模型预设 ID。
+   */
+  selectedModelId: string;
+
+  /**
+   * 选中的模型预设。
+   */
+  preset: ModelPreset;
+};
+
+/**
+ * 模型预设管理器。
+ */
+export class ModelPresetManager {
+  private readonly presets: ModelPreset[];
+  private readonly presetsById: Map<string, ModelPreset>;
+
+  constructor() {
+    this.presets = [...MODEL_PRESETS];
+    this.presetsById = new Map(
+      this.presets.map((preset) => [preset.id, preset] as const),
+    );
+  }
+
+  /**
+   * 列出所有可选模型预设（按定义顺序）。
+   */
+  listPresets(): ModelPreset[] {
+    return [...this.presets];
+  }
+
+  /**
+   * 根据预设 ID 获取模型预设。
+   */
+  getPreset(id: string): ModelPreset | undefined {
+    const key = String(id || "").trim();
+    if (!key) return undefined;
+    return this.presetsById.get(key);
+  }
+
+  /**
+   * 判断预设是否支持指定 provider 类型。
+   */
+  supportsProviderType(preset: ModelPreset, providerType: LlmProviderType): boolean {
+    return preset.providerTypes.includes(providerType);
+  }
+
+  /**
+   * 获取默认模型预设。
+   */
+  getDefaultPreset(): ModelPreset {
+    return (
+      this.getPreset(DEFAULT_MODEL_PRESET_ID) ||
+      this.getPreset(FALLBACK_MODEL_PRESET_ID) ||
+      this.presets[0]
+    );
+  }
+
+  /**
+   * 解析 init 输入的模型选择，并返回稳定的预设结果。
+   */
+  resolveInitPreset(input?: string): ResolvedInitModelPreset {
+    const selectedModelId = String(input || "").trim();
+    const preset =
+      this.getPreset(selectedModelId) ||
+      this.getPreset(FALLBACK_MODEL_PRESET_ID) ||
+      this.getDefaultPreset();
+    return {
+      selectedModelId: selectedModelId || preset.id,
+      preset: {
+        ...preset,
+        useCustomModelName: CUSTOM_MODEL_IDS.has(preset.id),
+      },
+    };
+  }
+}