Skip to content

增强包更新与兼容 ​

四类增强包共用宿主级更新控制器、EnhancementPacks 协调器及后台任务。设置页状态查询不发起更新,控制器在宿主启动后运行,监听应用级设置,退出时注销调度和网络观察者。账号、桌面、内嵌 Web 与 Remote 不各自启动控制器。

发布描述 ​

WeQ Release 按平台发布 enhancement-packs-平台-架构.json,描述文字识别、语音及意图/画像包;独立装扮仓发布 enhancement-pack.json。开发版和正式版统一读取已发布、非草稿的指定渠道描述,再固定明确 tag、URL、长度与 SHA-256 下载,不下载浮动 latest 资产。运行时不读取本机 .artifacts 或安装包内生成的引擎下载清单;本地生成物仅用于打包、验证和发布。

过渡期间,同一个已发布 Release 缺少统一描述时,可读取其 enhancement-engines-平台-架构.json 或 index-manifest.json 并转换成统一描述。旧引擎格式的模型部分使用当前客户端登记的固定模型契约;引擎 URL 和装扮资产必须与该 Release 实际资产对应,不根据本机版本推测地址。同一个 Release 已提供统一描述时只读统一描述,解析失败不会切换旧格式或更旧版本。

每包包含 id、contentVersion、minWeqVersion、runtime 和 components。组件分模型文件、预编译引擎及装扮索引;内容版本根据组件文件身份计算,不包含 Release tag、镜像 URL 或发布时间。相同内容换发布地址不会重复更新。

  • 引擎的 compatibility 保留冻结构建配方身份,runtime 描述运行接口,两者不再相互替代;v2.7.0 旧引擎回执继续可读。
  • 最低版本取各组件要求的最大值。现有独立引擎目录加载的最早正式版为 2.7.0;各配方和模型可分别登记更高要求,不把当次 WeQ 版本自动填进最低版本。数据或兼容依赖更新不提高接口基线。
  • 先解析稳定头部再解析组件,即使新版增加未知模型或格式,旧客户端也能显示最低版本及设置内升级链接。最新版不适用时不选择较旧的兼容更新。
  • 装扮沿用 NTDR v1,nativeCommit 仍绑定解密密钥来源;最低 WeQ 版本不能替代密钥及真实读取验证。本地源码 native 使用配套构建索引,不接入不匹配的发布版索引。

协调与恢复 ​

默认 enhancementUpdates = { autoCheck: true, autoInstall: false },与账号无关,随全局设置同步、备份及恢复默认。隐藏自动安装开关不清空值,但自动检查关闭时安装也不执行。检查间隔和测试版偏好读取现有软件更新设置;-1 禁用定时检查,手动检查不受影响。

仅本次成功检查到的已安装包参与自动安装。缓存描述可以用于显示和显式准备,检查失败不能标记最新或据此自动下载。重复检查合并,同一个包的在途准备不重复启动;忙碌结束后继续协调已确认的更新。明确卸载记录持久化,旧目录或保留原件不自动复活为已安装包。

所有显式下载入口共用清单解析步骤,包括增强包页、文字识别、语音和意图功能入口。本次运行尚未成功检查对应包时先读取在线清单,关闭自动检查不影响手动准备;读取失败可复用之前保存且通过内容校验的在线缓存,保留检查失败状态。首次没有在线缓存且无法联网时在组件下载前失败,可直接重试。已安装资源的离线使用和自动完整性核对不要求先联网。

安装历史与当前完整性独立:整包回执、组件安装记录或通过校验的完整专属旧模型可以证明曾安装;共享引擎和零散文件不能。旧版缺少新增组件时保留安装历史并标记待补齐,自动安装按此历史选择包,不要求当前已经齐全;明确卸载始终优先。占用统计独立于安装历史,包含部分文件与候选分段,不再因缺少专属模型将已有引擎归零。列表只增加短状态,缺项放工具提示;不引入整包就绪的业务功能总开关。

模型更新在 models/.versions/内容身份/模型ID/ 准备候选,完整文件经过哈希后 clone 复用;使用者从活动模型路径读取。引擎候选回执标记 staged,不会被普通发现过程当成活动版本。校验文件、执行 CPU 引擎探针和所属模型推理后,暂停新推理进入、等待已有推理结束,再切换活动资源并原子提交整包 ready.json。回执保存组件快照,中断后优先恢复整包提交点,而非各组件未提交的活动文件。

共享 ONNX 按一个物理组件准备,切换前验证其他已安装使用者;常驻模型按实际运行状态停止与重启。装扮在 native 工作线程完整解密读取三类索引,全部成功才同时替换;失败保留旧缓存,删除时清空缓存。业务装扮服务持有同一个可切换索引存储,不保留旧版本引用。

成功后只清理有管理回执且内容仍匹配的旧产物,保留旧原目录、变动文件、自放模型和未知附加内容。删除保留卸载记录及其他能力仍使用的共享资源;用户设置、识别结果与具体装扮素材不随包删除。

任务与网络 ​

每个包一次准备对应一个任务,模型、引擎及三类索引更新该任务的阶段和累计进度。检查更新本身不创建任务,进行中、等待网络、结果与失败原因通过包的检查状态在原处展示,可从原处重新检查或继续等待中的检查。ManagedDownload 负责分段身份、Range 续传、策略暂停及自动恢复;手动暂停跨组件保持,手动继续只放行本次包任务,不能豁免以后自动任务。后台检查受后台预取偏好约束,省流量切换会中止当前检查请求,允许后重新读取;API ETag 可减少未变化清单传输。

发布验证 ​

正式应用打包前运行 node scripts/verify-enhancement-engines.mjs --native-only,验证正式 native 提供源密钥身份、异步校验/重载及缓存清除接口,并与应用索引清单配套。首次上线须先发布新 native 与装扮资源,再更新已验证的 native 和索引版本锚;只完成本机源码验证不等于已发布这些资产。

引擎仍由现有脚本收集目标平台依赖、裁剪、签名、生成哈希及探针验证;上传器只向草稿 Release 上传并发布统一描述,不改写正式版本。可用 node scripts/verify-enhancement-engines.mjs --models-root 模型目录 复用本机模型验证真实 OCR、筛图、Laya 与 SenseVoice,测试不会复制模型原件或访问聊天数据库。

相关实现:更新控制器、统一发布描述。

网络与签名索引 ​

应用内公网 HTTP 请求通过轻量 @weq/network 适配;桌面使用 Chromium 系统代理/PAC,独立 Node 服务及联网 worker 使用环境代理,遵循 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。QQ 本机认证、协议 socket 以及需要钉住已核对 IP 的链接预览保留专用传输。适配层不自动重放写请求或 AI 生成请求。桌面读取保留显式 Cookie、Range 和最终重定向地址;二进制写请求由 Chromium 计算 Content-Length。

WeQ 与装扮资源仓通过固定 Release weq-update-feed 的 update-index.json 分发签名索引。该 Release 是机器读取入口,不是应用版本,也不设置为 Latest;明确版本的正式资产仍位于原 Release。索引携带每个渠道最新版本的发布身份、资产名称/长度/SHA-256,以及原始增强包描述。Ed25519 对完整索引签名,客户端使用内置公钥验签,镜像只传输字节。Mac/Linux 已确认版本的安装哈希可直接来自该签名描述,不再要求下载后再次访问 GitHub API;没有签名描述的旧发布继续从官方 HTTPS API 取得身份,不接受镜像自报摘要。

客户端合并在途索引读取,成功结果短缓存五分钟,并持久保存签名原文供重启后重新验签。离线缓存可用于明确版本的下载/核验,在线检查失败不冒充成功;拒绝渠道版本倒退。索引读取、旧描述及大文件下载复用同一镜像池,每批最多探测三个源,缓存源健康三十分钟;桌面网络接口变化后失效。后台策略暂停和取消会结束真实在途请求。

ManagedDownload 首字节默认十五秒、正文读取空闲默认三十秒;持续有数据不受固定一分钟总时限截断。每文件最多八次尝试,临时连接错误、超时、408/425/429及可重试5xx退避重试,尊重 Retry-After。策略暂停不消耗次数。可信长度和 SHA-256 相同的源可以在匹配的206分段响应下接续,跨源不携带旧源 If-Range;最终全文件哈希不匹配时丢弃坏分段再换源,200响应始终从头重写。无可信内容身份的普通资源仍要求同源验证信息。

模型文件描述保留 url,可附带 sources。OCR 和 SenseVoice 使用已经核对与旧文件相同的 ModelScope 明确提交,不再读取 master;旧在线描述中已知文件的浮动地址按文件哈希及长度规范化。Laya 保留原固定提交与 hfMirror 偏好,启用时将镜像与原站纳入候选,关闭时只使用原站。ModelScope 的两个域名属于同一平台,Laya 镜像也可能重定向至原 CDN,这些不是独立资源备份;本轮不重新托管模型。

发布接入 ​

node scripts/prepare-release-metadata-key.mjs 为维护机准备 Ed25519 密钥,私钥留在机器的发布配置目录,源码只提交公钥。发布环境通过 WEQ_RELEASE_SIGNING_KEY 提供相应 PEM 私钥;node scripts/publish-release-feed.mjs --check-key 在远端写入前核对公钥匹配。密钥不能打印到发布日志或进入 Git。

主程序与独立装扮发布工作流均先核密钥,再公开正常版本,最后调用 publish-release-feed.mjs。发布端从官方 Release 取得资产身份,只读取小型描述,不重新下载大型安装包或模型;首次运行从已公开版本初始化渠道基线。工作流串行更新索引,旧任务不得覆盖较新渠道版本。索引上传失败可重跑公开步骤,已发布正式资产不改写;客户端在索引尚未上线时仍保留旧发布路径。共享工具与两个仓的客户端公钥需要先同步,再配置相同签名密钥,最后上线索引;本地测试通过不代表这些远端步骤已执行。

当前文档对应 v2.7.4 · 已发布内容以 CHANGELOG 为准