argon-theme/.kiro/steering/xiaomi-mimo-api-fix.md

# 小米 Mimo API 修复说明

## 修复时间
2026-01-26

## 问题描述
小米 Mimo 模型 API 请求失败，无法正常调用 MiMo-V2-Flash 模型。

## 修复内容

### 1. 优化 `argon_call_xiaomi_api` 函数

**修改位置**: `functions.php` 第 8047-8140 行

**主要改进**:
- ✅ 添加 `stream` 参数，明确设置为 `false`（非流式响应）
- ✅ 添加 `Accept` 请求头，明确接受 JSON 格式
- ✅ 使用 `JSON_UNESCAPED_UNICODE` 标志编码请求体，确保中文字符正确传输
- ✅ 明确设置 `sslverify` 为 `true`，确保 SSL 验证

**修改前**:
```php
$data = [
	'model' => $model,
	'messages' => [
		['role' => 'system', 'content' => $prompt],
		['role' => 'user', 'content' => $content]
	],
	'temperature' => 0.7,
	'max_tokens' => 500
];

$response = wp_remote_post($endpoint, [
	'headers' => [
		'Content-Type' => 'application/json',
		'Authorization' => 'Bearer ' . $api_key
	],
	'body' => json_encode($data),
	'timeout' => 30
]);
```

**修改后**:
```php
$data = [
	'model' => $model,
	'messages' => [
		['role' => 'system', 'content' => $prompt],
		['role' => 'user', 'content' => $content]
	],
	'temperature' => 0.7,
	'max_tokens' => 500,
	'stream' => false
];

$response = wp_remote_post($endpoint, [
	'headers' => [
		'Content-Type' => 'application/json',
		'Authorization' => 'Bearer ' . $api_key,
		'Accept' => 'application/json'
	],
	'body' => json_encode($data, JSON_UNESCAPED_UNICODE),
	'timeout' => 30,
	'sslverify' => true
]);
```

### 2. 增强 `argon_get_xiaomi_models` 函数

**修改位置**: `functions.php` 第 9009-9055 行

**主要改进**:
- ✅ 添加 `Accept` 请求头
- ✅ 明确设置 `sslverify` 为 `true`
- ✅ 添加详细的错误日志记录
- ✅ 记录 HTTP 状态码和响应内容，便于调试
- ✅ 改进错误处理逻辑

**新增错误日志**:
- API 调用失败时记录错误信息
- HTTP 状态码非 200 时记录状态码和响应内容
- 响应格式异常时记录原始响应

## 可能的问题原因

根据修复内容，原始代码可能存在以下问题：

1. **缺少 stream 参数**: 某些 API 实现要求明确指定是否使用流式响应
2. **缺少 Accept 头**: API 可能需要明确的 Accept 头来返回正确格式
3. **中文编码问题**: 未使用 `JSON_UNESCAPED_UNICODE` 可能导致中文字符编码错误
4. **缺少错误日志**: 之前无法诊断具体的失败原因

## 测试方法

### 方法 1: 使用测试脚本

1. 打开 `test-xiaomi-mimo-api.php` 文件
2. 将 `YOUR_API_KEY_HERE` 替换为你的实际 API 密钥
3. 在浏览器中访问: `https://your-domain.com/wp-content/themes/argon/test-xiaomi-mimo-api.php`
4. 查看测试结果，包括：
   - 基本 API 请求测试
   - 简化请求格式测试
   - 获取模型列表测试
   - cURL 命令示例

### 方法 2: 在 WordPress 后台测试

1. 进入 WordPress 后台 → Argon 主题设置
2. 找到 "AI 功能" → "API 管理"
3. 添加或编辑小米 Mimo API 配置
4. 点击"测试"按钮
5. 查看测试结果

### 方法 3: 查看错误日志

如果仍然失败，检查 WordPress 错误日志：

```bash
# 查看 PHP 错误日志
tail -f /path/to/php-error.log

# 或者 WordPress debug.log
tail -f /path/to/wp-content/debug.log
```

错误日志会包含：
- API 调用失败的具体错误信息
- HTTP 状态码
- API 响应内容

## 小米 Mimo API 规范

### 端点
- **Chat Completions**: `https://api.mimo.xiaomi.com/v1/chat/completions`
- **Models**: `https://api.mimo.xiaomi.com/v1/models`

### 认证
使用 Bearer Token 认证：
```
Authorization: Bearer YOUR_API_KEY
```

### 请求格式
```json
{
  "model": "MiMo-V2-Flash",
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手。"},
    {"role": "user", "content": "你好"}
  ],
  "temperature": 0.7,
  "max_tokens": 500,
  "stream": false
}
```

### 响应格式
```json
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "MiMo-V2-Flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是小米的 AI 助手..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}
```

## 支持的模型

根据官方文档，小米 Mimo 目前支持的模型：

- **MiMo-V2-Flash** (推荐)
  - 309B 总参数，15B 活跃参数
  - 256K 上下文窗口
  - 擅长推理、编码和 Agent 场景
  - 在 SWE-bench 上排名第一

## 常见问题

### Q1: API 密钥在哪里获取？
A: 访问 [小米 Mimo 平台](https://platform.xiaomimimo.com/) 注册并获取 API 密钥。

### Q2: API 是否免费？
A: 根据官方信息，MiMo-V2-Flash 目前处于公测阶段，可能提供免费额度。具体请查看官方文档。

### Q3: 为什么返回 401 错误？
A: 检查以下几点：
- API 密钥是否正确
- API 密钥是否已激活
- 是否正确设置了 Authorization 头

### Q4: 为什么返回 429 错误？
A: 请求频率超过限制，需要：
- 降低请求频率
- 检查是否有配额限制
- 联系小米客服增加配额

### Q5: 为什么返回 500 错误？
A: 服务器端错误，可能原因：
- API 服务暂时不可用
- 请求参数格式错误
- 模型名称错误

## 参考资料

- [LiteLLM - Xiaomi MiMo](https://docs.litellm.ai/docs/providers/xiaomi_mimo)
- [Puter.js - Free Xiaomi MiMo API](https://developer.puter.com/tutorials/free-unlimited-xiaomi-mimo-api/)
- [OpenRouter - MiMo-V2-Flash](https://openrouter.ai/xiaomi/mimo-v2-flash-20251210/api)
- [Hugging Face - MiMo-V2-Flash](https://huggingface.co/XiaomiMiMo/MiMo-V2-Flash)

## 后续优化建议

1. **添加重试机制**: 对于临时性失败，自动重试 2-3 次
2. **缓存模型列表**: 减少对 models 端点的请求
3. **支持流式响应**: 对于长文本生成，支持流式输出
4. **添加速率限制**: 避免触发 API 限流
5. **监控 API 使用**: 记录 API 调用次数和成本

## 相关文件

- `functions.php` - 核心函数（包含 API 调用逻辑）
- `test-xiaomi-mimo-api.php` - 测试脚本
- `settings.php` - 设置页面（AI 功能配置）

## Git 提交

提交信息将包含：
```
fix: 修复小米 Mimo API 请求失败的问题

- 添加 stream 参数明确设置为非流式响应
- 添加 Accept 请求头确保返回 JSON 格式
- 使用 JSON_UNESCAPED_UNICODE 编码确保中文正确传输
- 添加详细的错误日志记录便于调试
- 改进 SSL 验证设置
```