promptfigure 0.2.0 → 0.3.1

package/skill/promptfigure-api/references/deliverables-ledger.md

@@ -0,0 +1,119 @@
+# 每轮交付与台账（round deliverables & ledger）
+
+> 场景：每次用 promptFigure 出图 / 优化图片 / 整文批处理结束后，宿主 AI 必须按本文件产出结构化交付。
+> 目的：用户随时能回答三个问题——**这轮做了什么图、图插在原文哪里、用了什么上下文/数据**。
+> 🔴 本文件是硬性协议：缺任何一项 = 交付不完整。CLI 优先——全程用 `pf` 命令沉淀状态，GUI 只留给人「看一眼 / 点审批」。
+
+---
+
+## 0.  CLI 优先原则（2026-09-25 定规）
+
+- 出图、核验、审批、定稿全链路都有 CLI：`pf open → craft → render → qa → review resolve → premium`，**能用 CLI 就用 CLI**
+- GUI 只用于两件事：人亲眼看图、人点审批。插件的门禁与留痕都挂在 CLI 上，走 CLI 的每一步都可审计
+- 每轮结束的交付目录里，路径一律引用**用户本机真实路径**（相对当前交付目录优先，跨目录用绝对路径），禁止只给「见图库」这类指不到文件的话
+
+---
+
+## 1. 交付目录结构（每一轮 = 一个新文件夹）
+
+在**用户当前工作目录**（论文旁边）建 `promptfigure-out/`，每轮交付新建递增版本文件夹：
+
+```
+promptfigure-out/
+├── v1/                          ← 第 1 轮交付（每次交付新建一个，v1 → v2 → v3…）
+│   ├── round-v1.md              ← 本轮反馈（见 §2 必含项）
+│   └── figures/                 ← 本轮产出的图（文件名带版本号）
+│       ├── fig-method-v1.png
+│       └── fig-method-v2.png    ← 改版后重新出，旧版保留可回溯
+├── v2/round-v2.md               ← 第 2 轮……
+├── paper-with-figures.md        ← 不断演进的「论文 + 已插图」版（见 §3）
+└── final/                       ← 最终论文版本（见 §4，仅最终成稿时建）
+    ├── paper-final.md
+    └── paper-final.docx         ← 格式副本，按用户原文档格式（见 §4）
+```
+
+- 版本号判断：`ls promptfigure-out/` 取最大 N + 1；用户已有自己的目录约定时听用户的
+- `figures/` 里的图**永不覆盖**：同一张图的每个版本都是独立文件（`-v1/-v2/…`），旧版要能随时打开对比
+
+---
+
+## 2. round-vN.md 必含项（本轮反馈）
+
+模板（每轮照此填，没有的项目写「无」并说明原因，禁止静默省略）：
+
+```markdown
+# 第 N 轮交付 · YYYY-MM-DD HH:mm
+
+## 本轮清单
+| # | 图 | 图种 | 档位 | 版本 | 本机路径 | 插入位置（§¶） | 状态 |
+|---|---|---|---|---|---|---|---|
+| 1 | 方法流程图 | pipeline | premium | v2 | figures/fig-method-v2.png | §2 ¶1 ↔ §2 ¶2 之间 | 已审批 |
+
+## 插入位置（图放在原文哪两段之间）
+逐张图给出——**上一段最后一句 + 「……」 + 下一段第一句**，让用户一眼定位：
+
+> ……la optimización por enjambre de partículas ajusta automáticamente los principales parámetros.……La estrategia de aumento de datos incluye recorte aleatorio, jitter de color y deformación elástica.
+> （图 1 插在上述两句之间，即 §2 ¶1 末 ↔ §2 ¶2 首）
+
+- 自然段为粒度（¶），不用句号硬切；原文没有下一段时注明「§2 段末，文末」
+
+## 所用上下文（只放首尾句，中间省略）
+- 原文上下文：「首句……尾句」（禁止整段贴入；用了哪几段就列哪几条，§¶ 标清楚）
+- 引用范围声明：本次生成具体使用了 §2 ¶1–¶2（明确到段，供用户核对）
+
+## 数据与引用
+- 本地表格/数据文件：[table1.csv](../data/table1.csv)、[run_exp2.m](../code/run_exp2.m) —— **只给引用链接，不内联内容**
+- 参考图：refDataUrl（本地图 /path/to/ref.png）或 refUrl（https://…）；用了就标，没用写「无」
+
+## 优化前 → 优化后（仅「优化已有图」任务）
+| 图 | 优化前 | 优化后 | 改了什么 | 所用上下文（首尾句） |
+|---|---|---|---|---|
+| 原图1（曲线组） | figures/orig/fig1-old.png | figures/fig1-v1.png | 色板改语义化、字号 8pt、去 3D | 「首句……尾句」 |
+```
+
+**三条填写铁律**：
+1. **上下文只放首句 + 尾句，中间一律省略号**——整段进 MD 会让用户无法快速审阅，也让版本 diff 爆炸
+2. **表格 / 代码 / 数据文件一律引用链接，禁止内联内容**——内联会让 MD 迅速腐烂、版本更新时无法对账；要「看见这轮用了什么」，点链接就是
+3. **每张图必须看得到版本**（文件名 `-vN` + 清单里的版本列 + 状态列）——版本是回溯和 diff 的唯一坐标
+
+---
+
+## 3. paper-with-figures.md（不断演进的呈现版）
+
+- 结构 = 用户原文的章节树；**本轮涉及的段落**照录，**不涉及的段落**一律省略为一行：`……（§3 全文见原文）`
+- 每张图插在自己的插入位置（§2 ¶1 ↔ ¶2 之间），图片用相对路径引用 vN 文件夹里的真实文件
+- 每次交付**更新同一个文件**（或在文件名带版本 `paper-with-figures.vN.md` 保留历史）——用户随时打开这一个文件就能看到「论文现在长什么样」
+
+---
+
+## 4. final/ 最终论文版本
+
+用户要求「最终成稿 / 定稿」时才建，包含：
+
+1. `final/paper-final.md`——最终呈现版（全部已审批图就位、引用与上下文清单汇总）
+2. `final/paper-final.<用户格式>`——**格式副本，按用户原文档格式来**：
+   - Word/.docx → 交付 .docx（有 pandoc/docx 工具就用；无工具要明说「做不了格式副本，交付 MD」）
+   - LaTeX/.tex → 交付 .tex（图用 `\includegraphics` 引用真实路径，结构可编译）
+   - WPS → 交付 .docx（WPS 可直接打开）
+   - 🔴 **副本必须能正常打开**：交付前自己验证（文件非零、结构完整、能找到图）；验证不了就明说，禁止交一个打不开的坏副本
+
+---
+
+## 5. 最终成稿流程（用户说「定稿 / 最终版」时按此走）
+
+1. **先提醒核对**：提醒用户「数据有没有更新？要不要重新跑一次核验？」——用户明确确认后，才进入 premium 最终定稿
+2. **确认高级定稿**：向用户复述「将消耗 premium 档额度出高清定稿，N 张」并取得确认；未确认不动手
+3. **定稿后问矢量图**（衔接 SKILL.md 阶段 5）：
+   - 提醒成本：矢量图由**用户自己的 AI 本地重绘**，token 消耗大、速度慢
+   - 🔴 **比赛 / 数学建模 / 学术会议竞赛：默认不做**，速度优先；只有时间充裕才做
+4. **用户确认做矢量图时**：把最终图**按元素分层重绘**为可编辑矢量（PPT 形状 / 分层 SVG 分组，每个模块、箭头、标签是独立对象），在用户偏好的应用里操作——**PPT 还是 WPS 还是其他，按用户主要偏好来**；描摹矢量（位图转路径）一律禁止
+
+---
+
+## 6. 自检清单（每轮交付前过一遍）
+
+- [ ] 版本文件夹新建（vN 递增）、图带版本号、旧版未覆盖
+- [ ] round-vN.md 五项齐：清单 / 插入位置（两段边界句）/ 上下文（首尾句）/ 数据引用（链接）/ 优化前后（如适用）
+- [ ] paper-with-figures.md 已更新到含本轮所有图
+- [ ] 路径全部指得到真实文件（md 里的链接点得开）
+- [ ] final/ 仅在最终成稿时出现，格式副本已验证可打开

package/skill/promptfigure-api/references/document-workflow.md

@@ -0,0 +1,231 @@
+# 文档插图工作流：在论文/报告里找到出图位置并生成配图
+
+> 场景：用户给你一篇 `.tex` / `.docx` / `.md` 文稿，要求「把该配图的地方配上图」。本文件教你 **① 定位哪里该出图 ② 从上下文写出正确 prompt ③ 把图插回文档**。
+>
+> 批量升级已有图（结果图溯源重绘/示意图 AI 升级/整文批处理/追溯台账）见 `figure-upgrade-workflow.md`；PDF/WPS 解析与主动插图建议见 `proactive-upgrade.md`。
+
+---
+
+## 0. 调研背景（2026-09-09，为什么不造轮子）
+
+调研了 GitHub 上的现成方案，**没有一个开源项目完整做到「读文档 → 定插图位 → 调外部生图 API → 插回文档」**。最接近的：
+
+| 项目                                                                                 | 做了什么                                                                                             | 对本技能的启示                                                                  |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| [paperfigg](https://github.com/oluwafemidiakhoa/paperfigg)（PyPI `paperfigg`，v0.4+） | 论文(PDF/MD) → agentic 规划→生成→审查 → 出图 + **LaTeX include snippet + caption + 图元素到原文 span 的溯源映射**     | 借鉴它的 **figure plan**（先列图清单再逐张生成）和 **caption 从原文生成** 思路；但它用自家生成器，不接外部 API |
+| [scitex-writer](https://github.com/SciTeX-AI/scitex-writer)                        | LaTeX 稿件管理 MCP server（`figures add fig01 plot.png "Caption"` 等 44 工具），管插图/编译不管生成                 | 插回 LaTeX 的命令式做法可参考；需要完整稿件工程，太重                                           |
+| [DeTikZify](https://github.com/potamides/DeTikZify)（NeurIPS 2024 spotlight）        | 多模态模型把草图/已有图/文本 caption 合成 TikZ 矢量图                                                              | 「caption→图」方向的学术标杆；要本地 GPU + TeX Live，不适合直接集成                            |
+| [paper-figure（kitcaf）](https://github.com/kitcaf/skills)、AutoResearchClaw、ARIS 等   | 数据图（matplotlib 级）+ `PAPER_PLAN.md` 图规划；**明确承认架构图/机制图自动生成质量不行**                                   | 数据图走本地脚本更省；**概念图/机制图/管线图正是 promptFigure 的强项**——两者互补不冲突                   |
+| docx 侧                                                                             | 只有 python-docx 机械插图的 skill（如 `vamseeachanta/workspace-hub` 的 image-insertion），**「哪里该插图」的决策完全空白** | 定位逻辑由本文件 §1 提供                                                           |
+
+结论：位置决策 + prompt 构造按本文件执行；不做通用工具，让 AI 现场判断。
+
+---
+
+## 1. 定位：哪里该出图
+
+### LaTeX（.tex）
+
+按优先级扫描这些信号（`grep -n` 即可）：
+
+> **用户给的不是 LaTeX 而是 PDF/WPS/Word 稿**：已有插图优化、插图位主动建议、从原始数据推演配图，
+> 走 `proactive-upgrade.md` 的四步管线（PDF 解析 → MCM 插图位惯例 → 提示词 → 迭代优化）；
+> 本节信号表面向 LaTeX 源。
+
+| 信号                                                                              | 含义          | 动作                      |
+| ------------------------------------------------------------------------------- | ----------- | ----------------------- |
+| `\begin{figure}...\end{figure}` 空壳或缺 `includegraphics`                          | 作者留了图位      | **必插**                  |
+| `% TODO: figure` / `%% FIGURE HERE` 类注释                                         | 明确占位        | **必插**                  |
+| 正文有 `如图~\ref{fig:xxx}` / `as shown in Figure~\ref{...}` 但 `\label{fig:xxx}` 不存在 | 引用了不存在的图    | **必插**（label 用引用处的 key） |
+| 无任何图引用                                                                          | 需要判断要不要建议插图 | 见下方「章节启发式」              |
+
+**章节启发式**（无显式占位时，按科研论文惯例推荐插图位）：
+
+- **引言/摘要末** → 图形摘要（graphical abstract）或 teaser 总览图，1 张，覆盖全文核心流程
+- **方法/模型章节** → 架构图、管线图、机制示意图（每小节最多 1 张，总 ≤3）
+- **实验设置** → 数据集/实验流程示意（可选）
+- **结果分析** → **数据图优先用本地 matplotlib/Excel 出**（paper-figure 类工具已覆盖），只有「对比关系示意」这类概念图才值得用本 API
+
+### 1.5 判定标准：这段文字配不配得上一张图
+
+占位符信号（必插）之外，无占位段落**只有 4 类正当理由**该配图——图的唯一使命是承载文字承载不了的信息：
+
+| 类型       | 文字判据                                  | 典型图              |
+| -------- | ------------------------------------- | ---------------- |
+| **结构拓扑** | 段内 ≥3 个实体 + 方向/连接词（送入、融合、拼接、输出、反馈、级联） | 管线/架构/流程图        |
+| **空间形态** | 在描述「长什么样、在哪、怎么连」而非「为什么」               | 通路位置、几何/布局示意     |
+| **概念对比** | 多组对象的**定性**差异（不含精确数值）                 | 方法 A vs B 流程差异示意 |
+| **全文压缩** | 读者需 30 秒理解全文                          | 图形摘要 / teaser    |
+
+口诀：**三个实体手拉手、文字读三遍才拼出结构 → 画；数字支撑 → 本地画；都没占 → 不画。**
+
+反向排除（不该加图）：
+
+- ❌ **带精确数值的结果图**（曲线、柱状、热图）→ 一律本地 matplotlib——AI 生图必画错数字，坐标数据必须是真数据
+- ❌ 1-2 个实体、一句话说得清的关系 → 凑数
+- ❌ 定义/假设/证明类纯逻辑段 → 装饰
+- ❌ 该信息已有别的图覆盖 → 重复
+
+### Word（.docx）
+
+```python
+from docx import Document
+doc = Document("paper.docx")
+for i, p in enumerate(doc.paragraphs):
+    t = p.text
+    if any(k in t for k in ("如图", "见图", "如上图", "如下图", "Figure", "Fig.", "图X", "【图")):
+        print(i, p.style.name, t[:80])
+```
+
+- 命中「如图 X 所示 / Figure X」且附近无图片段落 → 该处插入
+- 中文论文常写「（此处插入图 X）」或用「图 X」独立行占位 → 直接替换
+- 结构启发式同 LaTeX：「方法」章 → 机制图；「摘要」后 → 图形摘要
+
+### Markdown
+
+`![placeholder]`、\`\`、`**[图 X]**` 等占位，逻辑同上。
+
+---
+
+## 2. prompt 怎么写：从上下文提取，不凭空编
+
+**铁律不变（见 SKILL.md）**：说清「图种 + 实体 + 结构」即可，扩写交给服务端润色。关键是从文档里**提取真实实体**，而不是写通用模板句。
+
+### 2.0 上下文蒸馏三步法（🔴 原文段落绝不直接进 prompt）
+
+**为什么**：把插图位周围的成段原文塞给生图 API 是低效甚至有害的——润色层会被叙述性文本淹没（论点、引用、过渡句全变成噪声），重点稀释后实体和结构反而抓不准，长文本还挤占 prompt 预算。上下文的价值在于**给 Agent 提炼，不是给 API 阅读**。
+
+三步走：
+
+1. **提取**（本地）：把插图位前后 2-3 段原文 + 章节标题 + 现有 caption 抄到你的工作区
+2. **蒸馏**（本地）：从原文提炼成三份结构化清单——**实体清单**（模块/方法名，原词）、**结构清单**（数据流方向/并行/汇合）、**图种判定**（按 §1.5）
+3. **写 prompt**：只把三份清单按 golden skeleton（`prompt-review-workflow.md` 阶段 1）组装成 prompt——组装产物里**不应有任何一句完整的原文句子**
+
+**蒸馏 vs 粘贴（正反例）**：
+
+- ❌ 粘贴：`prompt: "论文写道：编码器提取特征后经跨尺度融合模块送入解码器，并与低层细节特征拼接，该方法在三个数据集上均取得最优精度……"`（叙述、结果句、引用全进了 prompt）
+- ✅ 蒸馏：`prompt: "模型管线图。Encoder → Cross-scale Fusion Module（含低层 skip 拼接）→ Decoder，箭头标数据流，模块名英文原样，扁平矢量白底"`（只有实体+结构+风格）
+
+### 2.1 上下文取材范围
+
+**上下文取材优先级**：插图位前后 2-3 段 > 章节标题层级 > 全文摘要 > 用户口头描述。够不到的用占位符，不反问。
+
+**只取与图有关的内容**：模块名、数据流方向词（送入/融合/拼接/级联）、对比对象、分组关系。**舍弃**：论点句、实验结论、引用文献、过渡句——这些进了 prompt 只会让图上长出垃圾文字。
+
+### 2.2 给 API 的上下文清单（最小充分集 3 项 + 建议集 4 项）
+
+API 的润色层需要的是**意图**，不是成稿 prompt。一次性提交按此清单收敛（零反问）：
+
+**必给 3 项（缺一图必歪）：**
+
+| # | 项                                            | 来源          | 没有时                        |
+| - | -------------------------------------------- | ----------- | -------------------------- |
+| 1 | **图种**：管线 / 机制 / 对比 / 框架 / 图形摘要              | §1.5 判定类型   | 从段落动词推断（「送入/融合」→管线）        |
+| 2 | **实体清单**：方法名、模块名**原样搬运**（拼写不改），实体数 ≈ panel 数 | 插图位前后 2-3 段 | 占位符（`Module A / Module B`） |
+| 3 | **关系结构**：谁指向谁、分几组、左右/上下、哪条是 skip/反馈/级联       | 段内方向词       | 默认从左到右单向流                  |
+
+**建议给 4 项（有推定默认，给了更准）：**
+
+| # | 项                                               | 推定规则（不给时）              |
+| - | ----------------------------------------------- | ---------------------- |
+| 4 | 视觉角色：哪个模块是核心贡献（强调色）                             | 章节主题词 ≈ 核心模块           |
+| 5 | caption 一句话（润色层的锚点）                             | 从插图位段落首句压缩             |
+| 6 | 版面 ratio：单栏 `3:2`/`1:1`，跨栏（`figure*`）/全宽 `16:9` | 按 LaTeX 单双栏或 Word 页宽推  |
+| 7 | 档位：投稿/对外展示 `premium`，工作稿/草稿迭代 `standard`        | 看文稿状态（预印本/投稿版→premium） |
+
+**上下文取材优先级**：插图位前后 2-3 段 > 章节标题层级 > 全文摘要 > 用户口头描述。够不到的用占位符，不反问。
+
+### 2.3 提取步骤
+
+1. **读插图位前后各 2-3 段**，提取：方法/模块名（原样保留拼写，如 ResTiNet、GPX4）、模块间数据流方向、对比对象、关键数值/指标名
+2. **定图种**（对照 `prompt-cookbook.md` 的五类模板）：流程/管线 → pipeline 模板；机制/通路 → mechanism 模板；多方法对比 → comparison 模板；技术路线 → framework 模板
+3. **prompt 里写清楚 caption 承担不了的信息**：图不重复正文文字，要补「结构」——谁指向谁、分几组、左还是右
+4. **比例按版面定**：LaTeX 单栏图 `3:2` 或 `1:1`；跨栏/双栏跨度（`figure*`）用 `16:9`；Word 全宽 `16:9`，半宽 `3:2`
+5. 图形摘要/teaser → `premium` 档（对外展示，见 SKILL.md 档位表）；方法章节工作稿 → `standard`
+6. **字体按规范写进 prompt**：无衬线正向 + 手写/花体禁令，见 `prompt-review-workflow.md` 字体规范节
+
+**一个从上下文到 prompt 的实例**（方法章写道「编码器提取特征后经跨尺度融合模块送入解码器，并与低层细节特征拼接」）：
+
+```json
+{"prompt": "论文方法章配图：模型整体管线图。三个模块从左到右：Encoder（提取特征）→ Cross-scale Fusion Module（跨尺度融合，含来自低层的 skip 连接拼接）→ Decoder（输出预测）。用箭头标注数据流，模块名按英文原样标注 Encoder / Cross-scale Fusion / Decoder。扁平矢量风，白底。", "model": "standard", "ratio": "16:9"}
+```
+
+要点：模块名**原样搬运自文档**（不翻译不改写）、数据流方向照正文、结构（skip 拼接）显式写出。
+
+---
+
+## 3. 插回文档
+
+### LaTeX
+
+```latex
+\begin{figure}[t]
+  \centering
+  \includegraphics[width=\linewidth]{figures/pipeline.png}
+  \caption{Overall architecture of the proposed method.（从对应段落一句概括，照 paperfigg 的做法 caption 承担「图在说什么」，不重复正文）}
+  \label{fig:pipeline}   % 若正文已用 \ref{fig:xxx} 引用，label 必须用同一个 key
+\end{figure}
+```
+
+- 保存图到 `figures/`（与 `\graphicspath` 一致）；PNG 直接可用
+- 位置参数：方法章机制图用 `[t]`（页顶），紧跟首次引用段落之后声明
+
+### Word（.docx，python-docx）
+
+```python
+from docx import Document
+from docx.shared import Inches, Pt
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+
+doc = Document("paper.docx")
+target = doc.paragraphs[12]            # §1 定位到的「如图 X 所示」段落
+
+# 图片段：插在 target 之前
+img_p = target.insert_paragraph_before()
+img_p.alignment = WD_ALIGN_PARAGRAPH.CENTER
+img_p.add_run().add_picture("pipeline.png", width=Inches(5.5))  # 全宽约 5.5-6.0in
+
+# 图注段：再插一次，正好落在图片之后、原文段落之前
+cap_p = target.insert_paragraph_before()
+cap_p.alignment = WD_ALIGN_PARAGRAPH.CENTER
+r = cap_p.add_run("图 1：模型整体管线示意")
+r.italic = True
+r.font.size = Pt(10)
+
+doc.save("paper.docx")
+```
+
+（图注惯例：图片下方居中，「图 1：说明」，10pt 斜体；插图后全文图号需人工复核顺延。）
+
+### Markdown
+
+```markdown
+![模型整体管线图](figures/pipeline.png)
+*图 1：Encoder → Cross-scale Fusion → Decoder 的数据流。*
+```
+
+### 3.5 LaTeX 编译环境：用户没有时怎么办
+
+先探测（`pdflatex --version` / `xelatex --version` / `latexmk` / `tectonic`）。**探测不到就问用户**「论文平时在哪里编译」（可能在本机别处、其他机器或 Overleaf），别擅自装重型工具链；用户确实想在本机新装时，按平台给官方下载指引：
+
+| 方案 | 平台 | 链接 | 适合 |
+|---|---|---|---|
+| **MiKTeX** | Windows/macOS | https://miktex.org/download | Windows 首选，按需自动装宏包 |
+| **TeX Live** | 全平台 | https://tug.org/texlive/ | 最完整，体积大（数 GB） |
+| **TinyTeX** | 全平台 | https://yihui.org/tinytex/ | 轻量（百 MB 级），命令行安装，适合自动化 Agent：`wget -qO- "https://yihui.org/tinytex/install-bin-unix.sh" | sh`（Windows 用 `install-bin-windows.bat`） |
+| **Tectonic** | 全平台 | https://tectonic-typesetting.github.io | 单二进制 + 自动拉依赖包，编译：`tectonic main.tex`；Windows `winget install TectonicTypesetting.Tectonic` 或 `scoop install tectonic` |
+| **Overleaf** | 在线 | https://www.overleaf.com | 零安装，把工程 zip 传上去编译；无本地权限时的默认答案 |
+
+装好后的标准编译序（含参考文献）：`pdflatex main → bibtex main → pdflatex main ×2`，或一条 `latexmk -pdf main`。CVPR 这类模板用 `xelatex` 时把 `pdflatex` 换成 `xelatex` 即可。
+
+Agent 行为规范：安装动作**必须先征得用户同意**再执行；用户选 Overleaf 就把工程打包成 zip 交付并说明上传步骤。
+
+---
+
+## 4. 完整流程清单
+
+1. 扫描文档 → 按 §1 列出**figure plan**（位置 + 每张的图种 + 从上下文提取的实体）——先给用户看清单再批量出图（这一步可以问，出图不问）
+2. 逐张构造 prompt（§2）→ 调 `/api/v1/generate` → base64 存 PNG
+3. **打开图片自查**（AI 有视觉能力就看一眼：文字乱码/实体拼写/结构对不对得上原文），不对就改 prompt 重出
+4. 按版式插回（§3）+ 生成 caption
+5. 汇报：每张图的「文档位置 → 图文件 → caption」对照表，提示用户全文图号/交叉引用需最终编译或人工复核

package/skill/promptfigure-api/references/figure-upgrade-workflow.md

@@ -0,0 +1,201 @@
+# 图表升级与整文批处理工作流
+
+> 场景：用户扔来一篇论文 + 一堆已有图（多半是 MATLAB/Python/Origin 出的），要求「把图都变高级，再加几张流程图/机制图」。本文件覆盖：**① 需求分型 ② 澄清协议 ③ 两种执行模式 ④ 代码图数据溯源 ⑤ 追溯台账**。插图位定位与上下文提取见 `document-workflow.md`；PDF/WPS 格式、主动插图建议、参考论文风格库见 `proactive-upgrade.md`；**单张图的意图确认与提示词审核协议（出图前免费环节）见 `prompt-review-workflow.md`**。
+
+---
+
+## 0. 需求分型：先看图里的数字是不是真的
+
+两类需求走两条完全不同的路，分错的代价是**数字造假**：
+
+| 需求 | 判据 | 路线 |
+|---|---|---|
+| **A1. 结果图美化**（曲线/柱状/热图/箱线…） | 图上带**精确数值**（刻度、柱高、数据点） | 🔴 **绝不走 AI 生图**。数据溯源 + 本地重绘（§3）——AI 画图模型必画错数字，坐标必须是真数据 |
+| **A2. 示意图升级**（用户已画的结构/流程/机制图，嫌丑） | 图上只有方块、箭头、标签，无数值 | AI 升级：结构照搬 + 视觉升级指令（§4.2），可选参考图 |
+| **A3. 结构组合**（多张小图合并成一张大图） | 多张 A1 或 A2 要拼版 | A1 部分本地 matplotlib subplot 拼版；A2 部分合并成一个多 panel prompt（§4.1） |
+| **B. 代码画不出的图**（流程图/机制图/神经网络图/算法示意） | 用户只能嘴上说 | promptFigure API（§4），本技能的主场 |
+
+**一句话分流：数字支撑 → 本地画；结构故事 → API 画；一张图里混着两者 → 拆开，各走各的，最后拼版。**
+
+> 🔴 **每轮结束必须交付台账**：新建 `promptfigure-out/vN/round-vN.md`——本轮清单（图种/档位/版本/本机路径/插入位置）、每张图的插入位置（上段末句 + …… + 下段首句）、所用上下文（只放首尾句）、数据文件只给引用链接；「优化前 → 优化后」对比也落在这里。全文协议见 `deliverables-ledger.md`。
+
+> 🔴 **「把终稿变成可编辑矢量/PPT 版」不属于以上任何一类**——那不是 matplotlib 的活，也不是出图 API 的活。走 `SKILL.md` **阶段 5**：终稿交付后先问用户要不要，比赛/数模默认不做（速度优先），时间充裕才由**宿主 AI 用本地的矢量工具/代码照着重绘**（禁止描摹，必须每个元素可编辑）。§3 的 matplotlib 只负责 A1 数据图的真数据重绘（防数字造假），不碰任何矢量转换。
+
+---
+
+## 1. 澄清协议：整文任务开工前的一轮集中反问
+
+SKILL.md 的「零反问」铁律**约束的是对 API 的出图过程**——出图时不许停下来问参数。但整文级批量任务（用户甩来一篇文章）在**开工前允许且应该有且只有一轮集中澄清**。这一轮的作用就是替 API 把意图收敛好：用户的 Agent 澄清得越准，发给 API 的请求就越正常。
+
+**必问 4 项**（一轮问完，之后不再问）：
+
+| # | 问题 | 为什么必须问 | 用户没答时的推定默认 |
+|---|---|---|---|
+| 1 | **使用场景**：期刊投稿 / 组会 PPT / 基金标书 / 海报？ | 决定信息密度、字号、比例、档位——期刊图求克制精确，PPT 图求大字号强对比 | 期刊投稿（最保守） |
+| 2 | **目标模式**：单图精修还是整文批处理？ | 决定执行流程（§2） | 整文批处理 |
+| 3 | **原始材料**：已有图的生成代码 / 数据文件（.xlsx/.csv/.mat）在不在？ | A1 类图没有原始数据就只能放弃或降级处理（§3） | 不存在 → 该图按 A2 处理或明确告知做不了 |
+| 4 | **定稿档位**：草稿满意后用 premium 2K 定稿？ | premium $0.15/张，批量任务先确认预算 | 草稿 standard，定稿 premium |
+
+**单图任务不需要这轮澄清**——上下文足够就推断，信息不足用占位符（这是 SKILL.md 零反问的适用域）。
+
+### Agent 自检：还缺什么（发给 API 前的最后闸门）
+
+每张图提交前，Agent 对自己过一遍这个清单——**缺的要么向用户澄清（仅限第 1 轮），要么推断补全，绝不含糊提交**：
+
+- [ ] 图种定了吗？（管线/机制/对比/框架/图形摘要，对照 `document-workflow.md` §1.5）
+- [ ] 实体清单齐全吗？**专有名词原样搬运**了吗？（拼写不改）
+- [ ] 关系结构（谁指向谁、分几组、哪条是 skip/反馈）写进 prompt 了吗？
+- [ ] 这张图是不是 A1 真数据图？（是 → 停，走 §3，不调 API）
+- [ ] ratio 和档位按场景定了吗？
+
+---
+
+## 2. 两种执行模式
+
+### 2.1 单图精修模式（图少、要求高）
+
+```
+意图收敛（§1 自检清单）→ standard 出 2~3 版草稿（prompt 各有侧重：
+一版忠实原结构、一版重构布局、一版换视觉方案）
+→ 看图自审 + 用户挑 → 定稿方向微调 prompt → premium 2K 定稿
+```
+
+- 草稿的价值在**探索构图**，不在画质——全用 standard，别烧 premium 试错
+- 定稿不是重新写 prompt：拿选中草稿的服务端润色结果（`result.prompt` 或页面对应的最终提示词）**微调**后升档，保证草稿→定稿一致
+
+### 2.2 整文批处理模式（用户甩来一整篇）
+
+```
+① 全文扫描：已有图逐张分型（§0），插图位定位（document-workflow.md §1）
+② 出 figure plan 清单给用户看：
+   | 位置 | 现有图 | 分型 | 处置动作（本地重绘/AI升级/新增/不动） |
+③ 集中澄清一轮（§1 必问 4 项）——合并进清单汇报里问
+④ 全部走 standard 草稿（新增图 + AI 升级图），A1 图并行做数据溯源
+⑤ 汇总：每张草稿 + 一句改动说明 → 用户确认/打回
+⑥ 满意后逐张 premium 2K 定稿，插回文档，写台账（§5）
+```
+
+- **默认先出全部草稿**再定稿——批处理改的多，先全稿确认能避免「第 3 张改了方向、前 2 张白定稿」的返工
+- 每张草稿都过视觉自查（乱码/拼写/结构与原文对不上 → 改 prompt 重出，别把垃圾递给用户）
+- 批量调用遵守 RPM 限制（免费 5/min，会员更高），串行 + 退避，别并发轰炸
+
+---
+
+## 3. 代码图数据溯源（A1 类的唯一正路）
+
+> 本节 = **A1 数据图专用**（曲线/柱状/热图等带真数值的图）。用 matplotlib 的唯一理由是「坐标必须是真数据」；它不是通用美化手段，更不是矢量转换手段——「照终稿做可编辑矢量版」见 `SKILL.md` 阶段 5。
+
+**为什么必须溯源**：结果图上的文字往往很小，视觉模型抄轴刻度、抄数据点**必然出错**；靠 OCR 抄数出来的图是假的。唯一可靠路径是找到原始数据，用真数据重绘。
+
+### 步骤
+
+1. **读图取线索**：轴标签、图例文字、caption 里的变量名/指标名（这些是下一 步的 grep 关键词）
+2. **找生成代码**：在用户工程里搜图例字符串/函数名：
+   ```bash
+   grep -rn "图例文字\|legend_label\|xlabel('Loss')" --include="*.m" --include="*.py" --include="*.ipynb" .
+   ```
+   MATLAB 从 `.m` 脚本看 `plot()/bar()/scatter()` 的数据来源变量；Python 看 `plt.plot(x, y)` 的 x/y 从哪个文件读的
+3. **顺藤摸到数据文件**：`.xlsx` / `.csv` / `.mat` / `.txt`，确认列名与图例一一对应
+4. **本地重绘美化**（pandas/matplotlib）：
+   - 语义化多色配色：每条曲线/每组柱子按含义定色（对照组冷色、实验组暖色、强调指标用高饱和强调色），不要默认 MATLAB 蓝
+   - 色相 ≤4 + 强调色 1~2，白底，去掉无用图表垃圾（多余边框、3D 效果、双 y 轴滥用）
+   - 字号按场景：期刊正文图 ≥8pt 成图尺寸，PPT 图 ≥18pt
+   - 导出：期刊 300dpi+ PNG/TIFF 或 PDF/SVG 矢量；PPT 用高分辨率 PNG
+5. **逐位核对**：重绘图的每个数据点与原图/原始数据核对，数值不许有任何出入
+6. **找不到代码或数据** → 回到 §1 必问第 3 项，向用户要。**要不到就明确告知这张图做不了 A1 升级**，可以降级为「构图示意版」（明说数字是示意），绝不 silently 假装是原数据
+
+---
+
+## 4. B 类图与 A2 升级：给 API 的 prompt 构造
+
+上下文提取总纲见 `document-workflow.md` §2（必给 3 项：图种/实体/关系结构）。本节只讲升级场景的增量。
+
+### 4.1 结构组合（多组合一）
+
+把 N 张小图的信息合并成一个多 panel prompt：
+
+- **panel 清单**：每个 panel 一句「画什么 + 实体 + 内部结构」
+- **布局声明**：几行几列、panel 编号（A/B/C）、公共图例放哪、箭头怎么跨 panel 连接
+- 实体名仍**原样搬运**；ratio 选 `16:9`（横向组合）或按 panel 数定
+- 实例：`"组合图，2 行 3 列六个 panel。Panel A：…；Panel B：…；panel 之间用带箭头的灰色连接线表示数据流，整体共享一个图例。"`
+
+### 4.2 视觉升级（A2：已有示意图嫌丑）
+
+prompt = **结构照搬** + **升级方向**，两部分都要：
+
+- 结构照搬：原图有哪些模块、怎么连、分几组——拓扑一个都不许变（变结构=篡改用户的学术内容）
+- 升级方向写具体：「扁平矢量风、白底深灰描边、模块按语义配色（输入=浅蓝、核心模块=橙红强调、输出=浅绿）、模块内配简洁图标、等宽圆角」——不要只写「变好看」
+- **参考图**：有原图截图可传 `refDataUrl`（base64 ≤8MB）或 `refUrl`（公网直链）。⚠️ 参考图通道（上游 /images/edits）2026-09-07 起有 503 故障记录——批量任务开始前先用 1 张 standard 试水，失败就纯文字描述结构（prompt 写清楚就够，本管线本就擅长从文字重建结构）
+- 🔴 **文字密集图（架构图/管线图，模块里带公式与小字注释）standard 档基本不可用**：2026-09-09 CVPR 论文实测，standard 出的架构图标题拼写错（"Uncertanity"）+ 多处小字乱码，直接不可交付。这类图草稿也别用 standard 省钱——乱码草稿没有参考价值，直接 premium；或把模块内小字删到只剩模块名再出 standard 草稿
+
+### 4.3 结合论文（A2/B 共用）
+
+从插图位前后 2-3 段提取实体与关系，不要让用户复述——详见 `document-workflow.md` §2.0/§2.1。批处理时这一步在 ② 阶段一次性做完，存进 figure plan。
+
+---
+
+## 5. 追溯台账：figure-ledger.json
+
+用户问「哪一次生图做了什么、想退回哪一版」——在**工程根目录**维护一个 JSON 台账，只追加、不覆盖、随工程进 git。本地文件即可，不需要服务端建表：轻量、随项目走、git 天然版本化。
+
+```json
+{
+  "project": "osti-rsr-paper",
+  "created": "2026-09-09",
+  "entries": [
+    {
+      "id": "fig3",
+      "ts": "2026-09-09T21:40:00+08:00",
+      "scene": "journal",
+      "source": {
+        "file": "sections/methods.tex",
+        "locator": "L142-156 (\\ref{fig:pipeline})",
+        "quote": "编码器提取特征后经跨尺度融合模块送入解码器"
+      },
+      "action": "new",                    // new | upgrade | combine | restyle
+      "prompt": "提交给 API 的原始意图",
+      "prompt_final": "服务端润色后的最终提示词（result.prompt）",
+      "tier": "standard",                  // 草稿 standard / 定稿 premium
+      "asset": "figures/drafts/fig3-v1.png",
+      "status": "draft",                   // draft | final | superseded
+      "note": "构图偏挤，v2 把 skip 连接移到 panel 下沿"
+    },
+    {
+      "id": "fig3",
+      "ts": "2026-09-09T22:10:00+08:00",
+      "prompt_final": "…（v2 微调后）",
+      "tier": "premium",
+      "asset": "figures/fig3.png",
+      "status": "final",
+      "note": "v1 定稿打回后重出"
+    }
+  ]
+}
+```
+
+规则：
+
+- 同一图 id 的每次生成（草稿、打回、定稿）都是**新 entry**，旧 entry 状态改 `superseded`——历史永远可回溯
+- `source.locator` 写到能一键跳回的粒度（文件 + 行号/段落号）
+- `prompt_final` 必须存：它是「草稿→定稿」一致性的锚点，也是用户日后手动微调的起点
+- 每轮批处理结束，把台账路径 + entry 摘要报给用户
+
+**两类 entry 模板要区分**（`action` 字段决定）：
+
+- **AI 生成**（`action`: new/upgrade/combine）：有 `prompt` / `prompt_final` / `tier`。⚠️ `/api/v1/generate` 的响应**不含润色后的 prompt**（`prompt_final` 只有网页异步流程 `/api/gen-result` 才返回）——纯 API 用户在 entry 里存 `prompt`（自己提交的意图）+ `crafted: true/false` 即可，`prompt_final` 字段留空并注明 `via: "api"`；走 §2.1 网页异步流程的才填 `prompt_final`
+- **数据图重绘**（`action`: restyle）：不写 prompt 字段，改写 `data_source`（生成脚本路径或数据文件路径）+ `verification`（核对项数与结果，如 "27 checks, 0 mismatch"）+ `style`（配色/字号要点）。真数据图没有 prompt，别硬套 AI 模板
+
+### 402 余额场景处置（批处理必读）
+
+迭代重试会连续扣费——**开工前先查余额**（控制台 `#account-balance`，API 的 `balance` 字段滞后不可信），预估「张数 × 单价 + 至少 2 次重试余量」。跑到一半 402 时：不扣费、任务中断，如实告知用户余额耗尽、请用户充值后继续——**已完成的图不回滚**，台账里记清中断位置，续跑从断点开始。
+
+---
+
+## 6. 完整流程清单（整文批处理）
+
+1. 扫描全文 → 已有图分型（§0）+ 插图位定位（`document-workflow.md` §1）
+2. figure plan 清单 + 集中澄清一轮（§1 必问 4 项）→ 用户确认处置方案
+3. A1 图：数据溯源 + 本地重绘（§3）；A2/B 图：构造 prompt（§4）
+4. 全部 standard 草稿 → 视觉自查 → 汇总给用户
+5. 用户确认 → 逐张 premium 2K 定稿 → 插回文档（`document-workflow.md` §3）
+6. 写台账（§5）→ 汇报：位置 → 图文件 → 版本 → 台账路径，提示图号/交叉引用需最终复核