@downcity/city 1.1.39 → 1.1.47

package/src/control/EnvApiRoutes.ts

@@ -2,7 +2,7 @@
  * 平台环境变量管理路由。
  *
  * 关键点（中文）
- * - 提供 control plane 级与 agent 级环境变量的统一读写接口。
+ * - 当前只提供平台全局 env 的统一读写接口。
  * - 所有 value 在 DB 中以密文存储，这里的接口只负责明文读写与删除。
  */
 
@@ -10,14 +10,6 @@ import dotenv from "dotenv";
 import type { Hono } from "hono";
 import { PlatformStore } from "@/platform/store/index.js";
 
-type EnvScope = "global" | "agent";
-
-function normalizeScope(input: string | undefined): EnvScope {
-  const value = String(input || "").trim().toLowerCase();
-  if (value === "agent") return "agent";
-  return "global";
-}
-
 function normalizeNonEmptyText(value: unknown, fieldName: string): string {
   const text = String(value || "").trim();
   if (!text) {
@@ -74,32 +66,9 @@ export function registerPlatformEnvRoutes(params: {
   const app = params.app;
 
   app.get("/api/ui/env", async (c) => {
-    const scope = normalizeScope(c.req.query("scope"));
-    const agentIdRaw = c.req.query("agent");
     const store = new PlatformStore();
     try {
-      if (scope === "agent") {
-        const agentId = String(agentIdRaw || "").trim();
-        const rows = agentId
-          ? await store.listAgentEnvEntries(agentId)
-          : await store.listAllAgentEnvEntries();
-        return c.json({
-          success: true,
-          scope,
-          agentId: agentId || undefined,
-          items: rows.map((item) => ({
-            scope: "agent" as const,
-            agentId: item.agentId,
-            key: item.key,
-            description: item.description,
-            value: item.value,
-            createdAt: item.createdAt,
-            updatedAt: item.updatedAt,
-          })),
-        });
-      }
-
-      const rows = await store.listGlobalEnvEntries();
+      const rows = await store.listEnvEntries();
       return c.json({
         success: true,
         scope: "global",
@@ -122,35 +91,17 @@ export function registerPlatformEnvRoutes(params: {
   app.post("/api/ui/env/upsert", async (c) => {
     try {
       const body = (await c.req.json().catch(() => ({}))) as {
-        scope?: string;
-        agentId?: string;
         key?: string;
         description?: string;
         value?: string;
       };
-      const scope = normalizeScope(body.scope);
       const key = normalizeNonEmptyText(body.key, "env key");
       const description = String(body.description || "").trim();
       const value = String(body.value ?? "");
       const store = new PlatformStore();
       try {
-        if (scope === "agent") {
-          const agentId = normalizeNonEmptyText(body.agentId, "agentId");
-          await store.upsertAgentEnvEntry({
-            agentId,
-            key,
-            description,
-            value,
-          });
-          return c.json({
-            success: true,
-            scope,
-            agentId,
-            key,
-          });
-        }
-
-        await store.upsertGlobalEnvEntry({
+        await store.upsertEnvEntry({
+          scope: "global",
           key,
           description,
           value,
@@ -171,26 +122,12 @@ export function registerPlatformEnvRoutes(params: {
   app.post("/api/ui/env/remove", async (c) => {
     try {
       const body = (await c.req.json().catch(() => ({}))) as {
-        scope?: string;
-        agentId?: string;
         key?: string;
       };
-      const scope = normalizeScope(body.scope);
       const key = normalizeNonEmptyText(body.key, "env key");
       const store = new PlatformStore();
       try {
-        if (scope === "agent") {
-          const agentId = normalizeNonEmptyText(body.agentId, "agentId");
-          store.removeAgentEnvEntry(agentId, key);
-          return c.json({
-            success: true,
-            scope,
-            agentId,
-            key,
-          });
-        }
-
-        store.removeGlobalEnvEntry(key);
+        store.removeEnvEntry(key);
         return c.json({
           success: true,
           scope: "global",
@@ -207,35 +144,14 @@ export function registerPlatformEnvRoutes(params: {
   app.post("/api/ui/env/import", async (c) => {
     try {
       const body = (await c.req.json().catch(() => ({}))) as {
-        scope?: string;
-        agentId?: string;
         raw?: string;
       };
-      const scope = normalizeScope(body.scope);
       const entries = parseDotenvEntries(body.raw);
       const store = new PlatformStore();
       try {
-        if (scope === "agent") {
-          const agentId = normalizeNonEmptyText(body.agentId, "agentId");
-          for (const entry of entries) {
-            await store.upsertAgentEnvEntry({
-              agentId,
-              key: entry.key,
-              description: "",
-              value: entry.value,
-            });
-          }
-          return c.json({
-            success: true,
-            scope,
-            agentId,
-            count: entries.length,
-            keys: entries.map((entry) => entry.key),
-          });
-        }
-
         for (const entry of entries) {
-          await store.upsertGlobalEnvEntry({
+          await store.upsertEnvEntry({
+            scope: "global",
             key: entry.key,
             description: "",
             value: entry.value,

package/src/control/PlatformApiRoutes.ts

@@ -34,7 +34,7 @@ export interface PlatformApiRouteHandlers {
   buildAgentsResponse(requestedAgentId: string): Promise<PlatformAgentsResponse>;
   /** 初始化 agent 项目骨架。 */
   initializeAgentProject(projectRoot: string, initialization: {
-    agentName?: unknown;
+    id?: unknown;
     modelId?: unknown;
     forceOverwriteShipJson?: unknown;
   }): Promise<AgentProjectInitializationResult>;
@@ -42,7 +42,7 @@ export interface PlatformApiRouteHandlers {
   startAgentByProjectRoot(projectRoot: string, options?: {
     initializeIfNeeded?: boolean;
     initialization?: {
-      agentName?: unknown;
+      id?: unknown;
       modelId?: unknown;
       localModel?: unknown;
       agentType?: unknown;
@@ -174,7 +174,7 @@ export function registerPlatformApiRoutes(params: {
         projectRoot?: unknown;
         initializeIfNeeded?: unknown;
         initialization?: {
-          agentName?: unknown;
+          id?: unknown;
           modelId?: unknown;
           forceOverwriteShipJson?: unknown;
         };
@@ -197,7 +197,7 @@ export function registerPlatformApiRoutes(params: {
     try {
       const body = (await c.req.json().catch(() => ({}))) as {
         projectRoot?: unknown;
-        agentName?: unknown;
+        id?: unknown;
         modelId?: unknown;
         autoStart?: unknown;
         forceOverwriteShipJson?: unknown;
@@ -207,7 +207,7 @@ export function registerPlatformApiRoutes(params: {
         return c.json({ success: false, error: "projectRoot is required" }, 400);
       }
       const initResult = await handlers.initializeAgentProject(rawProject, {
-        agentName: body.agentName,
+        id: body.id,
         modelId: body.modelId,
         forceOverwriteShipJson: body.forceOverwriteShipJson,
       });
@@ -217,7 +217,7 @@ export function registerPlatformApiRoutes(params: {
           created: true,
           started: false,
           projectRoot: initResult.projectRoot,
-          agentName: initResult.agentName,
+          id: initResult.id,
           message: "created",
         });
       }

package/src/control/gateway/AgentActions.ts

@@ -50,14 +50,14 @@ function resolveExecutionInput(params: {
   };
 }
 
-function resolveManagedAgentNameFromProjectRoot(projectRoot: string): string {
+function resolveManagedAgentIdFromProjectRoot(projectRoot: string): string {
   const normalizedRoot = path.resolve(String(projectRoot || "").trim() || ".");
   const fallback = path.basename(normalizedRoot);
   const configPath = getDowncityJsonPath(normalizedRoot);
   try {
-    const raw = fs.readJsonSync(configPath) as { name?: unknown };
-    const name = typeof raw.name === "string" ? raw.name.trim() : "";
-    return name || fallback;
+    const raw = fs.readJsonSync(configPath) as { id?: unknown };
+    const agentId = typeof raw.id === "string" ? raw.id.trim() : "";
+    return agentId || fallback;
   } catch {
     return fallback;
   }
@@ -68,7 +68,7 @@ function resolveManagedAgentNameFromProjectRoot(projectRoot: string): string {
  */
 export async function initializePlatformAgentProject(params: {
   projectRoot: string;
-  agentName?: unknown;
+  id?: unknown;
   modelId?: unknown;
   forceOverwriteShipJson?: unknown;
 }): Promise<AgentProjectInitializationResult> {
@@ -79,7 +79,7 @@ export async function initializePlatformAgentProject(params: {
   return initializeAgentProject(
     {
       projectRoot: params.projectRoot,
-      agentName: String(params.agentName || "").trim() || undefined,
+      id: String(params.id || "").trim() || undefined,
       execution,
       forceOverwriteShipJson: params.forceOverwriteShipJson === true,
     },
@@ -242,7 +242,7 @@ export async function startManagedAgentByProjectRoot(params: {
   cliPath: string;
   initializeIfNeeded?: boolean;
     initialization?: {
-      agentName?: unknown;
+      id?: unknown;
       modelId?: unknown;
       forceOverwriteShipJson?: unknown;
     };
@@ -281,7 +281,7 @@ export async function startManagedAgentByProjectRoot(params: {
     await initializeAgentProject(
       {
         projectRoot: normalizedRoot,
-        agentName: String(params.initialization?.agentName || "").trim() || undefined,
+        id: String(params.initialization?.id || "").trim() || undefined,
         execution,
         forceOverwriteShipJson: params.initialization?.forceOverwriteShipJson === true,
       },
@@ -330,8 +330,8 @@ export async function inspectManagedAgentRestartSafety(params: {
   const targetAgent = knownAgents.find(
     (item) => path.resolve(String(item.projectRoot || "")) === normalizedRoot,
   );
-  const agentId = String(targetAgent?.name || "").trim()
-    || resolveManagedAgentNameFromProjectRoot(normalizedRoot);
+  const agentId = String(targetAgent?.agentId || "").trim()
+    || resolveManagedAgentIdFromProjectRoot(normalizedRoot);
 
   const sessionRootDir = getDowncitySessionRootDirPath(normalizedRoot, agentId);
   if (await fs.pathExists(sessionRootDir)) {

package/src/control/gateway/AgentCatalog.ts

@@ -184,14 +184,14 @@ async function buildAgentOption(
   const running = Boolean(daemonPid && isProcessAlive(daemonPid));
   const endpoint = await resolveRuntimeEndpoint(projectRoot);
 
-  let displayName = basename(projectRoot);
+  let agentId = basename(projectRoot);
   let ship: PlatformAgentShipJson | null = null;
   try {
     const shipPath = getDowncityJsonPath(projectRoot);
     if (await fs.pathExists(shipPath)) {
       ship = (await fs.readJson(shipPath)) as PlatformAgentShipJson;
-      const name = String(ship?.name || "").trim();
-      if (name) displayName = name;
+      const configuredAgentId = String(ship?.id || "").trim();
+      if (configuredAgentId) agentId = configuredAgentId;
     }
   } catch {
     // ignore
@@ -205,7 +205,7 @@ async function buildAgentOption(
 
   return {
     id: projectRoot,
-    name: displayName,
+    agentId,
     projectRoot,
     running,
     host: running ? endpoint.host : undefined,
@@ -245,7 +245,7 @@ export async function listKnownPlatformAgents(): Promise<PlatformAgentOption[]>
     const runningA = a.running === true ? 1 : 0;
     const runningB = b.running === true ? 1 : 0;
     if (runningA !== runningB) return runningB - runningA;
-    return a.name.localeCompare(b.name);
+    return a.agentId.localeCompare(b.agentId);
   });
 }
 
@@ -325,18 +325,18 @@ export async function inspectPlatformAgentDirectory(
   const knownAgents = await listKnownPlatformAgents();
   const matched = knownAgents.find((item) => item.projectRoot === normalizedRoot) || null;
 
-  let displayName = basename(normalizedRoot);
+  let agentId = basename(normalizedRoot);
   let modelId = "";
   if (hasShipJson) {
     try {
       const ship = (await fs.readJson(shipPath)) as PlatformAgentShipJson;
-      displayName = String(ship?.name || "").trim() || displayName;
+      agentId = String(ship?.id || "").trim() || agentId;
       modelId = String(ship?.execution?.modelId || "").trim();
     } catch {
       // ignore parse failures
     }
-  } else if (matched?.name) {
-    displayName = matched.name;
+  } else if (matched?.agentId) {
+    agentId = matched.agentId;
   }
 
   return {
@@ -346,21 +346,17 @@ export async function inspectPlatformAgentDirectory(
     hasProfileMd,
     knownAgent: matched !== null,
     running: matched?.running === true,
-    displayName,
-        
+    ...(agentId ? { agentId } : {}),
+    ...(modelId ? { modelId } : {}),
   };
 }
 
 /**
- * 读取平台可选的本地 GGUF 模型列表。
+ * 构建 Global Model 面板响应。
  *
  * 关键点（中文）
- * - 如果项目已存在 `downcity.json`，优先尊重 `plugins.lmp.modelsDir`。
- * - 若项目未初始化，则回退到默认 `~/.models`，保证首次创建 agent 时也能直接选择。
- */
-
-/**
- * 构建 Global Model 面板响应。
+ * - 读取当前选中 agent 的 `execution.modelId`，再去平台模型池里补全 provider/model 信息。
+ * - 这里只返回全局模型池视图，不解析项目内本地模型目录。
  */
 export async function buildPlatformModelResponse(params: {
   requestedAgentId: string;
@@ -605,7 +601,7 @@ export async function buildPlatformConfigStatusResponse(params: {
   return {
     success: true,
     selectedAgentId: selectedAgent?.id || "",
-    selectedAgentName: selectedAgent?.name || "",
-      items: [...platformChecks, ...agentChecks],
-    };
+    selectedAgentProjectId: selectedAgent?.agentId || "",
+    items: [...platformChecks, ...agentChecks],
+  };
 }

package/src/control/instant/InstantSessionRunner.ts

@@ -32,6 +32,7 @@ import type {
 } from "@downcity/agent";
 import { InstantSystemComposer } from "@/control/instant/InstantSystemComposer.js";
 import { createRuntimeModel } from "@/model/runtime/CreateRuntimeModel.js";
+import { mergeProcessEnvWithPlatformGlobalEnv } from "@/env/ProcessEnv.js";
 import type { Logger as AgentLogger } from "@downcity/agent";
 
 type InstantSessionRunnerOptions = {
@@ -232,13 +233,14 @@ export class InstantSessionRunner implements PlatformInlineInstantRunner {
     });
     const model = await createRuntimeModel({
       config: {
-        name: "console-inline-instant-model",
+        id: "console_inline_instant_model",
         version: "1.0.0",
         execution: {
           type: "api",
           modelId,
         },
       },
+      env: mergeProcessEnvWithPlatformGlobalEnv(process.env),
     });
     const compactionComposer = new JsonlSessionCompactionComposer();
     const systemComposer = new InstantSystemComposer({

package/src/env/ProcessEnv.ts

@@ -0,0 +1,43 @@
+/**
+ * 平台全局环境变量读取与合并模块。
+ *
+ * 职责说明（中文）
+ * - 从平台 store 读取 global env。
+ * - 为 city 宿主提供显式 env 合并能力，避免让 `@downcity/agent` 直接依赖 `process.env`。
+ *
+ * 边界说明（中文）
+ * - 这里只处理 global env，不处理项目 `.env`。
+ * - 不负责 session 级运行时元信息（例如 `DC_SESSION_ID`）。
+ */
+
+import { PlatformStore } from "@/platform/store/index.js";
+
+/**
+ * 读取平台 global env 映射。
+ */
+export function readPlatformGlobalEnv(): Record<string, string> {
+  const store = new PlatformStore();
+  try {
+    return store.getEnvMapSync();
+  } catch {
+    return {};
+  } finally {
+    store.close();
+  }
+}
+
+/**
+ * 合并平台 global env 到目标环境变量映射。
+ *
+ * 关键点（中文）
+ * - 平台 global env 视为宿主层统一真相，应覆盖基础进程环境中的同名键。
+ * - 返回新对象，不直接修改传入参数。
+ */
+export function mergeProcessEnvWithPlatformGlobalEnv(
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  return {
+    ...baseEnv,
+    ...readPlatformGlobalEnv(),
+  };
+}

package/src/http/auth/AuthEnv.ts

@@ -55,7 +55,7 @@ export function resolveInvocationToken(params: {
  *
  * 关键点（中文）
  * - shell / task script / ACP 等通用执行面不应默认继承任何 HTTP 鉴权信息。
- * - 这样可以强制这些链路优先走 RPC，而不是通过环境变量隐式改走本地 HTTP。
+ * - 这样可以避免这些链路因为环境变量而隐式带上本地/远程 HTTP 鉴权。
  */
 export function stripInvocationAuthEnv(targetEnv: NodeJS.ProcessEnv): void {
   delete targetEnv[CLI_AUTH_TOKEN_ENV_KEY];

package/src/model/runtime/CreateRuntimeModel.ts

@@ -54,8 +54,30 @@ type RuntimeModelFactoryInput = {
    * - 仅用于把 sessionId 透传到 LLM 请求日志元数据。
    */
   getSessionRunScope?: () => ModelLogContext | undefined;
+  /**
+   * 宿主显式注入的运行时 env。
+   *
+   * 关键点（中文）
+   * - 这里只作为 provider apiKey 的回退来源。
+   * - 不再从 `downcity.json` 或 provider 配置里解析 `${ENV_KEY}` 占位符。
+   */
+  env?: Record<string, string> | NodeJS.ProcessEnv;
 };
 
+function normalizeRuntimeEnv(
+  env: Record<string, string> | NodeJS.ProcessEnv | undefined,
+): Record<string, string> {
+  const resolved: Record<string, string> = {};
+  if (!env) return resolved;
+  for (const [key, value] of Object.entries(env)) {
+    const normalizedKey = String(key || "").trim();
+    if (!normalizedKey) continue;
+    if (value === undefined || value === null) continue;
+    resolved[normalizedKey] = String(value);
+  }
+  return resolved;
+}
+
 function readProjectExecutionBinding(
   config: DowncityConfig,
 ): { type: "api"; modelId: string } | null {
@@ -98,63 +120,58 @@ function resolveProviderDefaultBaseUrl(
   return undefined;
 }
 
-function resolveEnvPlaceholder(value: string | undefined): string | undefined {
-  if (!value) return value;
-  if (value.startsWith("${") && value.endsWith("}")) {
-    const envVar = value.slice(2, -1);
-    return process.env[envVar];
-  }
-  return value;
-}
-
-function resolveApiKeyFallback(providerType: LlmProviderType): string | undefined {
+function resolveApiKeyFallback(
+  providerType: LlmProviderType,
+  env: Record<string, string> | undefined,
+): string | undefined {
+  const runtimeEnv = env || {};
   if (providerType === "gemini") {
     return (
-      process.env.GEMINI_API_KEY ||
-      process.env.GOOGLE_API_KEY ||
-      process.env.GOOGLE_GENERATIVE_AI_API_KEY ||
-      process.env.API_KEY
+      runtimeEnv.GEMINI_API_KEY ||
+      runtimeEnv.GOOGLE_API_KEY ||
+      runtimeEnv.GOOGLE_GENERATIVE_AI_API_KEY ||
+      runtimeEnv.API_KEY
     );
   }
   if (providerType === "anthropic") {
-    return process.env.ANTHROPIC_API_KEY || process.env.API_KEY;
+    return runtimeEnv.ANTHROPIC_API_KEY || runtimeEnv.API_KEY;
   }
   if (providerType === "deepseek") {
     return (
-      process.env.DEEPSEEK_API_KEY ||
-      process.env.OPENAI_API_KEY ||
-      process.env.API_KEY
+      runtimeEnv.DEEPSEEK_API_KEY ||
+      runtimeEnv.OPENAI_API_KEY ||
+      runtimeEnv.API_KEY
     );
   }
   if (providerType === "xai") {
-    return process.env.XAI_API_KEY || process.env.API_KEY;
+    return runtimeEnv.XAI_API_KEY || runtimeEnv.API_KEY;
   }
   if (providerType === "huggingface") {
     return (
-      process.env.HUGGINGFACE_API_KEY ||
-      process.env.HF_TOKEN ||
-      process.env.API_KEY
+      runtimeEnv.HUGGINGFACE_API_KEY ||
+      runtimeEnv.HF_TOKEN ||
+      runtimeEnv.API_KEY
     );
   }
   if (providerType === "openrouter") {
-    return process.env.OPENROUTER_API_KEY || process.env.API_KEY;
+    return runtimeEnv.OPENROUTER_API_KEY || runtimeEnv.API_KEY;
   }
   if (providerType === "moonshot-cn" || providerType === "moonshot-ai") {
     return (
-      process.env.MOONSHOT_API_KEY ||
-      process.env.KIMI_API_KEY ||
-      process.env.API_KEY
+      runtimeEnv.MOONSHOT_API_KEY ||
+      runtimeEnv.KIMI_API_KEY ||
+      runtimeEnv.API_KEY
     );
   }
   if (providerType === "kimi-code") {
     return (
-      process.env.KIMI_CODE_API_KEY ||
-      process.env.KIMI_API_KEY ||
-      process.env.MOONSHOT_API_KEY ||
-      process.env.API_KEY
+      runtimeEnv.KIMI_CODE_API_KEY ||
+      runtimeEnv.KIMI_API_KEY ||
+      runtimeEnv.MOONSHOT_API_KEY ||
+      runtimeEnv.API_KEY
     );
   }
-  return process.env.OPENAI_API_KEY || process.env.API_KEY;
+  return runtimeEnv.OPENAI_API_KEY || runtimeEnv.API_KEY;
 }
 
 function normalizeProviderType(value: unknown): LlmProviderType | null {
@@ -262,6 +279,7 @@ export async function createRuntimeModel(
   input: RuntimeModelFactoryInput,
 ): Promise<LanguageModel> {
   const logger = getLogger();
+  const runtimeEnv = normalizeRuntimeEnv(input.env);
   const execution = readProjectExecutionBinding(input.config);
   if (!execution) {
     await logger.log("warn", "No agent execution configured");
@@ -300,20 +318,19 @@ export async function createRuntimeModel(
     throw new Error(`Unsupported LLM provider type: ${providerConfig.type}`);
   }
 
-  const resolvedModel = resolveEnvPlaceholder(modelConfig.name);
-  if (!resolvedModel || resolvedModel === "${}") {
+  const resolvedModel = String(modelConfig.name || "").trim();
+  if (!resolvedModel) {
     await logger.log("warn", "No LLM model name configured");
     throw new Error("No LLM model name configured");
   }
 
   const resolvedBaseUrl = normalizeOptionalBaseUrl(
-    resolveEnvPlaceholder(providerConfig.baseUrl) ||
-      resolveProviderDefaultBaseUrl(providerType),
+    providerConfig.baseUrl || resolveProviderDefaultBaseUrl(providerType),
   );
 
-  let resolvedApiKey = resolveEnvPlaceholder(providerConfig.apiKey);
+  let resolvedApiKey = String(providerConfig.apiKey || "").trim() || undefined;
   if (!resolvedApiKey) {
-    resolvedApiKey = resolveApiKeyFallback(providerType);
+    resolvedApiKey = resolveApiKeyFallback(providerType, runtimeEnv);
   }
   if (!resolvedApiKey) {
     await logger.log("warn", "No API Key configured, will use simulation mode");