前言从本文开始我们将进入一个完整的实战案例——“鸿蒙壁纸大师”。这是一个基于 A2AAgent-to-Agent协议构建的生产级智能体应用用户通过与小艺对话即可生成各种风格的 AI 壁纸。本项目代码托管在ai-wallpaper-server本文所有代码均来源于实际项目可直接运行。本系列将分 10 篇文章从架构设计到代码实现完整展示一个鸿蒙 A2A 智能体的全流程开发。本文是第一篇项目概述与架构设计。一、项目背景1.1 为什么选择 A2A 模式在鸿蒙智能体平台中开发者可以选择多种编排方式详见本系列第 1 篇。对于壁纸生成这类需要复杂业务逻辑和自有后端服务的场景A2A 模式是最佳选择模式适用场景为什么不选单 Agent纯对话场景需要调用外部 AI 模型单 Agent 无法满足工作流平台内部编排需要自定义 API 服务和模型调用OpenClaw第三方 API 接入需要复杂的业务逻辑和状态管理A2A自有服务集成✅ 完全自控灵活扩展1.2 核心能力鸿蒙壁纸大师具备以下核心能力┌─────────────────────────────────────────────┐ │ 鸿蒙壁纸大师 │ ├─────────────────────────────────────────────┤ │ ● 多轮交互选择风格 → 选择主题 → 选择场景 │ │ ● AI 生成调用火山引擎文生图模型生成壁纸 │ │ ● 智能优化LLM 优化提示词提升壁纸质量 │ │ ● 设备适配根据设备型号自动优化壁纸尺寸 │ │ ● 异步推送生成完成后通过 Webhook 通知用户 │ │ ● 实时进度SSE 流式推送生成进度 │ │ ● 卡片展示通过 DisplayFaCard 展示壁纸 │ └─────────────────────────────────────────────┘上图展示了鸿蒙壁纸大师的整体架构用户通过小艺触发 A2A 请求壁纸服务器处理后调用火山引擎模型生成壁纸二、整体架构2.1 系统架构图┌──────────────┐ A2A协议 ┌──────────────────┐ │ 用户设备 │ ◄────────────► │ 小艺开放平台 │ │ (鸿蒙手机) │ │ (智能体执行引擎) │ └──────────────┘ └────────┬─────────┘ │ A2A/JSON-RPC ▼ ┌────────────────────────────────────────────────────────┐ │ AI Wallpaper Server (FastAPI) │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │ │ │ Routes │ │ Services │ │ Models/Schemas │ │ │ │ 路由层 │ │ 服务层 │ │ 数据模型 │ │ │ ├──────────┤ ├──────────┤ ├──────────────────────┤ │ │ │ agent_ │ │ wallpaper│ │ JsonRpcRequest/ │ │ │ │ routes.py│ │ _service │ │ Response │ │ │ │ │ │ intent_ │ │ CardData/CardInfo │ │ │ │ │ │ service │ │ A2ATask/Message │ │ │ │ │ │ wallpaper│ │ │ │ │ │ │ │ _flow_ │ │ │ │ │ │ │ │ service │ │ │ │ │ │ │ │ webhook_ │ │ │ │ │ │ │ │ push_ │ │ │ │ │ └──────────┘ └──────────┘ └──────────────────────┘ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │ │ │ Utils │ │ Config │ │ Core │ │ │ ├──────────┤ ├──────────┤ ├──────────────────────┤ │ │ │ intent_ │ │ device_ │ │ config.py (Settings) │ │ │ │classifier│ │resolution│ │ .env 环境变量 │ │ │ │ logger │ │ │ │ │ │ │ └──────────┘ └──────────┘ └──────────────────────┘ │ └──────────────────────────┬─────────────────────────────┘ │ HTTP/HTTPS ▼ ┌────────────────────────────────────────────────────────┐ │ 火山引擎 API │ │ │ │ ┌──────────────────┐ ┌─────────────────────────────┐ │ │ │ Language Model │ │ Image Generation Model │ │ │ │ doubao-pro │ │ doubao-seedream-5-0 │ │ │ │ - 意图识别 │ │ - 文生图 │ │ │ │ - 提示词优化 │ │ - 根据 prompt 生成壁纸 │ │ │ │ - 闲聊回复 │ │ │ │ │ └──────────────────┘ └─────────────────────────────┘ │ └────────────────────────────────────────────────────────┘2.2 技术栈选择组件技术选型选择理由Web 框架FastAPI高性能异步框架原生支持 SSEHTTP 客户端httpx异步 HTTP 请求支持流式响应数据验证Pydantic v2类型安全的数据模型A2A 协议兼容 Google A2A 鸿蒙扩展标准化的 Agent 通信协议AI 模型火山引擎 (豆包)兼具语言理解和文生图能力部署方式Docker systemd生产级容器化部署2.3 核心数据流一次完整的壁纸生成请求涉及以下数据流转 一次完整的壁纸生成请求数据流 Step 1: 用户 → 小艺 用户帮我生成一张星空壁纸 Step 2: 小艺 → 智能体执行引擎 → 意图识别generate_wallpaper → 选择智能体壁纸大师 Step 3: 智能体执行引擎 → AI Wallpaper Server (A2A) POST /agent/message { jsonrpc: 2.0, method: message/stream, params: { message: { role: user, parts: [{kind: text, text: 帮我生成一张星空壁纸}] } } } Step 4: AI Wallpaper Server → 火山引擎 (LLM) POST /chat/completions → 意图识别用户想生成壁纸 → 返回风格选项卡片 Step 5: 用户选择风格 → ... (多轮交互) Step 6: 最终生成 → 调用火山引擎文生图 POST /images/generations { model: doubao-seedream-5-0, prompt: ...优化后的提示词..., size: 1080x2400 } Step 7: AI Wallpaper Server → 小艺 (SSE 流式返回) data: {result: {kind: status-update, ...}} data: {result: {kind: artifact-update, ...}} Step 8: 小艺 → 用户 显示生成的壁纸卡片 三、项目目录结构3.1 完整的目录结构ai-wallpaper-server/ ├── main.py # 应用入口FastAPI 应用初始化 ├── requirements.txt # Python 依赖 ├── Dockerfile # Docker 构建文件 ├── docker-compose.yml # Docker Compose 编排 ├── .env.example # 环境变量模板 │ ├── core/ │ ├── __init__.py │ └── config.py # 配置管理 Settings 类 │ ├── config/ │ ├── __init__.py │ └── device_resolution.py # 设备分辨率映射配置 │ ├── models/ │ ├── __init__.py │ └── schemas.py # JSON-RPC / A2A / 卡片数据模型 │ ├── routes/ │ ├── __init__.py │ └── agent_routes.py # A2A 路由处理核心1559行 │ ├── services/ │ ├── __init__.py │ ├── wallpaper_service.py # 壁纸生成服务LLM文生图 │ ├── wallpaper_flow_service.py # 壁纸流程管理器 │ ├── intent_service.py # 意图识别服务 │ └── webhook_push_service.py # Webhook 推送服务 │ ├── utils/ │ ├── __init__.py │ ├── intent_classifier.py # 意图分类器 │ └── logger.py # 日志配置多文件分类 │ └── tests/ ├── __init__.py ├── test_api.py # API 测试 ├── test_intent.py # 意图识别测试 ├── test_intent_llm.py # LLM 意图识别测试 ├── test_refactor.py # 重构测试 ├── manual_test.py # 手动测试脚本 └── integration_test.py # 集成测试3.2 各模块职责模块文件职责核心功能入口main.pyFastAPI 应用创建与生命周期路由注册、Session/上下文/任务状态管理配置core/config.py全局配置Settings 类、环境变量读取设备config/device_resolution.py设备分辨率映射手机/平板/折叠屏的分辨率配置数据模型models/schemas.py协议数据结构JSON-RPC、A2A、卡片模型路由routes/agent_routes.pyA2A 协议路由7 种 RPC 方法处理核心壁纸服务services/wallpaper_service.py壁纸生成LLM 调用、文生图调用、SSE 流式推送流程管理services/wallpaper_flow_service.py多轮交互流程风格/主题/场景三步骤状态机意图识别utils/intent_classifier.py用户意图分类7 种意图类型的 LLM 分类器Webhookservices/webhook_push_service.py异步消息推送HMAC-SHA256 签名推送日志utils/logger.py多文件日志请求/SSE/火山引擎/通用日志分离四、应用入口详解4.1 main.py 核心代码 AI Wallpaper API Service 基于鸿蒙 Agent 通信协议兼容 Google A2A实现的 API 服务 采用 Streamable HTTP JSON RPC 协议支持 SSE 流式输出 转发请求到火山引擎 OpenAI 兼容接口 importjsonfromdatetimeimportdatetime,timedeltafromtypingimportDict,List,AnyfromfastapiimportFastAPI,Requestfromfastapi.responsesimportJSONResponsefromutils.loggerimportlogger,set_session_idfromcore.configimportsettingsfromroutes.agent_routesimportrouterasagent_routerfromservices.wallpaper_flow_serviceimportflow_managers# 内存存储生产环境建议使用 Redisagent_sessions:Dict[str,Dict[str,Any]]{}# Session 存储conversation_contexts:Dict[str,List[Dict]]{}# 对话上下文task_states:Dict[str,Dict[str,Any]]{}# 任务状态asyncdeflifespan(app:FastAPI):FastAPI lifespan 事件处理器# 启动事件logger.info(*60)logger.info(AI Wallpaper API 启动)logger.info(fVOLCANIC_BASE_URL:{settings.VOLCANIC_BASE_URL})logger.info(fLANGUAGE_MODEL:{settings.LANGUAGE_MODEL})logger.info(fIMAGE_MODEL:{settings.IMAGE_MODEL})logger.info(fINTENT_MODEL:{settings.INTENT_MODEL})logger.info(*60)# 将共享状态注入到 app.stateapp.state.agent_sessionsagent_sessions app.state.conversation_contextsconversation_contexts app.state.task_statestask_statesyield# 停止事件logger.info(AI Wallpaper API 关闭)# 创建 FastAPI 应用appFastAPI(titleAI Wallpaper API,description基于鸿蒙 Agent 通信协议的 AI 壁纸生成 API 服务,version1.0.0,lifespanlifespan,)app.include_router(agent_router)# 注册路由4.2 关键 API 端点端点方法用途说明/GET服务信息返回服务名称、版本、协议等信息/healthGET健康检查用于 Docker 健康检查和监控/agent/messagePOSTA2A 消息处理所有 A2A 协议的 RPC 方法入口/agent/GETAgent 信息返回 Agent 名称、端点、模型/webhook/pushPOSTWebhook 回调接收平台的推送通知4.3 模型配置# core/config.py - 配置管理classSettings:应用配置def__init__(self):# 服务配置self.HOSTos.getenv(HOST,0.0.0.0)self.PORTint(os.getenv(PORT,8080))# 火山引擎配置self.VOLCANIC_API_KEYos.getenv(VOLCANIC_API_KEY,)self.VOLCANIC_BASE_URLos.getenv(VOLCANIC_BASE_URL,https://ark.cn-beijing.volces.com/api/v3)# 三种不同用途的模型self.LANGUAGE_MODELos.getenv(LANGUAGE_MODEL,doubao-seed-2-0-mini-250115)self.INTENT_MODELos.getenv(INTENT_MODEL,doubao-lite-4k)self.IMAGE_MODELos.getenv(IMAGE_MODEL,doubao-seedream-5-0-260128)# Webhook 推送配置self.WEBHOOK_API_KEYos.getenv(WEBHOOK_API_KEY,)self.WEBHOOK_API_SECRETos.getenv(WEBHOOK_API_SECRET,)self.WEBHOOK_API_IDos.getenv(WEBHOOK_API_ID,)五、A2A 协议实现5.1 支持的 RPC 方法本项目实现了鸿蒙 A2A 协议的 7 种 RPC 方法方法用途是否必须initialize会话初始化✅notifications/initialized初始化通知✅message/stream流式消息处理✅tasks/cancel取消任务✅clearContext清理上下文❌authorize用户授权❌deauthorize解授权❌5.2 路由分发逻辑# routes/agent_routes.py - 路由入口router.post(/message)asyncdefhandle_agent_message(request:Request,agent_session_id:Optional[str]Header(None,aliasagent-session-id),):统一的 Agent 消息处理接口bodyawaitrequest.json()jsonrpc_requestJsonRpcRequest(**body)methodjsonrpc_request.method# 路由到不同的处理方法ifmethodinitialize:resultawaithandle_initialize(...)elifmethodnotifications/initialized:resultawaithandle_initialized(...)elifmethodmessage/stream:returnawaithandle_message_stream(...)# SSE 流式响应elifmethodtasks/cancel:resultawaithandle_tasks_cancel(...)elifmethodclearContext:resultawaithandle_clear_context(...)elifmethodauthorize:resultawaithandle_authorize(...)elifmethoddeauthorize:resultawaithandle_deauthorize(...)else:resultJSONResponse(status_code400,content...)returnresult六、为什么这个项目值得学习6.1 生产级设计本项目不是一个玩具项目而是按照生产标准设计的完善的日志系统5 种分类日志通用/请求/SSE/火山引擎完整的错误处理超时、重试、降级策略Docker 部署容器化 健康检查 Compose 编排状态管理会话、上下文、任务三种状态独立管理6.2 实战参考价值学习点说明对应文章A2A 协议实现7 种 RPC 方法的完整实现第 30-32 篇多轮交互设计状态机驱动的流程管理第 33 篇LLM 集成意图识别 提示词优化 文生图第 34-35 篇SSE 流式推送实时进度更新第 36 篇Webhook 异步推送生成完成通知第 37 篇设备适配根据型号优化壁纸尺寸第 38 篇卡片交互selectList DisplayFaCard第 39 篇七、快速开始如果你已经迫不及待想体验项目可以按照以下命令快速启动# 克隆项目示例仓库gitclone https://github.com/example/ai-wallpaper-server.gitcdai-wallpaper-server# 复制环境变量模板cp.env.example .env# 安装依赖并启动服务pipinstall-rrequirements.txt uvicorn main:app--host0.0.0.0--port8080--reload快速开始仅用于本地体验生产部署请参考后续文章。总结本文介绍了鸿蒙壁纸大师项目的整体架构和设计思路项目背景选择 A2A 模式的原因系统架构三层架构小艺平台 壁纸服务器 火山引擎目录结构6 大模块的职责划分应用入口FastAPI 应用初始化和配置管理A2A 协议7 种 RPC 方法的分发逻辑学习价值生产级项目的参考意义接下来的文章将逐一深入每个模块的具体实现。下一篇我们将介绍环境搭建与基础配置从零开始搭建开发环境。如果这篇文章对你有帮助欢迎点赞 、收藏 ⭐ 和关注 你的支持是我持续创作的动力相关资源项目源码ai-wallpaper-serverFastAPI 官方文档A2A 协议规范 - 华为Google A2A 协议火山引擎 - 豆包大模型火山引擎 - API 文档鸿蒙智能体开发实战系列 - 全部文章JSON-RPC 2.0 规范SSE (Server-Sent Events) 规范Docker Compose 文档