OoderAgent SceneEngine 3.0.3 深度解析

场景驱动的智能协作引擎 — 从架构设计到核心实现的全景剖析

ooder SDK · 版本 3.0.3 · Java 21 · Spring Boot 3.2.5

概述架构全景核心层引擎子系统事件系统场景组A2A协议LLM集成能力路由发现服务容错机制资产治理桥接层设计模式总结

目录

1. 概述：什么是 SceneEngine
2. 架构全景：分层与模块化设计
3. 核心层：SceneEngine 接口与客户端体系
4. 引擎子系统：11 大引擎的编排与管理
5. 事件系统：200+ 事件类型的全域驱动
6. 场景组模型：业务协作的核心抽象
7. A2A 协议：Agent 间智能通信
8. LLM 集成：场景化大模型能力
9. 能力路由：CAP 地址空间的精准分发
10. 发现服务：多策略能力发现
11. 容错机制：高可用的守护者
12. 资产治理：数字资产全生命周期
13. 桥接层：SDK-SE 双向同步
14. 设计模式与架构哲学
15. 总结与展望

一、概述：什么是 SceneEngine

SceneEngine 是 ooder SDK 生态中的场景驱动智能协作引擎，它以"场景"为核心抽象，将 Agent、Skill、Capability、知识库等异构资源统一编排到业务上下文中，为上层应用（ooder-Nexus、ooder-Nexus-Enterprise、agent-skillcenter）提供安全、可审计、高可用的协作基础设施。

核心理念：一切业务皆场景，一切协作皆能力调用。SceneEngine 通过场景组（SceneGroup）将分散的 Agent 和 Skill 组织成协作单元，通过能力路由（CapRouter）实现精准的能力分发，通过 A2A 协议实现 Agent 间的智能通信。

🔐 统一安全

Token 令牌控制、权限管理、安全审计日志，所有操作可追溯

📊 统一状态

Session 管理、连接状态追踪、场景生命周期状态机

🔗 统一连接

Agent 注册、心跳检测、A2A 通信、MCP 协议适配

📝 统一审计

全链路操作记录、事件溯源、审计日志导出

技术栈一览

二、架构全景：分层与模块化设计

SceneEngine 3.0.3 采用分层架构 + 模块化设计，从上到下分为接入层、核心层、引擎层、基础设施层四个层次，各层职责清晰、耦合度低。

图 1：SceneEngine 3.0.3 四层架构全景图

三、核心层：SceneEngine 接口与客户端体系

3.1 SceneEngine — 一切功能的入口

SceneEngine 是整个场景引擎的顶层接口，定义了引擎的完整契约。它遵循接口隔离原则，将不同角色的操作分离到 SceneClient（用户端）和 AdminClient（管理端）。

public interface SceneEngine {
    // 身份认证
    SceneClient login(String username, String password);
    SceneClient login(String token);
    AdminClient adminLogin(String username, String password);
    void logout(String sessionId);

    // 会话管理
    SessionInfo getSession(String sessionId);
    boolean validateSession(String sessionId);
    SessionInfo refreshSession(String sessionId);

    // 引擎生命周期
    void start();
    void stop();
    EngineStatus getStatus();
    boolean isRunning();

    // 服务定位与能力注册
    <T> T getService(Class<T> serviceType);
    void registerCapability(String capId, Object capability);

    // Provider 获取
    SkillService getSkillService();
    SceneProvider getSceneProvider();
    HeartbeatProvider getHeartbeatProvider();
}

«interface»SceneEngine«interface»SceneClient«interface»AdminClientSceneClientImplSessionInfosessionId / userId / tokenlogin() 返回adminLogin() 返回持有

3.2 SceneClient — 用户视角的操作集

SceneClient 封装了用户登录后的所有操作能力，通过持有 SessionInfo 和 SceneEngine 引用，将请求代理到底层服务：

3.3 SceneAgentCore — 场景代理核心

SceneAgentCore 是场景引擎内部的 Agent 抽象，与 agent-sdk 的 SceneAgent 形成桥接关系。它专注于场景生命周期管理和 Skill 挂载：

public interface SceneAgentCore {
    String getAgentId();
    SceneAgentState getAgentCoreState();
    void initialize(SceneConfig config);
    void mountSkill(String skillId, SceneConfig config);
    void unmountSkill(String skillId);
    CapResponse invokeCap(String capId, CapRequest request);
    void shutdown();
    default MemberRole getMemberRole() { return MemberRole.MEMBER; }
    default boolean isPrimary() { return MemberRole.PRIMARY.equals(getMemberRole()); }
}

Agent 状态遵循有限状态机模型：

图 3：SceneAgentState 状态机转换图

3.4 CapRouter — 能力请求的精准分发

CapRouter 是能力调用的核心路由器，它维护了能力 ID 到处理器（CapHandler）的映射表，并集成 CapRegistry 进行能力存在性校验。每次路由都会发布 CapabilityEvent 用于审计追踪。

能力调用流程

1. CapRouter.routeRequest(capId, request) 接收请求 2. 查询 CapRegistry.hasCapability(capId) 校验能力存在性 3. 查找 handlers 映射表获取 CapHandler 4. 执行 handler.handle(request) 或走默认处理 5. 发布 CapabilityEvent.invoked/invocationFailed 事件 6. 返回 CapResponse（含 requestId、success、result、metadata）

四、引擎子系统：11 大引擎的编排与管理

SceneEngine 定义了 11 种引擎类型（EngineType），每种引擎负责一个独立的功能域。所有引擎实现统一的 Engine 接口，由 EngineManager 统一编排生命周期。

4.1 Engine 接口 — 统一的生命周期契约

public interface Engine {
    EngineType getType();
    EngineStatus getStatus();
    void initialize();       // 初始化
    void start();            // 启动
    void stop();             // 停止
    void destroy();          // 销毁
    boolean healthCheck();   // 健康检查
    EngineStats getStats();  // 运行统计
    List<String> getCapabilities();
}

4.2 EngineStatus — 9 态生命周期

图 4：EngineStatus 9 态生命周期

4.3 EngineManager — 引擎编排器

EngineManager 负责所有引擎的注册、发现和批量生命周期管理。它提供了 initializeAll()、startAll()、stopAll()、destroyAll() 等批量操作，以及 healthCheckAll() 返回不健康引擎列表，实现统一的健康监控。

五、事件系统：200+ 事件类型的全域驱动

SceneEngine 构建了基于 Spring ApplicationEvent 的完整事件体系，定义了 200+ 种事件类型，覆盖安全、会话、技能、能力、配置、引擎、场景、用户、组织、工作流、节点、心跳、资产、知识库等 16 个领域。

5.1 SceneEvent — 事件基类

public abstract class SceneEvent extends ApplicationEvent {
    private final SceneEventType eventType;
    private final String traceId;          // 16位追踪ID，链路追踪
    private final Map<String, Object> metadata; // 可扩展元数据

    public SceneEvent addMetadata(String key, Object value) {
        metadata.put(key, value);
        return this;  // 链式调用
    }
}

5.2 事件类型分类

图 5：SceneEventType 事件类型分类体系

5.3 SceneEventPublisher — 事件发布器

SceneEventPublisher 封装了 Spring 的 ApplicationEventPublisher，提供同步和异步两种发布模式，以及类型安全的便捷方法：

@Component
public class SceneEventPublisher {
    public void publish(SceneEvent event);           // 同步发布
    public void publishAsync(SceneEvent event);      // 异步发布
    public void publishCapabilityEvent(...);           // 能力事件
    public void publishSessionEvent(...);              // 会话事件
    public void publishAgentEvent(...);                // Agent事件
}

六、场景组模型：业务协作的核心抽象

SceneGroup 是 SceneEngine 最核心的业务模型，它将一个完整的业务场景封装为包含参与者、能力绑定、知识库绑定、快照和事件日志的协作单元。

图 6：SceneGroup 核心模型与关联关系

6.1 场景组状态机

SceneGroup 的状态转换使用 AtomicReference<Status> + compareAndSet 实现无锁并发安全的状态转换：

图 7：SceneGroup 状态机转换图

6.2 SceneGroupManager — 场景组管理器

SceneGroupManager 是 Spring Bean（@Component），通过 @ConditionalOnProperty 条件装配，负责：

• 场景组的 CRUD 与状态转换
• 参与者心跳检测（60 秒间隔，300 秒超时）
• 已销毁场景组的定期清理（1 小时后移除）
• 审计事件发布（所有操作均发布 SceneGroupAuditEvent）
• 模板索引维护（templateId → List<SceneGroup>）

七、A2A 协议：Agent 间智能通信

A2A（Agent-to-Agent）协议是 SceneEngine 3.0.3 的核心创新之一，它定义了 Agent 间通信的统一标准，支持消息发送、请求-响应、多 Agent 对话、智能路由和协议转换。

图 8：A2A 协议架构与路由策略

7.1 五级路由策略

A2A 消息路由器采用五级优先级策略，从精确到模糊逐级降级：

7.2 Agent 上下文 — 四级隔离

AgentContext 实现了四级上下文隔离，确保不同层级的上下文信息不会互相污染：

public class AgentContext {
    private Map<String, Object> systemContext;       // 系统级：全局配置
    private Map<String, Object> sceneContext;       // 场景级：场景共享
    private Map<String, Object> sessionContext;      // 会话级：用户会话
    private Map<String, Object> conversationContext; // 对话级：当前对话
    private List<Map> conversationHistory;      // 对话历史（最多20条）
}

八、LLM 集成：场景化大模型能力

SceneEngine 3.0.3 深度集成了 LLM 能力，通过 LlmService 接口提供统一的聊天、补全、流式输出能力，并通过 LlmSceneContext 实现场景化的上下文管理。

8.1 LlmService 接口

public interface LlmService {
    ChatResponse chat(SceneChatRequest request);     // 同步聊天
    void chatStream(SceneChatRequest, StreamHandler); // 流式聊天
    String complete(String prompt, int maxTokens);     // 文本补全

    // 多 Provider / 多 Model 管理
    List<ProviderInfo> getProviders();
    List<ModelInfo> getModels(String providerId);
    void setActiveProvider(String providerId);
    void setActiveModel(String providerId, String modelId);

    // Function Calling 注册
    void registerFunction(String functionId, FunctionConfig config);
}

8.2 LlmSceneContext — 场景化上下文

LlmSceneContext 是 LLM 在特定场景中的完整上下文封装，支持 A2A 传递（实现 Serializable），包含：

8.3 LLM 审计与监控

SceneEngine 为 LLM 调用提供了完整的审计体系：LlmAuditService 记录每次调用的上下文、参数和结果；LlmProxyMonitor 监控代理状态和配额；LlmLoadBalancer 实现多 Provider 间的负载均衡。

九、能力路由：CAP 地址空间的精准分发

SceneEngine 的能力系统采用地址空间（CapabilityAddress）设计，每个能力拥有唯一的整型地址。CapabilityRouter 维护三张核心注册表：

Provider 解析策略

resolveProvider(address) 方法优先查找 bindingRegistry，若未命中则降级到 fallbackRegistry，实现主备切换的优雅降级。

十、发现服务：多策略能力发现

DiscoveryProvider 接口定义了能力发现的标准契约，支持多种发现策略（UDP 广播、mDNS、SkillCenter 等），每种策略以插件形式注册：

public interface DiscoveryProvider {
    String getProviderName();
    void initialize(DiscoveryConfig config);
    void start();
    void stop();
    CompletableFuture<List<DiscoveredItem>> discover(DiscoveryQuery query);
    int getPriority();                      // 优先级排序
    boolean isApplicable(DiscoveryScope scope); // 范围适配
}

发现系统支持按优先级排序、按范围过滤，查询结果以 CompletableFuture 异步返回，适合大规模分布式环境下的能力发现。

十一、容错机制：高可用的守护者

FailoverManager 提供了 Agent 级别的容错能力，确保在 Agent 故障时业务不中断：

💓 心跳监控

持续监控 Agent 心跳，检测超时节点

🔄 自动切换

reassignTasksAuto() 自动选择替代 Agent

📋 任务迁移

reassignTasks() 将失败 Agent 的任务迁移到目标 Agent

📊 统计监控

FailoverStats 跟踪切换次数、恢复率等指标

十二、资产治理：数字资产全生命周期

AssetGovernance 接口定义了数字资产的完整治理体系，覆盖注册、更新、停用、所有权转移、健康检查等全生命周期操作：

public interface AssetGovernance {
    void registerAsset(DigitalAsset asset);
    void decommissionAsset(String assetId);
    CompletableFuture<Void> transferOwnership(String assetId, String newOwnerId);
    CompletableFuture<AssetHealth> checkHealth(String assetId);
    AssetStatistics getStatistics();
    void addAssetListener(AssetListener listener); // 观察者模式
}

资产查询支持多维度过滤（类型、类别、状态、所有者、位置、关键词、标签），并通过 AssetListener 观察者接口实现资产变更的实时通知。

十三、桥接层：SDK-SE 双向同步

SceneGroupBridge 是 SDK SceneGroup 与 SE SceneGroup 之间的双向映射和同步桥梁，解决了两个系统间的模型差异：

图 9：SDK-SE SceneGroupBridge 双向同步架构

十四、设计模式与架构哲学

SceneEngine 3.0.3 的源码中蕴含了丰富的设计模式运用，体现了高度的工程化思维：

架构哲学

🎯 场景驱动

一切业务皆场景，SceneGroup 是协作的基本单元，所有资源围绕场景组织

🔌 插件化

Engine、DiscoveryProvider、CapHandler 均可插拔，通过 Spring 条件装配实现零配置集成

🔒 安全优先

Token 认证、权限校验、审计日志贯穿全链路，200+ 事件类型确保操作可追溯

⚡ 无锁并发

AtomicReference + CAS 实现状态转换，ConcurrentHashMap + CopyOnWriteArrayList 保障线程安全

十五、总结与展望

SceneEngine 3.0.3 是一个设计精良、职责清晰的场景驱动协作引擎。它以 SceneGroup 为核心抽象，以 A2A 协议实现 Agent 间智能通信，以 CapRouter 实现能力精准分发，以 200+ 事件类型构建全域驱动体系，以 11 大引擎覆盖完整功能域。

核心价值：SceneEngine 不是简单的中间件，而是一套完整的协作基础设施。它将"场景"这一业务概念提升为一等公民，让 Agent、Skill、Capability 等技术资源自然地围绕业务场景组织，实现了技术与业务的优雅对齐。

技术亮点回顾

SceneEngine 3.0.3 代表了场景驱动架构的成熟实践，为构建企业级智能协作系统提供了坚实的基础。随着 A2A 协议的深化、LLM 能力的增强和多模态交互的引入，SceneEngine 将持续演进，为更复杂的业务场景提供更强大的协作能力。

SceneEngine 3.0.3 深度解析 · ooder SDK · GitHub

本文基于源码分析撰写，转载请注明出处