资源转换工具接口与目录规划

项目	内容
文档版本	0.1
状态	建议冻结，尚未实现
更新日期	2026-08-28
依赖	D-039、D-041；`resource-package.md`、`image-conversion-plan.md`
目标	统一RGB母版导入、双屏转换、比较预览、校验和卡牌包构建入口

1. 总体建议

不另建 image-converter、dither-test、make-chb 等长期并存的小工具。继续使用已规划的 cardpack 作为唯一用户入口，在其下增加 asset 和 display 子命令：

cardpack
├─ init / import / validate / build / install / inspect / upgrade
├─ asset
│  ├─ import
│  ├─ convert
│  ├─ matrix
│  ├─ preview
│  └─ validate
└─ display
   ├─ validate
   └─ swatches

这样桌面管理器、未来网页端和命令行可以复用同一Python核心。命令行只负责解析参数和展示结果，转换规则不写在命令处理代码里。

顶层 cardpack import 保留为卡牌、属性和多资源的批量导入编排；cardpack asset import 是单个RGB母版的原子操作。批量导入内部复用原子操作，不维护第二套图片导入逻辑。

2. 工具边界

cardpack资源工具负责：

导入已经选中的RGB母版及其来源记录。
根据JSON配置完成裁切、缩放、量化、抖动和设备编码。
生成六色、RLCD和覆盖层预览。
生成算法对比矩阵。
校验调色板、尺寸、像素格式、哈希、引用和授权字段。
构建可分发卡牌包并安全安装到MicroSD。

它不负责：

调用Image 2或管理API密钥。
自动从网站抓取图片、卡片或元数据。
在设备端实时执行复杂图片转换。
修改RGB母版原文件。
把AI概念硬件图当成CAD或工程图。
替代Figma或UI渲染器生成动态文字和状态层。

Image 2生成与本地资源转换分开，有利于权限、成本、可重复性和离线构建。生成记录通过manifest连接，不把模型调用嵌入 cardpack build。

3. 编辑工程目录

在现有卡牌包编辑工程基础上，建议细化为：

my-cardpack/
├─ project.json
├─ cards/
├─ pools/
├─ sources/
│  └─ assets/
│     └─ char-anchor-001/
│        ├─ master.png
│        └─ asset.json
├─ profiles/
│  ├─ conversion/
│  │  ├─ portrait-rlcd-v1.json
│  │  ├─ portrait-eink6-v1.json
│  │  ├─ flat-art-rlcd-v1.json
│  │  ├─ flat-art-eink6-v1.json
│  │  ├─ ui-line-rlcd-v1.json
│  │  └─ ui-line-eink6-v1.json
│  └─ displays/
│     ├─ rlcd300x400-v1.json
│     └─ eink6-sim-v1.json
├─ build/
│  ├─ previews/
│  ├─ matrices/
│  ├─ assets/
│  │  ├─ rlcd300x400/
│  │  └─ eink6-sim/
│  ├─ manifests/
│  └─ reports/
└─ dist/
   └─ {packId}-{version}.chpack

约定：

sources/、cards/、pools/和 profiles/属于可编辑输入。
build/为可重复生成的中间结果，任何内容都不能成为唯一来源。
dist/只保存完成校验的发布包。
design-assets/仍是跨文档、跨卡包的设计资产库；只有入选母版才导入具体卡牌包。
导入时复制母版并记录原路径与哈希，避免卡牌包依赖工作区外的绝对路径。

4. `asset.json`契约

四类JSON的字段、严格校验、版本与迁移规则见图像资产与转换配置Schema规划。本节只保留接口示例。

每个母版旁保存一个资产说明，示例：

{
  "schemaVersion": 1,
  "assetId": "char-anchor-001",
  "assetClass": "portrait",
  "source": {
    "file": "master.png",
    "sha256": "<required>",
    "origin": "original-ai-assisted",
    "generationRecord": "<project-relative path>",
    "rightsRecord": "<project-relative path>"
  },
  "targets": {
    "rlcd300x400": {
      "displayProfile": "rlcd300x400-v1",
      "conversionProfile": "portrait-rlcd-v1"
    },
    "eink6": {
      "displayProfile": "eink6-sim-v1",
      "conversionProfile": "portrait-eink6-v1"
    }
  },
  "cropOverride": {
    "anchorX": 0.5,
    "anchorY": 0.42
  }
}

示例值不代表Schema已经冻结。原则是：资源身份、来源、目标屏幕和转换配置明确分离；裁切覆盖只记录与默认Profile不同的值。

5. 显示与转换配置分离

5.1 Display Profile

只描述硬件事实：

原生分辨率、旋转和有效显示区。
颜色索引和面板调色板。
像素格式、stride、位序、字节序和行对齐。
刷新等级与限制。

5.2 Conversion Profile

只描述内容处理策略：

portrait、flat_art或 ui_line。
裁切、缩放、gamma、对比度、锐化。
调色板映射、阈值和抖动算法。
预览和验收规则。

同一转换策略可以配合不同批次的Display Profile重新生成；更换面板不复制整套人物调参文件。

6. 命令规划

6.1 初始化

cardpack init <directory> --pack-id <id>

创建编辑工程和最小 project.json，不生成示例版权素材。若目录非空则拒绝，除非以后定义明确的导入模式。

6.2 导入RGB母版

cardpack asset import <image> --asset-id <id> --class portrait

行为：

读取图片但不修改原文件。
校验格式、色彩空间、尺寸和Alpha。
复制到 sources/assets/{assetId}/master.png。
生成或补全 asset.json。
记录输入哈希和来源字段缺失警告。
目标存在时拒绝覆盖；新版本必须明确指定版本或替换流程。

6.3 单资产转换

cardpack asset convert <assetId> --target rlcd300x400
cardpack asset convert <assetId> --target eink6 --display-profile eink6-sim-v1

默认读取 asset.json 和目标Profile。命令行参数只用于受控实验；参数覆盖必须写入构建manifest，不能产生“实际用了什么无人知道”的输出。

6.4 算法对比矩阵

cardpack asset matrix <assetId> --target rlcd300x400 --set rlcd-portrait-baseline
cardpack asset matrix <assetId> --target eink6 --set eink6-portrait-baseline

输出统一裁切、无单独美化的对比板和JSON报告。矩阵用于选择Profile，不直接进入设备包。

6.5 预览

cardpack asset preview <assetId> --target rlcd300x400 --overlay game-state-default

预览应展示：

RGB裁切结果。
逻辑目标图。
设备编码后反向解码图。
可选的体力、护盾、Token、焦点和锁定覆盖层。
尺寸、Profile、输入/输出哈希和 SIM 标记。

6.6 校验

cardpack asset validate <assetId>
cardpack display validate <profileId>
cardpack validate

层级：

asset validate：检查单项来源、目标、尺寸、调色板和编码往返。
display validate：检查Display Profile完整性和内部一致性。
cardpack validate：检查整个工程的引用、Schema、字体、卡池、资源、授权和构建状态。

6.7 色块测试

cardpack display swatches <profileId>

生成纯色色块、相邻边界、线宽、棋盘格和调色板索引测试资源，用于厂商工具与真机对照。

6.8 构建与检查

cardpack build --target all
cardpack inspect dist/<package>.chpack

build只接受通过校验的输入。inspect不解压执行内容，只读取manifest、索引、校验和、资源计数和兼容范围。

7. 人类输出与机器输出

所有命令默认提供简洁人类可读结果，同时支持机器模式：

cardpack asset validate char-anchor-001 --format json

JSON输出至少包含：

status：ok、warning或 error。
command和Schema版本。
输入、生成物和报告路径。
警告与错误代码。
是否发生文件写入。
使用的Profile和工具版本。

桌面管理器直接调用Python核心优于解析命令行文字；机器输出主要服务CI和外部脚本。

8. 安全和可逆性

转换命令绝不原地修改 master.png。
输出先写入同一目标目录下的staging文件，完成校验后原子替换构建结果。
来源资产默认不可覆盖；替换必须显式执行并保留旧哈希记录。
工具不执行卡牌包内脚本，不接受包内绝对路径和目录穿越。
build/可以重建，但清理命令必须只作用于已验证的项目内 build/，不接受模糊路径。
默认离线运行，不因构建触发网络下载或Image 2调用。
发布包签名前先完成文件长度、SHA-256、Schema和引用检查。

9. 缓存与增量构建

缓存键至少包含：

输入文件SHA-256
+ asset.json有效字段哈希
+ Conversion Profile哈希
+ Display Profile哈希
+ 转换核心版本
+ 设备编码器版本

任一项变化就重新生成对应目标。预览叠加层变化只重建预览，不重做未变化的底层量化资源。缓存命中不跳过最终引用和包级校验。

10. 错误等级

Error：阻止构建

缺少输入、重复ID、哈希不符或Schema不兼容。
输出尺寸错误、出现非法调色板颜色或编码往返不一致。
路径越界、未知像素格式或缺少目标Display Profile。
必填来源/授权状态不满足发布策略。

Warning：允许预览，默认阻止正式发布

使用 SIM 六色Profile。
母版分辨率不足、安全区可能被裁切或Alpha未明确处理。
使用资产级参数覆盖但没有填写原因。
尚无真机验收记录。

Info：不影响结果

缓存命中、生成物未变化或存在新的可选Profile。

11. 内部模块边界

未来实现建议按职责拆分，不让CLI、图像算法和设备编码互相调用细节：

cardpack/
├─ cli/          命令解析和结果展示
├─ schema/       project、asset、profile和manifest模型
├─ pipeline/     有向转换步骤和缓存
├─ imaging/      裁切、缩放、量化和抖动适配
├─ codecs/       CHB与未来六色像素格式
├─ preview/      PNG预览、状态覆盖和比较板
├─ validation/   规则、错误码和报告
└─ packaging/    .chpack构建、检查与安装

ImageMagick是 imaging/ 的一个基准适配器，不让其他模块拼接ImageMagick命令。未来替换为Pillow、厂商SDK或其他实现时，上层Schema和命令保持不变。

12. 分阶段落地顺序

T0：只冻结契约

冻结 asset.json、Display Profile、Conversion Profile和构建manifest的最小字段。
冻结命令名、输入输出位置和错误等级。
不实现桌面UI。

T1：RLCD纵向闭环

只实现 portrait、300×400、1-bit、CHB编码和反向解码。
使用 CHAR-ANCHOR-001 完成import、matrix、convert、preview、validate。

T2：六色模拟

增加六色 SIM Display Profile和调色板索引输出。
不将模拟Profile构建为正式发布资源。

T3：真实六色面板

导入真实Display Profile和厂商对照结果。
冻结六色像素格式并接入设备包。

T4：卡牌包与桌面管理器

cardpack build消费已验证资源。
桌面管理器复用Schema、pipeline、preview和validation，不复制算法。

13. 建议冻结与待决策

建议冻结

使用 cardpack 单一CLI，新增 asset、display 命名空间，不维护多个一次性转换工具。
编辑输入、可重建中间结果和发布包分目录管理。
所有配置使用JSON，路径以项目根目录为基准。
转换默认离线、不可原地修改母版、支持确定性缓存和反向解码验证。
Image 2生成与 cardpack转换分离，通过manifest连接。
先完成RLCD纵向闭环，再增加六色模拟和真实面板。

待决策

asset.json、Display Profile和Conversion Profile的最终Schema字段。
六色像素格式是否继续使用CHB容器及其PixelFormat枚举。
build中间结果是否默认纳入版本控制。
Python最低版本和依赖锁定方式。
CLI框架和Schema校验库。
未来桌面管理器是直接调用Python核心还是通过稳定服务接口调用。