OpenRig 升级

升级 OpenRig

升级是一个可观测的智能体工作流，而非隐藏在单个命令背后的事务。主机各有不同、进程状态可能漂移、本地插件文件会不断累积，而对失败步骤的有效响应取决于哪些部分仍然存活。

智能体掌握执行序列。每次变更后必须先停一步，观察实际效果，再选择下一步。 这里特意没有提供端到端的升级子命令。

安全模型

保持以下平面彼此隔离：

• 席位通常驻留在 tmux 中，可以在守护进程重启后存活。
• 守护进程、数据库、包装器和受管理的插件投影是正在变更的控制平面。
• rig down 会拆除席位。它不是保持连续性的升级的一部分。

在行动之前，明确需要保持连续性的 rig 和席位。在生产主机上，使用该主机常规的操作员仪式。在有利于恢复的构建 VM 上，编排器可以直接采用经过测试的运行时，但仍需观察每一步，并在出现无法解释的漂移时停止。

当恢复跨越实例边界时

在任一通道更改运行时状态之前，记录一个主机限定的执行器，并明确选择拥有恢复裁决的队列存储。声明原始所有者是继续、等待还是转移；另一个存储中的未完成义务并不是此裁决的独占保管权。如果原始存储不可用，请在存活裁决中保留其所有者的处置方式，并在竞争执行器行动之前将其传达给该所有者。

被拒绝的声明意味着在与裁决所有者协调所有权之前，不得进行任何进一步的运行时行动；它并不授权在另一个单独的旧行下继续。返回时需指定完整的执行器地址和经过慎重选择的存储。在恢复操作之前，读取该存储中的结果行，包括来源、目标、主体以及原始所有者的处置方式。仅创建接收凭证并不能证明等待的通道已收到或接受了转移。

循环

对于每一步：

1. 检查。 从当前主机获取实际事实。
2. 决定。 选择一个有边界的变更，并说明其预期效果。
3. 单次执行。 不要将下一次变更捆绑在一起。
4. 观察。 检查该步骤可能已更改的进程、监听器、数据库、插件和席位等层面。
5. 继续、调整或停止。 未达到预期是为智能体提供信息，而非允许盲目重试。

有边界的辅助脚本

让 SKILL_DIR 指向包含此 SKILL.md 的目录。这些脚本输出 JSON，但不决定升级顺序。

检查当前事实

node "$SKILL_DIR/scripts/inspect-upgrade.mjs"

此脚本查询已安装的 rig，获取其版本、守护进程状态、节点清单和插件清单。缺失的层面会保持可见，并附带建议的下一步探查。ready: false 意味着智能体必须解决或有意识地限定该差距；这并不意味着脚本应执行任何变更。

备份 SQLite

首先获取连续性快照：

rig snapshot <rig-id>
node "$SKILL_DIR/scripts/backup-sqlite.mjs" \
  --source "$OPENRIG_HOME/openrig.sqlite" \
  --destination "/safe/path/openrig-before-upgrade.sqlite"

该辅助脚本拒绝覆盖目标文件，优先使用 sqlite3 命令行的 .backup 命令（当命令行工具不可用时，回退到通过 node:sqlite 进行进程中备份），并用 PRAGMA integrity_check 验证备份。它不会停止守护进程或恢复数据库。

计划或应用安全的受管理插件刷新

插件树可能包含技能以及钩子和元数据。比较上一个打包的祖先版本、目标版本以及当前已安装的树：

node "$SKILL_DIR/scripts/refresh-managed-plugin.mjs" \
  --ancestor /path/to/previous/package/plugin \
  --target /path/to/target/package/plugin \
  --live "$OPENRIG_HOME/plugins/<plugin>"

查看排序后的决策。要仅应用 refresh-safe 和 add-safe 文件：

node "$SKILL_DIR/scripts/refresh-managed-plugin.mjs" \
  --ancestor /path/to/previous/package/plugin \
  --target /path/to/target/package/plugin \
  --live "$OPENRIG_HOME/plugins/<plugin>" \
  --apply-safe

该辅助脚本从不删除本地文件，也从不覆盖本地修改。本地删除、仅存在于本地的文件、目标版本的移除以及不明确的类型都会被报告，由智能体解决。在任何手动解决后重新运行计划。

迁移版本 0.5.9 之前的实例布局

版本 0.5.9 将上下文使用遥测数据放在 $OPENRIG_HOME/state/context-usage，提供者遥测数据放在 state/provider-usage，可寻址库放在 context/，默认的系统世界放在 context/system/system-world.yaml。现有的 0.5.8 版本用户目录通过智能体主导的迁移跨越这一边界：目标运行时先读取新规范位置，再回退到旧位置，而所有新写入都使用新的规范状态根。显式配置的自定义上下文库根目录在整个激活过程中保持不变。

该辅助脚本提供有边界、可检查的操作。智能体负责其执行顺序以及在它们之间激活目标运行时。在指定了精确的受保护预映像路径后，首先检查并准备规范目录、默认系统世界以及指向现有库的配置固定。准备工作不会复制遥测数据、重写实时收集器设置或运行生命周期操作：

--help 在不检查实例的情况下打印阶段语法。没有阶段标志时，该辅助脚本会按设计运行只读计划；未知选项会在计划或变更之前返回非零退出码。

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --help

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME"

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --apply-state \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before"

使用常规升级工作流激活确切的目標运行时。然后等待，直到每个有边界的应用后遗留写入都被同一席位更新的成对新根样本所跟随。这证明了时间收敛，而无需全面替换进程；后续的遗留写入是一个硬性停止。捕获验证 JSON；复制旧的副车并不构成证据：

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --verify \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
  > /safe/path/layout-0.5.9-verify.json

只有成功接收才授权单独调用的非破坏性终结器。它将未配置的旧库复制到规范根目录，不覆盖任何内容；自定义上下文库根目录保持不变：

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --apply-library \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
  --verification /safe/path/layout-0.5.9-verify.json

遇到任何报告的问题都应停止：格式错误或外来的遥测数据、保留路径冲突、库冲突、配置漂移、恢复的旧写入、字节漂移或缺少新的成对样本，都需要在继续之前进行指定的修复。验证将确切的已接受尾字节与其成对的新样本绑定；终结器在切换配置前立即重新验证它们。该辅助脚本永远不会删除旧遥测数据或库。它们的后续淘汰是另一个独立的智能体决策，需要在稳定的运行时、写入器、读取器和恢复证据后做出。它不会停止/启动守护进程、启动席位、访问数据库或决定升级是否继续进行。

要恢复，首先按照智能体主导的工作流要求恢复先前的运行时，然后仅撤销辅助脚本拥有的配置、系统世界、空目录和复制的库效果。真实的状态样本以及两个旧恢复源保留以供检查：

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --rollback "$OPENRIG_HOME/backups/layout-0.5.9-before"

智能体主导的连续性升级

这是一份决策指南，而非命令配方。根据您当前的主机调整路径和检查项。

1. 使用辅助脚本检查当前的 CLI、守护进程、节点和插件。
2. 检查点：保存当前工作，并记录确切的受保护 tmux/会话列表。
3. 为每个受保护的 rig 运行 rig snapshot <rig-id>。
4. 创建并验证 SQLite 备份。
5. 在隔离环境中编译或暂存目标运行时。在接触当前守护进程之前，验证其版本和源身份。
6. 运行 rig daemon stop。验证监听器和已识别的守护进程进程都已消失。如果命令返回时仍有任一进程留存，请停止：检查身份并使用主机授权的恢复流程。不要盲目地向 PID 发送信号。
7. 在启动目标运行时之前，要考虑它启动时对受管理插件和标记的全局技能进行的刷新。这个运行时在 $OPENRIG_HOME/backups/managed-refresh/ 下保留不同的替换文件，并报告每个恢复路径；如果目标运行时缺少该保留机制，请先复制这些树。使用 rig daemon start 或主机的已知包装器启动它。验证守护进程状态、进程路径、监听器、版本和数据库完整性。恢复副本保留字节；它们不保证自定义行为在刷新后仍然生效。
8. 以计划模式运行插件刷新辅助脚本。其计划仅控制辅助脚本后续的写入，而非已发生的启动写入。仅在三个根目录及其分类合理后应用安全写入；必要时逐一解决保留的路径。
9. 使用 rig ps --nodes -A --json、代表性的 rig capture 以及适用的 rig restore-check 验证受保护的席位。-A 是必需的：没有它，节点读取仅针对您当前的 rig，而守护进程升级会保护主机上所有 rig 的席位 — 因此，窄格式会报告成功，而您 rig 之外的席位却未经检查。
10. 只有在推导出该主机如何拥有包装器之后，再对齐包装器。使用其现有机制；此技能不会重写启动器。
11. 记录观察结果、剩余的本地保留决策以及确切回滚运行时和备份。
12. 阅读新版本中的变更内容 rig context get reference/whats-new.md，并告知您的用户其中任何改变他们工作方式的内容。

在以下情况下停止并交回控制权

• 升级前，某个受保护的 tmux 会话缺失；
• 数据库完整性或备份验证失败；
• 正在运行的进程或监听器与预期运行时不符；
• 守护进程停止报告成功，但已识别的进程或监听器仍然存在；
• 目标运行时无法针对现有数据库启动；
• 插件根目录无法关联到已知的祖先版本和目标版本；
• 某个必需的插件路径被分类为本地修改或已删除，且正确的所有权决策不明确；
• 继续执行需要 rig down、破坏性恢复、凭据更改或操作员不具备的更广泛权限。

停止时，报告最后一个经过验证的良好状态、第一个失败的预期结果、确凿的证据以及所有者所需的最小决策。除非恢复特别要求，否则保留在线席位和数据库。

回滚也是智能体主导的

优先针对仍在使用的数据库启动先前的已知运行时。仅当迁移或损坏发现需要时才恢复数据库备份；降级的投影本身并不能证明应该替换数据库。回滚后，重复前向路径中使用的相同进程、监听器、数据库、插件和席位观察。