v0.4.1 — 配置简化

亮点

• 配置模板更短、更清晰：.env.example 约 50 行，Compose 直接读取 .env
• 移除无效的 ai.referenceMode = "assetId" 选项与死代码
• 本地/生产配置升级无需改 Compose 文件

维护版本：简化环境变量与 Compose 模板，清理无效配置项。

变更

• 简化配置流程：.env.example 由 86 行压缩到约 50 行，按「安全 / 服务 / 限流 / AI / 邮件」分组；Compose 改用 env_file: .env，新增环境变量不再需要改 compose 文件。
• 清理默认配置：prompt-config.default.json 移除空占位密钥与重复开关（apiToken / enableAuth / apiKey），密钥统一走 .env；移除无效的 ai.referenceMode = "assetId" 选项与相关死代码。
• 更新 vite.config.ts、playwright.config.ts 中的过期注释，移除未使用的 dist-web 构建配置。

v0.4.0 — 首个公开版本

亮点

• 仓库与 GHCR 镜像转为 Public
• CodeQL 发现并修复 packId 路径穿越（升级到本版本）
• 新增 CodeQL、Dependabot、Secret Scanning、分支保护与第三方许可说明

首个公开版本：仓库与 GHCR 镜像转为 Public，补齐许可证、隐私政策、安全扫描与发布流程。

新增

• 图片编辑历史版本（查看 / 回退 / 随包导出）：单张图每次编辑或重生成都会记录上一版，卡片上的「版本 N」可打开历史面板查看每一版（缩略图、时间、修改要求）并回退到任意一版（回退只移动当前指针，不新增版本）。历史版本随 ZIP 一起导出到 history/<名称>/vN.<ext>（metadata.json 的 files[].versions[] 记录），重新导入会重新入库并重映射 assetId；GC 也会保护这些版本，不会被当孤儿清理。
• 参数化系列模板：极简蜡笔：新增风格「极简蜡笔涂鸦」与提示词预设「极简蜡笔」
  （id: minimal-crayon）。预设 = 1 段固定画风的 Master Prompt + 24 组带
  眼睛/嘴巴/手臂/姿势/辅助/文字 字段的情绪参数，对应「1 个 IP + 1 个模板 + 24 组情绪参数 = 24 张风格统一的表情包」。
  主体不写死：角色一律以参考图为准，人、猫、兔子或任意吉祥物都能复用。
• 统一透明背景：全部 13 套预设与 templates.sticker 要求纯透明背景（透明 PNG / alpha），适配亮/暗主题显示。
• 自定义提示词支持「追加 / 覆盖」：新增「自定义用法」下拉（promptMode），追加 = 预设 + 自定义，
  覆盖 = 只用自定义；随 metadata.json 记录，ZIP / 历史还原时一并回填。
• 提示词预设支持自带 style 与 emotions：选中预设时，前端自动切到推荐风格，后端用预设自带的
  情绪/动作集覆盖全局 emotions（整包生成与单张重生成都生效）；出厂不替用户随机选择，未声明则回退全局。
  这套结构可直接复用于后续任意「一个 IP 一套表情」的参数化系列。
• 风格选项成为真正的模板（global.stylePrompts）：新增「风格名 → 详细风格描述」映射，编译时把{{style}}展开成它。内置 13 种风格各有描述（如「极简蜡笔涂鸦」对应 Minimalist Kawaii Sticker / Crayon Doodle 关键词），同时消除「预设里写了画风、又选了风格」的重复描述。

变更

• 提示词拼接统一入口：新增 src/services/generate/promptBuilder.ts，贴纸 / 扩展资源 / 参考图三条路径由 buildStickerPrompt / buildExtraPrompt / buildReferencePrompt 统一拼接，最终结构固定为「内容 → 表情与动作 → 画面风格 → 背景 → 构图 → 负面约束（Avoid:）」。同步修复：未选风格时不再写出「画面风格：默认」（回退到 global.styles[0]）；全局负面去掉与「情侣互动」双主体冲突的「多人」（改「人群 / 多余角色」）；扩展资源补上「画面类型 / 构图 / 比例」，且不再混入贴纸专用的透明背景 / 主体居中段。
• 清除提示词/风格残留重复：
  • 预设去掉残留风格词：「情侣互动」不再写「Q 版」、「沙雕搞怪」不再写「大头小身」（比例/画风统一交给风格）。
  • 「期待」「庆祝」在 global.emotions 里重复出现两次，改为各自唯一。
  • 风格描述去重：「3D 卡通」不再写 clay-like（与「黏土 3D」撞车）、「国潮风」不再写 flat（与「扁平插画」撞车）。
  • 透明背景从 global.negativePrompt 移到 templates.sticker：它是贴纸专用规则，放全局会误伤封面/横幅/参考图（那些需要背景）。
• 移除死配置 global.prompt：预设 + 自定义迁移后已无人读取，删除字段与类型，避免误导。基础正向提示词一律来自「提示词预设 + 自定义」。
• 极简蜡笔主体段不再指定风格：去掉「转译为 Q 版形象 / 大头小身 / 四肢短小圆润」等风格描述，主体段只保留身份与特征一致；形象风格统一由所选风格（global.stylePrompts）决定。
• 统一预设提示词结构：13 套预设重写为同一格式 主体：…；主题：…；动作：…；元素：…，只写内容（不写画风/背景/构图）；背景透明、主体居中、完整不裁切、辅助元素不超过 2 个等通用规则收敛到 templates.sticker。新增预设按同结构填写，配套契约测试会校验字段与顺序。
• 预设不再重复写画风：「极简蜡笔」预设把原本内置的画风段移交给 global.stylePrompts，同一段风格只在编译时注入一次，避免与「风格选择」重叠/冲突。{{style}} 现为详细描述，另提供 {{styleName}} 取原始风格名。

修复

• 安全加固（CodeQL 发现）：packId 增加 URL 安全白名单，拒绝 ../ 等路径穿越（下载 / 还原 / 删除 / 列表统一校验）；.env 写入拒绝换行并正确转义反斜杠，避免键值注入或写坏配置。
• 编辑图片不再强制要求基础提示词：mode=edit 是图生图（主体以当前图片为准），现在「未选预设 + 自定义为空」也能编辑；只有 mode=regenerate 仍要求非空提示词（resourceSchema 用 superRefine 区分）。服务端 single.ts 对空提示词做了兜底。
• 历史还原 / 刷新还原现场更完整：还原 AI 生成的历史包现在会还原「创建方式（AI 生图 / 导入已有图片）」、AI 提供商、预设提示词、自定义提示词、promptMode、风格与贴纸数量。修复了：还原时创建方式被硬编码为「导入」；用了预设却把合并后的整段提示词塞进自定义框（重复）；刷新后 promptPreset 未随 localStorage 复原；localStorage 未持久化 generation/creationMode。
• 编辑单张图片不再新增历史记录：POST /api/packs 支持可选 packId（须归属一致），重建时原地更新同一份清单并保留 createdAt；前端重建打包会带上原 packId。此前每次编辑/单资源重生成都会用 nanoid() 新建一个包，历史与服务端对账后旧包又会重新出现，导致记录不断堆叠、旧包在磁盘残留。归属不一致或 packId 不存在时仍退回新建，避免覆盖他人或让客户端任意指定 ID。
• 告警风暴与「看不出原因」一并修复：
  • 错误率告警此前把 4xx（404/401/400/429、扫描器）也算作错误，导致「错误率过高」被客户端噪声频繁触发；默认规则现改为只统计 5xx（serverErrorRate，阈值 2%），4xx 另设 clientErrorRate 且默认关闭；旧 alerts-config.json 启动时自动迁移。
  • 修复回滞死区：值卡在阈值 90%～100% 之间时告警永不恢复、每过一个静默期就重推；现只要不再高于阈值即恢复。
  • 修复空闲期指标冻结：60s 滚动窗口此前只在收到 /api/* 请求时推进，没有流量后 errorRate 会永久停在最后一次采样值，告警既不恢复也不再停止通知。现由 1s 定时器持续推进窗口，读快照时也会先推进到当前时刻，空闲超过一个窗口后指标自动归零并恢复告警。
  • 错误率规则新增 minSamples（默认 20）：窗口内请求数不足时视为无数据，避免低流量下 1 个 5xx 就被放大成 100% 并锁死告警。
  • 通知节流改为按告警记录持久化的 lastNotifiedAt + max(规则 silenceMs, 全局 notificationInterval)，重启不再立即重推；新增「恢复通知」（触发/恢复各一次）。
  • 告警消息与 webhook 附带归因：出错路由、5xx/4xx 拆分、状态码分布、排查建议；后台告警列表同步展示。
• 生成中途失败时保留已成功的图片：此前失败路径会 renderPreview([], "error") 清空预览，导致本轮已经成功生成并展示过的贴纸全部消失。现在只在“一张都没成功”时才回到错误占位；有部分成功则保留它们并提示“已成功 N 张仍可预览”。
• AI 超时不再只是「前端不等了」：services/ai/client.ts 的超时现在会与任务取消 signal 联动，超时即 abort 底层 HTTP 请求。此前超时只 reject Promise、请求仍在后台跑完，且会被判为可重试，默认 retryMax: 3 时一张图最多可能叠出 4 个仍在计费的请求。现在超时会真正中断，避免额外费用；用户取消仍原样透传、不重试。

安全

• 公开仓库安全基线：新增 CodeQL 静态分析、Dependabot（npm + GitHub Actions）、
  Secret Scanning 与 Push Protection；CI / Docker / CodeQL 使用的 Action 全部固定到提交 SHA。

文档

• 公开前合规清理：统一许可证表述为 Apache-2.0（修正服务条款中的 MIT 文本）；隐私政策与帮助页改为如实描述默认 30 天保留期、6 小时巡检与孤儿素材回收策略；移除商业调研、运营策略与内部交接材料；仓库元数据改为 GitHub 地址。
• README 与文档体系重构：README 收敛为落地页（能力、平台、快速开始、文档导航、FAQ），功能细节下沉到文档。
• 新增 使用手册：按「创建 → 生成 → 导入 → 编辑 / 还原 → 下载 → 后台」组织完整操作流程。
• 新增 部署指南：从运维手册拆出 Docker / 裸机 / 反向代理 / 安全基线 / 升级与上线检查清单。
• 新增 路线图：把原架构文档中的 P1–P6 待办与目标目录独立成可认领清单；架构文档只保留当前实现。
• 重写 文档中心：按角色给出阅读路径，明确活文档 / 只读材料 / 事实来源与维护规则。
• 运维手册聚焦日志、存储清理、备份、监控告警、压测与排障；开发指南修正前端切片与目录说明。
• 移除易过期内容：README 不再嵌入会随 UI 迭代过期的截图；文档规范明确不收录界面截图 / 录屏，
  易变的功能数量、RPS、版本号改为引用配置参考 / CHANGELOG 或直接给命令。

v0.3.0

新增

• 多套提示词预设 + 提示词自定义互补：内置 12 套预设（日常聊天 / 职场吐槽 / 萌宠拟人 /
  情侣互动 / 节日祝福 / 沙雕搞怪 / 校园学习 / 游戏电竞 / 吃货美食 / 运动健身 / 旅行出游 /
  暖心治愈），在「配置与信息」下拉选择后，与「提示词自定义」拼接成最终提示词（可只填其一）。
  不做随机选择；可在 prompt-config.json 用 promptPresets 整体覆盖。
• 风格扩展到 12 种：在原有 6 种基础上新增手绘涂鸦 / 水彩风 / 软萌毛绒 / 黏土 3D /
  极简线条 / 复古漫画。

变更

• AI 提供商选择器前移：从第 3 步「配置与信息」移到第 1 步；选择「AI 生成」后即可确认提供商，
  第 1 步顺序调整为「创建方式 → AI 提供商 → 目标平台」，「配置与信息」保留 提示词预设/自定义、
  风格 / 数量 / 元数据。
• 提示词不再是「上传后自动填一整套」：改为「提示词预设（可选）+ 提示词自定义」，由用户显式选择。

修复

• 非微信平台（Telegram / WhatsApp）导入失效：导入接口从 req.body 取 presetId，
  但 multipart 下 req.body 为空，导致总是回落到微信、以「至少 8 张」拒绝。现改为从 URL
  query 读取（前端已带上 ?presetId=）。此前这两个平台导入完全不可用。
• 非微信平台导入放宽输入格式：Telegram / WhatsApp 此前只允许选择 PNG / WebP；现与微信一致
  支持 PNG / JPG / WebP / GIF，服务端统一转为平台格式。
• WhatsApp 数量上限对齐：由 50 改为 30（与前端及 WhatsApp 实际限制一致）。
• 提示词去掉写死的「微信」「240px」：global.prompt 与 templates.sticker 改为平台中立，
  为 Telegram / WhatsApp 生成时不再带微信语境。
• 导出包完整记录生成现场：metadata.json 的 generation 新增 promptPreset（预设 id）与
  promptCustom（自定义文本），风格仍记在 generation.styles；修正此前从 ZIP / 历史还原时
  提示词不会回填到输入框、预设下拉也无法恢复的问题。旧包（无这两个字段）仍能还原，
  只是把 prompt 当自定义文本回填。

完整改动见 CHANGELOG.md。

v0.2.0 · 文档重建 / 免源码 Docker 部署 / 后台与 e2e 修复

[0.2.0] - 2026-10-06

自 0.1.0 起共 100+ 次提交，按主题归纳。

新增

• AI 生成参考图：POST /api/generate/reference，用文字直接生成一张参考图（文生图），
  不再要求必须先上传图片；返回值与上传接口一致，可直接进入整套生成。
• 后台 · 全部包：多选 / 全选 + 「删除选中」，单删与批量均二次确认
  （全选删除需输入 DELETE）；删除后立即回收该包素材。
• 后台 · 统计页重做：按分钟聚合的请求吞吐、P50/P95 延迟、CPU/内存图表
  （真实坐标轴 + 网格 + 图例 + 悬浮读数），并新增「用户用量」「接口热点」明细表。
• 后台 · 用户管理：硬删除账号（DELETE /api/admin/users/:email），
  ?purge=true 一并清理名下包 / 素材、用量与监控记录，并回收该用户上传但从未进包的散图。
• 包归属与服务端历史：GET /api/packs 只返回自己的包；历史记录一键还原生成现场。
• 单图二次编辑：任一已生成图可「编辑图片」，只重做这一张，并可再附一张参考图；卡片标记「已编辑」。
• 导入 ZIP 还原：选择本站下载的 ZIP 即可读回提示词 / 风格 / 情绪 / 参考图，继续单张生成或编辑。
• metadata.json 升级到 easysticker-pack@0.3：逐张记录名称 / 尺寸 / 角色 / 提示词 / 风格，
  参考图原图入包；详见 docs/pack-format.md。
• 内容哈希与长缓存：前端资源按 sha256[:8] 版本化，素材与带版本资源 immutable，HTML no-cache。
• 后台仪表盘改 SSE：由 15 秒轮询改为服务端推送。
• 项目级开发指令：.pi/extensions/dev-commands.ts 提供 /dev、/web。

变更

• 生图统一为 OpenAI 兼容 Images API（gpt-image / generic 两种 variant）；
  BREAKING：移除 ComfyUI、doubao、hf、http、managedHttp、picsum 等旧 provider，
  参考图契约文档随之作废（参考工作流 comfy/workflow_api.json 已删除）。
• 存储模型：包只存清单（几 KB），ZIP 下载时现打，不再落盘；磁盘占用约减半。
• 后台暗色主题与主站统一；全站图标统一为 SVG（currentColor）。
• 管理后台账号改为受保护：不能被停用 / 删除，UI 按钮置灰并说明原因。

修复

• 安全：停用 / 删除账号后，其已签发的 JWT 立即失效（此前要等 7 天过期）。
• 后台「重新体检 / 立即清理」「确认告警 / 启用禁用 / 删除包」缺少可见反馈（无 body 请求误带
  content-type 导致 400）。
• 公开页面里相对引用的 admin.css 命中 1 年 immutable 缓存，样式更新不生效。
• 编辑后本地状态未回写，刷新会退回编辑前的图；二次编辑会以旧图为源。
• node --watch 与 pino worker transport 冲突导致 npm run dev 启动即崩溃。

性能

• 素材查找由 O(目录大小) 扫描改为 O(1) 扩展名探测。
• 预览更新由整组重绘改为定点替换单个节点（消除多余图片请求与长任务）。
• 定期 GC（默认每 6 小时）+ 存储面板 + 手动 npm run gc；保留期默认 30 天且不追溯既往。

文档

• 收敛为「活文档 + 只读材料 + 参考实现」三层；新增
  docs/development.md、docs/pack-format.md、
  本更新日志、CONTRIBUTING、SECURITY 与 CI。