记忆守护监管器 Nesarf/volcano-separator

Volcano Separator

CI

将三样被焊死在一起的东西分开。

volcano-separator 是 Hindsight 记忆守护进程的监管器。它修复的不是一个 bug——它修复的是一种结构性脆弱：

uvx（包安装器） └─ uv 缓存中的一个临时环境 ← 守护进程自身的代码就在这里 └─ hindsight 守护进程 ← 由宿主插件按需启动， └─ Postgres (pg0) 仅在会话开始时 / 在 retain 时 ← 数据就在这里

一个包安装器的状态决定了服务能否启动，而服务的生命周期又由宿主的会话时序决定。当任何一环感冒时，记忆就会消失——悄无声息地。

它实际治疗的是什么

在提取出本工具的机器上测得（volcano-separator doctor）：

12 次启动尝试，7 次因超时失败，1 次成功

每一条失败日志都在启动路径上显示 Downloaded botocore / Built claude-agent-sdk==0.2.16x。
一次构建和一个看门狗在互相竞速——插件的看门狗允许约 180 秒，而在机械硬盘上冷缓存的 uvx 运行需要的时间远不止于此。它每次都输。

修复方案：将工作分阶段，使任何看门狗都不会与构建竞速

| 阶段 | 它做什么 | 看门狗 |
| warm | 确保 uv 环境完整（幂等） | 无——它可能需要数分钟；它会运行至完成 |
| serve | 仅在环境已热时启动守护进程 | 有，但此时只需数秒——它永远不会触发 |
| watch | 按需进行健康探测与修复 | 心跳，健康时成本近乎为零 |

让这一切奏效的特性是：heal 在健康时耗时约 0.9 秒（一次 TCP 探测）。因此它可以每隔几分钟被调用一次，而无需保留一个常驻的监管进程——调度即监视。

修复的另一半在本工具的上游：将 UV_CACHE_DIR 指向一块 SSD，并把旧路径做成 junction，这样即使是冷启动也很快。

安装

git clone https://github.com//volcano-separator.git
cd volcano-separator
node bin/cli.mjs status # 无需安装步骤：零依赖

可选地将其加入 PATH：

npm link # 提供 volcano-separator 和 vsep

用法

volcano-separator status # 全链路检查（uv / 环境热度 / 守护进程 / pg / 守护进程日志错误 / 看门狗） volcano-separator heal # 智能修复：warm -> serve -> watch volcano-separator warm [--force] # 仅预热环境（无看门狗） volcano-separator serve # 仅启动服务 volcano-separator stop | restart volcano-separator doctor # 从插件日志统计历史启动失败次数 volcano-separator guard clean # 检查此刻执行 uv 缓存操作是否安全 volcano-separator install-service # 注册看门狗任务（登录时 + 每 N 分钟） volcano-separator service # 看门狗任务状态

选项：--profile （默认 coding-agent）、--port （默认 9077）、--json、--quiet、--force、--dry-run。

三种接口

| 形式 | 入口点 | 适用对象 |
| CLI | bin/cli.mjs | 人类、脚本、计划任务 |
| MCP | lib/mcp.mjs | 任何 harness —— volcano_status / volcano_heal / volcano_doctor |
| 库 | lib/core.mjs | 其他工具（纯 Node，零依赖） |

MCP 客户端配置： json {
"mcpServers": {
"volcano-separator": { "command": "node", "args": ["/path/to/volcano-separator/lib/mcp.mjs"] }
}
}

它为你处理的三个真实陷阱

1. 守护进程的代码位于 uv 缓存内部。
因此 uv cache clean / prune 会被正在运行的守护进程的占用锁阻止，而 --force 会在守护进程运行时删除它自己的文件。更糟的是，当它还活着时，缓存目录甚至无法被重命名（访问被拒绝）。
volcano-separator guard 会先检查并打印安全顺序：stop -> uv cache -> heal。

2. 由宿主插件启动的守护进程不被 embed 管理器识别。
hindsight-embed daemon stop 跟踪自己的 PID；宿主插件自己启动的守护进程不在该记录中，因此：

WARNING - Could not find PID for port 9077
WARNING - Port 9077 is bound but no hindsight daemon could be identified on it
Failed to stop daemon

因此 stop 有两个层级：先走官方路径，然后找到端口占用者并收集其进程树（仅限 uv/uvx/python/hindsight 进程——绝不包括其他任何东西）。没有这一层，一个由插件启动的守护进程会让监督程序永远无法停止它。

3. “端口有响应”不等于“它能工作”。
守护进程可以让 /health 保持绿色，却无法连接到它的数据库。在实际环境中观察到：磁盘饱和（一次后台文件清理）导致守护进程的 Postgres 连接握手超时 48 次，端口从未闪烁，而每次记忆写入都毫无可见原因地停滞。这就是为什么 status 还会探测 Postgres 并扫描守护进程自己的日志以查找错误——也是为什么它使用两个时间窗口：最近 5 分钟内的错误意味着它现在正在失败，而更早的任何内容都作为上下文（recovered）报告，这样过去的事件就不会让链条永远被标记为不健康。

设计边界

- 它不修补宿主插件。 插件的 ensureDaemon() 以 if (await isServerHealthy(...)) return; 开头——一旦服务已经健康，它会立即返回，那条脆弱的路径永远不会被进入。那是“不再被遍历”，而不是“被修补”。
- 没有额外的常驻进程。 监视被委托给操作系统调度器。
- 它只读取日志；它从不触碰 hindsight 自己的数据。

移植一切皆靠发现，而非硬编码：uvx 来自 PATH，缓存目录来自 UV_CACHE_DIR（并将 junction 解析为其真实目标），嵌入版本来自宿主配置。

在 lib/core.mjs 顶部的 DEFAULTS 中调整行为： js profile: 'coding-agent', port: 9077,
withPackages: ['pg0-embedded'],
warmProbeMs: 15000, // 一次干跑慢于此值意味着环境是冷的 warmBudgetMs: 15 * 60 * 1000, serveBudgetMs: 5 * 60 * 1000, taskName: 'Volcano-Separator', taskIntervalMinutes: 5,

平台说明：计划任务集成目前仅限 Windows（schtasks / New-ScheduledTask）。暂存模型本身是可移植的——在 macOS/Linux 上，将 installService() 替换为 launchd plist 或 systemd timer。

要求

Node >= 20.12。零第三方依赖。

测试 bash
node test/smoke.mjs # 或：npm test

冒烟测试刻意保持离线：无网络、无 uv、无运行中的守护进程。它断言对监督器至关重要的属性——模块能加载，每个探针在其依赖缺失时降级而非抛出异常，缓存护栏在没有任何运行中的进程时报告“安全”，以及 CLI 的退出码行为正常。CI 在 Node 20 和 22 上运行它，覆盖 Linux 和 Windows。

许可证

MIT