@downcity/agent 1.1.35 → 1.1.43

package/bin/config/AgentInitializer.js

@@ -0,0 +1,208 @@
+/**
+ * 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 { DEFAULT_PROFILE_MD_TEMPLATE, DEFAULT_SOUL_MD_TEMPLATE, } from "../executor/composer/system/default/InitPrompts.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 { assertProjectExecutionTarget } from "../config/ExecutionBinding.js";
+/**
+ * 规范化默认 Agent 名称。
+ *
+ * 关键点（中文）
+ * - 把目录名中的 `_` / `-` 统一折叠为空格，产出更适合作为展示名的默认值。
+ * - 这里只做轻量字符串清洗，不负责长度限制或唯一性处理。
+ */
+export function normalizeDefaultAgentName(input) {
+    return String(input || "")
+        .trim()
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * 规范化用户选择的渠道列表。
+ *
+ * 关键点（中文）
+ * - 只保留当前 agent 初始化流程支持的渠道。
+ * - 会自动去重并统一为小写，避免调用方在外部重复做清洗。
+ */
+function normalizeChannels(input) {
+    const allowed = new Set(["telegram", "feishu", "qq"]);
+    const seen = new Set();
+    for (const item of Array.isArray(input) ? input : []) {
+        const value = String(item || "").trim().toLowerCase();
+        if (!allowed.has(value))
+            continue;
+        seen.add(value);
+    }
+    return [...seen];
+}
+/**
+ * 判断项目是否已经具备最小初始化文件。
+ *
+ * 关键点（中文）
+ * - 当前只检查 `PROFILE.md` 与 `downcity.json`，用于快速判断是否已初始化过。
+ * - 不把 `.downcity/` 目录作为硬性条件，避免用户手动清理缓存后被误判为未初始化。
+ */
+export async function isAgentProjectInitialized(projectRoot) {
+    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) {
+    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;
+    const channels = normalizeChannels(input.channels);
+    const dotEnvPath = path.join(projectRoot, ".env");
+    const dotEnvExamplePath = path.join(projectRoot, ".env.example");
+    const createdFiles = [];
+    const skippedFiles = [];
+    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),
+        },
+    ];
+    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 = {};
+    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 = {
+        $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", []);
+    await appendMissingEnvEntries(dotEnvExamplePath, "Downcity Create Example", []);
+    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,
+    };
+}
+//# sourceMappingURL=AgentInitializer.js.map

package/bin/config/AgentInitializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentInitializer.js","sourceRoot":"","sources":["../../src/config/AgentInitializer.ts"],"names":[],"mappings":"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"}

package/bin/config/Config.d.ts

@@ -2,10 +2,18 @@ import type { DowncityConfig } from "../types/config/DowncityConfig.js";
 export type { DowncityConfig };
 /**
  * 读取平台共享环境变量（`env_entries.scope=global`）。
+ *
+ * 关键点（中文）
+ * - 当前 agent 包内仍保留空实现占位，等待后续接入平台级持久化存储。
+ * - 保持独立函数是为了让配置读取逻辑不依赖具体存储后端。
  */
 export declare function loadGlobalEnvFromStore(): Record<string, string>;
 /**
  * 读取 agent 私有环境变量（`env_entries.scope=agent`）。
+ *
+ * 关键点（中文）
+ * - 当前 agent 包内仍保留空实现占位，避免把平台存储细节耦合进运行时。
+ * - 当 `agentId` 为空时直接返回空对象，表示没有可用私有环境变量。
  */
 export declare function loadAgentEnvFromStore(agentId: string): Record<string, string>;
 /**
@@ -24,6 +32,14 @@ export declare function loadAgentEnvSnapshot(projectRoot: string): Record<string
  * - 不再把 agent env 注入全局，避免多个 agent 在同一 control plane 进程里互相污染。
  */
 export declare function loadProjectDotenv(projectRoot: string): Record<string, string>;
+/**
+ * 加载当前项目最终生效的 `downcity.json` 配置。
+ *
+ * 关键点（中文）
+ * - 读取顺序为“祖先目录 -> 当前项目目录”，后层配置覆盖前层配置。
+ * - `.env` 只影响占位符解析，不会把值写回配置文件。
+ * - 返回前会断言最小执行目标，保证 agent 至少知道该如何执行。
+ */
 export declare function loadDowncityConfig(projectRoot: string, options?: {
     projectEnv?: Record<string, string>;
     agentEnv?: Record<string, string>;

package/bin/config/Config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Config.d.ts","sourceRoot":"","sources":["../../src/config/Config.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAIvE,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE/D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI7E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOhF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAqB7E;AA4GD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC,GACA,cAAc,CA2ChB"}
+{"version":3,"file":"Config.d.ts","sourceRoot":"","sources":["../../src/config/Config.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAQvE,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI7E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOhF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAqB7E;AAmCD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC,GACA,cAAc,CA8ChB"}

package/bin/config/Config.js

@@ -1,22 +1,39 @@
 /**
- * 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 { 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";
 /**
  * 读取平台共享环境变量（`env_entries.scope=global`）。
+ *
+ * 关键点（中文）
+ * - 当前 agent 包内仍保留空实现占位，等待后续接入平台级持久化存储。
+ * - 保持独立函数是为了让配置读取逻辑不依赖具体存储后端。
  */
 export function loadGlobalEnvFromStore() {
     return {};
 }
 /**
  * 读取 agent 私有环境变量（`env_entries.scope=agent`）。
+ *
+ * 关键点（中文）
+ * - 当前 agent 包内仍保留空实现占位，避免把平台存储细节耦合进运行时。
+ * - 当 `agentId` 为空时直接返回空对象，表示没有可用私有环境变量。
  */
 export function loadAgentEnvFromStore(agentId) {
     const normalizedAgentId = String(agentId || "").trim();
@@ -70,56 +87,13 @@ export function loadProjectDotenv(projectRoot) {
         return {};
     }
 }
-function resolveEnvPlaceholdersDeep(value, resolveEnvVar) {
-    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;
-        const out = {};
-        for (const [k, v] of Object.entries(obj)) {
-            out[k] = resolveEnvPlaceholdersDeep(v, resolveEnvVar);
-        }
-        return out;
-    }
-    return value;
-}
-function isPlainObject(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
 /**
- * 深合并：对象递归合并，数组与标量以 override 为准。
+ * 读取单层 `downcity.json` 并完成环境变量占位符替换。
  *
  * 关键点（中文）
- * - downcity.json 的“继承/覆盖”语义：越靠近 agent 项目的配置优先级越高。
- * - 数组不做 concat，避免出现重复 paths / models。
+ * - 单层读取不做字段语义校验，便于后续统一合并后再做最终断言。
+ * - 环境变量解析策略由调用方注入，保持该函数只负责“遍历 + 替换”。
  */
-function deepMerge(base, override) {
-    if (!isPlainObject(base) || !isPlainObject(override)) {
-        return override === undefined ? base : override;
-    }
-    const out = { ...base };
-    for (const [key, overrideValue] of Object.entries(override)) {
-        const baseValue = base[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, resolveEnvVar) {
     const raw = fs.readJsonSync(filePath);
     return resolveEnvPlaceholdersDeep(raw, resolveEnvVar);
@@ -138,22 +112,14 @@ function assertNoProjectExtensionsLayer(filePath, layer) {
         return;
     throw new Error(`Invalid downcity.json: legacy "extensions" config is no longer supported. Use "plugins" instead (${filePath})`);
 }
-function collectAncestorShipJsonPaths(projectRoot) {
-    const paths = [];
-    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, options) {
     const projectDotenv = options?.projectEnv ?? loadProjectDotenv(projectRoot);
     const agentEnv = options?.agentEnv ?? loadAgentEnvFromStore(projectRoot);
@@ -173,7 +139,7 @@ export function loadDowncityConfig(projectRoot, options) {
         const projectValue = String(runtimeAgentEnv[name] || "").trim();
         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/bin/config/Config.js.map

@@ -1 +1 @@
-{"version":3,"file":"Config.js","sourceRoot":"","sources":["../../src/config/Config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Config.js","sourceRoot":"","sources":["../../src/config/Config.ts"],"names":[],"mappings":"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"}

package/bin/config/ConfigEnvResolver.d.ts

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

package/bin/config/ConfigEnvResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigEnvResolver.d.ts","sourceRoot":"","sources":["../../src/config/ConfigEnvResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAEjF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,mBAAmB,EAC1B,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAClD,mBAAmB,CAyBrB"}

package/bin/config/ConfigEnvResolver.js

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

package/bin/config/ConfigEnvResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigEnvResolver.js","sourceRoot":"","sources":["../../src/config/ConfigEnvResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAA0B,EAC1B,aAAmD;IAEnD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,0BAA0B,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,KAAmB,CAAC;QAChC,MAAM,GAAG,GAA2C,EAAE,CAAC;QACvD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/C,GAAG,CAAC,GAAG,CAAC,GAAG,0BAA0B,CACnC,KAA4B,EAC5B,aAAa,CACd,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/bin/config/Defaults.d.ts

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

package/bin/config/Defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Defaults.d.ts","sourceRoot":"","sources":["../../src/config/Defaults.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAEvE;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAmCnC,CAAC"}
+{"version":3,"file":"Defaults.d.ts","sourceRoot":"","sources":["../../src/config/Defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAEvE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAmCnC,CAAC"}

package/bin/config/Defaults.js

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

package/bin/config/Defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"Defaults.js","sourceRoot":"","sources":["../../src/config/Defaults.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAmB;IACnD,OAAO,EAAE,yCAAyC;IAClD,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE;QACL,IAAI,EAAE,IAAI;QACV,IAAI,EAAE,SAAS;KAChB;IACD,SAAS,EAAE;QACT,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,SAAS;KACnB;IACD,OAAO,EAAE;QACP,QAAQ,EAAE;YACR,gBAAgB,EAAE,EAAE;YACpB,oBAAoB,EAAE,MAAM;YAC5B,gBAAgB,EAAE,IAAI;YACtB,YAAY,EAAE,GAAG;SAClB;KACF;IACD,OAAO,EAAE;QACP,IAAI,EAAE;YACJ,KAAK,EAAE;gBACL,cAAc,EAAE,CAAC;gBACjB,eAAe,EAAE,GAAG;gBACpB,cAAc,EAAE,IAAI;aACrB;YACD,QAAQ,EAAE;gBACR,QAAQ,EAAE;oBACR,OAAO,EAAE,KAAK;oBACd,gBAAgB,EAAE,SAAS;iBAC5B;aACF;SACF;KACF;CACF,CAAC"}
+{"version":3,"file":"Defaults.js","sourceRoot":"","sources":["../../src/config/Defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAmB;IACnD,OAAO,EAAE,yCAAyC;IAClD,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE;QACL,IAAI,EAAE,IAAI;QACV,IAAI,EAAE,SAAS;KAChB;IACD,SAAS,EAAE;QACT,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,SAAS;KACnB;IACD,OAAO,EAAE;QACP,QAAQ,EAAE;YACR,gBAAgB,EAAE,EAAE;YACpB,oBAAoB,EAAE,MAAM;YAC5B,gBAAgB,EAAE,IAAI;YACtB,YAAY,EAAE,GAAG;SAClB;KACF;IACD,OAAO,EAAE;QACP,IAAI,EAAE;YACJ,KAAK,EAAE;gBACL,cAAc,EAAE,CAAC;gBACjB,eAAe,EAAE,GAAG;gBACpB,cAAc,EAAE,IAAI;aACrB;YACD,QAAQ,EAAE;gBACR,QAAQ,EAAE;oBACR,OAAO,EAAE,KAAK;oBACd,gBAAgB,EAAE,SAAS;iBAC5B;aACF;SACF;KACF;CACF,CAAC"}

package/bin/config/DowncitySchema.d.ts

@@ -1,3 +1,21 @@
+/**
+ * `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 declare const DOWNCITY_JSON_SCHEMA: JsonObject;
 //# sourceMappingURL=DowncitySchema.d.ts.map

package/bin/config/DowncitySchema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DowncitySchema.d.ts","sourceRoot":"","sources":["../../src/config/DowncitySchema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,eAAO,MAAM,oBAAoB,EAAE,UAgXlC,CAAC"}
+{"version":3,"file":"DowncitySchema.d.ts","sourceRoot":"","sources":["../../src/config/DowncitySchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,UAgXlC,CAAC"}

package/bin/config/DowncitySchema.js

@@ -1,3 +1,10 @@
+/**
+ * `downcity.json` 的本地 Schema 常量。
+ *
+ * 关键点（中文）
+ * - 初始化流程会把该常量写入 `.downcity/schema/downcity.schema.json`。
+ * - 该结构主要面向 IDE 校验与用户编辑体验，不替代运行时断言。
+ */
 export const DOWNCITY_JSON_SCHEMA = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     $id: "https://downcity.ai/schemas/downcity.schema.json",