生产级 Agent 多环境自动配置

import os
env = os.getenv("ENV", "development")  # 默认开发环境

agents/config/
├── __init__.py        # 模块入口，导出公共 API
├── schema.py          # Pydantic 数据模型定义
├── loader.py          # 核心加载逻辑（5 步流程）
├── paths.py           # 文件路径定位工具
├── demo.py            # 完整演示代码
├── README.md          # 文档
├── jsons/             # 结构化配置（可提交 Git）
│   ├── default.json   # ① 公共默认配置
│   ├── test.json      # ② test 环境覆盖配置
│   ├── dev.json       # ③ dev 环境覆盖配置
│   └── prod.json      # ④ prod 环境覆盖配置
└── envs/              # 敏感信息（不提交 Git）
    ├── test.env       # test 环境密钥
    ├── dev.env        # dev 环境密钥模板（参考用）
    └── prod.env       # prod 环境密钥模板（参考用）

base_config = load_default_config()
env_config = load_env_config(env)       # 只含差异项
final_config = merge_config(base_config, env_config) # 假设工具函数

def merge_config(base: dict, override: dict) -> dict:
    """深度合并两个字典, override 中同名键覆盖 base.
    规则::
        - dict + dict → 递归合并
        - 其他类型   → override 直接替换 base
    Examples::
        >>> merge_config({"a": {"x": 1}}, {"a": {"y": 2}})
        {'a': {'x': 1, 'y': 2}}
    """
    result = base.copy()
    for key, value in override.items():
        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
            result[key] = merge_config(result[key], value)
        else:
            result[key] = value
    return result

# .gitignore
config/.secrets.json
config/test/secrets.yml

class Anthropic(Base):
    """Anthropic configuration."""
    api_base: Any = Field(default=None)
    api_key: str = Field(default="")
    extra_headers: Any = Field(default=None)

def load_config(env: str | None = None) -> Config:
    """加载配置, 返回 Config 实例.
    """
    # ── Step 1: 获取 APP_ENV ───────────────────────────────────────────
    env = env or get_app_env()
    logger.info(f"[{env}] 开始加载配置")

    # ── Step 2: 读取公共配置 default.json ─────────────────────────────
    default_path = get_json_file("default")
    data = _load_json(default_path, required=False)
    logger.info(f"Step2: default.json → {list(data.keys()) if data else '(空)'}")

    # ── Step 3: 读取环境配置 {env}.json, 合并到公共配置 ───────────────
    env_path = get_json_file(env)
    env_data = _load_json(env_path, required=False)
    data = merge_config(data, env_data)
    logger.info(f"Step3: {env}.json merged → keys={list(data.keys())}")

    # ── Step 4: 读取敏感信息 {env}.env, 合并到配置 ────────────────────
    #   test: .env → 嵌套 dict → merge_config (data 直接含完整密钥)
    #   dev/prod: 不读文件, Pydantic BaseSettings 从 os.environ 自动补充 AGENTS_*
    if env in _ENVS_USE_FILE:
        env_vars = load_env_file(env)
        if env_vars:
            secrets_dict = _env_to_nested_dict(env_vars, prefix=ENV_PREFIX)
            data = merge_config(data, secrets_dict)
            logger.info(f"Step4: {env}.env merged → {len(env_vars)} 个密钥")

    # ── Step 5: 清理 & 校验, 返回 Config 实例 ────────────────────────────
    data = _clean_data(data)
    try:
        config = Config.model_validate(data)
    except pydantic.ValidationError as e:
        raise ValueError(f"Config 校验失败 [{env}]: {e}") from e

    logger.info(f"[{env}] 加载完成 — model={config.agents.defaults.model}")
    return config

# 使用 Pydantic Settings 嵌套格式:
#   AGENTS_PROVIDERS__QIANFAN__API_KEY → providers.qianfan.apiKey
#   格式: AGENTS_{顶级}__{二级}__{字段名}

# === Providers API Keys ===
AGENTS_PROVIDERS__QIANFAN__API_KEY=sk-test-qianfan-456
AGENTS_PROVIDERS__OPENAI__API_KEY=sk-test-openai-xxx
AGENTS_PROVIDERS__ANTHROPIC__API_KEY=sk-test-anthropic-xxx
AGENTS_PROVIDERS__CUSTOM__API_KEY=sk-test-custom-xxx

class Config(BaseSettings):
    """Root configuration.
    Environment variables are automatically loaded with the ``AGENTS_`` prefix::
    Nested fields use double underscore (``__``) as delimiter.
    """
    agents: Agents = Field(default_factory=Agents)
    api: Api = Field(default_factory=Api)
    ....
    
    model_config = ConfigDict(
        env_prefix="AGENTS_",
        env_nested_delimiter="__",
        # Allow extra fields from JSON (_comment, _envMeta, etc.)
        extra="ignore",
    )

config = Config.load_config()  # 自动完成全部加载、合并、校验
db_url = config.database.connection_string

class Base(BaseModel):
    """Base model that accepts both camelCase and snake_case keys."""
    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)