EOS皮肤格式与问题排查
Manifest
| 字段 | 当前规则 |
|---|---|
| schemaVersion | 1 或 2；新包建议 2 |
| id | ^[a-z0-9][a-z0-9.-]{2,127}$ |
| version | 严格 SemVer，例如 1.0.0；不能是 v1.0.0 或 1.0 |
| name / description / author | 最多 64 / 256 / 64 个字符 |
| appearance.light | 必填，包内相对路径 |
| appearance.dark | 可选；提供则同样完整校验 |
| preview | 可选位图路径；应用设置卡片目前使用 token 小型界面预览，不依赖这张图片 |
| wallpaper | 仅 schema 1 的单张画布背景 |
| wallpapers | 仅 schema 2 的分区背景；不能与 wallpaper 混用 |
所有引用必须是包内安全相对路径。不要使用绝对路径、.. 或网络地址。
颜色白名单
两种模式的必填键：canvas、surface、surfaceSecondary、overlay1、overlay2、border1、border2、border3、text、text2、text3、text4。
可选键：brand、brandHover、brandActive、brandSoft、brandBorder、info、success、danger、warning；缺省使用宿主对应默认值。未知键会被拒绝。
值只接受纯色字面量：十六进制、rgb() / rgba()、hsl() / hsla() 或 transparent。不允许 url()、var()、渐变、字号、圆角或布局。尽量使用 #RRGGBB，减少不同颜色语法的浏览器差异。
Schema 2 壁纸
在 manifest 中加入：
"wallpapers": {
"chrome": {
"light": "assets/chrome-light.png",
"dark": "assets/chrome-dark.png",
"anchor": "left",
"fit": "cover"
},
"canvas": { "effect": "grid", "scrim": "rgba(12,23,20,0.15)" }
}
这是 manifest 的字段片段，需要放入完整 JSON 对象中，并将所引用的图片加入包内。
可选区域为 chrome（窗口底与壳层）、sidebar（侧栏）、canvas（聊天内容区）、panel（右侧面板）。壁纸至少给 light/dark 中一个，或给 effect；缺少一个明暗图片时沿用另一张。
anchor：center、top、bottom、left、right、left top、left bottom、right top、right bottom。fit：cover、contain、auto。scrim 为纯色遮罩。effect 为宿主预置的 drift、spotlight 或 grid；作者只能选择名称，不能注入自定义 CSS 或脚本。
各区域叠加与透明度由宿主控制。不要依赖固定窗口大小、内部类名或某个旧版透明度数值；在应用里分别检查聊天、设置与面板。
包限制
ZIP/目录只允许 .json、.png、.jpg、.jpeg、.webp。整包和展开内容不超过 20 MiB，最多 200 个条目，单文件不超过 8 MiB。声明为图片的文件必须是真实、可识别的对应图片，改后缀无效。
排查顺序
| 现象 | 检查 |
|---|---|
| 找不到 theme.json | 压缩包是否多了一层目录 |
| 非法 token / 缺少 token | 删除未知键，补齐所有必填键；dark 也要完整 |
| 图片无法导入 | 文件是否存在、路径大小写、真实格式与尺寸/大小 |
| 壁纸字段不允许 | schema 1 用 wallpaper，schema 2 用 wallpapers，禁止混用 |
| 导入后没变 | 是否已选择该卡片、是否在另一明暗模式、是否存在更高版本 |
| 重复版本 | 增加版本号，或删除自己可删除的旧包再导入 |
| 有颜色却看不到图片 | 核对区域与图片构图，再在实际窗口检查宿主表面叠加 |
分享问题时附去除私人图片的最小包、Agent 版本、系统、明暗模式与具体错误。不要仅提供一张最终效果图。