AI Service 全景架构设计

本文档改为以 Mermaid 为主体。先看下面这张单张大图，这张图是 ai_service 的主图；后面的图都只是对这张图的局部展开。

1. AI Service 单张主图

flowchart TB
  classDef entry fill:#eef7ff,stroke:#3b82f6,color:#111827,stroke-width:1px;
  classDef control fill:#f5f3ff,stroke:#7c3aed,color:#111827,stroke-width:1px;
  classDef runtime fill:#ecfeff,stroke:#0891b2,color:#111827,stroke-width:1px;
  classDef service fill:#f0fdf4,stroke:#16a34a,color:#111827,stroke-width:1px;
  classDef storage fill:#fff7ed,stroke:#ea580c,color:#111827,stroke-width:1px;
  classDef external fill:#faf5ff,stroke:#a21caf,color:#111827,stroke-width:1px;
  classDef governance fill:#fefce8,stroke:#ca8a04,color:#111827,stroke-width:1px;

  subgraph L0[Clients And Upstream]
    direction LR
    DemoFE[Demo Frontend]
    StudioFE[Studio Admin Frontend]
    DemoBE[Demo Backend]
    ExternalCaller[Scripts Tests External Clients]
  end

  subgraph L1[Layer 1 Entry And API Assembly]
    direction LR
    MainPy[main.py]
    LocalMain[ai_service/main.py]
    Entrypoint[api/entrypoint.py]
    App[api/app.py]
    Docs[Protected Docs OpenAPI]
    CORS[CORS Middleware]
    StartupHooks[Startup Shutdown Hooks]
  end

  subgraph L2[Layer 2 Router And Control Plane]
    direction LR
    CoreRouter[core router\nsessions stream ws turns context]
    AgentsRouter[agents router\nagent version runtime config]
    KnowledgeRouter[knowledge router\nsources docs ingestion inspection]
    MCPRouter[mcp router\nserver credential mount preview]
    SkillsRouter[skills router\nskill version mount audit]
    FusionRouter[fusion router\nrun persisted io download proxy]
    EvaluationRouter[evaluation router\ndataset run gate export]
    ScheduledRouter[scheduled_tasks router\ntask list cancel history]
    JobsRouter[jobs router]
    AdminRouters[admin routers\nauth users audit settings models]
  end

  subgraph L3[Layer 3 Unified Business Anchors]
    direction LR
    AgentEntity[Agent]
    AgentVersion[AgentVersion]
    SessionEntity[Session]
    ConversationTurn[ConversationTurn]
    TurnSnapshot[TurnContextSnapshot]
    RuntimeCheckpoint[RuntimeCheckpoint]
    AgentMemory[AgentMemoryRecord]
    FusionRun[FusionRun]
    EvaluationRun[AgentEvaluationRun]
    ScheduledTask[ScheduledTask]
    KnowledgeSource[KnowledgeSource]
    DocumentEntity[Document]
    MCPMounts[AgentMCPLink]
    SkillMounts[AgentSkillLink]
  end

  subgraph L4A[Layer 4 Runtime Plane]
    direction LR
    ChatRegistry[orchestrator registry]
    ChameleonRT[Chameleon Chat Runtime]
    ReactRT[LangGraph ReAct Runtime]
    FusionRunService[FusionRunService]
    FusionRunner[FusionRuntimeRunner]
    FusionGraph[Fusion Runtime Graph]
    ExtractionGraph[Document Extraction Graph]
    ETLGraph[ETL Graph]
    EvaluationWorker[Evaluation Runner Worker]
    TimerWorker[Timer Scheduler Worker]
    SessionRuntime[Session Runtime Replay]
  end

  subgraph L4B[Layer 4 Governance And Runtime Policies]
    direction LR
    ModelRouting[Model Routing Config]
    MCPRuntimeConfig[MCP Runtime Config]
    MCPResponseConfig[MCP Response Config]
    GroundingConfig[Response Grounding Config]
    RequestLease[Agent Request Lease]
    UsageRollup[Usage Rollup And Cost Snapshot]
    FusionGovernance[Fusion Governance Context]
    AdminAuthz[Admin Authorization]
    EnvGuard[Environment Guard]
  end

  subgraph L5[Layer 5 Capability Services]
    direction LR

    subgraph ChatCapabilities[Chat And Shared Runtime Capabilities]
      direction TB
      CapabilityPipeline[Capability Pipeline]
      MCPPassthrough[MCP Passthrough]
      PromptContext[MCP Prompt Context]
      ModelLoader[Model Loader]
      LangfuseObs[Langfuse Tracing]
      TokenUsage[Token Usage]
    end

    subgraph RAGServices[RAG Services]
      direction TB
      IngestionSvc[Ingestion Service]
      ChunkingSvc[Chunking Service]
      EmbeddingSvc[Embedding Service]
      RetrievalSvc[Retrieval Service]
      RerankSvc[Rerank]
      MultiQuerySvc[Multi Query]
      SnapshotRebuild[Snapshot Rebuild]
      VectorRecon[Vector Reconciliation]
      ManualInspection[Manual Inspection]
      DocRecognition[Document Recognition]
    end

    subgraph MCPServices[MCP Services]
      direction TB
      MCPRegistry[MCP Registry Service]
      MCPClient[MCP Client Service]
      MCPAdapter[MCP Tool Adapter]
      MCPPolicy[MCP Policy]
      MCPSecret[MCP Secret Manager]
      MCPAudit[MCP Audit]
      MCPTracking[MCP Tool Tracking Runtime]
    end

    subgraph SkillServices[Skill Services]
      direction TB
      SkillRegistry[Skill Registry]
      SkillExecutor[Skill Executor]
      SkillPolicy[Skill Policy]
      SkillAudit[Skill Audit]
    end

    subgraph EvalServices[Evaluation Services]
      direction TB
      DatasetImporter[Dataset Importer]
      JudgeSvc[Judge Service]
      MetricsSvc[Metrics]
      GateSvc[Gate Service]
      RuntimeSummary[Runtime Summary]
    end

    subgraph InfraServices[Infra Runtime Services]
      direction TB
      CheckpointSvc[Runtime Checkpoint Service]
      MemorySvc[Agent Memory Service]
      ScheduledTaskSvc[Scheduled Task Service]
      TimerScheduler[Timer Scheduler Service]
      ReleaseMeta[Release Metadata]
      CorrectionSvc[Knowledge Correction Service]
    end

    subgraph ParserServices[Parser Services]
      direction TB
      PDFParser[pdf parser]
      DOCXParser[docx parser]
      TextParser[text parser]
      DoclingParser[docling parser]
    end

    subgraph AdminServices[Admin Services]
      direction TB
      AdminAuthSvc[admin auth service]
      AdminAuditSvc[admin audit service]
      SystemSettingsSvc[system settings service]
      ModelConfigSvc[llm model config service]
    end
  end

  subgraph L6[Layer 6 Persistence Domains]
    direction LR
    SessionsDomain[sessions domain]
    AgentsDomain[agents domain]
    KnowledgeDomain[knowledge domain]
    DocumentsDomain[documents domain]
    MCPDomain[mcp domain]
    SkillsDomain[skills domain]
    FusionDomain[fusion domain]
    EvaluationsDomain[evaluations domain]
    JobsDomain[jobs domain]
    ScheduledDomain[scheduled_tasks domain]
    AdminDomain[admin_access domain]
    ModelDomain[llm_model_config domain]
  end

  subgraph L7[Layer 7 Storage And External Infra]
    direction LR
    Postgres[(PostgreSQL)]
    MinIO[(MinIO)]
    Qdrant[(Qdrant)]
    LLMProviders[LLM Providers]
    ExternalMCP[External MCP Servers]
    Langfuse[(Langfuse)]
  end

  DemoFE --> App
  StudioFE --> App
  DemoBE --> App
  ExternalCaller --> App
  MainPy --> Entrypoint
  LocalMain --> Entrypoint
  Entrypoint --> App
  App --> Docs
  App --> CORS
  App --> StartupHooks
  App --> CoreRouter
  App --> AgentsRouter
  App --> KnowledgeRouter
  App --> MCPRouter
  App --> SkillsRouter
  App --> FusionRouter
  App --> EvaluationRouter
  App --> ScheduledRouter
  App --> JobsRouter
  App --> AdminRouters

  CoreRouter --> SessionEntity
  CoreRouter --> ConversationTurn
  CoreRouter --> TurnSnapshot
  CoreRouter --> RuntimeCheckpoint
  CoreRouter --> AgentMemory
  CoreRouter --> ChatRegistry
  CoreRouter --> CorrectionSvc

  AgentsRouter --> AgentEntity
  AgentsRouter --> AgentVersion
  AgentsRouter --> ModelRouting
  AgentsRouter --> MCPRuntimeConfig
  AgentsRouter --> MCPResponseConfig
  AgentsRouter --> GroundingConfig
  AgentsRouter --> RequestLease
  AgentsRouter --> UsageRollup

  KnowledgeRouter --> KnowledgeSource
  KnowledgeRouter --> DocumentEntity
  KnowledgeRouter --> IngestionSvc
  KnowledgeRouter --> ManualInspection
  KnowledgeRouter --> SnapshotRebuild

  MCPRouter --> MCPMounts
  MCPRouter --> MCPRegistry
  MCPRouter --> MCPClient
  MCPRouter --> MCPAudit

  SkillsRouter --> SkillMounts
  SkillsRouter --> SkillRegistry
  SkillsRouter --> SkillExecutor
  SkillsRouter --> SkillAudit

  FusionRouter --> FusionRun
  FusionRouter --> FusionRunService
  FusionRouter --> FusionGovernance

  EvaluationRouter --> EvaluationRun
  EvaluationRouter --> DatasetImporter
  EvaluationRouter --> EvaluationWorker

  ScheduledRouter --> ScheduledTask
  ScheduledRouter --> ScheduledTaskSvc

  AdminRouters --> AdminAuthz
  AdminRouters --> AdminAuthSvc
  AdminRouters --> AdminAuditSvc
  AdminRouters --> SystemSettingsSvc
  AdminRouters --> ModelConfigSvc

  ChatRegistry --> ChameleonRT
  ChatRegistry --> ReactRT
  ChameleonRT --> CapabilityPipeline
  ReactRT --> CapabilityPipeline
  CapabilityPipeline --> RetrievalSvc
  CapabilityPipeline --> MCPRegistry
  CapabilityPipeline --> SkillRegistry
  CapabilityPipeline --> ModelLoader
  CapabilityPipeline --> MCPPassthrough
  CapabilityPipeline --> PromptContext
  CapabilityPipeline --> TokenUsage
  CapabilityPipeline --> LangfuseObs

  FusionRunService --> AgentEntity
  FusionRunService --> AgentVersion
  FusionRunService --> FusionGovernance
  FusionRunService --> FusionRunner
  FusionRunner --> FusionGraph
  FusionGraph --> RetrievalSvc
  FusionGraph --> MCPRegistry
  FusionGraph --> ModelLoader
  FusionGraph --> MinIO

  ExtractionGraph --> ParserServices
  ExtractionGraph --> JobsDomain
  ExtractionGraph --> DocumentsDomain
  ETLGraph --> JobsDomain

  EvaluationWorker --> ChatRegistry
  EvaluationWorker --> JudgeSvc
  EvaluationWorker --> MetricsSvc
  EvaluationWorker --> GateSvc
  EvaluationWorker --> RuntimeSummary
  EvaluationWorker --> EvaluationsDomain

  TimerWorker --> TimerScheduler
  TimerScheduler --> ScheduledTaskSvc
  TimerScheduler --> SessionRuntime
  SessionRuntime --> ChatRegistry
  SessionRuntime --> CheckpointSvc
  SessionRuntime --> MemorySvc

  IngestionSvc --> ParserServices
  IngestionSvc --> ChunkingSvc
  IngestionSvc --> EmbeddingSvc
  IngestionSvc --> VectorRecon
  RetrievalSvc --> MultiQuerySvc
  RetrievalSvc --> RerankSvc
  SnapshotRebuild --> IngestionSvc
  DocRecognition --> IngestionSvc

  MCPRegistry --> MCPAdapter
  MCPAdapter --> MCPPolicy
  MCPPolicy --> MCPClient
  MCPClient --> MCPSecret
  MCPClient --> MCPTracking
  MCPTracking --> MCPAudit
  MCPClient --> ExternalMCP

  SkillRegistry --> SkillPolicy
  SkillPolicy --> SkillExecutor
  SkillExecutor --> SkillAudit

  ModelLoader --> LLMProviders
  LangfuseObs --> Langfuse

  SessionsDomain --> Postgres
  AgentsDomain --> Postgres
  KnowledgeDomain --> Postgres
  DocumentsDomain --> Postgres
  MCPDomain --> Postgres
  SkillsDomain --> Postgres
  FusionDomain --> Postgres
  EvaluationsDomain --> Postgres
  JobsDomain --> Postgres
  ScheduledDomain --> Postgres
  AdminDomain --> Postgres
  ModelDomain --> Postgres

  IngestionSvc --> DocumentsDomain
  RetrievalSvc --> DocumentsDomain
  MCPRegistry --> MCPDomain
  SkillRegistry --> SkillsDomain
  FusionRunService --> FusionDomain
  FusionRunner --> FusionDomain
  AgentEntity --> AgentsDomain
  AgentVersion --> AgentsDomain
  SessionEntity --> SessionsDomain
  ConversationTurn --> SessionsDomain
  TurnSnapshot --> SessionsDomain
  RuntimeCheckpoint --> SessionsDomain
  AgentMemory --> SessionsDomain
  FusionRun --> FusionDomain
  EvaluationRun --> EvaluationsDomain
  ScheduledTask --> ScheduledDomain
  KnowledgeSource --> KnowledgeDomain
  DocumentEntity --> DocumentsDomain
  MCPMounts --> MCPDomain
  SkillMounts --> SkillsDomain

  IngestionSvc --> MinIO
  IngestionSvc --> Qdrant
  EmbeddingSvc --> LLMProviders
  RetrievalSvc --> Qdrant
  SnapshotRebuild --> MinIO
  VectorRecon --> Qdrant

  EnvGuard --> Postgres
  StartupHooks --> EnvGuard
  StartupHooks --> AdminAuthSvc
  StartupHooks --> IngestionSvc
  StartupHooks --> VectorRecon
  StartupHooks --> EvaluationWorker
  StartupHooks --> TimerScheduler
  StartupHooks --> LangfuseObs

  class MainPy,LocalMain,Entrypoint,App,Docs,CORS,StartupHooks entry;
  class CoreRouter,AgentsRouter,KnowledgeRouter,MCPRouter,SkillsRouter,FusionRouter,EvaluationRouter,ScheduledRouter,JobsRouter,AdminRouters control;
  class ChatRegistry,ChameleonRT,ReactRT,FusionRunService,FusionRunner,FusionGraph,ExtractionGraph,ETLGraph,EvaluationWorker,TimerWorker,SessionRuntime runtime;
  class CapabilityPipeline,MCPPassthrough,PromptContext,ModelLoader,LangfuseObs,TokenUsage,IngestionSvc,ChunkingSvc,EmbeddingSvc,RetrievalSvc,RerankSvc,MultiQuerySvc,SnapshotRebuild,VectorRecon,ManualInspection,DocRecognition,MCPRegistry,MCPClient,MCPAdapter,MCPPolicy,MCPSecret,MCPAudit,MCPTracking,SkillRegistry,SkillExecutor,SkillPolicy,SkillAudit,DatasetImporter,JudgeSvc,MetricsSvc,GateSvc,RuntimeSummary,CheckpointSvc,MemorySvc,ScheduledTaskSvc,TimerScheduler,ReleaseMeta,CorrectionSvc,PDFParser,DOCXParser,TextParser,DoclingParser,AdminAuthSvc,AdminAuditSvc,SystemSettingsSvc,ModelConfigSvc service;
  class SessionsDomain,AgentsDomain,KnowledgeDomain,DocumentsDomain,MCPDomain,SkillsDomain,FusionDomain,EvaluationsDomain,JobsDomain,ScheduledDomain,AdminDomain,ModelDomain,AgentEntity,AgentVersion,SessionEntity,ConversationTurn,TurnSnapshot,RuntimeCheckpoint,AgentMemory,FusionRun,EvaluationRun,ScheduledTask,KnowledgeSource,DocumentEntity,MCPMounts,SkillMounts storage;
  class Postgres,MinIO,Qdrant,LLMProviders,ExternalMCP,Langfuse external;
  class ModelRouting,MCPRuntimeConfig,MCPResponseConfig,GroundingConfig,RequestLease,UsageRollup,FusionGovernance,AdminAuthz,EnvGuard governance;

这张图表达五件事：

• Agent 是统一业务锚点，连接 chat、fusion、evaluation、scheduled task 和各种 mount
• api/app.py 只是入口，真正的业务在 router、runtime、services、domains 分层展开
• Chat Runtime 和 Fusion Runtime 是两条平行主链，不是主从关系
• services/ 是共享能力层，storage/model_domains/ 是持久化真相源
• startup 会主动恢复 worker、做环境护栏和数据一致性修复

2. 总体系统边界

flowchart TB
  subgraph Clients[客户端]
    DemoFE[Demo Frontend]
    StudioFE[Studio Admin]
    DemoBE[Demo Backend]
    ScriptClient[Scripts Tests]
  end

  subgraph AIService[ai_service]
    direction TB

    subgraph Gateway[入口与装配]
      Main[main.py]
      Entrypoint[api/entrypoint.py]
      App[api/app.py]
      Routers[api/routers/*.py]
    end

    subgraph ControlPlane[控制面]
      AgentsCP[Agents Versions]
      KnowledgeCP[Knowledge Documents]
      MCPCP[MCP Registry Mounts]
      SkillsCP[Skills Mounts]
      FusionCP[Fusion Definition Run Control]
      EvalCP[Evaluation Control]
      AdminCP[Admin Auth Users Audit Settings]
      JobsCP[Jobs Scheduled Tasks]
    end

    subgraph RuntimePlane[执行面]
      ChatRT[Chat Orchestrator Runtime]
      FusionRT[Fusion Runtime]
      ExtractionRT[Document Extraction Runtime]
      ETLRT[ETL Runtime]
      EvalWorker[Evaluation Worker]
      TimerWorker[Scheduled Task Worker]
    end

    subgraph ServiceLayer[能力服务层]
      RAGSvc[RAG Services]
      MCPSvc[MCP Services]
      SkillSvc[Skill Services]
      ParserSvc[Parser Services]
      InfraSvc[Infra Runtime Services]
      AdminSvc[Admin Services]
      ModelLoader[Model Loader]
    end

    subgraph StorageFacade[存储适配层]
      Domains[storage model_domains]
      MinioClient[minio_client.py]
      QdrantClient[qdrant_client.py]
    end
  end

  subgraph Infra[外部基础设施]
    Postgres[(PostgreSQL)]
    MinIO[(MinIO)]
    Qdrant[(Qdrant)]
    LLM[LLM Providers]
    MCPServers[External MCP Servers]
    Langfuse[Langfuse]
  end

  Clients --> Gateway
  Gateway --> ControlPlane
  Gateway --> RuntimePlane
  ControlPlane --> ServiceLayer
  RuntimePlane --> ServiceLayer
  ControlPlane --> StorageFacade
  RuntimePlane --> StorageFacade
  ServiceLayer --> StorageFacade
  ServiceLayer --> LLM
  ServiceLayer --> MCPServers
  ServiceLayer --> Langfuse
  StorageFacade --> Postgres
  StorageFacade --> MinIO
  StorageFacade --> Qdrant

2. 分层结构

flowchart TB
  L1[API Gateway Layer]
  L2[Control Plane Layer]
  L3[Runtime Plane Layer]
  L4[Capability Service Layer]
  L5[Persistence Domain Layer]
  L6[Infra Layer]

  L1 --> L2
  L1 --> L3
  L2 --> L4
  L3 --> L4
  L2 --> L5
  L3 --> L5
  L4 --> L5
  L4 --> L6
  L5 --> L6

flowchart LR
  Entrypoint[api entrypoint app]
  Routers[api routers]
  Orchestrator[orchestrator]
  Fusion[fusion runtime]
  Agents[agents plugins]
  Services[services]
  Domains[storage model domains]
  Infra[postgres minio qdrant llm mcp langfuse]

  Entrypoint --> Routers
  Routers --> Orchestrator
  Routers --> Fusion
  Routers --> Agents
  Orchestrator --> Services
  Fusion --> Services
  Agents --> Services
  Services --> Domains
  Domains --> Infra
  Services --> Infra

3. 目录地图

mindmap
  root((ai_service))
    api
      entrypoint.py
      app.py
      routers
        core
        agents
        knowledge
        mcp
        skills
        fusion
        evaluation
        scheduled_tasks
        jobs
        admin_auth
        admin_users
        admin_audit
        admin_system_settings
        admin_llm_model_config
    orchestrator
      registry
      graph
      react_agent
      state
      runtime_kernel
      capability_pipeline
      checkpoint_state
      model_routing
      mcp_runtime_config
      mcp_response_config
      mcp_passthrough
      memory
    fusion
      services
      runtime
      capabilities
      schemas
    agents
      chat
      etl
      document_extraction
      fusion_definition_runtime
    services
      rag
      mcp
      skills
      evaluation
      admin
      infra
      parsers
    storage
      model_domains
      minio_client
      qdrant_client
    utils
      settings
      database
      logger
      model_loader
      environment_guard
    migrations

4. 启动与生命周期

sequenceDiagram
  participant Main as main.py
  participant Entry as api/entrypoint.py
  participant DB as PostgreSQL
  participant App as api/app.py
  participant Startup as FastAPI startup
  participant Workers as Background Workers

  Main->>Entry: run_uvicorn_app()
  Entry->>DB: verify_startup_database_connectivity()
  Entry->>Entry: resolve migration mode
  Entry->>Entry: run alembic upgrade if auto
  Entry->>App: import app
  Entry->>App: uvicorn.run(app)
  App->>Startup: on startup
  Startup->>Startup: environment guard
  Startup->>DB: init_database()
  Startup->>Startup: ensure bootstrap super admin
  Startup->>Startup: register agent plugins
  Startup->>Workers: cleanup stale ingestion jobs
  Startup->>Workers: reconcile document vectors
  Startup->>Workers: start evaluation supervisor
  Startup->>Workers: start timer scheduler
  Startup->>Workers: init langfuse

flowchart LR
  Start[Process Start]
  DBCheck[DB Connectivity Check]
  Migration[Migration Mode Resolve]
  AutoMigrate[Optional Auto Alembic Upgrade]
  AppImport[Import FastAPI App]
  Startup[Startup Hooks]
  Guard[Environment Guard]
  Bootstrap[Bootstrap Admin]
  Register[Register Agent Plugins]
  Recover[Recover Stale Runtime State]
  Ready[Ready]
  Shutdown[Shutdown Hooks]
  StopWorkers[Stop Worker Threads]
  StopTracing[Shutdown Langfuse]

  Start --> DBCheck --> Migration --> AutoMigrate --> AppImport --> Startup --> Guard --> Bootstrap --> Register --> Recover --> Ready --> Shutdown --> StopWorkers --> StopTracing

5. API 路由与控制面

flowchart TB
  App[api/app.py]

  subgraph Routers[api/routers]
    Core[core.py]
    Conversations[conversations/router.py]
    Agents[agents.py]
    Knowledge[knowledge.py]
    MCP[mcp.py]
    Skills[skills.py]
    Fusion[fusion.py]
    Evaluation[evaluation.py]
    Scheduled[scheduled_tasks.py]
    Jobs[jobs.py]
    DocumentRecognition[document_recognition/router.py]
    AdminAuth[admin_auth.py]
    AdminUsers[admin_users.py]
    AdminAudit[admin_audit.py]
    AdminSettings[admin_system_settings.py]
    AdminModels[admin_llm_model_config.py]
  end

  App --> Core
  App --> Conversations
  App --> Agents
  App --> Knowledge
  App --> MCP
  App --> Skills
  App --> Fusion
  App --> Evaluation
  App --> Scheduled
  App --> Jobs
  App --> DocumentRecognition
  App --> AdminAuth
  App --> AdminUsers
  App --> AdminAudit
  App --> AdminSettings
  App --> AdminModels

flowchart LR
  Core[core]
  Agents[agents]
  Knowledge[knowledge]
  MCP[mcp]
  Skills[skills]
  Fusion[fusion]
  Eval[evaluation]
  Scheduled[scheduled_tasks]
  Admin[admin_*]

  Core --> Sessions[Sessions Messages Turns WS SSE]
  Core --> Context[Turn Context Snapshot]
  Core --> Corrections[Knowledge Corrections]

  Agents --> AgentCRUD[Agent CRUD]
  Agents --> Versioning[Agent Versioning]
  Agents --> RuntimeCfg[Model Routing MCP Runtime Grounding]
  Agents --> FusionDraft[Fusion Draft Fields]

  Knowledge --> Sources[Knowledge Sources]
  Knowledge --> Docs[Documents]
  Knowledge --> Ingestion[Ingestion Manual Inspection Rebuild]

  MCP --> ServerCfg[MCP Servers Credentials]
  MCP --> MountCfg[Agent MCP Mounts]
  MCP --> Preview[Test Call Preview]

  Skills --> SkillCfg[Skill Versions Mounts Audit]
  Fusion --> FusionRun[Fusion Runs Persisted IO Download Proxy]
  Eval --> EvalRun[Datasets Runs Gate Export]
  Scheduled --> TaskOps[Task List Cancel History]
  Admin --> Control[Auth Users Audit Settings Models]

6. Agent 统一业务模型

flowchart TB
  Agent[Agent]
  AgentVersion[AgentVersion]
  KnowledgeLink[AgentKnowledgeLink]
  MCPLink[AgentMCPLink]
  SkillLink[AgentSkillLink]
  Session[Session]
  Turn[ConversationTurn]
  FusionRun[FusionRun]
  EvalRun[AgentEvaluationRun]
  Cost[Cost Usage Governance]

  Agent --> AgentVersion
  Agent --> KnowledgeLink
  Agent --> MCPLink
  Agent --> SkillLink
  Agent --> Session
  Session --> Turn
  Agent --> FusionRun
  AgentVersion --> FusionRun
  Agent --> EvalRun
  AgentVersion --> EvalRun
  Agent --> Cost

flowchart LR
  AgentType[agent_type]
  Chat[chat]
  ETL[etl]
  Extraction[document_extraction]
  FusionDef[fusion_definition_runtime]
  FusionAgent[fusion business path]
  OrchestratorKey[orchestrator_key]
  ChatV1[chameleon_chat_v1]
  ReactV1[langgraph_react_agent_v1]

  AgentType --> Chat
  AgentType --> ETL
  AgentType --> Extraction
  AgentType --> FusionDef
  AgentType --> FusionAgent
  Chat --> OrchestratorKey
  OrchestratorKey --> ChatV1
  OrchestratorKey --> ReactV1

7. Chat Runtime

flowchart TB
  Input[OrchestratorInput]
  Registry[orchestrator/registry.py]
  Runtime[ChatOrchestratorRuntime]

  subgraph ChatModules[orchestrator]
    Graph[graph.py]
    React[react_agent.py]
    State[state.py]
    Kernel[runtime_kernel.py]
    Pipeline[capability_pipeline.py]
    Checkpoint[checkpoint_state.py]
    Routing[model_routing.py]
    MCPRuntime[mcp_runtime_config.py]
    MCPResponse[mcp_response_config.py]
    Passthrough[mcp_passthrough.py]
    Memory[memory.py]
  end

  Input --> Registry --> Runtime
  Runtime --> Graph
  Runtime --> React
  Graph --> State
  Graph --> Kernel
  Graph --> Pipeline
  Pipeline --> Routing
  Pipeline --> MCPRuntime
  Pipeline --> MCPResponse
  Pipeline --> Passthrough
  Pipeline --> Checkpoint
  Pipeline --> Memory

flowchart LR
  UserInput[User Input]
  History[Conversation History]
  Retrieval[Retrieval Stage]
  ToolDecision[MCP or Skill Decision]
  Approval[Checkpoint Approval]
  ToolCall[Tool Invocation]
  Generation[Final Generation]
  Events[OrchestratorEvent Stream]
  Persist[Turn Snapshot Persist]

  UserInput --> Retrieval
  History --> Retrieval
  Retrieval --> ToolDecision
  ToolDecision --> Approval
  Approval --> ToolCall
  ToolCall --> Generation
  Retrieval --> Generation
  Generation --> Events
  Events --> Persist

stateDiagram-v2
  [*] --> ReceiveInput
  ReceiveInput --> BuildContext
  BuildContext --> Retrieve
  Retrieve --> DecideTools
  DecideTools --> ApprovalRequired
  DecideTools --> Generate
  ApprovalRequired --> ToolInvoke
  ToolInvoke --> Generate
  Generate --> EmitEvents
  EmitEvents --> PersistTurn
  PersistTurn --> [*]

8. Fusion Runtime

flowchart TB
  subgraph FusionModules[fusion]
    Schemas[schemas.py]
    subgraph Services[fusion/services]
      DefinitionSvc[definition_service.py]
      AgentSvc[agent_service.py]
      LinkSvc[link_service.py]
      GovSvc[governance_service.py]
      RunSvc[run_service.py]
    end
    subgraph Runtime[fusion/runtime]
      Runner[runner.py]
      Graph[graph.py]
      Nodes[nodes.py]
      Prompt[prompt_builder.py]
      OutputMapper[output_mapper.py]
      Validator[validator.py]
      State[state.py]
    end
    subgraph Capabilities[fusion/capabilities]
      ModelBinding[model_binding.py]
      RAGBinding[rag_binding.py]
      MCPBinding[mcp_binding.py]
      StorageBinding[storage_binding.py]
      ImageBinding[image_generation_binding.py]
    end
  end

  Schemas --> Services
  Services --> Runtime
  Runtime --> Capabilities

flowchart LR
  LoadDef[load_definition]
  ValidateDef[validate_definition_contract]
  ValidateInput[validate_run_inputs]
  PersistInput[persist_validated_inputs]
  ResolveBindings[resolve_capability_bindings]
  PrepareFiles[prepare_file_artifacts]
  RetrieveCtx[retrieve_context]
  BuildPrompt[build_prompt]
  PlanTools[plan_tool_usage]
  InvokeTools[invoke_tools]
  InvokeModel[invoke_model]
  NormalizeOut[normalize_outputs]
  ValidateOut[validate_outputs]
  PersistOut[persist_outputs]
  Finalize[finalize_run]

  LoadDef --> ValidateDef --> ValidateInput --> PersistInput --> ResolveBindings --> PrepareFiles --> RetrieveCtx --> BuildPrompt --> PlanTools --> InvokeTools --> InvokeModel --> NormalizeOut --> ValidateOut --> PersistOut --> Finalize

flowchart TB
  Agent[Agent]
  AgentVersion[Published AgentVersion]
  Governance[Governance Context]
  FusionRun[FusionRun]
  Inputs[FusionRunInput]
  Outputs[FusionRunOutput]
  Trace[Trace URL Trace ID]

  Agent --> AgentVersion
  AgentVersion --> Governance
  Governance --> FusionRun
  FusionRun --> Inputs
  FusionRun --> Outputs
  FusionRun --> Trace

9. RAG 子系统

flowchart TB
  subgraph RAG[services/rag]
    Ingestion[ingestion.py]
    Chunking[chunking.py]
    Embedding[embedding.py]
    Retrieval[retrieval.py]
    MultiQuery[multi_query.py]
    Rerank[rerank.py]
    Debug[debug.py]
    SnapshotRebuild[snapshot_rebuild.py]
    VectorRecon[document_vector_reconciliation.py]
    ManualInspection[manual_inspection.py]
    DocRecognition[document_recognition.py]
  end

  Ingestion --> Chunking
  Ingestion --> Embedding
  Retrieval --> MultiQuery
  Retrieval --> Rerank
  SnapshotRebuild --> Ingestion
  VectorRecon --> Retrieval
  ManualInspection --> Retrieval
  DocRecognition --> Ingestion

sequenceDiagram
  participant Upload as Knowledge API
  participant MinIO as MinIO
  participant Parse as Parser
  participant Chunk as Chunking
  participant Embed as Embedding
  participant PG as PostgreSQL
  participant Vec as Qdrant

  Upload->>MinIO: save original file
  Upload->>PG: create document and ingestion job
  Upload->>MinIO: download file for processing
  Upload->>Parse: parse text
  Parse->>PG: save DocumentParseSnapshot
  Parse->>Chunk: chunk text
  Chunk->>PG: save DocumentChunk rows
  Chunk->>Embed: build embeddings
  Embed->>Vec: upsert vectors
  Vec->>PG: update vector status and counts

flowchart LR
  Query[User Query]
  SourceFilter[Active Source Filter]
  VectorSearch[Vector Retrieval]
  MultiQuery[Optional Multi Query]
  Rerank[Optional Rerank]
  FinalChunks[Final Retrieved Chunks]
  DebugReport[Debug Report]

  Query --> SourceFilter --> VectorSearch --> MultiQuery --> Rerank --> FinalChunks
  VectorSearch --> DebugReport
  MultiQuery --> DebugReport
  Rerank --> DebugReport

10. MCP 子系统

flowchart TB
  subgraph MCPControl[控制面]
    Server[MCPServer]
    Credential[MCPCredential]
    Link[AgentMCPLink]
    Audit[MCPCallAudit]
  end

  subgraph MCPRuntime[services/mcp]
    Registry[registry.py]
    Client[client.py]
    Adapter[tool_adapter.py]
    Policy[policy.py]
    Secret[secret_manager.py]
    RuntimeModels[tool_runtime_models.py]
    RuntimeStrategies[tool_runtime_strategies.py]
    Tracking[tool_tracking_runtime.py]
    ToolCaps[tool_capabilities.py]
    RuntimeAudit[audit.py]
  end

  Server --> Registry
  Credential --> Secret
  Link --> Registry
  Registry --> Adapter
  Adapter --> Policy
  Policy --> Client
  Client --> Tracking
  Tracking --> RuntimeAudit
  RuntimeAudit --> Audit
  ToolCaps --> Adapter
  RuntimeModels --> Adapter
  RuntimeStrategies --> Client

flowchart LR
  Agent[Agent]
  Links[Active MCP Links]
  Resolve[Resolve Runtime Mounts]
  Filter[Filter Inactive Servers]
  Normalize[Normalize Allowed Tools Timeout Budget Priority]
  Mounts[AgentMCPMountRuntimeConfig]
  Runtime[Chat or Fusion Runtime]

  Agent --> Links --> Resolve --> Filter --> Normalize --> Mounts --> Runtime

11. Skills 子系统

flowchart TB
  Skill[Skill]
  SkillVersion[SkillVersion]
  AgentSkillLink[AgentSkillLink]
  Registry[services/skills/registry.py]
  Policy[services/skills/policy.py]
  Executor[services/skills/executor.py]
  Audit[services/skills/audit.py]
  Runtime[Chat Runtime]

  Skill --> SkillVersion
  Skill --> AgentSkillLink
  AgentSkillLink --> Registry
  Registry --> Policy
  Policy --> Executor
  Executor --> Audit
  Runtime --> Registry

12. Evaluation 子系统

flowchart TB
  subgraph EvalStorage[evaluations domain]
    Dataset[EvaluationDataset]
    Item[EvaluationDatasetItem]
    Run[AgentEvaluationRun]
    Result[AgentEvaluationResult]
  end

  subgraph EvalServices[services/evaluation]
    Importer[dataset_importer.py]
    Runner[runner.py]
    Judge[judge.py]
    Metrics[metrics.py]
    Gate[gate.py]
    RuntimeSummary[runtime_summary.py]
    RunnerState[runner_state.py]
  end

  Dataset --> Item
  Dataset --> Run
  Run --> Result
  Importer --> Dataset
  Runner --> Run
  Runner --> Result
  Runner --> Judge
  Runner --> Metrics
  Runner --> Gate
  Runner --> RuntimeSummary
  Runner --> RunnerState

stateDiagram-v2
  [*] --> queued
  queued --> running : worker claim
  running --> heartbeat_expired : stale
  heartbeat_expired --> queued : supervisor recover
  running --> completed
  running --> failed
  completed --> [*]
  failed --> [*]

sequenceDiagram
  participant API as evaluation router
  participant Store as evaluation storage
  participant Worker as evaluation runner
  participant Runtime as chat orchestrator
  participant Judge as judge service
  participant Gate as gate service

  API->>Store: create queued run
  Worker->>Store: claim run
  loop dataset items
    Worker->>Runtime: execute item
    Runtime-->>Worker: answer
    Worker->>Judge: judge answer
    Worker->>Store: persist item result
  end
  Worker->>Gate: evaluate gate
  Worker->>Store: complete run

13. Scheduled Tasks 子系统

flowchart TB
  Task[ScheduledTask]
  TaskRun[ScheduledTaskRun]
  CreateReq[ScheduledTaskCreateRequest]
  Scheduler[scheduled_tasks.py]
  Timer[timer_scheduler.py]
  SessionRuntime[session_runtime.py]
  Checkpoint[runtime_checkpoint_service.py]
  Memory[agent_memory_service.py]
  Chat[Chat Runtime]

  CreateReq --> Scheduler
  Scheduler --> Task
  Task --> Timer
  Timer --> TaskRun
  Timer --> SessionRuntime
  SessionRuntime --> Chat
  SessionRuntime --> Checkpoint
  SessionRuntime --> Memory

flowchart LR
  ScheduleKind[schedule_kind]
  At[at]
  Every[every]
  Cron[cron]
  Timezone[timezone_name]
  TargetMode[target_mode]
  PayloadKind[payload_kind]
  ConflictPolicy[conflict_policy]

  ScheduleKind --> At
  ScheduleKind --> Every
  ScheduleKind --> Cron
  At --> Timezone
  Every --> Timezone
  Cron --> Timezone
  Timezone --> TargetMode --> PayloadKind --> ConflictPolicy

14. Document Extraction 与 ETL

flowchart TB
  subgraph Extraction[agents/document_extraction]
    EState[state.py]
    ENodes[nodes.py]
    EGraph[graph.py]
    ESchemas[schemas.py]
    EPdf[pdf_utils.py]
  end

  subgraph ETL[agents/etl]
    TState[state.py]
    TNodes[nodes.py]
    TGraph[graph.py]
    TCsv[csv_utils.py]
  end

  subgraph Shared[shared dependencies]
    Parsers[services/parsers]
    Jobs[storage model_domains jobs]
    Docs[storage model_domains documents]
  end

  Extraction --> Shared
  ETL --> Shared

flowchart LR
  AgentType[Agent Type]
  ChatRT[Chat Runtime]
  FusionRT[Fusion Runtime]
  ExtractionRT[Document Extraction Runtime]
  ETLRT[ETL Runtime]
  EvalRT[Evaluation Worker Runtime]
  TimerRT[Scheduled Replay Runtime]

  AgentType --> ChatRT
  AgentType --> FusionRT
  AgentType --> ExtractionRT
  AgentType --> ETLRT
  ChatRT --> EvalRT
  ChatRT --> TimerRT

15. 存储域模型

mindmap
  root((storage model_domains))
    admin_access
      AdminUser
      AdminPermissionGrant
      AdminRefreshToken
      AdminActionAudit
      AdminSystemSetting
    sessions
      Session
      Message
      ConversationTurn
      TurnContextSnapshot
      RuntimeCheckpoint
      AgentMemoryRecord
    agents
      Agent
      AgentVersion
      AgentRequestLease
      AgentUsageRollupSnapshot
      AgentCostOverviewSnapshot
    fusion
      FusionDefinition
      FusionDefinitionVersion
      FusionRun
      FusionRunInput
      FusionRunOutput
    jobs
      ETLJob
      DocumentExtractionJob
      DocumentExtractionFieldReview
    knowledge
      KnowledgeSource
      AgentKnowledgeLink
    knowledge_corrections
      KnowledgeCorrection
    documents
      Document
      DocumentParseSnapshot
      IngestionJob
      ManualInspectionRun
      ManualInspectionResult
      DocumentChunk
    evaluations
      EvaluationDataset
      EvaluationDatasetItem
      AgentEvaluationRun
      AgentEvaluationResult
    mcp
      MCPServer
      MCPCredential
      AgentMCPLink
      MCPCallAudit
    skills
      Skill
      SkillVersion
      AgentSkillLink
      SkillExecutionAudit
    scheduled_tasks
      ScheduledTask
      ScheduledTaskRun

flowchart TB
  Agent[Agent]
  AgentVersion[AgentVersion]
  KnowledgeSource[KnowledgeSource]
  AgentKnowledgeLink[AgentKnowledgeLink]
  MCPServer[MCPServer]
  AgentMCPLink[AgentMCPLink]
  Skill[Skill]
  AgentSkillLink[AgentSkillLink]
  Session[Session]
  Turn[ConversationTurn]
  Snapshot[TurnContextSnapshot]
  FusionRun[FusionRun]
  FusionInput[FusionRunInput]
  FusionOutput[FusionRunOutput]
  EvalRun[AgentEvaluationRun]
  EvalResult[AgentEvaluationResult]
  Task[ScheduledTask]
  TaskRun[ScheduledTaskRun]

  Agent --> AgentVersion
  Agent --> AgentKnowledgeLink
  KnowledgeSource --> AgentKnowledgeLink
  Agent --> AgentMCPLink
  MCPServer --> AgentMCPLink
  Agent --> AgentSkillLink
  Skill --> AgentSkillLink
  Agent --> Session
  Session --> Turn
  Turn --> Snapshot
  Agent --> FusionRun
  AgentVersion --> FusionRun
  FusionRun --> FusionInput
  FusionRun --> FusionOutput
  Agent --> EvalRun
  AgentVersion --> EvalRun
  EvalRun --> EvalResult
  Agent --> Task
  Task --> TaskRun

flowchart LR
  Postgres[(PostgreSQL)]
  MinIO[(MinIO)]
  Qdrant[(Qdrant)]
  Config[Configs Versions Audit Runs Tasks]
  Files[Original Documents Fusion File IO]
  Vectors[Embedding Points]

  Postgres --> Config
  MinIO --> Files
  Qdrant --> Vectors

16. 五条主链路

Chat

sequenceDiagram
  participant Client
  participant Core as core router
  participant Session as sessions domain
  participant Registry as chat registry
  participant Runtime as chat runtime
  participant Services as rag mcp skills model
  participant Persist as turn snapshot audit

  Client->>Core: POST /stream or WS
  Core->>Session: get or create session
  Core->>Registry: build runtime
  Registry->>Runtime: instantiate
  Runtime->>Services: retrieval tool generation
  Services-->>Runtime: outputs
  Runtime-->>Core: events and result
  Core->>Persist: persist turn context usage
  Core-->>Client: stream response

Fusion

sequenceDiagram
  participant Client
  participant Router as fusion router
  participant RunSvc as FusionRunService
  participant Runner as FusionRuntimeRunner
  participant Graph as Fusion Graph
  participant Store as fusion storage

  Client->>Router: create run json or multipart
  Router->>RunSvc: create_run
  RunSvc->>Store: persist FusionRun
  Router->>RunSvc: execute_run
  RunSvc->>Runner: run
  Runner->>Graph: execute graph
  Graph->>Store: persist inputs outputs trace
  Runner-->>Router: final state
  Router-->>Client: run response

Knowledge Ingestion

sequenceDiagram
  participant Client
  participant Router as knowledge router
  participant MinIO as minio
  participant Ingest as ingestion service
  participant Parser as parser
  participant PG as postgres
  participant Vec as qdrant

  Client->>Router: upload document
  Router->>MinIO: save original
  Router->>PG: create document and job
  Router->>Ingest: process_document
  Ingest->>MinIO: download file
  Ingest->>Parser: parse
  Parser->>PG: save parse snapshot
  Parser->>PG: save chunks
  Parser->>Vec: save vectors
  Ingest->>PG: update status

Evaluation

sequenceDiagram
  participant Admin
  participant API as evaluation router
  participant Store as evaluation store
  participant Worker as evaluation worker
  participant Runtime as chat runtime
  participant Judge as judge

  Admin->>API: create run
  API->>Store: queue run
  Worker->>Store: claim run
  loop item
    Worker->>Runtime: execute
    Runtime-->>Worker: answer
    Worker->>Judge: judge
    Worker->>Store: persist result
  end
  Worker->>Store: finalize gate

Scheduled Task Replay

sequenceDiagram
  participant User
  participant Runtime as chat runtime
  participant TaskSvc as scheduled task service
  participant Store as scheduled task store
  participant Timer as timer worker
  participant SessionRuntime as session runtime

  User->>Runtime: ask to schedule
  Runtime->>TaskSvc: create task
  TaskSvc->>Store: persist task
  Timer->>Store: poll due tasks
  Timer->>SessionRuntime: dispatch due task
  SessionRuntime->>Runtime: execute future turn

17. 后台恢复与自愈

flowchart TB
  Startup[Startup]
  IngestionCleanup[Cleanup Stale Ingestion Jobs]
  VectorRecon[Document Vector Reconciliation]
  EvalRecover[Recover Evaluation Worker]
  TaskRecover[Recover Scheduled Task Worker]
  Ready[Ready]

  Startup --> IngestionCleanup --> VectorRecon --> EvalRecover --> TaskRecover --> Ready

stateDiagram-v2
  [*] --> Running
  Running --> ProcessCrash
  ProcessCrash --> Restart
  Restart --> StartupRecovery
  StartupRecovery --> ReconcileJobs
  ReconcileJobs --> RequeueEval
  RequeueEval --> RestartSchedulers
  RestartSchedulers --> Running

18. 观测与治理

flowchart TB
  Runtime[Runtime Execution]
  TokenUsage[token_usage.py]
  Langfuse[langfuse_tracing.py]
  AdminAudit[admin audit]
  MCPAudit[mcp audit]
  SkillAudit[skill audit]
  TurnSnapshot[TurnContextSnapshot]
  Checkpoint[RuntimeCheckpoint]
  FusionTrace[FusionRun trace_url trace_id]
  EvalResult[Evaluation Result]

  Runtime --> TokenUsage
  Runtime --> Langfuse
  Runtime --> AdminAudit
  Runtime --> MCPAudit
  Runtime --> SkillAudit
  Runtime --> TurnSnapshot
  Runtime --> Checkpoint
  Runtime --> FusionTrace
  Runtime --> EvalResult

flowchart LR
  Governance[Governance]
  ModelRouting[Model Routing]
  Grounding[Response Grounding]
  MCPRuntimeCfg[MCP Runtime Config]
  MCPResponseCfg[MCP Response Config]
  RequestLease[Request Lease]
  UsageRollup[Usage Rollup]
  CostSnapshot[Cost Snapshot]
  AdminPerm[Admin Permission]

  Governance --> ModelRouting
  Governance --> Grounding
  Governance --> MCPRuntimeCfg
  Governance --> MCPResponseCfg
  Governance --> RequestLease
  Governance --> UsageRollup
  Governance --> CostSnapshot
  Governance --> AdminPerm

19. 扩展点

flowchart TB
  NewChat[新增 Chat Runtime]
  NewAgentType[新增 Agent Type]
  NewFusionCap[新增 Fusion Capability]
  NewParser[新增 Parser]
  NewMCPPolicy[新增 MCP Strategy Policy]
  NewEval[新增 Evaluation Logic]
  NewDomain[新增 Storage Domain]
  NewObs[新增 Observability]

  NewChat --> OrchestratorRegistry[orchestrator/registry.py]
  NewAgentType --> AgentsPlugin[agents/* plugin]
  NewFusionCap --> FusionCaps[fusion/capabilities]
  NewParser --> Parsers[services/parsers]
  NewMCPPolicy --> MCPServices[services/mcp]
  NewEval --> EvalServices[services/evaluation]
  NewDomain --> StorageDomains[storage/model_domains + migration]
  NewObs --> InfraObs[services/infra/observability]

20. 收敛结论

flowchart LR
  Gateway[统一入口]
  Agent[统一业务锚点 Agent]
  MultiRuntime[多 Runtime 并存]
  SharedServices[共享能力服务层]
  DomainStorage[Domain 化持久化真相源]
  Recovery[恢复与自愈]
  Audit[观测审计治理]

  Gateway --> Agent --> MultiRuntime --> SharedServices --> DomainStorage --> Recovery --> Audit

mindmap
  root((结论))
    ai_service 不是普通 CRUD API
    Agent 是统一控制面实体
    Chat 与 Fusion 是平行运行时
    RAG MCP Skills 是平台能力层
    Evaluation 与 Scheduled Tasks 是后台执行平面
    storage model_domains 是持久化真相源
    MinIO 与 Qdrant 是 RAG 与文件执行的基础设施
    Langfuse 审计 checkpoint trace 共同构成观测体系