9.0 KiB
9.0 KiB
MiMo Code 投喂实操指南
本指南告诉 MiMo Code 怎么用、先喂什么、每次喂多少。 核心原则：每次只给它当前任务需要的上下文，不要一次全塞。
1. 项目目录结构（先搭好骨架）
QihuAI/
├── .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 QihuAI/.mimocode
mkdir -p QihuAI/docs
mkdir -p QihuAI/services
mkdir -p QihuAI/packages/web
mkdir -p QihuAI/deploy
# 把 docs/ 复制过去
cp docs/*.md QihuAI/docs/
# 把 AGENTS.md 放到 .mimocode/ 下
cp docs/05-AGENTS-MiMoCode配置.md QihuAI/.mimocode/AGENTS.md
# 用 VS Code 打开
code QihuAI
第二步：启动 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 行）
# 项目概述（50行）
- 一句话描述
- 用户模型
- 核心技术栈
# 项目结构（50行）
- 目录树
- 每个目录的职责
# 开发规范（100行）
- Python 规范
- TypeScript 规范
- Git 规范
- 测试规范
# 核心服务说明（200行）
- 每个服务的职责、端口、核心逻辑
# 计费原则（30行）
- 最重要的业务规则
# 重要约束（20行）
- 必须遵守的红线
不要放进去的东西
- ❌ 完整的数据库表定义（放 docs/03）
- ❌ 完整的 API 定义（放 docs/04）
- ❌ 完整的 PRD（放 docs/01）
- ❌ 部署步骤（放 README.md）
AGENTS.md 放"概述+规范"，docs/ 放"细节"。MiMo Code 自动读概述，你按需让它读细节。
文档结束