AI 助手
FolderSkin 可以根据一段描述生成皮肤，有两种方式：
- 本地模型在你自己的电脑上作画，完全免费。只需设置一次（FLUX.2 [klein] 4B，在 Mac 上要下载 4.6 GB，其他平台 5.2 GB），之后就能离线使用，不需要密钥，也不会向任何地方发送数据。它支持搭载 Apple 芯片、运行 macOS 14 或更高版本的 Mac，以及 Windows 和 Linux 电脑。
- 自带密钥：你在某个服务商那里已经有账号，就把它的 API 密钥粘贴进来。密钥会保存在你电脑上的一个私有文件里，FolderSkin 会从你的电脑直接与这个服务商通信。
在设置 → AI 服务商里进行选择。打勾表示本地模型已经设置好，或者某个服务商已经有了密钥。
FolderSkin 没有服务器，没有代理，没有内置密钥，也没有靠补贴撑着的免费额度。使用密钥时，在你按下生成之前不会发送任何内容。发送的只有 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 则会移除所有密钥。
每张图片都是为某一种形状生成的。在输入框下方、模型名称旁边，有一个形状按钮，用一个小图显示当前是哪种形状。点击它，或者在输入框中输入 @，就能换一种：
- Mac 文件夹：FolderSkin 的文件夹，和 Finder 里显示的一样。
- Windows 文件夹：Windows 画出的文件夹。
- Linux 文件夹：GNOME 和 KDE 画出的文件夹。
- 磁盘：各系统显示的每一种磁盘，从 Mac 的启动磁盘到 Linux 的 U 盘或 RAID 阵列，都按 FolderSkin 画它们的样子来画，详见 DRIVES.md（英文）。图片会用在这个磁盘上，在皮肤库里和磁盘皮肤放在一起。
- 自由图标：单独的一样东西，比如吉祥物、物品或角色，外面没有文件夹。它可以原样用在任何文件夹上。
输入 @ 之后，接着输入名称的一部分（比如 @win），再按回车键或 Tab 键，也可以直接点击其中一项。形状按钮会随之改变，输入框里以 @ 开头的那个词也会消失。如果文件夹面板当前显示的是磁盘，新聊天就从这个磁盘开始，否则从文件夹面板当前用来展示皮肤的那种文件夹开始。
形状跟着聊天走。每张图片都按发送时选中的形状生成，打开以前的聊天时，会回到它最后一张图片的形状，保存下来的皮肤也会记下它是为哪种形状生成的。不论用哪个服务商，还是用本地模型，提示词、模板、尺寸以及结果怎样抠出来，都由形状决定。
只要图案，还是整个文件夹
Section titled “只要图案，还是整个文件夹”对文件夹来说，这是最重要的一个选择，但它和画质无关。磁盘也有同样的选择，分别是只要图案和整个磁盘。
只要图案会让模型生成一张与文件夹比例相同的平面图片（Mac 文件夹是 1024 × 960，Windows 文件夹是 1024 × 800），再由 FolderSkin 把它包裹到自己的文件夹上，和你添加照片时完全一样。几何形状由我们掌控，所以在每种图标尺寸下，每款皮肤都能彼此对齐。所有服务商都能做到这一点，包括不支持透明背景的那些。这是默认选项，大多数时候也是最好的选择。
整个文件夹会让模型画出文件夹本身，这张图片会绕过合成器，直接成为图标。你放弃了像素级精确的几何形状，换来的是真正有立体感、还能突破文件夹上边缘的画面。
如果模型可以参考图片作画（OpenAI、Grok、Gemini 和 FLUX.2，以及本地模型），FolderSkin 会把自己为这种文件夹准备的空白模板作为第一张图片发过去：文件夹涂成均匀的浅灰色，居中放在纯色的抠像背景上，整张图按文件夹本身的比例，长边最多 1024 像素（Base::blank）。提示词会要求模型重画这个文件夹，保持它的轮廓、页签、构成这种文件夹的各个部分、大小和位置不变，背景保持原样。提示词里从不点明抠像颜色，因为模型一旦听到品红，就会拿品红来画。之后 FolderSkin 会沿着文件夹本身的轮廓把画抠出来，所以结果会保留 FolderSkin 的文件夹轮廓，画面的颜色也能一直保留到边缘。如果模型挪动了文件夹，或者改变了它的形状，就改用抠像颜色来抠图。你添加的参考图排在模板后面，每张都带着你给它指定的用途，模型能接受几张就发几张。
磁盘也是这样。它的图案按正面的形状生成（U 盘的标签是竖长的，Windows 磁盘的顶面是横宽的），它的模板则是这个磁盘本身：正面涂成模板的灰色，其余部分（接口、色条或指示灯）照 FolderSkin 画的样子保留，所以画整个磁盘时，这些部分都会保留下来。轮廓只在模板放置磁盘的位置附近判断，因为较窄的磁盘四周会留下很宽的边距，背景颜色容易在那里偏移。
自由图标总是由模型整个画出来：一个完整的主体，位于正方形画面的正中，背景是透明的，或者是抠像颜色，然后再抠出来。
如何处理透明背景
Section titled “如何处理透明背景”FolderSkin 会根据你选的模型走对应的路线：
- 原生 Alpha 通道。请求时要求透明背景，返回的 PNG 本身就是透明的。FolderSkin 只需裁掉透明的边距。GPT Image 2.5 Flare 和 Sunburst 就是这样。
- 无 Alpha 通道。提示词要求把文件夹单独画在纯色的抠像背景上。FolderSkin 随后会去掉这种颜色，再去掉渗进柔和边缘里的抠像颜色（正是这一步让抠出来的图不会带一圈彩色光晕），最后裁边。背景缺失时也能检测出来：如果边框不是抠像颜色，说明模型没有遵守指令，FolderSkin 会把这张图片当作图案，用在自己的文件夹上，而不是应用一个有问题的图标。对于 Recraft，还会把这个颜色作为参数（
controls.background_color）告诉它，所以无论你要什么风格，它的背景都是纯色。
抠像颜色是品红 #FF00FF，因为它几乎不会出现在文件夹图案里。有两种情况会改用绿色 #00FF00。一是 Gemini，它画在品红背景上的主体周围会留下一圈暗红色的边。二是本该是粉色或紫色的内容，因为按品红抠图会把这些颜色一起抠掉：霓虹灯、70 年代喷绘、波普艺术和合成波这几种风格，以及用 FolderSkin 支持的任意一种语言提到粉色或紫色的创意（pink、lilac、rose、rosa、morado、ピンク、보라、粉红 等）。可绿色在文件夹图案里很常见（树叶、田野都是绿的），因此只有和图片边缘连在一起的绿色背景才会被去掉，并且以实际画出的那种绿色为准。画在文件夹上的绿色都会保留（matte::cutout_connected）。
在 FolderSkin 模板上画出的整个文件夹，这两条路线都不走。它会像上文说的那样，沿着模板本身的轮廓抠出来，只有文件夹挪了位置时，才会退回到按抠像颜色抠图。
抠像代码位于 crates/folderskin-core/src/matte.rs，并有单元测试，连品红背景上画着真正粉色主体的情况也覆盖到了。
你的文字从不会被改写。crates/folderskin-ai/src/recipe.rs 会把一张图片需要的一切汇集成一份配方：你的创意、形状及其要保留的部分、风格、要写的文字、你的图片和每张图片的用途，以及主体周围放什么。然后由 prompts.rs 按每一类模型最能读懂的方式，把这份配方写成提示词，顺序始终相同：画什么、看起来什么样、怎样构图、图片、文字，以及不要画什么。
- OpenAI 和 Gemini 收到的是带小标题的分行文字（Style、Composition、Lettering、Constraints），图片依次称为 image 1、image 2，以此类推。
- Grok 收到的也一样，只是图片按 Grok 自己的叫法称为
<IMAGE_0>、<IMAGE_1>。 - FLUX（Black Forest Labs 和本地模型）收到的是一段平实的文字，主体放在最前面，也不写任何关于不要画什么的指令，因为 FLUX 没有负面提示词，你让它避开什么，它反而会画出什么。本地模型的提示词会控制在它的文本编码器能读取的 400 个 token 以内，必要时会把风格缩短到只剩媒介。
- Ideogram 和 Recraft 收到的是一份简短的设计说明，文字要求放在靠前的位置。
- Stability 收到的是一份简短的清单。Stability 和 Ideogram 都通过负面提示词收到不要画的内容（见下文）。
真正起作用的是结构方面的要求，而不是风格方面的：
- 图案提示词要求画一张连贯完整、铺满画面的图，主体要大，放在中间，文件夹页签挡住的那一条只留给天空或纹理，因为模板会把它裁掉或弯折掉。Windows 文件夹和 Linux 文件夹还要让左上角保持空白。磁盘没有页签，所以它的图案只要求主体周围留出一点空白。
- 整个文件夹提示词会从后往前说出文件夹的各个部分，以及哪些地方保持原样：Mac 文件夹唯一的页签和那道浅色纸条，或者 Windows 文件夹上那道弧形的台阶。少了这些，模型几乎一定会画出叠在一起的文件夹和双页签。磁盘则按它自己的各个部分来描述，比如 U 盘的插头、蓝色机身和挂绳孔。
- 自由图标提示词要求画一个完整的物体，在正方形画面里居中，不被裁切，周围没有地面、风景或边框。
- 参考图在提示词里按编号和用途来指明。主体图里的人或物要保持可辨认，风格图只借用它的媒介、色调、光线和质感，不取其中的任何内容，配色图只用它的颜色。
- 不要画的内容会针对形状和风格来写：边框、画框、水印和签名始终排除，文字在你没有要求时排除，这种风格的俗套元素（比如木版画里的富士山）在你的创意没有要求时排除，写实风格还会排除剪贴画式的效果。
- 所有提示词都不写尺寸。模型不会照着读到的像素数来画，所以尺寸放在请求本身的参数里（见下文）。
测试会针对每一类模型和每一种形状，确认那些关键语句都在。配方带有版本号（RECIPE_VERSION），所以每款皮肤都能说明自己是由哪个版本的配方生成的。
在输入框中输入 /，可以看到分成五组的三十种风格：照片与 3D、材质与工艺、绘画与素描、版画与印刷，以及数字与平面。输入名称的一部分可以缩小列表范围。风格会单独放在输入框旁边，从不写进你的文字里，所以你的创意一字不改，风格接在它后面加上。点风格上的 x 就能把它去掉。
每种风格都是 crates/folderskin-ai/src/styles.json 里的一项，应用、命令行（folderskin ai styles 会列出全部风格）和生成提示词的代码读取的都是这个文件。每一项包括风格的名称、一句话描述、提示词里描述它的文字（先是媒介，然后是技法、光线、色彩和质感，从不出现艺术家的名字）、它怎样呈现文字、它常会擅自加上的东西、结果应当通过的三项检查，以及各个服务商为这种风格准备的预设（如果有的话：Stability 的风格预设，以及 Ideogram 的风格预设或风格类型）。早期版本的旧风格名称仍然可用：travel 现在是旅行海报（screenprint），ukiyoe 是木版画，diorama 是移轴微缩。
同一个菜单里还有可以作为起点的创意（每条只有主体，不带风格）和我的提示词。新聊天里输入框下方的风格按钮也是同样的用法：每点一次，输入框里就会换上另一条创意，这个按钮的风格也会放到输入框旁边。
把想放在皮肤上的文字写在引号里：一只看地图的狐狸，写有“ESCAPE”字样。FolderSkin 会原样写出引号里的内容，对能读懂指令的模型，还会逐个字母拼出来。文字只写一次，用符合这种风格的字体，并按形状安排位置：放在文件夹上时横跨前面板中部，放在自由图标上时写在物体上或物体下方。没有引号时，提示词会要求画面上不要有任何文字。文字最好只有一两个短词，因为长文字还是会画得乱七八糟。
在 / 菜单里选保存为提示词，就能把输入框里的内容连同它的风格一起保存下来，名字由你来起。之后它会列在我的提示词下面：选中它，输入框里的文字和旁边的风格就会重新填好。如果输入的名字已经用过，FolderSkin 会先告诉你，再替换原来那条提示词。点你的提示词旁边的 x 可以移除它，之后几秒钟内还能撤销。
保存的提示词以技能（skill）的形式存放在 skins 文件夹旁边的 skills.json 里，格式是 crates/folderskin-ai/src/skill.rs 所描述的 folderskin.skill/1。skins 文件夹在哪里，见 ARCHITECTURE.md（英文）。技能把图片画的是什么（idea）和看起来什么样（base_style，或者它自己的画法描述 treatment、配色 palette 和光线 light）分开保存，所以一种保存下来的风格可以搭配任何创意。每个技能在写入之前都要经过检查。名称不能超过 60 个字符，也要有可保存的内容。风格必须是 FolderSkin 已有的一种。它自己的画法描述要有 8 到 60 个词，并且告诉模型该怎么画，而不是不该画什么。整个技能不能超过 4 KB。如果提示词把某个人当作风格（“in the style of”加人名，或者“by”加人名），保存前会先提醒你一句，因为描述技法的效果更好。
添加到提示词里的图片默认用作主体。点击它，可以改作风格（只借用画风，不取其中的内容）或配色（只用它的颜色，其他都不用）。图片会按这个顺序排在模板后面发给模型，提示词会按编号和用途逐一说明每张图片。
发给各个服务商的内容
Section titled “发给各个服务商的内容”crates/folderskin-ai/src/request.rs 严格按照各服务商 API 参考文档的写法构建每个请求，服务商有官方 SDK 的，还会对照 SDK 核对。它的测试会逐个字段检查每个请求。crates/folderskin-ai/tests/providers.rs 里还有一个测试，会把每个请求发到你电脑上运行的一个模拟服务器，这个服务器按服务商文档说的方式应答。这样，请求方法、地址、放密钥的请求头、内容类型和每个字段，都按实际传输的样子核对过。
这些选项都通过各服务商自己的参数传递，绝不写进提示词的文字里。尺寸就是所选形状需要的尺寸（Mac 文件夹的图案是 1024 × 960，Windows 文件夹的图案是 1024 × 800，整个文件夹按文件夹本身的比例，自由图标是正方形）。服务商接受任意尺寸时就原样发送，不接受时就发送它提供的最接近的尺寸或宽高比：
| 服务商 | 请求 | 尺寸 | 另外发送 |
|---|---|---|---|
| OpenAI | JSON 发到 images/generations，或者用表单发到 images/edits，每张图片作为 image[] | 原样发送，按 16 像素取整（1024 × 960） | quality：Flare 用 high，Sunburst 用 max，GPT Image 2 用 medium，这样价格事先就能确定 |
| xAI Grok | 只用 JSON，图片以 data URL 的形式放在里面（image，多张时用 images） | 最接近的 aspect_ratio，或者模板自身的画幅 | |
| Google Gemini | JSON 发到 generateContent | generationConfig.imageConfig：1K，加上最接近的 aspectRatio 或模板的画幅 | responseModalities: ["IMAGE"] |
| Black Forest Labs | JSON，图片放在 input_image、input_image_2 等字段里 | 原样发送，不超过一百万像素（FLUX.2 按百万像素计费，不足一百万也按一百万算） | 关闭提示词改写（disable_pup，flex 上是 prompt_upsampling: false） |
| Recraft | JSON | V4.1 尺寸列表里最接近的一项 | PNG 输出，以及作为 controls.background_color 的抠像颜色 |
| Stability AI | 表单 | 最接近的 aspect_ratio | 负面提示词，风格有对应预设时再加上风格预设 |
| Ideogram | 表单 | 3.0 提供的分辨率里最接近的一项（1024 × 960） | 关闭 Magic Prompt，加上负面提示词，以及风格类型或预设 |
负面提示词会排除文字（除非你要求加文字）、水印和签名，以及所选风格容易多加的东西。OpenAI、Gemini 和 Grok 没有负面提示词，所以它们的提示词会直接用文字说明同样的要求。
已移除的模型
Section titled “已移除的模型”在某个模型还能选的时候保存下来的选择，会改到接替它的模型上。皮肤则会保留生成它的模型的名字。
| 原来 | 现在 | 原因 |
|---|---|---|
| OpenAI GPT Image 1 | GPT Image 2 | OpenAI 于 2026 年 10 月 23 日停用它 |
| Gemini 2.5 Flash Image | Gemini 3.1 Flash Image | Google 于 2026 年 10 月 2 日停用它 |
| FLUX 1.1 Pro | FLUX.2 pro | 上一代模型，不接受图片输入 |
| Recraft V3 | Recraft V4.1 | 上一代模型，提示词最多 1,000 个字符，比 FolderSkin 自己的指令还短 |
Ideogram 4.0 暂时还没有提供：它会改写所有用文字写成的提示词，而 FolderSkin 要让你的创意保持你写下的原样。
每个请求都由服务商计入你自己的账户。在你按下按钮之前，生成界面会显示该模型的大致价格，这个价格是按 FolderSkin 发送的参数，从服务商的价格页面上查来的。有些服务商连收到的图片也要计费（xAI、Black Forest Labs），在这些服务商那里生成整个文件夹会稍贵一些。每张图片下方的“详情”会显示服务商报告的这次请求的费用（xAI、Black Forest Labs、Recraft）或用量（OpenAI、Gemini）。
每按一次，FolderSkin 只发一个请求，绝不会自动重试。服务商没画出图片就结束时也是这样，Gemini 有时就会这样（NO_IMAGE）：聊天里会说明情况，并提供重试，只有你按下它，才会再次发送请求。
构建与交叉编译
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 …” | 服务商拒绝了这个密钥 |
| “… is rate limiting you right now” | 429，稍等一会儿再试 |
| “… finished without painting a picture” | 服务商既没有返回图片，也没有说明原因（Gemini 的 NO_IMAGE）。请重试，或者换个说法描述创意 |
| “… declined that prompt: its filter blocked the picture” | 服务商的安全过滤器拦下了提示词或图片，比如 Stability 返回的模糊图片，或 Ideogram 的安全检查。请换个说法 |
| “… said: … (error 400)” | 服务商的原话，按收到的样子显示。如果里面提到了 FolderSkin 发送的某个字段，值得反馈一下 |
| “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（英文）。如果写入失败（比如磁盘满了），这款皮肤会在本次会话中一直保留，不会丢失。
它还会在皮肤索引里的 recipe 下记下自己是用什么做出来的，这样每个结果都能追溯到它的提示词，也能重新生成：发送时一字不差的提示词、负面提示词（仅限支持它的服务商）、风格、要写的文字、每张图片的用途和它的哈希值、模板及其版本（mac-folder/1）、抠像颜色，以及配方的版本。
切换到其他界面时，聊天里的文字和图片都会保留，包括还在生成的图片。FolderSkin 重新打开时会开始一个新聊天。之前的聊天都在聊天列表里，每个都保持它当初所用的形状。
想把生成的皮肤分享给所有人，就把它们放进社区皮肤包：给它们打上标签，然后在应用里用分享到社区，或者用 folderskin-tools packs make 把一个装满渲染图的文件夹做成皮肤包。这两种方法 PACKS.md 里都有介绍，SKINS.md 则说明了图片是如何落到文件夹上的。