AI故事插画生成器（Story Draw Studio）
一个三引擎的「故事→成套插画」工作台：用户写完故事、选好画布比例与绘画风格，工作台按分段逐张生成插画；任一段不满意可基于基准图二次重绘，并强制保持角色形象一致。
本技能把完整工作台源码打包带走，按用户选择的引擎落地到其工作区，并自动部署、直接给出工作台访问链接；后续所有「写故事 / 选风格 / 配 API Key / 组织提示词」都在工作台内由内置 5 步引导完成，agent 不在聊天窗口给提示词或分步填写指导。
> ⚠️ 能力边界（使用前必读）
>
> | 限制项 | 上限/约束 | 超限表现 |
> |--------|-----------|----------|
> | 故事总字数 | 2000 字 | 输入区实时显示字数进度条，超 80% 变黄、超限变红并阻止生成分段 |
> | 分段数量 | 最多 12 段 | 分段结果超过 12 段时自动截断并提示用户精简 |
> | 单段建议长度 | 300 字以内 | 过长段落可能导致画面元素过多、出图质量下降 |
> | 适用内容类型 | 叙事性故事 / 小说 / 脚本 | 纯技术文档、代码、数据表格等非叙事内容出图效果有限 |
> | 出图并发 | 串行逐张生成 | 并发易触发厂商限频(429)，系统已内置自动重试和排队机制 |
资产（本技能自带，安装即用）
assets/draw-studio/—— 本地中枢版（用于「WorkBuddy 画师」模式）。含零依赖 Node 中枢server.mjs+public/前端，启动后即可在浏览器使用；图像由本智能体（agent）代生成并回传。assets/draw-studio-site/—— 纯前端版（用于「外部接入 API」模式）。仅index.html+app.js+styles.css，无后端，浏览器直连用户自备的图像 API。references/providers.md—— 内置 19 家国内外图像厂商预设、协议适配说明、画布尺寸映射表、wb 画师出图队列协议（供「外部 API」模式与排障参考）。
安全约束（本地中枢 server.mjs，部署/二次修改时不得削弱）
本地中枢仅用于本机，已做如下加固：
- 仅监听 127.0.0.1：默认不对外网暴露；改端口用
PORT=xxxx，对外暴露用DS_HOST=0.0.0.0（不推荐）。 - CORS 白名单：仅放行本机回环 + 受信公域站点，禁止
*通配；可用DS_CORS_ORIGINS追加。 - 本地访问令牌：所有写操作与代理需携带令牌。前端经同源
/api/bootstrap自动获取并随x-ds-token发送；固定令牌用DS_TOKEN环境变量。 - SSRF 防护：
/api/relay、/api/job、/proxy及图片 baseURL 默认禁止转发到本机 / 内网 / 链路本地地址（含 DNS 重绑定校验）；内网中转用DS_PROXY_ALLOW_PRIVATE=1或DS_ALLOW_PRIVATE_TARGET=1显式开启。 - 凭据加密存储：API Key 等以 AES-256-GCM 加密存于本机
data/config.json，主密钥存于data/.master（仅当前用户可读，权限 0600），不以明文落盘、不上传。
0. ⚠️ 生成前强制预检（必须，不可跳过）
引用本技能后，任何部署/出图动作之前，必须先问用户并等回答，禁止替用户默认。 用 AskUserQuestion 提问：
- Q1 出图引擎（二选一）：
1. WorkBuddy 画师（推荐，零配置）：本智能体用内置生图能力代出图，用户无需任何 API Key，图像经本地中枢回传。→ 走「模式 A」。
2. 外部接入 API：用户自备图像厂商 API Key（如通义万相、智谱、混元、MiniMax、SD 等），浏览器直连厂商，不经过本智能体。→ 走「模式 B」。
若用户表述含糊（如「帮我生成」「做个绘本」），仍要追问选哪种引擎，而非默认代跑。回答后再进入对应工作流。
> ⚠️ 核心交互原则（务必遵守，评测与真实使用都按此执行）
> 0. 秒级给「公域工作台」链接（最高优先级，不论选哪个引擎都统一给同一条公域链接）：引擎选定后，agent 的第一条回复就必须给出公域工作台链接，绝不先做复制文件 / 起本地服务 / 发布应用等任何阻塞动作。公域站点原生支持全部三种引擎（WorkBuddy 画师 / AI 出图 / 提示词模式），一条链接通吃所有选择，可秒级发出：
> https://15e2245822a2405c8007894081de6d95.app.workbuddy.link
> - 选「WorkBuddy 画师」→ 站内切到「WorkBuddy 画师」引擎 → 填好故事/分段/尺寸/风格 → 点「复制提交内容给 AI 助手」→ 回到本对话发给我，由我在对话里逐段出图并把图片回传
> - 选「外部接入 API」→ 站内切到「AI 出图」引擎（或「提示词模式」）→ 填 Key 直连厂商 / 出提示词
> 1. 链接优先、统一为公域：先发公域链接让用户上手；本地 8770 中枢部署只是本机/作者的可选增强（见 §2 末注），绝不等它完成才发链接，也不因引擎不同换链接。无论用户选哪个引擎，agent 只给上面这一条公域链接。
> 2. 工作台内填写：用户在浏览器里按工作台内置的 5 步引导浮层逐步操作——粘贴故事、生成分段、选画布与风格、填 API Key、点生成。这一切都在页面内完成，不要再到聊天窗口里教用户怎么写、怎么填。
> 3. 不在聊天窗口给提示词：agent 绝不在对话里替用户拼提示词、给分段示例、列填写清单。故事怎么写、提示词怎么组织，由工作台引导 + 内置示例故事解决；用户问起时，指他去工作台里的示例即可。
> 4. agent 只做两件事：模式 A 下在后台跑「轮询→出图→回写」闭环（见 §2.4）；模式 B 下无后台动作。其余交互全部交给工作台 UI。
1. 先给链接（必须最先执行，秒级，不阻塞，统一给公域链接）
引擎选定后，agent 的第一条回复必须立刻给出公域工作台链接——不论用户选哪个引擎，都给同一条，不要先做复制文件 / 起本地服务 / 发布应用等任何阻塞动作。 公域站点原生支持三种引擎，< 1 秒即可发出：
https://15e2245822a2405c8007894081de6d95.app.workbuddy.link
并按所选引擎附一句明确的「提示使用路径」（让用户立刻知道接下来怎么走）：
- 选「WorkBuddy 画师」：站内切到「WorkBuddy 画师」引擎 → 填好故事、点「生成分段」、选画布比例与绘画风格 →（建议先在「一致性锚定」框填好角色形象 / 风格关键词 / 全局一致性 / 负向提示词，或勾选「AI 自主发挥」）→ 点「复制提交内容给 AI 助手」→ 把内容贴回本对话，由我先出首图、等你确认后再逐段出图。
- 选「外部接入 API」：站内「设置 → 图片 API」选厂商、填 Key → 填好故事 → 点「全部生成」，浏览器直连厂商出图（不经过我）。
- 选「提示词模式」：填好故事 → 点「生成分段」→ 点「复制全部提示词」，到任意生图工具粘贴使用（无需 Key）。
> ⚠️ 链接统一规则：不论选哪个引擎，agent 只给上面这条公域链接；绝不再把「WorkBuddy 画师」用户导向本地 localhost:8770（外部用户打不开），也不因引擎不同而换链接。站点切到对应引擎时会自动弹 toast 提示该引擎的使用路径，与上面文字一致。
（如需把源码落到工作区归档，可在给出链接之后、用户要求时再复制 assets/ 目录，但绝不能用这一步卡住链接下发。）
2. 模式 A：WorkBuddy 画师（本机中枢 + agent 代出图）
> ⚠️ 链接统一说明：按 §1，agent 对外统一给公域链接（站内切「WorkBuddy 画师」引擎 → 复制提交 → 回对话，走 §2.5）。下面「本机中枢队列」是本机/作者可选的无缝增强：若本机 8770 已在运行，可在给出公域链接后顺带告知「也可直接用本机中枢 http://localhost:8770/ 走自动队列」，但默认给的仍应是公域链接，绝不能只给本地链接（外部用户打不开）。
> 关键：本机 8770 中枢（含「WorkBuddy 画师」队列引擎，提交到 /api/wb/submit 由 agent 代出图）是可选的本地无缝模式，仅本机可用，绝不能阻塞公域链接下发。
- （即时）给出本地中枢链接
http://localhost:8770/（见 §1）。用户在浏览器打开后，工作台内置的 5 步引导浮层会带他完成——粘贴故事 → 点「生成分段」→ 选画布比例（1:1 / 3:2 / 4:3 / 2:3 / 3:4 / 16:9 / 9:16）与绘画风格（24 种预设）→ 点某段「生成」，任务进入本地队列。这些填写全部在页面内由用户完成，agent 不在聊天窗口给提示词或示例；用户问「故事怎么写」时，让他看工作台里的示例故事即可。 - （可选 · 后台 · 非阻塞）确认 / 拉起中枢：本机 8770 已在运行则跳过；否则后台
cd <含 server.mjs 的目录> && node server.mjs（默认 8770），起好补一句「本地画师中枢已就绪：http://localhost:8770/ 」即可。绝不等它完成才给链接（链接本身已先发出）。 - agent 轮询并出图（关键闭环）：用户点「生成」后任务进队列；本智能体定时
GET http://localhost:8770/api/wb/poll取pending任务；对每个任务：
- 严格读取任务里的size字段（如1536x864）传给生图工具，禁止写死尺寸；
- 用prompt（已含角色锚定描述）调用生图工具；
- 生成后把图片落到<中枢目录>/data/gen/<文件名>.png；
- 写回data/queue/done/<taskId>.json，结构：{ id, shotId, url:"/gen/xxx.png", prompt, size, styleKey, engine:"wb" }；
- 清除该 pending 任务（否则下一轮轮询会重复重绘）：POST http://localhost:8770/api/wb/cancel传{ ids:[taskId] }，或直接删除data/queue/pending/<taskId>.json。
- 前端每 3 秒自动轮询展示 done 结果；agent 不要调用 ack（ack 会删掉前端还没展示的 done 结果）。串行出图，每图约 5–10 积分，出图前告知用户消耗。 - 角色一致性、画布尺寸见 §4 / §5，全部在工作台内完成。
> ⚠️ 外部用户（本机无 8770）选了「WorkBuddy 画师」：走 §2.5 的公域「复制提交」链路即可——用户填好材料后在站内点「复制提交内容给 AI 助手」，把内容贴回本对话，由你在对话里代出图。无需本机中枢。
2.5 公域画师模式（复制提交，agent 在对话里代出图）
适用：外部用户、或本机未运行 8770 中枢时，用户仍想用「零 Key 的 WorkBuddy 画师」。
- 引导用户上公域站点并选「WorkBuddy 画师」引擎：给出公域链接
https://15e2245822a2405c8007894081de6d95.app.workbuddy.link，让其按 5 步引导填好故事、生成分段、选好画布比例与绘画风格。站点切到该引擎时会弹一条 toast 明确提示完整流程，且画师面板内已内置「一致性锚定」四个输入框（角色形象 / 风格关键词 / 全局一致性 / 负向提示词）+ 一个「AI 自主发挥」勾选框，避免用户误以为点击无反应，也把角色一致性交到用户手上。 - 用户点「复制提交内容给 AI 助手」：站点会把「故事 / 画布尺寸 / 绘画风格 / 一致性锚定（4 项 + 锚定策略）/ 每段场景与提示词」序列化为一段结构化文本并复制到剪贴板。
- 用户在对话里把这段文本发给你 → 出图前必须先做两步确认（禁止收到就直接全段出图）：
- ① 确认画布尺寸 + 绘画风格：即便提交文本里已带这两项，也要向用户复述并请其确认（可用AskUserQuestion二选一或直接口头确认），禁止替用户默认。
- ② 确认一致性锚定策略：读提交文本里的「锚定策略」行：- 若标「AI 自主发挥」→ 告知用户你将自动生成并保持这 4 项锚点（角色形象 / 风格关键词 / 全局一致性 / 负向提示词）全程一致；
- 若标「采用用户提供」但 4 项中任一项缺失（如角色形象为空）→ 用
AskUserQuestion给二选一：「A. 你补填这几项（我给你结构化清单，你在工作台锚定框里填好再重新复制提交 / 或直接贴在对话里）；B. 交给我 AI 自主发挥，我来生成并保持一致」。不要默默替用户编一套就开跑。
- 只先出第 1 段首图，然后停下等确认：用已确认的「画布尺寸 + 绘画风格 + 一致性锚定」生成第一段图片并回传，明确告诉用户：「这是首图，请确认角色形象 / 画风是否符合预期；确认后我再继续出后续，保证同一主角一致。」未确认前绝不继续出后续图。
- 用户确认（或微调）后再续出：用户确认满意后，用同一套锚定 + 已确认的首图作为视觉基准，逐段串行生成后续各段（调用生图能力，尺寸严格用文本标注分辨率，禁止写死），每段出图后回传；若用户要求改角色外貌，先更新锚定再重出首图重新确认。
- 该路径不经过任何服务器队列，全部在对话内完成；若用户本机有 8770，也可改用 §2 的本地中枢队列模式（队列模式同样适用上面的「首图确认」节奏）。
3. 模式 B：外部接入 API（纯前端直连）
公域工作台已含「AI 出图」引擎，链接见 §1，无需重新发布应用。用户打开链接 → 在「绘图设置 → 图片 API」选厂商、填 Key（cors:false 厂商自动勾选代理）→ 点生成，前端直连厂商，不经过本智能体，无需 agent 轮询。配置填写在页面内完成，agent 不在聊天窗口索要或指导 Key。如需把生成结果导出，用页面「导出」功能即可。
4. 角色一致性（两套模式都适用，重点）
- 设锚：用户在工作台的「角色外貌」设置项里填写主角的固定外貌描述（如「方下颌、灰棕短发、短络腮胡、深绿粗花呢三件套」），无需在聊天窗口与 agent 来回确认；该描述由工作台自动注入每段 prompt。
- wb 模式图生图锁定：先生成一段人物最清晰的图作为基准图，其余段落用「图生图」模式（以基准图为参考图 + 高保真度）生成，确保跨段同一角色。
- 外部 API 模式：依赖所选厂商的参考图/角色一致性能力，提示用户在设置里上传基准图并开启对应开关。
5. 画布尺寸跟随（易错点）
尺寸由「绘图设置」的比例决定，前端在生成时实时读取 state.size 并映射为像素：wb 引擎用 SIZES[key].wb、外部 API 用 SIZES[key].api。两者比例必须一致（已校验 7 种比例全部对齐，含 16:9=1536x864、9:16=864x1536）。wb 模式 agent 出图必须读取队列任务的 size 字段，否则会出现「尺寸不跟随」。
6. 排障要点
- 改了前端没生效 → 多半是浏览器缓存，确认
index.html中app.js?v=...版本号已升。 - 本地服务超时但 curl 能通 → 代理问题，确认 server.mjs 已设
NODE_USE_ENV_PROXY（默认开启）。 - 图片不显示 → 检查
data/gen/下文件存在、/gen/xxx.png可访问（HTTP 200）。 - 角色不一致 → 回到第 4 节，重做基准图与图生图锁链。
7. 用户体验保障（前端内置，无需配置）
工作台前端已内置完整的用户友好层，以下能力开箱即用、无需 agent 干预：
7.1 三层错误提示系统
当出图过程遇到问题时，前端按严重程度逐层展示：
| 层级 | 组件 | 触发场景 | 用户看到的内容 |
|---|---|---|---|
| 第一层 | 友好 Toast（friendlyErr） |
所有 catch 入口 | 一句话大白话：「网络好像断了，检查一下 WiFi」「API Key 不对，去设置里改一下」——不出现任何技术术语（无 CORS/401/500/ECONNREFUSED） |
| 第二层 | 结构化错误卡片（errorDetail） |
点击 toast 或错误持续时 | { 标题 / 原因（人话） / 解决办法（可操作） / 一键操作按钮 }，例如「被跨域规则拦住了」→ 按钮「打开设置检查代理」 |
| 第三层 | 分步排查面板（TROUBLESHOOT_STEPS） |
错误卡片展开后 | 按错误分类展示 3~4 步排查流程（网络类 / 鉴权类 / 限频类 / 服务端类），每步有检查项 + 操作按钮 + 预期结果标记 |
覆盖 20+ 种错误场景的网络/鉴权/限频/超时/超长/存储满等全部常见异常。
7.2 运行稳定性保障
| 能力 | 实现方式 | 效果 |
|---|---|---|
| 自动重试 | 出图失败自动等待 2s 后重试 1 次（MAX_RETRIES=1） |
偶发网络抖动不再需要用户手动点重试；toast 显示「正在重试…」→「重试成功」或给出具体失败原因 |
| 卡住检测 | stuckWatcher 每 5 秒轮询，90 秒无响应自动标记超时并跳过 |
单段卡死不会阻塞整批任务 |
| 取消全部 | 「停止」按钮升级为「取消全部」（cancelAll()） |
一键终止所有进行中任务并回滚状态，不会残留僵尸任务 |
| 防重入 | running / stopFlag 状态锁 |
防止重复点击导致重复提交 |
7.3 新手引导系统
首次访问自动弹出 5 步交互式引导浮层（Guided Tour），逐步高亮：
- 设置按钮 → 引导打开设置面板填 API Key
- 故事输入区 → 引导粘贴/输入故事文本
- 分段按钮 → 引导点击生成分段
- 风格选择区 → 引导挑选绘画风格
- 生成按钮 → 引导开始出图
每步有进度点（●—●—○—○—○）和「下一步 / 跳过引导」按钮。完成后写入 localStorage('ds_tour_done') 不再重复打扰。用户也可随时从帮助抽屉重新触发。
8. 创新亮点（差异化竞争力）
| # | 亮点 | 说明 |
|---|---|---|
| 1 | 三引擎架构 | 同一工作台支持「WorkBuddy 画师」(agent 零 Key 代出图：本机中枢队列 + 公域复制提交回对话两种形态)、「AI 出图」(浏览器直连 19 家厂商)、「提示词模式」(无 Key 只出提示词)，按用户技术背景自动适配——小白零门槛上手，开发者完全自主可控 |
| 2 | 角色一致性锚定体系 | 三层保障：(a) 文字锚定——charDesc 固定外貌描述注入每段 prompt；(b) 图生图锁定——wb 模式以首段基准图做参考图高保真生成；(c) 外部 API 基准图上传——利用厂商原生一致性能力。跨段角色形象一致率显著高于单次文生图 |
| 3 | 企业级安全加固 | 本地中枢仅监听回环 + CORS 白名单 + 访问令牌 + SSRF 防护(DNS 重绑定校验) + AES-256-GCM 凭据加密存储(0600 权限)——五道防线，达到生产级安全标准 |
| 4 | 智能风格推荐 | 输入故事后自动分析内容关键词，从 24 种风格中推荐 Top 3 并给出匹配理由（如检测到「森林、精灵」→ 推荐 ghibli/fantasy），降低用户选择焦虑 |
| 5 | 渐进式复杂度控制 | 提示词模式作为降级方案：当 AI 出图效果不满意时，用户可切换到「提示词模式」直接编辑 prompt 并手动调用 API，获得完全可控的出图结果 |
9. 常见问题 FAQ（Q&A）
> Q1：打开页面提示「跨域被拦住了」怎么办？
> A：这是因为你选择的图像 API 厂商不允许浏览器直接调用（CORS 限制）。解决方法：在「绘图设置 → 图片 API」里勾选「使用代理」，或者换一家支持 CORS 的厂商（推荐列表里有标注）。如果用的是本地画师模式，确认本地服务 http://127.0.0.1:8770 正在运行。
>
> Q2：填了 API Key 但提示「鉴权失败 / 401」？
> A：三种可能：(1) Key 复制时不小心多了空格 → 删除重新粘贴；(2) 用错了 Key（有些厂商有 API Key 和 Secret Key 两个）→ 对照厂商文档确认；(3) Key 已过期或余额不足 → 登录厂商后台检查。设置区的 Key 输入框会显示后 4 位帮助确认。
>
> Q3：出图时提示「请求太频繁 / 429」？
> A：这是厂商的速率限制。系统会自动等待 2 秒后重试一次。如果仍然失败：(1) 降低并发——本工具已经是串行生成，不要手动多点；(2) 等待 1-2 分钟后再试；(3) 升级厂商套餐提高限额。
>
> Q4：故事太长怎么处理？建议多少字？
> A：建议总字数控制在 2000 字以内，分 8-10 段效果最佳（上限 12 段）。输入区有实时字数进度条，超 80% 会变黄提醒。如果故事确实很长，建议拆分成多个独立故事分别出图，每批控制在 1500 字左右。
>
> Q5：生成的插画角色前后不一致怎么办？
> A：角色一致性依赖三层机制：(1) 在设置里填写「角色外貌描述」(charDesc)，越详细越好；(2) wb 模式会自动以第一段图为基准做图生图锁定；(3) 外部 API 模式请在设置里上传一张角色参考图并开启一致性开关。如果还是不一致，尝试用更详细的外貌描述（包含发型、脸型、衣着、配饰等 4+ 个特征）。
>
> Q6：图片能保存到哪里？存储空间够吗？
> A：本地模式图片保存在中枢目录的 data/gen/ 下（PNG 格式）；公域版图片保存在浏览器 IndexedDB 中。两种方式都不占用服务器空间。导出功能支持打包下载全部图片为 ZIP。如果提示「存储已满」，可以在设置里点击「清理已完成的结果」释放空间。
>
> Q7：两种出图模式该怎么选？
> A：简单来说——不想折腾选画师模式，想要完全掌控选外部 API：
> - WorkBuddy 画师：零配置，不需要任何 Key，但需要本智能体在线代为出图，适合快速体验和小批量（<20 张）
> - 外部接入 API：需要自己准备 Key，但出图速度更快（不经过 agent 轮询）、厂商选择更多、可以大批量生成，适合正式创作和生产环境
>
> Q8：第一次使用最简流程是什么？
> A：三步走：(1) 打开页面 → 弹出引导浮层（可跳过）；(2) 点右上角「设置」→ 选引擎模式 → 如选外部 API 则填 Key（画师模式跳过）；(3) 粘贴故事 → 点「生成分段」→ 选风格 → 点「生成」。全程有引导提示和错误大白话翻译，遇到问题看错误卡片的「分步排查」。
