06. 系统架构

6. 系统架构

本章描述 FlowNex 的系统架构、服务职责、主调用链路和关键运行时流程。

FlowNex 不是单体应用，而是由多个 Java 服务、一个 Python Agent Runtime、公共能力库和外部基础设施共同组成的联合作业系统。

6.1 总体架构

FlowNex 的总体架构可以分为六层：

1. 接入层。
2. 编排层。
3. 能力接入与治理层。
4. 领域层。
5. 运行时层。
6. 基础设施层。

flowchart TB
    subgraph Client["客户端 / 外部渠道"]
        Web["FlowNex Web 前端"]
        Lark["飞书 / Lark"]
        Ding["钉钉 / DingTalk"]
        APIClient["业务系统 API Client"]
        AIApp["AI 应用中心前端应用"]
    end

    subgraph Ingress["双网关接入层"]
        CLAWGW["ai-claw-gateway<br/>FlowNex 主站 / 非 AI 应用入口交互"]
        AIGW["ai-app-runtime-gateway<br/>/application/**"]
    end

    subgraph AppService["AI 应用聚合层"]
        APP["ai-app-service<br/>应用交互 API / 业务语义接口 / 业务数据落库"]
    end

    subgraph Control["能力中心与编排层"]
        CS["control-center"]
        CGW["Capability Gateway<br/>control-center 内部实现"]
        REG["Capability Registry"]
        ADP["Provider Adapter<br/>control-center 内部实现"]
    end

    subgraph Domain["领域层"]
        UDS["user-domain-service"]
        ADS["agent-domain-service"]
    end

    subgraph Runtime["运行时层"]
        RTG["agent-runtime-gateway"]
        SH["share-harness"]
    end

    subgraph Infra["基础设施"]
        DB["MySQL"]
        Redis["Redis"]
        MQ["RocketMQ"]
        OSS["OSS"]
        OV["OpenViking Knowledge Base"]
        AGFS["AGFS"]
        BIZAI["业务线 AI 能力 / 原子能力"]
    end

    Web --> CLAWGW
    Lark --> CLAWGW
    Ding --> CLAWGW
    APIClient --> CLAWGW
    AIApp --> AIGW
    AIGW --> APP
    CLAWGW --> CS
    APP --> CS
    CS --> CGW
    CGW --> REG
    CGW --> ADP
    ADP --> BIZAI
    CS --> UDS
    CS --> ADS
    CS --> RTG
    RTG --> SH
    SH --> RTG
    RTG --> APP
    APP --> AIGW

    UDS --> DB
    ADS --> DB
    APP --> DB
    CS --> MQ
    RTG --> Redis
    RTG --> MQ
    SH --> OSS
    SH --> OV
    SH --> AGFS

主链路可以概括为：

FlowNex 主站 / 非 AI 应用入口
  -> ai-claw-gateway
  -> control-center
  -> agent-runtime-gateway
  -> share-harness
  -> agent-runtime-gateway
  -> control-center
  -> ai-claw-gateway
  -> FlowNex 主站 / 外部渠道

AI 应用中心链路可以概括为：

AI 应用中心应用
  -> ai-app-runtime-gateway /application/**
  -> ai-app-service
  -> control-center
  -> agent-runtime-gateway
  -> share-harness
  -> agent-runtime-gateway
  -> ai-app-service
  -> ai-app-runtime-gateway
  -> AI 应用中心应用

业务线 AI 能力接入后的扩展链路是：

AI 应用中心前端应用
  -> ai-app-runtime-gateway /application/**
  -> ai-app-service
  -> control-center 能力中心
  -> Capability Gateway（control-center 内部）
  -> Provider Adapter（control-center 内部）
  -> 业务线 AI 应用或原子化 AI 能力
  -> Provider Adapter（control-center 内部）
  -> Capability Gateway（control-center 内部）
  -> Runtime 事件和任务轨迹

现有入口触发原子能力时，不经过 ai-app-service：

Web 前端 / 飞书 / 钉钉 / Agent / Skill / Tool
  -> ai-claw-gateway 或 Runtime 内部链路
  -> control-center 能力中心
  -> Capability Gateway（control-center 内部）
  -> Provider Adapter（control-center 内部）
  -> 业务线 AI 应用或原子化 AI 能力

6.1.1 业务线 AI 能力接入架构

业务线 AI 应用和原子化 AI 能力不应直接暴露给 Agent Runtime 或前端业务层。真实链路需要区分两类入口：

1. FlowNex 主站交互链路：Web 前端、对话入口、任务中心、Skill 市场、知识库管理、管理台、飞书、钉钉等非 AI 应用入口交互，仍统一经过 ai-claw-gateway -> control-center。
2. AI 应用中心接入链路：前端 AI 应用通过 ai-app-runtime-gateway 的 application 前缀路由进入 ai-app-service，由 ai-app-service 提供应用层交互接口、业务语义接口和业务数据落库。典型应用包括行云 AI 算力专项学习服务、会议智能总结、智能项目管理、智能标书。
3. 原子 AI 能力调用链路：只有 AI 应用中心前端应用发起的应用侧请求才会经过 ai-app-runtime-gateway -> ai-app-service -> control-center；现有 Web 前端、飞书、钉钉、Agent、Skill 或 Tool 仍经过 ai-claw-gateway -> control-center 或运行时内部链路进入能力中心。

Capability Gateway 和 Provider Adapter 均属于 control-center 内部实现，不作为独立应用部署，也不单独暴露给前端或业务线。

flowchart TB
    Main["Web 前端 / 飞书 / 钉钉 / 管理台"] --> CLW["ai-claw-gateway"]
    FE["AI 应用中心应用<br/>算力学习 / 会议总结 / 项目管理 / 智能标书"] --> GW["ai-app-runtime-gateway<br/>application 前缀路由"]
    CLW --> CS["control-center<br/>能力中心"]
    GW --> APP["ai-app-service<br/>应用交互接口 / 业务语义接口 / 业务数据落库"]
    APP --> CS["control-center<br/>能力中心"]

    subgraph Internal["control-center 内部实现"]
        CGW["Capability Gateway"]
        REG["Capability Registry"]
        ADP["Provider Adapter"]
        AUTH["租户授权 / 角色权限 / 配额"]
        OBS["Trace / Audit / Metrics / Evaluation"]
    end

    CS --> CGW
    CGW --> REG
    CGW --> AUTH
    CGW --> ADP
    CGW --> OBS
    ADP --> BIZ["业务线 AI 能力 / 原子能力 / 业务系统 API"]

    APP --> RTG["agent-runtime-gateway"]
    RTG --> SH["share-harness<br/>Agent / Skill / Tool 执行"]
    SH --> CS

这层设计承担以下职责：

模块	职责
ai-claw-gateway	FlowNex 现有主链路网关，承接 AI 应用入口之外的所有交互，包括 Web 前端、对话、任务中心、Skill、知识库、管理台、飞书、钉钉等
ai-app-runtime-gateway	AI 应用中心专用接入网关层，通过 application 前缀路径承接 AI 应用中心所有 AI 应用请求调用
ai-app-service	后端 AI 应用聚合代码仓库，只服务从 AI 应用中心前端应用侧进入的请求，提供应用层交互业务接口、业务语义接口和业务数据落库能力
control-center	能力中心所在服务，承接原子 AI 能力调用、能力管理、能力授权、路由治理和 Provider 适配
Capability Gateway	control-center 内部能力调用治理模块，负责路由、鉴权、限流、审计、Trace、降级和错误映射
Capability Registry	control-center 内部能力目录模块，保存能力元数据、输入输出 Schema、版本、负责人、适用租户和状态
Provider Adapter	control-center 内部 Provider 适配实现，适配不同业务线协议、鉴权方式、字段结构、错误码、超时和重试策略
Tenant Capability Config	控制租户、部门、角色、Agent、Skill 对能力的可见和可用范围
Observability Binding	将能力调用纳入任务 Trace、运行指标、调用成本、自动回归和质量评估

新增这层后，FlowNex 的架构边界更清晰：

1. ai-app-runtime-gateway 只负责 AI 应用入口路由，不承载业务语义。
2. ai-claw-gateway 负责 FlowNex Web 前端、主站、管理台、飞书、钉钉和非 AI 应用入口的交互接入。
3. ai-app-service 负责 AI 应用层交互、业务语义接口和业务数据落库。
4. control-center 决定本轮任务或前端请求能用哪些原子能力。
5. Capability Gateway 作为 control-center 内部模块负责统一执行能力调用治理。
6. Provider Adapter 作为 control-center 内部实现负责对接具体业务线能力。
7. share-harness 仍然负责 Agent 推理、Skill 装配和 Tool 调用，但不直接耦合业务线协议。
8. 能力元数据、授权、调用关系和审计所需业务真相由 control-center 能力中心统一维护，并按需与领域服务协同。

6.2 服务模块划分

ai-claw-gateway

ai-claw-gateway 是 FlowNex 现有主链路网关，负责 AI 应用入口之外的所有产品交互。

负责：

1. 承接 FlowNex Web 前端和主站对话入口。
2. 承接任务中心、历史会话、文件管理、Skill 市场、知识库管理和管理台请求。
3. 承接飞书 / Lark、钉钉 / DingTalk 等外部渠道进入 FlowNex 主链路的请求。
4. 透传用户、租户、角色、trace 等可信上下文。
5. 对接 control-center、领域服务或运行时回推链路。

不负责：

1. AI 应用中心内具体前端应用的 application 路由。
2. AI 应用业务数据落库。
3. 原子 AI 能力的 Provider 适配。
4. 最终模型推理。

ai-app-runtime-gateway

ai-app-runtime-gateway 是 AI 应用中心的专用接入网关层，只承接 AI 应用中心前端应用发起的应用侧请求。

负责：

1. 承接 AI 应用中心内所有前端 AI 应用请求调用。
2. 通过 application 前缀路径进行 AI 应用路由。
3. 透传用户、租户、trace、来源应用等网关上下文。
4. 对接 ai-app-service。
5. 承接需要回推给前端的 SSE 或事件流入口。

典型应用包括：

1. 行云 AI 算力专项学习服务。
2. 会议智能总结。
3. 智能项目管理。
4. 智能标书。

不负责：

1. Agent 任务编排。
2. 领域数据处理。
3. 模型推理。
4. 知识库检索。
5. 原子 AI 能力的 Provider 适配。

ai-app-service

ai-app-service 是后端 AI 应用层的聚合代码仓库，只服务通过 ai-app-runtime-gateway 进入的 AI 应用中心应用侧请求。

负责：

1. 提供 AI 应用中心前端应用所需的应用层交互业务接口。
2. 提供业务语义接口，例如应用会话、页面状态、表单确认、业务动作触发等。
3. 负责 AI 应用相关业务数据落库。
4. 对接运行时链路，发起 Agent 任务或接收运行时结果。
5. 当 AI 应用中心前端应用需要调用原子 AI 能力时，路由到 control-center 能力中心。

不负责：

1. 现有 Web 前端、飞书、钉钉、主站管理台等非 AI 应用入口交互。
2. 原子能力的统一授权、路由、限流和 Provider 适配。
3. 最终模型推理。
4. Prompt 最终装箱。
5. AGFS 文件底层读写。

control-center

control-center 是能力中心与 Agent 编排协同的核心服务。

负责：

1. 承接 ai-claw-gateway、ai-app-service、Agent、Skill、Tool 发起的原子 AI 能力调用。
2. 管理 Capability 定义、Provider、版本、Schema、租户配置和开通状态。
3. 通过内部 Capability Gateway 实现能力路由、鉴权、限流、审计、Trace、降级和错误映射。
4. 通过内部 Provider Adapter 适配具体业务线 AI 能力、第三方 AI Provider 或业务系统 API。
5. 计算当前用户、租户、角色、Agent、Skill 可用的 Capability、Tool、Skill 和知识库范围。
6. 与 agent-runtime-gateway 协同下发运行时任务和能力快照。
7. 接收 runtime 回调和能力调用结果摘要，支撑任务轨迹、指标和审计。
8. 提供知识库、Skill、权限、运行时配置和能力管理入口。

不负责：

1. 前端 AI 应用的业务数据落库。
2. 最终模型推理。
3. AGFS 文件底层读写。

user-domain-service

user-domain-service 是用户域服务。

负责：

1. 用户信息。
2. 用户身份。
3. 用户 Agent 风格。
4. 用户相关领域规则。
5. 用户数据持久化。

agent-domain-service

agent-domain-service 是 Agent 业务领域服务。

负责：

1. Agent 配置。
2. Conversation。
3. Message。
4. Task。
5. Task Step。
6. Skill 元数据。
7. Skill 安装和审核。
8. 知识库本地映射。
9. Skill 与知识库绑定关系。
10. AGFS 业务映射。
11. Agent 侧引用的 Capability 快照。
12. Capability 与 Tool、Skill、Agent 能力包之间的映射关系引用。

它保存 Agent 领域业务真相，但不负责运行时推理，也不作为能力中心主数据的归属服务。

agent-runtime-gateway

agent-runtime-gateway 是运行时网关。

负责：

1. 会话到 runtime 实例的绑定。
2. 运行时实例路由。
3. init / infer 请求转发。
4. runtime 事件接收。
5. SSE 事件回推聚合。
6. Redis 运行时状态管理。
7. 运行时不可用时的重建和重试。

它不直接接 MySQL，不负责业务领域持久化。

share-harness

share-harness 是实际 Agent Runtime。

负责：

1. ReAct / Plan 执行。
2. 模型调用。
3. Tool 调用。
4. Skill 加载和执行。
5. 上下文重建。
6. 知识检索工具调用。
7. 文件读写。
8. AGFS workspace 接入。
9. Runtime 事件输出。
10. 任务结果生成。

share-harness 是运行时装配真相：最终哪些上下文进入本轮模型请求，由它根据策略决定。

6.3 主链路：客户端到 Runtime

用户发起一轮对话时，系统主链路如下：

sequenceDiagram
    participant U as User
    participant M as ai-claw-gateway
    participant G as ai-app-runtime-gateway
    participant P as ai-app-service
    participant C as control-center
    participant A as agent-domain-service
    participant R as agent-runtime-gateway
    participant H as share-harness

    alt FlowNex 主站 / 飞书 / 管理台
        U->>M: 发送消息 / 建立 SSE
        M->>C: 主站交互请求
    else AI 应用中心
        U->>G: application 请求 / 建立 SSE
        G->>P: application 路由转发
        P->>P: 应用交互处理 / 业务数据落库
        P->>C: 发起 Agent 任务或原子能力调用
    end
    C->>A: 创建 Message / Task
    C->>C: 计算 Tool / Skill / KnowledgeAccess
    C->>R: infer(command)
    R->>H: /tasks 或 /infer
    H->>H: 上下文装配 / 模型与工具执行
    H-->>R: runtime events
    alt FlowNex 主站 / 飞书 / 管理台
        R-->>C: runtime events
        C-->>M: SSE push
        M-->>U: 流式输出
    else AI 应用中心
        R-->>P: runtime events
        P-->>G: SSE push
        G-->>U: 流式输出
    end
    H-->>R: finish
    R-->>C: runtime callback
    C->>A: 更新 Task / Message / Step

这个链路中有两个关键设计：

1. ai-claw-gateway 和 ai-app-runtime-gateway 是双网关关系，分别承接主站交互和 AI 应用中心请求。
2. ai-app-service 承担 AI 应用层交互和业务语义，不把应用业务逻辑下沉到网关。
3. control-center 在任务下发前完成能力授权和运行时能力快照计算。
4. share-harness 在运行时完成最终上下文装箱和工具执行。

6.4 SSE 流式响应链路

SSE 用于向用户实时展示 Agent 执行过程。

典型事件包括：

1. 任务开始。
2. Planner 输出计划。
3. Agent 思考过程摘要。
4. Tool 调用开始。
5. Tool 调用结果。
6. Skill 命中。
7. 知识库检索。
8. 文件生成。
9. 最终回答。
10. 任务完成或失败。

SSE 链路按入口分为两类：FlowNex 主站和飞书等非 AI 应用入口由 ai-claw-gateway 承接连接；AI 应用中心内的应用由 ai-app-runtime-gateway 承接 application 路由连接。agent-runtime-gateway 聚合 runtime 事件后，按来源回传给 control-center 或 ai-app-service，再由对应入口推送到前端连接。

SSE 只负责用户侧展示，不应成为业务持久化唯一来源。任务状态和消息结果仍需要通过 runtime callback 进入 control-center 和 agent-domain-service。

6.5 Runtime 回调与任务持久化

Runtime 执行过程中会持续产生事件。

这些事件分为两类：

1. 面向用户展示的流式事件。
2. 面向业务持久化和审计的结构化事件。

任务完成后，runtime 需要回调：

1. 最终回答。
2. 任务状态。
3. 错误码和错误信息。
4. Task Step。
5. 文件产物。
6. Tool 调用摘要。
7. 知识命中摘要。
8. token 和耗时指标。

control-center 接收回调后，更新 agent-domain-service 中的消息、任务和步骤状态。

6.6 上下文装配链路

上下文装配是 Agent 运行质量的核心。

一次任务的上下文来源包括：

1. System Prompt。
2. Agent 身份和风格。
3. 当前用户身份。
4. Recent Messages。
5. 本轮用户输入。
6. 本轮附件。
7. 本轮可见 Skill。
8. 本轮可用 Tool。
9. 知识库检索结果。
10. AGFS workspace 文件。
11. Memory 和经验提醒。

control-center 负责提供业务侧能力快照，share-harness 负责最终装箱。

推荐装配顺序：

基础系统上下文
  -> 用户和 Agent 身份
  -> 本轮消息和附件
  -> 可用 Tool / Skill 轻量目录
  -> 知识检索结果
  -> AGFS 文件上下文
  -> Memory / Runtime Reminder
  -> PromptBudgetPlanner 裁剪

6.7 工具与 Skill 执行链路

Tool 和 Skill 是 Agent 从“会回答”走向“会做事”的关键。

执行链路如下：

flowchart LR
    A["用户任务"] --> B["解析意图"]
    B --> C["选择候选 Skill"]
    C --> D["加载 Skill 说明"]
    D --> E["判断所需 Tool"]
    E --> F["检查本轮 Tool 授权"]
    F --> G["执行 Tool / Skill Script / Workflow"]
    G --> H["写入 Task Step 和事件"]
    H --> I["生成最终结果"]

注意：

1. Skill 提供方法和约束。
2. Tool 提供动作能力。
3. Tool 是否可用由本轮授权决定。
4. Skill 是否可用由用户安装、角色权限和 runtime 可见范围决定。
5. Skill 绑定知识后，知识权限仍需单独校验。
6. Skill 调用业务线原子能力时，仍需经过 Capability Gateway 完成能力级授权和审计。

6.8 知识检索链路

知识检索链路分为授权计算和运行时检索两段。

授权计算在 control-center：

1. 查询用户可访问知识范围。
2. 解析用户手选知识库。
3. 查询本轮 Skill 绑定知识。
4. 计算最终 knowledgeAccess。
5. 下发给 runtime。

运行时检索在 share-harness：

1. 根据任务意图决定是否检索。
2. 调用 knowledge_search 或 knowledge_qa。
3. 对结果去重、排序和裁剪。
4. 装配引用证据。
5. 回传知识命中轨迹。

6.9 AGFS 文件系统链路

AGFS 接入后，运行时文件链路会从“本地临时目录 + OSS 交付”升级为“标准 workspace + 文件系统级版本和回滚”。

AGFS 链路包括：

1. control-center 创建或选择 AGFS space。
2. agent-runtime-gateway 下发 mount 信息。
3. share-harness 挂载 AGFS workspace。
4. Agent 和工具通过普通路径读写文件。
5. AGFS 记录文件节点、版本和事件。
6. 任务结束后，文件产物与 Task、Message、Skill 建立关系。
7. 高价值文件进入知识候选。

6.10 多 Agent 协作链路

多 Agent 协作以任务图为核心。

flowchart TD
    A["用户复杂任务"] --> B["Planner 拆解任务"]
    B --> C["Researcher 检索知识"]
    B --> D["Executor 执行工具和文件操作"]
    C --> E["AGFS 共享资料"]
    D --> E
    E --> F["Reviewer 审查结果"]
    F --> G["Synthesizer 汇总输出"]
    G --> H["最终回复 / 文件产物"]

AGFS 为多 Agent 提供共享文件空间，Knowledge Base 为多 Agent 提供共享组织知识，Task Graph 为多 Agent 提供协作结构。