promptfigure 0.2.0 → 0.3.1

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/adapters/codex/promptfigure/skills/promptfigure-local/SKILL.md

@@ -375,6 +375,37 @@ pf craft --at "§3.2 ¶2" --figure-type pipeline \
 - **路径写法**：Git Bash 的 `/c/...`、Windows 的 `C:\...`、POSIX 的 `/home/...` 都能用；
   但 craft --out 建议用相对路径（当前目录下），最不容易踩环境差异。
 
+## 每轮交付与台账（每轮结束必交，CLI 优先）
+
+**CLI 优先**：出图、核验、审批、定稿全走 `pf` 命令（`pf next` 永远告诉你下一步）；
+GUI 只留给人两件事——亲眼看图、点审批。插件的门禁与留痕都挂在 CLI 上，
+走 CLI 的每一步在 `events.jsonl` 里可审计；无头环境（SSH/容器/CI）本来就全 CLI。
+
+每轮交付在**用户工作目录**建 `promptfigure-out/`，每轮一个新版本文件夹 `vN/`（v1 → v2…）：
+
+```
+promptfigure-out/
+├── vN/
+│   ├── round-vN.md                ← 本轮反馈（下面的必含项）
+│   └── figures/                   ← 本轮图（副本或引用，文件名带 -vN）
+├── paper-with-figures.md          ← 论文+已插图的演进版（无关段落省略，每次更新同一个）
+└── final/paper-final.md + 格式副本  ← 最终论文版本（定稿时才建）
+```
+
+**round-vN.md 必含**（与 promptfigure-api skill 的 deliverables-ledger.md 同一协议）：
+1. **本轮清单**：每张图——figureId / 图种 / 档位 / 版本 / 本机真实路径（本插件即
+   `~/.promptfigure/projects/<docId>/figures/<figureId>/vN.png`）/ 插入位置（§¶）
+2. **插入位置（两段边界）**：上一段最后一句 + 「……」 + 下一段第一句，用户一眼定位
+3. **所用上下文**：用了哪几段明确到 §¶；上下文只放**首句 + 「……」 + 尾句**；
+   数据/表格/代码文件一律给引用链接，不内联内容
+4. **图片版本**：每张图的每个版本独立文件（vN），旧版永不覆盖
+5. **优化前→优化后**（优化任务）：原图路径 vs 新图路径 + 改了什么 + 所用上下文（首尾句）
+
+**最终成稿流程**（用户说「定稿」）：提醒核对数据是否更新 → 用户确认后才 premium 定稿 →
+定稿后必问矢量图（本地 AI 重绘、token 贵、速度慢；比赛/数模默认不做；确认做则按元素
+分层重绘成可编辑矢量，PPT/WPS 按用户偏好）——完整协议见 promptfigure-api skill 的
+`references/deliverables-ledger.md`。
+
 ## 事件回放
 
 `~/.promptfigure/projects/<docId>/events.jsonl` 只追加不改写 —— 审批历史、

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.1",
+  "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/INSTALL.md

@@ -0,0 +1,45 @@
+# 安装这个技能（AI Agent Skill）
+
+> **版本 1.6.10**（2026-09-24）。下载页：https://promptfigure.top/skill 。查最新版：`curl -s https://promptfigure.top/downloads/promptfigure-api.version.json`；本地已装版本看 `SKILL.md` frontmatter 的 `version`。版本语义：主版本=接口不兼容改动（需重读 SKILL.md），次版本=新增能力，修订号=勘误。
+
+把 `promptfigure-api/` 整个文件夹放进你的 AI 工具的技能目录即可：
+
+| 工具 | 技能目录（复制到此处） |
+|---|---|
+| Claude Code | `~/.claude/skills/promptfigure-api/` |
+| Claude Desktop（Agent Skills） | 设置 → Skills → 导入本 zip，或放 `~/.claude/skills/` |
+| WorkBuddy / OpenClaw | `~/.workbuddy/skills/promptfigure-api/` |
+| Codex / Cursor / Cline 等任意 Agent | 无技能目录的，把 `SKILL.md` 内容追加到 `AGENTS.md` / `CLAUDE.md` / 规则文件末尾 |
+
+安装后对 AI 说「帮我用 promptFigure 画一张 XXX 图」，它会自动读取 `SKILL.md` 并按流程执行：
+注册/登录 → 拿 key（或复用你已有的 `PROMPTFIGURE_KEY`）→ 调 API 出图。
+
+## 本包还附带本地插件（plugin/）
+
+一个 zip 两样东西：根目录的 `SKILL.md` 是纯 REST 技能（上面的装法即用）；
+`plugin/` 是本地插件（`pf` CLI + promptfigure-local skill + 托盘）。想要「文档只读预览 /
+锚点定位 / GUI 审批 / 本地规则层 / 矢量导出」这些本机能力时再装它：
+
+```bash
+cd plugin && npm install && npm link   # 之后 pf 命令全局可用
+```
+
+详见 [PLUGIN.md](PLUGIN.md)；纯 REST 用户完全不用碰 plugin/。
+
+## 需要准备
+
+- 一个账号：https://promptfigure.top 注册（邮箱 + 密码 ≥8 位，无需邮箱验证）
+- 余额：控制台充值（$1 起整数，每满 $50 赠 $1）；API 按次计费 standard $0.02 / premium $0.15
+- API key：控制台「API 密钥」创建，`pf_` 开头明文只显示一次
+
+## 保持最新
+
+技能会过期。程序化查最新版本（不用下载整个包）：
+
+```bash
+curl -s https://promptfigure.top/downloads/promptfigure-api.version.json
+```
+
+本地 `version` 低于线上 `version` → 到下载页取最新包：https://promptfigure.top/skill
+（直链：https://promptfigure.top/downloads/promptfigure-api.zip ，或 GitHub Release 资产 promptfigure-api-1.6.10.zip）
+安装说明与 API 文档：https://promptfigure.top/docs/zh-CN/api