# 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 范围内。