治理详解

wesgine 的治理体系是 per-Cell 的效果边界治理模型，通过三步管道对每一次工具调用进行安全裁决。治理链不产生 HITL 交互；HITL 仅用于 Agent 主动交互场景（ask_user / browser_wait_for_user / CycleDetector）。

架构概览

工具调用请求
    │
    ▼
┌──────────────┐
│  Hardline    │  灾难命令拦截（18 条正则，恒 Deny）
└──────┬───────┘
       │ 通过
       ▼
┌──────────────┐
│  Sandbox     │  数据边界（DenyPaths / 写入限制 / NetworkPolicy）
└──────┬───────┘
       │ 通过
       ▼
┌──────────────┐
│  Zone        │  效果分类 + GovernMode 决策
└──────────────┘
       │
       ▼
  Green → Allow
  Yellow → 由 GovernMode 决定
  Red → 条件允许（需审计）

治理链的实现在 internal/govern/checker.go，三步顺序执行，前一步 Deny 则后续步骤不再执行。

Hardline：灾难命令拦截

Hardline 是治理链的第一道防线，包含 18 条正则表达式，用于拦截可能导致系统性灾难的命令。

特点

• 恒 Deny：不可覆盖，不受 GovernMode 影响
• 全工具覆盖：不限于 exec 工具，对所有工具检查 command/cmd/script/shell JSON 字段（INV-GOV-01）
• 即时拒绝：匹配即返回错误，不进入后续判断

拦截的命令类别

使用示例

Hardline 无需配置，始终生效：

spec := wesgine.CellSpec{
    ID: "my-cell",
    // Hardline 自动启用，无需声明
}

即使 GovernMode 为 open，Hardline 仍然拦截灾难命令。

Sandbox：数据边界

Sandbox 是治理链的第二步，负责限制工具的数据访问范围。

DenyPaths

DenyPaths 定义了 Cell 内工具禁止访问的路径列表。

spec := wesgine.CellSpec{
    ID: "dept-legal",
    Governance: wesgine.CellGovernance{
        DenyPaths: []string{
            "/etc/shadow",
            "/var/lib/wesgine/hypervisor.db",
            filepath.Join(dataDir, "secrets"),
        },
    },
}

注意事项：

• DenyPaths 与 Compliance 预设解耦（INV-GOV-COMPLIANCE-02）
• Compliance 只决定 RedactorRules + GuardrailsRequired
• DenyPaths 由预设注入（如 PresetFinancial 注入 /credentials 等）与显式 CellSpec.DenyPaths 管理
• 创建时用预设注入的 DenyPaths 在降级/升级后保持稳定

WorkDir 写入限制

工具的写入操作被限制在 Cell 的工作目录范围内：

• write/edit/apply_patch 输出必须落入 ArtifactDir 或 HostPaths（INV-IO-02）
• 禁止写入 /tmp、Scratch、任何 Cell 外路径
• ArtifactDir 由引擎从 (CellDataDir, Actor, AgentID) 推算（INV-IO-01）

NetworkPolicy

NetworkPolicy 控制 exec 工具中的网络命令：

当 NetworkPolicy=deny 或 internal_only 时，Sandbox 的 checkExecNetwork() 会检测 exec 命令中的网络工具（INV-GOV-02）：

被检测的命令：curl / wget / nc / ncat / netcat / ssh / scp / sftp / rsync

检测按命令位置进行（行首 / ;|& 分隔符后 / 引号与 $() 子 shell / sudo·env 等 wrapper 后），参数位置的同名词（如 grep -r curl .）不误杀。

Zone：效果分类

Zone 是治理链的第三步，将工具调用的效果分为三个区域：

Green Zone — 允许

纯读取、查询类操作。无论 GovernMode 如何，Green Zone 始终允许。

示例：read_file、grep、search、list_files

Yellow Zone — 由 GovernMode 决定

产生副作用但非灾难性的操作。GovernMode 决定是否允许。

示例：write_file、edit、exec（非灾难命令）、apply_patch

Red Zone — 条件允许

高影响操作，需要完整审计记录。

示例：delegate_task（子 Agent 启动，INV-GOV-03）

delegate_task 工具归类为 ZoneRed（非 ZoneYellow），子 Agent 启动必须经过完整审计。

GovernMode

GovernMode 是 per-Cell 声明，决定 Yellow Zone 的行为：

声明方式

spec := wesgine.CellSpec{
    ID: "dept-legal",
    Governance: wesgine.CellGovernance{
        GovernMode: wesgine.GovernModeLocked,
    },
}

默认行为

未声明 Governance → DefaultGovernance()，即 ModeOpen。这不是 fail-loud，open 是合理的默认值。要 locked 的调用方必须自己写全 CellSpec.Governance。

Compliance 预设

Compliance 提供一键装配能力，将 GovernMode、NetworkPolicy、Redactor 组合为预设方案：

ComplianceClass 语义标签

使用方式

// 方式一：直接使用预设
spec := wesgine.CellSpec{
    ID:         "dept-finance",
    Compliance: "financial",
}
// 引擎内部将通过 PresetFinancial 自动映射

// 方式二：手动组合
spec := wesgine.CellSpec{
    ID: "demo-cell",
    Governance: wesgine.CellGovernance{
        GovernMode:    wesgine.GovernModeLocked,
        NetworkPolicy: wesgine.NetworkPolicyDeny,
    },
}

Compliance 与 DenyPaths 的关系

Compliance 类与 DenyPaths 解耦（INV-GOV-COMPLIANCE-02）：

• Compliance 只决定 RedactorRules + GuardrailsRequired
• DenyPaths 由预设（PresetFinancial 注入 /credentials 等）与显式 CellSpec.DenyPaths 管理
• UpdateSpec(Compliance:) 热切只 swap RedactorRules，不增删 DenyPaths

CellQuotas：配额管理

治理体系还包含配额维度，用于限制 Cell 的资源消耗：

最佳实践

1. 编程/助手场景：使用 StandardPreset()（open + allow），依赖 Hardline 兜底
2. 金融合规场景：使用 RegulatedPreset()（locked + internal_only），额外配置 DenyPaths
3. 展示/Demo 场景：使用 ReadonlyPreset()（locked + deny），禁止一切副作用
4. 不要在 GovernMode=open 时假设安全：Hardline 恒 Deny 保护灾难命令，但 Yellow Zone 的副作用操作仍然会执行
5. DenyPaths 要包含敏感文件：如 hypervisor.db、配置文件、密钥目录等
6. 治理策略是声明式的：通过 CellSpec 声明，运行时不可动态修改（除非通过 UpdateSpec）

相关不变量