目录

​

• 一、概述与架构全景
• 二、核心概念模型
• 三、ActivityType 活动类型体系
• 四、引擎层设计
• 五、HUMAN 一等公民体系
• 六、SceneGroup 场景组体系
• 七、AGENT_EVENT 事件钩子体系
• 八、SSE 事件体系
• 九、六层上下文模型
• 十、Transition/Route 路由体系
• 十一、Guard 守卫机制
• 十二、部署架构
• 十三、模块清单与文件映射

一、概述与架构全景

1.1 平台定位

OODER 是一个以 Workflow 为驱动的 AI 原生应用开发平台。它的核心是将 NLP 管道、AI Agent、人工审批、事件驱动等能力统一抽象为 流程定义 (ProcessDefinition)，通过统一的 SkillFlowEngine 驱动执行，实现"一次编排、多处运行"。

1.2 核心设计原则

• 流程驱动：所有执行路径由 ProcessDefinition 定义，引擎按图驱动，避免分散的分支逻辑
• HUMAN 一等公民：人工节点具有发送/特送/收回/退回/委托/暂停/恢复/终止等完整操作集，操作状态通过 SSE 实时透传前端
• SG 独立封闭：SceneGroup 是自驱动单元，流程不可调度 SG 内部节点，SG 拥有独立的上下文、快照和任务调度能力
• AGENT_EVENT 自活：事件钩子自动注册、自主激活、强制分支分裂，支持 JOIN_BACK / MERGE_JOIN / AUTO_ADVANCE 三种合并模式
• 六层上下文：SYSTEM / PROCESS / KNOWLEDGE / HISTORY / WORKING / EPHEMERAL 六层严格分层，通过 ContextLayerManager 统一管理
• SSE 全链路闭环：从流程启动到活动执行到结果推送，事件驱动前端渲染，覆盖 27+ 事件类型

1.3 三层架构全景

1.4 统一执行模型演进

原存在 5 套并行执行模型（NlpPipeline / ScenarioOrchestrator / SkillFlowNode / SkillFlowExecutionEngine / WorkflowEngine），已统一为 SkillFlowEngine 单入口：

LocalEngine

= 当前 SkillFlowExecutionEngine + WorkflowEngine 合并，在 studio 进程内运行
RemoteEngine

= BPM WorkflowEngine 代理（aiserver），通过 HTTP 调用远程执行
RecoveryEngine

= 从 ActivityInstance.checkpoint 恢复执行（冷启动），@PostConstruct 加载非终态实例

二、核心概念模型

2.1 ProcessDefinition（流程定义）

流程定义是 workflow 的静态蓝图，描述从输入到产出的有向 DAG 图：

属性	类型	说明
processDefId	String	流程定义唯一ID e.g. “rad-scene”, “bpm-scene”
name	String	流程名称 e.g. “RAD组件设计”
version	int	版本号
workMode	String	工作模式：architect / business / work
classification	String	分类：architect / business / all
roundType	String	轮次类型：first (首轮) / multi (多轮)
activities	List	活动定义列表
transitions	List	迁移路线列表
swimLanes	List	泳道定义（SG 分组）
guardConfig	GuardConfig	守卫配置（回退策略等）

2.2 ActivityDefinition（活动定义）

活动是流程中的最小执行单元，由 ActivityType 决定执行语义，子模式进一步细化：

属性	类型	说明
activityId	String	活动唯一ID
activityType	ActivityType	活动类型：TASK / LLM_AGENT / HUMAN / AGENT_EVENT / SUBPROCESS / CALL_ACTIVITY / START / END
taskMode	TaskMode	TASK 子模式：SKILLS / SCENE_GROUP / SERVICE / SCRIPT
humanMode	HumanMode	HUMAN 子模式：CONFIRM / FORM / APPROVAL / DELEGATE
llmMode	LlmMode	LLM_AGENT 子模式：SINGLE / HARNESS / PROGRESSIVE
eventMergeMode	EventMergeMode	AGENT_EVENT 合并模式：JOIN_BACK / MERGE_JOIN / AUTO_ADVANCE
sceneGroupId	String	关联的场景组ID，taskMode=SCENE_GROUP 时必填
splitMode	SplitMode	分支模式：SEQUENCE / XOR_SPLIT / AND_SPLIT / OR_SPLIT / EVENT_SPLIT
joinMode	JoinMode	汇聚模式：AND_JOIN / XOR_JOIN / OR_JOIN
skillId	String	绑定的 Skill ID（TASK 模式下）
config	Map	扩展配置（operations 列表、LLM 配置等）

2.3 ProcessInstance（流程实例）

流程的一次运行实例，管理全生命周期状态：

状态	说明
PENDING	待启动
RUNNING	运行中
PAUSED	暂停（等待 HUMAN 确认/事件触发）
SUSPENDED	挂起（HUMAN 收回/退回等待）
COMPLETED	正常完成
FAILED	执行失败
CANCELLED	人工取消
ARCHIVED	已归档

2.4 ActivityInstance（活动实例）

状态	说明
PENDING	待执行
RUNNING	执行中
COMPLETED	正常完成
FAILED	执行失败
PAUSED	暂停等待
SKIPPED	已跳过
WITHDRAWN	已收回（HUMAN 收回操作）
RETURNED	已退回（HUMAN 退回操作）
EVENT_WAITING	事件等待（AGENT_EVENT 专用）

三、ActivityType 活动类型体系

3.1 8 值精简体系

从原有 13+ 枚举值精简为 8 值（6 核心 + 2 边界），子模式进一步细分执行语义：

类型	类别	子模式	说明
START	边界	—	流程起始节点，流程实例创建后自动进入
END	边界	—	流程结束节点，到达后设置 ProcessInstance.COMPLETED
TASK	核心	SKILLS / SCENE_GROUP / SERVICE / SCRIPT	自主驱动任务。SKILLS 编排 Skill 执行；SCENE_GROUP 进入 SG 自驱动
LLM_AGENT	核心	SINGLE / HARNESS / PROGRESSIVE	LLM 交互节点。SINGLE 单次 FC-Loop；HARNESS 多轮+校验；PROGRESSIVE 渐进式自决策
HUMAN	核心	CONFIRM / FORM / APPROVAL / DELEGATE	人工节点。一等公民，10 种操作，支持特送/收回/退回/委托
AGENT_EVENT	核心	eventMergeMode: JOIN_BACK / MERGE_JOIN / AUTO_ADVANCE	事件钩子。自活节点，强制分支分裂，条件满足后合并回主流程
SUBPROCESS	子流程	—	子流程嵌入。父流程可调度内部节点，子流程 HUMAN 阻断父流程
CALL_ACTIVITY	子流程	—	流程跳转/外部流程调用，支持跨流程实例调用

3.2 已移除/合并的旧类型

旧类型	去向
LLM_CALL	→ 合并到 LLM_AGENT（fromCode 保持兼容）
HUMAN_AGENT	→ 合并到 HUMAN + humanMode 区分
HUMAN_TASK	→ 合并到 HUMAN + humanMode 区分
AGENT_TASK	→ 合并到 TASK + taskMode 区分
GATEWAY	→ 由 SplitMode/JoinMode + Transition 承载
LOOP	→ 由 Transition.BACKWARD + maxRetry 承载
SERVICE	→ 合并到 TASK (config.taskMode=“service”)
SCRIPT	→ 合并到 TASK (config.taskMode=“script”)
SCHEDULED_TRIGGER	→ 合并到 AGENT_EVENT (config.eventType=“timer”)

3.3 ActivityType → BPM 平台映射

scene-engine 使用 8 值 ActivityType，aiserver/BPM 平台使用 9 值实现枚举进行引擎分派：

ActivityType	→ ActivityDefImpl	引擎分派
TASK (SKILLS)	Tool	serviceEngine
TASK (SCENE_GROUP)	Block	阻塞服务（场景服务）
TASK (SERVICE)	Service	agentEngine
LLM_AGENT	Service	agentEngine
HUMAN	No	rightEngine（权限控制）
AGENT_EVENT	Event	eventEngine
SUBPROCESS	SubFlow	子流程
CALL_ACTIVITY	OutFlow	外部流程
START / END	Process	边界

四、引擎层设计

4.1 SkillFlowEngine — 统一流程引擎

SkillFlowEngine 是流程执行的统一入口，职责：

• 加载 & 注册 ProcessDefinition
• 创建 ProcessInstance 并驱动执行
• 按 ActivityType 分派到不同执行器
• 管理活动间路由（RouteToEngine）
• 持久化流程实例状态
• 冷启动恢复（@PostConstruct 加载非终态实例）

核心执行循环

startExecution(processDefId, context)
  → 创建 ProcessInstance (PENDING)
  → 获取 START 活动的出边活动
  → 加入 activityQueue
  → 循环:
      取出活动 → executeActivity(actDef)
        → 按 ActivityType 分派:
          TASK       → executeTaskActivity()
          LLM_AGENT  → executeLlmAgent()
          HUMAN      → executeHumanActivity()
          AGENT_EVENT→ executeAgentEvent()
          SUBPROCESS → executeCallActivityActivity()
          CALL_ACTIVITY → executeCallActivityActivity()
      → RouteToEngine.resolveRoute()
        → 决定下一个活动
      → 更新 ProcessInstance 状态
  → 直到 END 或 PAUSED

4.2 RouteToEngine — 路由引擎

统一路由分派，根据 ActivityType 走不同路由策略：

路由方法	处理类型	说明
resolveTaskRoute()	TASK	内部分 taskMode：SKILLS→skillId 绑定执行推进；SCENE_GROUP→进入 SG 自驱动
resolveLlmAgentRoute()	LLM_AGENT	内部分 llmMode：SINGLE→单次 FC-Loop；HARNESS→多轮+校验；PROGRESSIVE→渐进式
resolveHumanRoute()	HUMAN	先检查 HUMAN 一等公民操作（SPECIAL_SEND/WITHDRAWN/RETURNED/DELEGATE），再走默认路由
resolveAgentEventRoute()	AGENT_EVENT	事件注册 → 主分支继续 → 事件分支等待 → 触发后汇总
resolveSceneGroupRoute()	TASK(SCENE_GROUP)	检查当前 scene 完成状态，全部完成则推进到下一活动

4.3 ActivityRouteResult — 路由结果

路由结果枚举，决定引擎下一步行为：

RouteAction	含义	引擎行为
AUTO_ADVANCE	自动推进	continueExecution() 继续循环
LLM_DISPATCH	LLM 调度	等待 LLM 通过 routeTo 指定下一步
HUMAN_CHOICE	人工选择	等待用户选择路由
EVENT_WAIT	事件等待	暂停分支等待事件触发
TASK_COMPLETE	任务完成	标记完成
NO_MATCH	无路由	触发 guard_escalation
SPECIAL_SEND	特送	continueExecution() 跨步骤跳转
WITHDRAWN	收回	仅终止当前分支不推进
RETURNED	退回	有显式 target 时 continueExecution，否则 legacy routeToNext 处理 BACKWARD
DELEGATED	委托	continueExecution() 路由到委托目标

4.4 FlowDefId — 流程定义枚举

完整的 18 个流程定义枚举，按分类和轮次类型组织：

枚举值	流程定义ID	分类	轮次类型	说明
INTENT_DISPATCH	intent-dispatch	all	first	意图分发流程
RAD_SCENE	rad-scene	architect	first	RAD 组件设计
BPM_SCENE	bpm-scene	architect,business	first	BPM 流程编排
DEEP_DESIGN_SCENE	deep-design-scene	architect	multi	深度设计
PAGE_DEBUG_SCENE	page-debug-scene	architect,business	multi	Page 调试
PATENT_REVIEW_SCENE	patent-review-scene	business	first	专利审查
KNOWLEDGE_INIT_SCENE	knowledge-init-scene	architect	first	知识库初始化
DBFIRST_BUILD	dbfirst-build	architect	first	数据库优先构建
VIEWFIRST_BUILD	viewfirst-build	architect	first	视图优先构建
DESIGNERFIRST_BUILD	designerfirst-build	architect	first	设计器优先构建
PERSISTENCE_LAYER_SUBFLOW	persistence-layer-subflow	architect	first	持久层子流程
QUALITY_VALIDATION_SUBFLOW	quality-validation-subflow	all	multi	质量校验子流程
ARCHITECT_PIPELINE	architect-pipeline	architect	first	架构师流水线
BUSINESS_PIPELINE	business-pipeline	business	first	业务流水线
UNDERSTAND_SUBFLOW	understand-subflow	all	first	理解子流程
COMPONENT_GENERATE_SUBFLOW	component-generate-subflow	architect	first	组件生成子流程
LLM_FALLBACK_SUBFLOW	llm-fallback-subflow	all	multi	LLM 回退子流程
INTEGRATE_SUBFLOW	integrate-subflow	architect	first	集成子流程
BUSINESS_INTEGRATE_SUBFLOW	business-integrate-subflow	business	first	业务集成子流程

FlowDefId 分类规则

维度	值域	说明
classification	architect / business / all	architect: 架构师流程，business: 业务人员流程，all: 通用
roundType	first / multi	first: 首轮执行，multi: 多轮迭代执行

五、HUMAN 一等公民体系

5.1 设计原则

• HUMAN 是 Workflow 中的一等公民，拥有完整的操作集合
• 操作分两类：默认可用（无需 DESIGNER 定义）和 需 DESIGNER 显式定义
• HUMAN 状态和操作通过 SSE 实时推送前端渲染
• HUMAN 节点的操作路由优先级高于默认的 _taskCompleted 检测

5.2 HumanOperation — 11 种操作

操作	说明	是否需要DESIGNER定义	图标
SEND	发送（正常推进）	否	ri-send-plane-line
PAUSE	暂停	否	ri-pause-circle-line
RESUME	恢复	否	ri-play-circle-line
TERMINATE	终止	否	ri-stop-circle-line
SPECIAL_SEND	特送（跨步骤跳过中间节点）	是	ri-skip-forward-line
WITHDRAW	收回（已发送但未执行的活动收回）	是	ri-arrow-go-back-line
RETURN	退回（Transition.BACKWARD + maxRetry）	是	ri-close-circle-line
DELEGATE_H2A	委托给 Agent	是	ri-robot-line
DELEGATE_H2H	委托给他人	是	ri-user-shared-line
DELEGATE_H2T	委托给 Task	是	ri-flashlight-line
INTERVENE_EXCEPTION	例外介入（守卫触发时）	否	ri-error-warning-line

5.3 HUMAN “显示生命” 闭环

闭环链路：

HumanOperationEngine.getAvailableOperations()
  → SkillFlowEngine.executeHumanActivity()
  → 写入 _availableOperations_{actId}
  → SseEventPushListener SSE 推送
  → 前端 _renderHumanOperationBar 动态渲染

5.4 HUMAN 一等公民操作路由（Phase A-2）

RouteToEngine.resolveHumanRoute 必须在 _taskCompleted 检查前先调用 checkHumanOperationRoute：

优先级	操作	context/status 标记	路由行为
1	SPECIAL_SEND	_specialSendFrom + _routeToActivityId	跨步骤 routeTo 目标，continueExecution
2	RETURNED	actInstance.status=RETURNED + _returnFrom + _returnToActivityId(可选)	有 target 时 continueExecution，否则 legacy routeToNext 处理 BACKWARD
3	WITHDRAWN	actInstance.status=WITHDRAWN	仅终止当前分支不推进
4	DELEGATED	_delegatedFrom_{actId} + _delegateType_{actId} + _delegateConfig_{actId}	路由到委托目标，continueExecution

5.5 前端渲染策略

• 默认操作（SEND/PAUSE/RESUME/TERMINATE）：始终显示，不由 config.operations 控制
• 设计器定义的操作：由 DESIGNER 的 config.operations 列表控制显示
• INTERVENE_EXCEPTION：守卫触发时才显示，不在 config.operations 中配置
• 所有操作按钮通过 SSE 事件 human_operation_bar 动态渲染，由 _renderHumanOperationBar 处理

六、SceneGroup 场景组体系

6.1 SG 定义

SceneGroup (SG) 是 Workflow 中的泳道 (SwimLane)概念。每个 SG 是独立封闭的自驱动单元，流程可通过注入上下文影响但不能调度 SG 内部节点。

6.2 SG 分类

SG-UNDERSTAND理解RouteAgent意图路由分发SG-UNDERSTANDSG-DESIGN设计MCPAgent调用外部设计工具SG-DESIGNSG-GENERATE生成MCPAgent调用代码生成服务SG-GENERATESG-QUALITY质量CoordinatorAgent多Agent协调校验SG-QUALITYSG-INTEGRATE集成RouteAgent模块间路由SG-INTEGRATE

6.3 SG vs SUBPROCESS 关键区别

维度	SUBPROCESS（子流程）	SCENE-GROUP（场景组）
调度权	父流程可调度子流程内部节点	父流程不可调度SG 内部节点
上下文	子流程共享父流程上下文	SG 独立上下文，仅通过注入影响
HUMAN 行为	子流程 HUMAN阻断父流程	SG 内 HUMAN不阻断，仅驱动场景
自管理	子流程由父流程驱动	SG自驱动，独立管理快照/进度/任务调度
返回方式	子流程按节点返回	SG 完整交付任务后整体返回
LLM 配置	从父流程继承	继承自 SG 配置或可选择从流程继承

6.4 SG 执行模型

引擎遇到 TASK(taskMode=SCENE_GROUP)：
  ① 读取 sceneGroupId + sceneGroupContextInjection
  ② 获取/创建 SG 实例（SceneGroupManager）
  ③ 注入流程上下文 → SG.businessContext
  ④ 激活 SG（SceneGroup.activate()）
  ⑤ 引擎将当前 ActivityInstance 设为 PAUSED(eventWait)
  ⑥ SG 自驱动执行（内部独立管理）

SG 执行期间：
  - SG 独立管理快照/进度/任务调度
  - SG 内 HUMAN 不阻断外部流程
  - SG 内 LLM 配置继承自 SG

SG 完成后：
  - 设置 SceneGroupOutput（taskStatus/taskSummary/artifacts）
  - 通知引擎 → resumeActivity
  - 写入 SG 产出物到 processInst.context
  - 沿 Transition 推进到下一活动

6.5 SG 输出契约 (SceneGroupOutput)

字段	类型	说明
taskStatus	String	“completed” | “failed” | “partial”
taskSummary	String	任务摘要文本
contextUpdates	Map<String,Object>	SG 上下文变更，合并到流程上下文
artifacts	List	产出物列表（代码、文档、配置等）
phaseDeliverables	Map<String,Object>	阶段目标交付物（用于多轮迭代）
auditLog	List	运行历程，用于审计和回溯

6.6 SG 内 HUMAN 不阻断策略

策略	说明
AUTO_HANDLE	SG 自动处理 HUMAN 节点（使用默认值/自动选择），不暂停 SG
SCENE_DRIVE	HUMAN 操作仅作为场景驱动因素记录到 auditLog，不阻断 SG 执行
CRITICAL_PAUSE	仅在关键决策点暂停 SG（SG 内部 PAUSED），不影响外部流程

七、AGENT_EVENT 事件钩子体系

7.1 设计原则

• AGENT_EVENT 是自活节点（self-live），不需要引擎主动激活
• 遇到 AGENT_EVENT 时强制分支分裂：主分支继续执行，事件分支暂停等待
• 事件触发后，事件分支根据 eventMergeMode 决定如何合并回主流程

7.2 三阶段生命周期

1. 埋点 (EVENT_WAITING)：引擎遇到 AGENT_EVENT，注册事件订阅，创建事件分支，设置 ActivityInstance.status=EVENT_WAITING
2. 触发 (AgentEventBridge 匹配)：条件满足时激活事件分支，AgentEventBridge.handleEventForSubscription() 被调用
3. 自活 (activateEventBranch)：创建一级图层，沿事件分支推进，事件节点按 eventMergeMode 合并

7.3 Hook 生命周期追踪

阶段	说明	SSE 推送
onRegistered	事件订阅已注册到 AgentEventBridge	flow_event_register
onMatched	事件条件已匹配成功	flow_event_matched
onEvent	事件正在处理中	flow_step(phase=event)
onComplete	事件分支已完成，准备合并	flow_step(phase=event_completed)

7.4 EventMergeMode — 事件合并模式

模式	说明
JOIN_BACK	事件完成后回到产生分裂的节点，重新执行该节点的后续路由
MERGE_JOIN	事件完成后到指定的 AND_JOIN 节点汇聚，等待所有分支到达后继续
AUTO_ADVANCE	事件完成后直接推进到当前节点的下一个活动，不等待也不回退

7.5 AGENT_EVENT 强制分裂实现

引擎遇到 AGENT_EVENT：
  ① 注册事件订阅（AgentEventBridge.registerSubscription）
  ② 查找非 AGENT_EVENT 出边（主分支继续）
  ③ 将主分支目标加入 activityQueue 继续执行
  ④ 创建 AGENT_EVENT 暂停分支（新 Token + 新 ActivityInstance）
  ⑤ 事件触发后 → AgentEventBridge.handleEventForSubscription()
     → 根据 eventMergeMode 决定汇聚方式:
       JOIN_BACK    → 回到分裂节点重新路由
       MERGE_JOIN   → 路由到 AND_JOIN 等待汇聚
       AUTO_ADVANCE → 直接推进到下一活动

八、SSE 事件体系

8.1 六层分类体系

8.2 SseEventAssembler 流程驱动事件

SseEventAssembler 将引擎内部事件统一组装为前端可消费的 SSE 事件格式：

事件名	触发时机	数据载荷
flow_step	每个活动执行完成	activityId, activityType, status, output, phase
flow_route	路由决策完成	fromActivity, toActivity, routeAction, reason
flow_artifact	活动产生产出物	activityId, artifactType, artifactData
flow_complete	流程整体完成	processInstId, finalStatus, summary

8.3 后端事件产生 → 推送路径

引擎内部事件ActivityEventSseEventAssembler事件组装SseEventPushListenerSSE 推送前端消费NlpChatInline

8.4 后端场景 → SSE 事件序列

场景	进入方式	SSE 事件序列
Designer 模式	RadChatScene	connected → flow_start → flow_plan → flow_step(tool_call) → flow_artifact → flow_complete
Build 模式	IntentDispatchScene → RadChatScene	connected → flow_start(intent_dispatch) → flow_step → flow_route → switch_scene_flow → flow_start(rad) → flow_step → flow_complete
Work 模式	WorkChatScene / SkillFlowChatScene	connected → flow_start → skill_match → skill_orchestrate → skill_execution_plan → flow_step(tool_call) → flow_artifact → flow_complete

8.5 前端 SSE 消费组件矩阵

组件	消费事件	渲染行为
SseChatInline	flow_step, token, thinking	逐 token 渲染 LLM 输出
ToolCallPanel	tool_call, flow_artifact	增量渲染工具调用卡片
FlowStatusBar	flow_start, flow_plan, flow_step, flow_complete	显示流程进度条
HumanOperationBar	human_operation_bar, human_confirm	动态渲染操作按钮

8.6 前端 tool_call 分发逻辑

前端消费 tool_call 事件时，根据 toolName 分发到 30+ 处理器：

function dispatchToolCall(toolName, payload) {
  switch (toolName) {
    case 'createFile':
    case 'editFile':
    case 'deleteFile':
      → FileToolHandler
    case 'readFile':
    case 'searchFile':
      → ReadToolHandler
    case 'runCommand':
    case 'runScript':
      → ExecutionToolHandler
    case 'webSearch':
    case 'webFetch':
      → WebToolHandler
    case 'askHuman':
    case 'humanConfirm':
      → HumanToolHandler
    default:
      → GenericToolHandler
  }
}

8.7 SSE 事件对齐矩阵

前端 FlowConstants.SSE_EVENT 与后端实际推送事件的完整对齐：

后端事件	前端常量	消费组件
connected	SSE_CONNECTED	SseChatInline
error	SSE_ERROR	SseChatInline, FlowStatusBar
token	SSE_TOKEN	SseChatInline
thinking	SSE_THINKING	SseChatInline
step	SSE_STEP	SseChatInline
progress	SSE_PROGRESS	SseChatInline
tool_call	SSE_TOOL_CALL	ToolCallPanel
human_confirm	SSE_HUMAN_CONFIRM	HumanOperationBar
flow_artifact	SSE_FLOW_ARTIFACT	ToolCallPanel
flow_start	SSE_FLOW_START	FlowStatusBar
flow_plan	SSE_FLOW_PLAN	FlowStatusBar
flow_step	SSE_FLOW_STEP	FlowStatusBar, SseChatInline
flow_route	SSE_FLOW_ROUTE	FlowStatusBar
flow_complete	SSE_FLOW_COMPLETE	FlowStatusBar
switch_scene_flow	SSE_SWITCH_SCENE	FlowStatusBar
flow_event_register	SSE_EVENT_REGISTER	FlowStatusBar
flow_event_matched	SSE_EVENT_MATCHED	FlowStatusBar
skill_match	SSE_SKILL_MATCH	ToolCallPanel
skill_orchestrate	SSE_SKILL_ORCHESTRATE	ToolCallPanel
skill_execution_plan	SSE_SKILL_EXEC_PLAN	ToolCallPanel
harness_log	SSE_HARNESS_LOG	ToolCallPanel
scene_harness	SSE_SCENE_HARNESS	ToolCallPanel
harness_end	SSE_HARNESS_END	ToolCallPanel
human_operation_bar	SSE_HUMAN_OP_BAR	HumanOperationBar
guard_escalation	SSE_GUARD_ESCALATION	HumanOperationBar, FlowStatusBar
flow_status_update	SSE_FLOW_STATUS	FlowStatusBar

九、六层上下文模型

9.1 六层上下文定义

ContextLayerManager 统一管理六层上下文，每层隔离、可组合：

层级	名称	内容	生命周期
L1	SYSTEM	系统提示词、全局配置、LLM 基础参数	应用启动 → 关闭
L2	PROCESS	ProcessInstance 上下文，活动状态、路由决策记录	流程创建 → 结束
L3	KNOWLEDGE	知识库数据、VFS 文件内容、参考文档	流程创建 → 结束
L4	HISTORY	压缩后的历史记录、SkillExecutionSummary	活动开始 → 结束
L5	WORKING	当前活动的工作数据、LLM 中间结果	活动执行期间
L6	EPHEMERAL	临时数据、FC-Loop 瞬态状态	单次 FC-Loop 调用

9.2 ContextLayerManager

ContextLayerManager 是 6 层上下文的统一管理入口，职责：

• 初始化和销毁上下文层级
• 跨层级上下文注入（如 WORKING → PROCESS 的合并）
• 上下文快照（执行 checkpoint 时冻结当前快照）
• 上下文压缩委托（调用 ContextCompressor）

9.3 ContextCompressor

ContextCompressor 使用 LLM-enhanced 压缩策略，保留核心信息：

SkillExecutionSummary 21 字段：包括 taskId, taskType, status, duration, tokenCount, inputSummary, outputSummary, keyDecisions, errorInfo, artifacts, routePath, llmModel, llmConfig, contextSize, compressionRatio, quality, retryCount, humanInterventions, subTaskSummary, metadata, rawLogPath

// 压缩流程：ContextCompressor.compress()
  1. 收集 HISTORY 层原始数据
  2. 按时间窗口分组（会话/活动级别）
  3. LLM 压缩请求生成摘要
  4. 提取 SkillExecutionSummary
  5. 过滤掉低价值信息（保留结构、决策、异常）
  6. 计算 compressionRatio 写入元数据

十、Transition/Route 路由体系

10.1 Transition 定义

Transition 是活动之间的有向边，组成流程的 DAG 结构：

属性	类型	说明
sourceId	String	源活动 ID
targetId	String	目标活动 ID
condition	Expression	条件表达式（可选），满足条件才触发
priority	int	优先级，值越小越优先（默认 0）
transitionType	TransitionType	FORWARD 正向 / BACKWARD 回退

10.2 SplitMode 分支模式

模式	说明
SEQUENCE	顺序执行所有出边活动（默认模式）
XOR_SPLIT	排他分支，只执行第一个满足条件的出边
AND_SPLIT	并行分支，所有出边同时执行
OR_SPLIT	或分支，执行所有满足条件的出边
EVENT_SPLIT	事件分支，AGENT_EVENT 专用，分裂出事件等待分支

10.3 JoinMode 汇聚模式

模式	说明
AND_JOIN	所有前驱活动到达后才触发当前活动（同步屏障）
XOR_JOIN	任一前驱活动到达即触发（排他汇聚）
OR_JOIN	部分前驱活动到达即触发（不完全同步）

10.4 按 ActivityType 的路由策略

ActivityType	SplitMode 默认	JoinMode 默认	路由策略
START	SEQUENCE	—	无条件出边
END	—	XOR_JOIN	流程结束
TASK	SEQUENCE / AND_SPLIT	AND_JOIN	resolveTaskRoute
LLM_AGENT	XOR_SPLIT (LLM 决策)	XOR_JOIN	resolveLlmAgentRoute
HUMAN	XOR_SPLIT (人工选择)	XOR_JOIN	resolveHumanRoute
AGENT_EVENT	EVENT_SPLIT	eventMergeMode	resolveAgentEventRoute
SUBPROCESS	SEQUENCE	AND_JOIN	子流程完成后继续
CALL_ACTIVITY	SEQUENCE	AND_JOIN	外部流程完成后继续

10.5 BACKWARD 路由

• RETURNED 操作触发 Transition.BACKWARD
• 检查 maxRetry（活动级别）：超过则触发 guard_escalation
• 回退时将目标活动的 ActivityInstance.status 重置为 PENDING
• 清空目标活动的输出数据，重新执行

10.6 AND_JOIN 实现

AND_JOIN 检查所有入边活动是否均已到达：

// joinChecker.checkAndJoin(actDef)
  获取 actDef 所有前驱活动
  检查 每个前驱活动的 ActivityInstance.status == COMPLETED
  如果 全部 COMPLETED → 触发当前活动
  否则 → 继续等待（不触发）

十一、Guard 守卫机制

11.1 GuardConfig 配置

属性	类型	默认值	说明
maxRetry	int	3	单个活动最大重试次数
maxGlobalBackward	int	5	全局最大回退次数
noMatchPolicy	NoMatchPolicy	DEFAULT	无路由匹配时的处理策略

11.2 NoMatchPolicy — 无匹配策略

策略	说明
ESCALATE_HUMAN	升级到 HUMAN，创建 INTERVENE_EXCEPTION 节点，等待人工干预
RETRY_LAST	重试最后失败的活动
SKIP	跳过当前活动，继续执行下一活动
DEFAULT	按流程默认策略处理（通常为 ESCALATE_HUMAN）

11.3 guard_escalation SSE 事件

完整载荷结构：

{
  "failedActivityId": "act_llm_001",
  "interventionActivityId": "act_human_intervene",
  "reasonCode": "NO_MATCH_ESCALATION",
  "humanMode": "EXCEPTION_INTERVENTION",
  "interventionRequired": true,
  "guardPausedReason": "重试3次后仍无匹配路由",
  "exceptionContext": { ... },
  "availableOperations": ["SEND", "RETURN", "TERMINATE"]
}

11.4 重试耗尽处理

• 单个活动连续失败次数 > maxRetry (默认 3) → 触发 guard_escalation
• 全局回退次数 > maxGlobalBackward (默认 5) → 触发 guard_escalation
• guard_escalation 创建 EXCEPTION_INTERVENTION 类型的 HUMAN 节点
• HUMAN 可选择：SEND（继续）、RETURN（退回修复）、TERMINATE（终止）

11.5 NoMatchPolicy 映射

通过 NoMatchPolicy.fromCode(str) 进行映射，而非手动 switch：

NoMatchPolicy policy = NoMatchPolicy.fromCode(config.getNoMatchPolicy());
switch (policy) {
  case ESCALATE_HUMAN:
    // 创建 EXCEPTION_INTERVENTION 节点
    break;
  case RETRY_LAST:
    // 重试最后活动
    break;
  case SKIP:
    // 跳过
    break;
  default:
    // 使用 DEFAULT 策略
}

十二、部署架构

12.1 服务拓扑

Studio（主应用）NlpChatInline 前端SkillFlowEngineHumanOperationEngineAiServer（远程）BPM WorkflowEngineRemote AgentRemote ProcessInstanceooder-test（测试）闭环测试框架NLP Harness场景验证HTTPSSE通信协议SSE: 前端 ←→ StudioHTTP: Studio ←→ AiServerSQLite / VFS: 本地持久化

12.2 通信协议

通信路径	协议	数据格式
前端 ←→ Studio	SSE（Server-Sent Events）	JSON 事件流
Studio ←→ AiServer	HTTP REST	JSON
Studio → SQLite	JDBC	关系数据
Studio → VFS	文件 I/O	.cls 文件

12.3 模块依赖关系

• studio 依赖 scene-engine（本地流程执行）和 ooder-pro（业务逻辑）
• scene-engine 依赖 ooder-common（元数据、枚举、工具类）
• aiserver 包含独立 BPM 引擎，通过 HTTP 代理提供远程执行能力
• ooder-test 依赖 scene-engine + aiserver，提供端到端闭环测试

十三、模块清单与文件映射

模块职责总览

模块	Maven 坐标	核心职责
ooder-common	net.ooder:ooder-common	元数据定义、枚举体系、工具类、BPM 通用客户端
scene-engine	net.ooder:scene-engine	流程引擎核心（SkillFlowEngine、RouteToEngine、HumanOperationEngine、AgentEventBridge、ContextLayerManager）
ooder-pro	net.ooder:ooder-pro	业务逻辑、Skill 编排、MCP Agent 管理
aiserver	net.ooder:aiserver	远程 BPM 引擎代理、LLM 代理服务
ooder-test	net.ooder:ooder-test	NLP 闭环测试框架、Harness 验证