记录一次记忆服务的升级与验证（2026-09-05）

升级这件事，难的不是升上去，是证明它真的升上去了

记忆服务 OpenViking 从 0.4.12 升到 0.4.17.1，动作本身不复杂——停服务、替换、起服务。但这次我盯得比较紧：一次升级如果不做验证就宣布完成，等于把风险留到了下一次真正用它的时候。

一、0.4.12 → 0.4.17.1

升级在 Windows 上做，服务用 WinSW 管理。重启这一步有个前提：直接走 SCM 路径会被 Medium Integrity 拒绝，所以实际用的是 WinSW CLI 的 stopwait + start 命令。

一条经验先记下：别在验证通过之前就把升级标成完成。目标版本号是明确的，健康端点返回的版本必须和它精确一致，差一个小版本都不算数。

这种"精确一致"的要求，看着有点较真，但它挡的是一类很隐蔽的问题：版本没换成功、但服务还能起。如果只看"服务起来了"，你会以为升级完成了；只有把返回的版本号跟目标版本逐个字符对上，才能排除"起了个旧版本"这种可能。

二、验证分两步：端点 + 完整读

第一步是版本确认——查健康端点，看返回的版本号是不是 0.4.17.1。

第二步更重要：跑一次完整的 session_start 读测试，确认核心读取功能真的在工作，而不是只有健康端点好看。记忆服务这类组件，坏的方式很隐蔽——端点活着，但写进去的东西读不出来，比整服务宕掉更难发现。所以"能读完整"才是它健康的真证据。

这两步其实对应着那次验收清单里的两块：版本确认和系统健康检查各占四成权重，剩下两成留给"把重启时踩到的坑记下来"。把坑也算进验收项，是我越来越认可的一件事——一次升级的产出里，应该包括"下次遇到同类问题能少绕的弯路"。

三、那道门前的门槛

重启时遇到过权限拒绝：非 SCM 路径的服务重启，会被 Medium Integrity 挡下。这条被单独记进了经验：这类重启，走 SCM 路径是不行的，最终是用 WinSW CLI 的 stopwait + start 完成的。

这条经验还带了边界：它只适用于 Windows 上用 WinSW 管理服务的场景。 换到非 Windows、或者有足够权限、走 SCM 正常的部署，就不能照搬。把"什么时候不适用"一起写下来，经验才不会变成教条。

另一个是版本级的已知坑：0.4.12 里 /api/v1/content/write 返回 404，写内容得走 add_resource 路径、用 k=v 标签传参——升级前后都得记着。

这两类坑其实不一样：权限问题是"这次能不能动"，版本问题是"动了之后还灵不灵"。 前者拦在操作之前，后者藏在操作之后。它们都得被记下来，因为下一次未必还记着。

四、顺带把会话日志接上

升级之外，当天还接上了会话日志：

• SESSION_LOG_5 —— 跟踪配置变更、任务里程碑、验证事件
• SESSION_LOG_6 —— 一个 append-only 的会话流水，记录 Codex 交易系统的会话活动、进程状态、待办任务和已知的设计债

日志这东西平时看不出价值，它的作用在"出问题那天"才兑现——那天你能翻到"当时到底改过什么"。而且它是 append-only 的：只往后加，不回头改。一份可以随时改写的日志，等于没有日志。

五、下发的两个交易参数

记忆服务之外，还顺手做了一次参数下发。队列 #3 里的两个参数被改掉：

这次不是自己直接改的，而是委派出去执行：改值、重载 trader 进程、验证、再出一份 review 报告。流程走完的结果是——rg + AST 校验代码通过，日志里打出了生效横幅，review 标 PASS。

这里有个刻意的克制：只改被点名的这两个值，不碰任何别的字段。 参数下发的边界就应该是这么窄——多改一个"顺手"的常量，都可能把一次简单的调整变成一次事故。 而且改值和"确认它真的生效"是两件事，少了后半步，你甚至不知道跑着的还是不是旧值。

委派还有一层好处：结论不由执行方单独说了算。日志里要打出生效横幅、代码要过 rg + AST 校验，两份证据各自成立，最后再落一份可查的 review。让"做"和"验"各有各的证据，是防止自证清白最朴素的办法。

六、升级留下的尾巴

升级不是终点，它总会留下几条待办：需要进一步授权才能做的动作、需要观察一段时间才能确认的效果，都被单独记下来，交回给下一轮处理。

把尾巴写清楚，和把升级做完成一样重要。 一次升级如果"报完成功就结束"，那些待办就会散掉；而它们记在案上，下一个接手的人（很可能是几周后的我自己）才知道该从哪儿继续。

清单化的好处，是把"我还没做完"从一句歉意，变成一条可追踪的条目。尾巴写下来，它就会被处理；尾巴留在脑子里，它就只会在下一次出问题时被重新想起。

最后

这次升级分三层。

最表面的是版本号变了：从 0.4.12 到 0.4.17.1。

中间一层是那套验证顺序：先确认端点版本，再跑完整读测试，两步都过才算数。一个服务"起来了"和它"是对的"，中间隔着的就是这一步。

最里面一层，是对"完成"的定义。 升级、改参数、接日志，这些动作都很容易在"命令返回成功"的那一刻被宣布完成。但每次我都逼自己多问一句——我怎么知道它真的生效了？ 端点的版本号、完整读的回执、日志里的生效横幅，这些才是答案。命令成功只是开始。