Skip to content

lwh1919/HeartAI

BranchesTags

Repository files navigation

Demo: Multi-Modal AI Conversation + A2A Multi-Agent Playground

一个面向“实时语音/文本/图片对话”和“多智能体协作（A2A）”的全栈 Demo 项目。后端位于本目录 demo/，前端位于仓库同级目录 demo-front/。

✨ Highlights

  • 情感通话：WebSocket + Protobuf 协议，支持实时语音/文本/图片输入与流式响应（文本/音频/ASR 结果）ASR+LLM+TTS+VLM。
  • A2A 助理：Host Agent + Remote Agents 协作，支持注册/列出/移除 Agent，进行基础对话调度。
  • DDD 分层：biz（领域/用例）+ data（持久化）+ infra（技术组件）+ interface（适配层）。（正在重构为DDD中）
  • 统一接口：gRPC 为主，HTTP Gateway 提供 REST（grpc-gateway）少量ECHO HTTP接口，并通过 JWT 做基础鉴权。

🏗️ 项目结构

demo/
├── api/                    # API 定义 (protobuf)
│   ├── generated/          # 生成的 gRPC/Protobuf 代码
│   └── proto/              # 原始 proto 文件
├── cmd/                    # 主程序入口
│   └── main.go             # 应用程序主入口
├── internal/               # 内部代码 (不可导出)
│   ├── biz/                # 业务逻辑层 (DDD)
│   │   ├── domain/         # 领域模型
│   │   ├── ports/          # 端口定义
│   │   ├── repo/           # 仓储接口
│   │   └── usecase/        # 用例实现
│   ├── data/               # 数据访问层
│   │   ├── ent/            # Ent ORM 模型
│   │   └── schema/         # 数据库模式定义
│   ├── infra/              # 基础设施层
│   │   ├── a2a/            # Agent to Agent 通信
│   │   ├── ai/             # AI 服务 (ASR/LLM/VLM/TTS)
│   │   ├── configkv/       # 配置管理
│   │   ├── conversation/   # 对话管理
│   │   ├── database/       # 数据库连接
│   │   ├── jwt/            # JWT 认证
│   │   ├── server/         # 服务器实现
│   │   └── websocket/      # WebSocket 实现
│   └── interface/          # 接口层 (gRPC/HTTP)
│       ├── grpc/service/   # gRPC 服务实现
│       ├── serialization/  # 序列化
│       └── websocket/      # WebSocket 处理
├── pkg/                    # 可导出的公共包
│   ├── config/             # 配置管理
│   ├── errors/             # 错误处理
│   ├── logger/             # 日志
│   └── storage/            # 存储服务
├── proto/                  # 协议定义
├── testdata/               # 测试数据
├── .env                    # 环境变量配置 (本地)
├── go.mod                  # Go 模块定义
└── README.md               # 项目说明

🏛️ 架构设计

整体架构图

graph TB
    subgraph "客户端层"
        A[Web Frontend] 
        B[Mobile App]
        C[Third-party]
    end
    
    subgraph "接口层"
        D[gRPC Gateway]
        E[WebSocket Server]
        F[HTTP REST API]
    end
    
    subgraph "应用层"
        G[API Handlers]
        H[Use Cases]
    end
    
    subgraph "领域层"
        I[Domain Models]
        J[Business Logic]
    end
    
    subgraph "基础设施层"
        K[AI Services]
        L[Database]
        M[Config KV]
        N[Storage]
    end
    
    subgraph "数据层"
        O[Repository Impl]
        P[Ent ORM]
    end
    
    A --> D
    B --> E
    C --> F
    D --> G
    E --> G
    F --> G
    G --> H
    H --> I
    H --> J
    I --> O
    J --> O
    O --> P
    K --> H
    L --> P
    M --> H
    N --> H
Loading

情感通话设计

情感通话模块采用实时流式处理架构，支持多模态输入输出：

  1. 输入处理: WebSocket 接收语音/文本/图片输入
  2. AI 编排: ASR → LLM → TTS/VLM 流式处理
  3. 可打断设计: 支持用户在AI响应过程中随时打断
  4. 连接级别复用: WebSocket 连接复用，减少连接开销
  5. 流式响应: 实时返回文本/音频/图片分析结果
  6. 记忆整合: 会话结束后触发记忆归档/摘要
sequenceDiagram
    participant Client as 客户端
    participant WS as WebSocket
    participant Runtime as 对话 Runtime
    participant ASR as ASR
    participant LLM as LLM
    participant TTS as TTS
    participant VLM as VLM
    
    Client->>WS: 发送语音/文本/图片
    WS->>Runtime: 处理输入
    alt 语音输入
        Runtime->>ASR: 语音转文本
        ASR-->>Runtime: 文本结果
        Runtime->>LLM: 生成响应
        LLM-->>Runtime: 文本响应（流式）
    else 图片输入
        Runtime->>VLM: 图片分析
        VLM-->>Runtime: 分析结果
        Runtime->>LLM: 生成响应
        LLM-->>Runtime: 文本响应（流式）
    else 文本输入
        Runtime->>LLM: 生成响应
        LLM-->>Runtime: 文本响应
    end
    Runtime->>TTS: 文本转语音（流式）
    TTS-->>Runtime: 音频流（流式）
    Runtime->>WS: 返回响应
    WS->>Client: 流式返回结果
Loading

A2A 多智能体协作设计

A2A 模块支持多个远程智能体协作：

  1. Host Agent: 作为中央协调器，管理远程智能体
  2. Remote Agents: 提供特定领域能力的智能体
  3. 服务发现: 通过 Agent Card 实现自动注册发现
  4. 通信协议: 基于 JSON-RPC 的标准化通信
graph TB
    subgraph "A2A Host"
        A[Host Agent]
        B[Session Manager]
        C[Remote Agent Manager]
    end
    
    subgraph "Remote Agents"
        D[ULearning Agent]
        E[Other Agents...]
    end
    
    subgraph "Communication"
        F[JSON-RPC Protocol]
        G[Agent Card Discovery]
    end
    
    A --> B
    A --> C
    C --> D
    C --> E
    D --> F
    A --> G
Loading

🧩 功能模块

1) 认证 (Auth)

  • JWT 令牌认证
  • gRPC 拦截器链
  • TODO：a2a内部及ws模块鉴权

2) 角色 (Character)

  • 角色 CRUD。
  • 角色携带多种 AI 配置（brain/voice/ear/eye 等 JSON 字段），用于运行时创建对话 Runtime。
  • TODO：角色模版化实现角色可配置，可分享，记忆勾连RAG实现重大事件记录，减轻提示词压力

3) 情感通话 (Conversation)

  • WebSocket 连接后，通过 Protobuf 消息进行会话控制（SESSION_START/END）与输入（SPEECH/TEXT）。
  • 运行时编排：ASR → LLM → TTS → 音频流回传。
  • 记忆整合：连接关闭或 SESSION_END 触发记忆归档/摘要。
  • TODO：架构优化，DDD架构下，存在拆分问题
  • TODO：音色训练
  • TODO：聊天记录清洗（纸飞机），用于训练特定聊天风格的ai

4) 配置中心 (ConfigKV)

  • Key-Value 配置 CRUD。
  • 作为运行时调参入口（例如提示词模板、阈值、Provider 切换等）。
  • TODO：部分提示词为录入，未来考虑用redis存储

5) A2A 多智能体协作 (A2A)

  • 注册/列出/移除远程 Agent。
  • Host Agent 通过统一入口进行对话（当前处于最基础能力阶段）。
  • TODO：A2A模块DDD化，完善功能，实现服务自动注册发现
  • TODO：remote_agent,组件化，提取多个remote_agent的相同代码封装为库，减少荣誉代码
  • TODO：部分技能mcp服务器化，未来可能引入mcp服务器，实现工具共享，但是会存在链路长延迟大问题
  • TODO：remote_agent 中对于敏感的操作应该采用"请求采样"技术，如u学院签到，数据库写操作

6）注册中心

  • 目前采用读取环境变量
  • TODO：引入注册中心配置

7）前端

  • 目前只有管理员调试的前端版本
  • TODO：前端实现功能的编排

🧱 技术栈

Backend (本目录)

  • Go：go.mod 中声明为 go 1.25.0
  • gRPC + Protobuf + grpc-gateway
  • WebSocket：gorilla/websocket（封装在 internal/infra/websocket）
  • HTTP Server：Echo v4（仅承载 /health 与 /ws/conversation 等）
  • DB：PostgreSQL + Ent ORM
  • Auth：JWT（gRPC 拦截器链）
  • AI：多 Provider 注册表（ASR/LLM/VLM/TTS），带 Mock Provider
  • Storage：腾讯云 COS + STS 临时凭证

Frontend (仓库同级 demo-front/)

  • Vue 3 + TypeScript + Vite
  • Tailwind CSS + Shadcn UI 风格组件
  • Pinia + Vue Router
  • Protobuf 生成代码 + API Client（对接 HTTP Gateway）

🚀 快速开始

0) 前置依赖

  • Go（与 go.mod 匹配，建议安装 Go 1.25+）
  • Docker & Docker Compose
  • Node.js 18+（仅前端需要）
  • 可选：buf（需要重新生成 protobuf 时）

1) 配置环境变量

本项目会在启动时尝试加载同目录下的 .env（不存在则不报错，使用系统环境变量），见 pkg/config/env.go:9。

cd demo
cp env.example .env

最小可运行配置（仅跑通服务与基础接口）：

  • 数据库：DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME/DB_SSLMODE
  • 服务端口：SERVER_HOST/SERVER_PORT/GRPC_PORT/GATEWAY_PORT

要跑通“情感通话”完整链路（ASR/LLM/TTS/VLM）与上传：

  • 对应 Provider 的 API Key / URL / Model（见 env.example）
  • COS/STS 配置（不配会降级，部分功能不可用）

2) 启动数据库

cd demo
docker-compose up -d

3) 启动后端（WebSocket + gRPC + Gateway）

cd demo
go mod download
go run cmd/main.go
//启动remote_agent go run demo/internal/infra/a2a/remote_agent/ul/main.go

启动后你将得到：

  • WebSocket/HTTP：http://localhost:8080
  • gRPC：localhost:9090
  • HTTP Gateway：http://localhost:8081

健康检查：

curl http://localhost:8080/health

4) 启动前端（可选）

cd ../demo-front
npm install
npm run dev

🔌 常用命令（需要安装 buf）：

cd demo
buf generate proto
buf generate api/proto

Ent 代码生成

入口：internal/data/schema/generate.go:3

cd demo
go generate ./internal/data/schema

代码内 TODO

  • internal/interface/websocket/processor/request.go:29：WS 获取 userID（JWT/query）
  • internal/interface/websocket/processor/request.go:257：接口层调用业务方法违反分层
  • internal/infra/server/interceptors/auth.go:17：auth proto/白名单机制完善
  • internal/infra/server/interceptors/auth.go:111：子协程 panic 防护
  • internal/infra/websocket/connection.go:56：生产环境检查 Origin
  • internal/infra/a2a/go_host/multiagent/cli.go:2：移除/重构临时 CLI
  • internal/infra/ai/factory.go:19：补充更多注册表
  • internal/infra/ai/tts/doubao/protocol.go:230：处理压缩 payload

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages