夜雨聆风
Coze Studio 源码解读(一):项目架构与核心模块
Coze Studio 源码解读（一）：项目架构与核心模块
深入理解一站式 AI Agent 开发平台的设计理念
一、项目概述
1.1 Coze Studio 是什么
Coze Studio 是字节跳动开源的一站式 AI Agent 可视化开发平台，源自服务于数万家企业和百万开发者的”扣子开发平台”。
Coze Studio 定位
核心价值
├── 降低 AI Agent 开发门槛
├── 提供可视化开发工具
├── 支持无代码/低代码开发
└── 快速构建和部署 AI 应用
目标用户
├── 企业开发者
├── AI 应用创业者
├── 技术爱好者
└── 教育培训机构
应用场景
├── 智能客服
├── 知识问答
├── 内容生成
├── 数据分析
└── 业务自动化
1.2 技术栈概览
技术架构
后端 (Golang)
├── 框架: Hertz (字节跳动开源 HTTP 框架)
├── 架构: 微服务 + DDD (领域驱动设计)
├── 运行时: Eino (CloudWeGo AI 框架)
├── ORM: GORM
└── Go 版本: >= 1.23.4
前端 (TypeScript)
├── 框架: React 18 + TypeScript
├── 构建: Rush (Monorepo)
├── 工作流: FlowGram.ai
├── 状态: Zustand
└── UI: 自研组件库
基础设施
├── 数据库: PostgreSQL
├── 缓存: Redis
├── 对象存储: MinIO
├── 容器: Docker + Docker Compose
└── 编排: Helm (Kubernetes)
二、项目目录结构
2.1 顶层目录
coze-studio/
├── backend/ # Go 后端服务
├── frontend/ # React 前端应用
├── docker/ # Docker 配置文件
├── helm/ # Kubernetes Helm Charts
├── idl/ # 接口定义语言 (IDL)
├── docs/ # 文档
├── scripts/ # 脚本工具
├── common/ # 公共代码
├── Makefile # 构建脚本
└── README.md # 项目说明
2.2 后端目录详解
backend/
├── main.go # 入口文件
├── api/ # API 层
│ ├── router/ # 路由注册
│ └── middleware/ # 中间件
├── application/ # 应用层 (核心业务)
│ ├── app/ # 应用管理
│ ├── conversation/ # 对话管理
│ ├── knowledge/ # 知识库
│ ├── memory/ # 记忆系统
│ ├── modelmgr/ # 模型管理
│ ├── plugin/ # 插件系统
│ ├── prompt/ # 提示词管理
│ ├── workflow/ # 工作流引擎
│ ├── user/ # 用户管理
│ └── singleagent/ # 单 Agent 模式
├── domain/ # 领域层 (DDD)
├── infra/ # 基础设施层
├── pkg/ # 公共工具包
│ ├── logs/ # 日志
│ ├── lang/ # 语言工具
│ └── ...
├── internal/ # 内部模块
├── conf/ # 配置文件
└── types/ # 类型定义
2.3 前端目录详解
frontend/
├── apps/ # 应用入口
│ └── coze-studio/ # 主应用
├── packages/ # 共享包
│ ├── ui/ # UI 组件库
│ ├── workflow/ # 工作流组件
│ └── shared/ # 共享工具
├── config/ # 配置文件
├── infra/ # 前端基础设施
└── scripts/ # 脚本工具
三、核心功能模块
3.1 模块概览
核心功能模块
模型服务层
├── modelmgr/ # 模型管理器
├── 多模型支持 # OpenAI, Claude, 国产模型
└── 统一接口抽象 # 屏蔽模型差异
Agent 构建层
├── singleagent/ # 单 Agent 模式
├── app/ # 多 Agent 应用
├── prompt/ # 提示词管理
└── memory/ # 记忆系统
工作流引擎
├── workflow/ # 工作流核心
├── 节点执行器 # LLM, 代码, 条件等
├── 流程控制 # 串行, 并行, 分支
└── 状态管理 # 变量, 上下文
知识库系统
├── knowledge/ # 知识库管理
├── 文档解析 # PDF, Word, Markdown
├── 向量化 # Embedding
└── 检索系统 # 语义检索, 关键词
插件系统
├── plugin/ # 插件管理
├── API 插件 # HTTP 调用
├── 代码插件 # Python 执行
└── 内置插件 # 搜索, 图片等
对话系统
├── conversation/ # 对话管理
├── 会话上下文 # 多轮对话
├── 流式响应 # SSE/WebSocket
└── 消息存储 # 持久化
3.2 模块依赖关系
模块依赖架构
┌─────────────────────────────────────────────┐
│ API Layer │
│ (router + middleware) │
├─────────────────────────────────────────────┤
│ Application Layer │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Agent │ │Workflow │ │Knowledge│ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │
│ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ │
│ │ Model │ │ Plugin │ │ Memory │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
├───────┴──────────┴──────────┴───────────────┤
│ Domain Layer │
│ (领域模型 + 业务规则) │
├─────────────────────────────────────────────┤
│ Infrastructure Layer │
│ (DB + Cache + Storage + External API) │
└─────────────────────────────────────────────┘
四、架构设计原则
4.1 分层架构 (DDD)
DDD 分层设计
API 层 (Interface)
├── 职责: 接收请求、参数验证、响应格式化
├── 组件: Router, Middleware, Handler
└── 原则: 不包含业务逻辑
应用层 (Application)
├── 职责: 用例编排、业务流程协调
├── 组件: Service, UseCase
└── 原则: 协调领域对象完成业务
领域层 (Domain)
├── 职责: 核心业务逻辑、领域模型
├── 组件: Entity, ValueObject, Repository
└── 原则: 纯粹的业务规则
基础设施层 (Infrastructure)
├── 职责: 技术实现、外部服务
├── 组件: DB, Cache, API Client
└── 原则: 支撑上层实现
4.2 设计模式应用
常用设计模式
工厂模式
├── 模型提供者工厂
├── 插件实例工厂
└── 工作流节点工厂
策略模式
├── 不同模型的调用策略
├── 不同检索策略
└── 不同执行策略
观察者模式
├── 工作流事件监听
├── 对话消息订阅
└── 系统事件通知
装饰器模式
├── 中间件链
├── 插件增强
└── 日志装饰
依赖注入
├── 服务注册
├── 接口抽象
└── 测试友好
五、快速上手
5.1 环境准备
# 系统要求
CPU: 2 核+
内存: 4 GB+
磁盘: 20 GB+
# 必需软件
Docker: 24.0+
Docker Compose: 2.0+
# 可选 (开发环境)
Go: 1.23.4+
Node.js: 18+
pnpm: 8+
5.2 一键部署
# 克隆项目
git clone https://github.com/coze-dev/coze-studio.git
cd coze-studio
# macOS / Linux
make web
# Windows
cp ./docker/.env.example ./docker/.env
docker compose -f ./docker/docker-compose.yml up
5.3 初始化配置
部署后步骤
1. 注册账号
URL: http://localhost:8888/sign
2. 配置模型
URL: http://localhost:8888/admin/#model-management
添加: OpenAI / 火山引擎 / 其他模型
3. 开始使用
URL: http://localhost:8888/
六、核心配置说明
6.1 环境变量
# .env 配置示例
# 应用配置
APP_ENV=production
LISTEN_ADDR=:8888
LOG_LEVEL=info
# SSL 配置 (可选)
USE_SSL=0
SSL_CERT_FILE=
SSL_KEY_FILE=
# 数据库配置
DB_HOST=postgres
DB_PORT=5432
DB_USER=coze
DB_PASSWORD=coze123
DB_NAME=coze
# Redis 配置
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=
# 存储配置
STORAGE_TYPE=minio
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=coze
6.2 模型配置
# 模型配置示例
models:
- name: GPT-4o
provider: openai
api_key: sk-xxx
base_url: https://api.openai.com/v1
model: gpt-4o
- name: Claude-3.5
provider: anthropic
api_key: sk-xxx
model: claude-3-5-sonnet
- name: 豆包
provider: volcengine
api_key: xxx
model: doubao-pro
七、本章小结
7.1 知识点回顾
本章要点
1. 项目定位
├── 一站式 AI Agent 开发平台
├── 支持无代码/低代码开发
└── 开源免费，Apache 2.0 协议
2. 技术架构
├── 后端: Go + Hertz + DDD
├── 前端: React + TypeScript + Rush
└── 基础设施: Docker + PostgreSQL + Redis
3. 核心模块
├── 模型服务、Agent 构建
├── 工作流引擎、知识库
└── 插件系统、对话管理
4. 快速部署
├── Docker 一键启动
├── 模型配置
└── 开始使用
7.2 后续章节预告
系列教程规划
第二章 后端服务架构详解
├── 服务启动流程
├── 中间件机制
├── 路由设计
└── 错误处理
第三章 Agent 构建系统
├── Agent 模型设计
├── 提示词管理
├── 记忆系统
└── 多 Agent 协作
第四章 工作流引擎实现
├── 工作流定义
├── 节点执行器
├── 流程控制
└── 状态管理
第五章 插件系统开发
├── 插件架构
├── 插件开发指南
└── 内置插件实现
第六章 知识库与 RAG 实现
├── 文档处理
├── 向量化存储
└── 检索策略
第七章 前端架构与组件设计
├── Monorepo 架构
├── 工作流画布
└── 状态管理
第八章 部署与二次开发
├── 生产部署
├── 性能优化
└── 自定义扩展
软件定制开发，微信联系：rustgopy