promptfigure 0.2.0 → 0.3.0

package/adapters/codex/promptfigure/skills/promptfigure-api/references/prompt-cookbook.md

@@ -0,0 +1,223 @@
+# prompt 构造手册
+
+## 先分清两种模式
+
+| | 默认模式（产品形态） | 降级模式 `polish:false`（紧急绕过） |
+|---|---|---|
+| 服务端 | LLM 编排 → 净化 → 审查 → 出图 | **跳过润色**，你的 prompt 直接进图模型 |
+| 你要写 | **大白话 + 意图说清楚** | **完整英文专业提示词** |
+| 难度 | 低 | 高 |
+
+⚠️ **默认模式才是产品的正常形态。** 降级模式仅在上游文本限频期默认管线连续失败时作为紧急绕过，平时不要用。
+
+---
+
+# 默认模式（正常形态）
+
+服务端会把你的大白话扩写成专业提示词。**你的职责是把用户意图一次性说清楚，不是替服务端写长提示词。**
+
+## 三要素，缺一项就补一项
+
+| 要素 | 说明 | 反例 |
+|---|---|---|
+| **图种** | flow / mechanism / pipeline / comparison / roadmap / graphical abstract | 「画个图」 |
+| **实体** | 组名、模型名、基因名、数值、实验条件——**这是最重要的** | 「两种方法的效果」 |
+| **结构** | 几个 panel、流向、是否要图例 | 完全不提布局 |
+
+**实体齐全度直接决定出图信息密度**。服务端能扩写句式，但扩写不出你没告诉它的实体。
+
+## 「一次性说清楚」的写法
+
+```
+✅ "对比 ResTiNet 和 CNN baseline 在 OCT 影像分类上的表现。
+    左图：数据流从输入经 4 个残差块到分类头。
+    右图：柱状图，准确率 94.2% vs 88.7%，推理时间 12ms vs 31ms。"
+
+❌ "画个深度学习对比图"    ← 无实体无结构，服务端无从扩写
+```
+
+注意：
+- **中英文都可以**——服务端负责润色，中文也可以（但 technical 名词保持原文大小写：`GPX4`、`ResTiNet`、`p < 0.001`、µm 等）
+- **数值要真实**：没有的数据留占位符或干脆不写。**编造的数值会被原样印到图上**
+- 一句话到三句话通常够，不必堆砌
+
+## 草稿 = 低文字密度构造法（2026-09-25 实测定规）
+
+standard 草稿的乱码率随**卡面文字量**上升（实测：说明性小字整行乱码
+"discards background patches"→"disnark"、标题 "Technical Roadmap"→"Cattlreet Tbgleftste"；
+实体名短标签几乎不出错）。草稿阶段构造 prompt 按三条：
+
+**① 卡面文字只留实体名。** 除实体名标签（+最多 2-3 个 ≤2 词的超短标签）外，一切说明性小字
+——阶段职能句、百分比、参数、长标题——全部**不写**，改写成 show 画法句让图模型画出来：
+
+```
+❌ "Stage 2 Coarse Filter discards background patches (85%)"
+✅ "Stage 2 Coarse Filter, show a funnel icon filtering grey patches and keeping a few highlighted ones"
+
+❌ "Stage 4 Fine Grader (6-layer transformer encoder) assigns per-patch defect scores"
+✅ "Stage 4 Fine Grader, show a stack of thin transformer layers glowing over one highlighted patch"
+```
+
+**② 风格基线块句句带上**（润色层不会替你补，缺一句图模型就自由发挥一句）：
+
+```text
+flat vector, pure white background, thin dark-gray outlines,
+no shadows no gradients no 3D,
+muted semantic palette (2-4 pastel hues + 1 accent color),
+clean sans-serif English labels, generous whitespace
+```
+
+每个颜色对应一个角色（数据=浅蓝、核心=橙红强调、输出=浅绿…），**禁止单一色相约束**（见下文配色节）。
+
+**③ 说明性文字留到 premium 再加回。** 草稿定下构图/母题/配色后，premium 定稿
+复用同一 prompt（只改 model/size），此时才把职能小字补回——premium 的 gpt-image
+文字渲染显著更强，且补回的文字必须逐字写对。
+
+一句话：**草稿管"长什么样"，premium 管"字写得对不对"。**
+
+## 常见图种的意图描述要点
+
+- **技术路线图**：几个阶段、从左到右、每阶段的关键动作
+- **机制/信号通路**：谁激活谁、谁抑制谁、最终结果；如有亚细胞定位一并说明
+- **实验管线**：原始输入 → 各处理步骤 → 输出；每步的方法名
+- **对比图**：比什么对象、在什么指标上、用什么图表类型（柱状/折线/箱线）
+- **图形摘要**：核心结论一句话 + 支撑它的 2–3 个要素
+
+组合式多 panel 写法见线上：https://promptfigure.top/docs/zh-CN/figure-structure
+（多 panel 图记得把 `ratio` 设成 `16:9`）
+
+## 参考图怎么用
+
+有参考图时**必须拆到特征级**——不要只写「参考这个风格」，那样必返工。逐项对照：
+
+方向（横/竖）· panel 数量 · 图表类型 · 图标风格 · 数据标注密度 · 配色分布
+
+把这些特征写进意图描述，参考图作为补充。
+
+```json
+{ "prompt": "...", "refUrl": "https://...直链.png" }
+```
+
+⚠️ **当前参考图端点可用性**：上游 `/images/edits` 自 2026-09-07 起持续 503。`refUrl`/`refDataUrl` 经常被忽略（`refIgnored: true`，**当次照常出图并计费**）。看到这种情况，**暂时改用纯文字精确描述**更好。（2026-09-25 复测：premium 2K + refDataUrl ≈0.54MB 一次通过、未标 `refIgnored`，通道可能已恢复——但每次批量任务开始前仍按上文用 1 张 standard 试水，以 `refIgnored` 信号为准。）
+
+---
+
+# 降级模式（`polish:false`，紧急绕过）
+
+服务端不润色，你的 prompt **原样**进图模型。此时必须自己写完整英文专业提示词。
+
+## 关键差异
+
+- ❌ prompt 必须**英文**（中文会被当噪声处理）
+- ❌ **没有服务端修正**：写错就错
+- ✅ 要把"图种 + 结构 + 风格 + 标签"全部写死
+- ⚠️ 图模型英文文字渲染差，关键标签必须**逐字写对**
+
+## 降级模式模板
+
+### 技术路线图
+
+```
+A horizontal 4-stage technical roadmap for <主题>, left to right:
+Stage 1 <名>, Stage 2 <名>, Stage 3 <名>, Stage 4 <名>.
+Each stage is a rounded rectangle with a short label and 2-3 sub-bullets.
+Arrows connect consecutive stages. Flat vector style, white background,
+thin dark-gray outlines, every stage in a distinct pastel color.
+All labels in English, spelled correctly.
+```
+
+### 机制 / 信号通路
+
+```
+A 2D flat conceptual diagram of <机制名>. <实体A> activates <实体B>,
+which inhibits <实体C>, leading to <结果>. Include: membrane boundary,
+receptor icon, arrow cascade with clear direction, and a labeled legend.
+No 3D, no gradients, no photorealism. White background, thin outlines.
+English text labels only, correct spelling (e.g. exactly "GPX4").
+```
+
+⚠️ 必须显式写 "2D flat"——不写容易出立体渲染。
+⚠️ 拼写逐字检查：这条模式下写错就是在图上印刷错误。
+
+### 实验管线
+
+```
+An experimental pipeline diagram, top to bottom: raw data acquisition →
+preprocessing (<步骤>) → feature extraction (<方法>) → model training →
+evaluation (accuracy <数值>%, F1 <数值>). Each stage is a full-width
+block with an icon and one-line caption in English. Flat vector, white
+background, consistent stroke width, distinct pastel color per stage.
+```
+
+### 对比图
+
+```
+A two-panel comparison of <方法A> vs <方法B> on <任务>.
+Left panel: <图表类型> showing <指标1> <数值A> vs <数值B>.
+Right panel: <图表类型> showing <指标2> <数值A> vs <数值B>.
+Both panels share the same vertical scale. Include axis labels with
+units. Clean scientific style, white background, panels labeled (a)(b).
+Axis labels in English: "Accuracy (%)", "Time (ms)".
+```
+
+### 图形摘要
+
+```
+A single-panel graphical abstract summarizing <论文主题>.
+Center: <核心对象>. Left inflow: <输入/数据源>. Right outcome: <结论/指标>.
+All labels in English. Generous whitespace, high visual hierarchy,
+white background, professional journal style.
+```
+
+## 配色（两种模式都适用）
+
+🚫 **禁止**约束单一色相。事故写法：
+
+- ❌ `"muted steel-blue fills"`
+- ❌ `"restrained navy/gray/teal palette"`
+- ❌ `"monochrome professional style"`
+
+图模型忠实执行 → 全图一个色系。
+
+✅ **语义化多色**：每个颜色对应一个角色。
+
+```
+coral-red for task labels, pastel green for model blocks,
+warm amber for training/evaluation blocks, sky blue for metric chips,
+pale pink for data blocks. White background, dark-gray outlines.
+Every color has a meaning — different roles get different hues.
+```
+
+5–7 个语义色通常刚好。**例外**：纯数据图表（柱状/折线）反而克制，≤4 色相 + 1–2 强调色。
+
+---
+
+## 降级模式专属：英文标签渲染
+
+实测（2026-09-09）polish:false 直出时图模型会画出 "Mcıuacy" 这类乱码：
+
+1. 关键标签在 prompt 里**逐字写好**，别写模糊描述让它猜
+2. 结尾加一句 `"All on-figure text labels in English, spelled correctly"`
+3. 重要场合用 `premium`（gpt-image 文字渲染显著优于 standard 的 Agnes）
+4. 出现乱码就换写法重试
+
+---
+
+## 发送前 Checklist
+
+**默认模式**
+- [ ] 图种说清楚了
+- [ ] 实体写全（组名/模型名/数值/条件）
+- [ ] 结构说了（panel 数/流向/图例）
+- [ ] 数值真实（没有的用占位符，绝不反问）
+- [ ] 草稿按低文字密度构造（卡面只留实体名，说明性内容转 show 画法句 + 风格基线块）
+- [ ] 多 panel 配了 `ratio: "16:9"`
+- [ ] `model` 选对（正式交付 = premium）
+
+**降级模式（额外）**
+- [ ] `"polish": false` 已设
+- [ ] 英文
+- [ ] 关键英文标签逐字写对
+- [ ] 150–300 词，>400 词会信息超载
+- [ ] 机制图标了 "2D flat"
+- [ ] 没有约束单一色相

package/adapters/codex/promptfigure/skills/promptfigure-api/references/prompt-review-workflow.md

@@ -0,0 +1,265 @@
+> 核心理念：**整个流程里唯一花钱的动作是 API 调用**。意图确认、提示词撰写、审核、打回重写——全部发生在你（Agent）和用户之间，零成本。把迭代全部前移到出图之前，第一次调用就该是接近定稿的提交。
+
+本文件定义 **四阶段协议**（阶段 0-2 免费本地完成，阶段 3 才花钱），以及鼓励用户**开两个 Agent 互审**的协作模式。
+
+---
+
+## 流程总览
+
+```
+阶段 0 意图确认（对用户，免费）
+   ↓ 用户确认
+阶段 1 提示词构建（本地，免费）
+   ↓ prompt 初稿
+阶段 2 提示词审核（本地，免费）──── 打回 ────→ 回阶段 1 重写
+   ↓ pass
+阶段 3 API 出图（花钱）
+   ↓ 图落盘
+阶段 4 成图审核（你亲自读图，免费）── FAIL 项转 prompt 修改指令 ──→ 回阶段 1
+   ↓ 全 PASS + 证据
+递给用户（用户挑方向/打回，打回仍回阶段 1）
+```
+
+---
+
+## 阶段 0：意图确认（强制，在写任何 prompt 之前）
+
+**为什么强制**：出图失败/返工的最大根因是意图没对齐就提交。宁可多花 30 秒确认，也不要花 $0.15 买一张废图。
+
+### 意图清单（5 项，必须全部有着落）
+
+| 项 | 说明 | 缺失时怎么办 |
+|---|---|---|
+| 图种 | 流程图/机制图/架构图/对比示意图/图形摘要/技术路线图… | 从用户措辞和上下文推断 |
+| 实体清单 | 模块名/组名/基因名/数据集名，**必须用用户材料里的原词** | 用户材料里找不到 → 必须问 |
+| 关系结构 | 数据流方向、并行/串行、包含/对比 | 用户材料里能推 → 推；推不出 → 必须问 |
+| 用途场景 | 期刊投稿/组会 PPT/标书/海报——决定精细度与档位 | 默认按期刊标准 |
+| 档位预算 | standard 草稿 → 满意后 premium 定稿，还是直接 premium | 默认「standard 草稿先行」 |
+
+### 澄清的两档处理
+
+**清晰输入**（实体和结构都能从用户材料里原词找到）：不打断用户。**回显确认卡**后直接执行：
+
+```
+按以下理解执行（有误请纠正，无回复我继续）：
+- 图种：方法管线图（Fig.1 位置）
+- 实体：Input Pair → Multi-View TTA → Dual Localizers → WBF Consensus（原词来自 2_method.tex）
+- 结构：左→右单向流，Dual Localizers 并行分支
+- 用途：期刊投稿 → premium 2K 定稿
+```
+
+**模糊输入**（实体是泛称、结构说不清、或用户材料里找不到对应物）：**必须停下来问**，一次问完，给选项不给开放题：
+
+```
+开两个 Agent 前请确认两点：
+1. 图里的三个模块名称用你论文里的原名（2_method.tex 的 X/Y/Z），还是用占位名？
+2. B 模块到 C 模块是单向箭头还是有反馈回路？
+```
+
+🔴 **一次问完**。禁止挤牙膏式连环追问；禁止问「什么风格」「什么配色」「几比几」（这些按 `SKILL.md` 一次性收敛表推定）。
+
+---
+
+## 阶段 1：提示词构建（golden skeleton）
+
+prompt 按五段骨架写（大白话即可，服务端会润色扩写，但骨架决定了润色的上限）：
+
+```text
+① 图种声明：一张 XX 图，用于论文 XX 章节
+② 实体清单：逐个列出（原词搬运，拼写逐字对齐用户材料）
+③ 结构关系：谁流向谁、哪里并行、哪里汇合
+④ 风格锚定：扁平矢量/白底/语义化多色 pastel/圆角矩形+箭头
+⑤ 禁令：无小字、无公式、拼写必须精确
+```
+
+**硬规则**：
+- 实体名逐字对齐用户材料——这是阶段 2 审核的第一优先项
+- **数字类内容（精确数值/坐标/统计量）禁止写进 prompt**——真数据图走本地 matplotlib（见 `figure-upgrade-workflow.md` §2）
+- 密集检测类术语组合（Candidate Boxes + Consensus + Filtering 多个同屏）可能触发 premium 上游内容审核（见 `troubleshooting.md`）——尽量用中性词（Estimator/Candidate/Select）
+- **字体规范进 prompt**（见下节）：正向写 "clean sans-serif English labels in Helvetica/Arial style"，禁令写 "NO handwritten, cursive, script, or decorative fonts"——两处都写，图模型对禁令响应弱于正向描述
+
+---
+
+## 字体规范（论文图没有手写体的位置）
+
+学术图字体有惯例，prompt 不写，图模型就会自由发挥出花体/手写体/装饰字——论文里不可接受：
+
+- **图内标签/轴/图例**（AI 图与 matplotlib 重绘通用）：**无衬线**，Helvetica / Arial / DejaVu Sans 风格；衬线体（Times/Computer Modern）属于正文与数学公式，不进图
+- 🔴 **永远禁止**：手写体、花体、cursive/script、Comic 风格、装饰性描边字
+- prompt 措辞模板：`clean sans-serif English labels in Helvetica/Arial style; NO handwritten, cursive, script, or decorative fonts`（正向+禁令各写一次）
+- **全文一致性**：同一篇文档的所有图统一字体族——本地重绘 `matplotlib.rcParams['font.family'] = 'DejaVu Sans'`，AI 图 prompt 统一写 "Helvetica/Arial style"
+- 审核清单第 9 项专门核对
+
+---
+
+## 阶段 2：提示词审核（pass 了才准调 API）
+
+### 审核清单（9 项，全过才 pass）
+
+1. **实体拼写**：每个实体名与用户材料逐字一致？（拼错=图上永久拼错）
+2. **实体完整**：意图清单里的实体是否都进了 prompt？有没有私加的？
+3. **结构正确**：流向/并行/汇合与用户确认的一致？
+4. **无数值承诺**：prompt 里没有会被画进图的精确数字？
+5. **图种匹配**：声明的图种与结构描述匹配（管线图≠机制图≠数据图）？
+6. **档位合理**：草稿 standard / 定稿 premium？文字密集图必须 premium 或已有 PIL 修补预案？
+7. **参数齐全**：ratio、size 是否按收敛表定了？
+8. **可润色性**：长度 150-300 词、大白话、无公式符号？
+9. **字体合规**：有无衬线正向描述 + 手写/花体禁令？与全文其他图同一字体族？
+
+### 审核执行方式
+
+- **最低要求**：构建 Agent 自审——把 9 项逐项过一遍，把结果展示给用户再调 API
+- **推荐（本 skill 鼓励的方式）：双 Agent 互审**，见下节
+
+---
+
+## 双 Agent 协作模式（推荐用户开两个 Agent）
+
+把「理解需求的智能」放在用户侧（用户的 Agent 天然带着论文/代码/历史对话上下文，比云端任何问询都懂用户），云端只承担最终出图。推荐分工：
+
+```
+用户 ──需求──→ Agent A（构建者：有完整用户上下文）
+                 │ 产出 handoff.json
+                 ↓
+              Agent B（审核者：读 skill + handoff.json + 用户材料，独立按 9 项清单判）
+                 │ pass → 用户授权 → Agent A 调 API
+                 │ reject → 打回 Agent A 重写（免费，循环直到 pass）
+                 ↓
+              出图 → 用户看图 → 不满意回 Agent A 改 prompt（仍是本地迭代）
+```
+
+### 交接契约 `handoff.json`（Agent A 写、Agent B 读）
+
+```json
+{
+  "intent": {"figure_type": "pipeline", "scene": "journal", "tier": "draft-then-final"},
+  "entities_source": "sec/2_method.tex L120-135（原词出处，供审核比对）",
+  "request": {"prompt": "…", "model": "standard", "ratio": "16:9", "size": "2K"},
+  "review": null
+}
+```
+
+Agent B 审核后回写：`"review": {"verdict": "pass|reject", "reasons": ["实体 'Extrection' 应为 'Extraction'（2_method.tex L128）"], "checked": [1,2,3,4,5,6,7,8,9]}`。
+
+**打回循环的成本是零**——这正是这个模式的意义：把原本「出图后看结果才发现不对」的返工，变成「出图前两秒就能发现」。
+
+### 给用户的使用提示（Agent 应主动说）
+
+> 建议开两个 Agent：这个窗口我负责理解你的需求并写提示词，另开一个窗口让 AI 读 promptfigure skill 的 `prompt-review-workflow.md` 当审核员，把 `handoff.json` 丢给它过 9 项清单，pass 了再回来出图。
+
+---
+
+## 阶段 3：出图与收敛
+
+- **第一次调用前**把阶段 0-2 的产物（确认卡 + prompt + 审核结论）展示给用户——用户点头才花钱
+- 失败（502/审核拒）→ 按 `troubleshooting.md` 处置；**不满意** → 回阶段 1 改 prompt 重走审核，**禁止不改 prompt 原样重试**
+- 草稿满意后升 premium：**复用同一个 prompt**（只改 model/size），保证草稿→定稿一致
+- 出图后记台账（`figure-upgrade-workflow.md` §5）
+
+---
+
+## 阶段 4：成图审核反馈环（宿主 AI 亲自读图，强制）
+
+**出图 ≠ 交付。** 审核完全由你（宿主 AI）执行——插件只负责把标准交到你手上，
+不替你审、也没有别的模型帮你看。把没读过的图直接甩给用户 = 把质检责任推给花钱的人。
+
+### 🔴 严格度条款（先读这个再开始审）
+
+1. **硬门槛制，不打印象分**：5 个维度每维独立判 PASS/FAIL，**任何一维 FAIL 即整图不合格**。
+   不存在"基本合格""整体不错"——那是放行，不是审核。
+2. **错一个字母也是 FAIL**：实体标签逐字比对，`Params → Perams`、`Unified → Unifed` 都是 FAIL，
+   不以"看得懂"为由放行。图上出现任何非实体清单里的文字（乱码、幻觉标签、多余水印）直接 FAIL。
+3. **证据先行，没证据不许下结论**：每个判定必须引用你**在图上看到的具体内容**
+   （"左二模块写作 Coarse Flter，缺 a"），写不出证据的判定视为没审。
+4. **禁止软化反馈**：FAIL 项必须转成可执行的 prompt 修改指令（写清哪一句改成什么）。
+   "画好点""文字再清楚些""配色可以更学术"这类说法 = 没有反馈。
+5. **自查两问**（审核前默念）：我放大看每个标签了吗？我是不是在替图模型找借口？
+
+### 5 维度审核（每维 PASS/FAIL + 图上证据，逐条写，不许只给总分）
+
+| 维度 | 判据 | FAIL 实例（2026-09-25 实测） |
+|---|---|---|
+| A 结构保真 | **判定前先逐箭头口述拓扑事实**（答错即 FAIL，禁止跳过）：每个箭头的起点是哪个块、终点是哪个块，按「X → Y」逐条列出，与确认卡比对方向。**不许用"方向正确"一笔带过**——2026-09-25 实测宿主把 Diffusion→Prior 看反成 Prior→Diffusion 还放了行 | 漏了某个模块；单向流画成双向；箭头起终点说反；语义上的"引导/前置"模块被画到下游 |
+| B 文字正确 | 图上**每个**标签与实体清单逐字比对（放大看） | "disnark"、"Unifed Preprocesing"、"Perams"、标题整行乱码 |
+| C 科研风格 | **判定前先答两个事实问题**（答错方向即 FAIL，禁止跳过）：① 背景是纯 #FFFFFF，还是带颜色/纹理/米灰色调？② 线条是均匀几何矢量，还是手绘笔触/水彩纹理/有阴影？图模型爱把「扁平矢量」跑成手绘水彩风，别被"浅到接近白"骗过去 | 米色纹理底；手绘水彩质感判成"纯白扁平"；彩虹配色；黑灰厚底块 |
+| D 信息密度 | 不空盒子（每个区域有自己的母题/内容）也不过挤 | 四个阶段画成一模一样的板子 = 空盒子 |
+| E 母题到位 | 阶段 1 里每个 show 画法句都被画出来 | 要缩略图没画、要漏斗没漏斗 |
+
+### 审核卡（每张图必出，格式固定）
+
+审完不给审核卡 = 没审。每张图按此格式输出后再决定下一步。
+**铁律：先观察后判定**——每维第一行必须先写「图上实况」（位置级/逐箭头的事实描述），
+第二行才能写 PASS/FAIL。先写结论再找"证据"的一律视为假审核：
+
+```
+【成图审核卡】图 N（model / 比例 / 迭代第 X 轮）
+A 结构保真：实况=<逐块列出位置 + 逐箭头列出 X→Y> → PASS/FAIL
+B 文字正确：实况=<逐个标签列出实际拼法> → PASS/FAIL（有错写"实际渲成 X，应为 Y"）
+C 科研风格：实况=<背景色/纹理、线条性质、有无阴影> → PASS/FAIL
+D 信息密度：实况=<各区域内容> → PASS/FAIL
+E 母题到位：实况=<逐条对 show 画法句在图上的对应物> → PASS/FAIL
+判定：合格（全 PASS，递给用户）/ 不合格（n 项 FAIL，执行下方修改指令后重出）
+修改指令（每 FAIL 项一条，写明 prompt 里哪句改成什么）：
+1. "……" → "……"
+```
+
+**交付路径**：最终图和中间产物一律存**当前工作目录相对路径**（如 `./fig1.png`），
+并把这个相对路径告诉用户——禁用 `/tmp`（Windows 双解析坑），
+不许让用户去系统临时目录里翻文件（2026-09-25 实测交付物落进 `C:\tmp` 用户找不到）。
+
+**台账**：每次 API 调用后向当前目录 `pf-ledger.md` 追加一行：
+`| 时间 | 图名 | model | ratio | crafted | 结果 |`——多图任务结束时给用户看总账。
+
+### 读图前的资源守则与降级判定（实测教训，2026-09-25）
+
+**有视觉就省着用（机械化执行，不留判断空间）**：
+0. 🔴 **先验完整性，再读缩图副本，永远不 Read 原图**——审核前固定执行：
+   ```bash
+   python -c "from PIL import Image; Image.open('<图>').verify()" && echo INTACT
+   python -c "from PIL import Image; im=Image.open('<图>').convert('RGB'); im.thumbnail((800,800)); im.save('audit_view.jpg', quality=80)"
+   ```
+   **verify 失败（截断 PNG）= 无效交付，禁止审核、禁止递给用户**：宿主工具掐断 curl 会写出
+   不完整 JSON → b64 部分解码 → 图底部黑带/缺 IEND（2026-09-25 实测：宿主明知截断仍判
+   "纯白背景 PASS"，把黑带伪影放行了）。处理：resp.json 本身不完整就重调 API 重出。
+   premium 2K 成品 2-3MB，直接 Read 原图一次 ≈ 77 万 token，一张就撑爆会话（同日实测）。
+1. **800px 缩图审结构/风格/密度；逐字拼写核对必须用标签特写（所有含文字的交付图，不限 2K）**：
+   800px 缩图上的文字**不可作为拼写判定的依据**——2026-09-25 实测：宿主读完 1312px standard
+   草稿的 800px 副本后宣称「全部标签逐个核对拼写均正确 → PASS」，图上实际有 2 个错拼
+   （`Outupt` / `Fidedlity`）。**B 维判定前必须用 PIL 把各标签区域 crop 出来拼成一张特写图
+   再读**（仍然只读这一张拼图），读不出/看不清就老实标「无法确认」转用户自查——
+   **不许编拼写判定，缩图上"看起来对"不算核对过**
+2. **同一张图只读一次**：请求因网关报错（`Content block not found` 等）失败时，**不要重读图片**——
+   图片内容已在上下文里，直接基于它继续；重读只会加倍 token（实测同图被读 3 次）
+3. **一次只读一张图**，审完再读下一张
+4. **读图后自检上下文**：单图读入后暴涨数万 token = 网关把图片 base64 当文本计数
+   → 本会话停止再读任何图，基于已读内容完成审核；一张都没读过才走降级分支
+5. **会话图片预算 ≤3 次**；宿主支持历史压缩的（如 claude CLI 的 /compact），阶段 4 读图前先压缩
+
+**宿主读不了图的降级分支（必须走，禁止跳过）**：
+- 触发症状（任一即触发）：读图报 `Content block not found` / 不支持图片块 / 400 上下文超限 /
+  你本来就没有视觉能力
+- **正确做法**：向用户明示「我这边读不了图」，然后把审核交给用户——给出审核卡的 5 个维度
+  改写成用户自查三问（①实体名有没有拼错的？②有没有乱码/多余文字？③风格是不是纯白底、
+  扁平、无阴影？），并附上每张草稿的文件路径
+- **🔴 禁止假装审核**：没有真正读过图，**绝对不许**输出任何 PASS 或"看起来不错"。
+  没读图就给判定 = 欺骗用户，比不审核更恶劣
+- 可以补一句建议：把图发给支持视觉的会话/模型审核，或宿主换带视觉的通道
+
+### 反馈环（FAIL 项 → 免费迭代）
+
+1. **每个 FAIL 项转成一句具体的 prompt 修改指令**——写清「哪一句改成什么」，
+   不许写「画好点」「文字清楚些」这种无法执行的反馈
+2. 回阶段 1 改 prompt → 阶段 2 重审 → 重出。standard 草稿迭代 2-3 轮是正常节奏，
+   每轮 ≈ $0.02，仍远低于 premium 试错
+3. **迭代上限**：同一 FAIL 连续 2 轮修不掉 → 换写法（拆 panel / 按草稿策略删文字 / 换图型），
+   不许第 3 次原样重试
+4. 全 PASS → 连同 5 维度证据一起递给用户。给用户的是**选择题不是开放题**：
+   两张草稿挑一张、A 方向还是 B 方向，比"你觉得怎么样"高效得多
+
+### 笼统输入的默认打法（用户说"帮我画张图"粒度时）
+
+1. 你先按 5 项意图清单**全部给出推定**（图种怎么定、实体从用户材料抽到哪些、结构怎么推），
+   做成确认卡——用户回数字即执行；不回复就按推定走 standard 草稿，别干等
+2. 笼统输入**一律草稿先行**：standard 出 2 张构图方向不同的草稿（一张忠实推定、一张重构布局），
+   按阶段 4 审核筛掉差的，带 1-2 张过关的 + 各自改进点让用户挑
+3. **禁止拿笼统意图直接出 premium**——premium 只用于用户挑过的方向

package/adapters/codex/promptfigure/skills/promptfigure-api/references/setup-guide.md

@@ -0,0 +1,151 @@
+# 拿到 promptFigure API key
+
+全程站点：https://promptfigure.top
+注册 **不需要邮箱验证码**，邮箱 + 密码（≥8 位）即可。
+
+**主路径：网页**。`/api/login`、`/api/keys` 等内部接口**面向已登录会话**，curl 注册可用但绕过了 UI（且会受 WAF UA 拦截），建议人肉注册、AI 只接管「登录后拿 key」这一步。
+
+---
+
+## 路径 A：网页人肉（小白 / 默认推荐）
+
+最稳。UI 自带 401/校验/防风控。
+
+1. 打开 https://promptfigure.top
+2. 右上角点 **注册**（或 登录）。填邮箱 + 密码（≥8 位），提交即完成，**无需验证邮件**
+3. 打开 https://promptfigure.top/console#account-balance 充值（$1 起、必须整数，上限 $10000；每满 $50 赠 $1 进余额——按 `floor(金额/50)` 计算，**零头不累计**：$99 只赠 $1，$100 赠 $2）
+4. 打开 https://promptfigure.top/console#account-keys → 点创建 → **复制明文 key（`pf_` 开头），立刻存好**
+5. 把 key 交给调用方环境变量：
+
+```bash
+export PROMPTFIGURE_KEY=pf_xxxxxxxx
+```
+
+⚠️ key 是 **会话内一次性明文**，弹窗关闭后只能看到 hint。库内只存 SHA-256 哈希 + hint。
+⚠️ SPA 必须带 hash 直达标签页：`#account-keys` / `#account-balance` 缺一不可，否则落总览页。
+
+---
+
+## 路径 B：浏览器自动化（有桌面/浏览器控制能力的 Agent）
+
+⚠️ **仅当路径 A 因浏览器限制不可用时用**。注册走 UI 风险大于收益，下面这版只接管「登录 + 拿 key」。
+
+注册（请用户自己点一次 UI）：
+- 邮箱 + 密码注册一次拿 `pf_` key 即可
+- 注册后只登录会话：弹窗顶部是**分段控件（segmented-control），「登录」「注册」两个 tab 按钮并排**——点「登录」按钮切到 login tab → 填 email/password → 提交。**没有「已有账号？」这类链接文案**，自动化时按 segmented-control 内的按钮文本（登录 / Login）定位
+
+登录后的 DOM 选择器（实测有效）：
+
+| 元素 | 选择器 |
+|---|---|
+| 邮箱输入 | `#lite-email` |
+| 密码输入 | `#lite-password` |
+| 登录/注册弹窗关闭 | `.modal-close` |
+| 提交按钮 | `.primary-action` |
+| API 密钥标签页 | 访问 `/console#account-keys` |
+| 余额标签页 | 访问 `/console#account-balance` |
+| 调试台 key 输入框 | `#pf-play-key` |
+| 调试台 prompt 输入框 | `#pf-play-prompt` |
+
+要点：
+- 登录入口是**右上角弹窗**，不是独立登录页——需先点触发再操作表单
+- 弹窗分 登录 / 注册 两个 tab，注册按钮在同一弹窗内切换（`mode` 状态）
+- SPA 路由走 `history.pushState`，自动化时应直接导航完整 URL（含 hash），不要依赖点击导航
+- 创建 key 后明文弹窗通常带「复制」按钮，优先点复制；若需读取文本，直接读弹窗 DOM 文本而不用 OCR
+- 浏览器 fetch 不会被 CF WAF 拦截（只有默认 UA 才拦）
+
+---
+
+## 路径 C：纯 curl（无 UI 场景 / 自建脚本）
+
+⚠️ 注册/登录/建 key 都是内部 REST 接口，**没文档承诺稳定**——产品主路径是网页。这条路径出问题时，请优先回退到路径 A。
+
+### 客户端 UA（必经）
+
+CF WAF 会拦 `Python-urllib/*`（实测 403 error code:1010）。其它都过。**curl 默认 UA 不在拦截名单里，可以直接用**；Python `requests` 默认 UA 也能过；只有 `urllib.request` 需要手动改 UA：
+
+```python
+import urllib.request
+req = urllib.request.Request(url, ...)
+req.add_header("User-Agent", "Mozilla/5.0")  # 绕过 CF WAF 拦截
+```
+
+### 1. 注册（可选，有账号则跳到 2）
+
+```bash
+curl -s -X POST https://promptfigure.top/api/register \
+  -H "Content-Type: application/json" \
+  -d '{"email":"you@example.com","password":"至少8位"}'
+```
+
+成功返回 `201` + `{ token, userId, email, balance: 0, ... }`。
+`409 email_taken` → 跳步骤 2 直接登录。
+
+### 2. 登录
+
+```bash
+curl -s -X POST https://promptfigure.top/api/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"you@example.com","password":"你的密码"}'
+```
+
+返回 `{ token, userId, email, balance, credits, ... }`，token 是 session token（30 天有效）。
+
+### 3. 创建 API key
+
+```bash
+export PF_TOKEN=<上一步的 token>
+curl -s -X POST https://promptfigure.top/api/keys \
+  -H "Authorization: Bearer $PF_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"my-agent"}'
+```
+
+返回 `{ id, key:"pf_...", hint, name, createdAt }`。立刻存：
+
+```bash
+export PROMPTFIGURE_KEY=pf_xxxxxxxxxxxxxxxx
+```
+
+⚠️ **明文只在此响应中出现一次**，库里只存 SHA-256 哈希 + hint。丢了无法找回，只能吊销重建。
+
+### 4. 充值（必须步骤）
+
+API 计费**只从余额扣**，与会员额度完全独立。新注册余额为 0，不充值调用会 `402`。
+充值走网页：https://promptfigure.top/console#account-balance（$1 起，整数）。
+**付款动作不应由 Agent 代劳**，留给用户人肉操作。
+
+### 5. 验证
+
+```bash
+curl -s -X POST https://promptfigure.top/api/v1/generate \
+  -H "Authorization: Bearer $PROMPTFIGURE_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt":"Simple two-group bar chart comparing method A and method B","model":"standard"}' \
+  | jq '{size, ratio, model, crafted, charged, balance}'
+```
+
+看到 `crafted: true` + `charged: 0.02` + `balance` 减少 → 打通（默认管线实测约 40–90 秒；若 502 看 `references/troubleshooting.md`）。
+
+---
+
+## key 管理
+
+```bash
+# 列表（不含明文，只有 hint）
+curl -s https://promptfigure.top/api/keys -H "Authorization: Bearer $PF_TOKEN"
+# 吊销
+curl -s -X POST https://promptfigure.top/api/keys/revoke \
+  -H "Authorization: Bearer $PF_TOKEN" \
+  -H "Content-Type: application/json" -d '{"id":"<key id>"}'
+```
+
+每人最多 10 把未吊销 key。
+
+---
+
+## 安全提示
+
+- key 不进代码仓库、不进 commit。放环境变量或 secrets store
+- 怀疑泄露先吊销再重建，成本为零
+- 一次性不要创建过多 key；按用途命名（如 `paper-agent`、`lab-batch`）便于追溯