packages/ai-trust-toolkit（版本 0.6.0，见 __init__.py:31 的 __version__）是本仓自研的核心库。它不是"某个 agent 的代码"，而是所有 agent 都能用的横切能力——防幻觉、闸门、评测、记忆、成本治理。

回忆 Day 05 的"薄业务 + 厚 toolkit"：一个业务 agent（如 sre-rca）真正自己写的代码可能就几百行，剩下的"可信/可观测/成本/记忆"全是从这个库 import 来的。所以吃透了 toolkit，你就吃透了整个平台。

另外还有几个"横切基础件"：config.py（Day 02 讲过的配置加载）、observability.py（可观测，Day 11）、handoff.py（Day 04 讲过）、effect.py（业务效果指标，下一讲就拆它）。

打开 ai_trust_toolkit/__init__.py，第一眼会觉得奇怪——一个这么大的库，顶层只导出了 5 个符号（__init__.py:34-49）：

__version__ = "0.6.0"                                       # __init__.py:31
# handoff 协议给 agent 端 import
from ai_trust_toolkit.handoff import HandoffSignal, new_chain_id      # :34
# 领域效果采集给 agent 端 import
from ai_trust_toolkit.effect import (                                 # :37
    bind_effect, current_effect, record_effect)
__all__ = [
    "HandoffSignal", "new_chain_id",
    "bind_effect", "current_effect", "record_effect",                 # :43-48
]

逐行读：__version__ 是全库版本；然后只 re-export 了 handoff（Day 04 学过的交接信号）和 effect（下一讲）两组东西。critic / memory / api / failsafe……顶层一个都没导出——它们全都要从子包按需 import。

而 __init__.py 开头那段 docstring（:1-27）反倒成了这个库最有用的东西——一张"API 地图"，把常用 import 路径全列了：

from ai_trust_toolkit.tools import safe_tool_result
from ai_trust_toolkit.failsafe import wrap_with_fallback, build_critic_router
from ai_trust_toolkit.critic import collect_valid_evidence_ids, build_critic_node
from ai_trust_toolkit.specialists import make_specialist_node, SpecialistConfig
from ai_trust_toolkit.eval import EvalSample, FiveDimScorer, run_eval
from ai_trust_toolkit.memory import VectorStore, PgVectorStore, InMemoryVectorStore
from ai_trust_toolkit.api import build_v1_router, CostTracker, check_or_raise
from ai_trust_toolkit.llm import set_llm_factory, get_llm
from ai_trust_toolkit.testing import FakeLLM, SystemAwareFake, install_fakes

先看它的"数据结构"——一个 task-local 的累加器（effect.py:29）：

# 当前 invoke 的 effect 累加器 · ContextVar task-local
_current_effect: contextvars.ContextVar[dict[str, float] | None] = \
    contextvars.ContextVar("ai_trust_current_effect", default=None)   # effect.py:29

它是一个 dict[str, float]（形如 {"upgraded": 3.0}），装在 ContextVar 里。默认是 None——即"当前没在采集"。再看两个用法函数：

@contextmanager
def bind_effect() -> Iterator[dict[str, float]]:              # effect.py:40
    acc: dict[str, float] = {}
    token = _current_effect.set(acc)     # 进入 with：把累加器塞进 ContextVar
    try:
        yield acc
    finally:
        _current_effect.reset(token)     # 退出 with：还原（防污染下一次 invoke）

def record_effect(key: str, n: float = 1) -> None:           # effect.py:50
    acc = _current_effect.get()
    if acc is None:
        return                           # AC-1.4 · 没 bind → 静默 no-op，不抛！
    if not isinstance(key, str) or not key:
        log.debug("record_effect ignored · invalid key: %r", key)
        return
    try:
        acc[key] = acc.get(key, 0.0) + float(n)   # 累加
    except (TypeError, ValueError):
        log.debug("record_effect ignored · non-numeric n: %r", n)

逐块讲：bind_effect() 是个上下文管理器，平台在一次 invoke 的边界用 with bind_effect(): 包住——进入时把一个空 dict 塞进 ContextVar，退出时 reset 还原。record_effect("upgraded", 1) 是业务在"真办成一件事"的那一行调用——它从 ContextVar 拿累加器，累加计数。invoke 结束时平台自动把这个 dict 收进响应的 metrics。业务只需一行 record_effect(...)，完全不用管"怎么上报、往哪存"。

Day 01 讲了"层与层之间"的依赖铁律。toolkit 内部模块之间也有一套依赖规则，保证它自己不会变成一团乱麻：

刚读的 effect.py 就是标准的"叶子"——它只 import 标准库 contextvars/logging，一个 toolkit 内部模块都不碰。这就是为什么它能被顶层 __init__ 安全 re-export（L03 设计取舍②）。另外还有几条"红线"：

• sensitivity/ 敏感度分类模块绝不 import anthropic / langchain——它必须极轻、无外部依赖（纯规则）。
• 许多函数刻意"没有依赖时静默降级"：record_effect 没 bind 静默 no-op（刚读过）、budget_gate 没 tracker 静默放行、get_llm 遇到不支持缓存参数的 FakeLLM 自动退化——都是为了让测试和独立调用不崩。

这是整个项目最核心的工程思想，CHANGELOG 的"关键工程经验"章节（CHANGELOG.md §关键工程经验）开门见山：

CHANGELOG 里把它写成了三行阶梯：

1 个 Agent 就抽 toolkit  → 接口不准（无第二样本）
2 个 Agent 出现重复才抽  → 接口刚好准
3+ 个 Agent 持续验证      → 抽象趋于稳定

意思是：不要在只有一个用例时就急着设计"通用框架"。等到第二个、第三个 agent 出现真实重复，你才真正知道哪些该抽、抽成什么样。过早抽象往往抽错，反而成为负担。

docs/CHANGELOG.md 完整记录了每一次抽象的"何时抽、为什么抽、为什么之前不抽"。我们读它记载的三次真实决策——注意它们不是照搬一条死规则，而是每次都在算"抽的收益 vs 抽错的代价"。

除了"渐进抽象"，CHANGELOG 的"关键工程经验"还记了三条，条条有真实数据支撑：

① 可选 > 强加

CHANGELOG 有一张大表统计 toolkit 各模块在 9 个 agent 里的复用情况，结论是"60% 模块可选——业务按需取用，不强加结构"。比如 make_specialist_node 在 RCA(N=4)/risk-reviewer(N=2)/alert-triage(N=3) 用了，但 doc-checker（双 LLM 节点）、bmc-agent（无 SP 概念）就没用，框架也不逼它们用。唯一近 100% 覆盖的是 v0.5 的 build_v1_router（api 地基，人人要）。

② 声明式 > 命令式

真实收益：alert-triage 的 critic_l1.py 从 ~50 行命令式代码缩到 15 行声明式规则集。

③ 删除老代码要谨慎——留空壳 re-export

Day 05 见过的那个 DEPRECATED 的 _factory.py，CHANGELOG 专门解释了为什么不删、改成 17 行 re-export：

toolkit 内部按"谁来用"分成两大类，理解这个划分能帮你快速定位代码——也解释了 L03 为什么 handoff/effect（agent-facing 小件）能上顶层，而 api（重外壳）留在子包：

一句话：图内节点用左边，HTTP 外壳用右边。 分清这个，你就知道一段代码大概在解决"业务推理"还是"服务治理"的问题。Day 05 读的 make_specialist_node 是左边，build_v1_router 是右边。

✋ 动手

# 1. 看 toolkit 模块全貌
find packages/ai-trust-toolkit/src/ai_trust_toolkit -maxdepth 1 | sort

# 2. 读顶层门面：只导出 5 个符号 + 一张 API 地图 docstring
sed -n '1,49p' packages/ai-trust-toolkit/src/ai_trust_toolkit/__init__.py

# 3. 逐行读"零侵入采集"模块（今天的核心真源码）
cat packages/ai-trust-toolkit/src/ai_trust_toolkit/effect.py

# 4. 读三次真实抽象决策史（含"为什么之前不抽 / 为什么破例抽"）
sed -n '379,405p' docs/CHANGELOG.md      # v0.2 specialist 工厂
sed -n '352,376p' docs/CHANGELOG.md      # v0.3 只有 1 用户也抽
sed -n '587,637p' docs/CHANGELOG.md      # 关键工程经验四条