oh-my-opencode-slim 生命周期 Hooks 架构：缓存安全注入与多 Agent 任务编排的底层机制

• 人工智能
• AI Agent
• Agent 编排
• AI 技能

oh-my-opencode-slim 是一个面向 OpenCode 的"精简但精准调优"的多 Agent 插件套件，其全部运行时能力都挂在 OpenCode 插件体系的生命周期 Hooks 上：消息/提示词转换、工具执行拦截、事件路由、缓存安全注入以及运行时命令拦截。本文以仓库内src/hooks/codemap.md为核心骨架，结合源码实现逐层拆解这套 Hook 体系的设计、装配顺序与关键机制，读者读完可以掌握：Hook 工厂如何被组织与装配、如何在不动摇 provider 提示词缓存的前提下向出站消息注入内容、以及 orchestrator 与后台任务会话是如何通过这些 Hook 实现可恢复编排的。

hooks 模块的职责定位

src/hooks/是插件面向 OpenCode 宿主暴露的全部生命周期切入点的实现集合。根据 codemap 的职责声明，它覆盖五类工作：

• 消息/提示词转换（message/prompt transforms）：在请求真正发往模型之前改写消息内容；
• 工具执行拦截（tool-execute interception）：在tool.execute.before/tool.execute.after两个切点介入工具的校验、改写与事后处理；
• 事件处理（event handling）：消费event钩子传递的会话生命周期事件；
• 缓存安全注入（cache-safe prompt injection）：所有需要追加到出站 payload 的内容，必须经由统一的、保证 provider prompt-cache 前缀不被破坏的通道；
• 运行时命令拦截（runtime command interception）：为/deepwork、/reflect、/loop等运行时命令注册执行前处理。

架构上有一个关键约定：每一个 Hook 都是一个工厂函数（factory function），由index.ts桶式导出（barrel-export），返回 OpenCode 实际调用的 hook point 处理器。插件主入口 src/index.ts 只从桶出口导入，而不逐个文件导入，这保证了装配点唯一、依赖关系清晰。

核心架构：五个基础构件

工厂桶出口（Factory Barrel）

src/hooks/index.ts 是全部 Hook 工厂的唯一出口，导出内容覆盖完整生命周期：

• 工具侧：createApplyPatchHook、createSearchPathGuardHook、createAbsolutePathRescueHook、createToolLoopGuardHook
• 消息转换侧：createPhaseReminderHook、createPostFileToolNudgeHook、createFilterAvailableSkillsHook、createChatHeadersHook、createTaskSessionManagerHook
• 事件侧：createCacheMonitorHook、createOrchestratorWakeScheduler（并导出ORCHESTRATOR_WAKE_TEXT等醒神文本常量）
• 命令侧：createDeepworkCommandHook、createReflectCommandHook、createLoopCommandHook
• 兜底与恢复：createJsonErrorRecoveryHook、createAutoUpdateCheckerHook、ForegroundFallbackManager（模型回退管理器）
• 共享辅助件：SessionLifecycle、cache-safe-injection、chat-headers、command-hook-utils、image-hook、types

SessionLifecycle：会话删除协调器

src/hooks/session-lifecycle.ts 是会话生命周期协调器，解决了多 Hook 各自监听session.deleted导致的重复与混乱：

• 清理回调注册：有状态的 Hook 通过onSessionDeleted(callback)注册自己的清理回调，而不是各自实现session.deleted处理器；主入口在收到session.deleted事件时统一调用dispatchSessionDeleted(sessionId)分发（见 src/index.ts）。单个回调抛错会被捕获并记录日志，不影响其他回调执行。
• pending 会话信号通道：markPending(sessionId)/consumePending(sessionId)实现**消费一次（consume-once）**语义——consumePending是原子的，每次markPending只有唯一一个调用方能拿到true，用于避免多个消费者重复处理同一个"待处理"会话。

Cache-safe injection：唯一合法的注入通道

src/hooks/cache-safe-injection.ts 是整个模块最核心的机制。其动机写在该文件头部注释中：provider 的 prompt cache 是对渲染后请求（tools → system → messages）的精确字节前缀匹配，任何改写或重排早期对话内容的转换都会使首个变化字节之后的所有内容缓存失效，导致会话内后续每次请求都重新支付完整输入成本与延迟。

为此它提供两组互补 API：

• 确定性追加：appendTaggedSyntheticPart(message, spec)在既有消息的尾部追加一段带标签的合成文本 part。它要求内容必须是会话稳定输入的纯函数，这样下一轮重新执行转换时会产出相同位置、相同字节，天然安全。
• 易变内容区：stripTaggedContent(messages, metadataKey)+appendTrailingVolatileMessage(messages, info, spec)用于作业看板（job board）、状态块这类回合间会变化的内容：先剥掉所有此前注入的出现（并删除因此被清空的消息），再在 payload 最末尾重新追加一条合成尾消息。这样变动只发生在 prompt 尾部，早期前缀保持字节稳定。

支撑实现值得注意的细节：

• 标签机制：createTaggedSyntheticPart构造的 part 带有synthetic: true标志和metadata[metadataKey] = true标签，isTaggedPart/hasTaggedPart/isVolatileTaggedMessage据此识别与去重。规则被 cache-safety 属性测试强制：永不修改或重排早期消息、永不注入无标签 part、永不把时间戳或随机性放进尾部之前的注入内容。
• 缓存断点提示：SyntheticPartCacheHint（type: 'ephemeral' | 'persistent'，可选ttlSeconds）会被复制到创建的 part 上，供 anthropic-messages / google-vertex / bedrock-converse / openrouter 等作为手动 cache-breakpoint 放置；v1 调用方从不传它，因此 v1 payload 保持字节一致，而 v2 上下文桥通过runWithSyntheticPartCacheHintScope+setDefaultSyntheticPartCacheHint用AsyncLocalStorage隔离并发会话的默认提示——因为 v2 宿主并发服务不同会话的请求，模块级全局变量会被跨会话的 set/restore 相互污染。

Command hook helper 与消息类型

src/hooks/command-hook-utils.ts 提供registerCommandHook(opencodeConfig, commandName, template, description)，被 deepwork、reflect、loop 三个命令型 Hook 共享：向 OpenCode 配置中注册命令，若已存在则跳过并返回false。

src/hooks/types.ts 定义统一的消息结构：MessageInfo（role、agent、sessionID、id）、MessagePart（type、可选text、开放索引）、MessageWithParts（info+parts），以及供 foreground-fallback 重放使用的辅助函数：isReplayableUserMessage、partsFromReplayMessage——它同时兼容 v1 的{info, parts}形状和 v2 的{type: 'user', text}形状（OpenCode 1.18 起的 SDK HTTP API）。

Hook 分类总览

原 codemap 用一张表概括了六大类 Hook 与其挂载点，完整继承如下：

这张表的落地位置在 src/index.ts 返回的插件对象中：event处理器（L1435 起）、command.execute.before（L1767 起）、chat.headers（L1805）、chat.message（L1809 起）、experimental.chat.system.transform（L1942 起）、experimental.chat.messages.transform（L2007 起）、tool.execute.before（L1740 起）与tool.execute.after（L2084 起）。

消息处理管线：转换链的装配顺序

原 codemap 给出了消息处理流程，其关键点是experimental.chat.messages.transform中的组合顺序是刻意编排的。对照 src/index.ts 的实现，实际执行顺序为：

1. OpenCode 收到聊天消息；
2. 插件先做一轮显示名改写：对所有 user 消息的文本 part 执行rewriteDisplayNameMentions（把 agent 显示名提及规范化为运行时 agent 名）；
3. processImageAttachments处理图片附件：当 orchestrator 模型不支持图片输入时，将图片字节替换为"委托给 @observer"的文本提示，并在 60 秒内只弹一次 toast（见IMAGE_SKIPPED_DEBOUNCE_MS）；
4. task-session-manager 先执行：先稳定仍在运行的任务 tool part，再重水合（rehydrate）历史运行中的任务，最后通过 cache-safe helpers 注入 Background Job Board——这一步必须在提醒门控之前做，以修复会话映射；
5. 随后依次执行postFileToolNudge（文件工具后提示）、phaseReminder（阶段提醒）、filterAvailableSkills（按 agent 权限策略过滤可见技能）；
6. 最后由taskSessionManagerHook.injectBackgroundJobBoard在尾部注入作业看板；
7. 转换后的消息发往模型；chat.headers转发到 OpenCode 的 header 槽位（v1 宿主直接转发，v2 宿主由 adapter 桥接到session.hook("model.request")，详见 src/v2/codemap.md）；
8. 模型响应/事件被 cache monitor（遥测）与 orchestrator-wake scheduler（空闲唤醒计时）观察。

工具拦截链的顺序同样讲究。tool.execute.before按此顺序执行：applyPatch→absolutePathRescue→searchPathGuard→taskSessionManagerHook→toolLoopGuard。注释明确指出：路径救援必须先于搜索守卫，否则守卫会先拦截掉 grep/glob 在缺失路径上的调用，救援永远见不到可救的路径；而 tool-loop-guard 必须放在所有可能拒绝的 before 钩子之后，否则被拒绝的调用不会产生tool.execute.after事件，会在 pending 调用表里留下永不消费的条目。tool.execute.after则全部包了一层wrapPostToolHook做错误隔离：单个钩子失败只记日志，不阻塞其余钩子。

Hook 注册流程

Hook 的装配没有中央注册表，而是在调用点直接组合：

1. 插件初始化（src/index.ts 的OhMyOpenCodeLite工厂）；
2. 依次调用各个 Hook 工厂，得到 handler 对象；
3. src/index.ts把返回的 handler 直接接进插件对象的 hook 字段（tool.execute.before、event、chat.headers等）；
4. 有状态的 Hook 通过SessionLifecycle.onSessionDeleted注册清理回调；
5. OpenCode 在消息/工具/事件生命周期中按需调用这些 Hook。

值得注意的是config钩子：deepworkCommandHook.registerCommand、reflectCommandHook.registerCommand、loopCommandHook.registerCommand都通过registerCommandHook在 OpenCode 配置阶段注册各自命令，这正是"命令型 Hook"与配置装配结合的体现。

事件观察（event hook）

事件钩子是插件感知会话状态的主要通道，src/index.ts 的扇出顺序清晰可读：

• token 流增量事件直接短路：message.part.delta、session.next.text.delta、session.next.reasoning.delta在每个推理/文本 chunk 都会触发，插件没有对应工作，直接return，避免无谓扇出；
• cache monitor观察完成的 assistant 消息中的tokens.cache.read/write，记录 prompt-cache bust/plateau 警告（纯观察，fail open）；
• task-session-manager将created、idle、busy、error、deleted、server.instance.disposed等会话生命周期事件路由给其 reconciler；
• orchestrator-wake scheduler追踪连续父会话空闲并触发周期唤醒提示（受hasInputWait与 continuation-model 接缝门控）；
• TUI 状态簿记：session.status的 busy/retry/idle/completed/stopped/error/failed、message.updated的 provider/model、session.created的父子链接都被记录用于侧边栏活动展示与模型继承解析；
• foreground-fallback消费message.updated/session.error/session.status检测限流与错误，触发运行时模型回退；
• session.deleted事件统一触发sessionLifecycle.dispatchSessionDeleted，随后清理会话元数据。

dispose钩子也值得一提：它依次释放 terminal gate、取消 foreground fallback 的初始延迟定时器、向 task-session-manager 与 orchestrator-wake 广播server.instance.disposed、调用clearAllWakeSessions()清空进程级 wake 门（保证opencode reload后新一代插件不会继承旧代的"两次唤醒无进展上限"）、释放 admission runtime 租约。

缓存安全注入：从实现到验证闭环

缓存安全不是口号，仓库为其构建了四层互补验证（见 docs/cache-verification.md）：

• 持续 CI 测试（bun test）：src/hooks/cache-safety.property.test.ts 把增长中的对话反复经过真实转换管线（镜像src/index.ts的组合顺序），断言回合间字节前缀稳定性、易变内容隔离到带标签尾消息、在墙钟/随机性变化下的确定性，并有一个 drift guard——当src/index.ts增删或重排转换步骤而测试未同步更新时直接失败；src/hooks/cache-payload.snapshot.test.ts 对插件注入的每个 prompt 表面（phase reminder、orchestrator 系统提示、规范转换 payload）做黄金快照；src/cache-safety-tripwire.test.ts 扫描 prompt 组装目录，检索Date.now、Math.random、randomUUID、performance.now等易变输入模式。
• 离线确定性载荷验证（bun run verify:cache-stability）：需要预先精确提供opencode-ai@1.18.2的二进制路径（OPENCODE_BIN=/absolute/path/to/node_modules/.bin/opencode），在本地捕获 provider 上断言四个主模型请求、system/tool/options 投影稳定、对话输入追加式前缀稳定等。
• 在线缓存冒烟（bun run cache:smoke）：一键启动真实opencode serve，运行脚本化场景（plain、tools、nudge、todos、long、board、board-churn、running-lane、agents），读取 assistant 消息的tokens.cache.read/write并给出判定；检测 SUSPECT（非首请求、输入 ≥4096 token、读到 0 缓存）与 plateau（cache-read冻结在相同非零值 ≥3 次且累计 ≥6144 未缓存输入）两种失败签名。退出码 0/1/2/3 分别表示正常/检测到失效/无结论/设置错误。
• 运行时缓存监控：src/hooks/cache-monitor/index.ts 是纯观察型的现场安全网。它订阅message.updated，只解析完成态消息（time.completed存在），对每会话维护状态并输出三类警告：

状态有界：最多跟踪 256 个会话、每会话 512 条消息 ID，超出即淘汰最旧项。

集成全景：消费者、子目录与依赖

消费者

• 主插件（src/index.ts）：从桶出口导入全部工厂并装配 handler；
• task-session-manager：所有 prompt 注入都依赖cache-safe-injection.ts，删除协调依赖session-lifecycle.ts；
• orchestrator-wake：以 task-session-manager 的hasInputWait与 continuation-model 接缝为门控；
• foreground-fallback：使用 src/hooks/types.ts 的重放辅助（isReplayableUserMessage、partsFromReplayMessage），并把可重试/延迟错误上报给 task-session-manager 的事件路由器。

子目录职责（继承自原 codemap 并补充源码信息）

依赖

• OpenCode SDK：MessageWithParts、MessageInfo与 Hook 签名类型；
• Node.js：fs、crypto（图片附件、带标签 part 哈希）；
• Utils：src/utils/ 下的logger、guards、任务解析、internal-initiator parts。

错误处理与性能考量

原 codemap 的最后两个小节总结了工程取舍，直接继承并展开：

错误处理三原则：

• Hook 全部 best-effort：文件系统/转换失败只记日志，Hook 继续处理剩余消息；
• cache monitor 对任何意外事件形状 fail open，遥测绝不阻断事件处理；
• orchestrator-wake scheduler 在 SDK 错误时选择抑制而不是重试风暴。

性能考量：

• 缓存安全优先：所有注入必须走 tagged/volatile 辅助函数，以保留 provider prompt-cache 前缀（对应backgroundJobs.strategy的两种模式——"latest"替换先前看板消息，"checkpoint-compatible"保留它们只追加变化的看板快照，见 src/config/schema.ts）；
• 防抖清理：图片清理与运行时状态对账跑在定时器上而非每个事件；
• 有界状态：cache monitor 与 wake gate 都设定了跟踪会话上限（如 cache monitor 的 256 会话 / 512 消息），idle 对账用每会话 token 使过期定时器失效。

小结

src/hooks/是 oh-my-opencode-slim 全部运行时行为的中枢。它用"工厂桶出口 + 调用点组合"的组织方式保持装配透明，用 SessionLifecycle 统一会话清理语义，用 cache-safe-injection 把"向出站 payload 加内容"收敛为唯一且经过属性测试、快照测试与线上监控三重保障的通道，再用精心编排的转换链与工具拦截链支撑起多 Agent 编排、后台任务看板与模型回退等上层能力。理解这套 Hook 架构，是深入这个插件其余一切模块（agents、task-session-manager、orchestrator-wake、foreground-fallback）的前提。

• 人工智能
• AI Agent
• Agent 编排
• AI 技能