15.5 Hook 系统（53 个 Hook 详解）

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

---

oh-my-opencode 的 Hook 系统是其最精密的子系统之一。53 个 Hook 构成了一张密集的"防护网"，覆盖了 Agent 行为的方方面面——从上下文窗口管理到错误恢复，从任务持续执行到 Agent 行为矫正。

15.5.1 Hook 分类

53 个 Hook 可以按功能分为 8 大类：

上下文注入类（4 个）

Hook	功能
directory-agents-injector	将项目 AGENTS.md 文件内容注入到 Agent 消息中
directory-readme-injector	将项目 README.md 注入到 Agent 上下文
rules-injector	注入 .opencode/rules/ 目录下的规则文件
compaction-context-injector	在上下文压缩后注入关键上下文（防止压缩导致信息丢失）

这些 Hook 的核心思想是：自动向 Agent 提供项目特定的上下文信息，而不需要用户每次手动粘贴。

错误恢复类（4 个）

Hook	功能
edit-error-recovery	编辑工具失败时注入恢复指令
json-error-recovery	JSON 解析错误时注入修正指令
anthropic-context-window-limit-recovery	Anthropic API 上下文窗口溢出时自动恢复
session-recovery	会话异常中断时的恢复机制

Agent 管理类（3 个）

Hook	功能
agent-usage-reminder	提醒 Agent 正确使用委托协议和工具
category-skill-reminder	提醒 Agent 在委托时选择正确的 Category 和 Skill
unstable-agent-babysitter	监控不稳定的子 Agent，在超时或异常时介入

会话管理类（4 个）

Hook	功能
context-window-monitor	监控上下文窗口使用率，发出警告
preemptive-compaction	在上下文窗口接近满时，先发制人地触发压缩
compaction-todo-preserver	压缩时保留 Todo 状态
session-notification	会话状态变更通知

输出控制类（3 个）

Hook	功能
tool-output-truncator	截断过长的工具输出以节省 Token
thinking-block-validator	验证思考块格式的正确性
think-mode	控制扩展思考模式的启用/禁用

任务管理类（4 个）

Hook	功能
todo-continuation-enforcer	强制 Agent 继续执行未完成的 Todo 任务
task-reminder	提醒 Agent 当前任务的状态和要求
task-resume-info	提供任务恢复所需的上下文信息
tasks-todowrite-disabler	在特定场景下禁用 TodoWrite 工具

自动化类（4 个）

Hook	功能
auto-slash-command	自动检测并执行斜杠命令
ralph-loop	自我驱动的持续工作循环
start-work	从 Prometheus 计划启动工作流
stop-continuation-guard	防止意外停止续接机制

环境适配类（2 个）

Hook	功能
non-interactive-env	非交互式环境（CI/CD）的适配
interactive-bash-session	交互式 Bash 会话的管理

其他类

Hook	功能
keyword-detector	检测用户消息中的关键词（如 "ultrawork"）
comment-checker	检查 AI 生成代码中的过多注释
hashline-read-enhancer	为 Read 工具的输出附加行号哈希
write-existing-file-guard	防止误写已存在的文件
question-label-truncator	截断过长的问题标签
background-notification	后台任务完成通知
delegate-task-retry	委托任务失败时的重试逻辑
anthropic-effort	Anthropic API effort 等级注入
prometheus-md-only	限制 Prometheus 只编辑 .md 文件
sisyphus-junior-notepad	Sisyphus Junior 的笔记本功能
atlas	Atlas Agent 的特殊处理
claude-code-hooks	Claude Code 兼容层的 Hook
auto-update-checker	自动更新检查
startup-toast	启动提示
empty-task-response-detector	检测空的任务响应

15.5.2 核心 Hook 实现剖析

preemptive-compaction：先发制人的上下文压缩

这是 oh-my-opencode 中最关键的 Hook 之一。它解决了一个根本性问题：当 Agent 的上下文窗口快要满时，如果不及时压缩，下一次 API 调用就会失败。

// oh-my-opencode/src/hooks/preemptive-compaction.ts
const PREEMPTIVE_COMPACTION_THRESHOLD = 0.78  // 78% 使用率时触发

export function createPreemptiveCompactionHook(ctx, modelCacheState) {
  const compactionInProgress = new Set<string>()  // 正在压缩的会话
  const compactedSessions = new Set<string>()      // 已压缩的会话
  const tokenCache = new Map<string, CachedCompactionState>()  // Token 使用缓存

  // Hook 点：每次工具执行完后检查
  const toolExecuteAfter = async (input, output) => {
    const { sessionID } = input
    if (compactedSessions.has(sessionID) || compactionInProgress.has(sessionID)) return

    const cached = tokenCache.get(sessionID)
    if (!cached) return

    // 计算实际上下文限制（考虑 Anthropic 100万上下文特殊情况）
    const actualLimit = isAnthropicProvider(cached.providerID)
      ? getAnthropicActualLimit(modelCacheState)
      : DEFAULT_ACTUAL_LIMIT

    // 计算使用率
    const totalInputTokens = (cached.tokens.input ?? 0) + (cached.tokens.cache?.read ?? 0)
    const usageRatio = totalInputTokens / actualLimit

    // 未达阈值则返回
    if (usageRatio < PREEMPTIVE_COMPACTION_THRESHOLD) return

    // 触发压缩
    compactionInProgress.add(sessionID)
    try {
      await ctx.client.session.summarize({
        path: { id: sessionID },
        body: { providerID: cached.providerID, modelID: cached.modelID, auto: true },
      })
      compactedSessions.add(sessionID)
    } finally {
      compactionInProgress.delete(sessionID)
    }
  }

  // 通过事件监听更新 Token 缓存
  const eventHandler = async ({ event }) => {
    if (event.type === "message.updated") {
      const info = event.properties?.info
      if (info?.role === "assistant" && info?.finish && info?.tokens) {
        tokenCache.set(info.sessionID, {
          providerID: info.providerID,
          modelID: info.modelID,
          tokens: info.tokens,
        })
      }
    }
  }

  return { "tool.execute.after": toolExecuteAfter, event: eventHandler }
}

工作原理：

1. Token 缓存更新：通过 event Hook 监听 message.updated 事件，每当 LLM 完成一次响应时，缓存该会话的 Token 使用量

2. 阈值检查：在每次工具执行完成后（tool.execute.after），检查当前会话的 Token 使用率是否超过 78%

3. 触发压缩：如果超过阈值，调用 OpenCode SDK 的 session.summarize() 方法，让 LLM 将对话历史压缩为一段摘要

4. 去重保护：使用 compactionInProgress 和 compactedSessions 两个 Set 防止重复压缩

context-window-monitor：上下文窗口监控

与先发制人压缩不同，上下文窗口监控器的作用是告知 Agent 当前的上下文使用状态：

// oh-my-opencode/src/hooks/context-window-monitor.ts
const CONTEXT_WARNING_THRESHOLD = 0.70  // 70% 使用率时警告

export function createContextWindowMonitorHook(ctx, modelCacheState) {
  const remindedSessions = new Set<string>()

  const toolExecuteAfter = async (input, output) => {
    if (remindedSessions.has(sessionID)) return

    const cached = tokenCache.get(sessionID)
    if (!cached || !isAnthropicProvider(cached.providerID)) return

    const usageRatio = totalInputTokens / getAnthropicActualLimit(modelCacheState)
    if (usageRatio < CONTEXT_WARNING_THRESHOLD) return

    remindedSessions.add(sessionID)

    // 在工具输出中附加上下文状态提醒
    output.output += `\n\n[SYSTEM REMINDER - CONTEXT WINDOW MONITOR]
You are using Anthropic Claude with 1M context window.
You have plenty of context remaining - do NOT rush or skip tasks.
[Context Status: ${usedPct}% used, ${remainingPct}% remaining]`
  }
}

注意两个 Hook 的阈值不同：监控器在 70% 时发出警告，压缩器在 78% 时触发压缩。这个 8% 的缓冲区给了 Agent 一个"预警期"——先知道上下文正在变满，然后在真正触发压缩之前有机会自行减少上下文消耗。

ralph-loop：自我驱动的持续工作循环

Ralph Loop 是 oh-my-opencode 最具标志性的特性。它实现了一个自我驱动的工作循环——Agent 完成一次响应后，如果任务未完成，系统自动发送一条继续提示，让 Agent 继续工作。

// oh-my-opencode/src/hooks/ralph-loop/types.ts
export interface RalphLoopState {
  active: boolean           // 循环是否激活
  iteration: number         // 当前迭代次数
  max_iterations: number    // 最大迭代次数
  completion_promise: string // 完成承诺（用于检测任务完成）
  started_at: string        // 开始时间
  prompt: string            // 用户原始提示
  session_id?: string       // 会话 ID
  ultrawork?: boolean       // 是否为 ultrawork 模式
}

Ralph Loop 的架构由 6 个子模块组成：

ralph-loop/
├── ralph-loop-hook.ts          # Hook 入口
├── ralph-loop-event-handler.ts # 事件处理器
├── loop-state-controller.ts    # 循环状态管理
├── loop-session-recovery.ts    # 会话恢复
├── continuation-prompt-builder.ts  # 继续提示构建
├── continuation-prompt-injector.ts # 继续提示注入
├── completion-promise-detector.ts  # 完成检测
├── storage.ts                  # 状态持久化
├── with-timeout.ts             # 超时处理
└── types.ts                    # 类型定义

工作流程：

1. 用户输入 "ultrawork" 或执行 /ralph-loop 命令

2. startLoop() 激活循环，记录初始状态

3. Agent 开始执行任务

4. 当 Agent 完成一次响应（session.idle 事件）

5. completion-promise-detector 检查响应是否包含"完成承诺"

6. 如果未完成，continuation-prompt-builder 构建继续提示

7. 通过 API 发送继续提示，Agent 继续工作

8. 重复 4-7，直到任务完成或达到最大迭代次数

todo-continuation-enforcer：Todo 任务持续执行保障

这是"让 Sisyphus 继续推石头"的核心机制。当 Agent 在有未完成 Todo 的情况下停止工作时，这个 Hook 会强制 Agent 继续。

// oh-my-opencode/src/hooks/todo-continuation-enforcer/index.ts
export function createTodoContinuationEnforcer(ctx, options) {
  const sessionStateStore = createSessionStateStore()

  const handler = createTodoContinuationHandler({
    ctx,
    sessionStateStore,
    backgroundManager,
    skipAgents,                    // 某些 Agent 不强制续接（如 Explore）
    isContinuationStopped,         // 检查是否被用户手动停止
  })

  return {
    handler,
    markRecovering,              // 标记会话正在恢复中（暂停强制续接）
    markRecoveryComplete,        // 标记恢复完成
    cancelAllCountdowns,         // 取消所有倒计时
  }
}

工作原理：

1. 当 Agent 的 Session 进入 idle 状态时

2. Hook 检查该 Session 是否有未完成的 Todo 项

3. 如果有，启动一个倒计时

4. 倒计时结束后，注入一条系统提醒消息：

[SYSTEM REMINDER - TODO CONTINUATION]

You have incomplete todos. Do NOT stop here.
Continue working on the next pending todo item.

1. 这条消息触发 Agent 继续执行

edit-error-recovery：编辑失败自动恢复

这个 Hook 简洁但高效——当 Edit 工具失败时，在输出中注入恢复指令：

// oh-my-opencode/src/hooks/edit-error-recovery/hook.ts
const EDIT_ERROR_PATTERNS = [
  "oldString and newString must be different",
  "oldString not found",
  "oldString found multiple times",
]

const EDIT_ERROR_REMINDER = `
[EDIT ERROR - IMMEDIATE ACTION REQUIRED]

You made an Edit mistake. STOP and do this NOW:
1. READ the file immediately to see its ACTUAL current state
2. VERIFY what the content really looks like (your assumption was wrong)
3. APOLOGIZE briefly to the user for the error
4. CONTINUE with corrected action based on the real file content
`

export function createEditErrorRecoveryHook(ctx) {
  return {
    "tool.execute.after": async (input, output) => {
      if (input.tool.toLowerCase() !== "edit") return

      const hasEditError = EDIT_ERROR_PATTERNS.some((pattern) =>
        output.output.toLowerCase().includes(pattern.toLowerCase())
      )

      if (hasEditError) {
        output.output += `\n${EDIT_ERROR_REMINDER}`
      }
    },
  }
}

这个 Hook 解决了 LLM 的一个常见问题：编辑失败后的"盲目重试"。没有这个 Hook 时，LLM 在编辑失败后可能会尝试相同的操作，导致重复失败。通过注入"先重新读取文件再尝试"的指令，强制 LLM 更新对文件状态的认知。

unstable-agent-babysitter：不稳定子 Agent 保姆监控

这是一个"监工"级别的 Hook——它监控后台运行的子 Agent，如果子 Agent 长时间没有活动或产出空响应，保姆 Hook 会介入：

// oh-my-opencode/src/hooks/unstable-agent-babysitter/unstable-agent-babysitter-hook.ts
const DEFAULT_TIMEOUT_MS = 120000   // 2 分钟超时
const COOLDOWN_MS = 5 * 60 * 1000  // 5 分钟冷却期

export function createBabysitterHook(ctx, options) {
  // 当后台任务完成时检查其响应质量
  // 如果响应为空或无意义，发送提醒给主 Agent
  // ...
}

保姆 Hook 的工作原理：

1. 监听后台任务的完成事件

2. 获取子 Agent 的最后几条消息

3. 分析响应是否"不稳定"（空响应、超时、异常终止）

4. 如果不稳定，构建一条提醒消息发送给主 Session 的 Agent

5. 进入冷却期（5 分钟内不再重复提醒）

衍生解释：什么是"防御式编程"？

防御式编程（Defensive Programming）是一种编程范式，其核心理念是：假设一切都可能出错，并为每种可能的错误预先准备恢复策略。

在传统软件工程中，防御式编程体现为：输入校验、异常处理、边界检查、错误日志等。在 AI Agent 系统中，防御式编程有了新的含义：

• Agent 可能"忘记"正在做什么 → Todo Continuation Enforcer 强制继续

• Agent 可能在错误的假设下编辑文件 → Edit Error Recovery 强制重新读取

• Agent 可能耗尽上下文窗口 → Preemptive Compaction 先发制人压缩

• 子 Agent 可能超时或返回空响应 → Unstable Agent Babysitter 介入

• Agent 可能添加过多注释 → Comment Checker 检测并警告

oh-my-opencode 的 53 个 Hook 本质上就是一套针对 AI Agent 行为的防御式编程框架。每个 Hook 都假设某种特定的失败模式会发生，并预先定义了恢复策略。

这也是 oh-my-opencode 命名的哲学基础——西西弗斯的石头会滚回来，但他会继续推。Agent 的任务会失败，但 Hook 系统确保它会恢复并继续。

本节小结

oh-my-opencode 的 53 个 Hook 构成了一个密集的行为控制和故障恢复网络。它们按功能分为 8 大类，覆盖了上下文管理、错误恢复、任务持续执行、Agent 行为监控等各个方面。

六个核心 Hook 的设计思路：

1. Preemptive Compaction（78% 阈值）：在上下文窗口溢出之前主动压缩，比被动等待错误更可靠

2. Context Window Monitor（70% 阈值）：比压缩更早发出警告，给 Agent 预警期

3. Ralph Loop：通过"响应 → 检测 → 继续提示 → 响应"的循环，实现自驱动的持续执行

4. Todo Continuation Enforcer：在 Agent 空闲时检查未完成任务，强制继续

5. Edit Error Recovery：拦截编辑错误，注入"先读取再重试"的恢复指令

6. Unstable Agent Babysitter：监控子 Agent 的健康状态，在异常时介入