卡牌包与资源生产规划

设计图、原创武将和拼版裁切见Image 2设计图与设备资源生产计划，六色量化、RLCD派生、转换Profile和真机校准见六色屏与RLCD本地图像转换规划。本文档负责设备包、Schema和可重建资源格式；另外两份文档分别负责RGB母版生产和本地设备资源转换，三者不互相替代。

1. 原则

• 电脑完成裁切、抖动、OCR和复杂转换。
• 设备离线读取编译后的资源。
• 卡牌属性与RLCD、六色屏图片分离。
• 内容包不包含可执行第三方代码。
• 资源损坏不影响固件启动。
• Schema、内容版本和固件版本分别管理。

2. 两种形态

编辑工程保留原图、参数和可编辑属性；设备包由工具可重复构建。设备包以.chpack分发，安装后展开到SD，避免ESP32在游戏过程中解压。

编辑工程
├─ project.json
├─ sources/
├─ cards/
└─ previews/

设备目录
/cardhelper/
├─ catalog-a.json
├─ catalog-b.json
└─ packages/{packId}/{version}/
   ├─ pack.json
   ├─ index.json
   ├─ checksums.json
   ├─ pools/
   ├─ assets/rlcd/
   ├─ assets/color/
   └─ fonts/

3. ID与版本

• schemaVersion：数据结构版本。
• version：内容包版本。
• minimumFirmware：最低固件版本。
• gameId、packId、cardId和poolId使用稳定小写ASCII ID。
• 名称和图片变化不修改ID，真正不同的武将版本建立新ID。

MVP以500张作为验收规模、1,000张作为压力测试规模。5,000张只保留为长期容量方向；达到该规模前必须重新评估索引格式和内存。

4. Pack Manifest

pack.json至少包含schemaVersion、packId、name、version、gameId、gameAdapter、minimumFirmware、cardCount、defaultLocale、publisher、contentOrigin和createdAt。

contentOrigin建议支持original、licensed、user_supplied和unknown。字段用于来源管理，不自动构成法律授权结论。

5. 索引和卡池

设备优先读取单一index.json，避免打开大量小JSON。索引包含稳定ID、名称、基础属性、卡池引用、标签和各屏幕资源路径。若1,000张压力测试显示JSON的解析时间或内存不可接受，由电脑工具生成紧凑设备索引，编辑格式仍保留JSON。

游戏专有属性位于gameData命名空间，例如sanguosha下的baseHp、kingdom、gender和variant。通用资源模块不理解这些规则。

卡池文件只引用CardId；一张卡可以属于多个卡池而不复制资源。随机和补抽操作基于ID集合完成。

6. CHB图片格式

建议定义CardHelper Bitmap，扩展名.chb。文件头至少包含Magic、格式版本、宽高、像素格式、压缩方式、Stride、Payload长度和CRC32。

Rev.A逻辑像素：

• Magic为CHB1。
• 300×400，MONO_1BIT。
• 从上到下、从左到右。
• 每字节最高位对应左侧像素。
• 0为白，1为黑。
• 每行字节数为向上取整的width/8。
• 不绑定ST7305显存排列。

300×400单帧约15KB。500张约7.5MB，1,000张约15MB，因此Rev.A不压缩，优先保证读取和调试简单。六色资源后续增加新的像素格式，不在设备端把全彩PNG实时量化为六色。

7. 图片生产

导入原图
   ↓
检查尺寸与比例
   ↓
选择裁切区
   ↓
缩放到目标画布
   ↓
灰度、对比度和锐化
   ↓
阈值或抖动
   ↓
300×400模拟预览
   ↓
状态覆盖安全区预览
   ↓
人工确认
   ↓
生成CHB与校验值

裁切、亮度、对比度、锐化和抖动方法保存在编辑工程，保证相同输入得到相同输出。卡面不烘焙实时体力、护盾或Token。

同一批测试卡必须生成三种候选内容：原始卡图黑白化、简化海报和结构化模板。通过可读性、识别速度和对局偏好决定RLCD默认方案，不预设完整原卡一定最佳。

8. 字体

固件内置系统UI、数字、错误和诊断所需字形，保证无SD时可用。外部字体同时验证设备级全局字体包和每卡包字体子集；根据多包混合显示、加载速度、内存、损坏恢复和授权管理决定最终方案。

9. Python资源工具

统一命令、目录、JSON配置、缓存、错误等级和内部模块边界见资源转换工具接口与目录规划。本节保留产品级命令总览。

规划命令：

• cardpack init：创建编辑工程。
• cardpack import：批量导入卡牌、属性和资源，图片部分复用 cardpack asset import。
• cardpack preview：生成RLCD与覆盖层预览。
• cardpack validate：检查ID、引用、尺寸、字体、Schema和路径。
• cardpack build：生成可分发.chpack。
• cardpack install：安全写入MicroSD。
• cardpack inspect：查看包信息和校验状态。
• cardpack upgrade：将旧Schema升级到当前编辑格式。

图片相关操作统一放在 cardpack asset，屏幕调色板和色块验证统一放在 cardpack display；不再为量化、抖动和CHB编码分别规划长期独立脚本。

未来桌面管理器和网页端应复用同一转换核心，不复制一套规则。

官方工具不内置未经授权素材源，不提供针对受保护网站的一键抓取或批量下载能力。测试、演示和公开发布资源必须原创或具有明确许可。

10. 安装与完整性

安装写入version.staging目录，验证所有长度和SHA-256后切换为正式版本，再更新Catalog备用槽。更新中断时旧版本继续有效。

构建和安装阶段使用SHA-256检查完整性；运行时图片用CRC32快速检测。官方包后续增加数字签名，Rev.A允许无签名用户资源并明确标记来源。

设备必须拒绝目录穿越、超限文件、未知像素格式、重复ID、包外引用、不兼容Schema和缺少对应游戏适配器的资源。

11. 兼容策略

固件建议支持当前Schema和上一个Schema。更旧格式由电脑工具升级，避免ESP32长期携带所有历史迁移代码。旧包不应因普通固件升级立即失效。

12. 六色屏迁移

同一卡牌可以同时声明rlcd300x400和eink6color资源。固件根据Display能力选择完全匹配资源，找不到时使用明确兼容资源或显示缺失提示。游戏属性、卡池和身份规则不因换屏重建。