AI 助手
FolderSkin 可以根据一段描述生成皮肤，有两种方式：
- 本地模型在你自己的电脑上作画，完全免费。只需设置一次（FLUX.2 [klein] 4B，在 Mac 上要下载 4.6 GB，其他平台 5.2 GB），之后就能离线使用，不需要密钥，也不会向任何地方发送数据。它支持搭载 Apple 芯片、运行 macOS 14 或更高版本的 Mac，以及 Windows 和 Linux 电脑。
- 自带密钥：你在某个服务商那里已经有账号，就把它的 API 密钥粘贴进来。密钥会保存在你电脑上的一个私有文件里，FolderSkin 会从你的电脑直接与这个服务商通信。
在设置 → AI 服务商里进行选择。打勾表示本地模型已经设置好，或者某个服务商已经有了密钥。
FolderSkin 没有服务器，没有代理，没有内置密钥，也没有靠补贴撑着的免费额度。使用密钥时，在你按下生成之前不会发送任何内容。发送的只有你的提示词、你选择的尺寸，以及你选的参考图。如果你要生成整个文件夹却没有选参考图，发送的就是 FolderSkin 自己的空白文件夹模板。
密钥存放在哪里
Section titled “密钥存放在哪里”经过加密，存放在 FolderSkin 自己的文件夹里，只有你的用户账户可以读取：
| macOS | ~/Library/Application Support/app.folderskin.desktop/keys.json |
| Windows | %APPDATA%\app.folderskin.desktop\keys.json |
| Linux | ~/.config/app.folderskin.desktop/keys.json |
密钥在写入之前会用 AES-256-GCM 加密。加密用的密钥由 keys.json 旁边 keys.secret 里的一段随机机密和这台电脑的硬件 ID 共同派生而来（HKDF-SHA256），所以单独拿到 keys.json 什么也看不出来，把两个文件一起复制到另一台电脑上也打不开：换了电脑，在新电脑上重新输入密钥就好。两个文件都以仅限所有者读写的权限（0600）创建，并以原子方式写入。有一件事任何文件都做不到：挡住一个已经以你的身份运行的程序，因为它能读取这两个文件。只有系统钥匙串能做到，代价就是下面说到的密码提示。
为什么不用系统钥匙串：macOS 会把保存的钥匙串项目与保存它的应用的确切签名绑定在一起。开源构建通常没有签名，或者只有临时（ad-hoc）签名，所以每次重新构建或更新，系统都会把它当成另一个应用，再次要你输入登录密码。一个刚下载的应用就弹窗索要密码，看起来就像恶意软件，可它偏偏不是。所以 FolderSkin 干脆完全不用钥匙串。
密钥只在发起请求的那一刻读取，绝不会出现在错误信息中，也绝不会返回给应用窗口。服务商对话框中的移除密钥会把它从文件中删除，删除 keys.json 则会移除所有密钥。
这是最重要的一个选择，但它和画质无关。
只要图案会让模型生成一张 1024 × 958 的平面图片，再由 FolderSkin 把它包裹到自己的文件夹模板上，和你添加照片时完全一样。几何形状由我们掌控，所以在每种图标尺寸下，每款皮肤都能彼此对齐。所有服务商都能做到这一点，包括不支持透明背景的那些。这是默认选项，大多数时候也是最好的选择。
整个文件夹会让模型直接在透明或可抠除的纯色背景上画出文件夹本身，这张图片会绕过合成器，直接成为图标。你放弃了像素级精确的几何形状，换来的是真正有立体感、还能突破文件夹上边缘的画面。
如果模型可以参考图片作画（OpenAI、Grok、Gemini），而你没有附上图片，FolderSkin 会把自己的空白文件夹模板作为参考图发过去：也就是我们的文件夹，涂成均匀的浅灰色，按请求的尺寸居中放在纯品红背景上（compositor::blank_template）。提示词会要求模型重画这个文件夹，保持它的轮廓、页签、纸边、大小和位置不变，并让品红背景保持纯色。这样得到的结果会保留 FolderSkin 的文件夹轮廓，而不是模型自己随意发明的文件夹。由于模板放在品红背景上，这种情况下总是走下文的抠像路线，即使模型本身能返回透明背景也一样。如果你自己附上了参考图，它会和以前一样被当作图案使用。
如何处理透明背景
Section titled “如何处理透明背景”模型分为两类，FolderSkin 会根据你选的模型走对应的路线：
- 原生 Alpha 通道。请求时要求透明背景，返回的 PNG 本身就是透明的。FolderSkin 只需裁掉透明的边距。
- 无 Alpha 通道。提示词要求把文件夹单独画在纯品红
#FF00FF背景上。FolderSkin 随后会去掉这种颜色，再去掉渗进柔和边缘里的品红（正是这一步让抠出来的图不会带一圈粉色光晕），最后裁边。之所以用品红，是因为它几乎不会出现在文件夹图案里，而且背景缺失时也能检测出来：如果边框不是品红，说明模型没有遵守指令，FolderSkin 会直接告诉你，而不是应用一个有问题的图标。
抠像代码位于 crates/folderskin-core/src/matte.rs，并有单元测试，连品红背景上画着真正粉色主体的情况也覆盖到了。
crates/folderskin-ai/src/prompts.rs 会把你的描述和一份约定组合成提示词。真正起作用的是结构方面的要求，而不是风格方面的：
- 图案提示词禁止画文件夹、图标、设备或样机，并把顶部八分之一和四周 6% 的边距留作空白，因为模板会把这些区域裁掉或弯折掉。
- 整个文件夹提示词会把结构定死：正好三个部分，一个页签、一道露出的纸边、一块前面板，并明确要求不要添加额外的层。少了这句话，模型几乎一定会画出叠在一起的文件夹和双页签。
- 模板提示词（
compose_on_template）与空白模板搭配使用：附上的图片就是要重画的那个文件夹，它的形状和构图保持不变，创意画在后面板和前面板上，品红背景保持纯色。 - 所有提示词的结尾都有一份严格的输出约定，写明像素尺寸、主体要单独呈现，以及抠像颜色或透明背景。
你可以修改这些模板。它们只是普通的 Rust 字符串常量，配有测试来确保关键语句都还在。
每个请求都由服务商计入你自己的账户。在你按下按钮之前，生成界面会显示该模型的大致价格。每按一次，FolderSkin 只发一个请求，绝不会自动重试。
构建与交叉编译
Section titled “构建与交叉编译”服务商层使用 rustls 实现 TLS，它的加密后端（aws-lc-sys）需要编译 C 代码。在各平台自己的 CI runner 上可以顺利构建，FolderSkin 的发布版本就是这样构建出来的。如果要从一种桌面系统交叉编译到另一种（比如在 Mac 上运行 cargo check --target x86_64-pc-windows-msvc），需要目标平台的 C 交叉编译工具链，否则会在 aws-lc-sys 的构建脚本中失败。工作区的其余部分不需要它也能交叉检查。
可能遇到的错误提示
Section titled “可能遇到的错误提示”| 提示 | 发生了什么 |
|---|---|
| “add your … API key first” | 这个服务商还没有保存密钥 |
| “that key was rejected by …” | 服务商返回了 401 或 403 |
| “… is rate limiting you right now” | 429，稍等一会儿再试 |
| “the model drew a scene instead of a folder on a plain backdrop” | 在整个文件夹模式下，背景没法抠除。请重试，或者改用只要图案 |
| “the provider returned something that is not an image” | 响应格式有误，或者返回的不是图片 |
用聊天助手画的文件夹
Section titled “用聊天助手画的文件夹”你也可以在 ChatGPT、Grok 或其他聊天助手里画一个完整的文件夹，再通过添加你的照片导入。请让它把文件夹画在纯 #FF00FF 背景上，或者透明背景上。FolderSkin 能识别这两种背景，会把图片抠出、裁边后直接作为图标使用，而不会再把它包进自己的文件夹里。其他图片都会被当作图案，包裹到模板上。确切的规则见 ARCHITECTURE.md（英文），其中也解释了为什么在品红色纸上拍的照片仍然算作图案。
保存生成的皮肤
Section titled “保存生成的皮肤”每款生成的皮肤一到手就会保存下来，和导入的图片一样，同时记下服务商、模型和你的提示词。重启之后，它仍然在皮肤库的我的皮肤里，在那里删除它就会把它从磁盘上删掉。文件存放的位置见 ARCHITECTURE.md（英文）。如果写入失败（比如磁盘满了），这款皮肤会在本次会话中一直保留，不会丢失。
想把生成的皮肤分享给所有人，就把它们放进社区皮肤包：给它们打上标签，然后在应用里用分享到社区，或者用 folderskin-tools packs make 把一个装满渲染图的文件夹做成皮肤包。这两种方法 PACKS.md 里都有介绍，SKINS.md 则说明了图片是如何落到文件夹上的。