krisolo/storyforge

Fork 0

Files

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. 总体方案

采用“双层结构”：

OneLiner session/message

保留现有聊天历史与自然语言上下文

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 最小化后的状态

悬浮按钮最小化时显示：

状态点
- 空闲
- 需确认
- 运行中
- 阻塞
当前任务数
一行极短状态摘要

摘要优先级：

最近待确认任务
最近阻塞任务
当前运行中的任务
最近完成任务

7. 前端交互设计

7.1 悬浮窗口布局

保留现有 OneLiner 右下角入口，不新增第二入口。

窗口内部改成：

顶部 run 区

待确认卡 / 运行中卡 / 阻塞卡 / 完成卡

中部聊天流

保留现有 session/message

底部输入区

继续支持自然语言对话

7.2 顶部 run 区优先级

打开窗口后，顶部默认显示：

最近一次需要用户确认的 run
若没有待确认，则显示最近一次阻塞 run
若没有阻塞，则显示当前运行中的 run
若都没有，则显示最近完成的 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 区能看到：
- 运行状态
- 极短状态摘要
- 最新进度
下方聊天流仍然正常工作。
最小化后，右下角能看到当前任务状态。
有管理员覆盖时，确认卡和运行卡都会明确提示。

7.9 KiB Raw Blame History Unescape Escape