# 皮肤格式与问题排查

## 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 中加入：

```json
"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 版本、系统、明暗模式与具体错误。不要仅提供一张最终效果图。