LAN Proxy Gateway · 皮肤开发 Skill

面向 AI agent 和人类开发者的主题 / 皮肤制作指南。 读完本文件即可从零创建一套完整皮肤，并通过 App 导入使用。

快速上手

1. 从内置皮肤导出模板

在 App 设置 → 外观主题 右上角点击「导出」，得到当前主题的 .json 文件。 或者用命令行直接复制示例模板：

cp skills/theme-dev/templates/starter-dark.json my-theme.json

2. 编辑 JSON

用任意编辑器修改颜色、圆角、阴影等参数（字段说明见下方）。

3. 导入并预览

在 App 设置 → 外观主题 点击「导入」，选择你的 .json 文件，即时生效。

4. 迭代调试

修改 JSON → 删除旧主题 → 重新导入，或直接编辑存储目录中的文件后切换主题刷新。

存储目录：~/.config/lan-proxy-gateway/themes/

JSON Schema

一个主题文件是一个 JSON 对象，包含以下字段（全部必填）：

{
    "id":              "my-theme",       // 唯一标识，英文+连字符，不能与内置冲突
    "name":            "我的主题",        // 显示名称，支持中英文
    "isDark":          true,             // 是否为深色模式（影响系统控件适配）

    // ── 基础色板（全部为 sRGB [R, G, B]，取值 0.0–1.0）──────────
    "canvas":          [0.08, 0.09, 0.11],    // 最底层画布背景
    "sidebar":         [0.10, 0.11, 0.13],    // 左侧导航栏背景
    "panel":           [0.13, 0.14, 0.16],    // 卡片 / 面板背景
    "panelRaised":     [0.16, 0.18, 0.20],    // 悬浮 / 弹出面板背景
    "border":          [0.26, 0.28, 0.32],    // 边框 & 分割线

    // ── 语义色（用于数据可视化和状态指示）────────────────────
    "cyan":            [0.30, 0.76, 0.66],    // 主强调色 — 链接、活跃状态、图表主色
    "coral":           [0.94, 0.45, 0.40],    // 警告 / 错误 / 拒绝
    "lime":            [0.55, 0.79, 0.40],    // 成功 / 健康 / 直连
    "yellow":          [0.94, 0.70, 0.32],    // 提醒 / 学习中 / 待处理
    "muted":           [0.60, 0.64, 0.70],    // 次要文字 / 占位符

    // ── 材质参数 ─────────────────────────────────────
    "radius":          3,           // 卡片圆角 (px)
    "radiusSmall":     2,           // 小组件圆角 (px)
    "borderWidth":     1.0,         // 边框线宽 (px)
    "shadowOpacity":   0.5,         // 卡片阴影透明度 (0=无, 1=最重)
    "shadowRadius":    12,          // 卡片阴影模糊半径 (px)
    "fontDesign":      "default",   // 字体风格: "default" | "rounded" | "serif" | "monospaced"

    // ── 画布渐变（可选视觉层次）────────────────────────
    "canvasGradient":  [            // 空数组 [] = 纯色; 2个色值 = 垂直渐变
        [0.10, 0.11, 0.13],
        [0.07, 0.07, 0.09]
    ]
}

字段详解

颜色角色在 UI 中的映射

材质参数对风格的影响

设计建议

配色对比度

• panel 和 canvas 之间需要可感知的明度差（建议 ΔL ≥ 0.03），否则卡片会"沉入"背景
• 深色主题中 border 亮度建议比 panel 高 0.10–0.15
• 浅色主题中 border 亮度建议比 panel 低 0.10–0.15
• muted 与 panel 需保证 WCAG AA 对比度（4.5:1），否则次要文字难以辨认

语义色一致性

• cyan 是全 App 出现频率最高的语义色，选一个高辨识度的色调
• coral 和 lime 应互为对立感知（暖 vs 冷 / 红 vs 绿），用于二元状态区分
• yellow 应与 coral 有明确区分（不要两者都偏红/橙）

深浅模式

• isDark: true 会让系统控件（滚动条、菜单）自动切换深色
• 深色主题的 canvas 建议 L ≤ 0.15；浅色建议 L ≥ 0.90
• 不需要同时提供深浅两版，每个 JSON 就是一个独立主题

内置主题参考

以下是 4 个内置主题的设计思路，可作为调色灵感：

通过「设置 → 导出」可获取它们的完整 JSON。

文件管理

内置主题不可删除，但可以导出后修改 id 和 name 做为自定义主题重新导入。

AI Agent 工作流

当用户请求 "帮我做一套 XX 风格的皮肤" 时：

1. 读取本 Skill 了解 JSON Schema 和设计建议
2. 导出一个接近的内置主题作为基线：选最接近的 isDark 和 fontDesign
3. 修改配色：根据用户描述的风格关键词确定色板
4. 写入 JSON 到 ~/.config/lan-proxy-gateway/themes/<id>.json
5. 切换主题：修改 UserDefaults appThemeID 或提醒用户在 App 设置中选择

# 直接写入自定义主题（无需通过 App 导入）
cat > ~/.config/lan-proxy-gateway/themes/my-theme.json << 'EOF'
{ ... }
EOF

# 提醒用户在 App 设置中切换到新主题
echo "主题已保存，请在 App 设置 → 外观主题中选择"

风格关键词 → 参数映射参考