feat: enhance environment variable handling and configuration resolution

Author: qorzj

docs/configuration.md

@@ -111,7 +111,7 @@ MCP（Model Context Protocol）服务器配置。值是键值对，键为服务
 
 > 当 `command` 为 `npx` 时，Deep Code 会自动在参数前补充 `-y`。
 
-详细 MCP 使用说明请参考 [docs/mcp.md](docs/mcp.md)。
+详细 MCP 使用说明请参考 [mcp.md](mcp.md)。
 
 
 #### `debugLogEnabled` — 调试日志

src/cli.tsx

@@ -23,7 +23,8 @@ if (args.includes("--help") || args.includes("-h")) {
       "  deepcode --help        Show this help",
       "",
       "Configuration:",
-      "  ~/.deepcode/settings.json   API key, model, base URL",
+      "  ~/.deepcode/settings.json    User-level API key, model, base URL",
+      "  ./.deepcode/settings.json    Project-level settings",
       "  ~/.agents/skills/*/SKILL.md  User-level skills",
       "  ./.agents/skills/*/SKILL.md  Project-level skills",
       "  ./.deepcode/skills/*/SKILL.md Legacy project-level skills",

src/common/shell-utils.ts

@@ -128,9 +128,10 @@ export function toNativeCwd(shellCwd: string): string {
   return posixPathToWindowsPath(shellCwd);
 }
 
-export function buildShellEnv(shellPath: string): NodeJS.ProcessEnv {
+export function buildShellEnv(shellPath: string, extraEnv: Record<string, string> = {}): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = {
     ...process.env,
+    ...extraEnv,
     SHELL: shellPath,
     GIT_EDITOR: "true",
   };

src/notify.ts

@@ -27,7 +27,8 @@ export function launchNotifyScript(
   notifyPath: string | undefined,
   durationMs: number,
   workingDirectory?: string,
-  spawnProcess: NotifySpawn = spawn as unknown as NotifySpawn
+  spawnProcess: NotifySpawn = spawn as unknown as NotifySpawn,
+  configuredEnv: Record<string, string> = {}
 ): void {
   const commandPath = notifyPath?.trim();
   if (!commandPath) {
@@ -37,7 +38,7 @@ export function launchNotifyScript(
   const options = {
     cwd: workingDirectory,
     detached: process.platform !== "win32",
-    env: buildNotifyEnv(durationMs),
+    env: buildNotifyEnv(durationMs, { ...process.env, ...configuredEnv }),
     stdio: "ignore" as const,
   };
 

src/session.ts

@@ -941,7 +941,7 @@ ${skillMd}
 
   async activateSession(sessionId: string, controller?: AbortController): Promise<void> {
     const startedAt = Date.now();
-    const { client, model, baseURL, thinkingEnabled, reasoningEffort, debugLogEnabled, notify } =
+    const { client, model, baseURL, thinkingEnabled, reasoningEffort, debugLogEnabled, notify, env } =
       this.createOpenAIClient();
     const now = new Date().toISOString();
 
@@ -955,12 +955,12 @@ ${skillMd}
       this.onAssistantMessage(
         this.buildAssistantMessage(
           sessionId,
-          "OpenAI API key not found. Please configure ~/.deepcode/settings.json.",
+          "OpenAI API key not found. Please configure ~/.deepcode/settings.json or ./.deepcode/settings.json.",
           null
         ),
         false
       );
-      this.maybeNotifyTaskCompletion(sessionId, notify, startedAt);
+      this.maybeNotifyTaskCompletion(sessionId, notify, startedAt, env);
       return;
     }
 
@@ -972,7 +972,7 @@ ${skillMd}
         failReason: "interrupted",
         updateTime: now,
       }));
-      this.maybeNotifyTaskCompletion(sessionId, notify, startedAt);
+      this.maybeNotifyTaskCompletion(sessionId, notify, startedAt, env);
       return;
     }
 
@@ -1114,7 +1114,7 @@ ${skillMd}
       if (this.sessionControllers.get(sessionId) === sessionController) {
         this.sessionControllers.delete(sessionId);
       }
-      this.maybeNotifyTaskCompletion(sessionId, notify, startedAt);
+      this.maybeNotifyTaskCompletion(sessionId, notify, startedAt, env);
     }
   }
 
@@ -1966,7 +1966,12 @@ ${skillMd}
     }
   }
 
-  private maybeNotifyTaskCompletion(sessionId: string, notifyCommand: string | undefined, startedAt: number): void {
+  private maybeNotifyTaskCompletion(
+    sessionId: string,
+    notifyCommand: string | undefined,
+    startedAt: number,
+    configuredEnv: Record<string, string> = {}
+  ): void {
     if (!notifyCommand) {
       return;
     }
@@ -1976,7 +1981,7 @@ ${skillMd}
       return;
     }
 
-    launchNotifyScript(notifyCommand, Date.now() - startedAt, this.projectRoot);
+    launchNotifyScript(notifyCommand, Date.now() - startedAt, this.projectRoot, undefined, configuredEnv);
   }
 
   private addSessionProcess(sessionId: string, processId: string | number, command: string): void {

src/settings.ts

@@ -1,10 +1,12 @@
 import { defaultsToThinkingMode } from "./model-capabilities";
 
-export type DeepcodingEnv = {
+export type DeepcodingEnv = Record<string, string | undefined> & {
   MODEL?: string;
   BASE_URL?: string;
   API_KEY?: string;
-  THINKING?: string;
+  THINKING_ENABLED?: string;
+  REASONING_EFFORT?: string;
+  DEBUG_LOG_ENABLED?: string;
 };
 
 export type ReasoningEffort = "high" | "max";
@@ -27,6 +29,7 @@ export type DeepcodingSettings = {
 };
 
 export type ResolvedDeepcodingSettings = {
+  env: Record<string, string>;
   apiKey?: string;
   baseURL: string;
   model: string;
@@ -44,48 +47,203 @@ export type ModelConfigSelection = {
   reasoningEffort: ReasoningEffort;
 };
 
-function resolveReasoningEffort(value: unknown): ReasoningEffort {
-  return value === "high" || value === "max" ? value : "max";
+export type SettingsProcessEnv = Record<string, string | undefined>;
+
+function resolveReasoningEffort(value: unknown): ReasoningEffort | undefined {
+  return value === "high" || value === "max" ? value : undefined;
 }
 
-function resolveThinkingEnabled(settings: DeepcodingSettings | null | undefined, model: string): boolean {
-  if (typeof settings?.thinkingEnabled === "boolean") {
-    return settings.thinkingEnabled;
+function parseBoolean(value: unknown): boolean | undefined {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value !== "string") {
+    return undefined;
   }
 
-  const legacyThinking = settings?.env?.THINKING;
-  if (typeof legacyThinking === "string" && legacyThinking.trim()) {
-    return legacyThinking.trim().toLowerCase() === "enabled";
+  const normalized = value.trim().toLowerCase();
+  if (["1", "true", "enabled", "yes", "on"].includes(normalized)) {
+    return true;
+  }
+  if (["0", "false", "disabled", "no", "off"].includes(normalized)) {
+    return false;
   }
+  return undefined;
+}
 
-  return defaultsToThinkingMode(model);
+function trimString(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
 }
 
-export function resolveSettings(
-  settings: DeepcodingSettings | null | undefined,
-  defaults: { model: string; baseURL: string }
+function normalizeEnv(env: DeepcodingSettings["env"]): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (!env) {
+    return result;
+  }
+
+  for (const [key, value] of Object.entries(env)) {
+    if (typeof value === "string") {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+export function collectDeepcodeEnv(processEnv: SettingsProcessEnv = process.env): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(processEnv)) {
+    if (!key.startsWith("DEEPCODE_") || typeof value !== "string") {
+      continue;
+    }
+    const strippedKey = key.slice("DEEPCODE_".length);
+    if (strippedKey) {
+      result[strippedKey] = value;
+    }
+  }
+  return result;
+}
+
+function extractMcpEnv(env: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (!key.startsWith("MCP_")) {
+      continue;
+    }
+    const strippedKey = key.slice("MCP_".length);
+    if (strippedKey) {
+      result[strippedKey] = value;
+    }
+  }
+  return result;
+}
+
+function mergeMcpServers(
+  userSettings: DeepcodingSettings | null | undefined,
+  projectSettings: DeepcodingSettings | null | undefined,
+  userEnv: Record<string, string>,
+  projectEnv: Record<string, string>,
+  systemEnv: Record<string, string>
+): Record<string, McpServerConfig> | undefined {
+  const userServers = userSettings?.mcpServers ?? {};
+  const projectServers = projectSettings?.mcpServers ?? {};
+  const serverNames = new Set([...Object.keys(userServers), ...Object.keys(projectServers)]);
+  if (serverNames.size === 0) {
+    return undefined;
+  }
+
+  const userMcpEnv = extractMcpEnv(userEnv);
+  const projectMcpEnv = extractMcpEnv(projectEnv);
+  const systemMcpEnv = extractMcpEnv(systemEnv);
+  const merged: Record<string, McpServerConfig> = {};
+
+  for (const name of serverNames) {
+    const userConfig = userServers[name];
+    const projectConfig = projectServers[name];
+    const command = projectConfig?.command ?? userConfig?.command;
+    if (!command) {
+      continue;
+    }
+
+    const env = {
+      ...userEnv,
+      ...(userConfig?.env ?? {}),
+      ...userMcpEnv,
+      ...projectEnv,
+      ...(projectConfig?.env ?? {}),
+      ...projectMcpEnv,
+      ...systemEnv,
+      ...systemMcpEnv,
+    };
+    const config: McpServerConfig = {
+      command,
+      args: projectConfig?.args ?? userConfig?.args,
+    };
+    if (Object.keys(env).length > 0) {
+      config.env = env;
+    }
+    merged[name] = config;
+  }
+
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+export function resolveSettingsSources(
+  userSettings: DeepcodingSettings | null | undefined,
+  projectSettings: DeepcodingSettings | null | undefined,
+  defaults: { model: string; baseURL: string },
+  processEnv: SettingsProcessEnv = process.env
 ): ResolvedDeepcodingSettings {
-  const env = settings?.env ?? {};
-  const topLevelModel = typeof settings?.model === "string" ? settings.model.trim() : "";
-  const model = topLevelModel || env.MODEL?.trim() || defaults.model;
-  const notify = typeof settings?.notify === "string" ? settings.notify.trim() : "";
-  const webSearchTool = typeof settings?.webSearchTool === "string" ? settings.webSearchTool.trim() : "";
+  const userEnv = normalizeEnv(userSettings?.env);
+  const projectEnv = normalizeEnv(projectSettings?.env);
+  const systemEnv = collectDeepcodeEnv(processEnv);
+  const env = {
+    ...userEnv,
+    ...projectEnv,
+    ...systemEnv,
+  };
+
+  const model =
+    trimString(systemEnv.MODEL) ||
+    trimString(projectSettings?.model) ||
+    trimString(projectEnv.MODEL) ||
+    trimString(userSettings?.model) ||
+    trimString(userEnv.MODEL) ||
+    defaults.model;
 
-  const mcpServers = settings?.mcpServers;
+  const thinkingEnabled =
+    parseBoolean(systemEnv.THINKING_ENABLED) ??
+    parseBoolean(projectSettings?.thinkingEnabled) ??
+    parseBoolean(projectEnv.THINKING_ENABLED) ??
+    parseBoolean(userSettings?.thinkingEnabled) ??
+    parseBoolean(userEnv.THINKING_ENABLED) ??
+    defaultsToThinkingMode(model);
+
+  const reasoningEffort =
+    resolveReasoningEffort(systemEnv.REASONING_EFFORT) ??
+    resolveReasoningEffort(projectSettings?.reasoningEffort) ??
+    resolveReasoningEffort(projectEnv.REASONING_EFFORT) ??
+    resolveReasoningEffort(userSettings?.reasoningEffort) ??
+    resolveReasoningEffort(userEnv.REASONING_EFFORT) ??
+    "max";
+
+  const debugLogEnabled =
+    parseBoolean(systemEnv.DEBUG_LOG_ENABLED) ??
+    parseBoolean(projectSettings?.debugLogEnabled) ??
+    parseBoolean(projectEnv.DEBUG_LOG_ENABLED) ??
+    parseBoolean(userSettings?.debugLogEnabled) ??
+    parseBoolean(userEnv.DEBUG_LOG_ENABLED) ??
+    false;
+
+  const notify =
+    trimString(systemEnv.NOTIFY) || trimString(projectSettings?.notify) || trimString(userSettings?.notify) || "";
+  const webSearchTool =
+    trimString(systemEnv.WEB_SEARCH_TOOL) ||
+    trimString(projectSettings?.webSearchTool) ||
+    trimString(userSettings?.webSearchTool) ||
+    "";
 
   return {
-    apiKey: env.API_KEY?.trim(),
-    baseURL: env.BASE_URL?.trim() || defaults.baseURL,
+    env,
+    apiKey: trimString(env.API_KEY) || undefined,
+    baseURL: trimString(env.BASE_URL) || defaults.baseURL,
     model,
-    thinkingEnabled: resolveThinkingEnabled(settings, model),
-    reasoningEffort: resolveReasoningEffort(settings?.reasoningEffort),
-    debugLogEnabled: settings?.debugLogEnabled === true,
+    thinkingEnabled,
+    reasoningEffort,
+    debugLogEnabled,
     notify: notify || undefined,
     webSearchTool: webSearchTool || undefined,
-    mcpServers,
+    mcpServers: mergeMcpServers(userSettings, projectSettings, userEnv, projectEnv, systemEnv),
   };
 }
 
+export function resolveSettings(
+  settings: DeepcodingSettings | null | undefined,
+  defaults: { model: string; baseURL: string },
+  processEnv: SettingsProcessEnv = process.env
+): ResolvedDeepcodingSettings {
+  return resolveSettingsSources(settings, null, defaults, processEnv);
+}
+
 export function modelConfigKey(config: Pick<ModelConfigSelection, "thinkingEnabled" | "reasoningEffort">): string {
   return config.thinkingEnabled ? `thinking:${config.reasoningEffort}` : "thinking:none";
 }