feat: add main agent governance foundation

2026-03-29 16:13:50 +08:00
parent dff369aafd
commit cb17fb0760
7 changed files with 2574 additions and 7 deletions
--- a/docs/superpowers/plans/2026-03-29-main-agent-governance-foundation.md
+++ b/docs/superpowers/plans/2026-03-29-main-agent-governance-foundation.md
@@ -0,0 +1,284 @@
+# Main Agent Governance Foundation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build the first production-ready governance foundation for StoryForge main-agent policy layers, versioning, admin overrides, rollback, and minimal governance UI.
+
+**Architecture:** Add dedicated governance tables and endpoints inside `oneliner_features.py`, compute effective policy layers at runtime for OneLiner context, then expose a minimal read/write UI in the existing Agent page and Admin Workbench without redesigning the shell.
+
+**Tech Stack:** FastAPI, SQLite, existing StoryForge Web V4 vanilla JS, Node test runner, Python unittest
+
+---
+
+### Task 1: Spec + plan docs
+
+**Files:**
+- Create: `docs/superpowers/specs/2026-03-29-main-agent-governance-foundation-design.md`
+- Create: `docs/superpowers/plans/2026-03-29-main-agent-governance-foundation.md`
+
+- [ ] **Step 1: Save the approved design**
+
+Write the governance design into the spec file above.
+
+- [ ] **Step 2: Save this implementation plan**
+
+Write this plan file and keep it committed with the implementation.
+
+- [ ] **Step 3: Commit docs checkpoint**
+
+```bash
+git add docs/superpowers/specs/2026-03-29-main-agent-governance-foundation-design.md docs/superpowers/plans/2026-03-29-main-agent-governance-foundation.md
+git commit -m "docs: add main agent governance foundation spec"
+```
+
+### Task 2: Add failing backend governance tests
+
+**Files:**
+- Create: `tests/test_main_agent_governance.py`
+- Modify: `tests/test_production_baseline.py`
+
+- [ ] **Step 1: Write failing tests for scope creation and runtime layering**
+
+Add tests that verify:
+- system default policy can be written and read
+- user global policy overrides system default
+- user platform policy overrides user global for one platform
+- admin override wins over user layers
+- rollback creates a new version instead of mutating history
+
+- [ ] **Step 2: Run the failing test file**
+
+Run:
+
+```bash
+python3 -m unittest tests.test_main_agent_governance -v
+```
+
+Expected: failures because governance tables and endpoints do not exist yet.
+
+### Task 3: Add backend schema and payload helpers
+
+**Files:**
+- Modify: `collector-service/app/oneliner_features.py`
+
+- [ ] **Step 1: Add schema tables**
+
+Add table creation SQL for:
+- `agent_policy_scopes`
+- `agent_policy_versions`
+- `agent_policy_effectivity`
+- `agent_policy_audit_logs`
+
+- [ ] **Step 2: Add policy helper functions**
+
+Implement helpers for:
+- scope payload
+- version payload
+- audit payload
+- system scope ensure
+- current active version lookup
+- effective layer merge
+
+- [ ] **Step 3: Re-run failing governance tests**
+
+Run:
+
+```bash
+python3 -m unittest tests.test_main_agent_governance -v
+```
+
+Expected: some tests still fail because endpoints are missing, but schema-related failures should move forward.
+
+### Task 4: Add governance write/read endpoints
+
+**Files:**
+- Modify: `collector-service/app/oneliner_features.py`
+
+- [ ] **Step 1: Add user-side endpoints**
+
+Implement:
+- `GET /v2/oneliner/governance/effective`
+- `GET /v2/oneliner/governance/user/global`
+- `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}`
+- `PUT /v2/oneliner/governance/user/platforms/{platform}`
+- `GET /v2/oneliner/governance/user/platforms/{platform}/versions`
+- `POST /v2/oneliner/governance/user/platforms/{platform}/rollback`
+
+- [ ] **Step 2: Add admin-side endpoints**
+
+Implement:
+- `GET /v2/admin/oneliner/governance/system/main-agent`
+- `PUT /v2/admin/oneliner/governance/system/main-agent`
+- `GET /v2/admin/oneliner/governance/system/main-agent/versions`
+- `POST /v2/admin/oneliner/governance/system/main-agent/rollback`
+- `GET /v2/admin/oneliner/governance/system/platforms/{platform}`
+- `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`
+- `POST /v2/admin/oneliner/governance/overrides`
+- `GET /v2/admin/oneliner/governance/overrides/versions`
+- `POST /v2/admin/oneliner/governance/overrides/rollback`
+
+- [ ] **Step 3: Add audit logging inside every governance mutation**
+
+Record actor, target, scope, version, reason, and rollback source where relevant.
+
+- [ ] **Step 4: Run governance backend tests**
+
+Run:
+
+```bash
+python3 -m unittest tests.test_main_agent_governance -v
+```
+
+Expected: backend governance tests pass.
+
+### Task 5: Connect runtime layering into OneLiner context
+
+**Files:**
+- Modify: `collector-service/app/oneliner_features.py`
+- Test: `tests/test_main_agent_governance.py`
+
+- [ ] **Step 1: Inject runtime policy into session context**
+
+Extend the OneLiner context builder so the runtime payload includes:
+- effective merged policy
+- ordered policy layers
+- active admin override notice
+
+- [ ] **Step 2: Make OneLiner reply builder surface active governance context**
+
+Use the runtime policy payload to explain active strategy layers in the result payload, without rewriting all prompt logic.
+
+- [ ] **Step 3: Add tests for runtime payload**
+
+Verify the runtime endpoint and OneLiner context expose the merged policy stack.
+
+- [ ] **Step 4: Run backend tests**
+
+Run:
+
+```bash
+python3 -m unittest tests.test_main_agent_governance tests.test_production_baseline -v
+```
+
+Expected: pass.
+
+### Task 6: Add minimal governance UI loading and rendering
+
+**Files:**
+- Modify: `web/storyforge-web-v4/assets/app.js`
+- Modify: `web/storyforge-web-v4/tests/workbench-pages.test.mjs`
+
+- [ ] **Step 1: Write failing frontend tests**
+
+Add assertions that:
+- Agent workspace references effective policy summary
+- Admin Workbench Agent governance tab references system policy, user overrides, and audit history
+
+- [ ] **Step 2: Run frontend tests and verify failure**
+
+Run:
+
+```bash
+node --test web/storyforge-web-v4/tests/workbench-pages.test.mjs
+```
+
+Expected: fail on missing governance UI text and loaders.
+
+- [ ] **Step 3: Load governance payloads in app state**
+
+Add app state fields and data loading for:
+- current runtime policy
+- current user version history
+- admin governance overview
+
+- [ ] **Step 4: Render minimal governance panels**
+
+Render:
+- user-side policy summary + version list in `Agent -> 当前 Agent 工作台`
+- admin-side system default, user override, audit summary in `管理员配置台 -> Agent 治理`
+
+- [ ] **Step 5: Re-run frontend tests**
+
+Run:
+
+```bash
+node --test web/storyforge-web-v4/tests/workbench-pages.test.mjs
+node --check web/storyforge-web-v4/assets/app.js
+```
+
+Expected: pass.
+
+### Task 7: Add minimal edit flows for first batch
+
+**Files:**
+- Modify: `web/storyforge-web-v4/assets/app.js`
+- Modify: `web/storyforge-web-v4/tests/workbench-pages.test.mjs`
+
+- [ ] **Step 1: Add user edit entrypoints**
+
+Provide modal actions for:
+- update user global strategy
+- update current platform strategy
+
+- [ ] **Step 2: Add admin edit entrypoints**
+
+Provide modal actions for:
+- update system default main-agent strategy
+- update system default platform strategy
+- update admin override strategy for selected user/platform
+- rollback selected scope version
+
+- [ ] **Step 3: Keep first batch UI intentionally small**
+
+Do not build a full-blown designer. Use the existing modal patterns with JSON textarea + summary/reason fields if needed.
+
+- [ ] **Step 4: Re-run frontend tests**
+
+Run:
+
+```bash
+node --test web/storyforge-web-v4/tests/workbench-pages.test.mjs
+```
+
+Expected: pass.
+
+### Task 8: Full verification, deploy, and publish
+
+**Files:**
+- Modify as needed from previous tasks only
+
+- [ ] **Step 1: Run full repo checks**
+
+```bash
+python3 -m unittest tests.test_platform_contracts tests.test_production_baseline tests.test_main_agent_governance -v
+node --test web/storyforge-web-v4/tests/dashboard-home.test.mjs web/storyforge-web-v4/tests/workbench-pages.test.mjs
+node --check web/storyforge-web-v4/assets/app.js
+python3 -m compileall collector-service/app tests
+git diff --check
+```
+
+- [ ] **Step 2: Deploy to fnOS**
+
+```bash
+bash scripts/deploy_fnos_storyforge_lan_stack.sh
+```
+
+- [ ] **Step 3: Run fnOS smoke**
+
+```bash
+bash scripts/smoke_fnos_storyforge_lan.sh
+```
+
+- [ ] **Step 4: Commit and push**
+
+```bash
+git add collector-service/app/oneliner_features.py web/storyforge-web-v4/assets/app.js tests/test_main_agent_governance.py tests/test_production_baseline.py web/storyforge-web-v4/tests/workbench-pages.test.mjs docs/superpowers/specs/2026-03-29-main-agent-governance-foundation-design.md docs/superpowers/plans/2026-03-29-main-agent-governance-foundation.md
+git commit -m "feat: add main agent governance foundation"
+git push gitea codex/storyforge-live-orchestrator-sync-20260323
+```
--- a/docs/superpowers/specs/2026-03-29-main-agent-governance-foundation-design.md
+++ b/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 可视化