Gemini Daily MCP Server (Compressed)

# Codex CLI → Gemini CLI 适配计划

**日期**: 2025-11-22
**目标**: 将 tuannvm/codex-mcp-server 适配为 Gemini CLI

---

## 关键差异对比

### 命令行参数

**Codex CLI**:
```bash
# 新对话
codex exec --model gpt-5-codex --skip-git-repo-check "prompt"

# 恢复对话
codex resume [conversation_id] --model gpt-5-codex --skip-git-repo-check "prompt"
```

**Gemini CLI**:
```bash
# 新对话
gemini -o stream-json -m gemini-2.0-flash-exp -p "prompt"

# 恢复对话
gemini -o stream-json -m gemini-2.0-flash-exp -c [conversation_id] -p "prompt"
```

**关键差异**:
1. Codex 使用子命令 (`exec`, `resume`)，Gemini 使用选项 (`-c`)
2. Codex 的 prompt 是位置参数，Gemini 的 prompt 用 `-p` 指定
3. Gemini 需要 `-o stream-json` 输出 JSON 格式
4. Codex 有 `--skip-git-repo-check`，Gemini 无此选项

---

### JSON 输出格式

**Codex CLI 输出** (stderr 包含元数据):
```
stderr: "conversation id: abc-123-def"
stdout: "Text response from Codex"
```

**Gemini CLI 输出** (stream-json 模式):
```json
{"event": "init", "conversation_id": "abc-123-def"}
{"event": "message", "role": "assistant", "content": "Partial response"}
{"event": "message", "role": "assistant", "content": " more text"}
{"event": "result", "text": "Complete response text"}
```

**适配策略**:
- 监听 `event: "init"` 提取 `conversation_id`
- 拼接所有 `event: "message"` 的 `content`
- 或直接使用 `event: "result"` 的 `text`

---

### 模型名称

**Codex 模型**:
- `gpt-5-codex` (默认)
- `gpt-4-codex`

**Gemini 模型**:
- `gemini-2.0-flash-exp` (推荐默认)
- `gemini-1.5-pro`
- `gemini-1.5-flash`

---

### Session ID 概念

**Codex**:
- 使用 `thread_id` 或 `conversation_id`
- 通过 `codex resume [id]` 恢复

**Gemini**:
- 使用 `conversation_id`
- 通过 `-c [id]` 恢复

**一致性**: 两者概念相同，都是用于恢复对话上下文

---

## 代码适配清单

### 1. types.ts

- [ ] `TOOLS.CODEX` → `TOOLS.GEMINI`
- [ ] 移除 `reasoningEffort` 参数（Gemini 不支持）
- [ ] 更新 tool 描述

### 2. handlers.ts

- [ ] `CodexToolHandler` → `GeminiToolHandler`
- [ ] 命令构建逻辑：
  - [ ] 移除 `exec`/`resume` 子命令
  - [ ] 添加 `-o stream-json`
  - [ ] 使用 `-c` 代替 `resume`
  - [ ] 使用 `-p` 传递 prompt
  - [ ] 移除 `--skip-git-repo-check`
- [ ] JSON 解析逻辑：
  - [ ] 解析 `event: "init"` 提取 `conversation_id`
  - [ ] 拼接 `event: "message"` 的 `content`
  - [ ] 使用 `event: "result"` 的 `text`
- [ ] 会话管理：
  - [ ] `codexConversationId` → `geminiConversationId`
  - [ ] `setCodexConversationId` → `setGeminiConversationId`

### 3. session/storage.ts

- [ ] `codexConversationId` → `geminiConversationId`
- [ ] 更新方法名称

### 4. server.ts

- [ ] 更新工具定义描述
- [ ] 更新服务器名称

### 5. 测试文件

- [ ] 更新所有测试用例
- [ ] 适配 mock 数据

### 6. 文档

- [ ] README.md
- [ ] docs/ 目录下的所有文档

---

## 实施步骤

### Phase 1: 核心适配 (2-3h)

1. **types.ts** - 更新工具名称和参数
2. **handlers.ts** - 适配命令构建和 JSON 解析
3. **session/storage.ts** - 更新会话管理

### Phase 2: 集成测试 (1-2h)

4. **测试** - 验证命令执行和 JSON 解析
5. **调试** - 修复边界情况

### Phase 3: 文档更新 (1h)

6. **README.md** - 更新安装和使用指南
7. **docs/** - 更新技术文档

---

## 风险点

1. **Gemini CLI 版本差异**: 不同版本的 Gemini CLI 可能有不同的 JSON 格式
2. **流式输出处理**: Gemini 的 stream-json 可能需要逐行解析
3. **错误处理**: Gemini 的错误消息格式可能不同

---

## 验证标准

- [ ] 单轮对话成功
- [ ] 多轮对话保持上下文（使用 conversation_id）
- [ ] Session 管理正常（创建、恢复、列表）
- [ ] 错误处理正确
- [ ] 所有 54 个测试用例通过（适配后）

---

**下一步**: 开始 Phase 1 - 核心适配