packages/gov-agents-server 是平台主进程——一个 FastAPI 服务。它自己没有任何业务逻辑，只干四件事：

• 维护一张"哪个 agent 名对应哪个模块"的注册表；
• 按 ENABLED_AGENTS 环境变量，懒加载并挂载对应 agent 的路由；
• 提供首页、健康检查、静态资源（skills 目录、安装脚本）；
• 统一接可观测性。

主文件 gov_agents_server/main.py（约 1021 行）。它是 Day 02 "启动平台"那条命令 uvicorn gov_agents_server.main:app 背后的东西。

平台的核心部署理念（写在 Dockerfile 开头）：构建一个镜像，靠 ENABLED_AGENTS 环境变量决定这个实例跑哪些 agent。

好处：同一个制品在不同环境按需组合，SRE 相关的部一台、质量相关的部一台，互不干扰又共用一份代码。这套逻辑就一个小函数 _parse_enabled（main.py:289）：

# main.py:289
def _parse_enabled(raw: str | None) -> list[str]:
    if not raw or not raw.strip():
        return list(AGENT_REGISTRY)                 # 不设 ENABLED_AGENTS → 挂全部
    names = [a.strip() for a in raw.split(",") if a.strip()]
    unknown = [n for n in names if n not in AGENT_REGISTRY]
    if unknown:                                     # 写了名册上没有的名字
        raise RuntimeError(f"未知 agent: {unknown!r}。合法值: {sorted(AGENT_REGISTRY)}")
    return names

server 怎么知道有哪些 agent？靠 main.py:62-81 一张写死的字典——{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"),
    # ... 共 18 条
}

启动时按名字用 importlib.import_module 懒加载对应模块，取出它的 build_router 函数。看真实的 _load_router（main.py:299），它有三条调用约定：

# main.py:299
def _load_router(name, *, case_store=None, pool=None, app=None) -> APIRouter:
    import inspect as _inspect
    mod_path, fn_name = AGENT_REGISTRY[name]         # 查名册拿到("sre_rca.server","build_router")
    mod = importlib.import_module(mod_path)          # 懒加载:用到才 import(启动更快)
    fn = getattr(mod, fn_name)
    if name in AGENTS_NEED_POOL:                     # 约定①:需要 DB 池的 agent
        if pool is None:
            raise RuntimeError(f"Agent '{name}' requires a database pool but none was provided.")
        return fn(pool)                              #   → 位置传 pool
    kwargs = {"case_store": case_store}              # 约定②:普通 agent → 关键字传 case_store
    try:
        sig = _inspect.signature(fn)                 # 约定③:探测 build_router 签名
        if "app" in sig.parameters and app is not None:
            kwargs["app"] = app                      #   含 app 参数就注入 FastAPI 实例
    except (ValueError, TypeError):
        pass                                         #   拿不到签名(罕见)→ 退化为不传
    return fn(**kwargs)

三条约定用一张表看更清楚：

create_app()（main.py:375）是平台工厂。模块底部 app = create_app()（main.py:1021）就是 uvicorn 直接 import 的实例。启动做这些：

第 4 步的"韧性"最值得看真代码。lifespan 里给 pool 类 agent（arch-compliance）建 MySQL 连接池，注意它被 try/except 整个包住（main.py:400）：

# main.py:400  lifespan 内建 aiomysql 连接池
pool: aiomysql.Pool | None = None
if needs_pool:
    db = _cfg.database.arch_compliance
    if db is None:
        log.error("configs/<APP_ENV>.yaml 缺 database.arch_compliance 配置 · 跳过 pool agents")
    else:
        try:
            pool = await aiomysql.create_pool(host=db.host, port=db.port, ..., minsize=2, maxsize=10)
        except Exception as e:
            log.warning("aiomysql pool 创建失败(%s: %s)· 跳过 pool agents · 平台其他 agent 正常",
                        type(e).__name__, e)          # ← 降级:不 raise!
            pool = None
    if pool is not None:
        for name in needs_pool:
            app.include_router(_load_router(name, pool=pool))   # 有池才挂业务路由

这是全平台覆盖率最高、最该理解的抽象。每个 agent 的 server.py 里的 build_router，核心就是调 toolkit 的 build_v1_router()（api/router.py:261）。业务只写一个 _invoke 函数，其余全自动：

# apps/sre-rca-agent/sre_rca/server.py:66
def build_router(case_store=None):
    router = APIRouter(tags=["sre-rca"])
    graph = build_rca_graph()                    # 你的 LangGraph 图
    store = case_store or make_case_store_from_env()

    async def _invoke(body, ctx, tracker) -> AgentOutcome:
        # ↑ 你只写这个：校验入参 → 跑图 → 包成结果
        with anthropic_key_override(ctx.anthropic_api_key):
            result = await graph.ainvoke(initial, config)
        return AgentOutcome(...)

    router.include_router(build_v1_router(         # ← 一行装齐下面全部
        agent_name="rca", invoke_fn=_invoke,
        stream_fn=_stream, case_store=store))
    return router

这一行 build_v1_router 自动给这个 agent 挂上标准端点：

把前面所有天串起来——一次 POST /v1/agent/rca/invoke 进来，_do_invoke（router.py:318）按顺序过这条链。开头这几行就是治理三闸 + 建账（前面的日子学的东西全在这里汇合）：

# api/router.py:325  _do_invoke 开头
await get_rate_limiter().check_or_raise(ctx.user_id)   # ① 限频:超额抛 429(不计 case/cost)
await check_quota(user_id=ctx.user_id)                 # ② token 配额:查上次累计(不含本次)
await check_budget(tenant_id=ctx.tenant_id)            # ③ 租户月度 USD cap:超 → 429
case_id = new_case_id()                                # ④ 生成 26 字符 ULID
...
tracker = CostTracker(agent=agent_name, user_id=ctx.user_id, tenant_id=ctx.tenant_id)
try:
    with bind_tracker(tracker):                        # ⑤ 绑记账器(Day 11 ContextVar)
        outcome = await invoke_fn(body, ctx, tracker)  # ⑥ 执行你写的 _invoke(跑图)
    metrics = tracker.finalize(status=outcome.status, retry_count=outcome.retry_count)  # 抄表
    envelope = _build_envelope(agent=agent_name, case_id=case_id, outcome=outcome, ...)  # ⑦ 装信封
    await _persist_case(..., envelope=envelope, sensitive_fields=sensitive)              # ⑧ 脱敏落库
    await record_quota_usage(...); await record_budget_cost(...)                          # 回写用量
    return envelope

统一 envelope（api/envelope.py:63）

所有 agent 返回的外壳完全一致（Day 02 见过），这是真实定义：

# api/envelope.py:22
InvokeStatus = Literal["success", "critic_end", "failed"]

# api/envelope.py:63
class InvokeResponse(BaseModel):
    model_config = ConfigDict(extra="forbid")   # 多一个字段都报错(严格)
    case_id: str                                 # 26 字符 ULID(带校验)
    agent: str
    status: InvokeStatus                         # success / critic_end / failed
    result: dict[str, Any]                       # agent 的业务字段装这
    metrics: Metrics                             # 平台维度量度(见下)
    trace_id: str
    deprecated_path: str | None = None           # 走老路径时的提示

    @field_validator("case_id")                  # api/envelope.py:81
    @classmethod
    def _check_case_id_format(cls, v: str) -> str:
        if len(v) != 26:                         # ULID 必须 26 字符,否则拒绝
            raise ValueError(f"case_id 必须 26 char ULID,当前 {len(v)} char: {v!r}")
        return v

metrics 里的字段名要记准（envelope.py:40），别写成简写：

# api/envelope.py:40
class Metrics(BaseModel):
    elapsed_ms: int = 0            # 耗时毫秒
    llm_tokens_in: int = 0        # 输入 token（不是 tokens_in！）
    llm_tokens_out: int = 0       # 输出 token
    cache_creation_tokens: int = 0; cache_read_tokens: int = 0   # v0.6+ prompt caching
    estimated_cost_usd: float = 0.0                              # 预估花费 USD
    retry_count: int = 0
    budget_exceeded_scope: str | None = None                    # 硬熔断时填 per_invoke/per_node

鉴权 header 契约（api/auth.py）

请求通过几个 header 传身份，被封装成 CallContext（auth.py:46）传给业务：

# api/auth.py:46
@dataclass
class CallContext:
    user_id: str
    tenant_id: str
    trace_id: str
    trust_level: TrustLevel               # "high" | "low" | "anonymous"
    anthropic_api_key: str | None = None  # 来自 X-Anthropic-Api-Key · 用完即弃 · 不落库

三档鉴权模式 PLATFORM_AUTH_MODE（auth.py:32）：open（默认，缺 X-User-Id 自动匿名）/ header（灰度过渡）/ strict（缺 X-User-Id 直接 401）。

✋ 动手

# 1. 读注册表和三条调用约定
sed -n '62,81p' packages/gov-agents-server/src/gov_agents_server/main.py
sed -n '299,331p' packages/gov-agents-server/src/gov_agents_server/main.py

# 2. 读一个 agent 的 build_router 怎么用 build_v1_router
sed -n '66,125p' apps/sre-rca-agent/sre_rca/server.py

# 3. 读 v1 路由工厂 + 一次 invoke 的治理链
sed -n '261,340p' packages/ai-trust-toolkit/src/ai_trust_toolkit/api/router.py

# 4. 读统一 envelope
sed -n '40,95p' packages/ai-trust-toolkit/src/ai_trust_toolkit/api/envelope.py

# 5. 起服务看首页和自我说明书
# curl localhost:8080/api ; curl localhost:8080/agents/rca/graph