先破一个最容易踩的误解——项目名叫 gov-agents-platform，但它跟"政务/政府"没有半点关系。这里的 gov 是 governance（治理）的缩写，意思是"给 AI Agent 上护栏、做可信工程化"。

不用听我下定义，直接看核心包的自我介绍。打开 packages/ai-trust-toolkit/pyproject.toml 最上面几行：

[project]
name = "ai-trust-toolkit"
version = "0.6.0"
description = "AI-Trust Engineering Toolkit — Critic, Failsafe, Eval, Memory Protocol for LangGraph Agents"
readme = "README.md"
license = {text = "Apache-2.0"}
requires-python = ">=3.10"
authors = [
    {name = "SRE Architecture Team"},
]
keywords = ["langgraph", "agent", "ai-safety", "critic", "evaluation", "rca"]

• description 那行是全仓最诚实的一句话定义：它是一套给 LangGraph Agent 用的"可信工程"工具箱 —— Critic（防幻觉）、Failsafe（失败闸门）、Eval（评测）、Memory（记忆）。这四个词就是 Day 06–11 的主线。
• keywords 里 ai-safety / critic / rca 揭示了它的出身：这套东西是 SRE（故障根因 RCA）场景打磨出来的护栏，后来抽成通用底座。
• version = "0.6.0" —— 记住这个号，等下 L09 你会看到 README.md 里还写着 v0.5.0，两个数字对不上，这不是笔误，是"文档漂移"，今天会专门讲怎么应对。

一句话给它下定义：

所以这个仓库本质上是四大块拼起来的：

想象一下：团队里每个人都在写自己的 AI Agent。如果没有统一框架，会发生什么？大模型会一本正经地编造不存在的证据（业界叫"幻觉"），某个工具接口挂了整个 Agent 就崩，没人知道这个 Agent 靠不靠谱、这个月烧了多少钱……于是每个人都得自己写一遍"防幻觉、防崩溃、评测、算钱"的代码。

这个框架就是把这些横切关注点抽出来做成公共能力：

后面几天会反复出现这些词，今天先混个脸熟，不用记住细节：

先给你看一个"文档 vs 教程"的诚实对照。仓库 README.md:24 的小标题就叫 「三层分层」——它只官方承认 3 层：

┌─────────────────────────────────────────────┐
│ L3 业务实现层 · apps/sre-rca-agent/         │  每个 Agent 写 State/Specialists/Prompts
├─────────────────────────────────────────────┤
│ L2 应用脚手架层                             │  langgraph-supervisor(pip) + ai-trust-toolkit⭐(自研)
├─────────────────────────────────────────────┤
│ L1 框架/Runtime 层 · langchain-ai/langgraph │  (pip 依赖)
└─────────────────────────────────────────────┘

那为什么我们的教程要画成 5 层？因为源码里还有两块东西不属于这 3 层、但你迟早要碰：gov-agents-portal/（研发门户）和 skills/（给 IDE AI 用的一句话 SOP）。AGENTS.md:119-130 的分层表就把它们补上了——多出 L2.5 DevX 和 L4 工具生态。所以"5 层"是我们为了讲清楚、在源码 3 层骨架上加的两层"标注"，不是我编的。

下图里那颗发光的小球，代表一次真实请求"从上往下穿过每一层"。你现在只需要建立一个直觉：越往下越通用、越稳定（很少改）；越往上越贴业务、越常改。

L1 · 框架 / Runtime 层

大白话：Agent 的"操作系统"。真正负责"跑流程图、管状态、按顺序执行节点"的底层引擎。

关键点：这一层全是外部开源库，本仓库一行都不改，通过 uv/pip 装进来。别只信我说——直接看 toolkit 的依赖清单：

dependencies = [
    # 仅依赖 langgraph runtime 本身，不依赖 supervisor-py
    # 这是核心解耦原则
    "langgraph>=0.2.0",
    "langchain-core>=0.3.0",
    "pydantic>=2.0",

• 第 2-3 行的注释是作者亲手写下的设计承诺："仅依赖 langgraph runtime 本身，不依赖 supervisor-py"。也就是说 L1 只有 langgraph 引擎 + langchain-core 的基础类型。
• langgraph>=0.2.0 就是 L1。toolkit 把它当地基用，但从不改它的源码——升级它只需要 uv lock --upgrade-package langgraph。
• pydantic>=2.0 用来做数据校验（后面 config、envelope 全靠它），不是 Agent 引擎，属于工具依赖。

L2 · 应用脚手架层 ⭐（框架的灵魂）

大白话：一组"横切的护栏能力"，让任何业务 Agent 开箱即有防幻觉/闸门/评测/记忆/成本治理。这就是 packages/ai-trust-toolkit/，是本教程 Day 06–11 的主战场。它内部的模块划分不是我编的，是 ls 出来的真实目录：

critic/    failsafe/   eval/     memory/     specialists/
cost/      api/        tools/    testing/    reporter/    sensitivity/
config.py  llm.py      effect.py  observability.py  handoff.py  portal_telemetry.py

这一层还包含 3 个"运行载体"包：gov-agents-server（多 agent 同进程 host）、gov-agents-cli（命令行 agentctl）、gov-agents-mcp（把 agent 暴露给 IDE）。Day 12–13 细讲。

L3 · 业务实现层

大白话：每个具体 Agent 自己写的业务代码，在 apps/<agent>/。规矩写死在 AGENTS.md:121——L3 只写四样东西：

L3 业务   apps/   ← 每个 Agent 只写：State / Specialists / Prompts / DAG

护栏能力全部从 L2 import 进来，不重复实现。Day 03 讲清 State/DAG 是什么，Day 05 拆解结构，Day 14 逐文件精读旗舰 Agent sre-rca。

L2.5 · 研发体验层 (DevX)  +  L4 · 工具生态层

这两层是后来补上的，AGENTS.md:120-122 明确了它们各自"只服务谁"：

• L2.5 = gov-agents-portal/：脚手架 CLI + Web Wizard + 开发工具，AGENTS.md:138 硬性规定"SHALL 只服务 R&D 工程师"，目标"写新 agent 快 10×"。Day 16 讲。
• L4 = skills/：给 IDE 里的 AI（Claude Code / Cursor）用的 SOP——你说一句人话"帮我审下这个 PR 的上线风险"，它就自动去调对应的 agent。Day 19 讲。

这是整个框架最重要的一条约束。它不是口号，而是写进了两个文件、措辞几乎一样——先看 README.md：

**关键约束**：
1. ai-trust-toolkit **不依赖** supervisor-py（toolkit 是 supervisor 之下的横切能力）
2. ai-trust-toolkit **只依赖** langgraph runtime 自身（State / Node / Edge / Reducer）
3. 业务 app 同时依赖 supervisor + toolkit + langgraph

再看 AGENTS.md 给新人/AI 的"铁律"版本，说得更狠：

**铁律**：
1. L2 不许 import L3 —— toolkit 不知道业务域存在
2. L3 不许重复实现 toolkit 已有的能力 —— 缺什么先去 toolkit 抽
3. 跨 L3 复用走 toolkit，**不许** apps 互相 import
4. L4 单向向下：skills/ 调 MCP tools / agentctl / OpenAPI · L1-L3 不许 import skills/

• 铁律 1（L2 不许 import L3）：翻译成大白话——底座不许知道有哪些业务。toolkit 里你永远不会看到 import sre_rca。因为一旦底座认识了某个业务，它就不通用了。
• 铁律 3（apps 不许互相 import）：apps/A 不许 import apps/B。两个业务要复用一段逻辑，唯一合法路径是"下沉到 toolkit，再各自 import 底座"。
• 铁律 4（skills 单向向下）：L4 只能调下面的东西，下面 L1-L3 绝不能反过来 import skills/。方向永远朝下。

把这几条画成一张"谁能指向谁"的依赖 DAG（有向无环图），你就永远不会记反：

打开仓库根目录，你会看到这些文件夹。先建立"哪个文件夹装什么"的地图，后面就知道去哪找：

gov-agents-platform/
├── apps/                 ★ L3 业务 Agent，每个一个独立包（实测 21 个）
├── packages/             ★ L2 toolkit + starter 包 + server/cli/mcp
│   ├── ai-trust-toolkit/       ⭐⭐ 可信底座，全仓灵魂
│   ├── ai-trust-toolkit-bom/   依赖版本清单（Bill of Materials）
│   ├── ai-trust-toolkit-starter-*  各类 agent 的"快速起手包"
│   ├── gov-agents-server/      多 agent 同进程 HTTP 服务
│   ├── gov-agents-cli/         命令行 agentctl
│   └── gov-agents-mcp/         把 agent 暴露给 IDE 的 MCP
├── gov-agents-portal/    L2.5 Web 管理门户（Next.js 前端 + FastAPI 后端）
├── skills/               L4 给 IDE AI 用的一句话 SOP
├── openspec/             规格驱动开发的契约（Day 20 讲）
├── configs/              分环境 YAML：base/dev/staging/prod/test（Day 02 讲）
├── deploy/               K8s 部署清单 + Grafana 面板
├── scripts/              运维/CI 脚本（ci/ canary/ infra/）
├── docs/                 平台文档 40+ 篇（含 learn-langgraph 入门 demo）
├── examples/             独立仓 agent 脚手架模板
├── Dockerfile            一个镜像 + ENABLED_AGENTS 跑任意 agent 组合
├── docker-compose.yml    本地全栈（redis + platform）
├── pyproject.toml        ⭐ uv workspace 根：把所有包串成一个整体
├── README.md             总说明
└── AGENTS.md             ⭐ 给新人/AI 的 30 秒 ramp-up 指南

"把所有包串成一个整体"这句话，落地就是根 pyproject.toml 里的 [tool.uv.workspace]。这是一张真实的清单——数一下有 31 个成员：

[tool.uv.workspace]
members = [
    "packages/ai-trust-toolkit",          # ← L2 灵魂
    "packages/gov-agents-server",         # ← 运行时
    "packages/gov-agents-cli",
    "apps/sre-rca-agent",                 # ← L3 旗舰
    "apps/risk-reviewer",
    # … 一直到 apps/supervisor-router-agent，共 31 条
    "gov-agents-portal/backend",          # ← 连门户后端也进了 workspace
]

[tool.uv.sources]
ai-trust-toolkit = { workspace = true }   # ← 关键！从本地 workspace 取，不去 PyPI 下载
gov-agents-mcp   = { workspace = true }

• members 列出了要被"当成一个大项目一起装"的所有子包。Day 02 会讲，一条 uv sync --all-packages 就把这 31 个包全部以 editable（可编辑）方式装好。
• [tool.uv.sources] 里 ai-trust-toolkit = { workspace = true } 是画龙点睛：它告诉 uv"当某个 app 声明依赖 ai-trust-toolkit 时，用本地这份源码，而不是去 PyPI 下载同名包"。这就是为什么你改一行 toolkit 源码，21 个 app 立刻用上新代码。

不用现在全懂，先知道"这个项目用了什么"。下表右列不是我编的，都能在 packages/ai-trust-toolkit/pyproject.toml:24-56 那段 dependencies 里逐行找到：

读这份代码的三条主线

✋ 动手 5 分钟（可选，但强烈建议）

如果你手边能打开这个仓库，跟着敲一遍——把"地图"落到真实文件上，顺便亲手验证今天引用的每一处：

# 1. 看核心包的自我介绍（对照 L01 的 description）
grep -A3 "name = \"ai-trust-toolkit\"" packages/ai-trust-toolkit/pyproject.toml

# 2. 亲眼确认"toolkit 只依赖 langgraph 不依赖 supervisor"（对照 L05）
sed -n '24,29p' packages/ai-trust-toolkit/pyproject.toml

# 3. 读依赖铁律（对照 L06）
sed -n '124,137p' AGENTS.md

# 4. 数一数到底有几个业务 Agent（验证"文档漂移"）
ls apps/ | wc -l          # 你会看到 21，而不是 README 说的 9

# 5. 看 workspace 把哪些包串在了一起（对照 L07）
grep -A 40 "tool.uv.workspace" pyproject.toml