# https://github.com/coze-dev/coze-studio 项目说明书

生成时间：2026-07-06 06:53:58 UTC

## 目录

- [项目概览与 DDD 架构总览](#page-1)
- [部署指南与常见启动故障排查](#page-2)
- [核心功能:Agent、Workflow、插件与知识库](#page-3)
- [模型管理、二次开发与社区贡献](#page-4)

<a id='page-1'></a>

## 项目概览与 DDD 架构总览

### 相关页面

相关主题：[部署指南与常见启动故障排查](#page-2), [核心功能:Agent、Workflow、插件与知识库](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/coze-dev/coze-studio/blob/main/README.md)
- [backend/main.go](https://github.com/coze-dev/coze-studio/blob/main/backend/main.go)
- [backend/application/application.go](https://github.com/coze-dev/coze-studio/blob/main/backend/application/application.go)
- [backend/infra/orm/impl/mysql/mysql.go](https://github.com/coze-dev/coze-studio/blob/main/backend/infra/orm/impl/mysql/mysql.go)
- [backend/domain/workflow/component_interface.go](https://github.com/coze-dev/coze-studio/blob/main/backend/domain/workflow/component_interface.go)
- [frontend/apps/coze-studio/src/app.tsx](https://github.com/coze-dev/coze-studio/blob/main/frontend/apps/coze-studio/src/app.tsx)
- [docker-compose.yml](https://github.com/coze-dev/coze-studio/blob/main/docker-compose.yml)
</details>

# 项目概览与 DDD 架构总览

## 一、项目定位与核心能力

Coze Studio 是 Coze（扣子）团队开源的一站式 AI Agent 开发平台，提供从模型接入、插件编排、知识库构建、工作流（Workflow/Chatflow）配置到智能体发布与调试的完整工具链。截至最新版本 V0.5.1，平台支持 Chatflow、多模型路由、配置管理仪表盘（`http://127.0.0.1:8888/admin`）以及对 Coze.cn 官方插件生态的接入能力 `资料来源：[README.md:1-40]()`。

平台主要由两个镜像构成：

- `cozedev/coze-studio-server`：基于 Go 语言实现的后端服务，承担业务逻辑、模型调度、插件执行与工作流编排职责。
- `cozedev/coze-studio-web`：基于 React/TypeScript 的前端工程，统一呈现工作流编辑器、Agent 调试控制台与后台配置面板。

社区中常见的部署问题（例如 `coze-server` 容器因 `Table 'opencoze.model_instance' doesn't exist` 反复重启）反映出项目当前依赖外部中间件（MySQL、Elasticsearch、MinIO）以及启动时执行的数据库迁移脚本；这些均属于"基础设施层"必须就绪的前置条件。

## 二、DDD 分层架构总览

后端代码遵循领域驱动设计（DDD）的经典四层架构，从入口到内核逐层收敛职责。下面用一张图说明各层之间的调用方向与依赖关系：

```mermaid
flowchart TB
    subgraph Interface["接口层 (interfaces/handler)"]
        HTTP["HTTP / OpenAPI / v3 路由"]
        ADMIN["Admin Dashboard API"]
        PLUGIN["Plugin Debugger API"]
    end

    subgraph App["应用层 (application)"]
        APP_SVC["application.go 服务装配"]
        USE_CASE["Use Case / Application Service"]
    end

    subgraph Domain["领域层 (domain)"]
        WF["workflow / chatflow"]
        AGENT["singleagent / plugin"]
        KB["knowledge / memory"]
    end

    subgraph Infra["基础设施层 (infra)"]
        ORM["orm/impl/mysql, elasticsearch"]
        OBJ["tos / minio 对象存储"]
        CONF["config / settings"]
    end

    HTTP --> APP_SVC
    ADMIN --> APP_SVC
    PLUGIN --> APP_SVC
    APP_SVC --> USE_CASE
    USE_CASE --> WF
    USE_CASE --> AGENT
    USE_CASE --> KB
    WF --> ORM
    AGENT --> OBJ
    KB --> CONF
```

各层职责说明：

- **接口层**负责协议适配与请求/响应序列化，将外部 HTTP/SDK 调用转化为对应用层服务的调用；`cozedev/coze-studio-server` 启动时通过 `backend/main.go` 注入路由与中间件 `资料来源：[backend/main.go:1-80]()`。
- **应用层**在 `backend/application/application.go` 中完成服务注册、依赖装配与生命周期管理，是协调领域对象完成用例（Use Case）的薄调度层 `资料来源：[backend/application/application.go:1-60]()`。
- **领域层**以 `domain/` 为根目录，按子域拆分：`workflow` 工作流编排（Chatflow 即在此基础上扩展）、`singleagent` 单智能体运行时、`plugin` 插件调用协议等。组件以接口契约方式暴露能力，例如 `domain/workflow/component_interface.go` 抽象了节点的输入/输出与执行契约 `资料来源：[backend/domain/workflow/component_interface.go:1-50]()`。
- **基础设施层**位于 `backend/infra/`，对数据库 ORM（`infra/orm/impl/mysql/mysql.go`）、对象存储（TOS/MinIO）、搜索引擎（Elasticsearch）以及全局配置做适配封装，并向领域层暴露不绑定具体实现的接口 `资料来源：[backend/infra/orm/impl/mysql/mysql.go:20-40]()`。

## 三、核心子域与模块边界

| 子域 | 主要目录 | 关注点 |
|------|---------|--------|
| workflow / chatflow | `backend/domain/workflow` | 节点图、DSL、执行引擎、Chatflow 多轮消息流 |
| singleagent | `backend/domain/singleagent` | Agent 决策循环、工具调用、消息路由 |
| plugin | `backend/domain/plugin` | OpenAPI v3 插件解析、沙箱执行、返回 `assistant` 多消息结构 |
| knowledge | `backend/domain/knowledge` | 知识库切片、检索召回、Embedding 缓存 |
| infra | `backend/infra` | 数据库、对象存储、向量检索、可观测性 |

设计上有两条隐含约束：领域层不直接依赖框架 Driver，而是通过 `infra` 提供的 Repository 接口反查；同时每个子域内的变更不应跨子域直接访问数据，避免耦合。社区多次出现的 Qwen 模型配置失败问题（#2520）也说明 `model_instance` 这类配置实体属于"配置管理"子域的边界，需由 admin 侧完成正确注册后业务侧才能调用 `资料来源：[backend/infra/orm/impl/mysql/mysql.go:20-60]()`。

## 四、部署运行与启动链路

平台推荐以 `docker-compose` 方式一键部署：

1. 由 docker-compose 编排 MySQL、Elasticsearch、MinIO、coze-server、coze-web 等容器 `资料来源：[docker-compose.yml:1-80]()`。
2. `coze-server` 启动时调用 `application.go` 装配基础设施，若任一依赖（数据库连接、MinIO 桶检查）失败则触发 `panic: InitializeInfra failed` 并退出，对应社区典型报错 `资料来源：[backend/application/application.go:60-120]()`。
3. 服务就绪后，前端通过反向代理访问 `coze-server` 暴露的 OpenAPI，前端路由入口位于 `frontend/apps/coze-studio/src/app.tsx`，并以多页面形式承载 IDE、Plugin、Admin 等模块 `资料来源：[frontend/apps/coze-studio/src/app.tsx:1-60]()`。

掌握这套"接口 → 应用 → 领域 → 基础设施"的依赖方向，能帮助开发者快速定位缺陷所属层级，从而选择合适的扩展点或贡献路径，符合社区对完善贡献指南（#62）与完善缺失功能（#488、#219）所期待的统一架构心智模型。

---

<a id='page-2'></a>

## 部署指南与常见启动故障排查

### 相关页面

相关主题：[项目概览与 DDD 架构总览](#page-1), [模型管理、二次开发与社区贡献](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docker/docker-compose.yml](https://github.com/coze-dev/coze-studio/blob/main/docker/docker-compose.yml)
- [docker/.env.example](https://github.com/coze-dev/coze-studio/blob/main/docker/.env.example)
- [docker/atlas/atlas.hcl](https://github.com/coze-dev/coze-studio/blob/main/docker/atlas/atlas.hcl)
- [docker/volumes/mysql/sql_init.sql](https://github.com/coze-dev/coze-studio/blob/main/docker/volumes/mysql/sql_init.sql)
- [docker/volumes/mysql/schema.sql](https://github.com/coze-dev/coze-studio/blob/main/docker/volumes/mysql/schema.sql)
- [docker/volumes/minio/.mc/config.json](https://github.com/coze-dev/coze-studio/blob/main/docker/volumes/minio/.mc/config.json)
</details>

# 部署指南与常见启动故障排查

## 概述

Coze Studio 采用 Docker Compose 作为官方推荐的一键部署方式，将基础中间件（MySQL、Redis、Elasticsearch、MinIO、PostgreSQL、etcd 等）与两个核心应用容器（`coze-server`、`coze-web`）通过编排文件统一拉起。`docker-compose.yml` 中通过 `depends_on` 声明容器启动顺序，但容器顺序并不等同于依赖就绪；`coze-server` 启动阶段会调用 `infra/orm/impl/mysql/mysql.go` 等模块逐项初始化各组件，任一环节失败都会触发 `panic: InitializeInfra failed` 并导致容器崩溃重启。本页梳理部署架构、启动流程，以及社区中频繁出现的冷启动故障与排查思路。

资料来源：[docker/docker-compose.yml:1-120]()

## 部署架构与服务依赖

部署由两个 Docker Compose 文件叠加构成：`docker-compose.yml` 负责中间件与 `coze-server`，第二份编排构建并启动 `coze-web`。基础设施账户、桶、索引等元数据均在首次启动时通过 `volumes` 挂载的初始化脚本自动注入，避免人工干预。

```mermaid
flowchart TD
    A[coze-web] --> B[coze-server]
    B --> C[MySQL]
    B --> D[Redis]
    B --> E[Elasticsearch]
    B --> F[MinIO/TOS]
    B --> G[etcd]
    B --> H[PostgreSQL]
    C --> I[sql_init.sql<br/>建库 + 授权]
    C --> J[Atlas + schema.sql<br/>建表]
    F --> K[mc config.json<br/>创建 opencoze 桶]
```

`coze-server` 必须等到所有依赖子系统健康后，HTTP/Thrift 服务端才会开始监听请求；任何中间件不可达都会中断整体启动链路。资料来源：[docker/docker-compose.yml:30-95](), [docker/volumes/mysql/sql_init.sql:1-40]()

## 环境准备与启动流程

1. 复制 `docker/.env.example` 为 `docker/.env`，按本机情况调整 `MYSQL_HOST`、`MINIO_HOST`、`ES_HOST` 等变量；该文件决定 `coze-server` 通过何种地址访问中间件。资料来源：[docker/.env.example:1-60]()
2. 在 `docker/` 目录执行 `docker compose up -d`，Compose 按 `depends_on` 拉起中间件；`coze-server` 启动时会按顺序输出 `init db`、`init redis`、`init tos client` 等阶段日志。资料来源：[docker/docker-compose.yml:60-110]()
3. 数据库结构由 Atlas 加载 `docker/atlas/atlas.hcl` 中的 schema 描述后应用；首次部署完成后 `model_instance`、`agent` 等核心业务表应已存在。资料来源：[docker/atlas/atlas.hcl:1-30](), [docker/volumes/mysql/schema.sql:1-40]()
4. 默认管理员账号初始化完成后访问 `http://127.0.0.1:8888` 进入配置管理面板，注册模型、插件与渠道。

## 常见启动故障排查

### MySQL 连接被拒绝

出现 `dial tcp ...:3306: connect: connection refused` 或 `mysql open ... unknown host`（对应 issue #2708）时，根因通常在于 `.env` 中 `MYSQL_HOST` 仍是默认的 `mysql`，而 Docker Desktop on Windows 等环境无法解析 Compose 网络内的服务名。

- 容器互通场景：保持 `MYSQL_HOST=mysql`，确认 `coze-server` 与 `mysql` 处于同一 Compose 网络。
- 跨主机部署：把 `MYSQL_HOST` 改为宿主机可达的 IP，并在 Windows 宿主机 `%WINDIR%\System32\drivers\etc\hosts` 中增加 `127.0.0.1 mysql`。
- 验证方式：`docker ps` 查看 `coze-mysql` 是否 `healthy`，否则进入容器执行 `mysqladmin ping`。资料来源：[docker/docker-compose.yml:30-50](), [docker/volumes/mysql/sql_init.sql:1-20]()

### MinIO/TOS 客户端初始化失败

报错 `err=init tos client failed ... no such host`（对应 issue #2703）多发于 Windows Docker Desktop，DNS 无法解析服务名 `minio`，导致 `mc` 客户端建桶失败：

- 在 `docker-compose.yml` 给 `coze-server` 添加 `extra_hosts: ["minio:host-gateway"]`，让容器通过宿主机网关访问。
- 删除 `minio` 数据卷后 `docker compose up -d minio`，`mc` 会按 `.mc/config.json` 中的凭据重建 `opencoze` 桶。资料来源：[docker/volumes/minio/.mc/config.json:1-25]()

### 数据库表缺失导致 `coze-server` 反复重启

日志报 `Table 'opencoze.model_instance' doesn't exist`（对应 issue #2704）说明 Atlas 迁移未生效：

- 确认 `docker-compose.yml` 中 MySQL 服务的 `volumes` 包含 `./volumes/mysql/sql_init.sql:/docker-entrypoint-initdb.d/init.sql`，由 MySQL 容器首次启动时执行建库与账号授权。资料来源：[docker/volumes/mysql/sql_init.sql:1-40]()
- 清理旧卷：`docker compose down -v && docker compose up -d mysql`，等待 `init script ran` 输出后再启动 `coze-server`，避免 Atlas 在表尚未创建时尝试连接。资料来源：[docker/atlas/atlas.hcl:1-25]()
- 重新启动 `coze-server` 后执行 `docker exec coze-mysql mysql -uroot -p opencoze -e "show tables"`，应能看到 `model_instance`、`agent`、`workflow` 等核心表。资料来源：[docker/volumes/mysql/schema.sql:1-40]()

### 日志检索技巧

`docker logs` 输出包含 ANSI 控制字符，默认 `grep` 会把它当作二进制文件处理。使用 `-a` 参数强制把输出视作文本，可顺利检索 `HandleMessage` 等关键字：

```
docker logs $(docker ps -aqf "name=coze-server") 2>&1 | grep -a 'HandleMessage'
```

资料来源：[docker/.env.example:1-30]()

## 总结

部署 Coze Studio 的关键在于保证中间件可达、表结构与对象存储桶在 `coze-server` 启动前已就绪。出现 `InitializeInfra failed` 时建议优先定位首个失败的子系统，对照上文修复策略逐项排查；遵循 `.env` 配置 → Compose 网络与 hosts → 初始化卷 → 应用容器顺序的检查链路，可覆盖社区中绝大部分冷启动失败案例（如 #2708、#2703、#2704）。若所有中间件都健康但仍反复 panic，请收集 `coze-server` 完整启动日志并附上 `docker compose config` 输出提交 issue，以便快速定位。资料来源：[docker/docker-compose.yml:1-120]()

---

<a id='page-3'></a>

## 核心功能:Agent、Workflow、插件与知识库

### 相关页面

相关主题：[项目概览与 DDD 架构总览](#page-1), [模型管理、二次开发与社区贡献](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [backend/domain/workflow/internal/compose/workflow.go](https://github.com/coze-dev/coze-studio/blob/main/backend/domain/workflow/internal/compose/workflow.go)
- [backend/domain/workflow/internal/schema/workflow_schema.go](https://github.com/coze-dev/coze-studio/blob/main/backend/domain/workflow/internal/schema/workflow_schema.go)
- [backend/domain/workflow/internal/nodes/llm/llm.go](https://github.com/coze-dev/coze-studio/blob/main/backend/domain/workflow/internal/nodes/llm/llm.go)
- [backend/domain/workflow/internal/nodes/json/json_deserialization.go](https://github.com/coze-dev/coze-studio/blob/main/backend/domain/workflow/internal/nodes/json/json_deserialization.go)
- [backend/domain/agent/singleagent/service/single_agent.go](https://github.com/coze-dev/coze-studio/blob/main/backend/domain/agent/singleagent/service/single_agent.go)
- [backend/domain/plugin/service/plugin_saas.go](https://github.com/coze-dev/coze-studio/blob/main/backend/domain/plugin/service/plugin_saas.go)
- [backend/domain/knowledge/service/knowledge.go](https://github.com/coze-dev/coze-studio/blob/main/backend/domain/knowledge/service/knowledge.go)
- [backend/conf/conf.go](https://github.com/coze-dev/coze-studio/blob/main/backend/conf/conf.go)
- [docker-compose.yml](https://github.com/coze-dev/coze-studio/blob/main/docker-compose.yml)
</details>

# 核心功能：Agent、Workflow、插件与知识库

## 功能定位与整体架构

Coze Studio 是一个面向 Agent 构建的一站式开发平台，其四大支柱能力由 `backend/domain/` 下的四个子领域共同承载：**SingleAgent（智能体）** 提供 LLM 对话与工具调用；**Workflow（工作流 / Chatflow）** 提供可视化节点编排与业务流程自动化；**Plugin（插件）** 为 Agent 与 Workflow 提供外部能力扩展；**Knowledge（知识库）** 提供文档级别的检索增强（RAG）能力。所有子模块共享同一套由 `backend/conf/conf.go` 加载的配置以及 `docker-compose.yml` 中的基础依赖（MySQL、MinIO、Elasticsearch 等）。

资料来源：[backend/conf/conf.go:1-50]()、`docker-compose.yml:1-100()`

## SingleAgent（智能体）

### 模块职责

`backend/domain/agent/singleagent/service/single_agent.go` 是 SingleAgent 服务的核心入口，封装了对单轮/多轮对话消息的处理、上下文组装、模型调用以及工具（插件、知识库）的调度逻辑。在 v0.5.0 中，官方为 OpenAPI v3 的 `/chat` 接口补充了 `assistant` 消息类型的支持，使第三方客户端可复用 Agent 的多轮会话能力。

资料来源：[backend/domain/agent/singleagent/service/single_agent.go:1-80]()

### 社区反馈

- Issue #2218（Q4 2025 路线图）提出需要完善 Agent 的长期记忆与多模态输入能力。
- Issue #2709 报告 Agent World 联盟认证接口（`/apply`）自 2026 年 7 月起持续返回 404，导致所有站点接入失败。

## Workflow（工作流 / Chatflow）

### 模块结构

工作流引擎在目录上按职责三层切分：

| 子目录 | 文件 | 职责 |
| --- | --- | --- |
| `compose/` | `workflow.go` | 把声明式 Schema 编译为可执行 DAG，控制节点调度顺序 |
| `schema/` | `workflow_schema.go` | 定义节点类型、边、变量作用域与输入输出契约 |
| `nodes/` | `llm.go`、`json_deserialization.go` 等 | 按节点类型实现具体执行逻辑 |

自 v0.3.0 起，引擎在传统“工作流”之上引入 Chatflow 模式，允许在工作流中持久化对话状态与变量，使 Agent、应用、单轮任务三种场景共享同一套节点语法。

资料来源：[backend/domain/workflow/internal/compose/workflow.go:1-60]()、`backend/domain/workflow/internal/schema/workflow_schema.go:1-80]()

### 典型执行链路

```mermaid
flowchart LR
    Start[Start 节点] --> VarAssign[变量赋值]
    VarAssign --> KBSearch[知识库检索]
    KBSearch --> LLM[LLM 节点]
    LLM --> JSON[JSON 反序列化]
    JSON --> End[End 节点]
    LLM -.分支.-> End
```

`nodes/llm/llm.go` 负责读取 prompt 模板、注入上游检索结果作为上下文，并解析模型输出；`nodes/json/json_deserialization.go` 提供结构化输出能力，将模型自由文本映射为下游可消费的对象。

资料来源：[backend/domain/workflow/internal/nodes/llm/llm.go:1-100]()、`backend/domain/workflow/internal/nodes/json/json_deserialization.go:1-80]()

> 社区提示：Issue #2702 多次呼吁官方开源“JSON 反序列化”节点；该功能在当前开源版本中并未完整开放。

## 插件（Plugin）

`backend/domain/plugin/service/plugin_saas.go` 处理插件的接入、鉴权与调用转发，对应 v0.5.0 中新增的“Coze.cn 插件官方市场”集成能力。插件既可在 SingleAgent 中被自动选用（作为工具），也可作为 Workflow 的独立节点被编排。

社区对该模块的反馈主要集中在生态层面：

- **Issue #488**：开源版与商业版插件市场完全隔离，Dify 风格的离线 `.difypkg` 安装机制尚未在 Coze Studio 中实现。
- **Issue #216**：UI 上缺少插件“查看”入口（已关闭）。
- **Issue #219**：希望补充图像/音/视频处理类插件节点。

资料来源：[backend/domain/plugin/service/plugin_saas.go:1-120]()

## 知识库（Knowledge）

知识库模块位于 `backend/domain/knowledge/service/knowledge.go`，负责文档上传、切片、向量化索引与召回，并在工作流中以“知识库检索”节点的形式对外暴露。检索结果通常作为 `LLM` 节点的 `context` 变量注入 prompt，从而实现检索增强生成（RAG）。

资料来源：[backend/domain/knowledge/service/knowledge.go:1-100]()

## 小结

四个核心模块之间通过统一的配置层（`backend/conf/conf.go`）与基础设施层（MySQL / MinIO / Elasticsearch）解耦：Agent 是“消费者”，调用插件与知识库；Workflow 是“编排者”，把 Agent、插件、知识库以及代码/条件节点串联；插件与知识库则是“能力提供者”。这一分层设计使得新增节点、新增插件或新增知识库类型时，核心业务模型保持稳定。

---

<a id='page-4'></a>

## 模型管理、二次开发与社区贡献

### 相关页面

相关主题：[部署指南与常见启动故障排查](#page-2), [核心功能:Agent、Workflow、插件与知识库](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [backend/bizpkg/config/modelmgr/modelmgr.go](https://github.com/coze-dev/coze-studio/blob/main/backend/bizpkg/config/modelmgr/modelmgr.go)
- [backend/bizpkg/llm/modelbuilder/model_builder.go](https://github.com/coze-dev/coze-studio/blob/main/backend/bizpkg/llm/modelbuilder/model_builder.go)
- [backend/conf/model/model_meta.json](https://github.com/coze-dev/coze-studio/blob/main/backend/conf/model/model_meta.json)
- [backend/conf/model/template/model_template_qwen.yaml](https://github.com/coze-dev/coze-studio/blob/main/backend/conf/model/template/model_template_qwen.yaml)
- [backend/conf/model/template/model_template_deepseek.yaml](https://github.com/coze-dev/coze-studio/blob/main/backend/conf/model/template/model_template_deepseek.yaml)
- [backend/infra/embedding/impl/ark/ark.go](https://github.com/coze-dev/coze-studio/blob/main/backend/infra/embedding/impl/ark/ark.go)
- [docker/.env](https://github.com/coze-dev/coze-studio/blob/main/docker/.env)
- [README.md](https://github.com/coze-dev/coze-studio/blob/main/README.md)
</details>

# 模型管理、二次开发与社区贡献

## 一、模型管理体系概览

Coze Studio 的模型能力以「配置中心 + 模板 + 构建器 + Provider」四层结构组织。配置中心入口在 v0.5.0 之后通过 `http://127.0.0.1:8888/admin` 提供可视化面板（参见 v0.5.0 release notes），后端核心逻辑由 `modelmgr.go` 负责加载、解析并校验模型定义；`model_builder.go` 将配置转换为运行时可调用的 LLM 客户端；`model_meta.json` 是模型元信息的单一事实来源；`backend/conf/model/template/` 目录下的 YAML 文件为不同厂商（Qwen、DeepSeek、Ark 等）提供参数模板。

| 层 | 主要职责 | 关键文件 |
|---|---|---|
| Meta | 模型清单、能力声明 | `conf/model/model_meta.json` |
| Template | 厂商参数默认值与字段映射 | `conf/model/template/*.yaml` |
| Manager | 启动期加载、CRUD、校验 | `bizpkg/config/modelmgr/modelmgr.go` |
| Builder | 运行时实例化 LLM/Embedding 客户端 | `bizpkg/llm/modelbuilder/model_builder.go` |
| Provider | 与具体厂商 SDK 交互 | `infra/embedding/impl/ark/ark.go` |

资料来源：[backend/bizpkg/config/modelmgr/modelmgr.go]()

## 二、二次开发：新增一个模型

新增模型的标准流程包含四步：

1. **准备元数据**：在 `model_meta.json` 中追加模型 ID、能力标签（chat / embedding / vision 等）与上下文窗口长度。
2. **复制模板**：从 `model_template_deepseek.yaml` 或 `model_template_qwen.yaml` 复制一份 `model_template_<vendor>.yaml`，按厂商文档填写 endpoint、API key 环境变量名、采样参数默认值。
3. **实现 Provider**：如使用新厂商 SDK，在 `backend/infra/embedding/impl/<vendor>/` 下新增适配文件，参考 `ark.go` 实现 `Embed` 接口。
4. **注册到 ModelManager**：通过 `modelmgr.go` 中的注册入口将模板路径与 Provider 绑定，并重启 `coze-server` 容器使配置生效。

常见排错要点：

- 启动时报 `Table 'opencoze.model_instance' doesn't exist`（issue #2704），多为首次部署未执行迁移脚本导致，需先完成数据库初始化。
- 添加 Qwen 模型报错（issue #2520）通常是因为 `template` 中的字段与 `model_meta.json` 的 schema 不匹配，需检查 `model_template_qwen.yaml` 中的必填项。
- 多模型成本路由（issue #2690）属于规划阶段，当前 ModelManager 不具备自动 fallback 能力，二次开发可在此层扩展。

资料来源：[backend/conf/model/template/model_template_qwen.yaml]()、[backend/conf/model/template/model_template_deepseek.yaml]()、[backend/infra/embedding/impl/ark/ark.go]()

## 三、社区贡献指南

社区普遍关心的两类贡献方向：(a) 补齐开源版相对商业版的功能差距（issue #62），(b) 插件生态的离线 `.difypkg` 互通方案（issue #488）。在提交代码前请遵循以下约定：

- **代码规范**：Go 模块遵循 `golangci-lint` 默认规则；TypeScript/React 部分保持 ESLint + Prettier 一致。
- **提交模板**：PR 描述须包含「动机 / 改动点 / 测试用例 / 关联 Issue」四段。
- **分支策略**：功能分支命名 `feat/<module>-<short-desc>`，修复分支 `fix/<issue-id>-<short-desc>`，目标合入 `main`；发布版本通过 tag 触发镜像构建（参考 v0.5.1 release 由 `@fanlv` 提交 PR #2404、#2405）。
- **可贡献模块**：`mod/plugin`（issue #216 已关闭，建议在新插件节点中回归测试）、多模态节点（issue #219 图像/音视频处理）、PostgreSQL 适配（issue #83，目前仅 MySQL 是默认支持的）。

```mermaid
graph LR
  A[Issue 提案] --> B[分支 feat/fix]
  B --> C[本地 lint + 单测]
  C --> D[提交 PR 关联 Issue]
  D --> E[Code Review]
  E --> F[合入 main + tag 发布]
```

资料来源：[README.md]()

## 四、已知限制与避坑

- **数据库**：默认仅支持 MySQL，PostgreSQL 需自行移植 `backend/infra/orm/impl/mysql/`（issue #83）。
- **对象存储**：MinIO 启动期会校验 `opencoze` bucket，Windows Docker Desktop 上若出现 `lookup minio ... no such host`（issue #2703），需检查 `docker/.env` 中 `MINIO_HOST` 与容器网络一致。
- **环境差异**：MySQL 连接被拒（issue #2708）多源于宿主机端口映射与容器内 `mysql:3306` 主机名冲突，应使用 `docker compose` 内置网络而非 `192.168.x.x`。
- **Python 运行时**：v0.5.1 之后若未检测到 `.venv`，会自动回退系统 Python（PR #2404），可减少插件节点的冷启动失败。
- **Agent World**：联盟接入 404（issue #2709）为外部服务问题，不属于开源版核心代码范围，需等待上游修复。

资料来源：[docker/.env]()

通过上述分层模型管理结构与清晰的贡献约定，开发者既能快速集成新模型，也能在「开源版 vs 商业版」差距处有序补齐功能，从而推动 Coze Studio 社区生态持续完善。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：coze-dev/coze-studio

摘要：发现 17 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。

## 1. 能力坑 · 能力证据存在缺口

- 严重度：high
- 证据强度：source_linked
- 发现：Sandbox install result is missing.
- 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
- 证据：evidence.evidence_gaps | https://github.com/coze-dev/coze-studio | Sandbox install result is missing.

## 2. 运行坑 · 沙箱验证已有失败原因

- 严重度：high
- 证据强度：runtime_trace
- 发现：llm_blocked_sandbox_execution
- 对用户的影响：失败原因未处理前，不应向用户暗示项目可顺利运行。
- 观测结果：sandbox_install_status=blocked; sandbox_quickstart_status=blocked; failure=llm_blocked_sandbox_execution
- 证据：sandbox_validation_results | planner_decision=llm_blocked; planner_reason=The candidate 'git clone' is not on the deterministic allowlist (only echo/python/node one-liners are) and is not an isolated install command.; failure=llm_blocked_sandbox_execution

## 3. 安全/权限坑 · 来源证据：[Feature Request] Multi-Model Smart Routing: Cost-aware model selection and fallback chains

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Multi-Model Smart Routing: Cost-aware model selection and fallback chains
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/coze-dev/coze-studio/issues/2690 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 安装坑 · 安装命令尚未沙箱验证

- 严重度：medium
- 证据强度：runtime_trace
- 发现：当前 install_status=documented，还只是文档/元数据线索。
- 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
- 复现命令：`git clone https://github.com/coze-dev/coze-studio.git`
- 观测结果：sandbox_install_status=blocked; sandbox_quickstart_status=blocked; failure=llm_blocked_sandbox_execution
- 证据：downstream_validation.install_status | https://github.com/coze-dev/coze-studio | install_status=documented; command=git clone https://github.com/coze-dev/coze-studio.git

## 5. 安装坑 · 来源证据：panic: InitializeInfra failed, err=init tos client failed, err=init minio client failed check bucket opencoze exist fai…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：panic: InitializeInfra failed, err=init tos client failed, err=init minio client failed check bucket opencoze exist failed Get "http://minio:9000/opencoze/?loc…
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/coze-dev/coze-studio/issues/2703 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 6. 安装坑 · 来源证据：problem

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：problem
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/coze-dev/coze-studio/issues/2704 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 7. 安装坑 · 来源证据：常见问题文档更新

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：常见问题文档更新
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/coze-dev/coze-studio/issues/217 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 8. 配置坑 · 来源证据：mysql InitializeInfra failed

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：mysql InitializeInfra failed
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/coze-dev/coze-studio/issues/2708 | 来源类型 github_issue 暴露的待验证使用条件。

## 9. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/coze-dev/coze-studio | README/documentation is current enough for a first validation pass.

## 10. 运行坑 · Quick Start 尚未实际跑通

- 严重度：medium
- 证据强度：runtime_trace
- 发现：quickstart_status=not_attempted。
- 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
- 观测结果：sandbox_install_status=blocked; sandbox_quickstart_status=blocked; failure=llm_blocked_sandbox_execution
- 证据：downstream_validation.quickstart_status | https://github.com/coze-dev/coze-studio | quickstart_status=not_attempted; sandbox_quickstart_status=blocked

## 11. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/coze-dev/coze-studio | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/coze-dev/coze-studio | no_demo; severity=medium

## 13. 安全/权限坑 · 存在安全注意事项

- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 证据：risks.safety_notes | https://github.com/coze-dev/coze-studio | No sandbox install has been executed yet; downstream must verify before user use.

## 14. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/coze-dev/coze-studio | no_demo; severity=medium

## 15. 安全/权限坑 · 来源证据：Agent World alliance onboarding completely broken — all API endpoints return 404

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Agent World alliance onboarding completely broken — all API endpoints return 404
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/coze-dev/coze-studio/issues/2709 | 来源类型 github_issue 暴露的待验证使用条件。

## 16. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/coze-dev/coze-studio | issue_or_pr_quality=unknown

## 17. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/coze-dev/coze-studio | release_recency=unknown

<!-- canonical_name: coze-dev/coze-studio; human_manual_source: deepwiki_human_wiki -->