# 制作第一个 Agent 皮肤

皮肤只包含颜色 token、JSON 配置与可选位图，不允许 JS、CSS、HTML 或 SVG。你不需要读取 Agent 源码即可按本指南制作和安装。

## 先试用一个包

打开 [皮肤展示](https://plugins.eosaios.com/themes/?lang=zh)，下载 `.eos-theme`，在 Agent **设置 → 外观 → 皮肤 → 导入皮肤包** 中导入。展示站是配色和壁纸的界面示意，应用内效果以实际窗口为准。

## 创建最小目录

```text
my-skin/
  theme.json
  tokens/
    light.json
```

`theme.json`：

```json
{
  "schemaVersion": 2,
  "id": "studio.paper",
  "name": "Paper",
  "description": "温暖的浅色工作台",
  "author": "Your Studio",
  "license": "MIT",
  "version": "1.0.0",
  "appearance": { "light": "tokens/light.json" }
}
```

`license` 应填写你确实有权授权的许可，不能沿用示例给他人的图片授权。第三方 ID 使用自己的作者前缀，避免与官方 `eos.*` 冲突。

`tokens/light.json`：

```json
{
  "canvas": "#f5f3ed", "surface": "#ffffff", "surfaceSecondary": "#f0eee7",
  "overlay1": "#ffffff", "overlay2": "#eae7df",
  "border1": "#e3dfd4", "border2": "#d5d0c5", "border3": "#b7b0a2",
  "text": "#242a25", "text2": "#414c43", "text3": "#616b62", "text4": "#747d74",
  "brand": "#3a745b"
}
```

## 安装并调试

可以直接在应用中导入这个目录。选择皮肤后，检查侧栏、聊天正文、代码块、按钮、设置页、右侧面板及禁用/错误状态。拖动窗口宽度，确认文字与背景的对比度。

添加 `tokens/dark.json` 时也必须提供完整的 12 个必填 token，再在 `appearance.dark` 中引用。没有 dark 变体时，应用在深色模式使用内置深色主题；不会自动推算深色颜色。

每次重新导入前递增 `version`。同 ID、同版本重复导入会报错；同 ID 的多个版本以较高版本为当前版本。测试请使用自己的 ID，内置皮肤不能删除。

## 打包与分享

在 `my-skin` 目录中运行：

```bash
zip -r ../studio-paper-1.0.0.eos-theme theme.json tokens
```

有图片时将 `assets` 加入命令。包根必须直接是 `theme.json`，不能多包一层 `my-skin/`，也不要带入 `.DS_Store`、编辑器文件或 `__MACOSX`。`.eos-theme` 本质是 ZIP，也支持 `.zip`。

发布到你自己的下载站或仓库，附名称、版本、适用的 Agent 版本、亮暗预览、文件大小、SHA-256、许可与导入步骤。当前展示平台由官方维护，尚未提供作者上传、审核或自行上架入口。

macOS/Linux 可用 `shasum -a 256 studio-paper-1.0.0.eos-theme`；Windows PowerShell 用 `Get-FileHash -Algorithm SHA256` 计算校验值。

继续阅读 [格式与问题排查](reference.md)。