promptfigure 0.2.0 → 0.3.1

package/adapters/codex/promptfigure/skills/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/adapters/codex/promptfigure/skills/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）→ 汇报：位置 → 图文件 → 版本 → 台账路径，提示图号/交叉引用需最终复核

package/adapters/codex/promptfigure/skills/promptfigure-api/references/proactive-upgrade.md

@@ -0,0 +1,120 @@
+# 主动升级工作流：PDF/WPS 文稿 · 主动插图建议 · 参考论文风格库
+
+> 场景：用户不是 LaTeX 用户——给的是 **PDF / WPS / Word**；而且常常说不出哪里该插图，只说「帮我弄得更高级」。本文件覆盖：**① PDF/WPS 格式对策 ② 主动插图建议 ③ 从原始数据到成图的四步管线 ④ 参考论文风格库**。图分型与执行模式见 `figure-upgrade-workflow.md`，LaTeX/docx 插回见 `document-workflow.md`。
+
+---
+
+## 0. PDF / WPS / Word：格式现实与对策
+
+**关键认知：PDF 是最终渲染产物，插不回去。** 所有「在 PDF 里换图/插图」的想法都不成立，只有三条正路：
+
+| 输入格式 | 能做什么 | 对策 |
+|---|---|---|
+| **.docx**（Word/WPS 另存的） | 完整读写 | 走 `document-workflow.md` 的 docx 路径（python-docx） |
+| **.wps 老格式** | python-docx 读不了 | 让用户在 WPS 里**另存为 .docx**；或 LibreOffice `soffice --convert-to docx` 转换后处理 |
+| **PDF** | 只读解析 | ① 解析取内容与已有图 ② **图文件 + 改动清单交付**（用户插回自己的源文档）③ 需要时生成一份 docx 副本供直接采用 |
+
+### PDF 解析（pymupdf/fitz）
+
+```python
+import fitz
+doc = fitz.open("paper.pdf")
+for pno, page in enumerate(doc):
+    text = page.get_text()                       # 逐页文本（定位章节/caption）
+    for img in page.get_images(full=True):       # 已有位图插图
+        xref = img[0]
+        pix = fitz.Pixmap(doc, xref)
+        pix.save(f"extracted/p{pno}_img{xref}.png")
+    # 矢量图/整页截图：page.get_pixmap(clip=rect, dpi=200)
+```
+
+- **找已有图**：`page.get_text()` 里检索 `Figure N` / `图 N` 的 caption 行，与同页图像配对
+- **找插图位**：caption 缺号、正文 `如图 N` 引用悬空、章节启发式（同 `document-workflow.md` §1）照样适用——只是动作从「插回」变成「写进建议清单」
+- 提取出的已有图 → 按 `figure-upgrade-workflow.md` §0 分型（真数据图 → 数据溯源；示意图 → AI 升级）
+
+---
+
+## 1. 主动插图建议（用户不知道哪里能插图）
+
+用户给不出占位符不等于没有插图位。扫描全文后，**主动产出一份「插入建议清单」**（位置 / 图种 / 理由 / 预期作用），让用户勾选后再画——建议可以大胆，画之前必须过目。
+
+**数学建模论文（MCM/国内赛）惯用插图位**（O 奖版式经验）：
+
+| 位置 | 建议图 | 说明 |
+|---|---|---|
+| 引言/问题重述之后 | **全文逻辑关系图 / 技术路线图** | 介绍后续各部分的承接逻辑，评委 30 秒看懂全文结构——O 奖标配，性价比最高的一张 |
+| 建模假设章 | 模型机制示意图 | 把抽象假设画成可视结构 |
+| 每个模型小节 | 该模型的流程/结构示意 | 一模型一图 |
+| 灵敏度/结果分析 | 数据图**本地画**；对比关系示意才走 API | 真数字铁律不变 |
+| 全文收尾 | 优缺点对比 / 方法对比示意 | 概念对比类 |
+
+**其他文体**：偏文科/综述类段落适合**事例示意图、场景示意、分类关系图**（实体多、关系定性、无数值——正符合 `document-workflow.md` §1.5 的正当理由）。判定仍按那条口诀：三个实体手拉手 → 画；数字支撑 → 本地画；都没占 → 不画。
+
+---
+
+## 2. 四步管线：从原始数据到高级 AI 图
+
+用户说「帮我弄高级」时，按这四步走，每步的产出喂给下一步：
+
+### ① 原始数据分析
+
+Agent 直接分析用户给的数据文件（pandas：描述统计、分布、分组差异、相关性、时序趋势）。产出：**这份数据里有什么值得画的结构**——不是替用户看数字，是找出「哪组对比/哪个趋势承载论文论点」。
+
+### ② 图像需求推演
+
+结合 ① 的发现 + 论文章节意图（这一节想论证什么），推断：哪里需要什么图、什么形式。分流按铁律：**数据承载 → 本地 matplotlib（§ figure-upgrade-workflow §3）；结构故事 → API**。输出物 = 建议清单（§1 格式）+ 每张图的分型。
+
+### ③ 提示词生成与绘图
+
+生成提示词按 `prompt-review-workflow.md` 的 golden skeleton 写，并走 8 项审核（或双 Agent 互审）后才调 API。
+
+逐张走 `figure-upgrade-workflow.md` §1 自检清单（图种/实体原样搬运/关系结构/ratio/档位）→ `/api/v1/generate`。批处理全程 standard 草稿，模式按 §2（单图精修 / 整文批处理）。
+
+### ④ 迭代优化循环（出图不算完）
+
+每张草稿出图后，Agent **必须打开图对照三方检查**，这是「激发对方 Agent 不断检查优化」的落点：
+
+- **对论文原文**：实体拼写、模块数、结构方向有没有画歪（乱码/漏实体 = 重出）
+- **对数据**：本地重绘图逐位核对（`figure-upgrade-workflow.md` §3 第 5 步）
+- **对之前的图**：全文配色语言、视觉风格是否一致——同一篇论文的图应像同一个人画的
+- 不合格 → 改 prompt 重出；合格 → 进台账、等用户确认后升档定稿
+
+---
+
+## 3. 参考论文风格库：让「高级」有个对照物
+
+用户说「想要高级」是模糊词，最好的解释物是好看的真实范例。约定目录：
+
+```
+refs/
+  papers/    # 整本 PDF（顶会/顶刊/优秀毕设）
+  figures/   # 单图 PNG（论文里的好看插图）
+```
+
+### 获取途径
+
+1. **Agent 自动找**：GitHub（awesome-list、论文官方 repo、ml-visuals 类开源可视化项目）、arXiv 顶会论文 PDF——按用户研究主题搜同类
+2. **用户手动下载**：学校账号拉 SCI/顶刊——Agent 列出想要的关键词/期刊清单让用户去下
+
+### 解析与使用
+
+- 整本 PDF → pymupdf 提取图 + caption（§0 方法）；单图直接看
+- Agent **看图归纳风格特征**：配色方案（几个色相、怎么强调）、布局（panel 结构、图例位置）、图标风格、标注密度、字体气质 → 拆到特征级
+- 风格特征转成 prompt 里的**视觉描述文本**（"多色语义化 pastel、白底深灰描边、模块圆角+简洁图标"），而不是"参考图 X 的样子"
+
+### 🔴 合规红线
+
+- 参考论文的图**只准提炼风格特征，禁止复刻**——照着别人已发表论文的图重绘内容并拿去展示/投稿，是学术与版权双重事故
+- `refDataUrl`/`refUrl` 参考图通道**只传用户自有或已授权的图**；别人的图一律走文字特征描述（通道本身 2026-09-07 起也有 503 故障记录，用前 1 张 standard 试水）
+- 风格可以学，内容必须原创
+
+---
+
+## 4. 完整流程清单（PDF 整文主动升级）
+
+1. 格式判定：docx 直读 / wps 转换 / PDF 解析（§0）——文本 + 已有图 + 章节结构一次取全
+2. 已有图分型（figure-upgrade-workflow §0）+ 数据分析（§2①）→ 图像需求推演（§2②）
+3. 产出两份清单给用户：**插入建议清单**（§1）+ **已有图处置清单**（重绘/升级/不动）→ 用户勾选
+4. 参考风格：refs/ 有料就先归纳特征写进每个 prompt（§3），没料按语义多色默认规范
+5. 全部 standard 草稿 → 三方检查迭代（§2④）→ 汇总给用户
+6. 确认后 premium 2K 定稿 → **图文件 + 改动清单 + figure-ledger 台账**交付（PDF 用户自行插回源文档；docx 用户可代插）