# WorkBuddy 模型接入配置指南

> **目标**：在新电脑上为一台全新的 WorkBuddy 配置模型，使其具备日常智能协作能力。
>
> **工作方式**：将本文件交给目标设备的 WorkBuddy AI，它会引导你逐步完成网络接入与模型配置。
>
> **前置要求**：你需要有一个西瓜 AI Hub 平台账号。

---

## 第一步：AI 智能检测 — 自动获取 API Key

AI 拿到本文件后，会**自动执行以下检测流程**，而不是直接向你索要 Key。

### 1.1 检测本地是否已有西瓜模型的配置

AI 会先读取 `~/.workbuddy/models.json`，检查以下情况：

| 场景 | 本地情况 | AI 行为 |
|------|---------|---------|
| **场景 A** | 已经配了 1 个或多个模型，且其中**任一模型的 API 地址**包含 `aiproxy.xiguacity.cn` | ✅ **直接复用已有 Key**，不再问你。直接跳到「第二步」开始配置剩余模型。 |
| **场景 B** | 已经配了模型，但**所有模型的 API 地址都不是**西瓜的地址（如 `api.deepseek.com`、`api.openai.com` 等） | ❌ 需要你提供 Key。AI 会引导你去 AI Hub 获取（见 1.3）。 |
| **场景 C** | models.json 为空或不存在（全新安装） | ❌ 需要你提供 Key。AI 会引导你去 AI Hub 获取（见 1.3）。 |

> **核心原则**：只要本地已有任何一个模型的 API 地址是西瓜的（`aiproxy.xiguacity.cn`），Key 一定是一样的，直接复用，**绝不再问你要**。

### 1.2 场景 A 示例（无需操作）

比如本地已经配了 4 个模型中的 1 个：

```json
{
  "id": "deepseek-v4-flash",
  "url": "https://aiproxy.xiguacity.cn/api/llm/v1/chat/completions",
  "apiKey": "95a2a8e0fc03456d91d188f6e5323ef8"
}
```

AI 会直接提取 `apiKey`（这 4 个模型的 API 地址和 Key 都一样），然后帮你补充配置剩余的 3 个模型。你什么都不用做。

### 1.3 场景 B / C：获取 API Key（仅当需要时才做）

如果 AI 判断需要你提供 Key，按以下步骤操作：

#### 连接网络

AI 会自动检测当前操作系统（macOS / Windows），按对应方式处理：

**在公司办公**：连接 `xigua-sec` 公司 WiFi。

**不在公司（远程办公）**：使用 OpenVPN 连接公司内网。

| 操作系统 | OpenVPN 操作方式 |
|---------|-----------------|
| **macOS** | 使用 Tunnelblick 或 OpenVPN Connect 客户端，导入 `.ovpn` 配置文件后连接 |
| **Windows** | 使用 OpenVPN GUI 客户端，右键系统托盘图标 → 导入配置文件 → 连接 |

> 如果当前设备尚未安装 OpenVPN 或没有配置文件，请联系 IT 部门获取。

连接成功后，确保可以正常访问 `https://aihub.xiguacity.cn`。如果网络不通，先排查 VPN 连接状态。

#### 访问 AI Hub 并获取 API Key

打开浏览器访问：

```
https://aihub.xiguacity.cn/
```

按以下步骤操作：

```
① 登录你的西瓜 AI Hub 账号
② 进入「我的API」
③ 创建新的 API-KEY（或选择已有的）
④ 点击「权限」→「策略模型」
⑤ 在策略模型中申请以下 4 个模型的权限：
   - deepseek-v4-flash
   - deepseek-v4-pro
   - gemini-3.1-pro-preview
   - gemini-3-flash-preview
⑥ 回到「我的API」，复制 API-KEY
```

将复制好的 API-KEY 发送给 AI，后续步骤由 AI 自动完成。

---

## 第二步：AI 自动配置模型

AI 使用已获取的 API-KEY（来自自动检测或你手动提供），结合预定义的 API 地址创建 4 个自定义模型。

### 2.1 模型清单

| 模型 ID | 显示名称 | 角色 | 上下文窗口 | API 地址 |
|---------|---------|------|:---------:|---------|
| `deepseek-v4-flash` | Deepseek v4 Flash | 日常主力（轻量/默认） | 1M | `https://aiproxy.xiguacity.cn/api/llm/v1/chat/completions` |
| `deepseek-v4-pro` | Deepseek v4 Pro | 深度思考路由目标 | 1M | `https://aiproxy.xiguacity.cn/api/llm/v1/chat/completions` |
| `gemini-3.1-pro-preview` | Gemini 3.1 Pro | pro 的深度思考路由目标 | 2M | `https://aiproxy.xiguacity.cn/api/llm/v1/chat/completions` |
| `gemini-3-flash-preview` | Gemini 3 Flash | 子代理模型 | 1M | `https://aiproxy.xiguacity.cn/api/llm/v1/chat/completions` |

> **注意**：`name`（显示名称）可以与 `id`（模型 ID）不同，WorkBuddy 界面中显示的是 `name`，路由逻辑使用 `id`。

### 2.1.1 Token 配置

| 模型 ID | maxInputTokens | 计算依据 | maxOutputTokens | 计算依据 |
|---------|:-------------:|---------|:--------------:|---------|
| `deepseek-v4-flash` | 600,000 | 1M × 60%（45% 基准 + 15% 缓冲） | 64,000 | 固定 64K |
| `deepseek-v4-pro` | 600,000 | 同上 | 64,000 | 固定 64K |
| `gemini-3.1-pro-preview` | 1,258,000 | 2M × 60%（45% 基准 + 15% 缓冲） | 32,768 | 默认 |
| `gemini-3-flash-preview` | 629,000 | 1M × 60%（45% 基准 + 15% 缓冲） | 8,192 | 默认 |

> **配置策略**：maxInputTokens 取模型上下文窗口的 60%（45% 基准用量 + 15% 安全缓冲），避免中途截断。maxOutputTokens 中 Gemini 使用模型默认上限，DeepSeek 统一设为 64K。

### 2.2 各模型 features

| 模型 ID | supportsImages | supportsToolCall | supportsReasoning |
|---------|:--------------:|:----------------:|:-----------------:|
| deepseek-v4-flash | false | true | true |
| deepseek-v4-pro | false | true | true |
| gemini-3.1-pro-preview | true | true | true |
| gemini-3-flash-preview | true | true | true |

### 2.3 配置 deepseek-v4-flash 的 relatedModels

```json
{
  "id": "deepseek-v4-flash",
  "name": "Deepseek v4 Flash",
  "vendor": "xigua AI HUB",
  "url": "https://aiproxy.xiguacity.cn/api/llm/v1/chat/completions",
  "apiKey": "<已获取的 apiKey>",
  "maxInputTokens": 600000,
  "maxOutputTokens": 64000,
  "supportsToolCall": true,
  "supportsImages": false,
  "supportsReasoning": true,
  "useCustomProtocol": false,
  "relatedModels": {
    "lite": "deepseek-v4-flash",
    "reasoning": "deepseek-v4-pro"
  }
}
```

### 2.4 配置 deepseek-v4-pro 的 relatedModels

```json
{
  "id": "deepseek-v4-pro",
  "name": "Deepseek v4 Pro",
  "vendor": "xigua AI HUB",
  "url": "https://aiproxy.xiguacity.cn/api/llm/v1/chat/completions",
  "apiKey": "<已获取的 apiKey>",
  "maxInputTokens": 600000,
  "maxOutputTokens": 64000,
  "supportsToolCall": true,
  "supportsImages": false,
  "supportsReasoning": true,
  "useCustomProtocol": false,
  "relatedModels": {
    "lite": "deepseek-v4-flash",
    "reasoning": "gemini-3.1-pro-preview"
  }
}
```

### 2.5 创建 gemini-3.1-pro-preview（无路由）

```json
{
  "id": "gemini-3.1-pro-preview",
  "name": "Gemini 3.1 Pro",
  "vendor": "xigua AI HUB",
  "url": "https://aiproxy.xiguacity.cn/api/llm/v1/chat/completions",
  "apiKey": "<已获取的 apiKey>",
  "maxInputTokens": 1258000,
  "maxOutputTokens": 32768,
  "supportsToolCall": true,
  "supportsImages": true,
  "supportsReasoning": true,
  "useCustomProtocol": false
}
```

### 2.6 创建 gemini-3-flash-preview（无路由）

```json
{
  "id": "gemini-3-flash-preview",
  "name": "Gemini 3 Flash",
  "vendor": "xigua AI HUB",
  "url": "https://aiproxy.xiguacity.cn/api/llm/v1/chat/completions",
  "apiKey": "<已获取的 apiKey>",
  "maxInputTokens": 629000,
  "maxOutputTokens": 8192,
  "supportsToolCall": true,
  "supportsImages": true,
  "supportsReasoning": true,
  "useCustomProtocol": false
}
```

---

## 第三步：设置子代理环境变量

AI 会自动检测操作系统，编辑对应的 shell 配置文件，追加环境变量：

- macOS → `~/.zshrc`
- Linux → `~/.bashrc` 或 `~/.bash_profile`
- Windows → 系统环境变量

追加内容：

```bash
# WorkBuddy 子代理模型配置
export CODEBUDDY_CODE_SUBAGENT_MODEL=gemini-3-flash-preview
```

写入后提示用户执行：

```bash
source ~/.zshrc
```

（或其他对应的 profile 文件）

---

## 第四步：配置完成 — 你该怎么理解这 4 个模型？

> ⚠️ **关于 Craft/Ask/Plan 模式与模型路由的澄清**
>
> `relatedModels` 配置控制的是 **Agent 工具的 `model` 参数路由**（如子代理调度时指定 `model: "lite"` 或 `model: "reasoning"`），**而不是主对话窗口的 Craft/Ask/Plan 模式切换**。
>
> 实测验证：选定 Deepseek v4 Pro 后切换到 Ask 模式，底层仍调用 v4 Pro，**不会自动切到 Flash**。主对话始终使用你手动选择的模型，模式仅控制执行权限（是否改文件、是否先出计划），不影响模型选择。

### 模型分工（说人话版）

| 角色 | 模型 | 由谁触发 | 简单理解 |
|------|------|---------|---------|
| **主对话模型** | 你手动选择的模型 | 你直接选 | 当前对话用的就是它，不管 Craft/Ask/Plan |
| **子代理轻量任务**（lite） | Deepseek v4 Flash | 子代理或 Agent 工具指定 `model: "lite"` | 后台提取、摘要等低价值任务，省成本 |
| **子代理推理任务**（reasoning） | v4 Pro / Gemini 3.1 Pro | 子代理或 Agent 工具指定 `model: "reasoning"` | 需要深度思考的子任务 |
| **子代理默认模型** | Gemini 3 Flash | 环境变量 `CODEBUDDY_CODE_SUBAGENT_MODEL` | AI 内部派活给"小助手"时用的 |

### 模式说明（正确的理解）

| 模式 | 做什么的 | 影响模型吗？ |
|------|---------|:----------:|
| **Craft（干活）** | 让 AI 动手改文件、写代码、做东西 | ❌ 不切换模型 |
| **Plan（规划）** | 让 AI 先出计划，确认后再执行 | ❌ 不切换模型 |
| **Ask（问答）** | 只聊天不动手，快速问问题 | ❌ 不切换模型 |

> 三种模式只控制**执行权限**，不控制**模型选择**。无论你选哪种模式，底层始终用你手动选择的主模型。

### 重要提示

- ✅ **主对话的模型由你手动决定**：切换到 Ask 模式不会自动切到 Flash，切换到 Plan 模式也不会自动切到 Pro。
- ✅ **relatedModels 影响子代理和 Agent 工具**：当子代理或 Agent 工具指定 `model: "lite"`/`model: "reasoning"` 时，系统根据主模型的 `relatedModels` 路由到对应模型。这不是你手动操作的。
- ✅ **以配置为准**：界面上可能不显示具体模型名称，这不代表没配好。只要 `models.json` 里 4 个模型都在，就是配好了。

---

## 验证清单

执行完成后，AI 会自动确认以下项目：

- [ ] `~/.workbuddy/models.json` 中 4 个模型全部存在，配置完整（含 maxInputTokens / maxOutputTokens）
- [ ] deepseek-v4-flash 的 relatedModels 已添加（lite → 自身，reasoning → deepseek-v4-pro）
- [ ] deepseek-v4-pro 的 relatedModels 已添加（lite → deepseek-v4-flash，reasoning → gemini-3.1-pro-preview）
- [ ] 环境变量 `CODEBUDDY_CODE_SUBAGENT_MODEL=gemini-3-flash-preview` 已写入 shell profile
- [ ] JSON 格式校验通过（无语法错误）
- [ ] Gemini 3 Flash 名称已修正（非 "3.1 Flash"）

---

## 路由行为速查（技术参考）

> 以下路由适用于 **Agent 工具的 `model` 参数**（`lite` / `default` / `reasoning`），**不适用于主对话的 Craft/Ask/Plan 模式切换**。

| 手动选择的模型 | lite 场景 | default 场景 | reasoning 场景 | 子代理任务 |
|--------------|:---------:|:-----------:|:-------------:|:---------:|
| **deepseek-v4-flash** | flash（自身） | flash | → deepseek-v4-pro | gemini-3-flash（环境变量） |
| **deepseek-v4-pro** | → flash | pro（自身） | → gemini-3.1-pro-preview | gemini-3-flash（环境变量） |

### 路由优先级（lite / reasoning 场景）

1. **环境变量**（最高）：`CODEBUDDY_SMALL_FAST_MODEL` → lite，`CODEBUDDY_BIG_SLOW_MODEL` → reasoning
2. **`relatedModels[variant]`**：主模型中的 `lite` / `reasoning` 配置
3. **内置默认**：仅对 CodeBuddy 内置模型生效，自定义模型跳过此步
4. **回退**：以上都不匹配时使用主模型自身

---

## 附录：自定义模型（备选方案）

> 如果你需要使用自己的模型（而非西瓜 AI Hub 的默认模型），按以下流程操作：

### 方案 A：本地已有配置
如果目标模型 ID 在本地 `~/.workbuddy/models.json` 中**已经存在**，AI 会直接复用，无需额外操作。

### 方案 B：新增自定义模型
如果目标模型 ID **不存在**，你需要向 AI 提供以下 3 个信息：

```
① 模型 ID（如 my-custom-model）
② API 端点 URL（如 https://api.example.com/v1/chat/completions）
③ API Key
```

AI 会使用这 3 个信息自动创建完整配置（features 默认全为 true），并询问你是否要将此模型加入路由链路或仅做手动切换使用。

---

*文档版本：v2.3 | 2026-05-13（修正 Craft/Ask/Plan 模式与 relatedModels 路由的混淆描述，补充实测验证和正确的生效范围说明）*