更新与版本发布

补编设计稿，编写日期：2026-10-20。本文规定待实现的发布流程，不证明已有构建流水线、签名包、更新器或回滚系统。 实际实施状态以阅读导航为准；技术约束以项目根目录 AGENTS.md 为准。

适用范围与基线

• 本文覆盖 Web、API、Windows Agent、共享协议及数据库迁移的版本管理、兼容、验证、发布和恢复。
• 本文不授权生产发布、远程设备更新或真实数据恢复；实际执行需要明确环境、范围及负责人。
• 架构与参数以设计决策与参数基线为唯一来源。
• D01 约束首版单 API 实例、单 worker；D02 约束持久化待分发与恢复；D06、D07 约束协议和逻辑执行开始边界。
• 试点范围使用 P01，任务期限使用 P02，离线检测使用 P03，数据保留使用 P09，备份恢复目标使用 P10。
• 本文不重复定义参数值，不承诺建议容量或恢复目标已经通过实测。
• 首次环境准备与生产门禁参见部署指南。

开工前决策与上线前条件

生产签名与正式环境资料尚未准备好，不妨碍本地契约设计；但会阻止对真实环境宣称具备受信发布能力。

版本与发布清单

• 发布清单还应包含变更说明、已知限制、必要配置变更、验证证据、发布人及核准记录。
• 发布产物不可静默覆盖；相同版本发现内容不一致时停止发布并调查。
• 容器镜像固定到具体版本或 digest；生产清单不得仅使用浮动标签作为可追溯依据。
• 包摘要用于完整性验证；没有可信签名或受保护清单的哈希不能单独证明发布者身份。
• 仓库只保留安全的示例配置和发布元数据，不包含真实密钥、用户数据、备份或设备凭据。

协议和数据库兼容规则

• Agent 握手时报告协议及执行能力版本；服务端按已发布兼容矩阵决定允许连接、仅允许对账或拒绝。
• 对已连接 Agent 的任务分发仍需检查任务类型与 Schema 版本，不能因握手成功接受任意字段。
• 新字段需通过明确版本协商；未知类型、未声明字段及不支持的版本应使用稳定错误码拒绝。
• 用户和设备权限由当前服务端策略决定，不因运行旧 Agent 而放宽；缺少安全校验能力的版本不能继续接收新执行任务。
• 数据库迁移采用兼容优先方案：先增加兼容结构，再切换读写，确认旧版本退出后才考虑清理。
• 仅声明“存在 downgrade”不能证明可回滚；必须核查字段转换、数据损失和旧程序读取新数据的能力。
• UUID、UTC、JSON、索引、外键和唯一约束按根规范迁移；兼容结论须来自 MySQL 8.4 验证。
• 无法兼容回退的数据库变更必须先给出恢复方案、允许的数据损失范围和核准条件。

发布前验证材料

• 提供真实构建、类型与 Lint 检查结果，并列出执行环境、组件版本及未验证范围。
• 提供受影响的单元、集成、契约和授权异常路径测试；文档审查不能替代这些证据。
• 提供任务重复投递、撤销、取消竞争、连接中断、进程崩溃及迟到结果的状态验证。
• 提供 MySQL 8.4 迁移与兼容验证，记录是否可以回退应用、是否需要恢复数据库及相应影响。
• 提供 Windows 标准用户安装、启动、凭据保护、独立浏览器执行和卸载验证。
• 提供 D04 浏览器实际网络目标限制的验证，覆盖适用的重定向、DNS 变化和页面附带请求。
• 提供备份与异机恢复演练结果；恢复表现未达到 P10 时明确差距和处置决定。
• 对本期未开放的聊天、模型、Skill、MCP、桌面与 Shell 能力给出禁用证据，不能以菜单不可见代替后端禁用。

服务端发布流程

• 首版遵循 D01，不承诺滚动无停机；更新窗口和用户影响必须在实施前明确。
• 服务端停止不能证明设备上的任务已经停止；不得把连接中断统一改写为 cancelled 或重新执行。
• 已经发放执行许可的任务按 D07 核对；撤销和暂停无法撤回已经发生的副作用。
• 若将来启用高风险能力，高风险任务执行中不得强制更新或重启 Agent；首版也应避免在任务结果未确认时强行替换进程。
• 就绪与存活接口目前按部署指南规划，实际发布流程只能使用届时已经实现并验证的检查。

Agent 可信发布与分批更新

• 首版可采用人工、可见安装的签名包，或由可信受保护发布清单验证来源的安装包；本期不默认实现自动升级。
• 选择签名方案时说明信任根、证书或公钥分发、签名验证、撤销和轮换方法；选择发布清单方案时说明清单来源与访问保护。
• 在执行任何安装内容前先验证来源、完整性和兼容范围；校验失败应停止，而不是允许用户忽略后继续自动安装。
• 更新包与发布清单走有效 TLS；同时验证 TLS 与包来源，不能认为加密下载自动等于可信软件来源。
• 先在受控测试设备验证，再按批准的批次扩大；批次规模结合 P01 与风险决定，不预设未经确认的生产比例。
• 每批观察设备重连、版本、权限拒绝、浏览器任务结果及异常指标；未达到条件时暂停下一批。
• 更新前持久保存任务日志与必要配置，保护设备凭据；新版本不得读取或迁移无关个人浏览器数据。
• 更新后核对任务和事件，不能把本地执行记录清空当作修复方法；凭据丢失时按重新配对流程处理。
• 回退包同样验证来源与兼容；不能为恢复可用性恢复已被撤销的设备秘密或关闭安全策略。
• 自动下载、后台安装、批量远程升级和自动回滚只有实现并验收后才能列为功能，文档流程本身不构成这些能力。

暂停和回滚判定

• 应用回退只在旧版本兼容当前数据库和协议时进行；恢复镜像不自动回退数据库。
• 若必须恢复数据库，先隔离旧写入者与分发器，核准恢复时间点和数据损失范围，再实施恢复。
• 恢复后先重新核验账户状态、权限撤销、设备凭据、任务事件和 Agent 记录，避免恢复历史权限或重复副作用。
• 无法取得可靠的备份后撤销事实时，保持登录和新执行关闭，失效全部旧用户会话与设备凭据，重新核准身份和授权后再配对；结果未知的任务和未确认停止的执行名额保持冻结。
• 已发生的业务副作用无法通过程序回退自动撤销；需要业务补偿时另外授权，并保留核实与执行审计。
• 回滚失败或恢复时间超过目标时升级给负责人员；不能通过禁用 TLS、放开授权或直接改写任务终态恢复表面健康。

发布结束与证据归档

• 记录最终部署版本、数据库 revision、设备版本分布、发布范围、暂停或回滚情况及已知限制。
• 保存适用检查结果、操作记录和恢复依据；数据保留按 P09，备份按 P10，秘密继续脱敏并受访问控制。
• 更新 README 的实际运行命令、兼容矩阵与实施状态导航，使部署说明与真实交付能力一致。
• 只有真实环境检查通过才能说明相应环境发布成功；模拟通过、安装包生成或文档补齐不得表述为功能已经上线可用。