技术原理核心

2.1 Agent 系统架构

oh-my-opencode 的 Agent 系统采用分层编排架构，核心设计理念是**“不同任务使用最适合的模型”**。这类似于一个真实的开发团队——架构师、研究员、实现工程师各司其职，使用不同的思维方式和工作方法。

graph TD
    A[用户请求] --> B[Sisyphus<br/>主编排 Agent]
    B --> C{任务分类}
    
    C -->|规划/分析| D[Prometheus<br/>计划 Agent]
    C -->|代码探索| E[Explore<br/>探索 Agent]
    C -->|文档研究| F[Librarian<br/>图书管理员]
    C -->|架构设计| G[Oracle<br/>战略顾问]
    C -->|前端开发| H[Frontend UI/UX<br/>前端工程师]
    C -->|深度实现| I[Hephaestus<br/>自主工作者]
    C -->|代码审查| J[Momus<br/>计划审查者]
    
    D --> K[Metis<br/>计划顾问]
    K --> L[任务队列]
    L --> M[并行执行]

核心设计哲学

1. 专业化分工：每个 Agent 专注于特定领域，避免”万金油”模型
2. 成本优化：根据任务重要性分配不同价位的模型
3. 能力匹配：Agent 角色与模型特性精准对应
4. 并行处理：多个 Agent 可以同时工作，提高效率

2.2 Agent 模型配置解析

oh-my-opencode 的 Agent 配置使用 Zod Schema 进行严格验证，配置结构如下：

interface AgentConfig {
  model: string;              // 模型标识符，如 "anthropic/claude-opus-4-5"
  variant?: string;           // 模型变体，如 "high", "low", "latest"
  temperature?: number;       // 温度参数，控制创造性 (0.0 - 1.0)
  top_p?: number;            // Top-p 采样参数
  prompt?: string;           // 自定义系统提示词
  prompt_append?: string;    // 追加提示词
  tools?: ToolPermissions;   // 工具权限配置
  permission?: Permissions;  // 访问权限配置
  category?: string;         // 继承的类别配置
}

模型标识符格式

格式: <provider>/<model-name>[:<variant>]

示例:
- anthropic/claude-opus-4-5:high
- openai/gpt-5.2
- google/gemini-3-flash
- opencode/glm-4.7-free

内置 Agent 默认模型配置

2.3 模型特性分类体系

oh-my-opencode 根据以下维度对模型进行分类：

2.3.1 能力维度

┌─────────────────────────────────────────────────────────────┐
│                    模型能力分类体系                           │
├──────────────┬──────────────────────────────────────────────┤
│ 能力类别      │ 描述                                          │
├──────────────┼──────────────────────────────────────────────┤
│ reasoning    │ 逻辑推理、数学计算、复杂问题求解                 │
│ tool_call    │ 函数调用、工具使用能力                          │
│ coding       │ 代码理解、生成、重构能力                        │
│ attachment   │ 多模态输入（图像、PDF等）处理能力                │
│ creativity   │ 创造性写作、设计能力                            │
│ instruction  │ 指令遵循准确性                                  │
└──────────────┴──────────────────────────────────────────────┘

2.3.2 成本级别定义

2.3.3 Agent 能力需求矩阵

2.4 模型选择背后的设计逻辑

为什么 Sisyphus 选择 Claude Opus 4.5？

核心原因：

1. 指令遵循能力：Claude Opus 4.5 具有业界领先的指令遵循准确性（9.9/10），这对于需要严格执行复杂工作流的编排 Agent 至关重要
2. 上下文窗口：200K+ tokens 的上下文窗口，能够处理大型代码库的全局分析
3. 工具调用稳定性：在复杂的多步工具调用场景下保持稳定的表现
4. 安全性和可控性：Anthropic 的 Constitutional AI 训练使模型更不容易产生有害或偏离轨道的输出

替代模型选择考量：

• GPT-5.2 虽然推理能力更强，但在长上下文代码理解方面略逊一筹
• Gemini 3 Pro 上下文更大，但工具调用稳定性不如 Claude

为什么 Librarian 使用免费模型 GLM-4.7？

核心原因：

1. 成本效益：文档研究是高频率操作，使用免费模型可大幅降低成本
2. 足够的能力：GLM-4.7 在代码理解和文档检索方面表现良好
3. 速度：轻量级模型响应更快，适合并行执行多个探索任务
4. 证据驱动：Librarian 的工作模式是”搜索-总结”，不需要深层次的创造性推理

风险提示：免费模型可能在处理非常复杂的跨文件依赖分析时表现不佳。

为什么 Explore 使用 Gemini Flash？

核心原因：

1. 极致速度：Gemini Flash 是 Google 推出的高速模型，延迟极低
2. 成本极低：每百万 tokens 仅需 $0.075，适合大规模并行探索
3. 足够的基础能力：对于代码搜索和模式匹配任务，Flash 版本已经足够
4. 适合后台任务：Explore 通常在后台运行，不需要等待结果

2.5 配置继承与覆盖机制

oh-my-opencode 采用三级配置继承体系：

用户全局配置 (~/.config/opencode/oh-my-opencode.json)
         ↓
项目级配置 (.opencode/oh-my-opencode.json)
         ↓
运行时参数 (环境变量 / 代码中覆盖)

配置合并规则

// 示例：Sisyphus 配置继承
const defaultConfig = {
  model: "anthropic/claude-opus-4-5",
  temperature: 0.7,
  maxTokens: 32768
};

const userConfig = {
  model: "anthropic/claude-sonnet-4-5",  // 覆盖模型
  temperature: 0.5                        // 覆盖温度
  // maxTokens 继承默认值
};

const finalConfig = { ...defaultConfig, ...userConfig };
// 结果: { model: "claude-sonnet", temperature: 0.5, maxTokens: 32768 }

这种设计允许用户在保持默认最佳实践的同时，根据特定需求进行灵活调整。

参考资料

• oh-my-opencode Agent Reference - Agent 参考文档
• Model Requirements Source - 模型需求定义源码
• Configuration Guide - 配置指南