# AI 助手

FolderSkin 可以根据一段描述生成皮肤，有两种方式：

- **本地模型**在你自己的电脑上作画，完全免费。只需设置一次（FLUX.2 [klein] 4B，在 Mac 上要下载 4.6 GB，其他平台 5.2 GB），之后就能离线使用，不需要密钥，也不会向任何地方发送数据。它支持搭载 Apple 芯片、运行 macOS 14 或更高版本的 Mac，以及 Windows 和 Linux 电脑。
- **自带密钥**：你在某个服务商那里已经有账号，就把它的 API 密钥粘贴进来。密钥会保存在你电脑上的一个私有文件里，FolderSkin 会从你的电脑直接与这个服务商通信。

在**设置 → AI 服务商**里进行选择。打勾表示本地模型已经设置好，或者某个服务商已经有了密钥。

![设置中的 AI 服务商页面：本地模型和七个服务商，每项都打了勾或标着“无密钥”，下方是这台电脑上的模型](https://folderskin.app/docs/images/ai-providers.webp)

FolderSkin 没有服务器，没有代理，没有内置密钥，也没有靠补贴撑着的免费额度。使用密钥时，在你按下**生成**之前不会发送任何内容。发送的只有你的提示词、你选择的尺寸，以及你选的参考图。如果你要生成整个文件夹却没有选参考图，发送的就是 FolderSkin 自己的空白文件夹模板。

## 密钥存放在哪里

经过加密，存放在 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 的文件夹轮廓，而不是模型自己随意发明的文件夹。由于模板放在品红背景上，这种情况下总是走下文的抠像路线，即使模型本身能返回透明背景也一样。如果你自己附上了参考图，它会和以前一样被当作图案使用。

## 如何处理透明背景

模型分为两类，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 只发一个请求，绝不会自动重试。

## 构建与交叉编译

服务商层使用 `rustls` 实现 TLS，它的加密后端（`aws-lc-sys`）需要编译 C 代码。在各平台自己的 CI runner 上可以顺利构建，FolderSkin 的发布版本就是这样构建出来的。如果要从一种桌面系统交叉编译到另一种（比如在 Mac 上运行 `cargo check --target x86_64-pc-windows-msvc`），需要目标平台的 C 交叉编译工具链，否则会在 `aws-lc-sys` 的构建脚本中失败。工作区的其余部分不需要它也能交叉检查。

## 可能遇到的错误提示

| 提示 | 发生了什么 |
|---|---|
| “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” | 响应格式有误，或者返回的不是图片 |

## 用聊天助手画的文件夹

你也可以在 ChatGPT、Grok 或其他聊天助手里画一个完整的文件夹，再通过**添加你的照片**导入。请让它把文件夹画在纯 #FF00FF 背景上，或者透明背景上。FolderSkin 能识别这两种背景，会把图片抠出、裁边后直接作为图标使用，而不会再把它包进自己的文件夹里。其他图片都会被当作图案，包裹到模板上。确切的规则见 [ARCHITECTURE.md](https://github.com/prajwal-svm/folderskin/blob/main/docs/ARCHITECTURE.md#artwork-or-a-finished-folder)（英文），其中也解释了为什么在品红色纸上拍的照片仍然算作图案。

## 保存生成的皮肤

每款生成的皮肤一到手就会保存下来，和导入的图片一样，同时记下服务商、模型和你的提示词。重启之后，它仍然在皮肤库的**我的皮肤**里，在那里删除它就会把它从磁盘上删掉。文件存放的位置见 [ARCHITECTURE.md](https://github.com/prajwal-svm/folderskin/blob/main/docs/ARCHITECTURE.md#saved-skins)（英文）。如果写入失败（比如磁盘满了），这款皮肤会在本次会话中一直保留，不会丢失。

想把生成的皮肤分享给所有人，就把它们放进社区皮肤包：给它们打上标签，然后在应用里用**分享到社区**，或者用 `folderskin-tools packs make` 把一个装满渲染图的文件夹做成皮肤包。这两种方法 [PACKS.md](https://folderskin.app/zh-cn/docs/packs/) 里都有介绍，[SKINS.md](https://folderskin.app/zh-cn/docs/skins/) 则说明了图片是如何落到文件夹上的。