ai-paas-comparison/docs/06-MiMoCode实操指南.md

# 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 行）

```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 自动读概述，你按需让它读细节。**

---

*文档结束*