|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +> 开始任务前先通读本文件；涉及架构决策时读 `ARCHITECTURE.md`；进入具体模块时读模块代码。 |
| 6 | +
|
| 7 | +## 项目概要 |
| 8 | + |
| 9 | +Coze Loop 是一个开源的 LLM 评测与可观测性平台，提供 Prompt 开发调试、评测（评测集 + 评估器 + 实验）、可观测性（Trace/Span）、模型集成（OpenAI / Volcengine Ark）等能力。采用 Go 后端（DDD 6 模块，Hertz + Kitex）+ TypeScript/React 前端（Rush.js 59 包）的多语言单体仓库架构，Thrift IDL 共享契约。 |
| 10 | + |
| 11 | +## 文档体系 |
| 12 | + |
| 13 | +| 层级 | 文件 | 职责 | |
| 14 | +|------|------|------| |
| 15 | +| L0 入口 | `AGENTS.md`（本文件） | 项目全貌、核心约束、导航 | |
| 16 | +| L1 架构 | `ARCHITECTURE.md` | 系统架构、代码地图、依赖关系、不变量 | |
| 17 | +| L1 专题 | `docs/AGENTS.md` | 中层索引，串联 reference/ 和 guidance/ | |
| 18 | +| L3 参考 | `docs/reference/backend-modules-api.md` | 后端 6 模块职责、分层、API 路由 | |
| 19 | +| L3 参考 | `docs/reference/frontend-packages.md` | 前端 59 包分层结构 | |
| 20 | +| L3 指南 | `docs/guidance/deployment-guide.md` | Docker Compose / Helm 部署 | |
| 21 | +| L3 指南 | `docs/guidance/idl-codegen-guide.md` | IDL 变更后代码生成流程 | |
| 22 | + |
| 23 | +## 导航表 |
| 24 | + |
| 25 | +| 我想… | 去哪里 | |
| 26 | +|-------|--------| |
| 27 | +| 了解仓库整体架构和模块关系 | `ARCHITECTURE.md` | |
| 28 | +| 查找 docs 下的专题文档 | `docs/AGENTS.md` | |
| 29 | +| 了解后端 6 个 DDD 模块的职责和 API | `docs/reference/backend-modules-api.md` | |
| 30 | +| 了解前端 59 包的分层结构 | `docs/reference/frontend-packages.md` | |
| 31 | +| 部署 Coze Loop（Docker / Helm） | `docs/guidance/deployment-guide.md` | |
| 32 | +| 修改 IDL 后生成代码 | `docs/guidance/idl-codegen-guide.md` | |
| 33 | +| 修改数据库表结构 | 本文件「开发流程」→ Step 3-4 | |
| 34 | +| 添加新的 API 接口 | 本文件「开发流程」→ Step 1-2 → Step 6 | |
| 35 | +| 运行本地开发环境 | `make compose-up-dev` | |
| 36 | +| 了解错误码定义规范 | 本文件「开发流程」→ Step 7 | |
| 37 | +| 执行 lint 检查 | `cd backend && golangci-lint run --config ../.github/.golangci.yaml --fix` | |
| 38 | + |
| 39 | +## 仓库结构 |
| 40 | + |
| 41 | +``` |
| 42 | +coze-loop/ |
| 43 | +├── idl/thrift/coze/loop/ # Thrift IDL（前后端共享契约，同步源） |
| 44 | +│ ├── <module>/domain/ # 开源领域实体 |
| 45 | +│ ├── <module>/domain_openapi/# OpenAPI 领域实体 |
| 46 | +│ └── <module>/coze.loop.*.thrift # 服务接口 |
| 47 | +├── backend/ |
| 48 | +│ ├── cmd/ # 服务入口（main.go HTTP, consumer.go MQ） |
| 49 | +│ ├── api/ # Hertz 网关层（生成 + handler） |
| 50 | +│ ├── modules/ # 6 个 DDD 业务模块 |
| 51 | +│ │ ├── evaluation/ # 评测（实验 / 评估器 / 评测集） |
| 52 | +│ │ ├── observability/ # 可观测性（Trace / Span） |
| 53 | +│ │ ├── prompt/ # Prompt 管理 |
| 54 | +│ │ ├── data/ # 数据管理（Dataset） |
| 55 | +│ │ ├── llm/ # LLM 模型集成 |
| 56 | +│ │ └── foundation/ # 基础（用户 / 空间 / API Key） |
| 57 | +│ ├── infra/ # 共享基础设施（DB, Redis, ClickHouse, MQ, middleware） |
| 58 | +│ ├── pkg/ # 共享工具库 |
| 59 | +│ ├── kitex_gen/ # Kitex 生成代码 ⚠️ 禁止手动修改 |
| 60 | +│ ├── loop_gen/ # Loop 生成代码 ⚠️ 禁止手动修改 |
| 61 | +│ └── script/ # 代码生成脚本 |
| 62 | +│ ├── cloudwego/code_gen.sh # IDL → Go |
| 63 | +│ ├── gorm_gen/generate.go # SQL → GORM Model |
| 64 | +│ └── errorx/code_gen.py # 错误码生成 |
| 65 | +├── frontend/ # Rush.js 前端 monorepo（59 包） |
| 66 | +│ ├── apps/cozeloop/ # 主 SPA（React 18, Rsbuild, react-router, zustand） |
| 67 | +│ ├── packages/ # loop-pages, loop-modules, loop-components, loop-base |
| 68 | +│ ├── config/ # eslint-config, ts-config, vitest-config 等 |
| 69 | +│ └── infra/ # IDL 转 TypeScript 工具等 |
| 70 | +├── release/deployment/ |
| 71 | +│ ├── docker-compose/ # Docker 部署（conf/ + bootstrap/） |
| 72 | +│ └── helm-chart/ # Kubernetes 部署 |
| 73 | +└── common/ # git-hooks（Rush 管理） |
| 74 | +``` |
| 75 | + |
| 76 | +## 核心约束 |
| 77 | + |
| 78 | +### 1. DDD 分层纪律 |
| 79 | + |
| 80 | +每个 `backend/modules/<domain>/` 遵循三层架构，依赖方向单向： |
| 81 | + |
| 82 | +``` |
| 83 | +api/ → application/ → domain/ ← infra/ |
| 84 | +``` |
| 85 | + |
| 86 | +- **domain/** 定义接口，**infra/** 实现接口，domain **绝不**引用 infra |
| 87 | +- Application 层负责 DTO↔DO 转换、用例编排 |
| 88 | +- Repository 的事务只在 infra 层启动 |
| 89 | + |
| 90 | +### 2. IDL 优先 |
| 91 | + |
| 92 | +`idl/thrift/` 是接口契约的同步源。商业化 IDL 仓库的 `open/` 目录从此处同步。修改 IDL 后必须运行代码生成。 |
| 93 | + |
| 94 | +### 3. 生成代码不可手动修改 |
| 95 | + |
| 96 | +- `backend/kitex_gen/` — Kitex 生成 |
| 97 | +- `backend/loop_gen/` — Loop 本地调用生成 |
| 98 | +- `backend/api/router_gen.go` — Hertz 路由生成 |
| 99 | +- `**/wire_gen.go` — Wire DI 生成 |
| 100 | +- `**/gorm_gen/**` — GORM 模型生成 |
| 101 | + |
| 102 | +### 4. 向前兼容 |
| 103 | + |
| 104 | +已有企业用户二开部署。IDL API / Domain 核心接口 / 配置文件 / 存储 Schema 均要求向前兼容。新增字段必须 optional，数据库只允许加列。 |
| 105 | + |
| 106 | +### 5. SQL 双路径同步 |
| 107 | + |
| 108 | +修改数据库表时，以下两个目录必须保持一致： |
| 109 | +- `release/deployment/docker-compose/bootstrap/mysql-init/`（Docker） |
| 110 | +- `release/deployment/helm-chart/charts/app/bootstrap/init/mysql/init-sql/`（Helm） |
| 111 | + |
| 112 | +修改表还需要在 `patch-sql/` 写 ALTER 语句。CI 会通过 `mysql-schema-check` 工作流校验两侧一致性。 |
| 113 | + |
| 114 | +### 6. 前端依赖分层 |
| 115 | + |
| 116 | +前端 6 层依赖结构（Level-1 到 Level-6），高层级只能依赖低层级，禁止反向依赖。商业版与开源版差异通过 Adapter 模式解耦（`adapter-interfaces/` → `*-adapter/` → `components-with-adapter/`）。 |
| 117 | + |
| 118 | +## 后端开发流程 |
| 119 | + |
| 120 | +``` |
| 121 | +Step 1: IDL 定义 → Step 2: 代码生成 → Step 3: MySQL Schema → Step 4: GORM Gen |
| 122 | +→ Step 5: 配置文件 → Step 6: 业务代码 → Step 7: 错误码 → Step 8: 国际化 |
| 123 | +→ Step 9: UT → Step 10: golint |
| 124 | +``` |
| 125 | + |
| 126 | +详细步骤见 `docs/guidance/idl-codegen-guide.md`（Step 1-2）和 `docs/guidance/deployment-guide.md`（部署配置）。 |
| 127 | + |
| 128 | +**Wire 依赖注入**：修改 `wire.go` 后运行 `wire generate` 重新生成 `wire_gen.go`。禁止手动编辑 `wire_gen.go`。 |
| 129 | + |
| 130 | +**代码复用约束**：新增功能前必须先搜索 codebase 是否已有相同/类似实现，有则复用或扩展，不得新建重复文件。 |
| 131 | + |
| 132 | +## 常用命令 |
| 133 | + |
| 134 | +### 后端（Go） |
| 135 | + |
| 136 | +| 操作 | 命令 | |
| 137 | +|------|------| |
| 138 | +| Go 编译 | `cd backend && go build ./...` | |
| 139 | +| 全量测试 | `cd backend && go test -gcflags="all=-N -l" ./...` | |
| 140 | +| 单测（指定包） | `cd backend && go test -gcflags="all=-N -l" ./modules/<domain>/...` | |
| 141 | +| 单测（指定函数） | `cd backend && go test -gcflags="all=-N -l" -run TestFuncName ./modules/<domain>/...` | |
| 142 | +| CI 级测试（含 race） | `cd backend && go test -gcflags="all=-N -l" -race -v -coverprofile=coverage.out -coverpkg=./... ./...` | |
| 143 | +| golint 修复 | `cd backend && golangci-lint run --config ../.github/.golangci.yaml --fix` | |
| 144 | +| IDL 代码生成 | `bash backend/script/cloudwego/code_gen.sh` | |
| 145 | +| GORM 代码生成 | `cd backend && go run script/gorm_gen/generate.go` | |
| 146 | +| 错误码生成 | `backend/script/errorx/code_gen.py <biz>` | |
| 147 | + |
| 148 | +### 前端（Rush.js + pnpm） |
| 149 | + |
| 150 | +| 操作 | 命令 | |
| 151 | +|------|------| |
| 152 | +| 安装依赖 | `node common/scripts/install-run-rush.js install` | |
| 153 | +| 全量构建 | `node common/scripts/install-run-rush.js rebuild --verbose` | |
| 154 | +| 开发服务器 | `cd frontend/apps/cozeloop && npm run dev` | |
| 155 | +| Lint | `cd frontend/apps/cozeloop && npm run lint` | |
| 156 | +| 测试 | `cd frontend/apps/cozeloop && npm run test` | |
| 157 | +| TypeScript 检查 | `cd frontend/apps/cozeloop && npm run build:ts` | |
| 158 | + |
| 159 | +### 部署 |
| 160 | + |
| 161 | +| 操作 | 命令 | |
| 162 | +|------|------| |
| 163 | +| 本地 dev 部署 | `make compose-up-dev` | |
| 164 | +| 本地 debug 部署（含 Delve） | `make compose-up-debug` | |
| 165 | +| 停止 dev | `make compose-down-dev` | |
| 166 | +| 停止并清理 volumes | `make compose-down-v-dev` | |
| 167 | +| Helm 部署 | `make helm-up` | |
| 168 | +| 查看 Pod 状态 | `make helm-pod` | |
| 169 | + |
| 170 | +### PR 标题格式 |
| 171 | + |
| 172 | +PR 标题必须符合 `[<type>][<scope>] <description>` 格式，CI 会校验。 |
| 173 | + |
| 174 | +- type: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `build`, `ci` |
| 175 | +- scope: `all`, `idl`, `frontend`, `backend`, `infra`, `workflow`, `prompt`, `evaluation`, `trace`, `model`, `tag`, `dataset`, `foundation` |
| 176 | + |
| 177 | +示例：`[feat][evaluation] add offline metric support` |
0 commit comments