feat: add main agent governance foundation

docs/superpowers/specs/2026-03-29-main-agent-governance-foundation-design.md

@@ -0,0 +1,283 @@
+# StoryForge 主 Agent 治理底座设计
+
+- 日期：2026-03-29
+- 状态：已确认，直接进入实现
+- 范围：`collector-service`、`web/storyforge-web-v4`
+
+## 1. 背景
+
+当前仓库已经有 `OneLiner` 主 Agent、平台 Agent、平台记忆、平台技能、额度和管理员运维面板，但真正决定长期生命力的治理层还没有闭环。
+
+现状问题：
+
+- `OneLiner` 能承接对话，但“系统默认策略 / 用户策略 / 管理员覆盖”还没有正式的数据模型。
+- 平台 Agent 已经有 profile、memory、skill，但用户策略变更还不能以“全局 / 单平台 / 覆盖层 / 历史版本”的方式正式管理。
+- 管理员配置台已经有入口，但还没有系统级主 Agent 策略、用户策略审计和覆盖管理的正式控制面。
+- 首页和工作台已经开始围绕“交给主 Agent”组织，但推荐逻辑和执行上下文还缺少一个可审计的策略底座。
+
+## 2. 目标
+
+- 建立主 Agent 治理底座的数据模型，不再把策略历史继续塞进旧 JSON。
+- 支持三层用户相关策略：
+  - 用户全局策略
+  - 用户平台策略
+  - 管理员覆盖策略
+- 保留系统默认策略层：
+  - 系统默认主 Agent 策略
+  - 系统默认平台 Agent 策略
+- 所有策略都具备：
+  - 版本
+  - 生效范围
+  - 状态
+  - 原因
+  - 操作者
+  - 回滚来源
+- 主 Agent 运行时可以读取当前用户的有效策略叠加结果。
+- Web 先补最小可用治理 UI：
+  - 用户侧可查看当前有效策略与版本历史
+  - 管理员侧可查看系统默认、用户覆盖、管理员覆盖与回滚记录
+
+## 3. 非目标
+
+- 本轮不重做主 Agent 全部 UI 体验。
+- 本轮不做完整自然语言“自动解析策略修改”闭环。
+- 本轮不把所有平台专属策略细节全部产品化。
+- 本轮不引入新的数据库或事件总线。
+
+## 4. 数据模型
+
+### 4.1 新表
+
+新增四张表：
+
+1. `agent_policy_scopes`
+- 定义策略作用域
+- 核心字段：
+  - `id`
+  - `scope_kind`：`system_main` / `system_platform` / `user_global` / `user_platform` / `admin_override`
+  - `subject_user_id`
+  - `subject_project_id`
+  - `platform`
+  - `status`
+  - `title`
+  - `summary`
+  - `current_version_id`
+  - `created_at`
+  - `updated_at`
+
+2. `agent_policy_versions`
+- 每次修改都生成一个新版本
+- 核心字段：
+  - `id`
+  - `scope_id`
+  - `scope_kind`
+  - `subject_user_id`
+  - `subject_project_id`
+  - `platform`
+  - `version_no`
+  - `title`
+  - `policy_json`
+  - `summary`
+  - `reason`
+  - `source_type`
+  - `rollback_from_version_id`
+  - `actor_user_id`
+  - `created_at`
+
+3. `agent_policy_effectivity`
+- 描述某版本当前是否生效，以及生效范围
+- 核心字段：
+  - `id`
+  - `scope_id`
+  - `version_id`
+  - `effect_mode`：`ongoing` / `scheduled`
+  - `starts_at`
+  - `ends_at`
+  - `status`
+  - `config_json`
+  - `created_at`
+  - `updated_at`
+
+4. `agent_policy_audit_logs`
+- 记录查看、创建、发布、代改、覆盖、回滚等动作
+- 核心字段：
+  - `id`
+  - `scope_id`
+  - `version_id`
+  - `action_key`
+  - `actor_user_id`
+  - `summary`
+  - `details_json`
+  - `created_at`
+
+### 4.2 运行时叠加顺序
+
+运行时有效策略按以下顺序叠加：
+
+1. 系统默认主 Agent / 平台 Agent 策略
+2. 用户全局策略
+3. 用户平台策略
+4. 管理员覆盖策略
+
+后者覆盖前者同名字段。
+
+## 5. 权限边界
+
+### 5.1 普通用户
+
+- 只能读取和更新自己的：
+  - 用户全局策略
+  - 用户平台策略
+- 只能查看自己的版本历史
+- 不能修改系统默认策略
+- 不能查看其他用户策略
+
+### 5.2 超级管理员
+
+- 可查看和修改系统默认主 Agent 策略
+- 可查看和修改系统默认平台 Agent 策略
+- 可查看任意用户策略
+- 可创建管理员覆盖策略
+- 可对用户策略或管理员覆盖进行回滚
+- 管理员操作不会抹掉用户自己的历史版本，只会形成更高优先级覆盖层
+
+### 5.3 Agent 读取边界
+
+- 主 Agent 可读取当前用户：
+  - 用户全局策略
+  - 用户平台策略
+  - 当前平台 Agent 记忆与技能
+- 平台 Agent 只能读取当前用户且当前平台相关的策略、记忆和技能
+
+## 6. 回滚规则
+
+- 回滚不是修改旧版本。
+- 回滚操作会生成一个新版本。
+- 新版本记录 `rollback_from_version_id`。
+- 同时写入审计日志。
+
+## 7. 后端接口
+
+### 7.1 用户侧
+
+- `GET /v2/oneliner/governance/effective`
+  - 返回当前用户在当前项目、当前平台下的有效策略叠加结果
+- `GET /v2/oneliner/governance/user/global`
+  - 返回当前用户全局策略 bundle 和历史统计
+- `PUT /v2/oneliner/governance/user/global`
+  - 更新当前用户全局策略
+- `GET /v2/oneliner/governance/user/global/versions`
+  - 返回当前用户全局策略历史
+- `POST /v2/oneliner/governance/user/global/rollback`
+  - 回滚当前用户全局策略到历史版本
+- `GET /v2/oneliner/governance/user/platforms/{platform}`
+  - 返回当前用户单平台策略 bundle 和历史统计
+- `PUT /v2/oneliner/governance/user/platforms/{platform}`
+  - 更新当前用户单平台策略
+- `GET /v2/oneliner/governance/user/platforms/{platform}/versions`
+  - 返回当前用户单平台策略历史
+- `POST /v2/oneliner/governance/user/platforms/{platform}/rollback`
+  - 回滚当前用户单平台策略到历史版本
+
+### 7.2 管理员侧
+
+- `GET /v2/admin/oneliner/governance/system/main-agent`
+  - 读取系统主 Agent 策略 bundle
+- `PUT /v2/admin/oneliner/governance/system/main-agent`
+  - 更新系统主 Agent 策略
+- `GET /v2/admin/oneliner/governance/system/main-agent/versions`
+  - 读取系统主 Agent 历史
+- `POST /v2/admin/oneliner/governance/system/main-agent/rollback`
+  - 回滚系统主 Agent 策略
+- `GET /v2/admin/oneliner/governance/system/platforms/{platform}`
+  - 读取系统平台策略 bundle
+- `PUT /v2/admin/oneliner/governance/system/platforms/{platform}`
+  - 更新系统平台策略
+- `GET /v2/admin/oneliner/governance/system/platforms/{platform}/versions`
+  - 读取系统平台策略历史
+- `POST /v2/admin/oneliner/governance/system/platforms/{platform}/rollback`
+  - 回滚系统平台策略
+- `GET /v2/admin/oneliner/governance/overrides`
+  - 读取某个用户/项目/平台的管理员覆盖策略 bundle
+- `POST /v2/admin/oneliner/governance/overrides`
+  - 发布管理员覆盖策略
+- `GET /v2/admin/oneliner/governance/overrides/versions`
+  - 读取管理员覆盖策略历史
+- `POST /v2/admin/oneliner/governance/overrides/rollback`
+  - 回滚管理员覆盖策略
+
+## 8. 运行时接入
+
+### 8.1 主 Agent
+
+`OneLiner` 生成上下文时，补充：
+
+- 当前用户有效策略栈
+- 当前命中的管理员覆盖层
+- 当前平台有效策略
+
+这些信息进入：
+
+- `runtime_policy`
+- `policy_layers`
+- `admin_override_notice`
+
+用于：
+
+- 主 Agent 回复中解释“为什么按这个策略执行”
+- 后续首页动作推荐引用同一份有效策略
+
+### 8.2 前端
+
+#### 用户侧 Agent 页面
+
+在 `Agent -> 当前 Agent 工作台` 增加：
+
+- 当前有效主 Agent 策略摘要
+- 当前用户全局策略
+- 当前平台策略入口
+- 最近版本历史
+
+#### 管理员配置台
+
+在 `管理员配置台 -> Agent 治理` 增加：
+
+- 系统默认主 Agent 策略
+- 系统默认平台 Agent 策略
+- 当前项目用户策略总览
+- 管理员覆盖层
+- 最近策略审计
+
+## 9. 测试
+
+### 9.1 后端
+
+- schema 初始化测试
+- 用户全局策略写入与读取测试
+- 用户平台策略覆盖测试
+- 管理员覆盖优先级测试
+- 回滚生成新版本测试
+- 审计日志记录测试
+- `runtime` 叠加顺序测试
+
+### 9.2 前端
+
+- Agent 页包含治理摘要入口
+- 管理员台包含治理区块
+- 版本历史和覆盖标记文案存在
+
+## 10. 第一批实现范围
+
+本轮只做：
+
+- 治理底座表结构
+- 核心策略接口
+- 主 Agent 运行时接入
+- 最小治理 UI
+- 基本测试
+
+不做：
+
+- 复杂自然语言自动改策略
+- 多项目多阶段高级调度面板
+- 完整的对比 diff 可视化