promptfigure 0.2.0 → 0.3.0

package/adapters/claude-code/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/claude-code/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`）便于追溯

package/adapters/claude-code/promptfigure-api/references/troubleshooting.md

@@ -0,0 +1,204 @@
+# 常见问题与排障
+
+## 错误码速查
+
+| 码 | error 值 | 原因 | 处置 |
+|---|---|---|---|
+| 400 | `prompt_required` / `prompt_too_long` | prompt 空或 >8000 字符 | 检查请求体 |
+| 401 | `invalid_api_key` | key 无效/已吊销/漏了 `Bearer ` 前缀 | 检查 header；无效则重建 key |
+| 402 | `insufficient_balance` | 余额不足 | 控制台充值（$1 起，整数） |
+| 403 | `error code: 1010` | **CF WAF 拦了客户端 UA**（仅 `Python-urllib/*` 默认 UA） | 切 Node / Go / Python `requests` / 浏览器；或给 urllib 加 `User-Agent: Mozilla/5.0` |
+| 429 | `rate_limited` | 超 RPM | 已退款，串行 + 退避重试（1s → 2s → 4s） |
+| 502 | `generation_failed` | 生图通道异常 | **已自动退款**，看 `detail` 后重试；最常见是 `orchestration_failed: empty or truncated polish output` |
+| 405 | `method_not_allowed` | 用了 GET | 必须 POST |
+
+> 注意 RPM 限制是**账号级**，与网页端工作台共享同一个分钟窗口。网页上刚连续出过图，API 立刻报 429 属正常。
+
+---
+
+## 🔧 502 `orchestration_failed: empty or truncated polish output`
+
+**上游 Agnes 文本模型间歇性限频**。限频期间默认管线可能 502（约 35 秒后返回），`refunded` 标明退还金额，无需补款。服务端已内置回落：主模型 agnes-2.5-flash 撞 429 时会自动用 agnes-2.0-flash 整体重试一次；两层都撞上才会 502。
+
+⚠️ 重要：**这是上游运维状态，不是产品形态。** `/api/v1/generate` 的设计就是默认走完整润色管线，与网页同款。不要把 `polish:false` 当常态。
+
+### 真实根因（2026-09-09 实证，已修订）
+
+上游返回 **`429 "Too many requests. Please try again in a moment."`**——**与本方用量完全无关**（实测窗口内仅 7 次调用 / 配额 7500，依然 429；数小时后自行恢复）。重要线索：同 key 同模型从本机直连不限流、只有站点出口被限 → **疑似 Agnes 按出口 IP 频控**，换模型未必躲得开，等服务端回落+稍后重试是正解。
+
+**已修复的误导**：此前四种不同失败（配额耗尽/key 冷却/上游空响应/被上游拒绝）统一报成 `empty or truncated polish output`。**现在错误 detail 里带 `last_text_failure:` 字段**，直接给出上游真实状态码和响应片段——看到它就不用再猜。
+
+### 如何区分「平台故障」vs「我自己的问题」
+
+| 特征 | 平台限频（本次） | 自己的问题 |
+|---|---|---|
+| 错误 detail | 含 `upstream 429` | 含 `prompt`/参数类提示 |
+| 耗时 | 恒定 ~35s（重试耗尽） | 秒级返回 |
+| `polish:false` 同参数重试 | ✅ 能出图 | 也失败 |
+| 隔一段时间重试 | ✅ 自愈 | 仍失败 |
+
+### 处置
+
+**首选：等几分钟到几小时后原样重试**（限频会自行解除；2026-09-09 实测当天恢复，默认管线 42–90s 成功出图）。
+
+赶时间时的临时绕过：
+
+```json
+{ "prompt": "<完整英文提示词>", "polish": false, "model": "standard" }
+```
+
+⚠️ `polish:false` 时服务端**不润色不扩写**，prompt 原样进图模型——所以必须自己写完整英文提示词（写法见 `prompt-cookbook.md` 的「降级模式」）。
+
+### 何时回到正常
+
+无需操作——限频解除后默认管线自动恢复（响应里 `crafted: true`）。`polish:false` 仅作为绕过手段保留。
+
+---
+
+## 🔴 CF WAF 403 `error code: 1010`
+
+实测拦截列表（2026-09-09）：
+
+| 客户端 | UA | 结果 |
+|---|---|---|
+| curl | `curl/7.x` | ✅ 200 |
+| Node fetch | `node` | ✅ 200 |
+| Python `requests` | `python-requests/2.x` | ✅ 200 |
+| Go `net/http` | `Go-http-client/1.1` | ✅ 200 |
+| 浏览器 fetch | `Mozilla/5.0 ...` | ✅ 200 |
+| Python `urllib.request` | **`Python-urllib/3.x`** | ❌ 403 |
+
+**修法**：
+- Python `urllib`：手动加 `User-Agent: Mozilla/5.0`
+- 或换 `requests` / `httpx` / Node / Go
+
+---
+
+## 🔴 `balance` 字段滞后
+
+`/api/login` 和 `/api/me` 返回的 `balance` **不等于真实余额**（实测：`me` 返回 0，扣费 0.02 后真实余额 0.09，扣费仍成功）。
+
+可能解释：这两接口里 `balance` 字段没同步 D1，或来自一个非权威缓存层。
+
+**操作规则**：
+- 不要因为 `balance` 看起来够而**预先估算**余额
+- 看到 `402` 不要立即判定没钱，先看 D1 控制台 https://promptfigure.top/console#account-balance
+- 用户报告「明明有钱却被 402」时，先核对控制台余额（不是接口返回的）
+
+---
+
+## 注册 / key 相关
+
+**Q：注册要收邮箱验证码吗？**
+不用。邮箱 + 密码（≥8 位）提交即完成，session token 立即可用。
+
+**Q：key 明文丢了怎么办？**
+找不回来。库内只存 SHA-256 哈希。吊销旧的重建：
+`POST /api/keys/revoke {"id":"..."}` → `POST /api/keys {"name":"..."}`。
+
+**Q：余额和会员额度是一回事吗？**
+不是。API 只从**余额**扣，与订阅赠送的额度完全独立。有会员但余额为 0 → 调用仍会 402。反过来，只充值不订阅也能一直用 API（免费层 5 RPM）。
+
+**Q：能创建几把 key？**
+每人最多 10 把未吊销。按用途命名便于追溯。
+
+**Q：为什么会 401 但我明明没吊销？**
+先查 `Authorization` header —— 必须是 `Bearer pf_xxx`。写成 `Token pf_xxx` 或直接裸 key 都会 401。
+
+---
+
+## 参考图
+
+**Q：`refIgnored: true` 是什么意思？**
+参考图缺失/非法/拉取失败，**已被忽略，当次照常出图并计费**。按序排查：
+
+1. URL 是图片**直链**吗？（浏览器打开直接显示图片，不是含图的网页）
+2. 是 PNG 吗？（某些 .webp/.jpg 后缀但实际格式不符会失败）
+3. 超过 8MB 吗？
+4. 是私网/本地地址吗？（会被拒绝）
+5. 图床是否还在？（免费图床政策常变）
+
+**Q：参考图端点是不是有问题？**
+**是**。上游 `/images/edits` 自 2026-09-07 起持续 503。`refUrl`/`refDataUrl` 当前经常 `refIgnored: true`。
+**绕开方案**：暂时改用「纯文字精确描述」——把参考图的特征（方向/panel 数/图表类型/图标风格/数据标注密度/色分布）全部写进 prompt。修复后第一时间回写到本文件。
+
+**Q：有既稳定又省事的方案吗？**
+图在公网 → 用 `refUrl`（服务器代取，你不用下载也不用转 base64）。
+图在本地且较小 → 用 `refDataUrl`。
+图在本地且较大 → 先挂免费图床：
+`curl -F "file=@ref.png" https://x0.at`
+
+---
+
+## 出图质量
+
+**Q：图里的文字糊/有乱码英文？**
+polish:false 直出时图模型对英文文字标签渲染差（实测出 "Mcıuacy" 这种乱码）。
+**修法**：prompt 里**逐字写对**所有英文标签，加一句 "All on-figure text labels in English, spelled correctly"。重要场合用 `premium`（gpt-image 文字渲染显著优于 Agnes standard）。
+
+**Q：数值和我给的不一致？**
+polish:false 时图模型会忠实画你给的数值，但也可能把"上下文中相似数字"画错。关键数值在 prompt 里重复一次并显式绑定单位。⚠️ 没有真实数据就别写——补出来的数值会被当成事实印到图上。
+
+**Q：配色太单调，全是一个色系？**
+prompt 里写了单一色相约束（如 `"muted steel-blue fills"`）。改用语义化多色（详见 `prompt-cookbook.md` 的配色小节）。
+
+**Q：机制图被画成了 3D？**
+prompt 里加 `2D flat`, `white background`, `no gradients, no photorealism`。
+
+**Q：构图和我给的参考图差很远？**
+「参考风格」不拆特征是必返工的。拆到特征级——方向、panel 数、图表类型、图标风格、标注密度、色分布——逐条写进 prompt 正文。参考图只是补充（且当前参考图端点 503）。
+
+**Q：prompt 很长但出图反而更差？**
+超 400 词后信息超载。压到 150–300 词，只保留核心实体与结构。
+
+**Q：为什么图快/出图秒成但像样？**
+polish:false 直出时快（~11s）但少了编排层润色，**质量低于正常管线是预期**，不是异常。正常管线应看到 `crafted: true` 的更慢但更好的结果。
+
+---
+
+## 计费
+
+**Q：既然 premium 1K 和 2K 同价，为什么还要选 1K？**
+基本不用选，默认 2K。仅当需要快速迭代或尺寸受限时用 1K。
+
+**Q：失败会扣钱吗？**
+不会。502、429 都会自动原路退款（响应里看 `refunded`）。只有成功出图才真扣费。
+
+**Q：RPM 不够用怎么办？**
+提升订阅档（Lite 10 / Plus 15 / Pro 40 / Ultra 80 RPM）。短期也可以：错峰、把批量任务摊到不同分钟。
+
+---
+
+## 时效
+
+**Q：响应要多久？**
+polish:false 实测 ~11s（standard）/ 60–120s（premium 2K 偶尔更长）。**客户端 timeout ≥ 300s**。
+⚠️ 别设 30s/60s 就以为服务挂了——通常是你自己先断开了。
+
+**Q：网页工作台和 API 一样慢/卡吗？**
+管线正常时网页与 API 同速（都在服务端润色）。网页端**没有 `polish:false` 等价开关**——上游限频期网页会卡在 polishing，急用请走 API 路径 A。
+
+---
+
+## 仍然解决不了
+
+- 线上文档（权威，比本文件更新）：https://promptfigure.top/docs/zh-CN/faq
+- 在线调试台（隔离是代码问题还是账号问题）：https://promptfigure.top/docs/zh-CN/api-playground
+- 服务状态/更新：https://promptfigure.top/news
+
+---
+
+## premium 被内容审核误伤（502 `content moderation`，2026-09-10 CVPR 实测）
+
+现象：502 + `detail.error = premium channel rejected` + 上游报 "rejected by content moderation"，**自动退款**。
+
+关键实测结论（二分验证）：
+
+- 触发是**整段组合判断，不是单词命中**——把整段 prompt 里的词逐个/分组喂给极简探针全部通过，合在一起就被拒。密集的「检测/候选框/过滤/一致性」类 CV 术语组合（如 …Candidate Boxes + Consensus + Filtering + 本地化器… 同屏多个）容易触发
+- 单个可疑缩写也可能命中（实测 `WBF` 被拒，全称 Weighted Box Fusion 反而通过）——先用极简探针 + 可疑词单独测，拒=免费，通过=正常扣费，别拿整段 prompt 反复烧钱试
+
+处置顺序：
+
+1. 拒了就换措辞重试**最多 2 次**（每次拒绝免费）；去掉标题/缩写、把检测类词汇换成中性词（Estimator/Candidate）常能过
+2. 还不过 → **不要继续试探**：改走 standard 出图（Agnes 通道审核宽松，同样内容能过），拼写/小字问题用 PIL 本地修补（采样盒底色覆盖 + Arial 按原字号重写标签），成本为零且拼写百分百正确
+3. 台账里记 `moderation_blocked: true` 与被拒 prompt，便于服务端侧后续排查

package/adapters/codex/promptfigure/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "promptfigure",
-  "version": "0.1.0",
-  "description": "promptFigure 本地插件：为论文配科研图（锚点定位 + 出图 + 审批闭环）",
+  "version": "0.2.0",
+  "description": "promptFigure 本地插件：为论文配科研图（锚点定位 + 出图 + 审批闭环），随包附带 promptfigure-api / promptfigure-local 两个 skill",
   "skills": "./skills/"
 }