docs: 新增 MiMo Code 投喂实操指南

2026-06-27 11:49:40 +00:00
1 parent 8209f15d0a
commit 3648b7a733
@@ -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 自动读概述，你按需让它读细节。**
 ---
 *文档结束*