@h-ai/core 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/node.js

@@ -1,13 +1,13 @@
-import { installRequestLocales, installRequestContext, createCore, i18n, err, HaiConfigError, ok, RequestAccessConfigSchema, RequestAccessPolicySchema, AccessConditionSchema, requestContext, sanitize, emitLogRecord, sanitizeLogFields, typeUtils, CoreConfigSchema } from './chunk-BEGTB6GL.js';
-export { AccessConditionSchema, CoreConfigSchema, EnvSchema, HaiCommonError, HaiConfigError, LogFormatSchema, LogLevelSchema, LoggingConfigSchema, RequestAccessConfigSchema, RequestAccessPolicySchema, TrustedProxiesSchema, err, ok } from './chunk-BEGTB6GL.js';
+import { installRequestLocales, installRequestContext, createCore, i18n, err, HaiConfigError, ok, RequestAccessConfigSchema, RequestAccessPolicySchema, AccessConditionSchema, requestContext, sanitize, emitLogRecord, sanitizeLogFields, CoreConfigSchema } from './chunk-MYNB4HIZ.js';
+export { AccessConditionSchema, CoreConfigSchema, EnvSchema, HaiCommonError, HaiConfigError, LogFormatSchema, LogLevelSchema, LoggingConfigSchema, RequestAccessConfigSchema, RequestAccessPolicySchema, TrustedProxiesSchema, err, ok } from './chunk-MYNB4HIZ.js';
 import { AsyncLocalStorage } from 'async_hooks';
 import { Buffer } from 'buffer';
 import { timingSafeEqual } from 'crypto';
 import { existsSync, readFileSync, openSync, constants, fstatSync, readSync, closeSync, readdirSync, watch } from 'fs';
-import path, { join } from 'path';
+import path, { join, resolve, basename, dirname } from 'path';
 import { BlockList, isIP } from 'net';
 import { networkInterfaces } from 'os';
-import process3 from 'process';
+import process4 from 'process';
 import { parse } from 'yaml';
 import { parseEnv } from 'util';
 import { execSync } from 'child_process';
@@ -41,8 +41,8 @@ function addAddress(list, entry) {
   list.addSubnet(address, bits, type);
 }
 function createClientIpResolver(trustedProxies = "auto") {
-  const entries = trustedProxies === "auto" ? process3.env.HAI_DEPLOY_PRIVATE_PROXY === "1" ? Object.values(networkInterfaces()).flatMap((interfaces) => interfaces?.filter((value) => !value.internal && value.cidr && !value.cidr.includes("%")).map((value) => value.cidr) ?? []) : [] : trustedProxies;
-  if (trustedProxies === "auto" && process3.env.HAI_DEPLOY_PRIVATE_PROXY === "1" && !entries.length)
+  const entries = trustedProxies === "auto" ? process4.env.HAI_DEPLOY_PRIVATE_PROXY === "1" ? Object.values(networkInterfaces()).flatMap((interfaces) => interfaces?.filter((value) => !value.internal && value.cidr && !value.cidr.includes("%")).map((value) => value.cidr) ?? []) : [] : trustedProxies;
+  if (trustedProxies === "auto" && process4.env.HAI_DEPLOY_PRIVATE_PROXY === "1" && !entries.length)
     throw new Error("Private proxy mode requires an isolated container network");
   const proxies = new BlockList();
   for (const entry of entries)
@@ -120,7 +120,7 @@ function createConditionCheck(input) {
   const condition = AccessConditionSchema.parse(input);
   return compileCondition(condition, condition.windows.length ? timeReader(condition.timezone) : void 0);
 }
-function loadPolicy(input = false, baseDirectory = process3.cwd()) {
+function loadPolicy(input = false, baseDirectory = process4.cwd()) {
   const config2 = RequestAccessConfigSchema.parse(input);
   if (config2 === false || !("file" in config2))
     return config2;
@@ -207,11 +207,11 @@ function createRequestCheck(input = false) {
         const nodes = [prefixes];
         let node = prefixes;
         const path2 = normalizeRequestPath(prefix ? pattern.slice(0, -3) || "/" : pattern);
-        for (const segment of path2.split("/").filter(Boolean)) {
-          let child = node.children.get(segment);
+        for (const segment2 of path2.split("/").filter(Boolean)) {
+          let child = node.children.get(segment2);
           if (!child) {
             child = { children: /* @__PURE__ */ new Map(), rules: [] };
-            node.children.set(segment, child);
+            node.children.set(segment2, child);
           }
           node = child;
           nodes.push(node);
@@ -233,11 +233,11 @@ function createRequestCheck(input = false) {
       }
       if (pattern.endsWith("/**")) {
         let node = prefixes;
-        for (const segment of pattern.slice(0, -3).split("/").filter(Boolean)) {
-          let child = node.children.get(segment);
+        for (const segment2 of pattern.slice(0, -3).split("/").filter(Boolean)) {
+          let child = node.children.get(segment2);
           if (!child) {
             child = { children: /* @__PURE__ */ new Map(), rules: [] };
-            node.children.set(segment, child);
+            node.children.set(segment2, child);
           }
           node = child;
         }
@@ -273,8 +273,8 @@ function createRequestCheck(input = false) {
       }
     }
     if (node.children.size) {
-      for (const segment of path2.split("/").filter(Boolean)) {
-        node = node.children.get(segment);
+      for (const segment2 of path2.split("/").filter(Boolean)) {
+        node = node.children.get(segment2);
         if (!node)
           break;
         for (const rule of node.rules) {
@@ -294,8 +294,8 @@ function createRequestCheck(input = false) {
       return void 0;
     let node = prefixes;
     let mode = node.encryption?.get(method) ?? node.encryption?.get("*");
-    for (const segment of path2.split("/").filter(Boolean)) {
-      node = node.children.get(segment);
+    for (const segment2 of path2.split("/").filter(Boolean)) {
+      node = node.children.get(segment2);
       if (!node)
         return mode;
       mode ??= node.encryption?.get(method) ?? node.encryption?.get("*");
@@ -305,72 +305,229 @@ function createRequestCheck(input = false) {
   return Object.assign(check, { encryption: hasEncryption ? encryption : () => void 0, requiresEncryption });
 }
 var access = { normalizeClientIp, createClientIpResolver, createConditionCheck, createRequestCheck, loadPolicy };
-var ENV_VAR_PATTERN = /\$\{([^}:]+)(?::([^}]*))?\}/g;
-var FULL_VAR_PATTERN = /^\$\{[^}:]+(?::[^}]*)?\}$/;
-function parseEnvValue(value) {
-  if (value === "")
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function segment(value) {
+  return value.replace(/[^a-z0-9]+/gi, "_").replace(/^_+|_+$/g, "").toUpperCase();
+}
+function shapes(node, root, value, depth = 0) {
+  if (depth > 32)
+    return [];
+  const result = [node];
+  if (typeof node.$ref === "string" && node.$ref.startsWith("#/")) {
+    let target = root;
+    for (const key of node.$ref.slice(2).split("/").map((item) => item.replaceAll("~1", "/").replaceAll("~0", "~")))
+      target = object(target)?.[key];
+    if (object(target))
+      result.push(...shapes(object(target), root, value, depth + 1));
+  }
+  for (const keyword of ["anyOf", "oneOf", "allOf"]) {
+    if (!Array.isArray(node[keyword]))
+      continue;
+    for (const item of node[keyword]) {
+      const branch = object(item);
+      if (!branch)
+        continue;
+      const fields = object(branch.properties);
+      const input = object(value);
+      if (fields && input && Object.entries(fields).some(([key, field]) => input[key] !== void 0 && object(field)?.const !== void 0 && object(field).const !== input[key]))
+        continue;
+      result.push(...shapes(branch, root, value, depth + 1));
+    }
+  }
+  return result;
+}
+function combined(nodes) {
+  const entries = nodes.map(object).filter((item) => item !== void 0);
+  return entries.length === 1 ? entries[0] : { anyOf: entries };
+}
+function scalar(text, node, root) {
+  const types = new Set(shapes(node, root).flatMap((item) => Array.isArray(item.type) ? item.type : typeof item.type === "string" ? [item.type] : []));
+  if (types.has("string") && [...types].every((type) => type === "string" || type === "null") && !(text === "null" && types.has("null")))
+    return text;
+  if (text === "")
     return "";
   try {
-    const parsed = parse(value);
-    return parsed === void 0 ? value : parsed;
+    return parse(text) ?? (text === "null" ? null : text);
   } catch {
-    return value;
+    return text;
   }
 }
-function normalizeEnvSegment(segment) {
-  return segment.replace(/[^a-z0-9]+/gi, "_").replace(/^_+|_+$/g, "").toUpperCase();
-}
-function buildConventionEnvName(name, path2) {
-  return ["HAI", name, ...path2].map(normalizeEnvSegment).filter(Boolean).join("_");
+function mergeEnv(layers) {
+  const values = {};
+  for (const layer of layers) {
+    for (const name of Object.keys(layer).sort((left, right) => left.length - right.length || left.localeCompare(right))) {
+      if (layer[name] === void 0)
+        continue;
+      if (name.startsWith("HAI_")) {
+        for (const previous of Object.keys(values)) {
+          if (previous.startsWith(`${name}_`))
+            delete values[previous];
+        }
+      }
+      values[name] = layer[name];
+    }
+  }
+  return values;
 }
-function resolveEnv(value, name, path2 = []) {
-  const conventionEnvValue = process3.env[buildConventionEnvName(name, path2)];
-  if (conventionEnvValue !== void 0)
-    return ok(parseEnvValue(conventionEnvValue));
-  if (typeof value === "string") {
-    ENV_VAR_PATTERN.lastIndex = 0;
-    const hasExplicitEnv = ENV_VAR_PATTERN.test(value);
-    ENV_VAR_PATTERN.lastIndex = 0;
-    if (!hasExplicitEnv)
-      return ok(value);
-    let result = value;
-    while (true) {
-      const match = ENV_VAR_PATTERN.exec(value);
-      if (!match)
-        break;
-      const [fullMatch, varName, defaultValue] = match;
-      const envValue = process3.env[varName];
-      if (envValue === void 0 && defaultValue === void 0) {
-        return err(HaiConfigError.CONFIG_ENV_VAR_MISSING, i18n.coreM("core_configEnvVarMissing", { params: { varName } }));
+function parseEnvironment(text) {
+  const result = parseEnv(text);
+  const names = /* @__PURE__ */ new Set();
+  const assignments = /^(?:export\s+)?([A-Z_]\w*)\s*=\s*('[^']*'|"(?:[^"\\]|\\.)*"|`[^`]*`|[^\r\n]*)/gim;
+  for (const match of text.matchAll(assignments)) {
+    const name = match[1];
+    if (names.has(name))
+      throw new Error(`Duplicate environment variable: ${name}`);
+    names.add(name);
+    if (match[2].startsWith('"') && (match[2].includes('\\"') || match[2].includes("\\u0027"))) {
+      try {
+        result[name] = JSON.parse(match[2]);
+      } catch {
       }
-      result = result.replace(fullMatch, () => envValue ?? defaultValue ?? "");
     }
-    if (FULL_VAR_PATTERN.test(value))
-      return ok(parseEnvValue(result));
-    return ok(result);
   }
-  if (Array.isArray(value)) {
-    const results = [];
-    for (const [index, item] of value.entries()) {
-      const r = resolveEnv(item, name, [...path2, String(index)]);
-      if (!r.success)
-        return r;
-      results.push(r.data);
+  return Object.fromEntries(Object.entries(result).filter((entry) => entry[1] !== void 0));
+}
+function stringifyEnv(values, options = {}) {
+  return `${Object.keys(values).sort().map((name) => {
+    if (!/^[A-Z_]\w*$/i.test(name))
+      throw new Error("Invalid environment variable name");
+    const value = values[name];
+    let literal;
+    if (!value.includes("'"))
+      literal = `'${value}'`;
+    else if (options.target === "compose")
+      literal = JSON.stringify(value).replaceAll("$", () => "$$");
+    else literal = JSON.stringify(value).replaceAll("'", "\\u0027");
+    return `${name}=${literal}`;
+  }).join("\n")}
+`;
+}
+function resolveEnvironment(options, literal = false) {
+  const environment = options.environment ?? process4.env;
+  const missingNames = /* @__PURE__ */ new Set();
+  let root;
+  try {
+    root = options.schema ? options.schema.toJSONSchema({ io: "input", unrepresentable: "any" }) : options.shape ?? {};
+  } catch {
+    root = {};
+  }
+  const prefix = `HAI_${segment(options.name)}`;
+  function visit(original, name, node, inheritedLiteral, depth, declaration = original) {
+    if (depth > 32)
+      throw new Error(name);
+    let value = original;
+    let fromEnvironment = inheritedLiteral;
+    if (environment[name] !== void 0) {
+      value = scalar(environment[name], node, root);
+      fromEnvironment = true;
+    }
+    const alternatives = shapes(node, root);
+    const discriminators = /* @__PURE__ */ new Map();
+    for (const candidate of alternatives) {
+      for (const [key, field] of Object.entries(object(candidate.properties) ?? {})) {
+        if (shapes(object(field) ?? {}, root).some((item) => Object.hasOwn(item, "const")))
+          discriminators.set(key, [...discriminators.get(key) ?? [], field]);
+      }
+    }
+    const selection = { ...object(value) };
+    for (const [key, fields] of discriminators) {
+      const text = environment[`${name}_${segment(key)}`];
+      if (text !== void 0)
+        selection[key] = scalar(text, combined(fields), root);
+    }
+    const candidates = shapes(node, root, Object.keys(selection).length ? selection : value);
+    const synthesized = value === void 0;
+    const valueType = typeof value;
+    const primitiveOverride = value === void 0 || candidates.some((candidate) => value !== null && candidate.type === valueType || candidate.const === value || value === null && candidate.type === "null");
+    if (primitiveOverride && !object(value) && !Array.isArray(value)) {
+      const declared = /* @__PURE__ */ new Set([...Object.keys(object(declaration) ?? {}), ...candidates.flatMap((candidate) => Object.keys(object(candidate.properties) ?? {}))]);
+      const specified = [...declared].filter((key) => Object.keys(environment).some((candidate) => environment[candidate] !== void 0 && (candidate === `${name}_${segment(key)}` || candidate.startsWith(`${name}_${segment(key)}_`))));
+      if (specified.length)
+        value = Object.fromEntries(specified.map((key) => [key, void 0]));
+    }
+    if (value === void 0 && Object.keys(environment).some((key) => environment[key] !== void 0 && key.startsWith(`${name}_`))) {
+      if (candidates.some((item) => item.type === "object" || object(item.properties)))
+        value = {};
+    }
+    const indexed = Object.keys(environment).filter((key) => environment[key] !== void 0 && key.startsWith(`${name}_`) && /^\d+(?:_|$)/.test(key.slice(name.length + 1)));
+    if (value === void 0 && indexed.length && candidates.some((candidate) => candidate.type === "array")) {
+      const defaults = candidates.find((candidate) => Array.isArray(candidate.default))?.default;
+      if (!Array.isArray(defaults))
+        throw new Error(indexed[0]);
+      value = structuredClone(defaults);
     }
-    return ok(results);
+    if (Array.isArray(value)) {
+      const itemShape = combined(candidates.map((item) => item.items));
+      for (const key of indexed) {
+        const index = key.slice(name.length + 1).split("_")[0];
+        if (/^\d+$/.test(index) && (String(Number(index)) !== index || Number(index) >= value.length))
+          throw new Error(key);
+      }
+      return value.map((item, index) => visit(item, `${name}_${index}`, itemShape, fromEnvironment, depth + 1, Array.isArray(declaration) ? declaration[index] : void 0));
+    }
+    const input = object(value);
+    if (input) {
+      const properties = /* @__PURE__ */ new Map();
+      for (const candidate of candidates) {
+        for (const [key, field] of Object.entries(object(candidate.properties) ?? {}))
+          properties.set(key, [...properties.get(key) ?? [], field]);
+      }
+      const declaredKeys = /* @__PURE__ */ new Set([...Object.keys(object(declaration) ?? {}), ...properties.keys()]);
+      const keys = /* @__PURE__ */ new Set([...Object.keys(input), ...[...declaredKeys].filter((key) => Object.keys(environment).some((nameInEnv) => environment[nameInEnv] !== void 0 && (nameInEnv === `${name}_${segment(key)}` || nameInEnv.startsWith(`${name}_${segment(key)}_`))))]);
+      const entries = [...keys].map((key) => {
+        if (["__proto__", "prototype", "constructor"].includes(key))
+          throw new Error(name);
+        return [key, visit(input[key], `${name}_${segment(key)}`, combined(properties.get(key) ?? candidates.map((candidate) => candidate.additionalProperties)), fromEnvironment, depth + 1, object(declaration)?.[key])];
+      }).filter(([, child]) => child !== void 0);
+      return synthesized && !entries.length ? void 0 : Object.fromEntries(entries);
+    }
+    if (typeof value !== "string" || fromEnvironment)
+      return value;
+    const full = /^\$\{[^}:]+(?::[^}]*)?\}$/.test(value);
+    const resolved = value.replace(/\$\{([^}:]+)(?::([^}]*))?\}/g, (_match, key, fallback) => {
+      if (environment[key] === void 0 && fallback === void 0 && options.missing !== "empty") {
+        missingNames.add(key);
+        throw new Error(key);
+      }
+      return environment[key] ?? fallback ?? "";
+    });
+    return full ? scalar(resolved, node, root) : resolved;
+  }
+  try {
+    return ok(visit(options.value, prefix, root, literal, 0));
+  } catch (failure) {
+    const name = failure instanceof Error && /^[A-Z_]\w*$/i.test(failure.message) ? failure.message : prefix;
+    if (!missingNames.has(name))
+      return err(HaiConfigError.CONFIG_VALIDATION_ERROR, i18n.coreM("core_configValidationFailed"), { fields: [name] });
+    return err(HaiConfigError.CONFIG_ENV_VAR_MISSING, i18n.coreM("core_configEnvVarMissing", { params: { varName: name } }));
   }
-  if (typeUtils.isObject(value)) {
-    const results = {};
-    for (const [k, v] of Object.entries(value)) {
-      const r = resolveEnv(v, name, [...path2, k]);
-      if (!r.success)
-        return r;
-      results[k] = r.data;
+}
+function toEnv(options) {
+  const result = {};
+  const root = options.schema ? options.schema.toJSONSchema({ io: "input", unrepresentable: "any" }) : options.shape ?? {};
+  function visit(value, name, node) {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(name))
+      throw new Error("Invalid environment variable name");
+    if (value === void 0)
+      return;
+    const input = object(value);
+    const candidates = shapes(node, root, value);
+    const properties = Object.assign({}, ...candidates.map((candidate) => object(candidate.properties) ?? {}));
+    const dynamic = candidates.some((candidate) => candidate.additionalProperties === true || object(candidate.additionalProperties));
+    if (input && Object.keys(input).length && !dynamic && Object.keys(input).every((key) => /^[a-z][a-zA-Z0-9]*$/.test(key))) {
+      for (const [key, item] of Object.entries(input))
+        visit(item, `${name}_${segment(key)}`, object(properties[key]) ?? {});
+    } else {
+      result[name] = value === null || typeof value === "object" ? JSON.stringify(value) : String(value);
     }
-    return ok(results);
   }
-  return ok(value);
+  visit(options.value, options.prefix, root);
+  return result;
 }
+
+// src/functions/core-function-config.node.ts
 var configCache = /* @__PURE__ */ new Map();
 var watchEntries = /* @__PURE__ */ new Map();
 function createNotLoadedError(name) {
@@ -399,20 +556,20 @@ function notifyWatchCallbacks(name, result) {
     }
   }
 }
-function loadYaml(name, filePath) {
+function loadYaml(name, filePath, schema) {
   if (!existsSync(filePath)) {
     return err(HaiConfigError.CONFIG_FILE_NOT_FOUND, i18n.coreM("core_configFileNotExist", { params: { filePath } }));
   }
   try {
     const content = readFileSync(filePath, "utf-8");
     const parsed = parse(content);
-    return resolveEnv(parsed, name);
+    return resolveEnvironment({ name, value: parsed, schema });
   } catch (error) {
     return err(HaiConfigError.CONFIG_PARSE_ERROR, i18n.coreM("core_configParseFailed", { params: { filePath } }), error);
   }
 }
 function loadConfig(name, filePath, schema) {
-  const yamlResult = loadYaml(name, filePath);
+  const yamlResult = loadYaml(name, filePath, schema);
   if (!yamlResult.success)
     return yamlResult;
   const parseResult = schema.safeParse(yamlResult.data);
@@ -433,12 +590,21 @@ function loadAndCache(name, filePath, schema) {
   }
   return result;
 }
+function loadConfigStructure(name, filePath, schemaHint) {
+  const result = loadYaml(name, filePath, schemaHint);
+  if (result.success)
+    configCache.set(name, { data: result.data, filePath, schemaHint, loadedAt: Date.now() });
+  return result;
+}
 function validateLoadedConfig(name, schema) {
   const entry = configCache.get(name);
   if (!entry) {
     return err(createNotLoadedError(name));
   }
-  const parseResult = schema.safeParse(entry.data);
+  const resolved = resolveEnvironment({ name, value: entry.data, schema }, true);
+  if (!resolved.success)
+    return resolved;
+  const parseResult = schema.safeParse(resolved.data);
   if (!parseResult.success) {
     return err(HaiConfigError.CONFIG_VALIDATION_ERROR, i18n.coreM("core_configValidationFailed"), parseResult.error.issues);
   }
@@ -458,7 +624,7 @@ function reloadAndNotify(name) {
     notifyWatchCallbacks(name, result2);
     return result2;
   }
-  const result = entry.schema ? loadConfig(name, entry.filePath, entry.schema) : loadYaml(name, entry.filePath);
+  const result = entry.schema ? loadConfig(name, entry.filePath, entry.schema) : loadYaml(name, entry.filePath, entry.schemaHint);
   if (result.success) {
     configCache.set(name, {
       ...entry,
@@ -482,15 +648,18 @@ function startFileWatcher(name) {
       callbacks: /* @__PURE__ */ new Set(),
       debounceTimer: null
     };
-    const watcher = watch(entry.filePath, (eventType) => {
-      if (eventType === "change") {
-        if (watchEntry.debounceTimer)
-          clearTimeout(watchEntry.debounceTimer);
-        watchEntry.debounceTimer = setTimeout(() => {
-          watchEntry.debounceTimer = null;
+    const filePath = resolve(entry.filePath);
+    const fileName = basename(filePath);
+    const watcher = watch(dirname(filePath), (_eventType, changedName) => {
+      if (changedName !== null && changedName.toString() !== fileName)
+        return;
+      if (watchEntry.debounceTimer)
+        clearTimeout(watchEntry.debounceTimer);
+      watchEntry.debounceTimer = setTimeout(() => {
+        watchEntry.debounceTimer = null;
+        if (watchEntries.get(name) === watchEntry)
           reloadAndNotify(name);
-        }, 100);
-      }
+      }, 100);
     });
     watchEntry.watcher = watcher;
     watchEntries.set(name, watchEntry);
@@ -509,7 +678,7 @@ function registerWatch(name, callback) {
   entry.callbacks.add(callback);
   return () => {
     const current = watchEntries.get(name);
-    if (!current)
+    if (current !== entry)
       return;
     current.callbacks.delete(callback);
     if (current.callbacks.size === 0) {
@@ -548,10 +717,67 @@ function clearCache(name) {
   }
 }
 var config = {
+  /**
+   * 合并从低到高的环境来源；高来源父项替换旧节点，同来源细项覆盖父 JSON。
+   * @param layers - 按优先级排列的字面变量。
+   * @returns 合并后的变量，可能含秘密。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.mergeEnv([{ HAI_APP_NAME: 'base' }, { HAI_APP_NAME: 'test' }])
+   * ```
+   */
+  mergeEnv,
+  /**
+   * 解析 dotenv 字面文本，拒绝重复键，不执行 shell 或变量展开。
+   * @param text - dotenv 文本，可能包含秘密。
+   * @returns 字面变量；重复键抛出不含变量值的错误。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.parseEnv('HAI_APP_NAME=Example\n')
+   * ```
+   */
+  parseEnv: parseEnvironment,
+  /**
+   * 无损编码 dotenv，父变量排在细项前；含秘密时只能写入受保护文件。
+   * @param values - 字面变量，不进行脱敏。
+   * @param options - 输出语法目标，默认 Node dotenv。
+   * @param options.target - Compose 目标同时处理其美元符号插值规则。
+   * @returns dotenv 文本；非法变量名抛错。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.stringifyEnv({ HAI_APP_NAME: 'Example' })
+   * ```
+   */
+  stringifyEnv,
+  /**
+   * 按已有结构或 Schema 解析父 JSON 和细项，不修改缓存或进程环境。
+   * @param options - 配置名、原始结构、变量、可选 Schema 和缺失插值规则。
+   * @returns 解析结果；调用方仍须执行最终 Schema 校验。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.resolve({ name: 'app', value: { name: 'Example' }, environment: { HAI_APP_NAME: 'Test' } })
+   * ```
+   */
+  resolve: (options) => resolveEnvironment(options),
+  /**
+   * 默认将对象展开为细项；数组、动态字典和空对象保留 JSON。
+   * @param options - 完整变量前缀、配置值和可选 Schema。
+   * @returns 字面环境变量，不脱敏；非法名称抛错。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.toEnv({ prefix: 'HAI_APP', value: { name: 'Example', tags: ['demo'] } })
+   * ```
+   */
+  toEnv,
   /**
    * 读取 dotenv 文件并按统一顺序合并，不修改进程环境。
    *
-   * 优先级：已有进程环境 > .env.local > .env.<mode> > .env。
+   * 优先级：已有进程环境 > .env.<mode>.local > .env.local > .env.<mode> > .env。
    * development/production 分别映射到 dev/prod；不存在的文件跳过。
    * 返回值可能包含私有配置，仅在 Node 启动/构建边界注入，不下发浏览器。
    * @param options - 文件所在目录及环境模式
@@ -570,18 +796,17 @@ var config = {
     const mode = options.mode === "development" ? "dev" : options.mode === "production" ? "prod" : options.mode;
     if (!/^[a-z0-9][\w-]*$/i.test(mode))
       return err(HaiConfigError.CONFIG_VALIDATION_ERROR, i18n.coreM("core_configValidationFailed"));
-    const envDir = options.envDir ?? process3.cwd();
+    const envDir = options.envDir ?? process4.cwd();
     try {
-      const merged = {};
-      for (const name of [".env", `.env.${mode}`, ".env.local"]) {
+      const layers = [];
+      for (const name of [".env", `.env.${mode}`, ".env.local", `.env.${mode}.local`]) {
         const file = join(envDir, name);
         if (existsSync(file))
-          Object.assign(merged, parseEnv(readFileSync(file, "utf8")));
-      }
-      for (const name of Object.keys(merged)) {
-        if (process3.env[name] !== void 0)
-          merged[name] = process3.env[name];
+          layers.push(parseEnvironment(readFileSync(file, "utf8")));
       }
+      const declared = new Set(layers.flatMap((layer) => Object.keys(layer)));
+      layers.push(Object.fromEntries(Object.entries(process4.env).filter(([name]) => declared.has(name) || name.startsWith("HAI_"))));
+      const merged = mergeEnv(layers);
       return ok(merged);
     } catch {
       return err(HaiConfigError.CONFIG_PARSE_ERROR, i18n.coreM("core_configParseFailed", { params: { filePath: envDir } }));
@@ -730,7 +955,8 @@ var config = {
   /**
    * 监听配置文件变更并自动重载。
    *
-   * 文件变更时自动重新加载并调用回调。配置未加载时立即回调 NOT_LOADED 错误。
+   * 普通写入、原子替换及删除重建均触发重载；失败保留最近成功的缓存并通知错误。
+   * 配置未加载时立即回调 NOT_LOADED 错误。
    *
    * @param name - 配置名称
    * @param callback - 配置变更回调，接收新配置或错误
@@ -781,14 +1007,14 @@ var config = {
   }
 };
 var nodeRequire = createRequire(import.meta.url);
-if (process3.platform === "win32" && process3.stdout.isTTY) {
+if (process4.platform === "win32" && process4.stdout.isTTY) {
   try {
     execSync("chcp 65001 > nul", { stdio: "ignore" });
-    if (process3.stdout.setDefaultEncoding) {
-      process3.stdout.setDefaultEncoding("utf8");
+    if (process4.stdout.setDefaultEncoding) {
+      process4.stdout.setDefaultEncoding("utf8");
     }
-    if (process3.stderr.setDefaultEncoding) {
-      process3.stderr.setDefaultEncoding("utf8");
+    if (process4.stderr.setDefaultEncoding) {
+      process4.stderr.setDefaultEncoding("utf8");
     }
   } catch (_e) {
   }
@@ -1044,7 +1270,7 @@ function initCore(options = {}) {
         });
       }
     } else {
-      const result = config.load(item.name, item.filePath);
+      const result = loadConfigStructure(item.name, item.filePath, options.configSchemas?.[item.name]);
       if (result.success) {
         logger2.info(`[core] Config loaded: ${item.name} <- ${item.filePath}`);
       } else {