治理指南

wesgine 的治理系统（Governance）提供 per-Cell 的效果边界控制，确保 AI Agent 在安全策略内运行。

核心概念

治理不是权限系统，而是效果边界系统——它决定 Agent 的操作可以产生多大的影响范围。

治理链不产生 HITL（人机交互）；HITL 仅用于 Agent 主动交互（ask_user、browser_wait_for_user、CycleDetector）。

三步管道

每个工具调用经过三步管道依次判定：

Hardline → Sandbox → Zone

第一步：Hardline（灾难命令拦截）

恒 Deny，不可覆盖，不受 GovernMode 影响。

Hardline 包含 18 条灾难命令正则，拦截足以造成不可逆损害的操作：

类别示例模式
系统销毁rm -rf /、mkfs、dd if=/dev/zero
Fork bomb:(){ :|:& };:
关机重启shutdown、reboot、halt
引擎自毁kill <engine-pid>

关键特性：

// Hardline 示例：以下操作总是被拒绝
exec("rm -rf /")           // 系统销毁
exec(":(){ :|:& };:")      // Fork bomb
exec("shutdown -h now")    // 关机

第二步：Sandbox（数据边界）

检查操作是否在允许的数据边界内：

Governance: wesgine.CellGovernance{
	DenyPaths: []string{
		"/etc/shadow",
		"/root/.ssh",
		"/var/lib/wesgine/hypervisor.db",
	},
	NetworkPolicy: "internal_only",
}

NetworkPolicy 网络命令检测（INV-GOV-02）

当 NetworkPolicy 为 deny 或 internal_only 时，Sandbox 按命令位置检测 exec 中的网络命令：

检测位置说明
行首curl https://...
; / | / & 分隔符后ls; curl ...
引号与 $() 子 shell 内$(wget ...)
sudo/env 等 wrapper 后sudo curl ...

检测的命令包括：curl、wget、nc、ncat、netcat、ssh、scp、sftp、rsync。

参数位置不误杀：grep -r curl . 不会被拦截。

第三步：Zone（效果分类 + Mode 决策）

将操作分为三个区域：

Zone含义行为
Green只读/无副作用总是允许
Yellow有副作用但可控由 GovernMode 决定
Red高风险操作需要条件审批
Green  → Allow（始终）
Yellow → GovernMode 决策
Red    → 条件审批

特殊分类：

GovernMode

Per-Cell 声明，决定 Yellow Zone 操作的处理方式：

open（默认）

Yellow Zone 操作 = Allow + Audit

Governance: wesgine.CellGovernance{
	GovernMode: "open",
}

适用场景：编程助手、通用对话、开发环境。

locked

Yellow Zone 操作 = Deny

Governance: wesgine.CellGovernance{
	GovernMode: "locked",
}

适用场景：金融合规、数据展示、受限环境。

Compliance 预设

一键装配 GovernMode + NetworkPolicy + Redactor：

StandardPreset

governance.StandardPreset(spec)
属性值
GovernModeopen
NetworkPolicyallow
Redactor无
适用wescode / wesclaw / wescraft

RegulatedPreset

governance.RegulatedPreset(spec)
属性值
GovernModelocked
NetworkPolicyinternal_only
Redactor按场景配置
适用金融 / PII / 医疗

ReadonlyPreset

governance.ReadonlyPreset(spec)
属性值
GovernModelocked
NetworkPolicydeny
Redactor无
适用展示 / Demo

DenyPaths

禁止 Agent 访问的路径列表。写操作和读操作都受此限制。

DenyPaths: []string{
	"/etc/shadow",
	"/root",
	filepath.Join(dirs.DataDir(), "hypervisor.db"),
	dirs.ConfigFile(),
}

注意事项：

Redactor 规则

对 Agent 输出进行敏感数据脱敏：

RedactorRules: []wesgine.RedactorRule{
	{
		Pattern:     `\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b`,
		Replacement: "[银行卡号已脱敏]",
		Category:    "financial",
	},
	{
		Pattern:     `\b\d{18}\b`,
		Replacement: "[身份证号已脱敏]",
		Category:    "pii",
	},
}

实战示例

编程助手（open + 路径限制）

spec := wesgine.CellSpec{
	ID: "ws-dev",
	Governance: wesgine.CellGovernance{
		GovernMode:    "open",
		DenyPaths:     []string{"/etc", "/root", "/var/lib/wesgine/hypervisor.db"},
		NetworkPolicy: "allow",
	},
}

金融合规部门（locked + 严格网络）

spec := wesgine.CellSpec{
	ID: "dept-finance",
	Compliance: "financial",
}
// 等价于：
governance.RegulatedPreset(&spec)
// GovernMode=locked, NetworkPolicy=internal_only, DenyPaths 包含 /credentials 等

Demo 展示（只读）

spec := wesgine.CellSpec{
	ID: "demo-cell",
}
governance.ReadonlyPreset(&spec)
// GovernMode=locked, NetworkPolicy=deny

最佳实践

  1. 优先使用 Compliance 预设，避免手工组装 Governance 字段
  2. DenyPaths 始终包含引擎自身路径（hypervisor.db、config 文件）
  3. 生产环境不要使用 open + allow 组合，除非明确需要
  4. 审计日志：open 模式下 Yellow Zone 操作虽被允许，但会记录审计日志
  5. NetworkPolicy 与 DenyPaths 互补：前者控制出网，后者控制文件系统

注意事项