升级指南

Captain Who 已包含签名稳定通道更新客户端，但当前公开更新通道尚未启用，也没有自动回滚服务。正式通道启用后，客户端只接受内置 Ed25519 trust root 验证过的 pointer、Release Manifest 和当前架构 artifact，并在下载后再次核对大小与 SHA-256。当前唯一内置的数据库升级路径是 exact storage v20 到 v21；它不会改变表结构或用户记录，只提升全局 schema 版本。其他跨版本兼容性不能据此推断。公开通道未启用时，只有可信分发方同时提供新构建及其适用说明，才应手动替换。

升级前

阅读分发方随新构建提供的变更、兼容性和已知问题说明；没有这些信息时，不要把替换视为无风险升级。
等待正在运行的 Agent、命令、MCP 调用和 Automation Run 结束或安全停止。
完全退出 Captain Who，避免在数据库或附件仍被写入时复制数据。
备份重要项目文件。项目目录不由 Captain Who 备份。
如需保护应用历史，备份完整的 Captain Who 应用数据目录，而不是只复制 storage.sqlite。该目录的位置由 Electron 按操作系统和安装身份决定，当前界面尚未提供“一键导出数据”功能。

当应用识别到 exact v20 数据库时，会在启动任何数据清理或 Agent 恢复前自动创建 storage-backups/pre-upgrade-v20-to-v21-*.sqlite。系统先验证只读源库，再从该备份构造并验证 v21 working copy，最后原子发布。该快照是数据库级恢复点，不包含应用数据目录中的附件、图片、Skill 或系统凭据，因此不能替代上面的完整目录备份。

模型 Token、Tavily Key 和图片生成凭据可能保存在操作系统凭据存储或构建专用的私有凭据目录中，不一定包含在数据库或普通文件数据目录备份中。旧版 v20 数据库及其升级前快照也可能仍含迁移前的明文凭据；所有备份都应按敏感数据保护。恢复配置后应按界面状态重新填写缺失凭据，不要把不透明引用当作可迁移的密钥。

安装新版本

从提供现有安装包的同一可信来源获取与操作系统、架构匹配的新安装包。
核对分发方实际提供的发布者、版本、签名、公证状态或文件校验值；文档未提供的验证信息不能自行推断。
保持应用关闭，按该平台的标准安装方式覆盖或替换旧版本。
启动后确认项目、对话和设置正常加载。
用低风险对话验证模型连接，再检查 Skill、MCP、浏览器和 Scheduled 页面。

不要使用开发构建、未签名目录包或来自另一操作系统的文件覆盖正式安装。

如果升级失败

保留首次错误信息，不要反复启动可能产生副作用的任务。
不要手工编辑 SQLite schema 或删除数据库来绕过错误。
若 v20→v21 失败，保留原 storage.sqlite 和生成的 pre-upgrade-v20-to-v21 快照；发布

前失败不会改写源库。

如果旧版本重新安装后无法打开新版本写入的数据，不要强制降级；当前尚未公布跨版本数据库回滚保证。
保留升级前的完整应用数据备份，并按诊断信息与日志整理无敏感信息的复现资料。

当前限制

当前没有已启用的公开自动更新通道或自动回滚服务。现有客户端只接受内置生产 trust root 验证通过的签名 pointer、Manifest 与完整 ZIP，并在下载后核对大小和 SHA-256；默认 trust 配置关闭，不能把代码存在等同于公开可用。
当前更新包是完整 ZIP，不提供差分更新。
没有正式的数据导出/导入和跨版本恢复向导。
内置迁移只接受 catalog fingerprint 完全匹配的 v20；v3–v19、未知版本、schema 漂移或

外键损坏都会 fail closed，不会被猜测性迁移。

数据库版本变化时，不能假设旧版本可读取新数据；只有分发方为具体版本提供的兼容性证据才能扩大这一结论。