promptfigure 0.2.0 → 0.3.0

package/adapters/codex/promptfigure/skills/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/bin/pf.mjs

@@ -6,6 +6,7 @@ import fs from "node:fs";
 import path from "node:path";
 import http from "node:http";
 import net from "node:net";
+import os from "node:os";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -121,6 +122,13 @@ promptFigure 本地插件 v${VERSION} —— 在你的 AI 宿主里为论文配
                                      + 计费兜底 + 排练留痕，每条带理由——可疑版本可直接打回
   pf setup-tex               下载便携 tectonic（没有 TeX 环境时用，~20MB 免安装）
   pf doc compile [--doc <id>]  重新编译 LaTeX → PDF（改了源文件后用）
+
+skill（npm 装的插件自带，一条命令装进宿主）：
+  pf skill install            把随包的两个 skill 装进宿主技能目录（默认 ~/.claude/skills/）
+                               · promptfigure-local —— 插件工作流（文档预览/锚点/审批 GUI）
+                               · promptfigure-api —— 纯 REST 出图（任何能跑 curl 的宿主）
+                               [--dir <路径>] 可指定其他技能目录；两者按宿主环境二选一或都装
+  pf skill path               只看两个 skill 在插件包里的路径（手动拷贝/排查用）
 `;
 
 function die(msg, hintCmd) {
@@ -1890,6 +1898,35 @@ async function main() {
       return;
     }
 
+    case "skill": {
+      // 随包发行的两个 skill 一键装进宿主（npm i -g promptfigure 后的落地步骤）
+      const PKG_ROOT = path.resolve(__dirname, "..");
+      const SKILLS = ["promptfigure-local", "promptfigure-api"];
+      const sub = rest[0] || "install";
+      if (sub === "path" || sub === "list") {
+        for (const s of SKILLS) console.log(path.join(PKG_ROOT, "skill", s));
+        return;
+      }
+      if (sub !== "install") {
+        die(`用法：pf skill install [--dir <技能目录>]｜pf skill path 只看路径`, "pf skill install");
+      }
+      const destRoot = arg("--dir") || path.join(os.homedir(), ".claude", "skills");
+      for (const s of SKILLS) {
+        if (!fs.existsSync(path.join(PKG_ROOT, "skill", s, "SKILL.md"))) {
+          die(`找不到 skill 源：${path.join(PKG_ROOT, "skill", s)} —— 插件包不完整？`, "重装：npm i -g promptfigure");
+        }
+      }
+      fs.mkdirSync(destRoot, { recursive: true });
+      for (const s of SKILLS) {
+        const dest = path.join(destRoot, s);
+        fs.cpSync(path.join(PKG_ROOT, "skill", s), dest, { recursive: true });
+        console.log(`✅ ${s} → ${dest}`);
+      }
+      console.log(`⏭ 其他宿主：Codex 把 ${path.join(PKG_ROOT, "adapters", "codex", "promptfigure")} 拷进 plugins 目录；`);
+      console.log(`   无技能目录的宿主（任意 Agent），把某个 skill 的 SKILL.md 内容追加进 AGENTS.md / CLAUDE.md 末尾。`);
+      return;
+    }
+
     case "serve": {
       const { startServer } = await import("../src/server.mjs");
       const port = Number(arg("--port")) || loadConfig().port || (await import("../src/config.mjs")).DEFAULT_PORT;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "promptfigure",
-  "version": "0.2.0",
-  "description": "promptFigure 本地插件：在你的 AI 宿主（Codex / Claude Code 等）里为论文配科研图。开文档（LaTeX 本地编译）、画锚点、本地规则层组装提示词、调出图、收审批。",
+  "version": "0.3.0",
+  "description": "promptFigure 本地插件：在你的 AI 宿主（Codex / Claude Code 等）里为论文配科研图。开文档（LaTeX 本地编译）、画锚点、本地规则层组装提示词、调出图、收审批。npm 安装即附带 promptfigure-local / promptfigure-api 两个 Agent Skill。",
   "type": "module",
   "bin": {
     "pf": "bin/pf.mjs"

package/scripts/build-adapters.mjs

@@ -1,31 +1,41 @@
-// build-adapters.mjs — 一份 skill 源 → 各 AI 宿主包装产物
+// build-adapters.mjs — skill 源 → 各 AI 宿主包装产物
 // 🔴 adapters/ 下全部由本脚本生成，勿手改
-// 🔴 skill 内容只有一份源 skill/promptfigure-local/SKILL.md
+// 🔴 skill 源在 skill/ 下，一份内容两个 skill：
+//    promptfigure-local（依赖 pf CLI 的本地工作流）/ promptfigure-api（纯 REST）
+//    两者随插件一起发行（zip 与 npm 包同此结构）：装插件 = 同时拿到两个 skill。
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, "..");
-const SKILL_SRC = path.join(ROOT, "skill", "promptfigure-local", "SKILL.md");
+const SKILLS = path.join(ROOT, "skill");
 const ADAPTERS = path.join(ROOT, "adapters");
+const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
+const VERSION = PKG.version;
 
-const skill = fs.readFileSync(SKILL_SRC, "utf8");
-fs.rmSync(ADAPTERS, { recursive: true, force: true });
+// 复制整个 skill 目录（SKILL.md + references/），目标不存在时建
+function copySkillDir(name, destDir) {
+  fs.cpSync(path.join(SKILLS, name), destDir, { recursive: true });
+}
+
+const fs_rmSync = fs.rmSync;
+fs_rmSync(ADAPTERS, { recursive: true, force: true });
 
 // ---- Codex：plugin 目录（.codex-plugin/plugin.json + skills/ + marketplace.json）----
 const codex = path.join(ADAPTERS, "codex", "promptfigure");
 fs.mkdirSync(path.join(codex, ".codex-plugin"), { recursive: true });
-fs.mkdirSync(path.join(codex, "skills", "promptfigure-local"), { recursive: true });
-fs.copyFileSync(SKILL_SRC, path.join(codex, "skills", "promptfigure-local", "SKILL.md"));
+for (const name of ["promptfigure-local", "promptfigure-api"]) {
+  copySkillDir(name, path.join(codex, "skills", name));
+}
 
 fs.writeFileSync(
   path.join(codex, ".codex-plugin", "plugin.json"),
   JSON.stringify(
     {
       name: "promptfigure",
-      version: "0.1.0",
-      description: "promptFigure 本地插件：为论文配科研图（锚点定位 + 出图 + 审批闭环）",
+      version: VERSION,
+      description: "promptFigure 本地插件：为论文配科研图（锚点定位 + 出图 + 审批闭环），随包附带 promptfigure-api / promptfigure-local 两个 skill",
       skills: "./skills/",
     },
     null,
@@ -51,25 +61,28 @@ fs.writeFileSync(
   ),
 );
 
-// ---- Claude Code：skill 目录拷贝脚本 ----
+// ---- Claude Code：skill 目录拷贝脚本（两个 skill 都装）----
 const claude = path.join(ADAPTERS, "claude-code");
 fs.mkdirSync(claude, { recursive: true });
-fs.copyFileSync(SKILL_SRC, path.join(claude, "SKILL.md"));
+for (const name of ["promptfigure-local", "promptfigure-api"]) {
+  copySkillDir(name, path.join(claude, name));
+}
 fs.writeFileSync(
   path.join(claude, "install.mjs"),
-  `// 安装到 ~/.claude/skills/promptfigure-local/
+  `// 安装到 ~/.claude/skills/（promptfigure-local + promptfigure-api 两个都装）
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-const src = new URL("./SKILL.md", import.meta.url).pathname.replace(/^\\/([A-Za-z]:)/, "$1");
-const dest = path.join(os.homedir(), ".claude", "skills", "promptfigure-local");
-fs.mkdirSync(dest, { recursive: true });
-fs.copyFileSync(src, path.join(dest, "SKILL.md"));
-console.log("✅ 已安装到 " + dest);
+const here = (p) => new URL(p, import.meta.url).pathname.replace(/^\\/([A-Za-z]:)/, "$1");
+for (const name of ["promptfigure-local", "promptfigure-api"]) {
+  const dest = path.join(os.homedir(), ".claude", "skills", name);
+  fs.cpSync(here("./" + name), dest, { recursive: true });
+  console.log("✅ 已安装到 " + dest);
+}
 `,
 );
 
-console.log("✅ adapters/ 已生成：");
+console.log("✅ adapters/ 已生成（v" + VERSION + "，两个 skill）：");
 for (const p of walk(ADAPTERS)) console.log("   " + path.relative(ROOT, p));
 
 function walk(dir) {

package/skill/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/ 风格库与合规红线 |