18.2 oh-my-opencode 的设计启示

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-18

---

如果说 OpenCode 展示了"如何构建一个可扩展的 AI 编程助手引擎"，那么 oh-my-opencode 则展示了"如何在引擎之上构建一个强大的 AI 编程团队"。作为 OpenCode 生态中最复杂的第三方 Plugin，oh-my-opencode 的设计理念值得每一个 AI 应用开发者学习。

18.2.1 "Prompt Engineering as Code"——将 Prompt 工程化

在很多 AI 应用中，Prompt 是作为"配置"或"字符串常量"存在的——写在配置文件或数据库里，由人工手动调整。oh-my-opencode 采取了完全不同的方法：把 Prompt 当作代码来工程化管理。

动态 Prompt 构建器

oh-my-opencode 的核心创新之一是 dynamic-agent-prompt-builder.ts——一个根据运行时状态动态生成 Prompt 的系统：

// 不是硬编码的字符串，而是根据可用 Agent 动态构建
export function buildToolSelectionTable(
  agents: AvailableAgent[],
  tools: AvailableTool[],
): string {
  const rows: string[] = ["### Tool & Agent Selection:", ""]

  // 根据实际可用的工具生成表格
  if (tools.length > 0) {
    rows.push(`- ${formatToolsForPrompt(tools)} — **FREE** — Not Complex`)
  }

  // 按成本排序 Agent，低成本优先
  const sorted = [...agents].sort(
    (a, b) => costOrder[a.metadata.cost] - costOrder[b.metadata.cost]
  )
  for (const agent of sorted) {
    rows.push(`- \`${agent.name}\` — **${agent.metadata.cost}** — ${agent.description}`)
  }

  return rows.join("\n")
}

这意味着：

• Prompt 会随着配置变化而变化：如果用户禁用了某个 Agent，Prompt 中就不会出现对它的引用

• Prompt 与数据保持同步：不会出现 Prompt 提到了不存在的工具的情况

• Prompt 可以被测试：构建函数是纯函数，可以用单元测试验证输出

Prompt 的版本控制

oh-my-opencode 中每个 Agent 的 Prompt 都是独立的 TypeScript 文件（如 agents/sisyphus.ts、agents/oracle.ts），而非 .txt 文本。这让 Prompt 可以：

• 引用变量和常量

• 使用模板字符串插值

• 包含条件逻辑

• 享受 TypeScript 的类型检查

// agents/sisyphus.ts 中的 Prompt 片段
const systemPrompt = `你是 Sisyphus——${teamDescription} 的技术负责人。

## 可用团队成员
${buildDelegationTable(availableAgents)}

## 当前项目上下文
${envContext}

## 委托协议
${delegationProtocol}
`

设计启示

将 Prompt 视为代码而非配置——这意味着 Prompt 应该享有代码的所有工程实践：版本控制、Code Review、单元测试、动态组装。对于复杂的 AI 应用，静态的 Prompt 字符串是不够的。

18.2.2 "Hook 即策略"——53 个 Hook 的设计哲学

oh-my-opencode 注册了多达 53 个 Hook（第 15.5 节），覆盖了从消息处理到错误恢复的方方面面。但重要的不是数量，而是背后的设计哲学。

Hook 作为策略模式

传统的策略模式（Strategy Pattern）通常用 Class 和接口实现。oh-my-opencode 用 Hook 实现了一种更灵活的策略模式：

┌─────────────────────────────────────────┐
│              OpenCode 核心               │
│                                         │
│  消息发送 ──Hook──▶ chat.message        │
│  工具执行前 ──Hook──▶ tool.execute.before│
│  工具执行后 ──Hook──▶ tool.execute.after │
│  会话压缩 ──Hook──▶ session.compacting  │
│                                         │
└─────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────┐
│         oh-my-opencode 策略层            │
│                                         │
│  chat.message:                          │
│    ├── stop-continuation-guard  ← 防止无限继续  │
│    ├── keyword-detector         ← 关键词检测    │
│    ├── auto-slash-command       ← 自动命令      │
│    └── agent-usage-reminder     ← Agent 使用提醒│
│                                         │
│  tool.execute.after:                    │
│    ├── tool-output-truncator    ← 输出截断      │
│    ├── preemptive-compaction    ← 先发制人压缩  │
│    └── comment-checker          ← 注释检查      │
│                                         │
└─────────────────────────────────────────┘

每个 Hook 都是一个独立的策略，可以通过配置启用或禁用：

{
  "disabled_hooks": ["ralph-loop", "auto-slash-command"]
}

Hook 分类体系

53 个 Hook 并非随意添加的——它们形成了清晰的分类体系：

类别	代表 Hook	设计意图
错误恢复	edit-error-recovery、session-recovery、json-error-recovery	AI 会犯错，系统要能自动修复
上下文管理	preemptive-compaction、context-window-monitor	Token 是稀缺资源，要主动管理
行为约束	stop-continuation-guard、unstable-agent-babysitter	AI 需要"护栏"，防止失控
信息注入	directory-agents-injector、rules-injector	给 AI 提供决策所需的上下文
输出控制	tool-output-truncator、thinking-block-validator	控制 AI 输出的质量和格式
任务管理	todo-continuation-enforcer、task-reminder	确保 AI 完成所有子任务

设计启示

不要试图让 AI 一次就做对——而是构建多层防护网。oh-my-opencode 的 53 个 Hook 构成了一个"防御纵深"（Defense in Depth）体系：

1. 预防层：stop-continuation-guard 防止 AI 无限循环

2. 检测层：context-window-monitor 监控上下文窗口使用率

3. 修复层：edit-error-recovery 自动修复编辑失败

4. 兜底层：session-recovery 在会话崩溃时尝试恢复

每一层都假设上一层可能失败。这种防御式设计是构建可靠 AI 系统的关键。

18.2.3 "Agent 人格化"——从希腊神话到工程实践

oh-my-opencode 为 Agent 赋予了希腊神话人物的名字：Sisyphus（西西弗斯）、Oracle（神谕）、Prometheus（普罗米修斯）、Hephaestus（赫菲斯托斯）、Atlas（阿特拉斯）、Metis（墨提斯）、Momus（摩墨斯）……

这不仅仅是命名偏好——它反映了一种深思熟虑的Agent 设计方法论。

名字暗示角色

每个神话人物的故事都与 Agent 的功能产生联想：

Agent 名	神话背景	功能联想
Sisyphus	被罚永远推巨石上山	主 Agent，反复处理任务，永不停歇
Oracle	德尔斐神谕，预知未来	技术顾问，提供决策建议
Prometheus	盗火给人类的先知	任务规划器，带来"火种"（计划）
Hephaestus	奥林匹斯的工匠之神	代码工匠，专注实现
Explore	—	代码搜索专家（保留了务实的命名）
Metis	智慧女神，宙斯的谋士	预规划分析师
Momus	批评之神，挑剔万物	方案评审专家
Atlas	扛天的巨人	项目导航，承载全局信息

这种命名策略的好处：

1. 可记忆性

比较两种日志：

[sisyphus] 委托给 prometheus 进行规划
[prometheus] 规划完成，移交给 hephaestus 实现

vs.

[agent-001] 委托给 agent-003 进行规划
[agent-003] 规划完成，移交给 agent-004 实现

神话名字让多 Agent 协作的日志像是在阅读一个"故事"，大大提升了可理解性。

2. 心智模型锚定

当你知道 Sisyphus 是"永远推石头的人"，你就能直觉地理解它是一个不会放弃、反复尝试的 Agent。这种心智模型帮助开发者快速理解 Agent 的行为特征。

3. Prompt 工程的锚点

Agent 的名字可以直接用在 Prompt 中，强化其角色认同：

你是 Sisyphus——一个永不放弃的技术负责人。
即使任务困难重重，你也会想方设法完成它。

设计启示

为 Agent 赋予有意义的"人格"。这不是多余的修饰——它帮助开发者理解 Agent 的设计意图，帮助 LLM 更好地"进入角色"，也让整个系统的行为更加可预测。好的 Agent 名字应该：

• 暗示其核心职责

• 让人一看就知道"它擅长什么"

• 在日志和调试中容易辨识

18.2.4 "防御式编程"——错误恢复与兜底策略

AI 系统与传统软件的根本区别在于：LLM 的输出是不确定的。传统软件出 Bug 是因为代码有错，而 AI 系统"出 Bug"可能仅仅因为模型这次"想法不同"。

oh-my-opencode 深刻理解这一点，构建了一套完整的防御式编程体系。

错误分类与定向恢复

session-recovery Hook 是典型示例。它不是简单地 try-catch 然后报错，而是分类错误并对症下药：

export type RecoveryErrorType =
  | "tool_result_missing"          // 工具结果丢失
  | "thinking_block_order"         // 思考块顺序错误
  | "thinking_disabled_violation"  // 思考功能未启用但出现了思考块
  | "assistant_prefill_unsupported" // 不支持 assistant 预填充

export function detectErrorType(error: unknown): RecoveryErrorType {
  const message = getErrorMessage(error)

  if (message.includes("tool_use") && message.includes("tool_result")) {
    return "tool_result_missing"
  }
  if (message.includes("thinking") && message.includes("first block")) {
    return "thinking_block_order"
  }
  // ...
}

每种错误类型有专门的恢复策略：

错误类型	恢复策略
tool_result_missing	补全缺失的工具结果，重新提交
thinking_block_order	调整消息中思考块的顺序
thinking_disabled_violation	删除消息中的思考内容
assistant_prefill_unsupported	将 assistant 消息转换为 user 消息

多层容错设计

oh-my-opencode 的容错不是单点的，而是多层嵌套的：

第1层: edit-error-recovery
  当 edit 工具失败时（如 old_string 不唯一），
  自动提供修复建议，而非让 Agent 盲目重试

第2层: unstable-agent-babysitter
  监控子 Agent 的行为，如果发现其输出异常
  （如连续失败、输出过短），自动干预

第3层: session-recovery
  如果整个会话因 API 错误崩溃，
  分析错误类型，尝试修复消息并恢复

第4层: context-window-monitor + preemptive-compaction
  在上下文窗口接近上限之前就主动压缩，
  避免因超限导致的硬错误

设计启示

构建 AI 系统时，应该遵循以下防御式编程原则：

1. 错误分类优于通用 catch：不同类型的错误需要不同的恢复策略

2. 主动预防优于被动修复：preemptive-compaction 在溢出前就行动

3. 优雅降级优于完全失败：即使某个 Agent 失败，系统应该能继续运行

4. 所有外部交互都可能失败：LLM API 调用、工具执行、文件操作——每一步都应该有容错处理

5. 记录恢复过程：错误恢复的日志对于调试和改进至关重要

---

oh-my-opencode 的这四个设计启示——Prompt 工程化、Hook 策略体系、Agent 人格化、防御式编程——不仅适用于 OpenCode Plugin 开发，更是所有 AI Agent 系统的通用设计智慧。在下一节中，我们将把这些洞察与 OpenCode 核心的设计决策整合，提炼出构建 AI 编程助手的最佳实践。