promptfigure 0.2.0 → 0.3.0

package/adapters/codex/promptfigure/skills/promptfigure-api/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: promptfigure-api
+description: 用 promptFigure 生成科研/学术配图（流程图、机制图、管线图、技术路线图、图形摘要），以及优化已有图表、整文批量升级（数据图本地重绘 + 示意图 AI 重构 + 可编辑矢量版 + 追溯台账）。当用户要「画一张图」「生成论文配图/示意图/机制图/graphical abstract」「把论文里的图变好看/变高级」「批量优化整篇文章的图」「要可编辑的矢量图/PPT 版」、给了 PDF/WPS/Word 文稿要配图或要主动建议插图位、或要配置 promptFigure API key、或要用 REST 接口批量出图时使用。走 https://promptfigure.top 的 /api/v1/generate，Bearer pf_ key 鉴权，返回 base64 PNG。强制学术字体规范（图内无衬线、禁手写/花体）与上下文蒸馏规则（原文段落绝不直接进 prompt，先蒸馏成实体/结构/图种三清单再组装）。网页端有多轮问询/二次确认，API 端一次性提交——所以要把用户绘图意图一次说清楚，服务端负责润色成完整示意。
+version: 1.6.8
+license: MIT
+metadata:
+  version: "1.6.8"
+  author: promptFigure (zhangmask)
+  homepage: https://promptfigure.top
+  repository: https://github.com/zhangmask/promptfigure-skill
+  latest-check: https://promptfigure.top/downloads/promptfigure-api.version.json
+---
+
+# promptFigure 出图技能
+
+把一句大白话变成可直接放进论文的科研图。整套管线（LLM 编排 + 提示词工程 + 审查 + 出图）都在服务端，调用方只需把**用户的绘图意图说清楚**。
+
+**线上站点**：https://promptfigure.top
+
+## 🔴 工作流总览：先对齐，后花钱
+
+**整个流程里唯一花钱的动作是 API 调用**。所有迭代都在本地免费环节完成：
+
+```
+阶段 0 意图确认（对用户）→ 阶段 1 写提示词 → 阶段 2 提示词审核 → 阶段 3 API 出图 → 阶段 4 成图审核 → 阶段 5 可编辑矢量版（可选，交付后必问用户）
+                                ↑__________ 打回/不满意只回到这里改 prompt，免费 __________↑
+```
+
+- **阶段 0-2 强制免费前置**：意图没对齐、prompt 没过审，不准调 API。详见 `references/prompt-review-workflow.md`
+- **🔴 读图守则是全局规则（所有阶段都算数，不只阶段 4）**：网关把图片按 base64 文本计 token（800px 缩图 ≈8 万，原图最高 ≈77 万），宿主每轮全量重发历史 → 读图几次必爆上下文上限（实测 532k > 524k 会话死亡）。所以：①**盘点/清点/检查旧文件时禁止 Read 任何图片**——用 PIL 打印尺寸、mode、文件头完整性就够，看内容不属于盘点 ②读图只发生在阶段 4 审核，**全流程 ≤3 次** ③一律读 800px 缩图副本，不读原图
+- **🔴 先核实后宣称（禁止虚报进度）**：curl 返回、且 resp 文件已落盘、且 JSON 元数据已回显之前，**禁止向用户说「已提交 / 已在生成 / 已计费 / 预算已花」**。没核实就宣称 = 欺骗用户（实测：宿主用 Bash 工具后台机制跑 curl，会话一结束任务被杀，resp 文件根本没落地，却报告"已提交、预算 $0.04"）。对应地：**curl 一律前台 + `--max-time 300`**；宿主 Bash 工具的"后台任务"机制会在会话结束杀死任务，禁止用它跑 curl；确需后台只允许 `nohup … &` 脱离会话 + 主动轮询到结果才结束回合。**台账 `pf-ledger.md` 每次调用后立即补一行**，禁止建空表不填
+- **阶段 4 强制成图审核（审核主体 = 你，宿主 AI）**：插件把标准交给你，审图由你亲自执行。出图 ≠ 交付——按 5 维度判定，**铁律：先观察后判定**，每维先写「图上实况」（A 维逐箭头口述 X→Y、C 维答背景/线条两问）再写 PASS/FAIL，先写结论再找证据 = 假审核；**硬门槛制：任何一维 FAIL 即整图不合格，错一个字母也是 FAIL，不打印象分、不软化**。每张图输出固定格式【成图审核卡】（实况 → 判定 → 修改指令），FAIL 项转成具体 prompt 修改指令回阶段 1 免费迭代。**读图守则：先 PIL verify 验完整性（截断图=无效交付，禁审禁交付）、一律读 800px 缩图副本不读原图、拼写核对一律用标签特写拼图（所有含文字的交付图，缩图不构成拼写证据——实测 1312px 草稿 800px 副本漏判 2 个错拼）、同图不重读、会话读图 ≤3 次**；宿主无视觉/网关不吃图时**必须明示用户并转用户自查，没有读过图绝对禁止输出 PASS（禁止假装审核）**。最终图存**当前目录相对路径**并告知用户，API 调用记台账（`pf-ledger.md`）。标准与降级分支详见 `references/prompt-review-workflow.md` 阶段 4
+- **双 Agent 模式（推荐给用户）**：Agent A（有用户上下文）写提示词，另开 Agent B 按 9 项清单审核 `handoff.json`，pass 才出图——把返工从"花钱买废图"变成"出图前两秒发现"
+- 出图本身一次到位率 >> 边出边改
+
+---
+
+## 🔴 阶段 5：可编辑矢量版（可选，交付后必须先问用户）
+
+终稿（阶段 4 PASS）交付后，**问用户一句**：「还要可编辑的矢量版吗？」——**不许默认做，也不许默认跳过**：用户没明确说「要」就不做；用户说「要」才进入本节。
+
+**要不要做，只看场景**：
+
+1. 🔴 **比赛 / 数学建模 / 学术会议竞赛**：默认建议**不做**，以速度为准——这些场景交 PNG 就够，矢量版是时间黑洞，别为它赌提交时限
+2. **时间充裕**（用户明确表示不赶、或场景是期刊/课设/长期维护的图）：做。全部用**用户本地的工具或代码**完成，不调用 promptFigure API、不消耗任何额度
+
+**做法（三条红线 + 一条推荐路）**：
+
+- 🔴 **禁止描摹矢量**：vtracer / potrace /「位图转 SVG 路径」之类一律不用——描摹出来的文字全是路径，不可编辑、不可搜索，越改越错。描摹矢量和「可编辑矢量」是两种东西，别拿描摹滥竽充数
+- 🔴 **必须是可编辑矢量**：每个元素是独立对象——PPT 形状、独立 SVG 元素/分组、Illustrator 图层都行。验收标准一句话：**用户能改，你的（宿主 AI）也能改**——后续微调是改对象属性，不是重画
+- 🔴 **文字保持文本**：标签必须是可编辑文本（无衬线，遵循图内字体规范），不许转路径
+- **推荐路**：拿最终确认版图，用本地代码/工具**照着画一遍**——如 python-pptx 生成形状化 PPTX、或写结构化 SVG（每个模块/箭头/标签一个元素），画完与确认版逐项比对、不一致就改，迭代到一致为止。参考做法：<https://github.com/icebird1998/scientific-illustifier>（宿主自行阅读，按本机工具链取舍）
+- 宿主没有本地矢量工具链（没有 python-pptx / 没有矢量软件 / 跑不动）时：**明示用户「做不了可编辑矢量版」**，交付确认版 PNG 收尾——仍然不许用描摹顶替
+
+**交付物**：矢量文件 + 一句「哪些元素可以直接改」（如「每个方框、箭头、文字都是独立形状，可拖动/改字/改色」）；`pf-ledger.md` 补一行，标注本地生成、零 API 消耗。
+
+---
+
+## 🔴 草稿策略：低文字密度 + 科研风格基线（2026-09-25 实测定规）
+
+standard 档的乱码率随**卡面文字量**上升：实测说明性小字是乱码重灾区
+（"discards background patches" → "disnark"、"6-layer transformer encoder" 整行乱码、
+标题 "Technical Roadmap" → "Cattlreet Tbgleftste"），而实体名短标签几乎不出错。
+草稿要好看且不乱码，构造 prompt 时按两条铁律：
+
+1. **卡面文字只留实体名**：草稿 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`
+   实体名标签本身必须逐字正确（这些错不起）。说明性小字留到 premium 定稿再加回
+   （gpt-image 文字渲染显著更强），且逐字写。
+2. **风格基线块句句带上**（润色层不会替你补）：
+   `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`
+   每个颜色对应一个角色；禁止单一色相约束（见 `prompt-cookbook.md` 配色节）。
+
+草稿是「构图探索」，不是缩水定稿：**构图、母题、配色在草稿里全定下来**，premium 只换清晰度
+和补回文字。详细构造法与正反例见 `references/prompt-cookbook.md`「草稿 = 低文字密度构造法」。
+
+---
+
+## 网页 vs API：同一个管线，少一步问询
+
+**`/api/v1/generate` 跑的就是网页工作台那一套完整管线**——LLM 编排、意图路由、确定性净化、独立审查、出图，全部包含。**唯一区别**：
+
+| | 网页工作台 | `/api/v1/generate` |
+|---|---|---|
+| 管线 | 完整 | **同款完整** |
+| 交互 | 多轮问询 + 二次确认 | **一次性提交，无问询** |
+| 结果 | 页面展示 + 下载 | JSON 返回 base64 PNG |
+
+所以**「一次性答完」指的是补全用户的绘图意图，不是替服务端写提示词**。
+
+- ✅ 正确：一次性说清「画什么图、有哪些实体、什么结构」→ 交给服务端润色扩写成完整示意
+- ❌ 错误：以为没有网页问询就可以自作主张改写/增删用户意图——那会丢信息
+
+---
+
+## 🔴 反问边界：先澄清意图，出图过程零反问
+
+**阶段 0（对用户）——意图不明必须主动澄清**：实体是泛称、结构推不出来、用户材料里找不到对应物时，**停下来问**，一次问完（给选项不给开放题）。这是买保险：30 秒的确认换掉 $0.15 的废图。清晰输入则回显确认卡后直接执行，不打断用户。
+
+**阶段 3（对 API）——零反问**：出图过程不向用户追问任何参数。信息不足就从上下文推断 + 占位符补全，一次性提交。
+
+- ❌ 禁止（任何时候）：「你想画什么风格？」「用什么配色？」「比例几比几？」——按一次性收敛表推定
+- ✅ 阶段 0 允许且必须：「三个模块用论文原名还是占位名？」「A→B 是单向还是有反馈？」——**只问意图级问题，一次问完**
+- ✅ 阶段 3 正确：确认卡已过 → 提交 → 出图 → 不满意回阶段 1 改 prompt
+- ✅ **用户说得特别笼统时（"帮我画张方法图"粒度）**：你先按 5 项意图清单**全部给出推定**（图种怎么定、实体从用户材料抽到哪些、结构怎么推），做成确认卡——用户回数字即执行，不回复就按推定走 standard 草稿。笼统输入**一律草稿先行**：standard 出 2 张构图方向不同的草稿（一张忠实推定、一张重构布局），你按阶段 4 审核筛掉差的，带过关的 + 改进点让用户挑。**禁止拿笼统意图直接出 premium**。
+
+完整协议（5 项意图清单 / 两档处理 / 确认卡模板）见 `references/prompt-review-workflow.md`。整文级批量任务的开工澄清（场景/模式/原始材料/档位）见 `references/figure-upgrade-workflow.md` §1。
+
+---
+
+## ✅ 管线状态（2026-09-09 核对）
+
+默认润色管线**正常**。润色文本模型已升级为 `agnes-2.5-flash`，并内置上游 429 自动回落（`agnes-2.0-flash` 整体重试一次）——调用方无感。
+
+| 项 | 状态 |
+|---|---|
+| `/api/v1/generate` 默认（带润色） | ✅ 实测 42–90s 出图，`crafted: true` |
+| 上游 429 限频期 | 服务端自动回落重试；若仍 502，看 `detail` 里的 `last_text_failure`，稍后原样重试即可（会自动退款） |
+| `polish:false` 直出 | ✅ ~11s，**仅紧急绕过用**（服务端不扩写，需自己写完整英文提示词） |
+
+**`polish:false` 不是常态**。仅当默认管线连续失败且 `detail` 显示上游故障、你又赶时间时才用。写法见 `references/prompt-cookbook.md` 的「降级模式」章节。
+
+⚠️ 走 `polish:false` 时图模型英文文字渲染明显下降（实测出 "Mcıuacy" 这类乱码）。重要场合用 `premium`（gpt-image 文字渲染优于 standard 的 Agnes）。
+
+---
+
+## 一次性收敛：交请求前内部定下 6 项
+
+| 项 | 必填 | 推定规则（按序命中即停） |
+|---|---|---|
+| `prompt` | ✅ 唯一必填 | **大白话即可，把意图说清楚**——服务端会润色扩写。关键是**实体写全**（组名/模型名/基因名/数值/实验条件）。详见 `references/prompt-cookbook.md` |
+| `model` | 推荐显式传 | 草稿/自用验证/批量试错的迭代稿 → `standard`（$0.02）；**正式交付、放进论文或汇报 → `premium`（$0.15）**。拿不准就用 `premium`。服务端默认 `standard` |
+| `size` | 默认 2K | 仅 `premium` 可设；1K/2K **同价**，无脑 2K。`standard` 恒 1K |
+| `ratio` | 默认 `1:1` | 多 panel 组合图 / 技术路线图 / 图形摘要 / 横向流程 → `16:9`；纵向信号通路、级联瀑布 → `9:16`；期刊单幅 Results 图 → `3:2`；方法示意图、单主体图 → `1:1` |
+| `refUrl` / `refDataUrl` | 无则不传 | 有参考图 → 优先 `refUrl`（公网图片直链，服务器代取）。本地图 → 挂免费图床（x0.at / uguu.se）拿直链，或用 `refDataUrl`（base64 PNG ≤8MB）。二选一，`refDataUrl` 优先 |
+| `polish` | 默认润色 | 正常不需要传。仅默认管线连续失败且 `detail` 显示上游故障时，才传 `false` 紧急绕过 |
+
+---
+
+## 调用
+
+```bash
+curl -s --max-time 300 -X POST https://promptfigure.top/api/v1/generate \
+  -H "Authorization: Bearer $PROMPTFIGURE_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt":"<大白话描述，实体写全>","model":"premium","ratio":"16:9"}'
+```
+
+响应 `.b64_json` 是 PNG：
+
+```bash
+curl -s ... | jq -r .b64_json | base64 -d > figure.png
+```
+
+🔴 **响应必须落文件，禁止直接回显**：响应体含几百 KB 的 base64（约 50 万 token 级别的文本）。
+直接把响应打印/写进对话轻则污染上下文，重则一击撑爆会话（2026-09-25 实测发生过）。
+永远：`curl -o fig.json`（或管道进 jq/base64 落盘）→ 用 jq 只提取 `size/model/crafted/charged/balance` 字段回显。
+🔴 **落盘与交付一律用当前目录相对路径，禁用 `/tmp`**：Windows 下 Git Bash 和 curl/python 对 `/tmp`
+解析不一致（AppData\Local\Temp vs `C:\tmp`），实测导致 8 轮「写成功但读不到」重试、交付物落进用户找不到的 `C:\tmp`。
+🔴 **curl 必须显式 `--max-time 300`**：生成 46s~160s+，宿主 Bash 默认 120s 会掐断（实测连续两次超时返工）。
+`timeout 300 curl` 救不了工具级掐断——Bash 工具有 timeout 参数的显式传 300000，没有的用 nohup 后台 + 分次轮询（见 `references/api-contract.md`）。
+
+⚠️ **CF WAF 拦 `Python-urllib/*`**（403 error code:1010）。curl / Node / Go / Python `requests` / 浏览器 fetch 都能过；urllib 需加 `User-Agent: Mozilla/5.0`。
+⚠️ **超时**：客户端 `timeout` 设 **≥ 300s**（完整润色管线是串行 3 次 LLM，premium 2K 偶尔更久）。
+
+---
+
+## 网页工作流等价的异步流程（可选）
+
+网页真实流水：**登录 → 拿 gen token（扣费）→ 提交异步任务 → 轮询结果**。AI 想拿与网页完全一致的处理可用这条。
+
+```js
+const tok = (await post("/api/login", {email, password})).token;
+const genToken = (await post("/api/generate-token", { token: tok, prompt, size:"1K", ratio:"16:9" })).token;
+const { jobId } = await post("/api/gen-async", { token: genToken });
+// 轮询 status: queued → polishing → imaging → qa → done（终态还有 error）
+const result = await poll("/api/gen-result", { token: tok, id: jobId });
+// result.imageUrl 图；result.prompt 服务端润色后的最终提示词
+```
+
+⚠️ 此路径**无 `polish:false` 开关**；上游文本限频期可能偏慢或失败，急用走 API 直调。
+
+完整契约、多语言示例、批处理见 `references/api-contract.md`。
+
+---
+
+## 响应与错误码
+
+成功：`{ b64_json, size, ratio, model, provider, crafted, charged, balance }`
+- `crafted: true` = 走了润色；`false` = `polish:false` 直出
+- `provider` = `agnes`（standard）/ `premium`（premium 档，高级档中转通道）
+
+| 码 | 含义 | 处置 |
+|---|---|---|
+| 401 | key 无效/已吊销 | 检查 `Authorization: Bearer pf_...`；重建 key |
+| 402 | 余额不足（不扣费） | 控制台充值（$1 起整数）后重试。**批处理/迭代任务开工前先查余额**（`balance` 字段滞后，以控制台为准），预估张数×单价+重试余量；中断时已完成图不回滚，从断点续跑 |
+| 429 | 超 RPM（免费 5 / Lite 10 / Plus 15 / Pro 40 / Ultra 80，账号级共享） | 串行 + 退避 |
+| 502 | 生成失败 | **已自动退款**；看 `detail` 的 `last_text_failure:`——含 `upstream 429` 是上游限频（稍后重试即愈），其余按 detail 判断；赶时间可临时 `polish:false` |
+| 403 | `error code: 1010` | CF WAF 拦了 `Python-urllib/*` UA，换客户端 |
+| 400 | `prompt_required` / `prompt_too_long` | prompt ≤8000 字符 |
+
+⚠️ **`balance` 字段滞后**：`/api/login`、`/api/me` 返回的 `balance` 不等于真实余额（实测返回 0 但扣费成功后余额 0.09）。判断余额以控制台 https://promptfigure.top/console#account-balance 为准。
+
+---
+
+## 首次使用：拿 key
+
+需要 `PROMPTFIGURE_KEY`。**网页为主路径**（含小白 + 浏览器自动化 AI），curl 仅高级补充。详见 `references/setup-guide.md`。
+
+1. 打开 https://promptfigure.top → 右上角 **登录/注册**（邮箱 + 密码 ≥8 位，**无邮箱验证**）
+2. 进 https://promptfigure.top/console#account-balance 充值（$1 起整数）
+3. 进 https://promptfigure.top/console#account-keys 创建 key → **明文 `pf_` 开头只出现一次**，立刻复制存好
+4. `export PROMPTFIGURE_KEY=pf_xxxx`
+
+⚠️ 明文丢失无法找回，只能吊销重建。
+
+---
+
+## 保持最新（重要）
+
+**上面「管线状态」是 2026-09-09 的核对快照。** 每次使用前若距上次核对 > 7 天，或用户报告了与本技能不符的行为，先探一次默认润色：
+
+```bash
+curl -s -X POST https://promptfigure.top/api/v1/generate \
+  -H "Authorization: Bearer $PROMPTFIGURE_KEY" -H "Content-Type: application/json" \
+  -d '{"prompt":"two-group bar chart comparing A and B","model":"standard"}' | jq .
+```
+
+`crafted: true` + 200 = 管线健康，无需任何特殊处理；502 看 `last_text_failure`（见 `references/troubleshooting.md`）。
+
+```text
+https://promptfigure.top/docs/zh-CN/api          # API 概览
+https://promptfigure.top/docs/zh-CN/api-playground  # 在线调试台
+https://promptfigure.top/docs/zh-CN/faq          # 常见问题
+https://promptfigure.top/pricing                 # 定价与额度
+https://promptfigure.top/news                    # 更新日志（看运维动态）
+```
+
+English 版把 `zh-CN` 换成 `en`。拿到新信息后**回写本技能文件**，别只在当次对话里用。
+
+本技能的**最新版打包**：https://promptfigure.top/downloads/promptfigure-api.zip —— 若发现本文件内容与线上文档不一致，可下载新版覆盖。
+
+### 版本自查（skill 与更新）
+
+本技能遵循 [Agent Skills 规范](https://agentskills.io/specification)，版本写在 frontmatter（`version` 顶层 + `metadata.version`，语义化版本）：
+
+- **查当前安装的版本**：读本文件 frontmatter 的 `version` 字段即可。
+- **查线上最新版本**（程序化，不用下载整个 zip）：
+
+```bash
+curl -s https://promptfigure.top/downloads/promptfigure-api.version.json
+# → {"name":"promptfigure-api","version":"1.5.1","updated":"2026-09-24","download":".../promptfigure-api.zip","changelog":"..."}
+```
+
+- 本地 `version` < 线上 `version` → 下载 zip 覆盖本地目录（保留 `pf_` key 等环境变量，它们不存放在 skill 目录里）。
+- 版本号含义：**主版本**变更 = 接口/流程不兼容改动（需重读 SKILL.md）；**次版本** = 新增能力（如新增参考文档）；**修订号** = 文字勘误。
+
+---
+
+## 参考文件
+
+| 文件 | 何时读 |
+|---|---|
+| `references/setup-guide.md` | 还没有 key，需要注册/登录/建 key/充值（含自动化选择器 + curl 路径） |
+| `references/prompt-cookbook.md` | **默认模式**：怎么把用户意图一次性说清楚。**降级模式**（polish:false）怎么写完整英文提示词 |
+| `references/prompt-review-workflow.md` | **每次出图前必读**：四阶段协议（意图确认→写提示词→审核→出图）、5 项意图清单、9 项审核清单（含字体合规）、双 Agent 互审与 `handoff.json` 交接契约 |
+| `references/api-contract.md` | 完整契约、网页工作流 4 步、多语言示例、批处理、WAF |
+| `references/troubleshooting.md` | 润色失败、WAF 403、balance 滞后、出图质量差 |
+| `references/document-workflow.md` | 用户给了 `.tex` / `.docx` / `.md` 文稿要配图：怎么定位插图位、从上下文写 prompt、插回文档；LaTeX 编译环境探测与官方下载指引（MiKTeX/TeX Live/TinyTeX/Tectonic/Overleaf） |
+| `references/figure-upgrade-workflow.md` | 用户要**优化已有图表**或**整文批量升级**：结果图数据溯源+本地重绘、示意图 AI 升级、结构组合、单图精修/整文批处理两种模式、figure-ledger.json 追溯台账 |
+| `references/proactive-upgrade.md` | 用户给的是 **PDF/WPS**（非 LaTeX）、说不出哪里插图要你**主动建议**、要从**原始数据**推演配图、或想参考顶会/SCI 论文的图学风格：PDF 解析、MCM 插图位惯例、四步管线（分析→推演→提示词→迭代）、refs/ 风格库与合规红线 |

package/adapters/codex/promptfigure/skills/promptfigure-api/references/api-contract.md

@@ -0,0 +1,319 @@
+# API 契约完整版
+
+**站点**：https://promptfigure.top
+
+---
+
+## ⚠️ 必看
+
+1. **默认就是完整润色管线**——`/api/v1/generate` 与网页工作台同一套（编排 + 净化 + 审查 + 出图），只是没有网页的多轮问询/二次确认。**不要因为要"一次性答完"就绕过润色。**
+2. **`polish:false` 仅是紧急绕过**（服务端不扩写，需自己写完整英文提示词），平时**不要传**。上游文本限频期服务端会自动回落重试（主模型 agnes-2.5-flash → 备用 agnes-2.0-flash）。
+3. **CF WAF 拦 `Python-urllib/*`**——其它客户端都过。
+4. **`balance` 字段滞后**——`/api/login`、`/api/me` 返回的 balance 不等于真实余额。
+
+---
+
+## 路径 A：API 直调（v1，同步）
+
+**Endpoint**：`POST https://promptfigure.top/api/v1/generate`
+**鉴权**：`Authorization: Bearer pf_...`
+**CORS**：全开（`Access-Control-Allow-Origin: *`），鉴权靠 key 不靠 cookie。
+
+### Request
+
+```jsonc
+{
+  "prompt":      "",        // ✅ 必填，大白话即可，≤8000 字符
+  "polish":      true,      // 默认润色；false 仅紧急绕过（服务端不扩写，平时不要传）
+  "model":       "standard" | "premium",   // 服务端默认 standard；非 "premium" 一律 standard
+  "size":        "1K" | "2K",              // 仅 premium 生效，默认 2K
+  "ratio":       "1:1" | "3:2" | "2:3" | "16:9" | "9:16",  // 默认 1:1，非法值回落 1:1
+  "refUrl":      "https://.../ref.png",    // 公网图片直链，PNG ≤8MB
+  "refDataUrl":  "data:image/png;base64,...",  // base64 后 ≤8MB
+  "mode":        "replica"                 // 一键临摹（2026-09-18）；别名 "replica":true、"mode":"一键临摹"
+}
+```
+
+规则：
+- `prompt` 空或缺失 → `400 prompt_required`（**临摹模式例外**：`mode:"replica"` 时 `prompt` 可留空，服务端补一句中性复刻指令）
+- `prompt` >8000 字符 → `400 prompt_too_long`
+- `model` 非 `"premium"` 任何值 → `standard`
+- `size` 非 `"1K"` → 2K；`standard` 恒输出 1K
+- `refUrl` + `refDataUrl` 都传 → **`refDataUrl` 优先**
+- `refUrl` 服务端安全限制：只接 `http(s)`；`localhost`/`.local`/`.internal`/环回与私网 IP 拒绝；校验 PNG 文件魔数（不看 content-type）；≤8MB；拉取超时 20s
+- **注意**：上游 `/images/edits` 端点 2026-09-07 起持续 503。`refUrl`/`refDataUrl` 当前可能 `refIgnored: true`（被忽略，**当次照常出图并计费**）
+
+### Response
+
+成功 `200`：
+
+```jsonc
+{
+  "b64_json": "<PNG base64>",
+  "size":     "2K",
+  "ratio":    "16:9",
+  "model":    "premium",
+  "provider": "premium",      // agnes=standard, premium=premium 档（高级档中转通道）
+  "crafted":  false,          // false=polish:false 直出
+  "charged":  0.15,
+  "balance":  12.34,
+  // 仅 mode:"replica" 出现：
+  "mode":          "replica",
+  "referenceSpec": { /* 见下「一键临摹」 */ },
+  "specError":     null       // 非 null = 参考图规格提取失败，已退化（不额外计费）
+}
+```
+
+失败：
+
+```jsonc
+{ "error": "insufficient_balance", "required": 0.15, "balance": 0.02 }   // 402
+{ "error": "rate_limited", "limit": 5 }                                   // 429，已退款
+{ "error": "generation_failed", "detail": "orchestration_failed: ...", "refunded": 0.15 }  // 502，已退款
+{ "error": "invalid_api_key" }                                            // 401
+```
+
+### 计费
+
+| model | 单价 | 输出 | 备注 |
+|---|---|---|---|
+| `standard` | **$0.02** / 次 | 恒 1K（Agnes） | 草稿、迭代、批量试错 |
+| `premium` | **$0.15** / 次 | 1K 或 2K **同价** | 终稿、正式交付、入 paper |
+
+✅ 尺寸不影响价格 → premium 无脑用 2K。
+✅ 每 key 关联账号，**只从余额扣**，与会员订阅额度独立。
+✅ **生成失败自动原路退款**（含 RPM 429 场景）。
+
+**RPM（每分钟请求数），与网页端共享同一窗口**：免费 5 · Lite 10 · Plus 15 · Pro 40 · Ultra 80。
+未订阅 = 免费层 5 RPM，批量任务务必串行 + 退避。
+
+### 调用示例
+
+#### Bash / curl（默认 UA 不会被 WAF 拦）
+
+🔴 **响应必须落文件，禁止把原始响应直接回显进对话**——`b64_json` 是几百 KB 的 base64
+（数十万 token 级），直接打印轻则污染上下文、重则撑爆会话（2026-09-25 实测）。
+照下面的范式：管道进文件，jq 只回显元数据字段。
+
+🔴 **落盘一律用当前目录相对路径，禁用 `/tmp`**（2026-09-25 实测）：Windows 下 Git Bash 的
+`/tmp` 指向 AppData\Local\Temp，而 Windows 版 curl/python 把 `/tmp` 解析成 `<当前盘>:\tmp`——
+两套解析混用会「写入成功但读不到」反复重试，最终交付物还会落在用户找不到的 `C:\tmp`。
+中间产物和最终交付图都放当前工作目录。
+
+🔴 **curl 必须显式 `--max-time 300`**：生成耗时 46s~160s+，很多宿主的 Bash 工具默认 120s
+就掐断命令（2026-09-25 实测连续两次超时返工）。宿主有 timeout 参数的一并设到 300s+。
+⚠️ **注意：`timeout 300 curl …` 救不了宿主工具级的 120s 掐断**——掐的是整个命令不是 curl。
+宿主 Bash 工具支持 timeout 参数的（如 claude CLI）调用时必须显式传（如 `timeout: 300000`）；
+不支持的用后台模式 + 分次轮询：
+
+🔴 **禁用宿主 Bash 工具自带的「后台任务」机制跑 curl**（claude CLI 的 run_in_background 等）：
+**会话一结束，未完成的任务直接被杀**——2026-09-25 实测 curl 被这样杀掉后 resp 文件根本没落地，
+宿主却已向用户报告"已提交、预算 $0.04"（虚报）。要后台只允许 `nohup … &`（脱离会话存活）+
+**轮询到 DONE 才能结束回合**；否则一律前台 curl。
+
+🔴 **先核实后宣称**：向用户报告任何进度前必须核实证据——resp 文件存在（`ls`）、
+JSON 合法（`jq '{size,model,crafted,charged,balance}' resp.json` 回显元数据）。
+没核实禁止说「已提交 / 已在生成 / 已计费」。台账 `pf-ledger.md` 每次调用**立即补一行**，禁止空表。
+
+```bash
+nohup curl -s --max-time 300 -X POST https://promptfigure.top/api/v1/generate \
+  -H "Authorization: Bearer $PROMPTFIGURE_KEY" -H "Content-Type: application/json" \
+  -d @req.json -o resp.json > curl.log 2>&1 &
+# 之后的工具调用里轮询（每次调用查一次，别在一个命令里 sleep 死等）：
+jq -e '.b64_json' resp.json > /dev/null && echo DONE || echo WAITING
+```
+
+```bash
+gen() {
+  curl -s --max-time 300 -X POST https://promptfigure.top/api/v1/generate \
+    -H "Authorization: Bearer $PROMPTFIGURE_KEY" \
+    -H "Content-Type: application/json" \
+    -d "$1" -o resp.json
+  jq -r .b64_json resp.json | base64 -d > "${2:-figure.png}"
+  jq '{size,model,crafted,charged,balance,refIgnored}' resp.json
+}
+gen '{"prompt":"对比 ResTiNet 和 CNN 在 OCT 分类上的表现，左侧数据流右侧柱状图","model":"premium","ratio":"16:9"}' fig1.png
+# 紧急绕过（平时不需要）：末尾加 "polish":false，且 prompt 需自己写成完整英文专业提示词
+# gen '{"prompt":"<完整英文提示词>","model":"premium","polish":false,"ratio":"16:9"}' fig1.png
+```
+
+#### Node（fetch 默认 UA 不过 WAF）
+
+```js
+const B = "https://promptfigure.top";
+const b64 = await fetch(B + "/api/v1/generate", {
+  method: "POST",
+  headers: { Authorization: `Bearer ${process.env.PROMPTFIGURE_KEY}`,
+             "Content-Type": "application/json" },
+  body: JSON.stringify({ prompt, model: "premium", ratio: "16:9" }),  // 正常：不传 polish
+  // 紧急绕过（平时不需要）：加 polish: false，且 prompt 需写成完整英文专业提示词
+}).then(r => r.json());
+require("fs").writeFileSync("figure.png", Buffer.from(b64.b64_json, "base64"));
+```
+
+#### Python `requests`（UA 安全，需 `pip install requests`）
+
+```python
+import os, base64, requests
+r = requests.post(
+    "https://promptfigure.top/api/v1/generate",
+    headers={"Authorization": f"Bearer {os.environ['PROMPTFIGURE_KEY']}"},
+    json={"prompt": "对比 ResTiNet 和 CNN 在 OCT 分类上的表现，左侧数据流右侧柱状图",
+          "model": "premium", "ratio": "16:9"},   # 正常：不传 polish
+          # 紧急绕过（平时不需要）：加 "polish": False，prompt 需写成完整英文专业提示词
+    timeout=300,
+)
+if not r.ok:
+    raise SystemExit(f"{r.status_code} {r.json()}")
+d = r.json()
+open("figure.png", "wb").write(base64.b64decode(d["b64_json"]))
+print(d["charged"], d["balance"], d.get("refIgnored"))
+```
+
+#### Python `urllib.request`（⚠️ 必须改 UA，否则 403）
+
+```python
+import json, base64, urllib.request
+req = urllib.request.Request(
+    "https://promptfigure.top/api/v1/generate",
+    data=json.dumps({"prompt":"...","model":"premium","ratio":"16:9"}).encode(),
+    # 紧急绕过（平时不需要）：dict 里加 "polish": False
+    headers={
+        "Authorization": f"Bearer {os.environ['PROMPTFIGURE_KEY']}",
+        "Content-Type": "application/json",
+        "User-Agent": "Mozilla/5.0",  # 绕开 CF WAF 拦截
+    },
+    method="POST",
+)
+d = json.loads(urllib.request.urlopen(req, timeout=300).read())
+open("figure.png", "wb").write(base64.b64decode(d["b64_json"]))
+```
+
+### 客户端 `timeout`
+
+默认管线实测 42–90s；premium 2K 偶尔更久。**所有客户端 timeout 建议 ≥ 300s**。
+
+---
+
+## 路径 B：网页工作流等价的异步流程
+
+完整 4 步（路径 B 走默认润色，无 polish 开关）：
+
+```js
+const B = "https://promptfigure.top";
+const post = (p, b, t) => fetch(B+p, {
+  method:"POST",
+  headers:{"Content-Type":"application/json", Authorization:`Bearer ${t}`},
+  body:JSON.stringify(b),
+}).then(r=>r.json());
+
+// 1. 登录
+const { token: tok } = await post("/api/login", {email, password});
+
+// 2. 铸造 gen token（此处扣费）
+//    body: { token: tok, prompt, size: "1K"|"2K", pool: "premium"|null, ratio }
+const { token: gt } = await post("/api/generate-token", {
+  token: tok,
+  prompt: "...",
+  size: "1K",
+  pool: null,        // null=标准池；premium 显式传 "premium"
+  ratio: "16:9",
+});
+
+// 3. 入队
+const { jobId } = await post("/api/gen-async", { token: gt });
+
+// 4. 轮询 /api/gen-result，status 序列：queued → polishing → imaging → qa → done（终态还有 error）
+for (;;) {
+  const r = await post("/api/gen-result", { token: tok, id: jobId });
+  if (r.status === "done") return r.imageUrl;        // 直接可用的图 URL
+  if (r.status === "error" || r.error) throw new Error(JSON.stringify(r));
+  await new Promise(s => setTimeout(s, 5000));
+}
+```
+
+⚠️ 路径 B **没有等价 `polish:false` 开关**——上游限频期偏慢或失败时，急用请走路径 A。
+
+---
+
+## 一键临摹 `mode: "replica"`（2026-09-18）
+
+**什么时候用**：用户给了一张现成的科研图（示意图 / 流程图 / 机制图 / 图形摘要 / 体系结构图），要求"照这个画一版 / 重画一张 / 保持结构一致"，或者想把别人论文里那张图重做成自己的一套图。**这是这种需求的首选参数**，比自己揣摩着写 prompt 准得多。
+
+**和普通参考图的区别**（关键，决定该不该用它）：
+
+| | 普通参考图（refUrl/refDataUrl） | 一键临摹（+ mode:"replica"） |
+|---|---|---|
+| 参考图给谁 | 只给生图模型，提示词层不知道它存在 | 先送**视觉模型**读成结构化清单，再由清单驱动提示词与审查 |
+| 保真依据 | 靠模型看图即兴 | 清单逐条比对（漏项/多项/编造都能判） |
+| 适合 | 只借风格、构图、配色 | 要**结构一致**的复刻 |
+
+**请求**（必须带参考图，`prompt` 可留空）：
+
+```bash
+gen '{"mode":"replica","refUrl":"https://.../figure3.png","model":"premium","ratio":"16:9"}' replica.png
+# prompt 也可以写要点，例如 {"mode":"replica","prompt":"改成中文标注","refUrl":"..."}
+```
+
+**响应里的 `referenceSpec` 就是那份清单**，可拿来核对本次出图：
+
+```jsonc
+{
+  "canvas": "16:9 landscape",          // ⚠️ 视觉模型对该字段不稳定，仅供方向参考（真实比例由 ratio 决定）
+  "layout": "three phases stacked vertically, Phase II splits into 3 parallel columns",
+  "sections": [{ "id": "a", "role": "..." }],
+  "palette":  [{ "role": "process steps", "color": "light green" }],
+  "text":     [{ "s": "MAPE 8.3%", "kind": "label", "lang": "en", "readable": true }],
+  "elements": [{ "name": "Data preprocessing box", "kind": "box", "note": "green rounded" }],
+  "relations":["Data -> Raw data box", "Decision diamond -> ... (no/tighten constraints)"],
+  "photos":   ["western blot panel"],
+  "ambiguities": ["exact arrow connectivity not individually drawn"]
+}
+```
+
+- `text` 是**原样抄录**（不翻译、不纠错），出图的图上文字按它逐字渲染——所以它也是"中文/英文标注是否正确"的验收依据。`readable:false` 的条目会用中性占位，不会瞎猜。
+- `photos` 里的区域会以**示意方式**重绘，不会伪造显微照片/电泳条带细节（科研场景伪造图像属于学术不端）。
+
+**约束与错误码**：
+
+| 情况 | 结果 |
+|---|---|
+| 没带参考图 | `400 replica_requires_reference`（不扣费） |
+| 参考图 base64 后 >8MB | `413 replica_reference_too_large`（临摹要把图送视觉模型，上限比普通参考图紧；压缩/裁剪后重试） |
+| 视觉轮失败 | 不报错：退化为"带图直接写提示词"，`specError` 带原因，正常计费 |
+| 润色失败 | `502 orchestration_failed` + **自动退款**（与普通生成同一闭环） |
+
+**不适合临摹的**：照片/显微照片/电泳图**本身**（要的是保真像素，不是重画）；数据图表里要精确到像素的坐标轴排布。
+
+---
+
+## 批处理
+
+必须串行 + 429 退避：
+
+```python
+import time, requests
+def gen(prompt, **kw):
+    for attempt in range(4):
+        r = requests.post(URL, headers=H,
+            json={"prompt": prompt, **kw},   # 正常：不传 polish
+            timeout=300)
+        if r.status_code == 429:
+            time.sleep(2 ** attempt); continue
+        if r.status_code == 502:
+            time.sleep(1); continue   # 已退款，可安全重试
+        r.raise_for_status()
+        return r.json()
+    raise RuntimeError("retry exhausted")
+```
+
+❌ 不要并发——RPM 是账号级窗口，并发只会换来 429，总吞吐不变。
+✅ 预算有限时先跑 `standard` 看构图，定了再跑 `premium` 出终稿。
+
+---
+
+## 不适合本 API 的场景
+
+- 需要**精确数据绑定**的图表（要有真实 CSV 数值驱动）→ 用 matplotlib / ggplot 画更准确
+- 超大分辨率打印级图（最高 2K）
+- 严格可复现、像素级可控的排版