Governance 模块详细设计

本文档展开 kgent/governance/ 的代码设计。

Governance 模块负责 Phase 1 的最小质量和安全基线，确保 kgent 不退化为无约束 prompt runner。

目标关联

该设计支撑：

• Quality and Governance System
• Sandbox-First Work Execution
• Tool-Mediated Action System
• Skill-Driven Capability System
• Memory-Aware Context System

模块范围

包含：

• required deliverable checks。
• governance result taxonomy。
• policy helper。
• missing deliverable reporting。
• unsafe config/tool/path 的结果映射。
• run state 建议。

不包含：

• reviewer agent。
• approval workflow。
• policy language。
• skill review UI。
• memory review UI。
• evaluation harness。

文件结构

src/kgent/governance/
  __init__.py
  deliverables.py
  policy.py
  results.py

数据模型

位置：results.py

class GovernanceStatus:
    passed
    failed
    incomplete
    blocked

class GovernanceResult:
    status: GovernanceStatus
    summary: str
    errors: list[ErrorInfo]
    missing: list[str]

语义：

• passed：检查成功。
• failed：违反硬性要求。
• incomplete：必需工作缺失，但可通过 revision 修复。
• blocked：因权限、无效配置或不安全请求，执行不能继续。

Deliverable Checks

位置：deliverables.py

def validate_required_deliverables(context: RunContext) -> GovernanceResult:
    ...

Phase 1 检查：

• required file exists。
• path is under deliverables/。
• file is non-empty unless explicitly allowed。

默认映射：

• missing required deliverable -> incomplete
• required path outside deliverables -> blocked
• unreadable deliverable -> failed

Policy Helpers

位置：policy.py

def map_config_error(error: ErrorInfo) -> GovernanceResult:
    ...

def map_permission_error(error: ErrorInfo) -> GovernanceResult:
    ...

def map_path_error(error: ErrorInfo) -> GovernanceResult:
    ...

默认映射：

• invalid config -> blocked
• missing enabled skill -> blocked
• unsafe tool permission -> blocked
• path outside sandbox -> blocked
• engine failure -> failed

Runtime 集成

Runtime 在以下时机调用 governance：

1. Config validation failure：转换为 blocked。
2. Skill discovery failure：转换为 blocked。
3. Tool permission rejection：转换为 blocked 并记录。
4. Engine completed 后：调用 validate_required_deliverables。
5. Engine failed 后：转换为 failed。

Run state 建议：

GovernanceStatus.passed -> completed
GovernanceStatus.incomplete -> incomplete
GovernanceStatus.failed -> failed
GovernanceStatus.blocked -> failed

Phase 1 的 RunStatus 应包含 incomplete。缺失交付物不应被折叠成普通 failed，因为它代表可 revision 的工作状态。

事件要求

Governance 应发出：

• deliverable.check.started
• deliverable.check.completed
• deliverable.missing
• run.failed

事件 data 应包含：

• governance_status
• missing
• errors

产物

读取：

runs/<run-id>/config.yaml
runs/<run-id>/deliverables/

写入：

runs/<run-id>/events.jsonl
runs/<run-id>/logs/errors.jsonl
runs/<run-id>/run.json

测试设计

单元测试：

• all required deliverables present -> passed。
• missing required deliverable -> incomplete。
• required deliverable outside dir -> blocked。
• empty file behavior follows policy。
• config error maps to blocked。
• path error maps to blocked。
• engine error maps to failed。

集成测试：

• mock engine 不写 deliverable -> run 记录 governance incomplete。
• mock engine 写 deliverable -> run completed。
• permission rejection 写 event 和 error log。

性能和调度考虑

• Deliverable checks 是简单文件存在性和大小检查。
• 不需要额外模型调用。
• Governance result 是未来 scheduler 判断 revision/retry 的依据。
• incomplete 应被视为可 revision，而不是不可恢复 failure。

验收标准

1. Required deliverables 被校验。
2. Governance result taxonomy 被实现。
3. Missing deliverable 可区分为 incomplete。
4. Blocked 类错误在 agent 执行前阻断。
5. Governance events 被写入。
6. Run state 反映 governance 结果。