详细设计说明

把危险动作挡在执行前，把人工审批纳入状态机

这份文档把"治理"从一句口号还原成可执行的工程契约：风险如何分档，Policy 如何写规则，HITL 如何分级，AWAITING_HITL 如何持久化沙箱，Break-Glass 如何在不绕开审计的前提下加速，以及成本如何在 Run / User / Workspace / Skill 四维度收敛。

1. 定位与概念

1.1 总体架构图

下图把治理与 HITL 的三层职责和双守门员位置叠加在一张图上：横向 3 个 tier 带（T1 蓝 / T2 紫 / T3 金），T1 区画"审批策略配置 + 审批 UI"，T2 区画"Team 权限边界"，T3 区把 Harness 八步管道画成一条横向流水线，⑤ Policy 校验和 ⑦ HITL 审批用金色虚线边突出，下方画出风险三档分流。

1.2 双场景时序图

下面两张时序图分别可视化双守门员的两条典型决议链。点击顶部 lifeline 头部色块可跳到下面对应章节的详细规则。

1.3 为什么要做双守门员（不做的痛点）

当前缺口：

双守门员解决的具体技术问题：

1. Policy 处理"已知规则"——结构 / 权限 / 成本 / 安全四类规则，毫秒级裁决，承载 95% 流量
2. HITL 处理"边缘高风险"——剩余 5% 进人工审批队列，分钟到小时级，由审批人承担责任
3. 风险三档自动分流——Skill 元数据 + 动作属性两路输入，确定性输出 Low / Med / High，决策树不靠人
4. 沙箱与 AWAITING_HITL 绑定——审批期间 RunState 保留、上下文不丢、容器不回收，批准即续跑
5. Break-Glass 只缩短等待——身份、权限、Policy、Trace 一项不少；唯一的不同是审批通道从异步改实时
6. 成本四维聚合——Run / User / Workspace / Skill 都是 Policy 的拒绝依据，超限 → 自动降级或转 HITL L4

1.4 三层职责定位

2. 风险矩阵

2.1 决策树：不可逆 × 影响范围

2.2 三档穷举表

Low · 自动通过

Medium · 本人确认

M8 注解：技术隔离上沙箱挂载只能动 /data/users/<user_id>/workspace（详见 沙箱边界 §F ↗），不会越界。但用户私有空间内仍可能误删用户自己的代码 / 数据，所以走本人确认（L2）。HITL 文案必须带可判断信息：完整 path、子项数量、总大小、最近修改时间——避免审批疲劳让用户秒批。批量删除一次审批一次列表（含全部 path），不要拆成 N 次。

High · 审批人 / 双人

2.3 风险等级重写规则

管理员可对自动判定的风险等级进行升降级覆盖。重写记录写入治理审计表，不可物理删除。

2.4 新增 Action 类型评估流程

评估检查清单：

1. 确认动作的不可逆性（是否能 5 分钟内恢复原状）
2. 确认影响范围（个人沙箱 / 项目空间 / 生产环境 / 外部可见）
3. 确认是否涉及金额、权限变更、数据删除
4. 确认是否对外发出消息（邮件 / IM / 公告 / API）
5. 对应 Skill 等级是否匹配（L1 沙箱内 / L4 系统级）
6. 在风险矩阵表中注册并分配编号
7. 提交治理委员会评审通过

3. Policy 自动规则

3.1 评估输入与决议输出

Policy 引擎在 ⑤ Policy 校验步骤接收"Plan + CallerIdentity + 上下文"，按规则路由分发到四类引擎，最后统一输出三选一决议。

决议输出三选一：

3.2 四类规则

结构性规则 · 校验 Plan 自身的合法性，最先执行。

权限规则 · 基于 RBAC 矩阵和 Skill level 校验。

成本规则 · 在 Tool 执行前预扣，超限即拒。

安全护栏 · 拦截已知危险模式，独立于风险矩阵硬规则。

3.3 规则优先级与短路

四类规则按"结构性 → 安全护栏 → 权限 → 成本"顺序短路评估：任一类命中拒绝即直接返回 reject 决议，不再评估后续。这保证：结构非法不会被算成本浪费时间；安全一票否决永远第一线；成本规则放最后是因为它最有可能"升级到 HITL"而非"直接拒"。

每条命中的规则都会单独写入 PolicyTrace（rule_id / 决议 / 原因 / 用时），即使被短路也不丢。

4. HITL 四级审批

4.1 四级审批模型

升级链路只有一条：L2 超时 → L3；L3 超时 → L4；L4 超时 → 终态 CLOSED_REJECTED（不再无限升级）。

4.2 每层权限模型

4.3 超时升级链路

超时由独立的"看门狗"进程定时扫描 AWAITING_HITL 状态的 Run，命中阈值即推进升级或终态。看门狗每次检查都写一条 HITLTrace 记录"等待时长 / 当前级别"，便于事后分析瓶颈。

4.4 审批记录契约

所有审批记录通过 ⑧ Trace 通道写入审计表，仅追加、不可修改。审批 UI 的查询入口按 run_id / requester_id / reviewer_id / hitl_level / decision / 时间范围聚合检索。

5. AWAITING_HITL 持久化

5.1 状态机定位

AWAITING_HITL 是 11 个 RunState 中唯一可由外部唤醒的中间态。它的合法转移有三条出路：通过审批 → 回到 EXECUTING 续跑；拒绝 → 进 TRACING → CLOSED_REJECTED；超时 → 进 TRACING → CLOSED_REJECTED。状态机不允许 AWAITING_HITL 直接进 CLOSED_*，必须先经 ⑧ Trace。

5.2 三个不释放

5.3 续跑契约

批准回来时，HITL 控制器把审批记录附加到 caller_extra，向 T3 发"通行 + 审批人修改后的参数（如有）"信号。T3 按以下步骤恢复：

1. 核对 RunState 仍在 AWAITING_HITL（防止重复批准 / 已超时）
2. 如审批人改了参数，用 modified_action 替换 Plan 中对应 tool_call 的入参
3. 状态转移 AWAITING_HITL → EXECUTING
4. 沙箱拉起 idle 容器到工作态，直接进 ⑥ Tool 执行
5. Tool 执行完后正常进 ⑧ Trace，HITLTrace 链接到 PolicyTrace 形成完整决议链

5.4 超时与僵尸 Run

独立看门狗进程每分钟扫描所有 AWAITING_HITL 的 Run：到达终极超时阈值（L4 平台管理员 48 小时）→ 强制 TIMEOUT → 进 ⑧ Trace → CLOSED_REJECTED → 释放沙箱。事后告警通知 requester 与最后一级审批人。

对于"看门狗自身挂了"的情况，部署架构上看门狗是无状态的多实例 + 抢锁；MySQL 上有冗余的扫描查询作为兜底，最坏情况下一天内必然回收所有僵尸 Run。

6. Break-Glass · 紧急通道

6.1 三个不变量

6.2 触发条件与申请字段

6.3 与正常审批的差异点

正常 L4 走完整异步审批，等待时长 = 审批人 SLA（小时级）；Break-Glass 改为"申请即走，平台管理员有 5 分钟窗口可中止"。差异只发生在审批通道这一段，前后链路（鉴权 / Policy / Trace / 沙箱）一致。

6.4 异常路径

7. 成本治理

7.1 四维度限额

7.2 八步管道的成本归集

每步的 token 与时延通过 ⑧ Trace 写入 CostTrace；按 Run / User / Workspace / Skill 四个维度的 GROUP BY 聚合即可生成各级仪表板。

7.3 超限降级策略

7.4 超限告警与白名单升级

Escalation 白名单：单个 Plan 最多 2 次预算追加，每次最多 8 个 jobs，理由必须命中白名单（stage1_underestimated / attachment_workload_grew / user_requested_more / admin_override），否则 reject。

7.5 仪表板与 Trace 字段对齐

所有仪表板的数据来源都是 ⑧ Trace 写入的 CostTrace + HITLTrace；不存在另起一套度量的"影子表"，保证账单与审计一致。