@ai-setting/roy-agent-core 1.3.9 → 1.3.11

package/src/config/env-key.ts

@@ -1,210 +0,0 @@
-/**
- * 环境变量键名转换工具
- * 
- * 提供统一的环境变量键名转换逻辑，供 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

@@ -1,252 +0,0 @@
-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");
-  });
-});