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