docs: add main agent runtime flow spec

docs/superpowers/specs/2026-03-29-main-agent-runtime-flow-design.md

@@ -0,0 +1,354 @@
+# StoryForge 主 Agent 运行层与悬浮工作流设计
+
+- 日期：2026-03-29
+- 状态：已确认，直接进入实现
+- 范围：`collector-service`、`web/storyforge-web-v4`
+
+## 1. 背景
+
+当前仓库已经有两类能力：
+
+- `OneLiner session/message`
+  - 承担用户与主 Agent 的对话历史
+- `execution_card`
+  - 能在单条消息里附带执行建议、下一步、证据和管理员覆盖提示
+
+但这些能力还不足以支撑“主 Agent 是全站统一工作入口”的产品目标。当前缺口主要有：
+
+- 页面里的“交给主 Agent”还没有统一承接链路。
+- 用户确认执行、后台运行、阻塞等待、近期进度都还没有独立的运行单元。
+- 右下角悬浮主 Agent 目前还是“聊天面板”，还不是“聊天 + 任务运行中心”。
+- 多任务并行/排队、最小化后状态感知、最近待确认任务都没有统一模型。
+
+如果继续把执行请求直接塞进聊天消息，会导致：
+
+- 聊天和任务状态纠缠
+- 运行中/待确认/阻塞/完成难以跟踪
+- 页面动作无法统一接入
+- 后续审计、商业化和管理员治理会越来越难做
+
+## 2. 目标
+
+- 在现有 `OneLiner session/message` 之外，新增独立的 `agent run` 运行层。
+- 所有页面里的“交给主 Agent”统一先创建一个 `needs_confirmation` 的 run。
+- 右下角悬浮主 Agent 继续作为唯一入口，但内部升级为：
+  - 顶部执行区
+  - 下方聊天流
+- 用户确认后，run 才进入真正执行。
+- 主 Agent 自己判断 run 是并行还是排队。
+- 悬浮按钮最小化后仍可看到：
+  - 状态点
+  - 当前任务数
+  - 一行极短状态摘要
+- 当存在管理员覆盖时，确认卡和运行卡需要显式提示。
+
+## 3. 非目标
+
+- 本轮不重做整套视觉风格。
+- 本轮不把所有前端按钮都改成真正自动化执行。
+- 本轮不实现复杂图形化编排器。
+- 本轮不引入新的任务基础设施或消息队列。
+- 本轮不替换现有 `OneLiner session/message`。
+
+## 4. 总体方案
+
+采用“双层结构”：
+
+1. `OneLiner session/message`
+- 保留现有聊天历史与自然语言上下文
+
+2. `agent run`
+- 新增专门的运行单元
+- 用于承接：
+  - 页面动作升级为主 Agent 执行
+  - 需要用户确认的执行计划
+  - 后台运行状态
+  - 阻塞等待和恢复
+  - 最近一次执行结果
+
+这两层通过 `session_id` 关联，但职责不同：
+
+- `session/message` 负责“说了什么”
+- `agent run` 负责“当前在做什么”
+
+## 5. 数据模型
+
+### 5.1 新表
+
+新增表：`agent_runs`
+
+核心字段：
+
+- `id`
+- `session_id`
+- `user_id`
+- `project_id`
+- `source_type`
+  - `homepage_action`
+  - `page_action`
+  - `chat_request`
+  - `system_followup`
+- `source_screen`
+- `source_action_key`
+- `title`
+- `summary`
+- `intent_key`
+- `platform`
+- `platform_scope`
+  - `single_platform`
+  - `all_platforms`
+- `delivery_mode`
+  - `ui`
+  - `oneliner`
+  - `hybrid`
+- `run_status`
+  - `needs_confirmation`
+  - `queued`
+  - `running`
+  - `blocked`
+  - `done`
+  - `failed`
+  - `cancelled`
+- `scheduling_mode`
+  - `parallel`
+  - `queued`
+- `active_executor_key`
+- `plan_json`
+- `result_json`
+- `status_summary`
+- `needs_user_input`
+- `blocked_reason`
+- `active_admin_override_notice_json`
+- `created_at`
+- `updated_at`
+- `started_at`
+- `finished_at`
+
+### 5.2 事件表
+
+新增表：`agent_run_events`
+
+核心字段：
+
+- `id`
+- `run_id`
+- `event_type`
+  - `run.created`
+  - `run.confirmed`
+  - `run.queued`
+  - `run.started`
+  - `run.progress`
+  - `run.blocked`
+  - `run.done`
+  - `run.failed`
+  - `run.cancelled`
+- `summary`
+- `details_json`
+- `created_at`
+
+### 5.3 运行状态机
+
+默认状态流转：
+
+- `needs_confirmation -> queued -> running -> done`
+
+异常流转：
+
+- `needs_confirmation -> cancelled`
+- `running -> blocked`
+- `blocked -> running`
+- `running -> failed`
+- `queued -> cancelled`
+
+## 6. 运行规则
+
+### 6.1 页面动作进入主 Agent
+
+所有页面中的“交给主 Agent”统一调用新入口：
+
+- `POST /v2/oneliner/runs`
+
+提交内容至少包含：
+
+- `project_id`
+- `source_screen`
+- `source_action_key`
+- `title`
+- `summary`
+- `platform`
+- `platform_scope`
+- `intent_key`
+- `plan_request`
+
+后端创建：
+
+- 一个 `agent run`
+- 默认 `run_status = needs_confirmation`
+- 并把当时的：
+  - 有效策略
+  - 执行步骤
+  - 平台 Agent 目标
+  - 管理员覆盖提示
+  写成 `plan_json`
+
+### 6.2 确认卡
+
+点击“交给主 Agent”后：
+
+- 自动打开右下角悬浮窗口
+- 顶部优先展示最近一次 `needs_confirmation` 的 run
+
+确认卡默认展示标准信息：
+
+- 目标
+- 影响对象
+- 执行步骤
+- 会调用哪些平台 Agent
+- 可能影响什么
+
+如果存在管理员覆盖，再额外展示一段简短提示：
+
+- `当前存在管理员覆盖：xxx`
+
+### 6.3 确认后执行
+
+确认执行后：
+
+- run 进入 `queued`
+- 主 Agent 根据当前运行情况决定：
+  - 并行执行
+  - 还是排队等待
+
+如果可以直接执行：
+
+- `queued -> running`
+
+如果要等其他 run：
+
+- 保持 `queued`
+- 更新 `status_summary`
+
+### 6.4 最小化后的状态
+
+悬浮按钮最小化时显示：
+
+- 状态点
+  - 空闲
+  - 需确认
+  - 运行中
+  - 阻塞
+- 当前任务数
+- 一行极短状态摘要
+
+摘要优先级：
+
+1. 最近待确认任务
+2. 最近阻塞任务
+3. 当前运行中的任务
+4. 最近完成任务
+
+## 7. 前端交互设计
+
+### 7.1 悬浮窗口布局
+
+保留现有 `OneLiner` 右下角入口，不新增第二入口。
+
+窗口内部改成：
+
+1. 顶部 `run` 区
+- 待确认卡 / 运行中卡 / 阻塞卡 / 完成卡
+
+2. 中部聊天流
+- 保留现有 `session/message`
+
+3. 底部输入区
+- 继续支持自然语言对话
+
+### 7.2 顶部 run 区优先级
+
+打开窗口后，顶部默认显示：
+
+1. 最近一次需要用户确认的 run
+2. 若没有待确认，则显示最近一次阻塞 run
+3. 若没有阻塞，则显示当前运行中的 run
+4. 若都没有，则显示最近完成的 run
+
+### 7.3 页面动作接入
+
+第一版先接以下入口：
+
+- 首页主动作中的 `交给主 Agent`
+- 首页次动作中的 `交给主 Agent`
+- `我的策略` 页的 `交给 OneLiner 调整`
+- `Agent` 页与策略治理相关的 `交给主 Agent`
+
+其他页面先保留现有 `open-oneliner`，后续再逐步切到 run 创建入口。
+
+## 8. 后端接口
+
+### 8.1 运行层
+
+- `POST /v2/oneliner/runs`
+  - 创建一个待确认 run
+- `GET /v2/oneliner/runs`
+  - 读取当前用户最近 run 列表
+- `GET /v2/oneliner/runs/{run_id}`
+  - 读取单个 run 详情
+- `POST /v2/oneliner/runs/{run_id}/confirm`
+  - 用户确认执行
+- `POST /v2/oneliner/runs/{run_id}/cancel`
+  - 用户取消
+- `GET /v2/oneliner/runs/{run_id}/events`
+  - 读取运行事件
+
+### 8.2 会话层保持不变
+
+保留现有：
+
+- `POST /v2/oneliner/sessions/{session_id}/messages`
+- `POST /v2/oneliner/actions/execute`
+
+第一版由 run 层在确认执行后，内部复用现有 `actions/execute` 或对话处理逻辑。
+
+## 9. 与治理底座的关系
+
+`agent run` 创建时会固化：
+
+- 当前有效策略摘要
+- 当前叠加层
+- 当前管理员覆盖提示
+
+这样可以确保：
+
+- 用户看到的确认卡可解释
+- 运行中状态与当时策略一致
+- 后续审计可以回答“为什么这样执行”
+
+## 10. 测试
+
+### 10.1 后端
+
+- run 创建测试
+- run 确认流转测试
+- run 阻塞/完成事件测试
+- run 创建时固化治理快照测试
+- run 列表优先级测试
+
+### 10.2 前端
+
+- 悬浮窗口包含 run 顶部区
+- 页面动作会创建待确认 run
+- 待确认 run 会优先展示
+- 最小化按钮显示状态点、数量、摘要
+- 管理员覆盖提示可见
+
+## 11. 第一版验收标准
+
+- 用户从首页点“交给主 Agent”，会打开悬浮窗口并看到标准确认卡。
+- 确认后，顶部 run 区能看到：
+  - 运行状态
+  - 极短状态摘要
+  - 最新进度
+- 下方聊天流仍然正常工作。
+- 最小化后，右下角能看到当前任务状态。
+- 有管理员覆盖时，确认卡和运行卡都会明确提示。