krisolo/storyforge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4cd9ff77d94e089d40a64d2c0a620f350db6eed8
storyforge/docs/superpowers/specs/2026-03-29-main-agent-runtime-flow-design.md
kris ccbe6ca565 docs: add main agent runtime flow spec
2026-03-29 18:05:30 +08:00

7.9 KiB
Raw Blame History

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
  • 保留现有聊天历史与自然语言上下文
  1. 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 区
  • 待确认卡 / 运行中卡 / 阻塞卡 / 完成卡
  1. 中部聊天流
  • 保留现有 session/message
  1. 底部输入区
  • 继续支持自然语言对话

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