活动 ZIP 分包与公共清单

当前仅金字塔接入。构建扩展位于 packages/activity-bundles，接入名单为 bundles.json。公共清单只描述资源，不包含活动开放时间、玩家资格或奖励状态。百人赛保留现有独立目录及 version.json 方案。

构建与发布

重启 Creator 2.4.15，使新构建扩展注册。金字塔继续配置为微信远程 Bundle、合并所有 JSON。
在微信构建配置中填写 HTTPS 资源服务器地址，完整构建微信小游戏。扩展自动压缩接入名单中的每个 Bundle，生成 SHA-256、ZIP 大小及解压文件校验清单。
默认发布产物在 build/wechatgame-activities/remote/：公共 manifest.json，以及 pyramid/pyramid.<SHA-256>.zip。同样输入重复构建，ZIP 和哈希不变。旧哈希 ZIP 保留，方便旧客户端和正在运行的请求继续读取。
先上传哈希命名的 ZIP，确认文件可访问后，再更新 remote/manifest.json。清单禁用 CDN 缓存；ZIP 可长期缓存。代码包中的 remote 目录不上传到微信。ZIP 只含资源，组件脚本仍由 src/scripts/pyramid/index.js 随微信代码包发布。
同步发布本次客户端代码。后续只改资源可更新 ZIP 和清单；修改脚本或本地依赖仍需要重新发布小游戏代码包。本工具不自动上传或发布。

已有构建目录可单独生成资源包（不编译 TypeScript，也不能替代完整构建）：

node packages/activity-bundles/pack.js build/wechatgame

资源地址取自构建产物 src/settings.js 的 server，例如 https://cdn.pay.nika4games.com/remote/manifest.json。运行时不会把业务接口域名当成资源域名。微信需配置该 CDN 的 request/downloadFile 合法域名。

公共清单严格使用以下结构，每个 Bundle 仅包含 file、hash、size。hash 是整个 ZIP 的 SHA-256，size 为 ZIP 字节数。下面的 goldMiner 是后续接入示例，当前构建只生成接入名单中的金字塔：

{
  "schemaVersion": 1,
  "bundles": {
    "pyramid": {
      "file": "pyramid/pyramid.<哈希值>.zip",
      "hash": "<ZIP文件的SHA-256>",
      "size": 123456
    },
    "goldMiner": {
      "file": "goldMiner/goldMiner.<哈希值>.zip",
      "hash": "<ZIP文件的SHA-256>",
      "size": 234567
    }
  }
}

Bundle 配置文件名、版本及逐文件校验信息存于 ZIP 内的 bundle-manifest.json，不加入公共清单。下载后先校验整个 ZIP，再校验内部清单与归档文件是否一致；本地缓存记录保存内部清单哈希，防止内部清单损坏导致完整性检查失效。

加载与缓存

ActivityBundleLoader.ensureBundle("pyramid") 接入 Cocos 的 Bundle 加载方式。微信构建扩展在 boot 前安装公共加载器，既支持该方法，也兼容既有 cc.assetManager.loadBundle(name, callback) 调用。编辑器和浏览器预览继续使用 Creator 原有加载方式。微信构建缺少加载器时明确报错，不悄悄退回远程目录下载。

首页依据活动日程、关卡门槛和已知个人完成状态预加载金字塔；未开放时不因清单而加载其他活动。打开活动复用日程，个人详情单独获取。
登录至首次首页共享一个资源检查周期；之后每次返回首页、切回前台开启新周期。一个周期内，各活动共享一个清单请求，同一 Bundle 共享加载任务。持续停留和倒计时不发起网络请求。
缓存按资源服务器地址、Bundle 名、ZIP 哈希隔离。哈希相同且每个文件的大小、SHA-256 和 Bundle 配置都正确时使用本地解压目录；缺失或损坏时重新下载。
ZIP 先下载到新的暂存目录，核对大小、实际 SHA-256 和归档路径后解压，再验证文件和配置。全部成功才更新该 Bundle 的缓存记录。失败只删除该暂存目录，不覆盖旧记录、不清除其他活动缓存。
清单请求、解析或校验失败时，允许使用本地缓存继续加载，但仍校验缓存归属、内部清单哈希及每个文件的完整性；没有有效缓存则失败，不猜测远端版本、不下载或改写缓存记录。同周期共享加载结果，下次返回首页或切回前台重新检查清单。正常清单缺少活动条目或 ZIP 加载失败时仍报错，不回退旧缓存。
活动页面与进行中的 Prefab 预加载持有资源引用。新哈希可先下载，但使用中的 Bundle 保持有效，引用释放后下次加载才切换。切换时清理本 Bundle 的旧内存资源，不调用全局清缓存。
只有一份本次客户端支持的接入名单；未来接入其他活动时添加 Bundle 名、接入其开放判断和页面引用生命周期，再完整构建。

业务接口请求时机

时机	activityConfig/list
登录成功	请求一次
登录后的首次首页	复用登录中的请求或已取得结果
从关卡等页面返回首页	请求一次，刷新通关后的解锁条件
后台切回前台（包括关卡内）	请求一次；首页与全局监听共享请求
抽奖、领奖、支付确认成功	不请求；金字塔刷新 pyramid/api action:info
首页持续停留、倒计时变化	不请求，按服务器校准时间本地判断
点击入口、资源预加载	复用日程，不额外请求列表

首次首页若登录查询失败或结果已失效，允许补取一次；在途请求始终合并。账号或环境变化清空个人日程，资源仍按资源服务器隔离，不按账号重复下载。

本地验证

node --test tools/test-activity-bundles.cjs tools/test-pyramid-resource-loader.cjs
node --test tools/test-activity-schedule.cjs tools/test-pyramid-entry.cjs tools/test-pyramid-home-reminder.cjs
node tools/check-pyramid-types.cjs HEAD

覆盖确定性 ZIP、SHA-256、按需下载、缓存命中及修复、下载/解压失败保留旧包、多活动/并发共享清单、环境隔离、前台新周期、旧请求延迟及活动页面持有期间更新。发布前还需在微信开发者工具与真机核对 CDN 配置和本地文件系统加载；Node 测试不能代替微信设备验证。

6.1 KiB Raw Blame History Unescape Escape

活动 ZIP 分包与公共清单

构建与发布

加载与缓存

业务接口请求时机

本地验证

6.1 KiB

Raw Blame History