治理：守正之美，给自主性装上闸

08.1治理导论：自主性的成本是乘法

端到端成功率 = 每步可靠性的连乘，不是相加；治理就是把 checkpoint 重新插回这条乘法链，给误差封顶。

底层机制（比"模型会犯错"深一层）：Anthropic 明说"agentic 系统常用延迟和成本换更好的任务表现""agent 的自主性意味着更高成本，以及复合误差的风险"。把它算成数字：99% 准确率的步骤连跑 10 步，端到端是 0.99^10 ≈ 90%；20 步 ≈ 0.99^20 ≈ 82%；一条 95%/步的 5 步链只剩 0.95^5 ≈ 77%。两股力让它随时间更糟。其一，误差在抵达下一个 checkpoint 前是沉默的。其二，Anthropic 实测无人打断的单轮时长在一个季度内几乎翻倍（约 25→45 分钟，2025-10 至 2026-01），未设 checkpoint 的窗口——复合悄悄发生的那段——正在变长。每加一道治理控制都会花掉一些自主性、规模或延迟，所以工程动作是按用例在那条曲线上选点，而不是把自主性最大化。

# 复合误差：端到端成功率是每步可靠性的连乘，不是平均
def end_to_end_success(per_step_reliability, n_steps):
    return per_step_reliability ** n_steps          # 乘法，不是加法

assert round(end_to_end_success(0.99, 10), 2) == 0.90   # 99%/步 × 10 步 ≈ 90%
assert round(end_to_end_success(0.99, 20), 2) == 0.82   # 20 步 ≈ 82%
assert round(end_to_end_success(0.95,  5), 2) == 0.77   # 95%/步 × 5 步  ≈ 77%

# 推论：自主长度是首要风险变量，不是单步质量。
# 治理 = 在链上插 checkpoint，给「沉默累积的误差」封顶——
# checkpoint 越靠后，能在它之前积累的 error 越多（无人打断的单轮 ~25→45 min）。

08.2审批门：可持久暂停 = 两阶段提交

审批门是一次可持久暂停：agent 在不可逆动作前 interrupt，把全量状态落盘交还调用方，人/策略批准后 resume 注入决策、继续同一次运行。

底层机制（比"暂停一下"深一层）：框架命中 interrupt()（LangGraph）或把待执行的工具调用浮现成一个 interruption（OpenAI Agents SDK），通过 checkpointer 把全量 agent 状态序列化、交还调用方；这个暂停是持久的——进程重启都活得下来，因为状态已落盘。人/策略批准后，Command(resume=...) 或 state.approve() 把决策注入、继续同一次运行。这正是两阶段提交（2PC）：把 agent 当事务协调者而非 oracle——Phase 1（prepare）暂存一个可逆改动并校验不变式，人工 interrupt 就是 prepare→commit 的屏障，Phase 2 提交或回滚，全程带审计轨迹。低一层的陷阱：resume 时 LangGraph 会从顶部重跑整个 node，不是从 interrupt() 的下一行续。所以放在 interrupt 之前的任何副作用（写库、发邮件、扣款）会触发两次。

过度设闸为什么是真实的失败模式：审批门花掉的是延迟（人的周转）和过度设闸的诱惑。Anthropic 给出了一个可测量的理由——当 Claude Code 对每个动作都询问时，用户批准了约 93% 的提示，也就是橡皮图章：它提供了治理表演，却没有真实复核；同期改用 sandbox 把提示量砍掉约 84% 反而提升了安全。所以只对不可逆、高爆炸半径的动作设闸，把人的注意力省给可逆性救不回来的地方。

# LangGraph 风格审批门 = 两阶段提交。resume 会重跑整个 node，
# 所以 interrupt() 之前不能有任何副作用。
from langgraph.types import interrupt, Command

def sensitive_node(state):
    # Phase 1 prepare：只暂存 + 校验，绝不写真实副作用
    plan = stage_change(state.action)           # 可逆暂存
    preview = plan.dry_run()                     # 预演 diff，无副作用

    # ---- 屏障：interrupt() 落盘全量状态，交还调用方 ----
    # 此行之前不得有 DB 写 / 发邮件 / 扣款——node 会从顶部重跑。
    decision = interrupt({"action": state.action,
                          "preview": preview,
                          "blast_radius": estimate_blast_radius(plan)})
    if decision["reject"]:
        return {"status": "aborted"}             # 回滚：暂存从未提交

    # Phase 2 commit：唯一不可逆动作，挂幂等键防重放双写
    result = plan.commit(idempotency_key=state.run_id)   # >= 一次安全
    return {"status": "committed", "result": result}

# resume:  app -> graph.invoke(Command(resume={"reject": False}), thread)
#          → sensitive_node 整体重跑；stage/dry_run 再做一遍（无副作用），
#            commit 因幂等键命中而 no-op，不会二次扣款。

08.3爆炸半径：sandbox 收环境，least agency 收能力

爆炸半径 = 一次坏动作能触达的最大破坏，由 agent 能碰到的一切的并集决定；两把正交的剪刀分别收窄环境与能力。

底层机制（比"加沙箱"深一层）：两把正交的剪刀。其一，sandbox 收环境——Anthropic 的三层隔离从轻到重：claude.ai 用临时的 gVisor 容器，Claude Code 用 OS 系统调用沙箱（Seatbelt / bubblewrap），Cowork 用密封 VM 带 read-only / read-write / read-write-no-delete 三种挂载模式，凭据留在宿主 keychain、绝不进入 guest。Anthropic 用血换来的教训是"你自己造的软件往往是最弱的一环"——标准 hypervisor / 系统调用过滤器胜过自制的 allowlist 代理。其二，least privilege + least agency 收能力——把每个工具收窄到任务所需的确切资源，默认只读，签发短时、按任务收窄的凭据。least agency 比 least privilege 更进一步：不只限制能触达什么资源，而是限制能表达什么动作——暴露一个参数化查询接口而非裸 SQL、一个固定 schema 的 MCP 工具而非 shell，让 agent "能完成这份工作，却无法悄悄扩大这份工作"。

08.4渐进承诺：把信任做成单调阶梯

用一道单调阶梯替换二元信任决策：read-only（洞察）→ recommend-and-wait（辅助）→ act-within-guardrails（自主），信任按履历逐级挣得，不可跳级。

底层机制（比"分级授权"深一层）：三个机制叠起来。其一，read-then-write 默认——先观察读行为是否可预测，再加写权限。其二，dry-run / preview-then-commit——算出动作的 diff/plan 却不施加（借自 terraform plan/apply、rsync --dry-run），人/检查批准预览后，再把同一份 plan 提交，让不可逆操作在开火前可被检视。其三，挣来的晋升——一个运行时授权平面（ABAC/RBAC + 审批阈值）输出 ALLOW / MASK / DENY / REQUIRE_APPROVAL，信任层级从运行历史里晋升，而非一上来就授予。低一层的失败模式：信任持久化（trust persistence）——一个工具/路径一旦被批准，这份授权常常活得比当初证成它的上下文更久，而一个跑过 100 次成功的 agent 又常被当作和全新 agent 完全一样处理。没有降级机制，渐进承诺就悄悄退化成一揽子承诺（blanket commitment）。

08.5可观测性：拒绝黑盒，让运行可回放

可观测性把非确定的黑盒变成可审计、可回放的工件：每次 LLM 调用、工具调用、推理步都落成结构化 span，事后能重放复现。

底层机制（比"加日志"深一层）：底座是结构化 tracing——每次 LLM 调用、工具调用、推理步都是一个 span。OpenTelemetry GenAI semantic conventions 把 span 的形状标准化、让 trace 厂商中立：gen_ai.operation.name（取值含 chat / invoke_agent / execute_tool / create_agent / embeddings）、gen_ai.agent.name、gen_ai.tool.name、用 gen_ai.conversation.id 把多轮会话缝起来、gen_ai.usage.input_tokens/output_tokens 算成本，以及选择性开启的内容捕获（gen_ai.input.messages / gen_ai.output.messages）——因为 prompt/输出含 PII 且存储昂贵，所以默认关闭。Span 名形如 invoke_agent {name}、execute_tool {name}。trace 之上坐着 eval（用 LLM-as-judge / code / 多轮评估器给真实生产 trace打分，而不只是离线测试集）和 replay（重跑一条捕获的 trace 以确定性复现故障）。这正好闭合治理回路。

# 用 OTel GenAI semconv 把每步落成 span；trace 之上跑 eval + replay
with tracer.start_span("invoke_agent", attrs={
        "gen_ai.operation.name": "invoke_agent",
        "gen_ai.agent.name":     agent.name,
        "gen_ai.conversation.id": session_id}):     # 缝多轮会话
    action = agent.propose()                         # L36：单步，误差跨步连乘

    with tracer.start_span("execute_tool", attrs={
            "gen_ai.operation.name": "execute_tool",
            "gen_ai.tool.name":      tool.name,
            "gen_ai.usage.input_tokens":  in_tok,    # 算成本
            "gen_ai.usage.output_tokens": out_tok}):
        result = tool.commit(action.args)            # 仅在审批后（L37）

    # 内容捕获默认关闭：含 PII + 存储贵，按需 opt-in 并做脱敏/采样
    if CAPTURE_CONTENT:
        span.set_attribute("gen_ai.input.messages",  redact(messages))
        span.set_attribute("gen_ai.output.messages", redact(result))

emit_eval(trace=current_trace(), judge=llm_as_judge)   # L40：给真实生产 trace 打分
# replay：re-run 这条 trace 即可确定性复现故障，反哺 L38/L39 的护栏与 eval。