文档 — Paseo Skins

快速开始

在主题库中选择一款主题，进入模拟器检查首页、任务页、侧栏与窄窗口，然后复制一键换肤命令：

npx --yes github:huangguang1999/paseo-skins apply morning-mist --persist

第一次运行时，CLI 会读取公开 catalog、校验同源主题清单、下载图片并核对 SHA-256，再安装当前用户的持久 Guardian。关闭终端、退出 Paseo 或重启电脑后，主题都会自动恢复。若 Paseo 正在运行但没有开启本机 CDP，CLI 会要求你在工作完成后正常退出并重新打开，不会强制重启正在工作的 Agent。

没有桌面客户端。

本项目刻意只提供静态网站与开源 CLI。网页负责浏览和制作，CLI 负责本机换肤，两者职责清晰。

Theme v2

主题是声明式 JSON，不包含可执行脚本。核心字段包括：

{
  "$schema": "…/paseo-theme-v2.schema.json",
  "schemaVersion": 2,
  "id": "morning-mist",
  "version": "1.0.0",
  "name": "晨雾山水",
  "image": "morning-mist.jpg",
  "appearance": "light",
  "art": { "focusX": 0.78, "focusY": 0.5 },
  "colors": { "accent": "#66776f", "background": "#f2eee5" },
  "integrity": { "algorithm": "sha256", "sha256": "…" }
}

art

focusX 和 focusY 决定背景主体位置；home、workspace、utility 三个 opacity 分别控制不同路由的图片强度。

colors

accent、background、panel、panelAlt、text、muted、line 与 glow 构成可预测的主题色板。Studio 可从图片自动生成，再由你调整。

图片约束

支持 PNG、JPEG、WebP。
单图不超过 16 MB，单边不超过 16384 px，总像素不超过 5000 万。
推荐 16:9 横图，把视觉主体放在右侧 55% 区域，避开左侧导航。
公开投稿必须说明作者、来源和许可证。

Safe CSS

Safe CSS 是 Studio 中的可选视觉微调文本。验证器会拒绝远程资源、脚本表达式、固定覆盖层，以及隐藏界面或禁用交互的规则。Safe CSS 不应改变权限提示、安全界面和数据含义。

.paseo-skin-root {
  --paseo-accent: #d5b36b;
}

主题包

最小主题包由 JSON 清单和同目录图片组成。公开主题库会把 Paseo Theme v2 清单、未经修改的 DreamSkin 原背景图和来源说明打成 ZIP 供直接下载。来源说明保留原作者、许可证、下载地址、原包 SHA-256 与原图 SHA-256；上游 CSS 和脚本不会进入适配包。CLI 的 inspect 可以离线验证，verify 用真实 renderer 检查主题生命周期和布局安全。

my-theme/
├── my-theme.theme.json
├── background.webp
└── README.txt

安全边界

不 patch Paseo.app、app.asar、daemon 或 Agent 数据。
CDP 只监听 127.0.0.1，不得转发到局域网或公网。
远程主题必须使用 HTTPS，清单与图片必须同源，不执行远程 JavaScript。
pause / reset 会销毁 observer、overlay、style 与动态内联样式。
同一端口只允许一个 watcher，避免重复注入。

从预览到应用，每一步都可解释。