DataOps-platform/docs/phase2/P2_WP09_AGENT_GOVERNANCE.md

P2-WP09 Agent 基础治理工程说明

1. 完成范围

P2-WP09 已完成本地工程实现和定向验证。平台在已有知识检索、MCP 网关和 Agent 业务实现之上 增加统一治理控制面，不建设通用 Agent 编排器、Agent 开发平台或无人值守执行平台。

本工作包完成：

• Agent 编码、名称、用途、责任人、不可变定义版本、生命周期和机器主体登记；
• 绑定 Agent、业务域和环境的 HMAC 短期凭证，最长 15 分钟，明文只返回一次；
• 只读、建议、审批执行、低风险自动四级自治策略；
• 按 Agent、API/MCP、工具、动作、业务域、环境和风险的精确授权；
• 禁止动作、提示注入识别、证据引用、统一审批、双人复核和决策回放；
• Agent 治理看板、身份授权台账、一次性凭证提示和决策证据回放页面。

2. 身份、版本与凭证边界

governed_agents 保存治理当前态，governed_agent_versions 保存定义快照和内容哈希。 Agent 机器主体采用 agent:<code>:<uid>，不复用操作人员身份。定义修订、暂停和退役会撤销 当前有效凭证。凭证包含 Agent、业务域、环境、签发和失效声明，最长存活 900 秒；数据库只保存 SHA-256 摘要和 JTI，不保存可恢复明文。生产环境必须配置独立 AGENT_CREDENTIAL_SECRET， 缺失时失败关闭；本地和测试环境才允许从应用密钥派生回退密钥。

当前没有实现企业租户模型，凭证只绑定业务域和环境。正式多租户场景需在后续租户底座完成后 增加 tenant claim、租户隔离索引和跨租户拒绝测试。

3. 自治、授权与风险策略

授权按 Agent + interface + tool + action + domain + environment 精确匹配，未命中默认拒绝。 只读 Agent 只能读取；建议 Agent 可以读取和形成带引用建议；审批执行需要统一工作中心批准； 低风险自动只有在动作、授权和风险均为低风险时才可标记自动执行。

高风险和关键风险操作始终需要 dual_control 且至少两名独立审批人。批准后状态为 approved_for_manual_execution，不能调用自动完成接口。删除数据库、关闭审计、导出密钥、 授予权限、执行 Shell 和修改安全策略为固定禁止项。提示中出现忽略系统指令、泄露密钥、 绕过权限或审计等信号时，本次请求直接拒绝并留痕。

4. 证据与统一工作中心

建议动作按 Agent 的 Prompt 策略强制携带版本化证据引用。决策记录保存输入摘要、提示安全 信号、Agent 版本、授权、工具、动作、范围、风险、引用、审批任务和结果摘要，不保存提示原文、 凭证明文或输出正文。审批请求复用 P2-WP07 的 agent_approval/high_risk 任务；工作中心只 产生审批证据，Agent 治理服务显式同步结果，不由任务表直接改写 Agent 请求状态。

每次登记、授权、凭证、策略判定、审批同步和结果留证都追加治理事件及 outbox 证据事件。 回放按请求编号返回最小化决策时间线。当前回放不包含模型供应商、模型版本、推理用量和完整 Prompt 模板版本，这些属于后续预算、模型网关和高级 Agent 治理范围。

5. 权限与接口

• agents:read：查看 Agent 台账、策略判定、看板和证据回放；
• agents:operate：由责任人修订、授权、签发/撤销凭证、切换生命周期和记录执行证据；
• agents:manage：登记 Agent、查看全局治理状态并同步统一审批结果。

所有变更接口使用现有用户认证，机器凭证作为 Agent 调用的第二层身份。状态变更使用 If-Match 乐观版本。前端首批登记只开放只读和建议级选项，避免把更高自治等级误当成默认 能力；后端仍保存审批执行和低风险自动的严格策略模型，供后续受控试点。 OpenAPI 已由当前源码重新生成，共 367 个操作，Agent 治理提供 15 个路由操作。

6. 定向验证与剩余门禁

本工作包按约束只运行本次变动相关验证：

• Agent 注册、凭证、自治、越权、提示注入、证据引用和高风险双人审批核心测试；
• API 角色、一次性凭证响应、乐观版本、权限策略、迁移和前端契约测试；
• 本次 Python 文件 Ruff、前端改动文件 ESLint 和前端生产构建；
• 本地 PostgreSQL 从 20260802_440 实际升级到 20260802_450；
• 一个只读 Agent 和一个建议级 Agent 的真实 PostgreSQL 定向测试，覆盖授权、跨域拒绝、 提示注入拒绝、摘要存储和证据回放，测试样本在事务结束后回滚。

本地工程完成不等同企业验收或生产就绪。正式投产仍需登记真实 Agent 和责任人，绑定企业 业务域、正式 MCP/API 工具清单及独立密钥；完成密钥轮换、吊销传播、并发/容量、告警、备份 恢复和红队 UAT；验证企业 Prompt 注入语料、审批参与人和审计保留制度。预算配额、模型网关、 运行沙箱、异常自动暂停/降级、事故关联、租户隔离和受治理插件市场不在 P2-WP09 范围内。