# 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 区能看到：
  - 运行状态
  - 极短状态摘要
  - 最新进度
- 下方聊天流仍然正常工作。
- 最小化后，右下角能看到当前任务状态。
- 有管理员覆盖时，确认卡和运行卡都会明确提示。