pikasTech-unidesk/docs/reference/pipeline-oa-event-flow.md

Pipeline OA Event Flow

Pipeline 的最终控制模型必须是 100% OA 事件流驱动。开发过程可以分阶段迁移，但交付态不能保留中间态、双写语义、点对点控制通道或依赖旧事件的永久兜底；任何阶段性兼容只能作为局部迁移手段，必须在同一重构闭环内被删除并由 E2E 证明已退出。

Core Principles

• OA backend 是 Pipeline runtime 的唯一控制总线；node、monitor、runner、UniDesk frontend 和 CLI 都只能通过 OA 事件表达事实、订阅事实或发出控制意图。
• Node 之间不得直接启动、暂停、重试或通知彼此；monitor 不得绕过 OA 直接控制 runner；frontend 不得直接写 Pipeline .state、prompt 文件、命令队列或 worker 状态文件。
• 事实事件只描述已经发生的事实，策略判断由 OA 加载 Pipeline config/topology 后完成；node-finished 不得携带 legacy audit policy flag、nextNodeIds、shouldStartDownstream 这类控制决策字段。
• 控制行为必须由 OA 控制/管理事件表达，例如 start downstream、pause、resume、single-step、append prompt、guide、modify、approve、redo/restart、skip、cancel 和 retry。
• UI、CLI、E2E 和调试工具都应消费 OA 归一化读接口或通过 OA 控制 API 写入事件，不得解析 monitor 文本、worker log、runner 私有文件或旧 JSONL 文件来反推控制语义。
• 旧的本地文件传输通道必须完全退出控制路径：不得创建、轮询或依赖 control-prompts.jsonl、monitor-prompts.jsonl、monitor-control、control-events.jsonl、monitor stop 文件、.state/pipeline-runs/{runId}/control/commands/ 或给 monitor 容器挂载可读 /pipeline-state 来完成 prompt、stop、guide、approve、redo/restart、append 或 UI/Gantt 事件取证。

Event Identity And Tags

• 每条事件必须有稳定 eventId、type、createdAt、sourceKind、sourceId、correlationId 和可选 causationId，用于排序、幂等、回放和追踪控制来源。
• Pipeline 后端必须自动附加 scope tag：pipeline:{pipelineId}、epoch:{runId}，node 相关事件还必须带 node:{nodeId}；attempt/procedure 相关事件应带 attempt:{attemptId} 或 procedure:{procedureRunId}。
• Monitor 在 config 中只声明要订阅的业务 tag 或事件类型，OA backend 在订阅时自动追加当前 pipeline:{pipelineId} 与 epoch:{runId} 限制，避免不同 pipeline 或 epoch 串流。
• 一次 epoch 应绑定 config snapshot 或 config version；OA 的审核、拓扑推进、并发和单步策略都以该快照为准，避免运行中配置漂移导致控制解释不一致。
• 控制事件必须有幂等键，重复投递同一个 start、approve、redo/restart 或 append prompt 时，OA 应识别为同一意图而不是重复启动或重复写入。

Fact Events

• node-started、node-finished、node-failed、node-cancelled、node-long-running-observation 等事实事件用于记录运行状态，不承担流程推进决策。
• node-finished 是中性完成事实，包含 node id、procedure run id、status、timestamps、outputs summary 和诊断摘要；它不描述是否需要审核，也不直接声明下游节点。
• 长任务观察事件只在 node 未进入终态时触发，默认节奏为 2、5、10、20 分钟，之后每 20 分钟循环；固定 30 秒 monitor 周期不得作为正式机制保留。
• legacy batch completion gate 只能作为派生统计或兼容只读事件，不能作为流程推进门禁；下游推进由每个 node-finished 加 OA config/topology 判断完成。
• 如果 node 完成后需要 monitor 审核，UI 中仍只应保留这一条 node-finished 作为完成/等待审核的事实点，不再创建独立的 legacy node audit request event 或 legacy monitor audit request event 事实点。

No-Audit Flow

1. Runner 观察到 node 进入终态，并把中性 node-finished 事实推入 OA backend。
2. OA backend 记录事件，加载该 epoch 的 config snapshot 和 topology。
3. OA 判定该 node 不需要 monitor 审核，且下游依赖已满足。
4. OA 产生下游 start-node 控制事件。
5. Runner 只消费 OA 控制事件来启动下游 node，并把启动结果再写回 OA 事件流。

Audit Flow

1. Runner 把中性 node-finished 事实推入 OA backend。
2. OA backend 记录事件，并按 config snapshot 判定该 node completion 需要 monitor 审核。
3. Monitor 通过 OA 订阅收到同一 scope 下的 node-finished 事实和 prompt；是否需要审核来自 OA policy，不来自 node-finished.detail。
4. Monitor 通过 OA skill 或等价 OA 控制 API 发出 approve、modify、redo/restart、reject 等管理事件。
5. OA backend 记录 monitor 决策，按 config/topology 产生 start downstream、reset downstream、restart target 或 stop/pause 等后续控制事件。
6. Runner 只消费 OA 控制事件执行后续动作，执行结果继续回写 OA 事件流。

Single-Step And Debug Flow

• 单步运行、人工放行、暂停、恢复、重试、跳过和取消都必须建模为 OA 控制事件；不得通过调试 HTTP 端点直接修改 runner 内存状态。
• CLI 和 UniDesk frontend 的 node 精细控制面板只能调用 Pipeline 后端的 OA 控制 API；后端可保留 node-control 路由名，但路由内部必须写入 OA 事件并由 OA dispatcher 执行。
• Debug 工具可以读取事件流、config snapshot 和归一化状态机结果，但不得维护另一套流程推进逻辑。

Rendering Contract

• UniDesk Pipeline UI 只消费 Pipeline 后端根据 OA 事件流生成的 snapshot、Gantt DTO、node detail 和 control history，不直接消费旧 monitor append 文件语义。
• 甘特图中的执行条、prompt 点、monitor 决策点、长任务观察箭头和人工控制箭头都必须来自 OA 事件或 OA 派生 DTO。
• 有 monitor 的 pipeline 中，monitor node 固定在甘特图第 1 列，其余 node 再按拓扑上游到下游向右排列。
• node-long-running-observation 必须画从被观察 node 到 monitor node 的观察连线；被观察 node 上不得额外绘制“观察来源”点，因为点只代表真实行为。
• Running node 必须显示从实际开始时间延伸到当前时间的实时闪动执行条；相邻 OpenCode step 之间的真实空闲区间必须留白，不能被连续装饰线误渲染为执行。
• 审核开启时不得同时渲染 node-finished 和独立 audit-request 点；node completion 是唯一完成/等待审核点，monitor 的 approve/modify/redo/restart 是后续独立控制点。

Migration And Completion Gates

• 分阶段重构只允许按“schema 文档与测试门禁 -> OA 事件写入 -> OA dispatcher 接管控制 -> UI/CLI 改为 OA 读写 -> 删除旧事件和旧控制路径”的方向前进，不得把双写/双读作为最终设计。
• 完成态必须删除或禁用以下残留：legacy detail audit policy flag 作为权威策略字段、legacy node audit request event / legacy monitor audit request event 独立审核请求事件、legacy batch completion gate 控制推进、monitor 直接调用 runner、node 直接启动下游、frontend/CLI 直接写 .state 文件。
• 完成态还必须删除文件传输残留：PIPELINE_MONITOR_APPEND_FILE、PIPELINE_MONITOR_STOP_FILE、PIPELINE_MONITOR_CONTROL_DIR、PIPELINE_NODE_PROMPT_APPEND_FILE、control-events.jsonl、runControlEventFile、appendJsonLine、readJsonLineRecords、readPromptAppendFile、parseCommandFile、parseMonitorCommandFile、readMonitorCommands、fallbackMonitorInterventions、syntheticMonitorStopPrompt 以及 monitor 的 /pipeline-state 挂载都不得出现在运行代码中。
• E2E 必须覆盖有审核与无审核两条链路：无审核时由 OA 从 node-finished 推进下游；有审核时由 monitor 经 OA 控制事件推进下游；事件都必须带 pipeline:{pipelineId} 与 epoch:{runId} tag。
• Pipeline 甘特图 E2E 必须证明没有重复审核点、长任务观察有连线且无来源伪点、running node 有实时条、OpenCode step 空闲区间留白、控制箭头来自 OA 控制事件。
• 代码检查应加入防回归搜索或等价单元测试，防止重新引入 legacy audit policy flag 权威字段、旧 audit-request 事件、legacy batch completion gate 推进逻辑或非 OA 控制写路径。