图像资产与转换配置Schema规划

项目	内容
文档版本	0.1
状态	建议冻结，尚未实现Schema文件
更新日期	2026-08-28
依赖	D-039、D-041；`asset-tool-interface-plan.md`
范围	`asset.json`、Display Profile、Conversion Profile、Build Manifest

1. 目标

Schema的作用不是增加填写工作，而是阻止以下问题进入批量生产：

RGB母版来源、授权或生成记录丢失。
六色屏换型号后仍误用旧调色板或像素编码。
同名Profile参数被修改，却无法判断哪些设备资源需要重建。
裁切和算法只存在于某个人的命令历史或图片编辑器里。
构建成功但输出尺寸、颜色索引、位序或输入版本不明。
JSON拼写错误被工具静默忽略。

建议采用四类独立Schema，互相以稳定ID引用，不把所有字段塞进一个大文件。

2. 四类Schema及职责

Schema	回答的问题	不负责
Asset	这是什么资产、母版在哪里、来源是什么、要生成哪些目标	面板物理参数和通用算法细节
Display Profile	目标屏幕是什么、原生像素和调色板如何编码	某张人物如何裁切和增强
Conversion Profile	某类内容如何裁切、缩放、量化和抖动	资产版权和面板批次
Build Manifest	这次实际使用了什么输入、配置、工具并生成了什么	可编辑设计意图

Asset、Display Profile和Conversion Profile是可编辑输入；Build Manifest只由工具生成，不人工维护。

3. 公共约定

3.1 ID

使用小写ASCII、数字和连字符。
建议正则：^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$。
ID一经被卡牌、卡池或发布包引用，不因名称、图片或参数变化而修改。
参数变化通过 revision 表达；语义上成为另一种资产或另一块屏幕时建立新ID。

3.2 路径

全部使用项目根目录相对路径。
JSON中统一使用 /，即使工具运行在Windows。
禁止绝对路径、盘符、UNC路径、..和空路径段。
构建manifest可以记录工作区外原始导入路径的脱敏提示，但发布包不得包含本机绝对路径。

3.3 版本

每个文件至少包含：

schemaVersion：字段结构版本，只在需要迁移时增加。
revision：同一ID的内容修订号，任何影响输出的修改都增加。
createdAt与 updatedAt：ISO 8601 UTC时间。

文件名不承载唯一版本事实，不能只靠 -v2-final 判断内容。

3.4 严格解析

已定义对象默认拒绝未知字段，避免拼写错误被忽略。
扩展信息统一放入 extensions，键使用反向域名或组织命名空间。
数值字段定义范围；颜色、哈希、枚举和ID使用明确格式。
工具读取失败时指出JSON路径和错误代码，不只显示“配置无效”。

4. Asset Schema

建议文件：sources/assets/{assetId}/asset.json。

4.1 最小字段

{
  "schemaVersion": 1,
  "assetId": "char-anchor-001",
  "revision": 1,
  "assetClass": "portrait",
  "createdAt": "2026-08-28T00:00:00Z",
  "updatedAt": "2026-08-28T00:00:00Z",
  "source": {
    "file": "sources/assets/char-anchor-001/master.png",
    "sha256": "<64 lowercase hex>",
    "mediaType": "image/png",
    "width": 2160,
    "height": 2880,
    "colorSpace": "srgb",
    "alphaMode": "none",
    "origin": "original-ai-assisted",
    "generationRecord": "manifests/generation/char-anchor-001.json",
    "rightsRecord": "manifests/rights/char-anchor-001.json"
  },
  "targets": {
    "rlcd300x400": {
      "displayProfileId": "rlcd300x400-v1",
      "conversionProfileId": "portrait-rlcd-v1"
    },
    "eink6": {
      "displayProfileId": "eink6-sim-v1",
      "conversionProfileId": "portrait-eink6-v1"
    }
  }
}

示例中的时间、尺寸和路径只展示字段，不表示文件已经存在。

4.2 `assetClass`

首版只允许：

portrait
flat_art
ui_line

后续若增加 hardware_render、document_hero 等只服务文档的类别，应与设备资源类别分开；不因为它们都是PNG就共用一套设备转换默认值。

4.3 `alphaMode`

none：完全不含Alpha。
straight：直通Alpha。
premultiplied：预乘Alpha。

进入设备转换时，含Alpha资产必须在Target或Conversion Profile中明确底色合成规则；不允许工具自行猜测白底或黑底。

4.4 来源与授权

origin建议允许：

original-human
original-ai-assisted
licensed
user-supplied
unknown

origin不是法律结论。公开发布时必须存在rights record，并由发布策略决定哪些状态可以通过。生成记录至少引用模型、提示、输入参考、生成日期和人工修改。

4.5 Target与Override

每个Target引用一个Display Profile和一个Conversion Profile。可选的资产级覆盖只允许经过批准的字段，例如裁切锚点、gamma和锐化，并要求填写：

{
  "value": 1.08,
  "reason": "face loses separation in RLCD preview",
  "reviewedBy": "<name-or-role>"
}

不允许用自由对象覆盖任意字段，否则Profile会失去约束作用。

5. Display Profile Schema

建议文件：profiles/displays/{profileId}.json。

5.1 状态

status建议允许：

simulation：临时调色板，只能设计探索。
provisional：基于厂商资料，尚未完成真机校准。
measured：包含指定批次的实测数据。
released：已通过真机和编码验收，可进入正式卡牌包。

正式发布默认拒绝 simulation 和 provisional。

5.2 几何

{
  "geometry": {
    "width": 300,
    "height": 400,
    "rotation": 0,
    "pixelAspectRatio": 1.0,
    "safeArea": { "x": 0, "y": 0, "width": 300, "height": 400 }
  }
}

宽高、方向和有效区属于硬件事实，不允许Conversion Profile覆盖。

5.3 调色板

每个颜色项建议包含：

稳定 colorId和设备 index。
厂商标称RGB值。
可选的实测Lab值、测量设备、光源、观察条件和面板批次。
是否允许用于高频快刷层。

模拟Profile可以只有标称值，但必须带明显状态。released六色Profile要求六个索引唯一、编码完整并有关联真机记录。

5.4 像素编码

至少记录：

pixelFormat
bitsPerPixel
pixelsPerByte
bitOrder
byteOrder
rowAlignmentBytes
strideBytes
顶到底、左到右方向

CHB文件头保存必要的自描述字段；Display Profile保存面板与编码器的完整契约。具体六色PixelFormat枚举仍待面板选型。

5.5 刷新能力

Display Profile记录能力，不记录页面行为：

支持的R1/R2/R3等级。
全刷和局刷支持情况。
每种模式允许的颜色、区域对齐和最小区域。
典型/最大时间、残影限制和是否需要周期清屏。

UI页面仍在设计规范中声明需要哪种刷新等级，由校验器检查需求与能力是否匹配。

6. Conversion Profile Schema

建议文件：profiles/conversion/{profileId}.json。

6.1 顶层字段

{
  "schemaVersion": 1,
  "profileId": "portrait-rlcd-v1",
  "revision": 1,
  "assetClass": "portrait",
  "targetFamily": "rlcd",
  "pipelineVersion": 1,
  "crop": {},
  "resize": {},
  "colorManagement": {},
  "preprocess": {},
  "quantize": {},
  "encode": {},
  "acceptance": {}
}

6.2 Crop

mode：cover、contain或 exact。
anchorX、anchorY：0～1。
safeMargin：可按像素或比例表示，但一个Profile内只能选择一种单位。
matteColorId：contain或Alpha合成时必须明确。

6.3 Resize

filter首版允许 lanczos、nearest。
人物和背景默认Lanczos。
原生像素UI只允许Nearest或直接生成目标尺寸。

6.4 Color Management与Preprocess

输入工作空间首版固定sRGB。
gamma、contrast、brightness、sharpen均定义合法范围和默认中性值。
自动直方图拉伸、CLAHE和降噪默认关闭；启用时必须有明确参数，避免工具版本变化造成隐式差异。

6.5 Quantize与Dither

method和 dither分开记录：

method：threshold、palette-remap。
dither：none、floyd-steinberg、bayer。
Bayer要求显式记录矩阵尺寸和强度。
Threshold要求显式记录阈值。

Atkinson和感知色差映射在验证证明需要后再进入枚举，不先为未采用算法增加长期兼容负担。

6.6 Acceptance

机器可验证项：

目标尺寸。
合法颜色或逻辑值集合。
是否允许Alpha。
编码往返必须一致。
最大文件大小。
是否允许资产级覆盖。

“人物好看”“面部可读”等人工判断保存在评审记录，不伪装成不可靠的自动评分。

7. Build Manifest Schema

建议输出：build/manifests/{assetId}-{target}.json。

Build Manifest由工具生成且不可手改，至少包含：

buildId、时间和状态。
assetId、Asset revision和输入SHA-256。
Display Profile ID、revision和文件SHA-256。
Conversion Profile ID、revision和文件SHA-256。
所有资产级覆盖及原因。
Python、Pillow、NumPy、OpenCV、ImageMagick和转换核心版本；未使用的工具明确为null。
pipeline步骤及每步关键参数。
逻辑输出、设备编码、反向解码预览和报告的路径、尺寸、媒体类型与SHA-256。
warnings、errors、缓存命中与真机验收引用。

Build Manifest不得包含API密钥、用户主目录、临时代理、完整本机绝对路径或无关环境变量。

8. 引用与交叉校验

构建前执行：

Asset引用的两个Profile必须存在且Schema有效。
Asset class必须与Conversion Profile的 assetClass一致。
Conversion Profile的 targetFamily必须与Display Profile一致。
Display Profile的原生尺寸必须与最终逻辑输出一致。
Conversion Profile使用的 matteColorId必须存在于目标调色板。
ui_line不能启用误差扩散。
六色输出的全部索引必须存在于Display Profile。
RLCD输出只能包含0/1逻辑值。
正式发布不允许引用 simulation Profile。
输入哈希变化但Asset revision未增加时报告错误，防止静默替换母版。

9. 版本与迁移

9.1 什么变化需要增加Revision

母版文件或裁切锚点变化。
调色板数值、面板批次或像素编码变化。
gamma、对比度、锐化、量化、抖动或编码参数变化。
影响输出的工具规则修复。

9.2 什么变化需要增加Schema Version

字段被删除、重命名或含义改变。
原来单值变为对象等结构变化。
新增必填字段且旧文件无法直接解释。

新增可选字段通常不需要破坏性升级，但实现仍应记录支持的Schema范围。

9.3 升级策略

工具支持当前Schema和上一版Schema读取。
cardpack upgrade显式写出新文件，默认先备份并生成迁移报告。
普通 validate和 build不得静默改写输入配置。
迁移只改变结构，不在同一步自动重新调色或替换母版。

10. JSON Schema与Python模型建议

对外契约建议采用JSON Schema Draft 2020-12，便于编辑器、CI、桌面端和非Python工具验证。Python内部模型可选择能导出兼容JSON Schema的成熟库，但JSON Schema文件才是跨语言契约，不把某个Python类的私有行为当标准。

选择Python模型库时验证：

严格未知字段检查。
枚举、正则、范围和判别联合类型。
清晰JSON路径错误信息。
稳定Schema导出。
迁移和自定义交叉校验的可维护性。

具体选择Pydantic、jsonschema或其他库留到脚手架阶段，不在方案阶段以流行度代替验证。

11. 版本控制建议

默认纳入版本控制：

project.json
cards/、pools/
sources/中的已选母版与Asset文件
profiles/
generation、rights和人工评审记录
少量固定回归金样及其预览

默认不纳入版本控制：

可完全重建的普通 build/输出
本地缓存和临时矩阵
未入选的大量探索图

正式 .chpack是否进入仓库由发布策略决定。即使不提交构建产物，也必须能从指定输入、依赖锁和Profile可重复构建。

12. Schema冻结顺序

先冻结Asset最小字段和路径规则。
以已知RLCD建立第一个Released Display Profile。
冻结 portrait-rlcd-v1 Conversion Profile。
用 CHAR-ANCHOR-001生成第一个Build Manifest样例。
根据实际闭环删减无用字段，再形成Schema v1。
六色面板确定后扩展Display Profile，不为了未知硬件提前冻结错误编码。

13. 建议冻结与待决策

建议冻结

Asset、Display Profile、Conversion Profile、Build Manifest四类Schema独立。
JSON严格解析，未知字段默认报错，扩展信息进入命名空间对象。
所有路径项目相对化并禁止目录穿越。
Display Profile记录硬件事实，Conversion Profile记录内容处理策略。
Build Manifest由工具生成，包含输入、配置、依赖和输出哈希。
对外采用JSON Schema Draft 2020-12，普通构建不静默升级配置。

待决策

ID正则和revision是否使用整数。
generation record与rights record的独立Schema。
六色PixelFormat枚举和CHB扩展方式。
Python模型/校验库。
金样图片和发布包是否进入Git。