Day 01 我们建立了"地图"。今天把地图落到能跑的环境上，并且读几段真源码。学完你能：

• 讲清 uv workspace + editable 安装为什么能做到"改一处、全平台生效"；
• 读懂 config.py 里 load_config() 的完整 5 步流水线，和 _deep_merge() 的递归逻辑；
• 亲手走一个 真实的 base.yaml + dev.yaml 合并，预测出最终 arch_compliance.host 的值；
• 把 gov-agents-server 跑起来，用统一 envelope 调一个 Agent。

monorepo（单体仓库）就是"把很多相关的包放在同一个 git 仓库里"。本项目就是——一个仓库里同时住着 toolkit、21 个 agent、server、cli、前端门户……它们互相依赖。

Day 01 我们已经看过成员清单。今天补上那把"钥匙"——pyproject.toml:44-53 的 [tool.uv.sources]，它才是 editable 生效的关键：

[tool.uv.workspace]
members = [
    "packages/ai-trust-toolkit",
    "packages/gov-agents-server",
    "apps/sre-rca-agent",
    # ... 共 31 条
]

[tool.uv.sources]
ai-trust-toolkit = { workspace = true }   # ← 当谁依赖它，就用本地这份源码，不去 PyPI
gov-agents-mcp   = { workspace = true }

• members（:8-42）= "要一起装的 31 个子包"。uv sync --all-packages 会把它们全部装进同一个 .venv。
• [tool.uv.sources]（:44-53）里 ai-trust-toolkit = { workspace = true } 是精髓：某个 app 的 pyproject 写"我依赖 ai-trust-toolkit"时，uv 不去 PyPI 下载同名包，而是把它指向本地 packages/ai-trust-toolkit/ 的源码目录（生成一个 .pth 软链）。
• 这就是 editable（可编辑安装）：装的是"指路牌"不是"复印件"。你改 toolkit 一行，Python 下次 import 时读的就是新源码，无需重装。

装好 uv 后（curl -LsSf https://astral.sh/uv/install.sh | sh），在仓库根目录只需要一条命令。这条命令和参数来自 README.md:140-141：

参数解释：--all-packages = 装所有 31 个 workspace 成员；--all-extras = 连每个包的可选依赖（如 [postgres]、[observability]）也一起装。装完你可以直接 uv run pytest 跑全套测试——因为测试全部走 FakeLLM（假大模型），不联网、不花钱、几秒跑完。

平台要在本地、测试、预发、生产等不同环境跑，每个环境的数据库地址、预算上限都不同。它用一套"基础配置 + 环境覆盖"的 profile 系统解决，文件在 configs/（base/dev/staging/prod/test.yaml 五个）。核心加载器就一个函数——我们把它整段贴出来读：

@lru_cache(maxsize=4)
def load_config(env: str | None = None) -> Config:
    app_env = env or os.environ.get("APP_ENV", "dev")          # ① 定 profile
    configs_dir = _find_configs_dir()                          # ② 找 configs/ 目录
    base_path = configs_dir / "base.yaml"
    env_path = configs_dir / f"{app_env}.yaml"

    if not env_path.exists():                                  # 找不到就退回 dev（坑！见下）
        log.warning("profile %s.yaml not found ... falling back to dev", app_env)
        env_path = configs_dir / "dev.yaml"
        ...
    try:
        base_data = yaml.safe_load(_expand_env_vars(base_path.read_text(...))) or {}   # ③ 读+展开
        env_data  = yaml.safe_load(_expand_env_vars(env_path.read_text(...)))  or {}
    except yaml.YAMLError as e:
        raise ConfigError(f"yaml syntax error · {e}") from e

    merged = _deep_merge(base_data, env_data)                  # ④ 深度合并
    merged["app_env"] = app_env                                #   app_env 以传入为准(SSOT)
    try:
        return Config(**merged)                                # ⑤ Pydantic 校验
    except Exception as e:
        raise ConfigError(f"config validation failed for {app_env}: {e}") from e

• ① app_env = env or os.environ["APP_ENV"]（默 dev）：先定"我是哪个环境"。这决定第二个 yaml 读谁。
• ② _find_configs_dir()：从当前目录一路往上找到含 configs/base.yaml 的目录（config.py:270-287）。找不到就 raise ConfigError，不静默。
• ③ _expand_env_vars(read_text(...))：先把 yaml 文本里的 ${VAR} 占位符换成真环境变量，再喂给 yaml.safe_load。顺序很关键——先展开、后解析。（L06 细讲）
• ④ _deep_merge(base_data, env_data)：把"公共默认"和"本环境覆盖"逐字段合并。这是全函数的心脏，L05 逐行拆。
• ⑤ Config(**merged)：交给 Pydantic 校验成类型安全的对象。字段名/类型不对当场报错。

返回类型 Config 是一个 Pydantic 模型，它的字段结构就是"平台一共有哪些配置块"的数据字典：

class Config(BaseModel):
    model_config = ConfigDict(extra="forbid")           # ← 多写一个 key 直接报错

    app_env: str = "dev"
    database: DatabaseConfig = Field(default_factory=DatabaseConfig)
    redis: RedisConfig = Field(default_factory=RedisConfig)
    llm: LLMConfig = Field(default_factory=LLMConfig)
    cost: CostConfig = Field(default_factory=CostConfig)
    quota: QuotaConfig = Field(default_factory=QuotaConfig)
    budget: BudgetConfig = Field(default_factory=BudgetConfig)
    observability: ObservabilityConfig = Field(default_factory=ObservabilityConfig)
    gateway: GatewayConfig = Field(default_factory=GatewayConfig)

load_config 的第 ④ 步 _deep_merge 是配置系统的心脏。它只有 13 行，但决定了"base 和 env 到底怎么拼"。整段贴出来：

def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
    """deep merge · dict 递归 · list / scalar 走 override 覆盖。"""
    result = dict(base)                      # ① 先拷一份 base 当底
    for key, value in override.items():      # ② 遍历 override 的每个 key
        if (
            key in result
            and isinstance(result[key], dict)
            and isinstance(value, dict)      # ③ 两边都是 dict → 递归往下合并
        ):
            result[key] = _deep_merge(result[key], value)
        else:
            result[key] = value              # ④ 否则(标量/列表/新key) → override 直接盖
    return result

• ① result = dict(base)：以"公共默认"为底稿拷一份，不改原对象。
• ② for key, value in override.items()：只遍历"本环境覆盖"里写了的字段——没写的字段压根不碰，天然保留 base 的值。这就是"env 只写差异"的实现。
• ③ 两边都是 dict → 递归：像 database.arch_compliance.host 这种嵌套，会一层层钻进去合并，而不是把整个 database 块替换掉。
• ④ else → override 直接盖：注意 docstring 第一行——标量和 list 都走"整体覆盖"，不合并。这个细节是最大的坑，下面 pitfall 专门说。

现在用仓库里真实的两个文件走一遍。看数据库那块，base.yaml 给的是 docker 默认，dev.yaml 覆盖成了真实的 RDS 地址：

把 _deep_merge 当调试器单步走一遍，跟踪 arch_compliance 这个嵌套 dict：

配置里怎么放密码？不硬编码进 yaml，而是写占位符 ${VAR}，运行时从环境变量取。负责展开的是 _expand_env_vars：

# ${VAR} 或 ${VAR:-default} · 锁 var 名走 UPPER_SNAKE
_VAR_PATTERN = re.compile(r"\$\{([A-Z_][A-Z0-9_]*)(:-(.*?))?\}")

def _expand_env_vars(text: str) -> str:
    def replace(m: re.Match[str]) -> str:
        var = m.group(1)
        default = m.group(3) if m.group(3) is not None else ""
        return os.environ.get(var, default)      # env 有→用 env；没有→用默认；再没有→空串
    return _VAR_PATTERN.sub(replace, text)

• _VAR_PATTERN 只认 ${大写下划线名}，可带 :-默认值。例如 base.yaml:31 的 ${REDIS_URL:-redis://redis:6379}。
• replace()：env 里有这个变量就用 env 值；没有但写了默认值就用默认；两者都没有就替换成空串（交给后面 Pydantic 决定要不要报错）。
• 关键顺序（对照 L04 第③步）：先展开文本、再 yaml 解析。所以 secret 永远只活在环境变量里，yaml 文件里只有占位符。

还有个旧的 .env 读取器 load_dotenv_if_present，它有个贴心又关键的保证：

def _apply_env_file(path: Path) -> None:
    """解析 KEY=VALUE 格式,不覆盖已有 env vars。引号去掉,# 当注释。"""
    for raw in path.read_text(encoding="utf-8").splitlines():
        line = raw.strip()
        if not line or line.startswith("#") or "=" not in line:
            continue
        key, _, val = line.partition("=")
        key = key.strip(); val = val.strip().strip('"').strip("'")
        if key and key not in os.environ:        # ← 关键：已存在的 env 绝不覆盖
            os.environ[key] = val

平台主进程是 gov-agents-server（FastAPI 服务），按环境变量 ENABLED_AGENTS 决定挂载哪些 agent：

# 方式 A：脚本一键起
./scripts/start_server.sh                       # 默认 8080

# 方式 B：直接 uvicorn（看清底层）
ENABLED_AGENTS=sre-rca,doc-checker \
  uv run uvicorn gov_agents_server.main:app --host 0.0.0.0 --port 8080

它是怎么按名字找到 agent 的？靠一张写死的注册表，不是自动扫目录：

AGENT_REGISTRY: dict[str, tuple[str, str]] = {
    "sre-rca":      ("sre_rca.server", "build_router"),
    "risk-reviewer":("risk_reviewer.server", "build_router"),
    "alert-triage": ("alert_triage.server", "build_router"),
    "doc-checker":  ("doc_checker.server", "build_router"),
    "biz-link-gov": ("biz_link_gov.server", "build_router"),
    # ...
}

• 这是个字典：key = agent 名（ENABLED_AGENTS 里写的），value = (模块路径, 工厂函数名)。
• 启动时按名字 importlib.import_module("sre_rca.server") 懒加载，再调它的 build_router(pool) 挂到 FastAPI 上。
• 不是自动扫描文件夹——加新 agent 必须手动往这张表加一行（main.py:19-22 的注释就是这么教的）。Day 12 细讲这套机制。

server 起来后访问 http://localhost:8080/ 有自带首页；也可用命令行打 HTTP，每个 agent 端点都是 POST /v1/agent/<name>/invoke：

注意这个返回结构——所有 agent 返回的格式都长一样，叫"统一 envelope（信封）"：case_id（ULID 唯一 ID）/ status / result（业务结果）/ metrics（耗时/token/花钱）/ trace_id。这套外壳是 toolkit 的 build_v1_router() 自动给每个 agent 装上的（Day 12 精讲）。

不想在本机装 Python 依赖？用 Docker。仓库根 docker-compose.yml 定义了本地全栈，关键是它用 APP_ENV 把容器和 L04 的配置系统打通了：

    environment:
      # APP_ENV 决定读哪个 yaml profile：dev → configs/dev.yaml，prod → configs/prod.yaml
      APP_ENV: ${APP_ENV:-dev}
      ENABLED_AGENTS: sre-rca,risk-reviewer,alert-triage,doc-checker,biz-link-gov,...

• APP_ENV: ${APP_ENV:-dev}：compose 把宿主机的 APP_ENV 透传进容器，没设就默认 dev。于是APP_ENV=prod docker compose up 就切成生产配置——同一个镜像，靠环境变量切 profile，正好复用 L04/L06 那套 ${VAR} 展开。
• ENABLED_AGENTS 这里写死了一长串 agent 名，对应 L07 的注册表 key。
• docker-compose.yml:33-48 还把 DB_PASSWORD、ANTHROPIC_API_KEY 等 secret 用 ${VAR:-} 透传——呼应 L06："secret 只走环境变量，不进镜像"。

✋ 动手

# 1. 装好全仓（需先装 uv）
uv sync --all-extras --all-packages

# 2. 跑全套测试，感受"几秒跑完、不联网"
uv run pytest -q

# 3. 亲手读今天的核心源码
sed -n '255,267p' packages/ai-trust-toolkit/src/ai_trust_toolkit/config.py   # _deep_merge
sed -n '290,339p' packages/ai-trust-toolkit/src/ai_trust_toolkit/config.py   # load_config

# 4. 对比 base 与 dev 的 database 段，验证 L05 的合并例子
sed -n '7,16p'  configs/base.yaml
sed -n '4,12p'  configs/dev.yaml

# 5.（有 key 的话）起服务、开浏览器
ENABLED_AGENTS=doc-checker uv run uvicorn gov_agents_server.main:app --port 8080