@ai-setting/roy-agent-core 1.0.0

package/src/config/env-key.ts

@@ -0,0 +1,210 @@
+/**
+ * 环境变量键名转换工具
+ * 
+ * 提供统一的环境变量键名转换逻辑，供 EnvSource 和其他组件使用
+ * 
+ * 转换规则（toEnvKey）：
+ * 1. 将点号替换为下划线
+ * 2. 将驼峰命名转换为下划线分隔的大写形式
+ * 3. 拼接前缀（如果前缀不以_结尾则自动添加）
+ * 
+ * 转换规则（fromEnvKey - 用于 EnvSource）：
+ * 1. 移除前缀
+ * 2. 保持原始格式（大小写）
+ * 
+ * 转换规则（envKeyToConfigKey - 通用）：
+ * 1. 移除前缀
+ * 2. 转小写
+ * 3. 将下划线替换为点号
+ * 4. 拼接组件名前缀
+ * 
+ * @example
+ * // toEnvKey
+ * toEnvKey("llm.defaultModel", "LLM") -> "LLM_LLM_DEFAULT_MODEL"
+ * toEnvKey("logTrace.level", "LOG") -> "LOG_LOG_TRACE_LEVEL"
+ * 
+ * // fromEnvKey (用于 EnvSource.list)
+ * fromEnvKey("LLM_LLM_DEBUG", "LLM_") -> "DEBUG"
+ * 
+ * // envKeyToConfigKey (通用，支持任意组件)
+ * envKeyToConfigKey("LLM_LLM_DEFAULT_MODEL", "LLM", "llm") -> "llm.default.model"
+ * envKeyToConfigKey("LOG_LOG_TRACE_LEVEL", "LOG", "logTrace") -> "logTrace.level"
+ */
+
+/**
+ * 将点号路径转换为环境变量名（带前缀）
+ * 
+ * 规则：
+ * - `.` 和 `-` 都替换为路径分隔符 `_`
+ * - 驼峰转为下划线大写
+ * 
+ * 转换示例：
+ * - `llm.defaultModel` + `LLM` -> `LLM_LLM_DEFAULT_MODEL`
+ * - `log-trace.logging.level` + `LOG` -> `LOG_TRACE_LOGGING_LEVEL`
+ * 
+ * @example
+ * toEnvKey("llm.defaultModel", "LLM") -> "LLM_LLM_DEFAULT_MODEL"
+ * toEnvKey("log-trace.logging.level", "LOG") -> "LOG_TRACE_LOGGING_LEVEL"
+ */
+export function toEnvKey(key: string, prefix: string): string {
+  // 1. 将点号和连字符替换为下划线
+  let keyNormalized = key.replace(/[.-]/g, "_");
+  
+  // 2. 将驼峰命名转换为下划线分隔的大写形式
+  keyNormalized = keyNormalized
+    .replace(/([a-z])([A-Z])/g, "$1_$2")
+    .replace(/_+/g, "_")
+    .toUpperCase();
+  
+  // 3. 拼接前缀
+  if (prefix) {
+    // 如果前缀已以下划线结尾，不要重复添加
+    const separator = prefix.endsWith("_") ? "" : "_";
+    return `${prefix}${separator}${keyNormalized}`;
+  }
+  return keyNormalized;
+}
+
+/**
+ * 从环境变量名提取内部键名（移除前缀，保持原始格式）
+ * 
+ * 用于 EnvSource.list() 等需要保持原始格式的场景
+ */
+export function fromEnvKey(envKey: string, prefix: string): string {
+  if (!prefix) {
+    return envKey;
+  }
+  
+  // 检查前缀匹配
+  if (envKey.startsWith(prefix)) {
+    const afterPrefix = envKey.slice(prefix.length);
+    // 移除开头的下划线（如果有）
+    if (afterPrefix.startsWith("_")) {
+      return afterPrefix.slice(1);
+    }
+    return afterPrefix;
+  }
+  return envKey;
+}
+
+/**
+ * 将环境变量名转换为配置键名（通用，支持任意组件）
+ * 
+ * 规则：
+ * - `_` 转换为 `.` 作为键路径分隔符
+ * - 组件名中的 `-` 在环境变量中也会是 `_`（因为 toEnvKey 会转换）
+ * 
+ * 环境变量格式约定:
+ * - PREFIX_KEY: 如 LLM_DEFAULT_MODEL -> llm.default.model
+ * - PREFIX_COMPONENT_KEY: 如 LLM_LLM_DEFAULT_MODEL -> llm.default.model
+ * - 对于带连字符的组件名: 如 LOG_TRACE_LOGGING_LEVEL -> log-trace.logging.level (当组件名为 log-trace)
+ * 
+ * @param envKey - 环境变量名（如 LLM_LLM_DEFAULT_MODEL 或 LOG_TRACE_LOGGING_LEVEL）
+ * @param prefix - 环境变量前缀（如 LLM 或 LOG）
+ * @param componentName - 组件名（如 llm, logTrace, log-trace）
+ * @returns 配置键名（如 llm.default.model 或 log-trace.logging.level）
+ * 
+ * @example
+ * // 格式1: PREFIX_KEY
+ * envKeyToConfigKey("LLM_DEFAULT_MODEL", "LLM", "llm") -> "llm.default.model"
+ * 
+ * // 格式2: PREFIX_COMPONENT_KEY
+ * envKeyToConfigKey("LLM_LLM_DEFAULT_MODEL", "LLM", "llm") -> "llm.default.model"
+ * 
+ * // 格式3: 连字符组件名（环境变量中 - 会被转成 _）
+ * envKeyToConfigKey("LOG_TRACE_LOGGING_LEVEL", "LOG", "log-trace") -> "log-trace.logging.level"
+ */
+export function envKeyToConfigKey(envKey: string, prefix: string, componentName: string): string | undefined {
+  const prefixUpper = prefix.toUpperCase();
+  
+  if (!envKey.startsWith(prefixUpper)) {
+    return undefined;
+  }
+  
+  // 将组件名转换为下划线大写格式用于比较
+  const componentUpperNormalized = componentName
+    .replace(/-/g, "_")
+    .toUpperCase();
+  
+  // 移除前缀
+  let keyPart = envKey.slice(prefixUpper.length);
+  
+  // 移除前缀后的分隔符
+  if (keyPart.startsWith("_")) {
+    keyPart = keyPart.slice(1);
+  }
+  
+  if (!keyPart) {
+    return undefined;
+  }
+  
+  // 找出第一个下划线的位置
+  const firstUnderscore = keyPart.indexOf("_");
+  let restPart: string;
+  
+  if (firstUnderscore === -1) {
+    // 没有下划线，整个作为 rest
+    restPart = keyPart;
+  } else {
+    const firstPart = keyPart.slice(0, firstUnderscore);
+    const remaining = keyPart.slice(firstUnderscore + 1);
+    
+    // 检查第一段是否等于组件名的大写形式
+    if (firstPart === componentUpperNormalized) {
+      // 匹配成功，移除组件名前缀
+      restPart = remaining;
+    } else {
+      // 第一段不是组件名，整个 keyPart 作为 rest
+      restPart = keyPart;
+    }
+  }
+  
+  if (!restPart) {
+    return undefined;
+  }
+  
+  // 将下划线转换为点号，转小写，拼接组件名
+  const restPartConverted = restPart.replace(/_/g, ".");
+  
+  return `${componentName}.${restPartConverted.toLowerCase()}`;
+}
+
+/**
+ * 从环境变量键名提取组件名
+ * 
+ * 用于自动发现所有以 prefix 开头的环境变量
+ * 
+ * @param envKey - 环境变量名
+ * @param prefix - 前缀
+ * @returns 组件名和剩余部分（如 ["llm", "default.model"]）
+ */
+export function extractComponentFromEnvKey(envKey: string, prefix: string): [string, string] | undefined {
+  const prefixUpper = prefix.toUpperCase();
+  
+  if (!envKey.startsWith(prefixUpper)) {
+    return undefined;
+  }
+  
+  // 移除前缀
+  let keyPart = envKey.slice(prefixUpper.length);
+  // 移除前缀后的下划线（如果有）
+  if (keyPart.startsWith("_")) {
+    keyPart = keyPart.slice(1);
+  }
+  
+  if (!keyPart) {
+    return undefined;
+  }
+  
+  // 提取组件名（第一段下划线之前的部分）
+  const underscoreIndex = keyPart.indexOf("_");
+  if (underscoreIndex === -1) {
+    // 只有一个部分，如 LLM_DEFAULT_MODEL -> llm.default_model
+    return [keyPart.toLowerCase().replace(/_/g, "."), ""];
+  }
+  
+  const component = keyPart.slice(0, underscoreIndex).toLowerCase();
+  const rest = keyPart.slice(underscoreIndex + 1);
+  
+  return [`${component}.${rest.replace(/_/g, ".")}`, rest];
+}

package/src/config/env-source.test.ts

@@ -0,0 +1,252 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { EnvSource } from "./env-source";
+
+describe("EnvSource", () => {
+  // 保存原始环境变量
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    // 重置环境变量
+    process.env = { ...originalEnv };
+    // 删除测试相关变量
+    delete process.env.TEST_VAR;
+    delete process.env.NESTED_VAR;
+    delete process.env["USER.PROFILE.NAME"];
+    delete process.env.PREFIX_TEST_ONE;
+    delete process.env.PREFIX_TEST_TWO;
+  });
+
+  afterEach(() => {
+    // 恢复原始环境变量
+    process.env = originalEnv;
+  });
+
+  test("read returns undefined for non-existent key", () => {
+    const source = new EnvSource();
+    const value = source.read("NON_EXISTENT_VAR");
+    expect(value).toBeUndefined();
+  });
+
+  test("read returns value from environment variable", () => {
+    process.env.TEST_VAR = "hello world";
+    
+    const source = new EnvSource();
+    expect(source.read("TEST_VAR")).toBe("hello world");
+  });
+
+  test("read converts key to uppercase", () => {
+    process.env.TEST_VAR = "value";
+    
+    const source = new EnvSource();
+    expect(source.read("test_var")).toBe("value");
+    expect(source.read("TEST_VAR")).toBe("value");
+  });
+
+  test("read supports prefix matching", () => {
+    process.env.MY_APP_DEBUG = "true";
+    process.env.MY_APP_PORT = "8080";
+    process.env.OTHER_VAR = "ignored";
+    
+    const source = new EnvSource({ prefix: "MY_APP_" });
+    expect(source.read("DEBUG")).toBe("true");
+    expect(source.read("PORT")).toBe("8080");
+    expect(source.read("OTHER_VAR")).toBeUndefined();
+  });
+
+  test("read returns original key if prefix doesn't match", () => {
+    process.env.MY_APP_DEBUG = "true";
+    
+    const source = new EnvSource({ prefix: "OTHER_" });
+    expect(source.read("DEBUG")).toBeUndefined();
+    expect(source.read("MY_APP_DEBUG")).toBeUndefined();
+  });
+
+  test("read returns string value by default", () => {
+    process.env.TEST_STRING = "hello";
+    process.env.TEST_NUMBER = "42";
+    
+    const source = new EnvSource();
+    expect(source.read("TEST_STRING")).toBe("hello");
+    expect(source.read("TEST_NUMBER")).toBe("42");
+  });
+
+  test("read applies transform function", () => {
+    process.env.TEST_BOOL = "true";
+    process.env.TEST_NUM = "42";
+    
+    const source = new EnvSource({
+      transform: (value, key) => {
+        if (key.endsWith("_BOOL")) return value === "true";
+        if (key.endsWith("_NUM")) return parseInt(value, 10);
+        return value;
+      },
+    });
+    
+    expect(source.read("TEST_BOOL")).toBe(true);
+    expect(source.read("TEST_NUM")).toBe(42);
+  });
+
+  test("write sets environment variable", () => {
+    const source = new EnvSource();
+    const result = source.write("TEST_VAR", "new value");
+    expect(result).toBe(true);
+    expect(process.env.TEST_VAR).toBe("new value");
+  });
+
+  test("write applies prefix", () => {
+    const source = new EnvSource({ prefix: "APP_" });
+    source.write("DEBUG", "true");
+    expect(process.env.APP_DEBUG).toBe("true");
+  });
+
+  test("write applies transform function", () => {
+    const source = new EnvSource({
+      transform: (value) => String(value),
+    });
+    source.write("TEST_NUM", 42);
+    expect(process.env.TEST_NUM).toBe("42");
+  });
+
+  test("write converts key to uppercase", () => {
+    const source = new EnvSource();
+    source.write("test_var", "value");
+    expect(process.env.TEST_VAR).toBe("value");
+  });
+
+  test("delete removes environment variable", () => {
+    process.env.TEST_VAR = "value";
+    
+    const source = new EnvSource();
+    const result = source.delete("TEST_VAR");
+    expect(result).toBe(true);
+    expect(process.env.TEST_VAR).toBeUndefined();
+  });
+
+  test("delete returns false for non-existent key", () => {
+    const source = new EnvSource();
+    const result = source.delete("NON_EXISTENT");
+    expect(result).toBe(false);
+  });
+
+  test("delete applies prefix", () => {
+    process.env.APP_TEST = "value";
+    
+    const source = new EnvSource({ prefix: "APP_" });
+    const result = source.delete("TEST");
+    expect(result).toBe(true);
+    expect(process.env.APP_TEST).toBeUndefined();
+  });
+
+  test("list returns all environment variables", () => {
+    process.env.TEST_ONE = "1";
+    process.env.TEST_TWO = "2";
+    process.env.OTHER = "3";
+    
+    const source = new EnvSource();
+    const entries = source.list();
+    
+    const testEntries = entries.filter((e) => e.key.startsWith("TEST_"));
+    expect(testEntries).toContainEqual({ key: "TEST_ONE", value: "1" });
+    expect(testEntries).toContainEqual({ key: "TEST_TWO", value: "2" });
+  });
+
+  test("list applies prefix filter", () => {
+    process.env.MY_APP_DEBUG = "true";
+    process.env.MY_APP_PORT = "8080";
+    process.env.OTHER_VAR = "ignored";
+    
+    const source = new EnvSource({ prefix: "MY_APP_" });
+    const entries = source.list();
+    
+    expect(entries).toContainEqual({ key: "DEBUG", value: "true" });
+    expect(entries).toContainEqual({ key: "PORT", value: "8080" });
+    expect(entries).not.toContainEqual(
+      expect.objectContaining({ key: "OTHER_VAR" })
+    );
+  });
+
+  test("list removes prefix from keys", () => {
+    process.env.APP_DEBUG = "true";
+    
+    const source = new EnvSource({ prefix: "APP_" });
+    const entries = source.list();
+    
+    expect(entries).toContainEqual({ key: "DEBUG", value: "true" });
+    expect(entries).not.toContainEqual(
+      expect.objectContaining({ key: "APP_DEBUG" })
+    );
+  });
+
+  test("watch monitors environment changes", async () => {
+    const source = new EnvSource({ pollInterval: 50 });
+    const events: any[] = [];
+    
+    const unwatch = source.watch((event) => {
+      events.push(event);
+    });
+    
+    // 等待 watcher 初始化
+    await new Promise((r) => setTimeout(r, 100));
+    
+    // 修改环境变量
+    process.env.TEST_VAR = "changed";
+    
+    // 等待事件触发（需要轮询间隔）
+    await new Promise((r) => setTimeout(r, 150));
+    
+    unwatch();
+    
+    expect(events.length).toBeGreaterThan(0);
+  });
+
+  test("watch returns unsubscribe function", async () => {
+    const source = new EnvSource({ pollInterval: 50 });
+    let called = false;
+    const wrappedCallback = (event: any) => { called = true; };
+    
+    const unwatch = source.watch(wrappedCallback);
+    
+    // 等待 watcher 初始化
+    await new Promise((r) => setTimeout(r, 100));
+    
+    unwatch();
+    
+    process.env.TEST_VAR = "changed";
+    
+    // 等待事件触发（需要轮询间隔）
+    await new Promise((r) => setTimeout(r, 150));
+    
+    expect(called).toBe(false);
+  });
+
+  test("has correct name and priority", () => {
+    const source = new EnvSource();
+    expect(source.name).toBe("env");
+    expect(source.priority).toBe(20);
+  });
+
+  test("default priority is higher than file source", () => {
+    const envSource = new EnvSource();
+    expect(envSource.priority).toBe(20);
+  });
+
+  test("transform receives key and value", () => {
+    process.env.TEST_VAR = "original";
+    
+    let receivedKey = "";
+    let receivedValue = "";
+    
+    const source = new EnvSource({
+      transform: (value, key) => {
+        receivedKey = key;
+        receivedValue = value;
+        return value.toUpperCase();
+      },
+    });
+    
+    const result = source.read("TEST_VAR");
+    expect(result).toBe("ORIGINAL");
+    expect(receivedKey).toBe("TEST_VAR");
+    expect(receivedValue).toBe("original");
+  });
+});