omo-opencode TuiStateMirror 心跳生命周期与插件销毁接线：一次 RED-GREEN 修复的源码级拆解-开发者社区

omo-opencode TuiStateMirror 心跳生命周期与插件销毁接线：一次 RED-GREEN 修复的源码级拆解

【免费下载链接】oh-my-openagentOmO: Just type "mass ulw" keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent

本文围绕 oh-my-openagent 仓库中packages/omo-opencode的 TUI Sidebar 快照镜像机制，以.omo/evidence/20260831-mem-tui-mirror/REPORT.md记录的一次真实 RED-GREEN 修复为主线，深入讲解TuiStateMirror的心跳（heartbeat）生命周期、unref句柄释放、插件dispose()幂等销毁以及生产装配接线。读完本文，你将掌握这套"插件进程写镜像、TUI 进程读镜像"双进程协作架构的核心原理，并能在自己的插件项目中复现同样的生命周期与测试保障实践。

背景：TUI Sidebar 的"双进程镜像"架构

omo-opencode 的 TUI 侧边栏（Sidebar）并不与插件进程共享内存，两者之间唯一的通道是一份落盘的 JSON 镜像文件。依据 features/tui-sidebar/AGENTS.md 中的数据流描述：

plugin side: events/heartbeat → TuiStateMirror.flush() → buildTuiRuntimeSnapshot() → writeMirror() (atomic JSON) TUI side: 1s poll → readMirror() → derivers → computeView() → viewKey diff → buildViewNodes() → sidebar_content

插件侧（写入者）：TuiStateMirror负责把运行时的会话状态、后台任务（job board）、ULW 循环（loop）状态聚合为一份TuiRuntimeSnapshot，经 250ms 防抖和原子写落盘；
TUI 侧（读取者）：以 1s 周期轮询镜像文件，通过派生器（derivers）计算视图，仅当viewKey变化时才重渲染。

这份镜像机制由开关tui.sidebar.enabled控制，默认开启（除非显式设为false），见 config/schema/tui.ts 中TuiSidebarConfigSchema的enabled: z.boolean().default(true)。写入侧的类实例化发生在 create-managers.ts：当pluginConfig.tui?.sidebar?.enabled !== false时构造TuiStateMirror并立即start()。

TuiStateMirror：写入侧的核心类

TuiStateMirror定义在 mirror-manager.ts，其构造函数通过依赖注入接收client（会话客户端）、projectDir（项目目录）、backgroundManager（后台任务快照提供者），以及可选的getStatuses、sessionAgentResolver、reportFlushError。类的三个公开生命周期方法是flush()、start()、stop()。

flush()：250ms 防抖 + 单飞行中写

flush()的核心职责是把一次快照写入请求合并进防抖窗口（WRITE_DEBOUNCE_MS = 250，定义于 constants.ts）：

若已有pendingFlush，直接返回该 Promise，避免叠加；
否则调度一个 250ms 的setTimeout，到期后调用私有方法runFlush()；
runFlush()内部维护inFlightFlush，保证同一时刻只有一个快照构建在飞行中，后续请求复用同一 Promise（对应测试用例#given concurrent flush calls #when the first build is in flight #then it does not double-build）。

实际的写快照逻辑writeSnapshotNoThrow()遵循"失败即降级、绝不抛出"的约定：构建快照后若已stopped则直接返回；任何Error都会被捕获并交给reportFlushError（默认打印[tui-sidebar] mirror flush failed日志），而不是让心跳/事件循环崩溃。

start()：2s 心跳 + unref 释放

start()是本次修复的核心对象：

start(): void { this.stopped = false if (this.heartbeatID !== null) { return } this.heartbeatID = setInterval(() => { void this.flush() }, HEARTBEAT_MS) this.heartbeatID.unref?.() }

HEARTBEAT_MS = 2_000（2s）：即使没有任何会话事件，心跳也会周期性地触发flush()，保证镜像文件始终"新鲜"；
if (this.heartbeatID !== null) return：重复调用start()不会创建第二个 interval，具备幂等性；
this.heartbeatID.unref?.()：这就是本次 RED-GREEN 修复引入的关键一行。setInterval返回的定时器句柄默认会让 Node.js/Bun 事件循环保持活跃，若插件进程其余工作已结束，一个仅用于刷镜像的心跳会"卡住"进程不退出；unref()将该句柄从事件循环的活跃集合中摘除，进程可以在没有其他待处理工作时正常退出，同时心跳在进程存活期间仍然持续触发。

stop()：幂等清理

stop(): void { this.stopped = true if (this.heartbeatID !== null) { clearInterval(this.heartbeatID) this.heartbeatID = null } if (this.debounceID !== null) { clearTimeout(this.debounceID) this.debounceID = null } if (this.resolvePendingFlush) { this.resolvePendingFlush() this.resolvePendingFlush = null } this.pendingFlush = null }

stop()一次性完成四件事：置stopped = true、清除心跳 interval、清除防抖 timeout、resolve 挂起的 flush。挂起 flush 被 resolve 后，等待方不会永久悬挂；而writeSnapshotNoThrow()中if (this.stopped) return的二次检查，则确保停止后不再产生任何镜像写入。

RED 阶段：heartbeat 句柄未 unref 导致测试失败

REPORT 文档记录的第一次 RED 验证命令为：

bun /tmp/omo-mac-test.mjs fix/mem-tui-mirror-heartbeat -- packages/omo-opencode/src/features/tui-sidebar

运行结果为exit 1; 57 pass, 1 fail，失败用例是：

error: expect(received).toHaveBeenCalledTimes(expected) Expected number of calls: 1 Received number of calls: 0 (fail) TuiStateMirror > #given a started mirror #when started #then heartbeat handle is unref'd

这个断言对应 mirror-manager.test.ts 中的用例：测试用 fake timers 接管globalThis.setInterval，使其返回一个带unrefspy 的句柄对象，随后调用mirror.start()，断言unref被调用恰好 1 次。修复前start()只创建 interval 却不调用unref，因此 spy 调用次数为 0，测试红灯。

该用例的价值在于把"心跳不应阻止进程退出"这一运行时行为固化为可回归的契约——任何后续改动只要遗漏unref，就会立即被该测试拦截。

GREEN 阶段：两处核心变更

REPORT 文档将 GREEN 阶段的变更总结为两条：

Heartbeat interval callsunref?.()after creation：即start()中this.heartbeatID.unref?.()。使用可选调用（?.）意味着即使运行环境（如某些嵌入式实现）不提供unref方法，也不至于抛错，保持最大兼容性。
Plugin disposal accepts an optional TUI mirror and callsstop()inside the idempotent disposal promise：即createPluginDispose接受可选的tuiStateMirror参数并在幂等销毁 Promise 内调用stop()。

GREEN 验证命令扩展了测试范围：

bun /tmp/omo-mac-test.mjs fix/mem-tui-mirror-heartbeat -- packages/omo-opencode/src/features/tui-sidebar packages/omo-opencode/src/plugin-dispose.test.ts

结果exit 0，65 pass, 0 fail, 124 expect() calls，新增通过的核心用例包括：

TuiStateMirror > #given a started mirror #when started #then heartbeat handle is unref'd（本次修复的直接回归测试）；
createPluginDispose > #given plugin with a TUI mirror #when dispose() is called #then the mirror is stopped（销毁接线契约测试）。

插件销毁的幂等实现：plugin-dispose.ts

createPluginDispose定义在 plugin-dispose.ts，它的设计要点在于幂等：模块级disposePromise首次调用后即被赋值，后续任何再次调用都直接await同一 Promise 并返回，不会重复执行清理。清理顺序为：

tuiStateMirror?.stop()（本次新增，可选项调用）；
await backgroundManager.shutdown()；
await skillMcpManager.disconnectAll()；
disposeHooks()。

每一段清理都被独立try/catch包裹并记录日志，保证"某个清理项抛错不会阻断其余清理项"，对应 plugin-dispose.test.ts 中#given backgroundManager.shutdown() throws #when dispose() is called #then skillMcpManager.disconnectAll() and disposeHooks() are still called等容错用例。对应的镜像停止测试用例#given plugin with a TUI mirror #when dispose() is called #then the mirror is stopped则验证了传入tuiStateMirror后stop()恰好被调用一次。

生产装配接线修正

第一轮 GREEN 只是让模块级测试通过；真正暴露问题的是生产装配层。REPORT 文档记录的第二次 RED 命令：

bun /tmp/omo-mac-test.mjs fix/mem-tui-mirror-heartbeat -- packages/omo-opencode/src/features/tui-sidebar packages/omo-opencode/src/plugin-dispose.test.ts packages/omo-opencode/src/testing

失败用例为：

(fail) createPluginModule() > #given bundled security skills are enabled #then dispose stops the started TUI state mirror 103 pass 1 fail

这说明：虽然createPluginDispose支持了可选的tuiStateMirror，但生产调用链createPluginModule还没有把managers.tuiStateMirror传递进去，集成层面"dispose 会停止镜像"的契约并未兑现。接线修正位于 create-plugin-module.ts：

const dispose = createPluginDispose({ backgroundManager: managers.backgroundManager, skillMcpManager: managers.skillMcpManager, tuiStateMirror: managers.tuiStateMirror, disposeHooks: hooks.disposeHooks, })

接线完成后重跑同一命令，结果104 pass, 0 fail, 193 expect() calls, Ran 104 tests across 14 files。这段流程演示了一个典型的三层验证路径：单元契约测试（RED）→ 模块实现修复（GREEN）→ 生产装配接线验证（再 RED → 再 GREEN），正是 TDD 中"测试驱动接线"的完整闭环。

同时，create-managers.test.ts 也从装配层覆盖了镜像生命周期：默认配置下createManagers会构造并start()镜像，backgroundManager.shutdown()后镜像stop()被调用；而tui: { sidebar: { enabled: false } }时镜像根本不会被构造（tuiStateMirror为undefined），从源头避免无谓的心跳与写盘。

写入侧的配套加固：原子写、0600 权限与 schema 版本化

镜像的生命周期不止于内存中的定时器管理，落盘路径同样有严格的工程约束：

原子写：write-file-atomically.ts 先写临时文件、fsync后rename覆盖，并处理 Windows 上 EPERM/EACCES 的重试路径，避免读者读到半截 JSON；
权限 0600：mirror-io.ts 的writeMirror以{ mode: 0o600 }写入，镜像文件仅属主可读写；
读侧三重校验：readMirror依次检查 JSON 可解析、schema 匹配、canonicalProjectDir与当前项目一致、updatedAt未超过STALE_MS = 6_000（6s 过期），任何一项不满足都返回null走降级路径；
schema 版本化：snapshot-schema.ts 用 Zod 定义TuiRuntimeSnapshotSchema，version固定为字面量MIRROR_SCHEMA_VERSION = 1；快照形状变更必须升版本号，否则旧读者会静默丢弃文件；
存储路径隔离：mirror-path.ts 将镜像放在XDG_DATA_HOME（缺省~/.local/share）下的opencode/storage/oh-my-openagent/tui-state目录，文件名取项目目录 canonical realpath 的 SHA-1 前 16 位，天然实现多项目隔离。

快照内容由 snapshot-builder.ts 构建：activeAgents只保留busy | retry | running三种活跃状态并通过sessionAgentResolver解析为 agent 名称；jobBoard来自BackgroundManager.getTasksSnapshot()；loop来自 ULW 循环读取器，且redactLoopText会把activeGoal文本置为null——隐私约束（渲染侧显示 "private"）被内置在写入路径中。

读取侧配套：1s 轮询与 viewKey diff

TUI 侧的生命周期与写入侧遥相呼应：POLL_INTERVAL_MS = 1_000（1s）轮询readMirror，但不会在每次轮询都重渲染——computeView先根据 agents/jobs/loop 是否活跃判定视图种类（active / broken / idle），compute-view.ts 的viewKey再把视图序列化为稳定字符串（元素顺序规范化），只有 key 变化才触发重绘。derivers.ts还以JOB_STATUS_PRIORITY（running > pending > interrupt > error > cancelled > completed）对任务排序，并分别以MAX_AGENTS、MAX_JOBS = 12封顶，防止侧边栏无限膨胀。

这也解释了为什么写入侧必须保证镜像"新鲜"：写入侧 2s 心跳 + 250ms 防抖的节奏，恰好与读取侧 1s 轮询 + 6s 过期阈值构成协调的供需关系——心跳停摆会导致镜像超过 6s 未更新而被读取侧判为过期，侧边栏回退到本地配置派生的 idle 兜底视图。

测试矩阵与回归保障

本次修复最终沉淀的测试矩阵（均以 bun test 运行）可以归纳为四层：

层级	文件	覆盖点
镜像单元	mirror-manager.test.ts	flush 可读镜像、心跳无事件也写盘、heartbeat 句柄 unref、stop 后无写入、flush 错误上报、并发去重
销毁单元	plugin-dispose.test.ts	各清理项按序调用、mirror stop 被调用、重复 dispose 幂等、单项异常不阻断其余
装配层	create-managers.test.ts	默认启动镜像、关闭开关不构造、shutdown 联动 stop
集成层	create-plugin-module.test.ts	`createPluginModule()`生成的`dispose`钩子会停止已启动的 TUI 镜像

REPORT 文档中的关键数字（57→65→103→104 pass）串起来正是这条从"单点契约"到"生产接线"逐层收紧的验证链条：先修复TuiStateMirror自身的契约，再补createPluginDispose的接线契约，最后验证createPluginModule的生产调用链，每一层红灯都对应一层真实的行为缺口。

工程启示与约束总结

从这次 heartbeat 生命周期修复中，可以提炼出几条可复用的工程约束：

定时器必须考虑进程退出语义：任何仅作为"后台刷新"用途的setInterval，都应显式unref()，否则会成为进程退出的隐形绊脚石；unref?.()的可选调用形式则兼顾了运行环境差异。
销毁逻辑必须幂等且容错：createPluginDispose的disposePromise记忆化 + 逐项try/catch，保证重复调用零副作用、单项失败不牵连全局。
装配接线要用集成测试验证：模块级 GREEN 不代表生产调用链就绪，必须有一层createPluginModule级别的测试证明"配置真的被穿起来了"。
生命周期契约要固化为测试：heartbeat unref、dispose 停止 mirror、disabled 时不构造，这些行为都已成为 mirror-manager.test.ts 与 plugin-dispose.test.ts 中的回归断言，后续任何改动都无法悄悄破坏它们。

结合 features/tui-sidebar/AGENTS.md 中的反模式清单，本模块的边界也值得铭记：插件进程与 TUI 进程绝不共享内存，镜像文件是唯一通道；快照形状变更必须升MIRROR_SCHEMA_VERSION；所有写入必须走TuiStateMirror.flush()以保证防抖与去重语义；所有时序参数（STALE_MS、HEARTBEAT_MS、POLL_INTERVAL_MS、WRITE_DEBOUNCE_MS 等）统一收敛在 constants.ts，禁止内联散落。这套约束让"心跳、防抖、过期、降级"四件事各自有唯一的权威定义，也正是它能够被测试稳定锁住的前提。

【免费下载链接】oh-my-openagentOmO: Just type "mass ulw" keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考