PaperSpine5 更新机制实战指南：preflight 调用检查、稳定更新通道与事务性升级全解析

• AI 技能
• AI 写作
• 人工智能
• 深度研究
• AI 应用

PaperSpine5 采用"每次调用前自动检查、有新版则事务性整包升级"的更新策略：在任何论文生产（paper production）或恢复（resume）工作流启动之前，应先运行已安装 Skill 自带的paperspine_update.py --preflight检查。本文以 update.md 为骨架，结合 paperspine_update.py、stable_updater.py 与 test_update_preflight.py 源码级佐证，完整讲解 preflight 的调用方式、命令行参数、稳定通道与平台选择、事务性升级与回滚、旧入口迁移路径，以及 V4 兼容版本序列的区隔原则。读完本文，你将能在 Codex、Claude Code、OpenClaw 或普通终端中安全、正确地维护 PaperSpine5 安装，并理解其更新机制的底层实现原理。

一、每次论文生产前先跑 preflight：调用检查与即时升级

PaperSpine5 把"更新检查"内置进生产工作流的前置环节。文档给出的标准调用命令是：

python -B scripts/paperspine_update.py --preflight --yes

其中：

• -B禁止 Python 写入__pycache__字节码缓存，保证更新器在只读场景下也干净运行；
• --preflight表示"每次调用都检查"：如果当前已是最新则立即继续；如果有更新则事务性（transactionally）应用新版完整套件；
• --yes跳过交互式确认，适用于 Agent 或无人值守环境。

从源码看，paperspine_update.py的run_preflight()（src/scripts/paperspine_update.py#L856-L916）承担了这条主路径：

1. 先检查自动更新策略文件update_policy.json；若用户显式关闭了自动更新（--disable-auto-update），直接输出{"status": "disabled", "continue_existing": true}，不做任何网络检查；
2. 定位已安装的paper-spineSkill 目录与更新控制目录，加载已安装套件的稳定更新器（stable updater）入口；
3. 读取更新通道元数据，与本地安装身份（build_id / product_version / archive_sha256）比对，得出up_to_date、update_available或recovery_required三种状态；
4. 有新版本时，执行module.auto(...)完成事务性安装。

对应的预检结果语义在 test_update_preflight.py#L85-L126 中有明确验证：

• 已是最新时--preflight --check-only返回退出码0，且绝不下载套件包（测试断言must-not-download.zip不存在）；
• 有可用更新时--check-only返回退出码2，并且auto()不会被调用——即检查模式只报状态、不安装；
• 显式关闭自动更新后，加载稳定更新器的入口根本不会被触发（load.assert_not_called()）。

离线与失败的严格区分

文档特别强调了一条边界：元数据网络失败 ≠ 安装失败。

• 检查阶段如果只是连不上更新源（URLError/TimeoutError/ConnectionError），_preflight_offline()（src/scripts/paperspine_update.py#L848-L853）会输出{"status": "check_unavailable", "continue_existing": true}，继续使用现有安装并给出提示，退出码仍为0；
• 但一旦进入安装阶段，包损坏或安装失败就是致命错误：必须保留旧安装并报告真实错误，绝不允许把失败描述成"离线成功"。对应测试 test_update_preflight.py#L128-L141 验证了"预检离线可继续、下载失败必须抛UpdateError"这一不对称策略。

二、paperspine_update.py 命令行参数全景

文档提到的所有参数均可在源码parse_args()（src/scripts/paperspine_update.py#L51-L123）中找到完整定义，且带约束校验：

文档明确了两点约束，与源码一致：--disable-auto-update的显式关闭"保持生效"；旧的--auto选择加入模式"保留其间隔行为"。另外--preflight与旧式自动更新策略命令互斥——二者是两条不同的维护路径。

三、事务性升级：快照、锁与回滚的安全边界

PaperSpine5 的更新不是简单的覆盖拷贝，而是具备完整事务语义的套件切换。stable_updater.py的apply()（paperspine5/core/06_插件化/release/stable_updater.py#L498-L612）展示了核心流程：

1. 加锁：lock()（stable_updater.py#L183-L205）在控制目录创建update.lock，Windows 用msvcrt.locking、POSIX 用fcntl.flock非阻塞加锁，防止多个宿主同时更新；
2. 快照：安装前把现有 Skill 目录完整复制到事务目录的previous/备份，并记录文件级 SHA-256 清单（inventory()），用于校验"旧安装未在更新期间被改动"；
3. 候选验证：按通道的 SHA-256 校验下载的套件 zip，解压后由版本适配器（stable_update_adapter.py）执行prepare，生成带installed-suite.json指针的候选 Skill；
4. 原子切换：用os.replace先把旧目录改名为.paperspine-retired-*、再把候选目录从 stage 改名为正式目录，避免出现"半套新 + 半套旧"的中间态；
5. 健康探测：切换后调用适配器的probe动作，实际运行新安装的paperspine5_web.py --help，确认 Web/host 启动器可执行；
6. 失败回滚：任意一步失败都会调用_recover()（stable_updater.py#L464-L495）依据transaction.json日志恢复旧安装，并对回滚结果再次做清单校验；
7. 提交：全部通过后把控制目录中的更新器入口与settings.json一并替换为随新包携带的新版本（即"更新器自更新"），写入committed状态的交易日志与receipt.json。

文档中"绝不要把失败更新当作成功""一个损坏的包或安装失败就是错误"的说法，正是这套事务机制的行为契约。恢复逻辑还额外防止两类危险：安装目标与更新控制目录互相包含（control必须在 Skill 发现与安装根之外）、以及事务目录路径逃逸声明父目录。

更新后必须做的两件事

文档明确要求：更新成功之后，重读已安装的 Skill 与当前工具 schema（契约随版本演进），并优雅重启运行中的旧 Web 服务：

• 在现有 profile 上以旧代码优雅关闭 Web 服务，再使用新代码启动；
• 不要同时启动两个"写入者"（duplicate writers），避免多进程并发写同一份论文数据。

这一要求与 dist/openclaw/skills/paper-spine/SKILL.md#L47-L55 中的产品级描述完全一致：更新只涉及安装本身，必须保留任务、profile 与用户文件。

四、稳定更新通道与平台选择

自动套件通道是：

https://raw.githubusercontent.com/WUBING2023/PaperSpine/main/website/downloads/update-channel.json

仓库中的 update-channel.json 展示了通道的实际结构。它采用paperspine-updater/1协议，顶层提供两类字段：

• 历史兼容字段bundle：单包描述（当前为 Windows x64 兼容包），供旧的 Windows bootstrap使用；
• 新字段bundles：平台映射，为 Windows x64、Linux glibc x86_64、macOS arm64、macOS x86_64 分别提供独立 bundle。

每个 bundle 均包含url（发布 zip）、sha256（64 位十六进制）、bytes、platform、build_id、product_version。stable_updater.py的select_bundle()（stable_updater.py#L49-L76）负责解析：

• 通过platform.system()/machine()归一化当前平台（amd64 → x86_64、aarch64 → arm64、darwin → macos）；
• 在bundles映射中必须恰好匹配一个bundle，否则报错；
• 校验 bundle 必须提供合法 SHA-256 且platform标注与当前平台一致。

由此，未知系统/架构会被直接拒绝，而不是回退到 Windows ZIP——这正是文档强调"unknown systems/architectures are rejected instead of falling back to the Windows ZIP"的代码实现。需要说明的是：当前仓库通道已发布至0.4.0-alpha.3（四个平台包齐全，见 release/v0.4.0-alpha.3/manifest.json），其 Windows 包同时保留在bundle字段中以兼容历史 bootstrap。

本地诊断参数

文档给出的本地诊断方式是：

python -B scripts/paperspine_update.py --preflight \ --source <channel.json> --skill-root <paper-spine> --control-root <updater-directory>

• --source指向本地通道文件或 HTTPS 通道，用于离线环境或预发布通道验证；
• --skill-root指向被管理的paper-spineSkill 目录；
• --control-root指向更新器控制目录（settings、transaction 日志所在处，默认~/.paperspine5/updater）。

从源码看，这些参数都强制要求搭配--preflight（paperspine_update.py#L115-L116），防止误用。控制目录中的settings.json记录了skill_root、channel、data_roots；若显式指定了属于另一个Skill 安装的控制目录，_stable_control()会直接拒绝（对应测试 test_update_preflight.py#L189-L194）。

已安装套件的身份校验

托管安装通过两层身份文件互证：

• paper-spine/references/installed-suite.json：paperspine5.installed-suite-pointer协议指针，记录build_id、product_version、archive_sha256、platform、suite_root、updater_entry、content_index_sha256；
• 套件根目录的suite-manifest.json：paperspine5.suite-manifest协议清单（schema 见 suite-manifest.schema.json），包含suite.build_id与content.index_sha256。

_managed_installation()（paperspine_update.py#L750-L774）要求指针与清单的build_id、content_index_sha256完全一致，任何漂移都会在执行任何更新动作之前失败——测试 test_update_preflight.py#L151-L159 验证了指针漂移与入口被篡改两种情况均不会被执行。

五、从旧入口取得补丁：老安装的迁移路径

已发布的paperspine-updater/1应用协议继续受支持。场景如下：你的机器上还是一个"旧版 stable updater + 旧版 Skill"，需要先拿到补丁才能进入 V5 套件体系。

文档给出的迁移路径是：

1. 旧 stable updater 先安装新的平台专用通道（或"精确 ZIP + SHA-256"）。该包同时携带工作流补丁与新的更新器；
2. 然后调用一次新安装的scripts/paperspine_update.py --preflight --yes；
3. 这一次调用会顺带从已验证的已安装包中刷新外部的旧 bootstrap——如果已是最新则不重复下载。

细节与源码吻合：stable_updater.py的_refresh_bootstrap()（stable_updater.py#L356-L410）专门完成"旧更新器交接"——读取已提交的交易日志，从transactions/<op>/suite/release/stable_updater.py中取出已验证的新 bootstrap 替换控制目录中的paperspine_update.py，并做控制文件前后哈希校验。

需要特别注意的两点平台差异（文档明确）：

• 历史 Linux / macOS bootstrap 不认识新的bundles映射，首次跳转必须使用匹配的update-channel-<platform>.json（例如update-channel-linux-x86_64.json、update-channel-macos-arm64.json）——仓库 website/downloads/ 下确实按平台维护了这些分片通道文件；
• 通用通道保留一个 Windows 兼容bundle，供历史 Windows bootstrap 使用。

另外一个关键约束是：绝不要用开发分支 checkout 冒充已发布 release（"Never substitute a developer checkout for an installed release"）。已安装的 wrapper 使用与 Skill 捆绑的同一份规范 stable bootstrap，而不是任何本地开发副本。

六、V4 组件更新器与版本序列的区隔

PaperSpine5 的更新体系与历史 V4 组件更新器并存，但版本序列相互独立。旧 V4 组件更新器仍然会发现dist/paperspine_version.json。仓库中的 dist/paperspine_version.json 内容如下：

{ "version": "4.0.1", "channel": "main", "repository": "https://github.com/WUBING2023/PaperSpine", "manifest_url": "https://raw.githubusercontent.com/WUBING2023/PaperSpine/main/dist/paperspine_version.json", "archive_url": "https://github.com/WUBING2023/PaperSpine/releases/download/v0.4.0-alpha.2/paperspine-compat-4.0.1.zip", "product_version": "0.4.0-alpha.2" }

文档中的表述在代码层面完全成立：

• version: 4.0.1是兼容版本号（V4 组件更新器读到的就是它），这个 4.0.1 包承载的是"新 wrapper / bootstrap"（compat 桥接包）；
• 真正的V5 产品版本号是0.4.0-alpha.2（字段product_version），当前仓库通道已进一步发布0.4.0-alpha.3（见 update-channel.json）；
• 这是两条独立的版本序列：preflight 绝不能把 V5 的 0.4.x 当作对 V4 4.x 的降级来比较。

底层支撑是version_key()（paperspine_update.py#L219-L252）实现的 SemVer 2.0.0 优先级比较：它完整解析major.minor.patch[-prerelease][+build]，忽略构建元数据，并明确支持alpha.N这类预发布标识（注释指出：PaperSpine 用0.4.0-alpha.1做 shadow 迁移，若把更新器限制为仅rc.N将无法安全地进行分阶段发布）。数值型预发布标识符不允许前导零，非数值标识符按字典序低于数值标识符，与 SemVer 规范一致。

一次性组件更新完成后，preflight 会为当前操作系统选择完整套件，并沿用既有更新控制目录。文档还特别说明：旧的公共 Skill 若没有已安装套件指针（installed-suite.json 缺失），也能通过同一条事务完成迁移——迁移时保留其旧文件作为回滚备份，论文数据（paper data）与已保存的 profile 一律不移动、不清除。

七、显式安装 / 更新入口：网站 manifest 与 install.ps1 / install.sh

除了 preflight 自动更新，文档确认网站 manifest 与install.ps1/install.sh仍然是受支持的显式安装 / 更新入口。仓库 website/downloads/manifest.json 与 release/v0.4.0-alpha.3/manifest.json 展示了发布清单结构：每个平台 artifact 都给出file、bytes、sha256、download_url、install_command与build_id，并额外提供installer_sha256等安装器校验值。

文档对此给出的安全要求是：执行任何下载代码之前，先校验 manifest 的哈希与大小（"Verify manifest hashes and sizes before executing downloaded code"）。这与 stable updater 全链路哈希校验的设计一脉相承——通道元数据被视为可信发布输入，但下载的 zip 必须在落地后与sha256精确比对（candidate()函数，stable_updater.py#L227-L242），且远程通道只接受 HTTPS、禁止重定向离开 HTTPS。

最后，文档给出了一条非常务实的观察纪律，值得所有 Agent 与运维者遵守：成功的安装器事务、重新加载的主机、正在运行的 Web 进程，是三件不同的事——"一个成功的事务"不代表"宿主已重载"、"宿主已重载"也不代表"Web 进程已在跑"。在报告结果时只汇报实际发生且验证过的观测，不要把三者混为一谈。

八、自动更新策略的持久化与查询

与文档提及的--disable-auto-update/--auto行为配套，源码实现了完整的自动更新策略持久化机制，便于长期维护：

• 策略文件为~/.paperspine/update_policy.json（可用--config-home或PAPERSPINE_CONFIG_HOME覆盖），schema 版本1.0；
• 字段包括auto_update（布尔）、interval_hours（默认 24，允许 1–168）、target、last_checked_at、last_result、last_error；
• --enable-auto-update/--disable-auto-update写入策略；--auto-status可离线查看策略与上次检查结果；
• 自动更新到期判断由auto_update_due()（paperspine_update.py#L196-L207）完成：以last_checked_at + interval_hours与当前 UTC 时间比较，未到期的检查直接跳过且不触网。

--preflight与这些旧式策略命令互斥，因为 preflight 的默认语义本身就是"每次调用都检查"——它取代了定时任务式的旧模式，而显式--disable-auto-update依然能覆盖这一默认行为，保证用户的自主控制权始终生效。

九、关键文件索引

想深入阅读或二次验证本文结论，可按以下路径继续：

• 更新器主入口（参数解析、preflight、事务安装）：src/scripts/paperspine_update.py
• 稳定更新器 bootstrap（平台选择、锁、回滚、bootstrap 交接）：paperspine5/core/06_插件化/release/stable_updater.py
• 版本适配器（prepare / probe 动作、installed-suite 指针写入）：paperspine5/core/06_插件化/release/stable_update_adapter.py
• 更新器协议声明（paperspine-updater/1、Python ≥ 3.12）：paperspine5/core/06_插件化/release/updater-protocol.json
• 官方更新通道：website/downloads/update-channel.json及平台分片文件
• 兼容版本清单：dist/paperspine_version.json；产品发布清单：release/v0.4.0-alpha.3/manifest.json
• preflight 行为测试（离线、禁用、check-only、指针漂移等）：tests/test_update_preflight.py
• 已安装 Skill 中的更新条款：dist/openclaw/skills/paper-spine/SKILL.md

总而言之：PaperSpine5 的更新体系以--preflight为每次调用的守门人，以平台分片通道 + SHA-256 校验 + 事务日志 + 自动回滚为安全底座，以paperspine-updater/1协议连接新旧两代入口，并严格区分 V4 兼容版本与 V5 产品版本两套序列。按照文档给出的命令与本文展开的边界条件操作，即可在 Codex、Claude Code、OpenClaw 或纯终端环境中长期、安全地维护本地优先的论文研究工作区。

• AI 技能
• AI 写作
• 人工智能
• 深度研究
• AI 应用