15.6 Feature 模块

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

---

oh-my-opencode 的 features/ 目录包含 20 个独立的功能模块，每个模块封装了一个完整的功能域。本节将深入分析其中最核心的几个模块。

15.6.1 后台 Agent 系统（features/background-agent/）

后台 Agent 系统是 oh-my-opencode 最复杂的 Feature 模块，拥有 33 个源文件。它实现了异步并行的子 Agent 管理——主 Agent 可以在不阻塞自身的情况下，将子任务分发到后台执行。

架构组件

background-agent/
├── spawner.ts                    # 子会话创建器
├── spawner/                      # 创建器的子模块
├── manager.ts                    # 后台任务管理器
├── task-poller.ts                # 任务轮询器
├── concurrency.ts                # 并发控制器
├── parent-session-notifier.ts    # 父会话通知器
├── parent-session-context-resolver.ts  # 父会话上下文解析
├── result-handler.ts             # 结果处理器
├── session-idle-event-handler.ts # 会话空闲事件处理
├── session-output-validator.ts   # 输出验证器
├── error-classifier.ts           # 错误分类器
├── state.ts                      # 状态管理
├── types.ts                      # 类型定义
└── ...

Spawner：子会话创建器

Spawner 负责创建后台子 Agent 的会话：

// oh-my-opencode/src/features/background-agent/spawner.ts
export function createTask(input: LaunchInput): BackgroundTask {
  return {
    id: `bg_${crypto.randomUUID().slice(0, 8)}`,  // 8 位唯一 ID
    status: "pending",
    queuedAt: new Date(),
    description: input.description,
    prompt: input.prompt,
    agent: input.agent,
    parentSessionID: input.parentSessionID,
    parentMessageID: input.parentMessageID,
    parentModel: input.parentModel,
    parentAgent: input.parentAgent,
    model: input.model,
  }
}

export async function startTask(item: QueueItem, ctx: SpawnerContext): Promise<void> {
  const { task, input } = item

  // 获取父会话的工作目录
  const parentSession = await client.session.get({ path: { id: input.parentSessionID } })
  const parentDirectory = parentSession?.data?.directory ?? directory

  // 获取 Agent 的工具权限限制
  const restrictions = getAgentToolRestrictions(input.agent)

  // 创建新会话并发送提示
  const response = await promptWithModelSuggestionRetry(client, {
    path: {}, // 空 path 表示创建新会话
    body: {
      parts: [{ type: "text", text: input.prompt }],
      agent: input.agent,
      model: input.model,
    },
    query: { directory: parentDirectory },
  })

  // 通知 tmux 管理器
  if (onSubagentSessionCreated) {
    await onSubagentSessionCreated({
      sessionID: response.sessionID,
      parentID: input.parentSessionID,
      title: input.description,
    })
  }
}

Concurrency：并发控制

并发控制器使用信号量模式管理同时运行的后台任务数量：

// oh-my-opencode/src/features/background-agent/concurrency.ts
export class ConcurrencyManager {
  private counts: Map<string, number> = new Map()   // 每个模型的当前并发数
  private queues: Map<string, QueueEntry[]> = new Map()  // 等待队列

  getConcurrencyLimit(model: string): number {
    // 优先级：模型级限制 > Provider 级限制 > 默认限制
    const modelLimit = this.config?.modelConcurrency?.[model]
    if (modelLimit !== undefined) return modelLimit === 0 ? Infinity : modelLimit

    const provider = model.split('/')[0]
    const providerLimit = this.config?.providerConcurrency?.[provider]
    if (providerLimit !== undefined) return providerLimit === 0 ? Infinity : providerLimit

    return this.config?.defaultConcurrency ?? 5  // 默认并发 5
  }

  async acquire(model: string): Promise<void> {
    const limit = this.getConcurrencyLimit(model)
    const current = this.counts.get(model) ?? 0

    if (current < limit) {
      this.counts.set(model, current + 1)
      return  // 未达上限，直接获取
    }

    // 达到上限，进入等待队列
    return new Promise<void>((resolve, reject) => {
      const queue = this.queues.get(model) ?? []
      queue.push({ resolve, rawReject: reject, settled: false })
      this.queues.set(model, queue)
    })
  }

  release(model: string): void {
    // 释放一个槽位，唤醒队列中的下一个等待者
    const queue = this.queues.get(model)
    if (queue?.length) {
      const next = queue.shift()!
      next.settled = true
      next.resolve()
    } else {
      const current = this.counts.get(model) ?? 0
      this.counts.set(model, Math.max(0, current - 1))
    }
  }
}

并发控制支持三层粒度的配置：

{
  "background_task": {
    "defaultConcurrency": 5,              // 全局默认
    "providerConcurrency": {
      "anthropic": 2,                     // Anthropic 最多 2 个
      "openai": 10                        // OpenAI 最多 10 个
    },
    "modelConcurrency": {
      "anthropic/claude-opus-4-6": 1      // Opus 最多 1 个
    }
  }
}

Parent Session 通知

当后台任务完成时，通知器会向父会话发送结果摘要。这实现了异步通知模式——主 Agent 不需要轮询后台任务的状态，而是在任务完成时被动收到通知。

15.6.2 Boulder 状态管理（features/boulder-state/）

Boulder State 是一个概念性的模块——它管理 Sisyphus 的"石头"，即当前正在执行的工作计划。

// oh-my-opencode/src/features/boulder-state/types.ts
export interface BoulderState {
  active_plan: string     // 活跃计划文件的绝对路径
  started_at: string      // 工作开始的 ISO 时间戳
  session_ids: string[]   // 参与该计划的所有会话 ID
  plan_name: string       // 从文件名派生的计划名称
  agent?: string          // 恢复时使用的 Agent 类型
}

export interface PlanProgress {
  total: number           // 总检查项数
  completed: number       // 已完成检查项数
  isComplete: boolean     // 是否全部完成
}

Boulder State 使石头的状态可以跨会话持久化。当用户关闭 OpenCode 再重新打开时，Sisyphus 可以恢复之前的工作计划，继续"推石头"。

15.6.3 Claude Tasks 系统（features/claude-tasks/）

Claude Tasks 是一套结构化的任务管理系统，比 OpenCode 内置的 Todo 系统更强大。它支持任务的创建、更新、列表查看和状态跟踪，并通过专门的 task 工具暴露给 Agent。

15.6.4 内置 Skill 系统（features/builtin-skills/）

oh-my-opencode 内置了 5 个 Skill：

builtin-skills/
├── git-master/       # Git 操作增强
├── frontend-ui-ux/   # 前端 UI/UX 设计指导
├── dev-browser/       # 浏览器自动化开发
├── agent-browser/     # Agent 浏览器
└── skills/            # Skill 注册和加载

每个 Skill 本质上是一段精心编写的 Markdown 文档，包含了某个领域的专家级指导。例如，git-master Skill 包含了 Git 操作的最佳实践、原子提交规范、rebase/squash 策略等。

这些 Skill 通过 load_skills 参数注入到子 Agent 中：

task(
  category="quick",
  load_skills=["git-master"],  // 注入 Git 专家知识
  prompt="Create an atomic commit for the auth changes"
)

15.6.5 内置 Command 系统（features/builtin-commands/）

oh-my-opencode 提供了一组内置的斜杠命令：

builtin-commands/
├── commands.ts        # 命令定义
├── templates/         # 命令模板
└── types.ts

典型的内置命令包括：

• /init-deep：初始化层级化的 AGENTS.md 知识库

• /ralph-loop：启动自驱动工作循环

• /ulw-loop：启动 ultrawork 模式循环

• /start-work：从 Prometheus 计划启动工作会话

• /refactor：智能重构命令

• /handoff：创建上下文交接摘要

15.6.6 tmux Sub-agent 管理（features/tmux-subagent/）

tmux 子 Agent 管理是 oh-my-opencode 的一个视觉化特性——当后台 Agent 运行时，它们会在 tmux 的分割窗格中实时显示，让用户可以直观地观察多个 Agent 的工作状态。

决策引擎

decision-engine.ts 是 tmux 管理的核心，它决定何时创建新窗格、如何分割空间、以及何时关闭窗格：

// oh-my-opencode/src/features/tmux-subagent/decision-engine.ts
export {
  calculateCapacity,     // 计算当前可容纳的窗格数
  computeGridPlan,       // 计算网格布局方案
  mapPaneToSlot,         // 将窗格映射到网格槽位
} from "./grid-planning"

export {
  canSplitPane,          // 检查是否可以分割窗格
  getBestSplitDirection, // 获取最佳分割方向
  findMinimalEvictions,  // 寻找最少驱逐方案
} from "./pane-split-availability"

export { findSpawnTarget } from "./spawn-target-finder"
export { decideCloseAction, decideSpawnActions } from "./spawn-action-decider"

网格布局规划

grid-planning.ts 将 tmux 窗口视为一个网格，自动计算最优的窗格分割方案：

┌────────────────────┬──────────┐
│                    │ Explore  │
│     Sisyphus       ├──────────┤
│     (主 Agent)      │ Librarian│
│                    ├──────────┤
│                    │ Oracle   │
└────────────────────┴──────────┘
     主窗格 (60%)      子窗格 (40%)

配置参数控制布局比例：

{
  "tmux": {
    "enabled": true,
    "layout": "main-vertical",
    "main_pane_size": 60,            // 主窗格占 60%
    "main_pane_min_width": 120,      // 最小宽度 120 列
    "agent_pane_min_width": 40       // 子窗格最小 40 列
  }
}

15.6.7 Skill MCP Manager（features/skill-mcp-manager/）

Skill MCP Manager 管理 Skill 文件中声明的内嵌 MCP 服务的生命周期。当一个 Skill 声明了需要某个 MCP 服务（如 Context7），Manager 负责启动该 MCP 进程、维持连接，并在不再需要时清理资源。

15.6.8 MCP OAuth（features/mcp-oauth/）

处理需要 OAuth 认证的 MCP 服务的认证流程。

15.6.9 Context Injector（features/context-injector/）

通用的上下文注入器，为其他模块提供向 Agent 消息中注入上下文信息的基础能力。

其他 Feature 模块

模块	功能
claude-code-agent-loader	加载 Claude Code 格式的 Agent 定义
claude-code-command-loader	加载 Claude Code 格式的 Command
claude-code-mcp-loader	加载 Claude Code 格式的 MCP 配置
claude-code-plugin-loader	加载 Claude Code 格式的 Plugin
claude-code-session-state	管理 Claude Code 兼容的会话状态
opencode-skill-loader	加载 OpenCode Skill 文件
run-continuation-state	管理 oh-my-opencode run 的续接状态
task-toast-manager	管理任务相关的 Toast 通知
tool-metadata-store	存储工具的元数据（描述、使用统计等）
hook-message-injector	向 Hook 消息中注入额外信息

衍生解释：什么是信号量（Semaphore）模式？

信号量是操作系统中经典的并发控制机制，由荷兰计算机科学家 Edsger Dijkstra 在 1965 年提出。它维护一个计数器，代表可用资源的数量。

在 oh-my-opencode 的 ConcurrencyManager 中：

• acquire() = P 操作（信号量减 1）：获取一个执行槽位。如果没有可用槽位，调用者会被放入等待队列

• release() = V 操作（信号量加 1）：释放一个槽位，并唤醒等待队列中的下一个任务

这种模式确保了同时运行的后台 Agent 数量不会超过配置的上限，防止 API 限流或资源耗尽。

与传统信号量不同，oh-my-opencode 的实现使用 JavaScript 的 Promise 来实现等待/唤醒，而不是操作系统级别的线程阻塞。这是因为 JavaScript 的运行时是单线程的，使用 Promise 队列比线程锁更加自然。

本节小结

oh-my-opencode 的 20 个 Feature 模块覆盖了从后台 Agent 管理到 tmux 可视化的完整功能谱系。最核心的模块包括：

1. 后台 Agent 系统（33 个文件）：完整的子会话创建、并发控制和结果通知

2. Boulder State：跨会话的工作计划状态持久化

3. tmux Sub-agent：将后台 Agent 的工作过程可视化在 tmux 分割窗格中

4. 内置 Skill（5 个）：注入领域专家知识

5. 内置 Command：预定义的斜杠命令

这些模块通过清晰的接口相互协作——例如后台 Agent 创建时通知 tmux 管理器分配窗格，任务完成时通过通知器向父会话汇报结果。