feat(skill): 新增 imagegen skill 引导用户说清楚生图需求(seedream tool)

五步法:诊断模糊度 → 一次性给推断 + 待确认项 → 用户拍板 → 装配 prompt → 调
seedream tool。五维清单(主体/场景/风格/构图/光线)缺 2 维以上就先问;mermaid
vs seedream 选型给"默认倾向 mermaid + 反向选 seedream 信号 + 模糊时主动问用
户"三段式(没在 system prompt 那条流程图优先 mermaid 上一刀切,留 skill 层细
化判断)。size/watermark/search 默认值取舍 + 失败不复发的解药表 + 8 条反模式。

skills/imagegen/SKILL.md 单文件(参考 coding skill 范式);seedream tool 本身
不动,本 skill 仅是流程引导层。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

PROGRESS.md

@@ -2,7 +2,7 @@
 
 > 配合 `DESIGN.md`。本文件只记 phase 状态、决策偏差、文件量、下一步。每条 1-2 句:做了啥 + 关键判断;细节查 `git log` / `git diff` / `DESIGN §7.9`。
 
-最后更新:2026-05-21(登录页加管理员发用户入口 + 删 chat meta 条/tok 显示)
+最后更新:2026-05-21(新增 imagegen skill 引导用户说清楚生图需求)
 
 ---
 
@@ -23,6 +23,7 @@
 
 ### 2026-05-21
 
+- **新增 imagegen skill(引导用户说清楚生图需求)**:`skills/imagegen/SKILL.md` 单文件(参考 coding skill 范式无 scripts/references)。核心是"先诊断模糊度 → 一次性给推断 + 待确认项 → 用户拍板 → 装配 prompt → 调 `seedream` tool"五步法,防止用户一句"画个 XX"就直接烧 ¥0.22。五维清单(主体/场景/风格/构图/光线)缺 2 维以上就先问;mermaid vs seedream 选型给"默认倾向 mermaid + 反向选 seedream 信号 + 模糊时主动一句话问用户"三段式(没在 system prompt 那段流程图优先 mermaid 上一刀切,留 skill 层细化判断);size/watermark/search 默认值取舍 + 失败不复发的解药表 + 8 条反模式。`seedream` tool 本身不动,skill 仅是流程引导层。
 - **登录页加"+ 管理员添加用户"入口 + 删 chat meta 条/tok 显示**:`web/auth.py` 加 `create_user()` helper(CLI/web 共用,避免漂移)+ `AuthConfig.admin_token` 从 `ZCBOT_ADMIN_TOKEN` env 读(未设 → None);`web/app.py` 加 `POST /v1/auth/admin/create_user` 校验共享口令后落库(503/403/400/409 分支);前端 `dev.html` 登录卡片右下加 ghost link + 弹窗(email/密码/管理员口令),成功后回填邮箱到登录表单提示"已创建请登录",不自动登录;同时删 chat 顶栏 `${n_messages} 条 · ${tokens} tok` 一行(与左 task 列表重复)。否决"User 表加 is_admin 列 + 管理员 JWT"方案 —— 开发期成本不划算,env 共享口令(类 PLATFORM_KEY 范式)够用。
 - **新增 documents skill(内部材料学科知识库 document_search API)**:`skills/documents/{SKILL.md, client.py}`,四函数 `list_kb / search / download / health`;走 `https://ai.ctc-zc.com:8100/api` Bearer 认证,env `DOCUMENT_SEARCH_API_KEY` + `DOCUMENT_SEARCH_URL`(可覆盖);search 默认返 `md_content`(整篇 Markdown 50K-200K 字符级),SKILL.md 反模式约束"只 print 前 300 字"防爆上下文;smoke 验证发现库实质是 7 个材料学科预收的英文学术论文(胶凝/陶瓷/玻璃/晶体/复合/耐火/检验检测,21W+ 文件)+ 跨语言语义检索,SKILL.md 据此校准(原写"主语料中文"是错的);与 research(OpenAlex)互补,documents 已 Markdown 化对 LLM 更友好,但仅覆盖材料领域。
 - **dev SPA SSE 客户端重连(覆盖 --reload 抖动)**:`fetchSse` 拆出 `consumeSseStream` + 包重连壳(1s/2s/4s 退避,最多 3 次);reader EOF 未见 done/error 算异常关流触发重连;后端 `stream_events` 入口检 `tasks.run_status`,非 running/cancelling 立即吐 done 关流(否则进程重启后新 broker 内存空,客户端会无限挂 ping)。3 次仍失败 → 卡片末尾红色"连接已断开,请重发"。断开期间 LLM delta 丢失,接受。

skills/imagegen/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: imagegen
+description: 用豆包 Seedream 5.0 生图(`seedream` tool)。当用户要配图 / 封面 / 概念图 / 效果图 / 示意图 / 海报 / 插画时使用 —— 重点是把用户的模糊一句话**问清楚再画**,而不是上来就烧 ¥0.22。
+---
+
+# Imagegen
+
+把"我想要张图"变成一张能用的图。**先诊断模糊度 → 一次性给推断 + 待确认项 → 用户拍板 → 装配 prompt → 调 `seedream`**。
+
+每次 `seedream` 调用 **¥0.22**(`search=true` 加 ¥0.05),3-5 秒出图。**模糊就问,不要赌**。
+
+## 何时用本 skill
+
+- 用户要**配图 / 封面 / 概念图 / 效果图 / 示意图 / 海报 / 插画**(明确说"画一张" / "出张图" / "来个封面")
+- 用户拿到 mermaid 结构图后说"太干了想要有质感的版本" / "做个有视觉感的"
+- ppt / proposal skill 流程中,要往 deck / docx 里塞概念图 / 引子图
+
+## 何时不走本 skill(直接走通用工具)
+
+- 用户**没主动要图**(别为"丰富回复"装饰性生图 —— 这是 system prompt 红线)
+- 用户给了具体参考图说"按这个改" —— Seedream 5.0 是文生图不接图像输入,告诉用户走描述
+- 已有合适素材(用户上传 / 之前生成过)—— 直接 `read` / 引用,别重新生成
+
+## 关键岔路:mermaid vs seedream
+
+**默认倾向 mermaid**(`run_python` 或 proposal skill 的 `render_diagrams.py` 都能渲):
+- 节点-箭头-结构关系明确(技术路线 / 流程 / 组织架构 / 时序 / 甘特)
+- 优势:矢量、文字清晰、可编辑、零成本
+
+**反向选 seedream**(满足任一):
+- 用户**明确说**"画一张图" / "做张示意图" / "出个图"(而非"画个流程图" / "做个架构图")
+- 需要**视觉冲击 / 美感**:汇报封面 / ppt 引子页 / 营销 / 宣传配图
+- 概念是**抽象 / 隐喻**的("AI 与材料融合"、"创新驱动"、"绿色低碳"这类只能靠意象表达)
+- 用户看过 mermaid 版本后说"太干了" / "想要有质感的"
+
+**模糊时主动问一句**:
+> 这张图你想要 **结构清晰的流程图**(mermaid 矢量,零成本),还是 **有视觉感的示意图**(seedream 生成,¥0.22)?
+
+不要默默替用户决定。
+
+## 诊断模糊度 — 五维清单
+
+用户原话能不能撑起一个 prompt?在脑里过一遍这 5 维:
+
+| 维度 | 缺失信号 |
+|---|---|
+| **主体** What | "画个混凝土" → 混凝土的什么?试块 / 楼板 / 微观结构 / 配料? |
+| **场景** Where | 工地 / 实验室 / 实验台面 / 虚拟空间? |
+| **风格** Style | 写实摄影 / 工程效果图 / 扁平插画 / 水彩 / 工业风 / 学术示意? |
+| **构图** Composition | 特写 / 中景 / 广角俯视 / 第一视角 / 截面图? |
+| **光线/氛围** Mood | 自然光 / 工业灯 / 暖色 / 冷色 / 神秘氛围 / 高对比? |
+
+**评估规则**:
+- 5 维**填齐 / 缺 ≤1** → 可以直接装配 prompt 调用
+- 缺 2 维及以上 → **先问再画**(见下节)
+- 用户直接给了完整中文长描述(自带主体+场景+风格)→ 视为已对齐,跳过追问
+
+## 一次性给推断 + 待确认项(不要一个个问)
+
+模糊时 **不要**轮流追问 "什么主体?" / "什么风格?" —— 用户会烦。**一次把你的推断摆出来,让用户改或确认**:
+
+> 你说"画个混凝土的图",我打算这样画:
+> - **主体**:施工中正在浇筑的现代混凝土楼板
+> - **场景**:工地俯视视角,远处有塔吊
+> - **风格**:写实工程摄影,质感细腻
+> - **构图**:广角俯视
+> - **光线**:正午阳光,清晰阴影
+>
+> 这样画可以吗?或者告诉我:你想突出什么?(微观结构 / 浇筑工艺 / 成品质感 / 新旧对比 ...)
+
+推断时优先看**上下文**:做申报书"水泥水化"章节 → 八成是要学术示意图;做营销海报 → 八成是要写实摄影感;做内部汇报 ppt 封面 → 八成是有视觉冲击的概念图。
+
+## 装配 prompt — 用户确认后
+
+用户拍板后,**把 5 维拼成自然中文 prompt**,直接传给 `seedream`:
+
+```
+施工中正在浇筑的现代混凝土楼板,工地俯视视角,远处有塔吊,
+写实工程摄影,质感细腻,广角俯视,正午阳光,清晰阴影
+```
+
+要点:
+- **中英文都行**,豆包模型自己理解;**用中文更省脑**(用户也是中文给的)
+- **不要堆"高质量 4K 8K masterpiece"** 这类废话(模型不靠这些发挥)
+- **不要写否定提示词**("not blurry"、"no watermark")—— Seedream 不支持 negative prompt,这些会被当正向词吃进去反而坏事
+- 主体放最前,风格 / 光线放后
+
+## 参数取舍
+
+| 参数 | 默认 | 何时改 |
+|---|---|---|
+| `size` | `2048x2048`(配置默认) | **超大海报 / 印刷需求** → `3072x3072`(原生最高);**ppt 单页配图** → `2048x2048` 已够;**做缩略图** → `1024x1024` 省体积。注意:**比例只能正方形** —— 需要 16:9 横版要自己后期裁,豆包 5.0 文生图不直接出非方形 |
+| `watermark` | `false` | 默认无水印(申报书 / ppt / 客户交付都不该带);**仅当用户明确说"加水印"** 才传 `true` |
+| `search` | `false` | **需要时事元素 / 特定品牌识别 / 真实人物**(如"画一下特斯拉 Cybertruck") → `true`,加 ¥0.05;**纯概念 / 抽象 / 通用对象** → `false`,模型本身知识足够 |
+
+## 调用范式
+
+`seedream` 是 tool 不是 skill 函数,**直接调,不要 `run_python` 包一层**:
+
+```
+seedream(
+    prompt="施工中正在浇筑的现代混凝土楼板,工地俯视视角,远处塔吊,写实工程摄影,质感细腻,广角俯视,正午阳光",
+    size="2048x2048",     # 可省,走默认
+    watermark=false,       # 可省
+    search=false,          # 可省
+)
+```
+
+返回串首行是 `[seedream] model=... · size=... · cost=¥... · elapsed=...s` —— 把这行原样保留给用户(前端 SPA 会 parse 挂徽章)。第二行 `saved: <相对路径>` 是产物路径,告诉用户。
+
+产物自动落 `<task_dir>/figures/<时间戳>-<rand>.png` + 同名 `.meta.json`(prompt / 参数 / 成本 / response_id)。
+
+## 失败 / 不满意后怎么办
+
+**不要原 prompt 重发**!那是浪费 ¥0.22。失败模式 / 解药:
+
+| 现象 | 原因 | 解药 |
+|---|---|---|
+| 主体方向偏(画了砂浆但想要混凝土) | prompt 主体词不够具体 | 增加修饰:"现代浇筑成型的钢筋混凝土楼板" |
+| 风格不对(给了卡通但想要写实) | 缺风格词或风格词冲突 | 把风格词放到 prompt 前 1/3 位置:"写实工程摄影,xxx" |
+| 光线 / 氛围不对 | 没指定光源 | 加 "正午阳光" / "工业冷光" / "暖色调" |
+| 画面太空 / 太挤 | 没指定构图 | 加 "广角俯视" / "中景特写" / "黄金分割构图" |
+| 出现奇怪文字 | Seedream 中文文字渲染不稳 | prompt 里**不要要求画文字 / 标签** —— 文字后期 ppt 里加 |
+
+**先口头跟用户对齐改哪一维**,再发新调用 —— 不要"再画一张试试"连续烧钱。
+
+## 产物处理
+
+生图完成后:
+- 把 `saved: figures/xxx.png` 路径告诉用户
+- 如果是做 ppt / docx 配图,直接在后续 `add_picture` / `![](...)` 引用,不需要再问
+- 用户说"换张" → 走上节的"对齐改哪一维"流程,不要默认重发
+- 用户说"再来几张备选" → **先确认**:"备选 N 张会花 ¥{0.22 * N},确认?"(防止隐形烧钱)
+
+## 反模式
+
+- ❌ 用户没主动要图就装饰性生成(system prompt 红线)
+- ❌ 用户说"画个 XX" 直接拿这 4 个字当 prompt 调用 —— 五维清单至少先问 1 轮
+- ❌ 一个个问"什么主体?""什么风格?" —— 一次性摆推断 + 让用户改
+- ❌ 同一目的不满意连续重发 2+ 次 —— 先校准 prompt 再调
+- ❌ prompt 里堆 "high quality, 8k, masterpiece, ultra detailed" —— 没用,Seedream 不靠这些
+- ❌ prompt 里写否定词 "no text, not blurry" —— Seedream 不支持 negative,会反向起效
+- ❌ 给 `search=true` 跑通用概念(¥0.05 白付) —— 只有时事 / 特定品牌 / 真人才开
+- ❌ 让用户在 mermaid / seedream 之间默默替他决定 —— 模糊就一句话问明白
+- ❌ 用 `run_python` 调 `requests` 裸打豆包 API —— 走 `seedream` tool(已封装计费 / 落盘 / meta)
+
+## 输出
+
+调完告诉用户:
+- 文件相对路径(`figures/xxx.png`)
+- 本次成本(¥0.22 或 ¥0.27)
+- 用的 prompt 摘要(主体 / 风格 / 光线 3 件套)
+- 一句"要换方向 / 调风格 / 再来一张吗?"