feat: add unified OA event flow
This commit is contained in:
Codex
@@ -6,7 +6,13 @@ UniDesk 前端是 React 组件化工业控制台，不追求展示型大屏效
|
||||
|
||||
frontend 应用源码必须使用 TypeScript + React，禁止在 `src/components/frontend` 中维护手写 `.js` / `.jsx` 应用源码。浏览器请求的 `/app.js` 只能由 frontend Bun server 从 `src/components/frontend/src/app.tsx` 及其 TSX imports 转译生成；`public/` 目录只保存 HTML/CSS 等静态资产，不提交手写 `app.js`。
|
||||
|
||||
`src/components/frontend/src/app.tsx` 只承担应用 shell、登录、全局数据加载、主模块/子标签路由和通用控制台页面。用户服务前端必须模块化到独立 TSX 文件，禁止继续把所有业务页面堆进 `app.tsx`。当前长期固定入口为：`todo-note.tsx` 承载 Todo Note 工作台，`findjob.tsx` 承载 FindJob 工作台，`pipeline.tsx` 承载 Pipeline 工作台，`met-nonlinear.tsx` 承载 MET Nonlinear 训练编排工作台，`claudeqq.tsx` 承载 ClaudeQQ QQ 消息网关工作台，`baidu-netdisk.tsx` 承载 Baidu Netdisk 存储工作台，`code-queue.tsx` 承载 Code Queue 控制台；新增用户服务也必须按同样规则新增独立页面模块，并由 `app.tsx` 只做导入和路由分发。
|
||||
`src/components/frontend/src/app.tsx` 只承担应用 shell、登录、全局数据加载、主模块/子标签路由和通用控制台页面。用户服务前端必须模块化到独立 TSX 文件，禁止继续把所有业务页面堆进 `app.tsx`。当前长期固定入口为：`todo-note.tsx` 承载 Todo Note 工作台，`findjob.tsx` 承载 FindJob 工作台，`pipeline.tsx` 承载 Pipeline 工作台，`met-nonlinear.tsx` 承载 MET Nonlinear 训练编排工作台，`claudeqq.tsx` 承载 ClaudeQQ QQ 消息网关工作台，`baidu-netdisk.tsx` 承载 Baidu Netdisk 存储工作台，`code-queue.tsx` 承载 Code Queue 控制台，`oa-event-flow.tsx` 承载统一 OA 事件流控制台；新增用户服务也必须按同样规则新增独立页面模块，并由 `app.tsx` 只做导入和路由分发。
|
||||
|
||||
## Shared Dialog Component
|
||||
|
||||
通用模态弹窗统一复用 `src/components/frontend/src/dialog.tsx` 的 `UniDeskDialog`。新增确认弹窗、选择弹窗、表单弹窗或小窗口不得在业务页面内重复手写 `modal-backdrop` / `raw-dialog` 结构；业务页面只传入 title、body、actions、test id、关闭行为和少量业务 class。这样可以统一 `role="dialog"`、`aria-modal`、关闭按钮、点击遮罩关闭、滚动边界、action 区和 E2E 定位语义。
|
||||
|
||||
Code Queue 的 queue 合并弹窗是该公共组件的首个业务复用示例；后续用户服务前端需要独立小窗口时应优先复用 `UniDeskDialog`，只有原始 JSON 查看器这类已有专用展示器可以继续保留自己的内容渲染。
|
||||
|
||||
## Deployment Contract
|
||||
|
||||
@@ -32,7 +38,7 @@ frontend 所有默认可见的时间、日期、时钟、更新时间、心跳
|
||||
|
||||
## Layout
|
||||
|
||||
左侧边栏只切换主模块：运行总览、资源节点、任务调度、用户服务、系统配置。顶部标签只切换当前主模块内的子功能；例如资源节点下的节点清单、资源标签、心跳状态只属于资源节点，用户服务下的服务目录、Todo Note、FindJob、Pipeline、MET Nonlinear、ClaudeQQ、Baidu Netdisk、Code Queue 只属于用户服务，和运行总览、任务调度、系统配置没有重复或共享语义。桌面端左侧边栏必须支持收起，只保留模块 code 和展开按钮，以便最大化主面板空间；移动端左侧边栏会转为顶部横向主模块条，但高度必须在不同主模块之间保持一致，并保持窄条、单行、不换行；主内容区无论内容多少都必须从顶部向下排列，空状态也不得上下居中制造大块留白。
|
||||
左侧边栏只切换主模块：运行总览、资源节点、任务调度、用户服务、系统配置。顶部标签只切换当前主模块内的子功能；例如资源节点下的节点清单、资源标签、心跳状态只属于资源节点，用户服务下的服务目录、Todo Note、FindJob、Pipeline、MET Nonlinear、ClaudeQQ、Baidu Netdisk、Code Queue、OA Event Flow 只属于用户服务，和运行总览、任务调度、系统配置没有重复或共享语义。桌面端左侧边栏必须支持收起，只保留模块 code 和展开按钮，以便最大化主面板空间；移动端左侧边栏会转为顶部横向主模块条，但高度必须在不同主模块之间保持一致，并保持窄条、单行、不换行；主内容区无论内容多少都必须从顶部向下排列，空状态也不得上下居中制造大块留白。
|
||||
|
||||
## Route Model
|
||||
|
||||
@@ -88,17 +94,18 @@ frontend shell 必须把左侧主模块与顶部子标签编译为统一的 URL
|
||||
- `FindJob` 子标签必须把 D601 findjob 后端渲染为 UniDesk React 控件，包括岗位指标、岗位预览、草稿报告和显式原始 JSON 按钮。
|
||||
- `ClaudeQQ` 子标签必须把 D601 ClaudeQQ 后端渲染为 UniDesk React 控件，包括 NapCat 容器登录二维码、NapCat HTTP/WS 状态、事件缓存、QQ 事件订阅表、订阅创建表单、消息推送表单、主用户私聊账号 `645275593` 标记、最近 QQ 事件、已发送记录和显式原始 JSON 按钮。
|
||||
- `Baidu Netdisk` 子标签必须把主 server `baidu-netdisk-backend` 后端渲染为 UniDesk React 控件，包括 OAuth 设备码二维码/用户码登录、账号容量、配置工作根文件浏览（当前默认百度网盘根目录 `/`）、staging 目录上传/下载任务、上传/下载自测按钮与 MD5 结果、脱敏安全说明、日志摘要和显式原始 JSON 按钮；不得把 access token、refresh token、dlink 或 staging 文件字节流裸露到浏览器。
|
||||
- `Code Queue` 子标签必须把主 server `code-queue-backend` 后端渲染为 UniDesk React 控件，包括多 queue lane、queue 内串行、queue 间并行、queue 合并（只能合并任务归属、不能删除源 queue，合并后按原 queueEnteredAt/createdAt 时间顺序串行）、任务 ID/复制任务 ID、引用按钮、任务耗时、任务提交/批量提交、引用任务 ID、创建成功提示、清空输入、模型下拉、显式入队份数、默认模型 `gpt-5.5`、MiniMax judge 状态、Codex CLI-like 输出流、attempt 终态、运行中追加 prompt、打断、手动重试和显式原始 JSON 按钮；Codex CLI-like 输出流必须始终保留任务的初始 `Submitted prompt` 和运行中 `Steer prompt`；整个 agent loop 消息流统一命名为专有名词 `Trace`，`Trace` 包含 assistant message、user prompt、system event 和 tool call；Code Queue 与 Pipeline/OpenCode messages 必须共用 `src/components/frontend/src/trace.tsx` 的 Trace 公共组件、统一 Trace item 接口和 codex/opencode port 适配层；连续 read/edit/run 工具调用只是在 Trace 内折叠为可展开工具调用组，汇总格式至少包含 `xx read, xx edit, xx run`，并展示读取文件、编辑文件、运行命令和耗时摘要；最近 3 个工具调用保持展开，工具调用内容不得自动换行且必须在工具调用块内部横向滚动，工具调用组展开后不得再增加额外左侧缩进；message 与 prompt 必须自动换行，普通 message 不显示左侧项目符号缩进且永不折叠；Trace 首屏可以是摘要预览，但终态任务被选中后必须自动在后台加载完整 Trace，手动“加载完整 Trace”也必须从 Code Queue output archive 分页补齐早期 trace，不得把 preview 的 `hasMore=false` 当成完整历史；即使热状态为控制体积裁剪了早期 raw output，也要从结构化 `basePrompt/displayPrompt/promptHistory` 和 archive 合成完整用户输入与 agent trace，并且初始 prompt 默认显示注入前 prompt 而不是引用注入全文；当初始 prompt 含引用注入时，引用内容必须默认折叠，并只在 Trace 的初始消息中提供可展开的“最终传入 Codex 的真实完整 prompt”，不得再渲染独立 Prompt 全量卡片；多轮引用注入必须按上游/最早上下文在前、直接引用在后的顺序排列，每一轮必须有明确 `Reference Round N/M` 分割线和时间范围，不能用固定 6 轮截断引用链；点击队列引用按钮必须自动把该任务 ID 写入提交表单的引用输入框，引用任务 ID 创建新任务时必须自动注入 `bun scripts/cli.ts codex task <taskId>` 的提示；连续执行同一 prompt 应通过入队份数一次性生成多条任务，避免快速连点造成操作员误判。
|
||||
- `OA Event Flow` 子标签必须把主 server `oa-event-flow-backend` 后端渲染为 UniDesk React 控件，包括服务健康、事件表、tag 过滤、SSE live 状态、Trace/STEP stats 表、Code Queue/Pipeline 标签入口和显式原始 JSON 按钮；默认页面不得裸铺完整事件 JSON，事件表只展示结构化摘要，完整 envelope/payload 只能通过 `查看原始JSON` 打开。
|
||||
- `Code Queue` 子标签必须把主 server `code-queue-backend` 后端渲染为 UniDesk React 控件，包括多 queue lane、queue 内串行、queue 间并行、queue 合并（点击“合并 queue”后必须用公共 `UniDeskDialog` 打开独立小窗口，用下拉菜单选择源 queue；不得把源 queue 选择控件塞进正常提交任务的 Queue 选择区；合并后自动删除源 queue，只保留合并后的目标 queue，目标 queue 按原 queueEnteredAt/createdAt 时间顺序串行）、任务 ID/复制任务 ID、引用按钮、任务耗时、任务提交/批量提交、引用任务 ID、创建成功提示、清空输入、模型下拉、显式入队份数、默认模型 `gpt-5.5`、MiniMax judge 状态、Codex CLI-like 输出流、attempt 终态、运行中追加 prompt、打断、手动重试和显式原始 JSON 按钮；Codex CLI-like 输出流必须始终保留任务的初始 `Submitted prompt` 和运行中 `Steer prompt`；整个 agent loop 消息流统一命名为专有名词 `Trace`，`Trace` 包含 assistant message、user prompt、system event 和 tool call；Code Queue 与 Pipeline/OpenCode messages 必须共用 `src/components/frontend/src/trace.tsx` 的 Trace 公共组件、统一 Trace item 接口和 codex/opencode port 适配层；连续 read/edit/run 工具调用只是在 Trace 内折叠为可展开工具调用组，汇总格式至少包含 `xx read, xx edit, xx run`，并展示读取文件、编辑文件、运行命令和耗时摘要；最近 3 个工具调用保持展开，工具调用内容不得自动换行且必须在工具调用块内部横向滚动，工具调用组展开后不得再增加额外左侧缩进；message 与 prompt 必须自动换行，普通 message 不显示左侧项目符号缩进且永不折叠；Trace 首屏可以是摘要预览，但终态任务被选中后必须自动在后台加载完整 Trace，手动“加载完整 Trace”也必须从 Code Queue output archive 分页补齐早期 trace，不得把 preview 的 `hasMore=false` 当成完整历史；即使热状态为控制体积裁剪了早期 raw output，也要从结构化 `basePrompt/displayPrompt/promptHistory` 和 archive 合成完整用户输入与 agent trace，并且初始 prompt 默认显示注入前 prompt 而不是引用注入全文；当初始 prompt 含引用注入时，引用内容必须默认折叠，并只在 Trace 的初始消息中提供可展开的“最终传入 Codex 的真实完整 prompt”，不得再渲染独立 Prompt 全量卡片；多轮引用注入必须按上游/最早上下文在前、直接引用在后的顺序排列，每一轮必须有明确 `Reference Round N/M` 分割线和时间范围，不能用固定 6 轮截断引用链；点击队列引用按钮必须自动把该任务 ID 写入提交表单的引用输入框，引用任务 ID 创建新任务时必须自动注入 `bun scripts/cli.ts codex task <taskId>` 的提示；连续执行同一 prompt 应通过入队份数一次性生成多条任务，避免快速连点造成操作员误判。
|
||||
- `Code Queue` 前端改进必须在同一任务内重建并上线公网 frontend，不能只修改源码或本地 bundle；重建 frontend 是无状态 WebUI 替换，不会导致 Code Queue 长期任务失败。已结束未读任务只能在 task card 边角显示类似未读消息的 `codex-unread-badge` 圆点和“标为已读”操作，不得把整张卡片改成红色/琥珀色失败态边框、背景或胶囊标签；状态栏的“结束未读”提示也不得使用失败态红色。
|
||||
- `Code Queue` 前端必须把 PostgreSQL-backed backend API 作为 task、queue、readAt/未读状态和 attempt 状态的唯一数据来源；不得用 `localStorage`、`sessionStorage` 或 IndexedDB 持久化这些业务状态，也不得在后端标记已读失败时伪造本地成功。前端允许保留 React 内存态、请求 in-flight guard 和本轮页面缓存，但刷新页面或切换设备后的状态必须完全由后端 PostgreSQL 数据恢复。
|
||||
- `Code Queue` 前后端通信必须采用渐进式披露：首屏只请求 queue/task 轻量摘要、必要的 selected preview 和小体积统计，不得默认拉取完整 transcript、raw output、原始 JSON 或全部历史任务；加载下一页或搜索分页时必须显式传递 `selected=0`、`includeActive=0`、`stats=0` 等价开关，避免每一页重复请求 selected/active/stats；点击/选中 task 后再按需加载 summary、prompt part、trace step、raw output 或完整 Trace。`read`/`mark all read` 应调用专用 mutation 并用后端返回的 patch 更新当前内存态，不能为了隐藏未读圆点而强制刷新完整 overview；请求仍需遵守 PostgreSQL 权威源，失败时不得本地伪造已读。Code Queue 性能问题应优先通过缩小 API 响应、分页/cursor、去重 in-flight 请求、短 TTL 且 mutation 失效的页面缓存和后端 SQL 聚合解决，避免以重写渲染层或把大 JSON 藏在 DOM/React state 中规避慢请求。
|
||||
- `Code Queue` 的 queue/session 左侧边栏必须提供 task 关键词搜索，并采用顶部对齐和内容高度优先布局：搜索栏、列表、分组和 task card 都不得用居中、space-between、stretch 或隐式等高网格去拉满侧栏高度；item 少时允许下半部分留空，不能把单个 item 拉高来铺满；每个 task card 必须显示 `最近更新: ...前` 这类相对更新时间，便于判断运行中的 Trace 是否卡住；`queued` task card 的状态徽标必须显示排队原因，例如 `QUEUED(PREV TASK)`、`QUEUED(MEM LIMIT)`。SSE/事件驱动刷新只能更新队列列表与当前选中任务的详情，不得因为其他任务产生 `task-step` 或 `task-updated` 而自动切换当前选中的 task；只有用户点击任务、提交新任务或显式切换 queue 才能改变选中任务。提交任务时必须立即锁定 prompt、引用 ID、queue、模型、工作目录、最大尝试和入队份数等输入控件，显示等待状态，并用前端 in-flight guard 阻止重复点击造成重复入队；当解析到多个待入队任务时必须显式要求用户勾选批量确认，防止 `---` 分隔或入队份数误操作导致错误传入多个任务。Trace 面板的主滚动条使用全站细窄现代滚动条；工具调用块内部的横向滚动必须可滚动但隐藏横向滚动条，避免移动端阅读被滚动条占用。公共 `TraceView` 的自动滚动必须采用 follow-tail 语义：只有当前滚动位置在底部附近时才跟随新增输出；用户手动向上滚动后立即暂停自动滚动，异步刷新不得把视图拉回底部，直到用户再次滚动到最底部才恢复自动跟随。
|
||||
- `Code Queue` 的 queue/session 左侧边栏必须提供 task 关键词搜索，并采用顶部对齐和内容高度优先布局：搜索栏、列表、分组和 task card 都不得用居中、space-between、stretch 或隐式等高网格去拉满侧栏高度；item 少时允许下半部分留空，不能把单个 item 拉高来铺满；每个 task card 必须显示 `最近更新: ...前` 这类相对更新时间，便于判断运行中的 Trace 是否卡住；`queued` task card 的状态徽标必须显示排队原因，例如 `QUEUED(PREV TASK)`、`QUEUED(MEM LIMIT)`。Code Queue 的事件驱动刷新必须订阅统一 `oa-event-flow` 的 `service:code-queue` tag stream，并消费 `trace-stats-updated` 等统计变化事件；旧 Code Queue 私有 SSE 不得作为 Trace/STEP 刷新权威。左侧 STEP、执行过程摘要页的 read/edit/run/STEP 只能显示 `oa_trace_stats` 投影值；投影缺失时显示同步中/`--`，不得回退到 task JSON、transcript 或前端 `toolCallCount` 重算。事件驱动刷新只能更新队列列表与当前选中任务的详情，不得因为其他任务产生 `task-step` 或 `task-updated` 而自动切换当前选中的 task；只有用户点击任务、提交新任务或显式切换 queue 才能改变选中任务。提交任务时必须立即锁定 prompt、引用 ID、queue、模型、工作目录、最大尝试和入队份数等输入控件，显示等待状态，并用前端 in-flight guard 阻止重复点击造成重复入队；当解析到多个待入队任务时必须显式要求用户勾选批量确认，防止 `---` 分隔或入队份数误操作导致错误传入多个任务。Trace 面板的主滚动条使用全站细窄现代滚动条；工具调用块内部的横向滚动必须可滚动但隐藏横向滚动条，避免移动端阅读被滚动条占用。公共 `TraceView` 的自动滚动必须采用 follow-tail 语义：只有当前滚动位置在底部附近时才跟随新增输出；用户手动向上滚动后立即暂停自动滚动，异步刷新不得把视图拉回底部，直到用户再次滚动到最底部才恢复自动跟随。
|
||||
- 用户服务页面不得 iframe 业务旧前端、Todo Note 原 Vite 前端或 Pipeline 自身 WebUI，不得把用户服务后端端口暴露为浏览器直连 URL，也不得把业务 API 的 JSON 裸铺在页面上。
|
||||
- `Pipeline` 子标签是 D601 `/home/ubuntu/pipeline` 的 UniDesk host UI。
|
||||
- Pipeline 仓库自带 WebUI 前端已经废弃；UniDesk frontend 是唯一用户可见的 Pipeline UI。
|
||||
- Pipeline 用户服务只提供 backend/control API，UniDesk 通过 `/api/microservices/pipeline/proxy/...` 拉取 snapshot、Gantt DTO、node detail 和控制接口。
|
||||
- Pipeline 页面必须通过同源用户服务代理展示 `model/minimax-m27` 的 MiniMax 限额，包括当前窗口总量/已用/剩余、重置时间和查询状态；主界面不得展示 API key，完整 quota JSON 只能通过显式 `查看原始JSON` 打开。
|
||||
- Pipeline 控制与观测的最终权威是 100% OA 事件流；分阶段迁移不得在交付态保留点对点控制、旧审核事件或旧 batch 推进逻辑，完整规则见 `docs/reference/pipeline-oa-event-flow.md`。
|
||||
- Pipeline 控制与观测的最终权威是统一 `oa-event-flow` 事件流与 Pipeline OA 状态机；分阶段迁移不得在交付态保留点对点控制、旧审核事件或旧 batch 推进逻辑，共享事件表与 tag 订阅规则见 `docs/reference/oa-event-flow.md`，Pipeline 控制流完整规则见 `docs/reference/pipeline-oa-event-flow.md`。
|
||||
- 基础视图必须包含组件矩阵、React Flow 控制图框图、epoch 列表、运行材料索引、epoch 甘特图和 node 精细控制面板。首屏信息顺序必须把核心操作前置：`控制图` 是 Pipeline hero 之后的第一个业务面板，`Epoch 甘特图` 紧随其后；观测指标、评分器、MiniMax 限额、OA 事件流和组件矩阵只能排在这两个核心面板之后，移动端也必须保持同一 DOM 顺序。控制图和甘特图的右侧详情栏默认收起，主图占满可用宽度；点击控制图 node 或甘特图执行线/事件点后才展开对应右侧栏，并必须提供手动收起入口。
|
||||
- Pipeline scorer 结果必须结构化展示为 `x/N`、通过率、scorer 状态、item pass/fail badge 和 raw inspector 入口；主界面不得裸展示 scorer JSON。
|
||||
- 用户点击控制图中的 node 后，必须通过同源用户服务代理抓取该 node 执行过程，并支持向运行中 node 追加 prompt、给下次尝试下发 guide、对已完成 node 排队 modify、提交 monitor 审核 approve，以及排队 restart/redo。
|
||||
@@ -125,9 +132,9 @@ frontend shell 必须把左侧主模块与顶部子标签编译为统一的 URL
|
||||
- run 级图形事实数据使用 `GET /api/node-control/runs/{runId}?view=timeline&tail=N`；该接口不得要求返回后端 y 坐标。
|
||||
- node 级 OpenCode 明细来自用户选择后的 `GET /api/node-control/runs/{runId}/nodes/{nodeId}`，避免跨 UniDesk provider HTTP 代理时一次性拉取全 run 的大体积 step 数组。
|
||||
- 这些 monitor/control 事件的权威来源是 Pipeline OA 事件流；Pipeline 后端会为每条事件自动附加当前 `epoch:{runId}` 与 `pipeline:{pipelineId}` scope tag，并在 monitor 订阅时自动追加同一组 scope 限制，避免不同 epoch 之间串流。UniDesk 只消费 Pipeline 暴露的结构化读接口，不直接依赖旧的 monitor append 文件语义；OA 事件流的完整约束见 `docs/reference/pipeline-oa-event-flow.md`。
|
||||
- prompt 点来源于 attempt 级 `controlEventRecords` 中的 prompt-delivered 事件，必要时回退到 `controlPromptRecords` / `monitorPromptRecords`。
|
||||
- prompt 点只能来源于 attempt 级 `controlEventRecords` 中的 prompt-delivered 事件；`controlPromptRecords` / `monitorPromptRecords` 只能作为旧数据取证字段，不得参与交付态 UI 渲染或补点。
|
||||
- Monitor prompt 点必须将 `node-finished`、`node-long-running-observation` 作为一等结构化事件展示；`node-finished` 是中性完成事实，不得携带是否审核的权威策略字段。是否需要审核由 OA backend 根据当前 epoch 的 Pipeline config/topology 判定；审核开启时同一个 node completion 在 UI 中只保留一条完成/等待审核点，不得再生成独立 `legacy node audit request event` 或 `legacy monitor audit request event` 点。
|
||||
- 控制点和 monitor/人工控制箭头来源于 run 级 `controlEvents`，必要时回退到 `controlCommands`。
|
||||
- 控制点和 monitor/人工控制箭头只能来源于 run 级 `controlEvents`；`controlCommands` 不得作为 Gantt/UI 补点或控制显示 fallback。
|
||||
- 控制事件必须依赖后端记录的 `sourceKind`、`sourceNodeId`、`targetNodeId`、`commandId`、`eventId`、`resetNodeIds` 和 `interruptedProcedureRunIds` 等结构化字段识别 monitor、UniDesk frontend、CLI 等发起者，不能通过解析 monitor 自己的 step 文本来反推。
|
||||
- `Pipeline` monitor 审核与详情展示。
|
||||
- Pipeline 页面必须提供结构化 `OA 事件流` 诊断面板，通过 `/api/microservices/pipeline/proxy/api/oa-event-flow/diagnostics` 展示 100% 事件流模式、禁止残留数、no-audit 证据、monitor 审核证据、控制 queued/applied 计数和近期 run 证据；原始 diagnostics 只能通过 `查看原始JSON` 打开。
|
||||
|
||||
Reference in New Issue
Block a user