第三章：模型配置详解

模型配置是整个 my-opencode-deepseek-config 方案的核心基础设施。它定义了「用什么模型、怎么用、谁来用」——这三个问题的答案直接决定了协作质量、响应速度和控制成本。本章从 DeepSeek V4 双模型体系出发，逐层拆解 Provider 配置、Thinking 模式、模型路由策略、参数调优和跨模型协作机制。

3.1 DeepSeek V4 双模型体系

这套方案只使用两个模型，通过角色分工实现精度与效率的平衡。

3.1.1 deepseek-v4-pro：重型推理引擎

deepseek-v4-pro 是 DeepSeek 的旗舰推理模型，具备强大的逻辑推理、深度分析和长文本理解能力。在本方案中，它承担所有需要「深思熟虑」的任务：

Pro 的关键特征是慢思考（slow thinking）：它在回答前会进行内部推理链，得出更准确、更完整的结论。代价是响应时间更长、Token 消耗更高。

3.1.2 deepseek-v4-flash：快速轻量引擎

deepseek-v4-flash 是 DeepSeek 的快速推理模型，强调低延迟和高吞吐。在本方案中，它处理所有「不需要深度推理」的工作：

此外，三个后台系统 Agent 也使用 Flash 模型：

• title：为会话自动生成标题
• summary：为长对话自动生成摘要
• compaction：在上下文接近窗口上限时执行压缩

Flash 的关键特征是快、省：低延迟响应 + 低 Token 成本，适合高频率的检索和小修改操作。

3.1.3 模型 ID 命名规则

在 OpenCode 中，模型通过 provider_id/model_id 格式唯一标识。本方案中的两个模型：

deepseek/deepseek-v4-pro
deepseek/deepseek-v4-flash

其中 deepseek 是 Provider ID，deepseek-v4-pro 和 deepseek-v4-flash 是模型 ID。这种命名规则贯穿整个配置体系——无论是在 opencode.jsonc 的顶层 model 字段、Agent 定义文件中的 model 字段，还是命令路由中，都以同样的格式引用模型。

重要：由于模型 ID 本身包含斜杠 /，在 agent 配置中建议始终使用 model 字段明确指定模型，而非依赖默认继承。这避免了 Provider 枚举时模型 ID 被错误解析为路径。

3.1.4 成本对比

Pro 和 Flash 的定价差异显著，按 DeepSeek 官方定价（以 2026 年初为参考）：

以一个典型开发会话为例：Pro 完成一次「深度分析 + 多文件修改」可能消耗 50K-200K tokens，而 Flash 完成一次「代码库搜索 + 报告」可能只消耗 5K-15K tokens。将高频、低认知负担的任务交给 Flash，是本方案控制成本的核心策略。

3.2 为什么只用 DeepSeek

本方案只使用 DeepSeek 一个 Provider，不是临时选择，而是经过深思熟虑的设计决策。

3.2.1 模型隔离设计：双重锁机制

在 opencode.jsonc 中，通过白名单和黑名单实现双重锁定：

{
  "enabled_providers": ["deepseek"],
  "disabled_providers": ["openai", "anthropic", "google", "openrouter"]
}

• enabled_providers（白名单）：只允许 deepseek Provider 加载。设置为非空数组后，只有列表中的 Provider 可用。
• disabled_providers（黑名单）：显式禁用 openai、anthropic、google、openrouter。即使系统中配置了这些 Provider 的 API Key 或环境变量，OpenCode 也不会加载它们。

双重锁的价值在于防御性：白名单定义了「允许谁」，黑名单再次确认「禁止谁」。即使白名单被意外修改（例如合并了其他配置文件），黑名单仍然生效——在配置合并机制中，黑名单的优先级高于白名单。

3.2.2 团队统一的考虑

当团队多人共用同一套配置时，统一 Provider 的核心收益是消除行为差异：

• 同一个任务，运行在 Claude 和 DeepSeek 上可能产生不同的输出风格、代码结构、甚至不同的 Bug 修复策略。
• 在代码审查中，Pro Agent 给出的反馈应该基于同一个模型的能力基准——如果 Reviewer 用 Claude 而 Deep Worker 用 DeepSeek，审查意见的「精度预期」就不一致。
• 团队积累的 AGENTS.md 规则和 Prompt 优化经验，都是在特定模型行为上迭代的结果。切换模型相当于丢弃这些积累。

简言之：用同一个模型家族的 Pro + Flash 组合，比「跨 Provider 混搭」更能保证一致性和可预测性。

3.2.3 成本可控性

多 Provider 混搭的隐性成本不仅来自「贵模型用多了」，更来自不可预测性：

• 不同 Provider 对同样的系统提示词可能产生不同长度的响应。
• 不同 Provider 的上下文窗口大小、压缩策略、缓存机制各不相同。
• 切换模型时，由于行为差异导致的返工（推倒重来）是最大的成本黑洞。

只用一个 Provider + 两个模型的组合，让成本完全可量化：每月用量 = Pro 用量 × Pro 单价 + Flash 用量 × Flash 单价，不存在「某次不小心调了 Opus」的意外账单。

3.2.4 避免「模型大杂烩」

在 AI 辅助编程领域有一个常见的反模式：给每个 Agent 配备不同 Provider 的模型（例如 Orchestrator 用 GPT-5、Deep Worker 用 Claude、Explore 用 Gemini Flash）。这种策略的隐性代价是：

1. 上下文漂移：Orchestrator 用 GPT 分析任务后传给 Claude 执行的子上下文，GPT 的表达方式和 Claude 的解读方式存在细微差异，导致信息损耗。
2. 审查不校准：Reviewer（Codex）审查 Deep Worker（Claude）的代码时，两个模型的「好代码」标准不同，可能产生无意义的争议。
3. 维护负担：5 个 Agent × 3 个 Provider = 15 个模型行为需要理解和调优。出了 Bug，排查时还要先排除「是不是模型行为差异导致的」。
4. 配置复杂化：每个 Provider 有独立的 options（API Key、baseURL、timeout、headers），配置膨胀且容易出错。

纯 DeepSeek 方案把「模型行为」这个变量彻底剔除。所有 Agent 共享同一个底层的训练数据和推理范式，行为差异仅来自 Prompt 和温度参数，而非模型本身。

3.3 Provider 配置详解

完整的 Provider 配置如下（来自 opencode.jsonc）：

{
  "model": "deepseek/deepseek-v4-pro",
  "small_model": "deepseek/deepseek-v4-flash",
  "enabled_providers": ["deepseek"],
  "disabled_providers": ["openai", "anthropic", "google", "openrouter"]
}

3.3.1 model：默认主模型

"model": "deepseek/deepseek-v4-pro"

model 字段定义了全局默认模型。其加载优先级如下：

1. 命令行 --model / -m 标志
2. 配置文件中的 model 字段
3. 上次使用的模型（会话记忆）
4. 按内部优先级选第一个可用模型

在本方案中，所有未显式指定 model 的 Agent（包括自定义 Agent）都将使用 deepseek-v4-pro。但实际所有 Agent 都在各自的定义文件中显式指定了模型，所以这个字段的作用是兜底——防止任何 Agent 因缺少模型配置而用错模型。

3.3.2 small_model：轻量模型

"small_model": "deepseek/deepseek-v4-flash"

small_model 定义了轻量任务默认模型。OpenCode 会将以下后台任务分流到此模型：

• 标题生成（title Agent）：根据会话内容自动生成描述性标题
• 摘要生成（summary Agent）：在上下文压缩时生成阶段性摘要
• 上下文压缩（compaction Agent）：将长对话压缩为简洁的上下文摘要

在本方案中，这三个后台 Agent 都在 agent 配置块中显式指定了模型和回退：

"agent": {
  "title": {
    "model": "deepseek/deepseek-v4-flash",
    "fallback": "deepseek/deepseek-v4-pro"
  },
  "summary": {
    "model": "deepseek/deepseek-v4-flash",
    "fallback": "deepseek/deepseek-v4-pro"
  },
  "compaction": {
    "model": "deepseek/deepseek-v4-flash",
    "fallback": "deepseek/deepseek-v4-pro"
  }
}

small_model 字段和这些 Agent 级配置共存的设计是防御性冗余：即使 Agent 级配置被意外覆盖或删除，small_model 仍然生效。

fallback 字段指定了 Flash 模型不可用时的回退模型。当 deepseek-v4-flash 连接失败、返回错误或超时时，系统自动降级到 deepseek-v4-pro 完成任务——这保证了后台任务永远不会因模型不可用而失败。

3.3.3 enabled_providers：白名单

"enabled_providers": ["deepseek"]

白名单的工作机制：

• 设为空数组或不设置：所有已认证的 Provider 都可用。
• 设为非空数组：只有列表中的 Provider ID 可用，其他 Provider 即使已认证也不会加载。
• 被白名单排除的 Provider 不会出现在 /models 列表中，Agent 无法选择或使用它们。

在本方案中，白名单只包含 deepseek，意味着只有 DeepSeek 的模型可以加载和使用。

3.3.4 disabled_providers：黑名单

"disabled_providers": ["openai", "anthropic", "google", "openrouter"]

黑名单的工作机制：

• 即使对应的 API Key 已设置或环境变量已配置，被列入黑名单的 Provider 也不会加载。
• 黑名单优先级高于白名单：如果某个 Provider ID 同时出现在两个列表中，黑名单生效。
• 被禁用的 Provider 不会消耗任何启动时间（跳过加载流程）。

本方案显式禁用了四个主流 Provider：OpenAI、Anthropic、Google、OpenRouter。它们的 API Key 可能因其他工具的需求而配置在系统中，但 OpenCode 不会误用。

3.4 Thinking/Reasoning 模式配置

DeepSeek V4 Pro 支持思考模式（Thinking Mode）——一种让模型在回答前进行内部推理链增强的机制。本方案通过 Provider 级别的 options 配置为 Pro 模型启用此模式：

"provider": {
  "deepseek": {
    "models": {
      "deepseek-v4-pro": {
        "options": {
          "thinking": { "type": "enabled" }
        }
      }
    }
  }
}

注意：如果你的 opencode.jsonc 中尚未包含此 Provider 配置块，请添加。Thinking 模式仅对 Pro 模型生效，Flash 模型不支持或不需要此配置。

3.4.1 Thinking 模式的工作机制

Thinking 模式是 DeepSeek 对标 OpenAI o-series 和 Anthropic Extended Thinking 的推理增强功能。当启用时：

1. 模型在生成最终回答之前，先进行一段内部推理链（think step）。
2. 推理链对用户不可见（除非显式设置为可见），但会显著提升答案的准确性和完整性。
3. 推理链消耗额外的 Token（称为 “reasoning tokens” 或 “thinking tokens”），计入输入 Token 费用。

它和「让模型在 Prompt 里写 Let me think step by step」有本质区别：

• Prompt 里的 CoT（Chain of Thought）是显式推理：模型把推理过程写进输出，占用输出 Token。
• Thinking 模式是隐式推理：模型在内部完成推理，只输出结论，不占用输出 Token，但消耗思考 Token（通常按输入 Token 计费）。

3.4.2 适用场景

不适合的场景：简单的单文件修改、打字修正、配置变更、模板填充——这些 Flash 模型已经足够。

3.4.3 成本权衡

Thinking 模式的代价是思考 Token 消耗：

实践建议：Keep it on。对于需要 Pro 模型的任务（深度分析、规划、审查），思考 Token 的额外成本远小于「返工一次」的代价。一张错误的设计图，在实现阶段可能浪费 10 倍于思考 Token 的成本。

3.4.4 可以配置的 Thinking 选项

如果你的场景对推理深度有特殊要求，可以进一步配置：

"provider": {
  "deepseek": {
    "models": {
      "deepseek-v4-pro": {
        "options": {
          "thinking": {
            "type": "enabled",
            "budgetTokens": 16000
          }
        }
      }
    }
  }
}

• type: "enabled"：开启思考模式（默认）。
• type: "disabled"：关闭思考模式。
• budgetTokens：设置思考 Token 预算上限，超过此上限模型会尽早输出答案。

budgetTokens 是成本控制的重要旋钮：对于中度复杂的任务，8K-16K 的预算通常足够；只有在极端复杂的推演场景（如大规模系统重构方案），才需要更大的预算。

DeepSeek V4 Pro 的 Thinking 模式基于模型原生能力，不需要额外的 API 参数适配。如果你使用的是 DeepSeek 兼容 API（通过代理或自建网关），需要确认网关是否转发 thinking 请求参数。

3.5 模型路由策略

本方案通过「模型感知路由」实现精准的任务-模型匹配。路由发生在两个层面：Agent 分配层和Orchestrator 调度层。

3.5.1 Flash 优先原则

在 AGENTS.md 的 Core Principles 中明确规定：

Right-size the model to the task. Prefer flash for search, lookup, and simple edits; reserve pro for reasoning and heavy implementation. When borderline, prefer flash.

这条规则的具体含义：

当任务处于边界时，AGENTS.md 明确规定：prefer flash。宁可先用 Flash 快速探路、发现不够再升级，也不要一开始就用 Pro 消耗大量 Token。

3.5.2 Pro 专注推理

Pro 模型的所有使用场景都有一个共同特征：需要推理。它不是「写代码快」的模型——在本方案中，代码编写是 Deep Worker 的职责，Deep Worker 之所以用 Pro，不是因为 Pro 写代码快，而是因为 Deep Worker 在写代码前需要：

1. 读取和理解多文件上下文
2. 推演改动的连锁影响
3. 设计修改方案
4. 并行规划执行步骤
5. 自我验证

这些步骤都需要推理。如果 Deep Worker 只需要做一个简单的单行改动，Orchestrator 根本不会调度它——Light Orchestrator（Flash）就足够了。

3.5.3 自动升级机制

当 Flash Agent 无法完成任务时，本方案内置了升级路径：

1. Orchestrator 层面：Orchestrator 分析 Flash Agent 返回的结果。如果结果不完整、质量不满足要求，或 Agent 明确表示「这个任务超出了我的能力」，Orchestrator 将任务升级到 Pro Agent 并附带完整上下文。
2. Agent 内部：后台系统 Agent（title/summary/compaction）在 Flash 模型不可用时，通过 fallback 字段自动降级到 Pro 模型。
3. fallback 链：deepseek-v4-flash → deepseek-v4-pro，不引入第三方模型。

升级时，Orchestrator 会将 Flash Agent 已完成的探索结果作为上下文传递给 Pro Agent，避免重复工作。这是本方案「不浪费 Token」的核心设计之一。

3.5.4 Agent 模型分配总览

下面是所有 Agent 的模型分配：

Pro（deepseek-v4-pro）:
  ├── orchestrator      — 主控调度
  ├── planner           — 战略规划
  ├── oracle            — 深度分析、根因调试
  ├── reviewer          — 代码审查
  ├── consultant        — 方案评估、脑力激荡
  ├── deep-worker       — 重型实现
  ├── ui-builder        — 前端界面构建
  └── (build / plan)    — 内置主智能体（备用）

Flash（deepseek-v4-flash）:
  ├── explore           — 代码库搜索（只读）
  ├── librarian         — 外部文档检索（只读）
  ├── light-orchestrator— 简单任务执行
  ├── title             — 标题生成（系统）
  ├── summary           — 摘要生成（系统）
  └── compaction        — 上下文压缩（系统）

这种分配遵循的核心原则是：让 Pro 做需要思考的事，让 Flash 做需要手快的事。

3.6 模型参数调优

不同 Agent 需要不同的行为参数。本方案根据角色需求差异化配置了 temperature 和 steps。

3.6.1 Temperature 设置

Temperature 控制模型输出的随机性（0.0 = 确定，1.0 = 最大随机性）：

核心规律：分析型角色（Oracle、Explore、Reviewer）用 0.1-0.2 的低温度保证确定性；创造性角色（Consultant、Planner）用 0.3-0.5 获得多样性。

3.6.2 Steps 限制

steps 限制了 Agent 在单次会话中最多执行多少次「思考-行动」循环：

Steps 既是成本控制阀门，也是质量保证——限制步数迫使 Agent 在有限步骤内给出最优解，而非无限试探。达到上限时，Agent 会收到系统提示，要求总结已完成工作并列出剩余任务。

3.6.3 上下文窗口

本方案的 compaction 配置：

"compaction": {
  "auto": true,
  "prune": false,
  "tail_turns": 8,
  "preserve_recent_tokens": 12000,
  "reserved": 10240
}

• auto: true：上下文接近窗口上限时自动压缩
• prune: false：不自动裁剪旧工具输出（保留用于回溯）
• tail_turns: 8：保留最近 8 轮对话的完整历史
• preserve_recent_tokens: 12000：在压缩后额外保留最近 ~12K tokens 的对话
• reserved: 10240：为压缩过程预留 ~10K tokens 缓冲

对于 Deep Worker 这种可能产生超长会话的 Agent（100 steps × 每轮输出），compaction 是防止上下文溢出和 Token 失控的关键机制。

3.6.4 各 Agent 关键参数汇总

未显式设置 temperature 的 Agent（如 Orchestrator）使用模型默认值。DeepSeek V4 系列的默认 temperature 通常在 0.6-0.7 之间（取决于版本），Orchestrator 的调度决策不需要严格的确定性，默认值即可。

3.7 多模型协作模式

Pro Agent 和 Flash Agent 不是独立运作的孤岛，它们通过 Orchestrator 的调度机制协同工作，形成完整的任务处理流水线。

3.7.1 协作流程：一个典型任务的生命周期

以「在项目中添加一个新功能」为例：

用户请求
    │
    ▼
[Orchestrator (Pro)]
    ├── 分析意图：实现新功能 → 属于"Explicit implementation"
    │
    ▼
[Planner (Pro)]
    ├── 系统分析，编写 Spec
    ├── 输出：功能分解、文件清单、实现步骤
    │
    ▼
[Explore (Flash)] ← 被 Deep Worker 内部调用
    ├── 并行搜索相关代码位置
    ├── 返回：受影响文件的精确列表
    │
    ▼
[Deep Worker (Pro)]
    ├── 读取 Explore 提供的文件清单
    ├── 逐文件实现
    ├── 遇到外部库 API 不确定
    │   │
    │   ▼
    │ [Librarian (Flash)]
    │   ├── 搜索官方文档
    │   ├── 返回：API 签名和用法
    │   │
    │   ▼
    ├── 使用 Librarian 的 API 信息继续实现
    ├── 自我验证
    ├── 完成
    │
    ▼
[Reviewer (Pro)] ← 可选，取决于任务复杂度
    ├── 审查变更
    ├── 输出：审查意见
    │
    ▼
[Light Orchestrator (Flash)] ← 提交阶段
    ├── 运行 `git diff`
    ├── 生成 Conventional Commits 消息
    ├── 执行 `git commit`
    │
    ▼
完成

在这个流程中，Pro Agent 承担了所有需要思考的阶段（分析、规划、实现、审查），Flash Agent 在中间穿插处理检索和简单操作。每次 Flash Agent 完成任务后，它的结果被注入主流程的上下文，Pro Agent 无需重新探索。

3.7.2 Orchestrator 的模型感知路由

Orchestrator 了解每个子 Agent 的模型能力和限制（参见 orchestrator.md 中完整的意图-路由映射表）。它的路由逻辑是模型感知的：

• 当任务需要推理时 → 路由到 Pro Agent（planner、oracle、reviewer、deep-worker、consultant、ui-builder）
• 当任务只需要检索时 → 路由到 Flash Agent（explore、librarian）
• 当任务是简单执行时 → 路由到 Flash Agent（light-orchestrator）
• 当任务处于边界时 → 优先路由到 Flash Agent（AGENTS.md 规则：”When borderline, prefer flash”）

这种「右尺寸模型」的路由策略，是方案成本效率的核心——它确保没有一个推理 Token 浪费在搜索上，也没有一个搜索等待推理链完成。

3.7.3 上下文在模型间的传递机制

当 Orchestrator 将任务从一个 Agent 传递给另一个时，上下文的传递遵循以下原则：

1. 子会话隔离：每个子 Agent 在独立的子会话中工作。子会话拥有启动时注入的完整系统上下文（AGENTS.md、Skill 等），但不会累积主会话的历史噪音。

2. 结果而非过程：子 Agent 完成任务后，只返回精炼结论给主会话，而非原始探索过程。例如 Explore 返回「函数 X 在 src/foo.ts:42 定义，被 a.ts、b.ts、c.ts 调用」，而不是返回每次 grep 的完整输出。

3. 路径引用而非内容复制：返回结论中使用文件路径和行号引用（如 src/app.ts:42），而非粘贴完整文件内容。调用方 Agent 可以自行决定需要读取哪些部分。

4. 升级时带完整上下文：当 Flash Agent 无法完成任务、Orchestrator 升级到 Pro Agent 时，它将 Flash Agent 的完整子会话上下文传递给 Pro Agent——这样 Pro Agent 不需要重复 Flash 已经做过的工作。

这套传递机制的 Token 效率体现在：主会话只累积「谁做了什么 + 结论是什么」，不累积每次搜索的原始输出。一个包含 10 次子代理调用的会话，如果每次都复制原始上下文，上下文体积可能膨胀到数万 tokens；而用精炼结论，可能只有数千 tokens。

3.7.4 后备链中的模型切换

本方案的后备链是单 Provider 内降级，而非跨 Provider 切换：

deepseek-v4-flash (首选)
    ├── 成功 → 完成
    └── 失败/不可用 → deepseek-v4-pro (fallback)

这种设计的优势：

• 行为一致性：回退到 Pro 后，模型输出风格与 Flash 相近（同家族），不会产生风格突变。
• 配置简单化：不需要维护多个 Provider 的 API Key、baseURL、timeout 等参数。
• 失败可预测：Flash 失败的原因通常是服务故障或配额耗尽，回退到 Pro 后这些问题通常不存在。

跨 Provider 后备链（如 DeepSeek Flash 失败 → 回退到 Claude Haiku）虽然听起来更安全，但实际引入了行为差异和配置复杂度。在本方案的「Pure-config philosophy」下，单 Provider 后备链更简洁、更可控。

3.7.5 多模型协作的收益量化

以一个月的使用数据为例（假设日均 50 次 Agent 调用）：

注：此为估算值，实际取决于任务复杂度。关键不在于数字的精确性，而在于比例关系：Flash 处理了 ~57% 的调用次数，但只消耗了 ~30% 的 Token 成本——因为单次成本低且任务都足够简单。

如果把所有 146+ 次调用都交给 Pro，总成本大约会翻 3-4 倍。这就是双模型协作的价值：高频调用的成本被 Flash 压到了最低，Pro 只在高价值的推理场景下出场。

3.8 小结

本章全面解构了 my-opencode-deepseek-config 的模型配置体系，核心要点回顾：

1. 双模型体系：deepseek-v4-pro 负责推理（规划、分析、审查、实现），deepseek-v4-flash 负责检索和简单执行（搜索、文档查询、配置修改、后台任务）。

2. 单一 Provider 设计：通过白名单 + 黑名单双重锁定，只用 DeepSeek。避免多 Provider 混搭导致的行为不一致、成本不可控和配置复杂化。

3. Thinking 模式：为 Pro 模型启用内部推理链，提升复杂任务的质量。思考 Token 的额外成本远小于返工的代价。

4. 模型感知路由：Orchestrator 根据任务需求，将任务精确路由到「能力恰好匹配」的 Agent。Flash 优先原则确保高频任务的成本最优。

5. 参数差异化：分析型 Agent 用低 temperature（0.1-0.2），创造性 Agent 用中 temperature（0.3-0.5）。Steps 限制了每个 Agent 的迭代次数，兼顾成本控制和输出质量。

6. 多模型协作：Pro 和 Flash 不是替代关系，而是互补关系。Flash 做探索、检索和简单执行，产出精炼结论注入主流程；Pro 做推理、规划和复杂实现，利用 Flash 的检索成果快速起步。

这套模型配置体系是「纯配置驱动」理念的体现——不需要额外的中间件或路由框架，仅通过 OpenCode 的原生配置机制，就实现了生产级的任务分发和模型协作。

下一章：第四章：多 Agent 体系完全解析 —— 深入剖析 11 个 Agent 的设计哲学、职责边界和协作关系。