@downcity/agent 1.1.32 → 1.1.43

package/src/config/AgentInitializer.ts

@@ -0,0 +1,262 @@
+/**
+ * Agent 项目初始化模块。
+ *
+ * 职责说明（中文）
+ * - CLI `city agent create` 与 Console 共用同一套初始化逻辑，避免模板与目录结构分叉。
+ * - 负责创建项目骨架、静态 prompt、默认 `downcity.json`、基础目录与 schema 文件。
+ * - 负责把用户在创建阶段提供的最小执行配置与渠道配置写入项目。
+ *
+ * 边界说明（中文）
+ * - 这里只处理“初始化一个新项目”所需的静态文件与目录，不处理 daemon 启停。
+ * - 这里只校验项目创建阶段依赖的最小平台条件，不承担后续运行时配置合并职责。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import {
+  getCacheDirPath,
+  getDowncityAgentsRootDirPath,
+  getLogsDirPath,
+  getProfileMdPath,
+  getDowncityConfigDirPath,
+  getDowncityDataDirPath,
+  getDowncityDebugDirPath,
+  getDowncityDirPath,
+  getDowncityJsonPath,
+  getDowncityProfileDirPath,
+  getDowncityProfileOtherPath,
+  getDowncityProfilePrimaryPath,
+  getDowncityPublicDirPath,
+  getDowncitySchemaPath,
+  getDowncityTasksDirPath,
+  getSoulMdPath,
+} from "@/config/Paths.js";
+import { DEFAULT_DOWNCITY_JSON } from "@/config/Defaults.js";
+import { DOWNCITY_JSON_SCHEMA } from "@/config/DowncitySchema.js";
+import type { DowncityConfig } from "@/config/Config.js";
+import type { DowncityChatPluginChannelsConfig } from "@/types/config/DowncityConfig.js";
+import {
+  DEFAULT_PROFILE_MD_TEMPLATE,
+  DEFAULT_SOUL_MD_TEMPLATE,
+} from "@executor/composer/system/default/InitPrompts.js";
+import type { EnvFileEntry } from "@/types/common/EnvFile.js";
+import { appendMissingEnvEntries } from "@/config/EnvFile.js";
+import { ensureGitignoreEntry } from "@/config/Gitignore.js";
+import { renderTemplateVariables } from "@/utils/Template.js";
+import { ensureDir, saveJson } from "@/utils/storage/index.js";
+import type {
+  AgentProjectChannel,
+  AgentProjectInitializationInput,
+  AgentProjectInitializationResult,
+} from "@/types/config/AgentProject.js";
+import { assertProjectExecutionTarget } from "@/config/ExecutionBinding.js";
+import type { ExecutionBindingConfig } from "@/types/config/ExecutionBinding.js";
+
+/**
+ * 规范化默认 Agent 名称。
+ *
+ * 关键点（中文）
+ * - 把目录名中的 `_` / `-` 统一折叠为空格，产出更适合作为展示名的默认值。
+ * - 这里只做轻量字符串清洗，不负责长度限制或唯一性处理。
+ */
+export function normalizeDefaultAgentName(input: string): string {
+  return String(input || "")
+    .trim()
+    .replace(/[_-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * 规范化用户选择的渠道列表。
+ *
+ * 关键点（中文）
+ * - 只保留当前 agent 初始化流程支持的渠道。
+ * - 会自动去重并统一为小写，避免调用方在外部重复做清洗。
+ */
+function normalizeChannels(input: AgentProjectChannel[] | undefined): AgentProjectChannel[] {
+  const allowed = new Set<AgentProjectChannel>(["telegram", "feishu", "qq"]);
+  const seen = new Set<AgentProjectChannel>();
+  for (const item of Array.isArray(input) ? input : []) {
+    const value = String(item || "").trim().toLowerCase() as AgentProjectChannel;
+    if (!allowed.has(value)) continue;
+    seen.add(value);
+  }
+  return [...seen];
+}
+
+/**
+ * 判断项目是否已经具备最小初始化文件。
+ *
+ * 关键点（中文）
+ * - 当前只检查 `PROFILE.md` 与 `downcity.json`，用于快速判断是否已初始化过。
+ * - 不把 `.downcity/` 目录作为硬性条件，避免用户手动清理缓存后被误判为未初始化。
+ */
+export async function isAgentProjectInitialized(projectRoot: string): Promise<boolean> {
+  const normalizedRoot = path.resolve(String(projectRoot || "").trim() || ".");
+  const profileReady = await fs.pathExists(getProfileMdPath(normalizedRoot));
+  const shipReady = await fs.pathExists(getDowncityJsonPath(normalizedRoot));
+  return profileReady && shipReady;
+}
+
+/**
+ * 初始化 agent 项目骨架。
+ *
+ * 关键点（中文）
+ * - 会创建 prompt 文件、配置文件、`.downcity` 目录结构以及 schema 快照。
+ * - 对已存在文件采取“能跳过就跳过、明确冲突则报错”的策略，降低误覆盖风险。
+ * - 返回结果只描述本次初始化写入摘要，方便 CLI 与控制台直接展示。
+ */
+export async function initializeAgentProject(
+  input: AgentProjectInitializationInput,
+): Promise<AgentProjectInitializationResult> {
+  const projectRoot = path.resolve(String(input.projectRoot || "").trim() || ".");
+  const projectBaseName = path.basename(projectRoot);
+  const fallbackAgentName = normalizeDefaultAgentName(projectBaseName) || projectBaseName;
+  const agentName = String(input.agentName || "").trim() || fallbackAgentName;
+  const execution = input.execution as ExecutionBindingConfig;
+
+  const channels = normalizeChannels(input.channels);
+  const dotEnvPath = path.join(projectRoot, ".env");
+  const dotEnvExamplePath = path.join(projectRoot, ".env.example");
+  const createdFiles: string[] = [];
+  const skippedFiles: string[] = [];
+
+  assertProjectExecutionTarget({
+    name: agentName,
+    version: "1.0.0",
+    execution,
+  });
+
+  await ensureDir(projectRoot);
+
+  const profileMdPath = getProfileMdPath(projectRoot);
+  const soulMdPath = getSoulMdPath(projectRoot);
+  const shipJsonPath = getDowncityJsonPath(projectRoot);
+  const existingShipJson = await fs.pathExists(shipJsonPath);
+  if (existingShipJson && input.forceOverwriteShipJson !== true) {
+    throw new Error(`downcity.json already exists: ${shipJsonPath}`);
+  }
+
+  const initTemplateVariables = {
+    agent_name: agentName,
+  };
+  const staticPromptFiles = [
+    {
+      filename: "PROFILE.md",
+      filePath: profileMdPath,
+      content: renderTemplateVariables(DEFAULT_PROFILE_MD_TEMPLATE, initTemplateVariables),
+    },
+    {
+      filename: "SOUL.md",
+      filePath: soulMdPath,
+      content: renderTemplateVariables(DEFAULT_SOUL_MD_TEMPLATE, initTemplateVariables),
+    },
+  ] as const;
+
+  for (const file of staticPromptFiles) {
+    if (await fs.pathExists(file.filePath)) {
+      skippedFiles.push(file.filename);
+      continue;
+    }
+    await fs.writeFile(file.filePath, file.content, "utf-8");
+    createdFiles.push(file.filename);
+  }
+
+  const channelsConfig: DowncityChatPluginChannelsConfig = {};
+  if (channels.includes("telegram")) {
+    channelsConfig.telegram = { enabled: true };
+  }
+  if (channels.includes("feishu")) {
+    channelsConfig.feishu = { enabled: true };
+  }
+  if (channels.includes("qq")) {
+    channelsConfig.qq = { enabled: true };
+  }
+
+  const shipConfig: DowncityConfig = {
+    $schema: DEFAULT_DOWNCITY_JSON.$schema,
+    name: agentName,
+    version: "1.0.0",
+    execution,
+    plugins: {
+      skill: {
+        enabled: true,
+        paths: [".agents/skills"],
+        allowExternalPaths: false,
+      },
+      ...(input.plugins || {}),
+    },
+    ...(Object.keys(channelsConfig).length > 0
+      ? {
+          plugins: {
+            chat: {
+              channels: channelsConfig,
+            },
+          },
+        }
+      : {}),
+  };
+  await saveJson(shipJsonPath, shipConfig);
+  createdFiles.push("downcity.json");
+
+  await appendMissingEnvEntries(
+    dotEnvPath,
+    "Downcity Create",
+    [] satisfies EnvFileEntry[],
+  );
+  await appendMissingEnvEntries(
+    dotEnvExamplePath,
+    "Downcity Create Example",
+    [] satisfies EnvFileEntry[],
+  );
+
+  const gitignoreStatus = await ensureGitignoreEntry(projectRoot, ".downcity");
+  if (gitignoreStatus === "created" || gitignoreStatus === "updated") {
+    createdFiles.push(".gitignore");
+  } else {
+    skippedFiles.push(".gitignore");
+  }
+
+  const dirs = [
+    getDowncityDirPath(projectRoot),
+    getDowncityTasksDirPath(projectRoot),
+    getLogsDirPath(projectRoot),
+    getCacheDirPath(projectRoot),
+    getDowncityProfileDirPath(projectRoot),
+    getDowncityDataDirPath(projectRoot),
+    getDowncityAgentsRootDirPath(projectRoot),
+    getDowncityPublicDirPath(projectRoot),
+    getDowncityConfigDirPath(projectRoot),
+    path.join(projectRoot, ".agents", "skills"),
+    path.join(getDowncityDirPath(projectRoot), "schema"),
+    getDowncityDebugDirPath(projectRoot),
+  ];
+  for (const dir of dirs) {
+    await ensureDir(dir);
+  }
+
+  const shipSchemaPath = getDowncitySchemaPath(projectRoot);
+  await ensureDir(path.dirname(shipSchemaPath));
+  await saveJson(shipSchemaPath, DOWNCITY_JSON_SCHEMA);
+  createdFiles.push(".downcity/schema/downcity.schema.json");
+
+  try {
+    await ensureDir(getDowncityProfileDirPath(projectRoot));
+    await fs.ensureFile(getDowncityProfilePrimaryPath(projectRoot));
+    await fs.ensureFile(getDowncityProfileOtherPath(projectRoot));
+  } catch {
+    // ignore optional profile memory bootstrap errors
+  }
+
+  return {
+    projectRoot,
+    agentName,
+    ...(execution?.type === "api" && String(execution.modelId || "").trim()
+      ? { modelId: String(execution.modelId || "").trim() }
+      : {}),
+    channels,
+    createdFiles,
+    skippedFiles,
+  };
+}

package/src/config/Config.ts

@@ -1,21 +1,34 @@
 /**
- * Config：agent 项目环境与配置读取模块。
+ * Agent 项目配置读取与装配模块。
  *
- * 关键点（中文）
- * - 这里统一处理 `downcity.json`、项目 `.env`、全局 env 快照三类配置来源。
- * - agent 运行时通过这里读取项目配置，避免各处重复拼装规则。
+ * 职责说明（中文）
+ * - 统一负责读取 `downcity.json`、项目 `.env` 与外部注入的环境变量快照。
+ * - 负责把祖先目录中的多个 `downcity.json` 逐层合并成当前项目的最终配置。
+ * - 负责在配置读取阶段完成 `${ENV_NAME}` 占位符替换与最小结构校验。
+ *
+ * 边界说明（中文）
+ * - 这里只做“配置文件 -> 运行时配置对象”的装配，不负责项目初始化写文件。
+ * - 这里只校验配置是否满足 agent 运行最低要求，不负责平台模型是否真实可用。
  */
 import dotenv from "dotenv";
 import fs from "fs-extra";
 import path from "path";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
-import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import type { ResolvedConfigValue } from "@/types/common/ResolvedConfigValue.js";
 import { assertProjectExecutionTarget } from "@/config/ExecutionBinding.js";
+import { resolveEnvPlaceholdersDeep } from "@/config/ConfigEnvResolver.js";
+import { deepMerge } from "@/utils/object/DeepMerge.js";
+import { isPlainObject } from "@/utils/object/ObjectGuards.js";
+import { collectAncestorNamedFilePaths } from "@/utils/path/AncestorFiles.js";
 
 export type { DowncityConfig };
 
 /**
  * 读取平台共享环境变量（`env_entries.scope=global`）。
+ *
+ * 关键点（中文）
+ * - 当前 agent 包内仍保留空实现占位，等待后续接入平台级持久化存储。
+ * - 保持独立函数是为了让配置读取逻辑不依赖具体存储后端。
  */
 export function loadGlobalEnvFromStore(): Record<string, string> {
   return {};
@@ -23,6 +36,10 @@ export function loadGlobalEnvFromStore(): Record<string, string> {
 
 /**
  * 读取 agent 私有环境变量（`env_entries.scope=agent`）。
+ *
+ * 关键点（中文）
+ * - 当前 agent 包内仍保留空实现占位，避免把平台存储细节耦合进运行时。
+ * - 当 `agentId` 为空时直接返回空对象，表示没有可用私有环境变量。
  */
 export function loadAgentEnvFromStore(agentId: string): Record<string, string> {
   const normalizedAgentId = String(agentId || "").trim();
@@ -76,71 +93,13 @@ export function loadProjectDotenv(projectRoot: string): Record<string, string> {
   }
 }
 
-type ResolvedConfigValue =
-  | JsonValue
-  | undefined
-  | { [key: string]: ResolvedConfigValue }
-  | ResolvedConfigValue[];
-
-function resolveEnvPlaceholdersDeep(
-  value: ResolvedConfigValue,
-  resolveEnvVar: (name: string) => string | undefined,
-): ResolvedConfigValue {
-  if (typeof value === "string") {
-    const match = value.match(/^\$\{([A-Z0-9_]+)\}$/);
-    if (!match) return value;
-    const envVar = match[1];
-    return resolveEnvVar(envVar);
-  }
-
-  if (Array.isArray(value)) {
-    return value.map((item) => resolveEnvPlaceholdersDeep(item, resolveEnvVar));
-  }
-
-  if (value && typeof value === "object") {
-    const obj = value as JsonObject;
-    const out: { [key: string]: ResolvedConfigValue } = {};
-    for (const [k, v] of Object.entries(obj)) {
-      out[k] = resolveEnvPlaceholdersDeep(v as ResolvedConfigValue, resolveEnvVar);
-    }
-    return out;
-  }
-
-  return value;
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
 /**
- * 深合并：对象递归合并，数组与标量以 override 为准。
+ * 读取单层 `downcity.json` 并完成环境变量占位符替换。
  *
  * 关键点（中文）
- * - downcity.json 的“继承/覆盖”语义：越靠近 agent 项目的配置优先级越高。
- * - 数组不做 concat，避免出现重复 paths / models。
+ * - 单层读取不做字段语义校验，便于后续统一合并后再做最终断言。
+ * - 环境变量解析策略由调用方注入，保持该函数只负责“遍历 + 替换”。
  */
-function deepMerge(base: unknown, override: unknown): unknown {
-  if (!isPlainObject(base) || !isPlainObject(override)) {
-    return override === undefined ? base : override;
-  }
-
-  const out: Record<string, unknown> = { ...base };
-  for (const [key, overrideValue] of Object.entries(override)) {
-    const baseValue = (base as Record<string, unknown>)[key];
-    if (Array.isArray(overrideValue)) {
-      out[key] = overrideValue;
-      continue;
-    }
-    if (isPlainObject(overrideValue) && isPlainObject(baseValue)) {
-      out[key] = deepMerge(baseValue, overrideValue);
-      continue;
-    }
-    out[key] = overrideValue === undefined ? baseValue : overrideValue;
-  }
-  return out;
-}
-
 function readShipJsonLayer(
   filePath: string,
   resolveEnvVar: (name: string) => string | undefined,
@@ -167,21 +126,14 @@ function assertNoProjectExtensionsLayer(
   );
 }
 
-function collectAncestorShipJsonPaths(projectRoot: string): string[] {
-  const paths: string[] = [];
-  const resolvedRoot = path.resolve(projectRoot);
-  let dir = resolvedRoot;
-  while (true) {
-    const candidate = path.join(dir, "downcity.json");
-    if (fs.existsSync(candidate)) paths.push(candidate);
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  // root -> leaf
-  return paths.reverse();
-}
-
+/**
+ * 加载当前项目最终生效的 `downcity.json` 配置。
+ *
+ * 关键点（中文）
+ * - 读取顺序为“祖先目录 -> 当前项目目录”，后层配置覆盖前层配置。
+ * - `.env` 只影响占位符解析，不会把值写回配置文件。
+ * - 返回前会断言最小执行目标，保证 agent 至少知道该如何执行。
+ */
 export function loadDowncityConfig(
   projectRoot: string,
   options?: {
@@ -209,7 +161,10 @@ export function loadDowncityConfig(
     return projectValue || undefined;
   };
 
-  const ancestorShipJsonPaths = collectAncestorShipJsonPaths(projectRoot);
+  const ancestorShipJsonPaths = collectAncestorNamedFilePaths(
+    projectRoot,
+    "downcity.json",
+  );
   if (ancestorShipJsonPaths.length === 0) {
     throw new Error("downcity.json not found in project directory");
   }

package/src/config/ConfigEnvResolver.ts

@@ -0,0 +1,52 @@
+/**
+ * Agent 配置域环境变量占位符解析模块。
+ *
+ * 职责说明（中文）
+ * - 负责把配置树中的 `${ENV_NAME}` 形式占位符替换为运行时可见的环境变量值。
+ * - 服务 `downcity.json` 等配置载体的解析流程，让配置读取相关逻辑集中留在 `config/` 语义域。
+ *
+ * 边界说明（中文）
+ * - 该模块只处理结构遍历与替换，不读取文件，也不决定环境变量来源优先级。
+ * - 这里只负责“如何替换”，不负责“缺失变量时是否报错”的业务策略。
+ */
+
+import type { JsonObject } from "@/types/common/Json.js";
+import type { ResolvedConfigValue } from "@/types/common/ResolvedConfigValue.js";
+
+/**
+ * 递归解析配置值中的环境变量占位符。
+ *
+ * 关键点（中文）
+ * - 仅替换“整个字符串就是 `${VAR}`”的场景，不处理字符串内插值拼接。
+ * - 数组与对象会递归遍历，保持原有结构不变。
+ * - 未命中的环境变量会返回 `undefined`，由调用方决定后续行为。
+ */
+export function resolveEnvPlaceholdersDeep(
+  value: ResolvedConfigValue,
+  resolveEnvVar: (name: string) => string | undefined,
+): ResolvedConfigValue {
+  if (typeof value === "string") {
+    const match = value.match(/^\$\{([A-Z0-9_]+)\}$/);
+    if (!match) return value;
+    const envVar = match[1];
+    return resolveEnvVar(envVar);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveEnvPlaceholdersDeep(item, resolveEnvVar));
+  }
+
+  if (value && typeof value === "object") {
+    const obj = value as JsonObject;
+    const out: { [key: string]: ResolvedConfigValue } = {};
+    for (const [key, child] of Object.entries(obj)) {
+      out[key] = resolveEnvPlaceholdersDeep(
+        child as ResolvedConfigValue,
+        resolveEnvVar,
+      );
+    }
+    return out;
+  }
+
+  return value;
+}

package/src/config/Defaults.ts

@@ -1,15 +1,23 @@
 /**
- * Defaults：agent 项目默认配置模板。
+ * Agent 项目默认配置模板模块。
  *
- * 关键点（中文）
- * - 这里集中声明初始化项目时写入的默认 `downcity.json`。
- * - 默认值只服务项目初始化，不参与运行时配置合并逻辑。
+ * 职责说明（中文）
+ * - 集中声明初始化新项目时写入的默认 `downcity.json` 结构。
+ * - 为创建流程提供一份稳定、最小可运行的默认配置基线。
+ *
+ * 边界说明（中文）
+ * - 这里的默认值只服务“新项目生成”，不参与运行时多层配置合并。
+ * - 业务运行过程中若要读取最终配置，应始终走 `Config.ts` 的装配逻辑。
  */
 
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 
 /**
  * 默认 `downcity.json` 配置。
+ *
+ * 关键点（中文）
+ * - 这是一份“初始化模板”，不是运行时的最终真相来源。
+ * - 调用方若只想取某个字段的默认值，也应意识到它可能被用户项目配置覆盖。
  */
 export const DEFAULT_DOWNCITY_JSON: DowncityConfig = {
   $schema: "./.downcity/schema/downcity.schema.json",
@@ -31,7 +39,7 @@ export const DEFAULT_DOWNCITY_JSON: DowncityConfig = {
       compactRatio: 0.5,
     },
   },
-  services: {
+  plugins: {
     chat: {
       queue: {
         maxConcurrency: 2,

package/src/config/DowncitySchema.ts

@@ -1,5 +1,23 @@
+/**
+ * `downcity.json` Schema 定义模块。
+ *
+ * 职责说明（中文）
+ * - 提供项目初始化时写入本地的 JSON Schema 常量。
+ * - 统一维护用户可编辑配置的结构约束、字段说明与编辑器联想元数据。
+ *
+ * 边界说明（中文）
+ * - 这里是静态 schema 常量，不负责运行时配置装配或业务校验逻辑。
+ * - 当 schema 与运行时实现存在差异时，应同时更新配置解析与用户文档。
+ */
 import type { JsonObject } from "@/types/common/Json.js";
 
+/**
+ * `downcity.json` 的本地 Schema 常量。
+ *
+ * 关键点（中文）
+ * - 初始化流程会把该常量写入 `.downcity/schema/downcity.schema.json`。
+ * - 该结构主要面向 IDE 校验与用户编辑体验，不替代运行时断言。
+ */
 export const DOWNCITY_JSON_SCHEMA: JsonObject = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
   $id: "https://downcity.ai/schemas/downcity.schema.json",
@@ -120,11 +138,11 @@ export const DOWNCITY_JSON_SCHEMA: JsonObject = {
         },
       },
     },
-    services: {
+    plugins: {
       type: "object",
       additionalProperties: true,
       properties: {
-        skills: {
+        skill: {
           type: "object",
           additionalProperties: true,
           properties: {
@@ -187,12 +205,6 @@ export const DOWNCITY_JSON_SCHEMA: JsonObject = {
             },
           },
         },
-      },
-    },
-    plugins: {
-      type: "object",
-      additionalProperties: true,
-      properties: {
         asr: {
           type: "object",
           additionalProperties: true,

package/src/config/EnvFile.ts

@@ -0,0 +1,99 @@
+/**
+ * Agent 配置域 Env 文件工具模块。
+ *
+ * 职责说明（中文）
+ * - 负责 `.env` / `.env.example` 这类项目配置文件的轻量解析与补齐。
+ * - 服务于 agent 项目初始化与配置维护流程，避免把文本拼接逻辑散落到业务模块。
+ *
+ * 边界说明（中文）
+ * - 这里只处理配置文件文本结构，不负责把值注入运行时 `process.env`。
+ * - 当前能力以 agent 项目配置场景为中心，不追求成为通用 shell env 解析库。
+ */
+
+import fs from "fs-extra";
+import type { EnvFileEntry } from "@/types/common/EnvFile.js";
+import { escapeRegExp } from "@/utils/string/EscapeRegExp.js";
+
+/**
+ * 解析 Env 文本中已经声明的变量键名集合。
+ *
+ * 关键点（中文）
+ * - 会忽略空行与注释行。
+ * - 仅识别 `KEY=value` 的基础形式，足够覆盖当前 agent 配置初始化流程。
+ */
+export function parseEnvKeys(content: string): Set<string> {
+  const out = new Set<string>();
+  for (const rawLine of String(content || "").split(/\r?\n/)) {
+    const line = String(rawLine || "").trim();
+    if (!line || line.startsWith("#")) continue;
+    const matched = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+    if (!matched) continue;
+    out.add(matched[1]);
+  }
+  return out;
+}
+
+/**
+ * 仅在目标文件缺失指定键时追加 Env 条目。
+ *
+ * 关键点（中文）
+ * - 已存在的键默认保持不变，只有显式列入 `overwriteKeys` 才会覆写。
+ * - 当目标文件原本为空时，会自动补一行总标题注释，便于用户识别来源。
+ * - `entries` 中的空键名会被自动忽略，避免写入无效行。
+ * - 该函数默认服务项目初始化阶段，因此输出格式偏向“可读、可手改”。
+ */
+export async function appendMissingEnvEntries(
+  filePath: string,
+  sectionTitle: string,
+  entries: EnvFileEntry[],
+  overwriteKeys?: Set<string>,
+): Promise<void> {
+  const normalizedFilePath = String(filePath || "").trim();
+  if (!normalizedFilePath) return;
+
+  const normalizedEntries = Array.isArray(entries)
+    ? entries.filter((item) => Boolean(String(item?.key || "").trim()))
+    : [];
+  const writableOverwriteKeys = overwriteKeys || new Set<string>();
+
+  let existing = "";
+  if (await fs.pathExists(normalizedFilePath)) {
+    existing = await fs.readFile(normalizedFilePath, "utf-8");
+  }
+
+  const existingKeys = parseEnvKeys(existing);
+  let nextContent = existing;
+  const appendedEntries: EnvFileEntry[] = [];
+
+  for (const entry of normalizedEntries) {
+    if (!existingKeys.has(entry.key)) {
+      appendedEntries.push(entry);
+      continue;
+    }
+    if (!writableOverwriteKeys.has(entry.key)) continue;
+    const linePattern = new RegExp(`^${escapeRegExp(entry.key)}\\s*=.*$`, "gm");
+    if (linePattern.test(nextContent)) {
+      nextContent = nextContent.replace(linePattern, `${entry.key}=${entry.value}`);
+    }
+  }
+
+  if (appendedEntries.length > 0) {
+    const lines: string[] = [];
+    if (!nextContent.trim()) {
+      lines.push("# Downcity 环境变量");
+    }
+    lines.push("", `# ${String(sectionTitle || "").trim()}`);
+    for (const entry of appendedEntries) {
+      lines.push(`${entry.key}=${entry.value}`);
+    }
+    let chunk = lines.join("\n");
+    if (nextContent && !nextContent.endsWith("\n")) {
+      chunk = `\n${chunk}`;
+    }
+    nextContent = `${nextContent}${chunk}\n`;
+  }
+
+  if (appendedEntries.length > 0 || !(await fs.pathExists(normalizedFilePath))) {
+    await fs.writeFile(normalizedFilePath, nextContent, "utf-8");
+  }
+}