Day 01 / 共 20 天 · 第 1 周 环境与骨架
项目全景：它是什么
今天不写代码，只建地图。目标：搞清楚 Coze Loop 是个什么平台、和大家更熟悉的 Coze Studio 有什么区别、仓库里六大模块分别管什么、代码大概在哪。这张地图会贯穿后面 19 天。
📍 你在整门课的位置 · 第 1 周 环境与骨架（共 4 周 · 20 天）
D1 项目全景→
D2 Docker 跑起来→
D3 进程启动→
D4 HTTP 网关→
D5 Handler 桥接
L01
Coze Loop 到底是什么
🤔 痛点：写了个 Agent，上线之后怎么知道它有没有变笨？
你调好了一个 Prompt，上线跑了两周，忽然有人反馈"AI 回答得没有以前准了"。你怎么证明？怎么找到是哪次改动导致的？靠人肉翻聊天记录显然不现实——你需要一套"给 AI 应用做体检"的系统。这就是 Coze Loop 要解决的问题。
💡 本质：AI Agent 的开发运维平台（不是造 Agent 的平台）
README.cn.md 开篇原话："Coze Loop 是一个面向开发者，专注于 AI Agent 开发与运维的平台级解决方案，提供从开发、调试、评估、到监控的全生命周期管理能力"。注意关键词是"开发与运维"——它不负责画流程图拖节点搭 Agent，而是负责 Agent 做出来之后的"调优 + 质检 + 巡检"三件事。
🎯 一句话：Coze Loop 是给 AI Agent 用的"Prompt 调试台 + 自动化质检中心 + 全链路监控台"——三块拼在一起，帮你把"AI 是不是真的变好了"这件事，从凭感觉变成看数据。
README.cn.md 里给出了三大能力，对应三个模块：
| 能力 | 大白话 | 对应模块 |
|---|---|---|
| Prompt 开发 | 可视化 Playground 改 Prompt、对比不同模型效果、管版本 | prompt |
| 评测 | 用一批标准问答"考"你的 Prompt/Agent，自动打分（准确性/简洁性/合规性） | evaluation + data |
| 观测 | 把一次调用从用户输入到 AI 输出的全过程录下来，出问题能回放 | observability |
🍼 类比：体检中心
把 Coze Loop 想成"AI 应用的体检中心"：Prompt 模块是问诊台（医生和你面对面调参数）；评测模块是标准化体检套餐（同一套题给不同"病人"做，自动出报告）；观测模块是住院监控仪（实时录下每一次心跳）。三者共用同一套"病历系统"（
foundation 用户空间）和"检验科"（llm 模型调用）。开源版 vs 商业版：README 说"Coze Loop 在商业化版本的基础上，推出开源版免费对开发者开放核心基础功能模块"。也就是说你现在读的这个仓库，是商业版抽出来的核心引擎——功能完整但没有商业版的多租户计费等企业能力。这和 Coze Studio 开源版的定位是一个套路。
L02
和 Coze Studio 的区别（新手最容易搞混）
🤔 痛点：名字都带"Coze"，是不是同一个东西换了个皮？
很多人第一次看到
coze-loop 会以为它是 coze-studio 的另一个版本或者子模块。完全不是——它俩是"生产 Agent"和"体检 Agent"的关系，代码库、技术栈、职责都不同。💡 本质：Studio 造 Agent，Loop 管 Agent 的质量
Coze Studio 是可视化搭建平台：拖节点、连工作流、接知识库、发布成一个能对话的智能体——它关心的是"Agent 怎么造出来"。Coze Loop 关心的是"造出来的 Agent（或者其中一段 Prompt）到底靠不靠谱、有没有退化、出了问题能不能查到根因"——它不负责造，只负责调优、质检、巡检。
| 维度 | Coze Studio | Coze Loop |
|---|---|---|
| 核心问题 | 怎么造一个 Agent | Agent/Prompt 造出来后靠不靠谱 |
| 核心产物 | 可发布、可对话的智能体应用 | Prompt 版本、评测报告、Trace 记录 |
| 典型用户动作 | 拖节点、连插件、发布 Bot | 改 Prompt、跑评测集、查一条慢请求的调用链 |
| 后端分层关键词 | domain/crossdomain（Agent/Workflow/Knowledge/Plugin） | modules/<domain>/{application,domain,infra}（DDD 四层） |
| 关系 | 两者都用 Eino 调大模型；实际使用中常常是"Studio 造 Agent → Loop 给 Agent 的 Prompt 做评测和观测" | |
🍼 类比：装修公司 vs 质检公司
Coze Studio 像装修公司（帮你把房子设计施工出来），Coze Loop 像第三方质检公司（房子装完了，来检测甲醛超不超标、承重墙有没有问题、日后维修要看哪个房间的监控）。两者可以合作，但干的是完全不同的活。
⚠️ 小白常见误解：以为装了 Coze Studio 就自动有 Coze Loop 的评测/观测能力——其实这是两个独立仓库、独立部署的系统，商业版里打通了，开源版需要你自己各自部署，用 SDK（
cozeloop-go 等）把 Trace 上报过去对接。L03
六大业务模块总览
💡 本质：backend/modules/ 下正好 6 个目录，一一对应产品能力
这不是巧合——Coze Loop 后端是严格按业务域划分的 DDD 架构，backend/modules/ 下每个子目录就是一个"业务模块"，模块内部再分 application/domain/infra 三层（Day 06 细讲）。今天先记住六个名字和各自的角色。
prompt
Prompt 的编写、调试、版本管理（草稿/提交/回滚）、Playground 流式调试。今天到 Day 10 的主角。
evaluation
评测集、评估器（Evaluator）、实验（Experiment）——自动化地给 Prompt/Agent 输出打分。
data
数据集（Dataset）与标签（Tag）管理，是评测模块的"考卷仓库"。
observability
Trace 上报与查询、Span 检索、任务调度——全链路可观测性的落地。
foundation
用户、空间（Workspace）、鉴权（Auth）、文件服务——所有模块都要先过这里（Day 08 细讲）。
llm
模型接入与运行时：管理模型配置、通过 Eino 框架统一调用各家大模型（Day 10 细讲）。
模块之间怎么协作？ 后面 Day 04/05 会看到：真实请求要经过 Foundation 鉴权，Prompt 模块要调用 LLM 模块跑模型，Evaluation 模块要调用 Data + Prompt + LLM 三个模块——但它们从不直接 import 彼此的内部包，而是通过一层"本地 Kitex 客户端"互相调用（这是 Coze Loop 一个很特别的设计，Day 05/06 会揭秘）。
L04
仓库顶层目录地图
顶层跑一遍 ls，除了几个说明文档，真正的"地盘"是这 5 个目录：
coze-loop/
├── backend/ ★★ Go 后端服务，DDD 六模块（本教程主战场）
├── frontend/ ★ Rush.js 管理的 TS/React 单体仓库，59 个包
├── idl/ ★ Thrift IDL：前后端共享的接口契约（Day 07 细讲）
├── release/ ★ Docker Compose / Helm Chart 部署配置（Day 02 细讲）
├── docs/ ★ guidance（部署/IDL 指南）+ reference（模块索引）
├── common/ Rush 管理的 git-hooks
└── README.cn.md / ARCHITECTURE.md / Makefile / rush.json ...读源建议：跟着这个顺序——先
backend/cmd（进程怎么起，Day 03）、再 backend/api（请求怎么进来，Day 04-05）、然后 backend/modules/prompt（业务怎么分层，Day 06/09），最后 idl/（契约从哪来，Day 07）。本教程 10 天基本就是这条主线。backend 内部顶层同样值得先扫一眼（ARCHITECTURE.md 有完整表格，Day 03-06 会逐个进去）：
| 目录 | 职责 | 架构不变量 |
|---|---|---|
cmd/ | 服务入口（main.go / consumer.go） | 只做启动编排，不含业务逻辑 |
api/ | HTTP 路由 + handler（Hertz 框架） | 只做参数校验和转发 |
modules/ | 6 个 DDD 业务模块 | 模块间不直接互调 |
infra/ | 共享基础设施（DB/Redis/CK/MQ/中间件） | 被 modules 引用，不引用 modules |
kitex_gen/ / loop_gen/ | Thrift 生成代码 | 禁止手动修改 |
L05
后端 DDD 分层速览（今天先看个轮廓）
ARCHITECTURE.md 明确画出了一次请求从上到下要经过的四层。今天只建立直觉，Day 06 会拿真实代码逐层拆开。
api/ · 门卫
Handler参数校验
RouterIDL 生成
MiddlewareSession/Locale
application/ · 经理
用例编排
Wire DI装配依赖
domain/ · 专家
entity领域模型
service业务规则
repo仓储接口
infra/ · 水电工
repo 实现MySQL/Redis
rpc调其他模块
依赖方向铁律：
api → application → domain ← infra。domain 层只定义接口（"我需要一个能存 Prompt 的仓库"），infra 层负责实现（"用 MySQL 存"）。domain 绝不反向引用 infra——这样领域规则可以脱离数据库单独测试。L06
先混个脸熟：术语表
后面会反复出现这些词，今天先认识，不用记细节：
| 名词 | 大白话解释 | 哪天细讲 |
|---|---|---|
| Hertz | 字节 CloudWeGo 团队的 Go HTTP 框架，Coze Loop 用它接收请求 | Day 04 |
| Kitex | CloudWeGo 的 RPC 框架，这里被用来做"进程内本地调用"而不是跨机 RPC | Day 05 |
| Thrift IDL | 接口描述语言，一份 .thrift 文件生成前后端都能用的类型和接口 | Day 07 |
| Wire | Google 的依赖注入代码生成工具，帮你手写"把哪些零件组装成哪个大对象" | Day 06 |
| Eino | CloudWeGo 的 Go LLM 应用框架，Coze Loop 通过它统一调用各家大模型 | Day 10 |
| Span / Trace | 一次调用链路里的"一段"和"整条"，观测模块的核心数据单位 | 后续周 |
| Workspace 空间 | 团队隔离单位，几乎所有资源（Prompt/数据集）都挂在某个空间下 | Day 08 |
L07
今日小结 + 动手
🧠 今天你应该能回答
- Coze Loop 是什么？（AI Agent 开发运维平台：Prompt 调试 + 评测 + 观测，不负责搭 Agent）
- 它和 Coze Studio 的关系？（Studio 造 Agent，Loop 给 Prompt/Agent 做质检和监控，两个独立系统）
- 六大模块分别是什么？（prompt / evaluation / data / observability / foundation / llm）
- DDD 四层依赖方向？（api → application → domain ← infra，domain 不依赖 infra）
🎵 记忆口诀
「调 Prompt、跑评测、看链路，三件套都靠 Foundation 撑腰、LLM 兜底」——今天记住这句，后面 9 天都是在往这个骨架上填肉。
✋ 动手 5 分钟
# 1. 看项目定位
head -30 README.cn.md
# 2. 感受六大模块
ls backend/modules/
# 输出应为: data evaluation foundation llm observability prompt
# 3. 看顶层目录地图
ls backend/ frontend/ idl/ release/ docs/
# 4. 瞄一眼架构文档的分层说明（明天会用到）
head -70 ARCHITECTURE.md明天预告 · Day 02：把它跑起来！用
make compose-up 一键拉起 MySQL/Redis/ClickHouse/MinIO/RocketMQ 五件套 + 应用容器，浏览器打开 localhost:8082 看看真实界面长什么样，顺便把模型接进去。