AgentHub 开发者文档

Appearance

Architecture — 架构总览 ​

本页是根 README.md 的架构拆分页，给出 AgentHub V1.5 的纵向能力场域与横向技术分层全貌。 这是导读级摘要；唯一架构事实源为 docs/design/2.technical/architecture.md 与 architecture-scaffold.md（均已 frozen v1.0）。

一、架构形态：FastAPI 模块化单体 ​

AgentHub V1.5 采用 FastAPI Modular Monolith（见 ADR-0001）：单一后端进程内通过 7 个能力场域强隔离，每个场域对应 backend/app/ 下一个代码包。场域间禁止直接操作彼此的数据库表，跨域协作必须经显式接口契约。

二、纵向：7 个能力场域（Domain） ​

场域名称代码包关键能力
D-A建设态 · 项目与资源建模app/builder/项目壳 / 模型 / 知识库 / Agent 团队 / 套餐注册组装；只造材料
D-B建设态 · 流程编排与发布app/orchestrator/LangGraph WorkflowSpec、SOP DSL 校验、灰度路由、错误预算闸门
D-C交付态 · 应用交付与前端契约app/delivery/App Manifest、Workflow Binding、Conformance Token、PDK、OpenAPI 生成
D-D运行态 · 运营监控与系统自治app/ops/Prometheus / Alertmanager、四层指标、自愈剧本、Ops Agent 集群、飞书 IM
D-E消费态 · 用户任务执行app/runtime/LangGraph Checkpoint、NodeDispatcher、System/Tool/Agent Node、SSE/WebSocket
D-F消费态 · 商业化与账务app/billing/积分服务（乐观锁 + 行级锁）、预算服务、微信支付、补偿事务、对账
D-H横向 · 基础设施与平台内核app/core/Keycloak / OpenBao Adapter、审计、RLS / 限流中间件、Event Bus、Model Router、BFF Cache

编号规则：D-A~D-F 为业务场域，D-H 为横向支撑（无 D-G）。共 45 个产品模块映射到这 7 个代码包，映射表见 domain_and_module_division.md。

三、横向：5 个技术分层（Layer） ​

每个场域代码包内部都按下列层组织子目录（api/ service/ domain/ repository/）：

text
┌────────────────────────────────────────────────────────────┐
│ Layer 5  Frontend         React 控制台 / Taro 小程序 / PDK   │
├────────────────────────────────────────────────────────────┤
│ Layer 4  API / BFF        FastAPI Router + 中间件            │
│                           (JWT / RBAC / RLS / 限流 / Trace) │
├────────────────────────────────────────────────────────────┤
│ Layer 3  Application      UseCase 编排、事务边界、跨聚合协调   │
├────────────────────────────────────────────────────────────┤
│ Layer 2  Domain           领域模型 + 领域服务 + 领域事件      │
│                           业务规则与不变量；无框架依赖        │
├────────────────────────────────────────────────────────────┤
│ Layer 1  Infrastructure   仓储 / 适配器 / 外部 SDK 客户端     │
│                           SQLAlchemy / OpenBao / Keycloak…  │
└────────────────────────────────────────────────────────────┘
  • 纵向（场域 D-A~D-H） × 横向（技术分层 L1~L5） 构成二维矩阵。
  • 依赖方向严格自上而下：上层可依赖下层，下层不得反向依赖上层。
  • Domain 层零外部依赖：不得 import FastAPI / SQLAlchemy / httpx / structlog；业务规则与不变量落在此层。
  • API/BFF 层零业务逻辑：只做协议适配、入参校验、响应序列化，不得直接访问 ORM 做写操作。

四、依赖方向守卫：import-linter ​

层间与场域间的依赖方向由 import-linter 在 CI 中静态守卫，违反即构建失败：

bash
make importlinter      # = cd backend && uv run lint-imports

契约定义见 backend/pyproject.toml 的 [tool.importlinter] 段，原始合约规则见 architecture-scaffold.md §三。

五、AI / Agent 分层调度 ​

层选型职责
SOP 编排层LangGraph 1.0主流程编排 + Checkpoint 状态持久化
Agent 能力层（单 Agent）LangChain 1.0单 Agent Capability、工具封装、LLM Provider 抽象
Agent 能力层（多 Agent）AgentScope 1.0多 Agent 协作 Runtime
基础能力层D-H app/core/多租户、模型路由、凭证保险箱、预算熔断

三层解耦：SOP 流程变更不需要改 Agent 逻辑，Agent 能力升级不影响编排骨架。

六、相关页 ​