From 3648b7a7331110e80d89082d7f64b1a86802346b Mon Sep 17 00:00:00 2001 From: qyyfw Date: Sat, 27 Jun 2026 11:49:40 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20MiMo=20Code=20?= =?UTF-8?q?=E6=8A=95=E5=96=82=E5=AE=9E=E6=93=8D=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/06-MiMoCode实操指南.md | 295 ++++++++++++++++++++++++++++++++++++ 1 file changed, 295 insertions(+) create mode 100644 docs/06-MiMoCode实操指南.md diff --git a/docs/06-MiMoCode实操指南.md b/docs/06-MiMoCode实操指南.md new file mode 100644 index 0000000..9dfd33b --- /dev/null +++ b/docs/06-MiMoCode实操指南.md @@ -0,0 +1,295 @@ +# MiMo Code 投喂实操指南 + +> 本指南告诉 MiMo Code **怎么用、先喂什么、每次喂多少**。 +> 核心原则：**每次只给它当前任务需要的上下文，不要一次全塞。** + +--- + +## 1. 项目目录结构（先搭好骨架） + +``` +ai-paas-platform/ +├── .mimocode/ +│ └── AGENTS.md ← 【头】永远加载，每次对话自动读 +├── docs/ ← 【尾】按需读取，不自动加载 +│ ├── 01-PRD-产品需求文档.md +│ ├── 02-系统架构设计.md +│ ├── 03-数据库设计.md +│ ├── 04-API接口规范.md +│ └── 05-AGENTS-MiMoCode配置.md +├── services/ ← 代码目录（逐步填充） +├── packages/ ← 前端代码 +├── deploy/ +│ └── docker-compose.yml +└── README.md +``` + +## 2. 投喂顺序：三步走 + +### 第一步：搭骨架（头文件） + +``` +在你的开发机上执行: + +mkdir -p ai-paas-platform/.mimocode +mkdir -p ai-paas-platform/docs +mkdir -p ai-paas-platform/services +mkdir -p ai-paas-platform/packages/web +mkdir -p ai-paas-platform/deploy + +# 把 docs/ 复制过去 +cp docs/*.md ai-paas-platform/docs/ + +# 把 AGENTS.md 放到 .mimocode/ 下 +cp docs/05-AGENTS-MiMoCode配置.md ai-paas-platform/.mimocode/AGENTS.md + +# 用 VS Code 打开 +code ai-paas-platform +``` + +### 第二步：启动 MiMo Code，开始对话 + +打开 VS Code 后，MiMo Code 会**自动读取 `.mimocode/AGENTS.md`**。 + +然后你**每次给一个具体任务**，像跟人说话一样： + +--- + +## 3. 每次对话怎么喂（实战示例） + +### 🔹 对话 1：初始化项目结构 + +``` +你: 根据 .mimocode/AGENTS.md 和 docs/02-系统架构设计.md， + 创建整个项目的目录结构，包括: + 1. services/ 下的 6 个 FastAPI 服务骨架（每个有 main.py + config.py + requirements.txt） + 2. deploy/docker-compose.yml（含 PostgreSQL + Redis + Kafka + Casdoor + NEW API + APISIX） + 3. pyproject.toml（顶层依赖管理） + 4. README.md + + 先创建骨架，不要写业务逻辑。 +``` + +> MiMo Code 会读 AGENTS.md（自动）+ 指定的 docs/02（按需读） + +### 🔹 对话 2：写计费引擎 + +``` +你: 参考 .mimocode/AGENTS.md、docs/03-数据库设计.md、docs/04-API接口规范.md， + 实现 ai-paas-billing 服务。 + + 请先读 docs/03-数据库设计.md 中的 credit_transactions 表定义， + 然后实现: + 1. Redis Lua 原子扣费脚本（先扣后服+幂等） + 2. POST /api/v1/billing/subscribe（订阅管理） + 3. GET /api/v1/billing/transactions（流水查询） + 4. POST /api/v1/billing/topup（充值） + + 使用 FastAPI + Redis + PostgreSQL，遵循 ruff + black 格式。 +``` + +> MiMo Code 读 AGENTS.md（自动）+ docs/03 + docs/04（按需） + +### 🔹 对话 3：写前端登录页 + +``` +你: 参考 docs/04-API接口规范.md 中的认证接口定义， + 实现 Web 前端的登录/注册页面。 + + 使用 React + TypeScript + Ant Design Pro。 + 页面: + 1. 登录页（手机号+验证码 / 邮箱+密码） + 2. 注册页（手机号+验证码） + 3. 实名认证页（姓名+身份证号） + 4. 个人中心页（显示订阅状态、余额） + + API 对接: BASE_URL = http://localhost:8080 +``` + +### 🔹 对话 4：写 LLM 调用网关 + +``` +你: 实现 ai-paas-gateway 的核心 LLM 调用链路。 + + 参考: + - .mimocode/AGENTS.md（整体架构） + - docs/04-API接口规范.md 第5节 LLM 调用接口 + + 调用链: + 1. 接收请求 → JWT/API Key 验证（查 Casdoor） + 2. 检查用户状态（订阅/欠费） + 3. Redis Lua 扣费 + 4. 转发到 NEW API（http://new-api:3000/v1/chat/completions） + 5. 流式 SSE 透传回客户端 + 6. 异步上报用量到 Kafka + + 特别注意: 流式响应不能缓冲，要实时透传。 +``` + +--- + +## 4. 关键原则 + +### 原则 1：头永远读，尾按需喂 + +``` +┌─────────────────────────────────────────┐ +│ .mimocode/AGENTS.md │ ← 【头】每次自动加载 +│ 包含: 项目概述、技术栈、开发规范、 │ MiMo Code 自动读 +│ 核心模块说明、计费原则 │ +│ 大小: 控制在 300-500 行以内 │ 不要太大，否则噪音多 +├─────────────────────────────────────────┤ +│ docs/01-PRD-产品需求文档.md │ ← 【尾】按需读取 +│ docs/02-系统架构设计.md │ 你告诉 MiMo Code +│ docs/03-数据库设计.md │ "请读 docs/03" +│ docs/04-API接口规范.md │ 它才会去读 +│ docs/05-AGENTS-MiMoCode配置.md │ +└─────────────────────────────────────────┘ +``` + +### 原则 2：每次只给一个任务 + +``` +❌ 错误: "把所有服务都写完" +✅ 正确: "先写 billing 服务的 Redis Lua 扣费脚本" +``` + +### 原则 3：明确告诉它读哪个文件 + +``` +❌ 错误: "参考设计文档写代码"（它不知道读哪个） +✅ 正确: "参考 docs/03-数据库设计.md 中的 credit_transactions 表定义" +``` + +### 原则 4：先骨架，后逻辑 + +``` +第一轮: 创建项目结构 + 所有 main.py 骨架（空路由） +第二轮: 逐个服务填充业务逻辑 +第三轮: 服务间联调 +第四轮: 前端对接 +``` + +### 原则 5：遇到问题直接问 MiMo Code + +``` +你: 我们要对接阿里云实名认证 API，帮我调研一下接入方式， + 然后写一个 FastAPI 的 /api/v1/auth/verify 接口。 + +MiMo Code 会自动搜索、调研、然后写出代码。 +``` + +--- + +## 5. 完整开发顺序 + +### Phase 1（第 1-3 周）: 基座搭建 + +| 对话# | 任务 | 喂什么文件 | 预计输出 | +|-------|------|-----------|---------| +| 1 | 项目骨架 | AGENTS.md + docs/02 | 目录结构 + docker-compose | +| 2 | 数据库初始化 | AGENTS.md + docs/03 | migrations/ + init.sql | +| 3 | Casdoor 配置 | AGENTS.md + docs/02 | casdoor/ 配置文件 | +| 4 | NEW API 配置 | AGENTS.md + docs/02 | new-api/ 配置文件 | +| 5 | gateway 骨架 | AGENTS.md + docs/04 | main.py + 路由 + 中间件 | +| 6 | JWT 验证 | AGENTS.md + docs/04 | auth middleware | +| 7 | LLM 调用链路 | AGENTS.md + docs/04 | gateway → NEW API 透传 | +| 8 | 里程碑验证 | — | 注册→登录→调LLM | + +### Phase 2（第 4-6 周）: 计费引擎 + +| 对话# | 任务 | 喂什么文件 | +|-------|------|-----------| +| 9 | Redis Lua 扣费 | AGENTS.md + docs/03 | +| 10 | 订阅管理 | AGENTS.md + docs/03 + docs/04 | +| 11 | 充值/Token包 | AGENTS.md + docs/04 | +| 12 | 用量追踪 | AGENTS.md + docs/03 | +| 13 | Kafka 消费者 | AGENTS.md + docs/02 | + +### Phase 3（第 7-9 周）: 能力市场 + +| 对话# | 任务 | 喂什么文件 | +|-------|------|-----------| +| 14 | 能力 CRUD | AGENTS.md + docs/03 + docs/04 | +| 15 | Skills 市场 | AGENTS.md + docs/03 + docs/04 | +| 16 | 实名认证对接 | AGENTS.md + docs/04 | +| 17 | 能力审核流程 | AGENTS.md + docs/04 | +| 18 | 开发者提现 | AGENTS.md + docs/03 + docs/04 | + +--- + +## 6. 常见坑与避坑 + +### 坑 1：MiMo Code 生成的代码风格不统一 +**解法**: 在 AGENTS.md 中明确写开发规范（已有），每次对话开头强调： +``` +"遵循 docs/05-AGENTS-MiMoCode配置.md 中的开发规范" +``` + +### 坑 2：它不知道你的数据库表结构 +**解法**: 每次涉及数据库的对话，明确告诉它： +``` +"请先读 docs/03-数据库设计.md 中的 [表名] 表定义" +``` + +### 坑 3：它生成的 API 不符合你的规范 +**解法**: 每次涉及 API 的对话，明确告诉它： +``` +"请先读 docs/04-API接口规范.md 中的 [接口名] 定义，严格按照这个格式实现" +``` + +### 坑 4：上下文太长，它开始犯糊涂 +**解法**: 一个对话只做一件事。做完就开新对话。不要在一个对话里堆太多任务。 + +### 坑 5：它不知道开源组件怎么配置 +**解法**: 直接告诉它： +``` +"NEW API 的 Docker 镜像是 justsong/one-api:latest，端口 3000， + 配置文件在 infra/new-api/config.yaml。帮我写配置。" +``` + +--- + +## 7. AGENTS.md 投喂策略 + +AGENTS.md 是 MiMo Code 的"大脑"，但**不是越大越好**。 + +### 推荐结构（300-500 行） + +```markdown +# 项目概述（50行） +- 一句话描述 +- 用户模型 +- 核心技术栈 + +# 项目结构（50行） +- 目录树 +- 每个目录的职责 + +# 开发规范（100行） +- Python 规范 +- TypeScript 规范 +- Git 规范 +- 测试规范 + +# 核心服务说明（200行） +- 每个服务的职责、端口、核心逻辑 + +# 计费原则（30行） +- 最重要的业务规则 + +# 重要约束（20行） +- 必须遵守的红线 +``` + +### 不要放进去的东西 +- ❌ 完整的数据库表定义（放 docs/03） +- ❌ 完整的 API 定义（放 docs/04） +- ❌ 完整的 PRD（放 docs/01） +- ❌ 部署步骤（放 README.md） + +**AGENTS.md 放"概述+规范"，docs/ 放"细节"。MiMo Code 自动读概述，你按需让它读细节。** + +--- + +*文档结束*