Coze Studio 原理与使用文档目录项目概览整体架构后端原理:Go + Hertz + DDD 前端原理:R

本文档基于对 coze-dev/coze-studio 仓库源码的深度分析整理而成,涵盖项目定位、架构原理、核心子系统实现、部署与二次开发指南。

阅读对象:希望深入理解或基于 Coze Studio 二次开发的工程师/架构师。

1. 项目概览

1.1 项目定位

Coze Studio 是字节跳动开源的一站式 AI Agent 可视化开发平台,源自服务千万级开发者的"Coze 开发平台"商业版,核心引擎完全开源。它解决的是 AI Agent 从开发到部署的全链路问题:

Prompt 工程:模板化 Prompt 管理
RAG 检索增强:知识库构建、文档解析、向量索引、Rerank
插件系统:第三方 API 接入(OpenAPI Schema + OAuth)
可视化工作流:拖拽式 DAG 编排(26+ 内置节点)
多模型接入:OpenAI、火山方舟、Claude、Gemini、Qwen、DeepSeek、Ollama
API & SDK:对话/工作流 OpenAPI、Web Chat SDK 嵌入业务系统

1.2 技术栈一览

层	技术
前端	React 18 + TypeScript + Semi Design + Tailwind + Zustand + FlowGram
前端构建	Rush.js Monorepo(135+ 包)+ Rsbuild/Rspack
后端	Go ≥ 1.23.4 + Hertz HTTP 框架
架构方法	DDD(领域驱动设计)+ 微服务式分层
Agent/Workflow 运行时	Eino (CloudWeGo LLM 编排框架)
数据库	MySQL 8.4.5(主数据)/ OceanBase(可选)
缓存	Redis 8.0
全文搜索	Elasticsearch 8.18(SmartCN 中文分词)
向量数据库	Milvus v2.5.10 / VikingDB / OceanBase 向量
对象存储	MinIO / 火山引擎 TOS
消息队列	NSQ(默认)/ Kafka / RocketMQ / Pulsar / NATS
配置中心	etcd 3.5
IDL	Apache Thrift(双向生成 Go + TypeScript)

1.3 仓库目录速览

coze-studio/
├── backend/         # Go 后端(DDD 分层)
├── frontend/        # 前端 Monorepo(Rush.js)
├── idl/             # Thrift 接口定义(前后端共享契约)
├── docker/          # docker-compose 部署
├── helm/            # Kubernetes Helm Chart
├── common/          # 跨语言共享(Go util、Python 沙箱等)
├── scripts/         # 构建/迁移脚本
├── docs/            # 设计文档
├── Makefile         # 一键编排
└── rush.json        # 前端 monorepo 工程定义

2. 整体架构

2.1 分层架构图

┌──────────────────────────────────────────────────────────────────┐
│  浏览器 / Chat SDK                                               │
└────────────────────────────┬─────────────────────────────────────┘
                             │ HTTP/WebSocket/SSE
┌────────────────────────────▼─────────────────────────────────────┐
│  coze-web (Nginx)         前端静态资源 + 反向代理                │
└────────────────────────────┬─────────────────────────────────────┘
                             │ /api/*  /v1/*
┌────────────────────────────▼─────────────────────────────────────┐
│  coze-server (Go Hertz)                                          │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ API Layer       Hertz Handler ← IDL 自动生成                 │ │
│ │ Middleware      Auth/I18n/Log/CORS/Inspector                 │ │
│ ├──────────────────────────────────────────────────────────────┤ │
│ │ Application     业务编排 + 跨域协调 + 事务/事件              │ │
│ ├──────────────────────────────────────────────────────────────┤ │
│ │ Domain          17 个限界上下文(Agent/Workflow/Knowledge…)   │ │
│ │   ├ entity     聚合根/值对象                                 │ │
│ │   ├ service    领域服务接口                                  │ │
│ │   ├ repository 仓储接口                                      │ │
│ │   └ internal   dal/convert/mock                              │ │
│ ├──────────────────────────────────────────────────────────────┤ │
│ │ Infra           DB/Cache/ES/Milvus/MinIO/NSQ/etcd 实现       │ │
│ └──────────────────────────────────────────────────────────────┘ │
└────────────┬─────────────────┬──────────────┬────────────────────┘
             │                 │              │
   ┌─────────▼──────┐  ┌───────▼──────┐  ┌────▼────────────┐
   │ MySQL/Redis/ES │  │ Milvus/MinIO │  │ NSQ / etcd      │
   └────────────────┘  └──────────────┘  └─────────────────┘
                                              ▲
                            (后台事件驱动:索引重建、异步任务等)

2.2 核心设计原则

DDD 限界上下文:每个领域(Agent / Workflow / Knowledge / Plugin / Conversation …)拥有完整的 entity / service / repository,通过 crossdomain/ 暴露的接口跨域调用,避免直接依赖。
Adapter 模式:前端大量使用 xxx-base + xxx-adapter 双包,商业版可替换 adapter 注入闭源功能;后端用接口隔离基础设施。
API-First / IDL 驱动:Thrift 是单一事实来源,Go Handler 与 TS Client 均自动生成,避免前后端契约漂移。
事件驱动:NSQ 用于异步任务(知识库重建索引、应用发布通知等),让在线请求保持低延迟。
流式优先:Agent 与 Workflow 全程基于 Eino schema.StreamReader[T],从模型 → 领域 → API → 浏览器 SSE 全链路流式。

3. 后端原理:Go + Hertz + DDD

3.1 后端目录布局(backend/)

目录	职责
`api/`	Hertz HTTP Handler、Middleware、Router(IDL 自动生成 + 手写胶水)
`application/`	应用服务层,组合多个领域服务、处理事务、发事件
`domain/`	17 个领域:agent / workflow / knowledge / plugin / conversation / memory / app / permission / user / connector / prompt / upload / openauth / search / template …
`crossdomain/`	跨域服务接口契约(避免循环依赖)
`infra/`	DB、Cache、ES、Milvus、MinIO、NSQ、etcd、CodeRunner、Embedding、Reranker、Parser 等基础设施实现
`conf/`	模型/插件/Prompt/Workflow 默认配置(JSON、模板)
`bizpkg/`	业务通用包(配置管理、调试、文件)
`pkg/`	通用工具(日志、上下文、错误码、i18n)
`types/`	共享类型、常量、DDL、错误码定义
`main.go`	服务入口

3.2 启动流程

入口在 backend/main.go,典型启动顺序:

// 1. 加载 .env / .env.{APP_ENV}
// 2. application.Init(ctx) —— 初始化全部依赖(数据库/缓存/ES/MQ/领域服务)
// 3. 启动 Hertz HTTP 服务

s := server.Default(opts...)
s.Use(middleware.ContextCacheMW())     // 必须最先
s.Use(middleware.RequestInspectorMW()) // 必须第二
s.Use(middleware.SetHostMW())
s.Use(middleware.SetLogIDMW())
s.Use(cors.New())
s.Use(middleware.AccessLogMW())
s.Use(middleware.OpenapiAuthMW())  // OpenAPI Token 鉴权
s.Use(middleware.SessionAuthMW())  // 会话鉴权
s.Use(middleware.I18nMW())         // 必须在 SessionAuthMW 之后
router.GeneratedRegister(s)        // 注册所有 IDL 生成的路由
s.Spin()

中间件顺序非常关键(ContextCacheMW 必须最先以建立请求级上下文缓存)。

3.3 应用层依赖注入

backend/application/application.go 是顶层组装点,依赖按层级初始化:

func Init(ctx context.Context) error {
    infra := appinfra.Init(ctx)              // 1. 基础设施
    basic := initBasicServices(infra)         // 2. 基础服务(用户/上传/权限)
    primary := initPrimaryServices(basic)     // 3. 主体服务(插件/知识/工作流)
    complex := initComplexServices(primary)   // 4. 编排服务(Agent/会话/搜索)
}

AppDependencies 集中持有所有基础设施句柄(appinfra/app_infra.go):

type AppDependencies struct {
    DB                       *gorm.DB
    CacheCli                 cache.Cmdable
    IDGenSVC                 idgen.IDGenerator
    ESClient                 es.Client
    OSS                      storage.Storage
    ResourceEventProducer    eventbus.Producer
    KnowledgeEventProducer   eventbus.Producer
    CodeRunner               coderunner.Runner
    ParserManager            parser.Manager
    SearchStoreManagers      []searchstore.Manager   // Milvus 等
    Reranker                 rerank.Reranker
    WorkflowBuildInChatModel modelbuilder.BaseChatModel
}

3.4 领域层典型布局

以 singleagent 为例(backend/domain/agent/singleagent/):

singleagent/
├── entity/                # 聚合根:SingleAgent、AgentPublish
├── repository/            # 仓储接口:SingleAgentRepo、DraftRepo
├── service/               # 领域服务
│   ├── single_agent.go         # 接口定义
│   ├── single_agent_impl.go    # 业务规则实现
│   └── executable_impl.go      # eino runtime 包装
└── internal/
    ├── dal/               # GORM model + 自动生成 query
    ├── convert/           # Entity ↔ DAL Model 转换
    └── mock/              # 测试 mock

领域服务接口示例:

type SingleAgent interface {
    CreateSingleAgentDraft(ctx context.Context, creatorID int64,
        draft *entity.SingleAgent) (int64, error)
    StreamExecute(ctx context.Context, req *entity.ExecuteRequest) (
        *schema.StreamReader[*entity.AgentEvent], error)
    GetSingleAgent(ctx context.Context, agentID int64, version string) (
        *entity.SingleAgent, error)
}

返回 schema.StreamReader[*AgentEvent] 即直接复用 Eino 的流式抽象。

3.5 基础设施实现 (infra/)

子系统	实现位置	用途
MySQL ORM	`infra/orm/impl/mysql/`	GORM + GORM Gen 生成 query
Redis	`infra/cache/impl/redis/`	缓存、ID 生成、Eino 检查点
Elasticsearch	`infra/es/impl/es/`	文档/对话/资源全文搜索
Milvus	`infra/document/searchstore/impl/`	知识库向量检索
MinIO/TOS	`infra/storage/impl/`	对象存储
NSQ	`infra/eventbus/impl/`	事件驱动
CodeRunner	`infra/coderunner/`	工作流 Code 节点的 Python 沙箱
Embedding	`infra/embedding/`	文本向量化
Reranker	`infra/rerank/`	检索结果重排
Parser	`infra/parser/`	PDF/Word 等文档解析
NL2SQL	`infra/nl2sql/`	自然语言转 SQL
ImageX	`infra/imagex/`	图像处理

4. 前端原理:Rush.js Monorepo + React 18

4.1 Monorepo 结构(135+ 包,4 层依赖)

通过 rush.json 严格管理依赖层级,杜绝循环引用:

层级	目录	角色	示例包
L1	`frontend/config/`、`frontend/infra/`、`frontend/packages/arch/`	基础设施	`bot-api`、`bot-http`、`bot-store`、`i18n`、`logger`、`idl-parser`
L2	`frontend/packages/common/`、`frontend/packages/foundation/`、`frontend/packages/data/common/`	通用组件/工具	`chat-area`、`chat-core`、`account-base`、`global-store`、`semi-ui` 包装
L3	`frontend/packages/{agent-ide,workflow,studio,data,project-ide,devops,plugins}/`	业务域	`agent-ide/entry`、`workflow/playground`、`data/knowledge-ide-base`
L4	`frontend/apps/coze-studio/`	主应用	路由编排 + 页面

4.2 主应用入口

frontend/apps/coze-studio/src/index.tsx → 初始化 i18n、特性开关、动态样式 → createRoot() 渲染 <App />。

构建器使用 Rsbuild(rsbuild.config.ts),关键能力:

chunk 切分:按尺寸切 3MB–6MB
Semi 主题插件:@douyinfe/semi-rspack-plugin
import-watch-loader:自定义热更
代理配置:开发态把 /api/* 与 /v1/* 转发到 localhost:8888
路由:React Router v6 + 动态 import + Suspense

4.3 关键业务包

包	职责
`agent-ide/entry`	Bot 创建/编辑器主入口
`agent-ide/chat-debug-area`	调试聊天面板
`agent-ide/bot-plugin`	插件挂载 UI
`workflow/playground`	工作流编辑器(画布 + 属性面板 + 调试)
`workflow/nodes`	26+ 节点 UI 组件与 schema
`common/flowgram-adapter`	FlowGram 适配层(自由布局/固定布局两套)
`studio/project-entity`	项目模式(把多个 agent/workflow 打包发布)
`data/knowledge-ide-base`	知识库管理 IDE
`data/database-v2`	表格型记忆数据库
`foundation/global-store`	全局 Store(账户、空间、配置)

4.4 状态管理:Zustand

每个业务域自维护 store。例如 frontend/packages/foundation/global-store/src/stores/common-config-store.ts:

import { create } from 'zustand';
import { devtools } from 'zustand/middleware';

export const useCommonConfigStore = create<State & Action>()(
  devtools(set => ({
    ...DEFAULT_COMMON_CONFIG_STATE,
    updateCommonConfigs(commonConfigs) {
      set(state => ({ ...state, commonConfigs }));
    },
    setInitialized: () => set({ initialized: true }),
  })),
);

4.5 API 客户端:IDL 生成

@coze-arch/bot-api 是面向业务的 RPC 入口,所有 namespace(developer_api / playground_api / workflow_api / knowledge / memory …)由 @coze-arch/idl2ts-* 链路从 idl/*.thrift 自动生成。这意味着前端永远不需要手写请求/响应类型。

import { DeveloperApi } from '@coze-arch/bot-api/developer_api';
const list = await DeveloperApi.GetBotList({ space_id });

底层 HTTP 由 @coze-arch/bot-http(Axios 封装)统一处理鉴权、错误码、i18n。

5. 核心子系统:工作流引擎

工作流是 Coze Studio 的最复杂子系统。它的设计哲学是:画布即 DSL,DSL 即 Eino DAG。

5.1 后端工作流域(backend/domain/workflow/)

workflow/
├── entity/
│   ├── workflow.go              # 聚合根(草稿/版本/Schema)
│   ├── node_meta.go             # 26+ 节点类型元数据
│   ├── workflow_execution.go    # 执行历史
│   └── interrupt_event.go       # 中断事件(用户问答/外部回调)
├── interface.go                 # 领域服务接口(Sync/Stream/Async/AsTool)
└── internal/
    ├── compose/                 # 基于 Eino 的执行引擎
    │   ├── workflow_run.go      # WorkflowRunner(总编排)
    │   ├── node_builder.go      # 节点构建/参数填充
    │   └── workflow_tool.go     # 工作流作为工具被 Agent 调用
    └── execute/                 # 低级执行控制
        ├── context.go           # 执行上下文(变量/路径/批处理)
        ├── event.go             # 中断/恢复事件
        └── callback.go          # 节点输出处理

5.2 内置节点类型(26+)

按用途归类:

类别	节点
流程	Entry / Exit
AI	LLM(对话模型)、IntentDetector(意图识别)
逻辑控制	Selector(If/Else)、Loop、Batch、Break、Continue
代码	CodeRunner(Python/JS 沙箱)
集成	Plugin、SubWorkflow、HTTPRequester
知识库	KnowledgeRetriever、KnowledgeIndexer
数据库	DatabaseQuery / Insert / Update / Delete
变量	VariableAssigner
数据处理	TextProcessor、JsonSerialization、JsonDeserialization
交互	QuestionAnswer(中断点)、ConversationHistory、ConversationList
IO	InputReceiver、OutputEmitter
辅助	Comment

5.3 前端画布:FlowGram 适配

前端基于字节开源的 FlowGram,包装于 common/flowgram-adapter。FlowGram 提供:

自由布局编辑器(@flowgram-adapter/free-layout-editor)
节点拖拽、连线、对齐、缩放
表单引擎与节点表单 schema
撤销重做、画布历史

业务侧只需在 workflow/nodes/ 注册节点元数据(图标、表单、运行时序列化规则)。

5.4 端到端执行链路

┌────────────────────────────────────────────────────────────┐
│ 1. 浏览器: 用户拖拽节点 → 画布 JSON Schema                  │
└─────────────────────┬──────────────────────────────────────┘
                     │ POST /api/workflow_api/save
                     ▼
┌────────────────────────────────────────────────────────────┐
│ 2. Hertz Handler → application/workflow                    │
│    持久化到 MySQL(workflow_draft 表)                       │
└─────────────────────┬──────────────────────────────────────┘
                     │ POST /api/workflow_api/test_run
                     ▼
┌────────────────────────────────────────────────────────────┐
│ 3. domain/workflow.WorkflowRunner                          │
│    - 加载 Schema → DSL                                     │
│    - 通过 Eino compose 构建 DAG                             │
│    - 节点 builder 注入(NodeBuilder Registry)               │
└─────────────────────┬──────────────────────────────────────┘
                     │
                     ▼
┌────────────────────────────────────────────────────────────┐
│ 4. 节点执行                                                 │
│    - field_fill: 入参从上游节点变量填充                      │
│    - type_convert: 自动类型转换                             │
│    - 调用模型 / 代码 / 数据库 / 插件                         │
│    - TokenCollector: 统计 token 消耗                       │
└─────────────────────┬──────────────────────────────────────┘
                     │
                     ▼
┌────────────────────────────────────────────────────────────┐
│ 5. 控制流                                                   │
│    - InterruptEvent: QuestionAnswer 节点暂停                │
│    - CheckPointStore (Redis): 保存中断现场                  │
│    - StreamWriter: 实时推送节点状态                         │
└─────────────────────┬──────────────────────────────────────┘
                     │ SSE
                     ▼
┌────────────────────────────────────────────────────────────┐
│ 6. 浏览器接收事件流                                          │
│    - 节点高亮、token 计数、中间结果、最终输出                │
└────────────────────────────────────────────────────────────┘

5.5 三种执行模式

SyncExecute:阻塞返回最终结果,适合 OpenAPI 调用方
StreamExecute:流式返回中间事件,用于调试 UI 与对话场景
AsyncExecute:返回 executeID 后台跑,客户端轮询/订阅,适合长任务

6. 核心子系统:Agent 与 Eino 运行时

6.1 Eino 框架

Eino 是 CloudWeGo 出的 Go LLM 编排框架,Coze Studio 用它来:

抽象模型调用(compose.Runnable)
统一流式协议(schema.StreamReader[T]、schema.Message)
DAG/Chain 组合
Checkpoint(支持工作流中断恢复)
适配多模型(eino-ext/components/model/* 适配 OpenAI / Ark / Claude / DeepSeek / Qwen / Ollama …)

6.2 SingleAgent 执行

backend/domain/agent/singleagent/service/executable_impl.go 把一个 Agent 的"模型 + 系统 Prompt + 工具(插件/工作流/知识库) + 记忆"组合为一个 Runnable,执行后返回 StreamReader[*AgentEvent],事件类型包括:

模型 token 增量
工具调用前/后
知识库召回片段
完成与错误

6.3 模型管理

模型配置存放于 backend/conf/model/,每个文件描述一个模型连接:

id: 100001
meta:
  conn_config:
    api_key: ${ARK_API_KEY}
    model: doubao-1-5-pro-32k
    base_url: https://ark.cn-beijing.volces.com/api/v3
  protocol: ark
  capability:
    function_call: true
    json_mode: true

启动时由 bizpkg/config/modelmgr/ 加载,运行时按 ID 选择。

7. 核心子系统:知识库 (RAG)

backend/domain/knowledge/ 实现完整 RAG 流水线:

原文档 (PDF/Word/MD/URL)
   │
   ▼ Parser (infra/parser)        # 解析 / OCR
   │
   ▼ 切片 (DocumentSlice 实体)
   │
   ▼ Embedding (infra/embedding)   # 向量化
   │
   ├──► Milvus (向量索引)
   └──► Elasticsearch (全文索引,SmartCN 中文分词)

查询时:
   Query
   │
   ▼ Embedding
   │
   ├──► Milvus 向量召回
   └──► ES BM25 召回
   │
   ▼ Rerank (infra/rerank)         # 重排提升精度
   │
   ▼ 拼入 LLM Prompt

文档处理通过 NSQ 事件异步执行(上传后立刻返回,后台索引),进度通过事件总线推送。

8. 核心子系统:插件系统

插件让 Agent 拥有调用外部 API 的能力。

协议:OpenAPI 3.0 Schema + OAuth 2.0
配置目录:backend/conf/plugin/
- pluginproduct/:官方插件模板
- common/oauth_schema.json:OAuth 通用 Schema
领域:backend/domain/plugin/ 负责注册、鉴权、调用、版本管理
运行时:Agent 通过 Eino 工具调用、Workflow 通过 Plugin 节点调用,统一走插件运行时

自定义插件:复制 pluginproduct/ 模板,填好 OpenAPI Schema、OAuth 信息(若需),在管理后台导入即可。

9. IDL 与代码生成

9.1 Thrift 文件分布(idl/)

idl/
├── api.thrift                  # 顶层服务汇总
├── app/*.thrift                # Bot/App、开发者 API
├── conversation/*.thrift       # 会话、消息、Agent run
├── workflow/*.thrift           # 工作流执行
├── data/*.thrift               # 知识库、数据库、变量
├── permission/*.thrift         # 鉴权、RBAC
├── plugin/*.thrift             # 插件管理
├── upload/*.thrift             # 文件上传
└── passport/*.thrift           # 用户体系

api.thrift 用 Thrift extends 把所有子服务串起来:

service IntelligenceService extends intelligence.IntelligenceService {}
service ConversationService extends conversation_service.ConversationService {}
service WorkflowService extends workflow_svc.WorkflowService {}

9.2 双向生成

Go 端:Hertz cwgo 生成 backend/api/handler/coze/ 与 backend/api/router/
TS 端:@coze-arch/idl2ts-cli 解析 → Babel AST → 输出到 frontend/packages/arch/bot-api/src/,并附带运行时类型

修改流程:改 Thrift → 重新生成 → 实现 / 调用。

10. 部署与运维

10.1 Docker Compose(开箱即用)

docker/docker-compose.yml 编排的服务清单:

服务	镜像	端口	作用
mysql	mysql:8.4.5	3306	主数据
redis	bitnami/redis:8.0	6379	缓存、检查点
elasticsearch	bitnami/elasticsearch:8.18.0	9200	全文搜索
milvus	milvusdb/milvus:v2.5.10	19530/9091	向量库
etcd	etcd:3.5	2379/2380	Milvus 元数据
minio	minio:RELEASE.2025-06-13	9000/9001	对象存储
nsqlookupd / nsqd / nsqadmin	nsq:1.2.1	多端口	消息队列
coze-server	cozedev/coze-studio-server:latest	8888/8889	Go 后端
coze-web	cozedev/coze-studio-web:latest	8888	Nginx 静态 + 反代

最低硬件要求:2 核 / 4 GB 内存。

10.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

启动后访问 http://localhost:8888/sign 注册账号,然后到 /admin/#model-management 添加模型。

10.3 Makefile 关键目标

目标	作用
`make web`	一键启动完整生产栈
`make middleware`	只启动中间件(MySQL/Redis/ES/Milvus/MinIO/NSQ/etcd)
`make server`	编译并运行 Go 后端
`make fe`	构建前端
`make debug`	完整开发模式(env + middleware + python + server)
`make sync_db`	Atlas 数据库迁移
`make dump_db`	导出 schema 为 HCL
`make sql_init`	初始化数据
`make atlas-hash`	重算迁移哈希

10.4 Helm Kubernetes(helm/)

StatefulSet:MySQL、Elasticsearch、etcd、Milvus、MinIO
Deployment:coze-server、coze-web
Job:Elasticsearch 索引初始化
ConfigMap:模型配置、ES 初始化脚本
可选:OceanBase 替代 MySQL/向量

10.5 公网部署的安全风险

官方明确提示不建议直接裸跑公网,需自行评估:

注册接口(应限制或加验证码)
Workflow Code 节点 Python 沙箱(强建议网络隔离)
coze-server 监听地址(不应暴露 8889 等内部端口)
SSRF(HTTPRequester / 知识库 URL 抓取)
部分接口的水平越权

11. 二次开发指南

11.1 开发环境

# 1. 拉取代码 + 安装依赖
git clone https://github.com/coze-dev/coze-studio.git
cd coze-studio
rush update                      # 注意:不要在根目录 npm install

# 2. 启动中间件
make middleware

# 3. 启动后端
make server

# 4. 启动前端
cd frontend/apps/coze-studio
npm run dev                      # 默认通过 rsbuild 起开发服务器

# 一键全开
make debug

11.2 添加一个工作流节点(典型流程)

后端
- 在 backend/domain/workflow/entity/node_meta.go 注册节点类型常量
- 在 backend/domain/workflow/internal/compose/ 实现 NodeBuilder(入参 schema、运行函数、流式行为)
前端
- 在 frontend/packages/workflow/nodes/ 添加节点目录:
  - meta.ts:节点元信息(图标、分类、表单 schema)
  - form/:Semi Design 表单组件
  - index.ts:注册到 NodeRegistry
国际化:在 frontend/packages/arch/i18n/ 添加文案
测试:在画布拖入新节点,联调输入输出

11.3 接入新模型

复制 backend/conf/model/template/ 模板到 backend/conf/model/
填写 id、meta.conn_config.api_key、meta.conn_config.model
选择 protocol(openai / ark / claude / gemini / qwen / deepseek / ollama)
重启 coze-server,在 /admin 后台启用

11.4 添加自定义插件

在 backend/conf/plugin/pluginproduct/ 复制一个模板目录
编辑 OpenAPI 3.0 Schema(api.json)
若需 OAuth,参考 common/oauth_schema.json
重启后在管理后台导入,在 Agent / Workflow 中挂载

11.5 修改 IDL/接口

修改 idl/*.thrift
重新生成:Go 端在 backend/api/handler/ 下补实现,TS 端通过 @coze-arch/idl2ts-cli 重新构建
在 backend/application/<domain>/ 编写应用层逻辑
在 backend/domain/<domain>/ 实现领域规则

11.6 测试

范畴	工具
前端单元/集成	Vitest(`rush test` / 包内 `npm run test`)
前端覆盖率	`npm run test:cov`
后端	Go 原生 `go test ./...`(在 `backend/` 下)
E2E	单独 e2e subspace 配置

测试覆盖率门槛(按包层级):

L1: 80% 覆盖,90% 增量
L2: 30% 覆盖,60% 增量
L3/L4: 灵活

11.7 提交规范

使用 rush commit(基于 Conventional Commits)
pre-commit 钩子自动跑 rush lint-staged
PR 前确保 rush test / rush lint 通过

12. 关键路径速查

后端

主题	路径
入口	backend/main.go
应用组装	backend/application/application.go
基础设施聚合	backend/application/base/appinfra/app_infra.go
中间件	backend/api/middleware/
路由注册	backend/api/router/register.go
各领域	backend/domain/
模型配置	backend/conf/model/
插件配置	backend/conf/plugin/
工作流引擎	backend/domain/workflow/internal/compose/

前端

主题	路径
Monorepo 配置	rush.json
主应用	frontend/apps/coze-studio/
主应用入口	frontend/apps/coze-studio/src/index.tsx
构建配置	frontend/apps/coze-studio/rsbuild.config.ts
API 客户端	frontend/packages/arch/bot-api/
API Schema 生成	frontend/packages/arch/api-schema/
工作流画布	frontend/packages/workflow/
FlowGram 适配	frontend/packages/common/flowgram-adapter/
Agent IDE	frontend/packages/agent-ide/
知识库 IDE	frontend/packages/data/knowledge-ide-base/
全局 Store	frontend/packages/foundation/global-store/

共享

主题	路径
Thrift IDL	idl/
Docker 编排	docker/docker-compose.yml
环境模板	docker/.env.example
Helm Chart	helm/charts/opencoze/
顶层 Makefile	Makefile
Claude 项目说明	CLAUDE.md

致谢与参考

Eino:Agent / Workflow 运行时 — github.com/cloudwego/e…
FlowGram:工作流画布编辑器 — github.com/bytedance/f…
Hertz:Go 高性能 HTTP 框架 — github.com/cloudwego/h…
Rush.js:大型 Monorepo 管理 — rushjs.io/
Rsbuild / Rspack:Rust 写的下一代打包工具 — rsbuild.dev/
Semi Design:字节开源 React 组件库 — semi.design/

License:Coze Studio 使用 Apache 2.0 协议开源。商业使用请关注其与商业版的功能差异(如音色定制等仅限商业版)。