html-paper-figure

# Paper Figure — HTML/CSS 矢量图（MetaMath Harness 版） 用 HTML+CSS 生成论文非数据类示意图。 只处理架构/流程/路线类示意图；数据图（matplotlib/seaborn）由上游 paper-figure 步骤生成。 **HTML 相对 DrawIO 的核心优势**：用 flex/grid 自动布局，不写绝对坐标 → 天然免疫节点重叠/坐标错位/连线穿越。因此本 skill **不需要** drawio 的坐标结构自检（drawio_check.py），改用 HTML/PDF 专属质检。 ## ⚠ 运行环境（MetaMath Harness / DSH 专用约定，与 TRAE 版的差异） - **命令一律经 DSH 的 `pwsh` 工具执行**：每次调用都是全新 pwsh 进程，**变量不跨调用保留**，工作目录用 `workdir` 参数指定。原文 bash 块仅作语义参考，执行时按语义翻译成 PowerShell（`ls figures/*.pdf | wc -l` → `(Get-ChildItem figures\fig_*.pdf).Count`；`grep -c` → `Select-String | Measure-Object`；临时文件写工作区 `_tmp\`，不写 `/tmp/`）。 - **视觉自检不依赖外部脚本**（TRAE 版的 drawio_vision_check.py / tikz_vision_check.py 本机没有，也不要去找）：改用 DSH 原生视觉能力——`read_image` 直接看渲染出的 PNG，或 `vision_analyze` 让视觉模型审图。PDF→PNG 用 PyMuPDF（本机已装）。⛔ `vision_analyze` 明确返回"无法查看图片"时按 skipped 处理，禁止凭文件名/尺寸/上下文猜测图面内容。 - 下文 `$CAPTURE` / `$HTMLCHECK` / `$TPL_DIR` 等是**语义简写**，指《工具路径解析》一节定位出的完整路径；由于 pwsh 变量不跨调用，每次实际执行前先在该次调用里重定位（或直接写完整路径）。 - 本机事实（已验证）：`python` 可用（⛔ 不用 `python3`，会触发 Microsoft Store 存根）；`xelatex`/`pdftoppm`/`pdfseparate` 来自 TeX Live 2025；PyMuPDF(fitz) 可用、pdf2image 不可用；`node`/`npx` 可用、`electron` 不在 PATH（由 screenshot_capture.py 自动回退 `npx --yes electron`）。 ## ⚡ 快速模式检测（开头先定一次） DSH 下 **FAST_MODE 默认 0**（质量优先）。当用户在当前对话明确说"快速模式/赶时间/跳过视觉自检"时记 FAST_MODE=1，并在 Step 5 / Step 5.6 / Step 7 一致按 1 处理（pwsh 块间不共享变量，各步骤就地重判一次，不依赖文件探测）。 **若 `FAST_MODE=1`（速度优先）：** 仍按图表清单产出所有图（一张不漏、能出 PDF、过 html_pdf_check、**过 Step 4.5 元素级几何自检**），但**跳过** vision 视觉自检的多轮修复循环——生成即用，仅当 html_pdf_check FAIL 或明显空图时才补。**若 `FAST_MODE=0`（默认）：** 视觉自检修复循环照常执行。⛔ **几何自检（Step 4.5）任何模式都跑**：它快（纯几何、几十毫秒）、且能挡"文字被裁/越界/重叠"这类真翻车，不算 vision 加分项。 ## Constants - **FIG_DIR = `figures/`** - **CUSTOM_REQUIREMENTS** — 用户自定义要求，最高优先级。 ## ⛔ 工具路径解析（每次会话开头先定位，实际执行时在各次 pwsh 调用里重新赋值） **MetaMath Harness（DSH）环境下没有后端注入的 `_templates/`、`_utils/`**，本 skill 的完整安装位置（含 templates/ tools/）是 `F:\DeepSeekHarness\.dsh\skills\html-paper-figure\`，出图工具 screenshot_capture.py + capture.js + katex-assets 已随 skill 安装。优先用工作区副本（`_templates/`、`_utils/`、`tools/`，若存在），没有才回退安装目录。防御式解析，找不到再报错： ```powershell # ⛔ 这台机器必须用 python，不能用 python3（python3 触发 Microsoft Store 存根，exit 49） $PYTHON = 'python' # DSH skill 安装目录（本 skill 的完整安装位置，含 templates/ tools/） $SKILL_DIR = 'F:\DeepSeekHarness\.dsh\skills\html-paper-figure' # 模板目录：优先工作区 _templates/，回退到 skill 安装目录（模板仅极端兜底参考，正常流程不读） $TPL_DIR = @('_templates', (Join-Path $SKILL_DIR 'templates')) | Where-Object { Test-Path (Join-Path $_ 'tpl_roadmap.html') } | Select-Object -First 1 "模板目录 TPL_DIR=$TPL_DIR" # 出图工具（screenshot_capture.py：DSH 版包装器，内部自动调 Electron + capture.js） $CAPTURE = @('_utils\screenshot_capture.py', 'tools\screenshot_capture.py', (Join-Path $SKILL_DIR 'tools\screenshot_capture.py')) | Where-Object { Test-Path $_ } | Select-Object -First 1 "出图工具 CAPTURE=$CAPTURE" # HTML/PDF 质检脚本（优先 _utils/，回退 skill 安装目录） $HTMLCHECK = @('_utils\html_pdf_check.py', '_templates\html_pdf_check.py', (Join-Path $SKILL_DIR 'tools\html_pdf_check.py')) | Where-Object { Test-Path $_ } | Select-Object -First 1 "质检脚本 HTMLCHECK=$HTMLCHECK" # 视觉自检：MetaMath Harness（DSH）原生能力 —— read_image 直接看渲染 PNG / vision_analyze 让视觉模型审图。 # 不依赖外部脚本（原 TRAE 版的 drawio_vision_check.py 本机没有，不要去找）。PDF→PNG 用 PyMuPDF(fitz)，见 Step 5。 # ===== TikZ 依赖（仅当规划有精密几何图才用；公式本身走 HTML+KaTeX，几何示意才靠 xelatex 编译 TikZ）===== # 规则文档（物理尺寸/字号/scale 匹配规则；无则用 Step 5.5 内置规则） $TIKZ_RULES = @('_utils\tikz_rules.md', 'skills\shared-scripts\tikz_rules.md') | Where-Object { Test-Path $_ } | Select-Object -First 1 "TikZ 规则 TIKZ_RULES=$(if ($TIKZ_RULES) { $TIKZ_RULES } else { '（无，将用内置规则）' })" # tikz_check.sh 结构自检脚本（bash 脚本，DSH 环境大概率没有；没有就跳过，由几何/视觉自检兜底） $TIKZ_CHECK = @('_utils\tikz_check.sh', 'skills\shared-scripts\tikz_check.sh') | Where-Object { Test-Path $_ } | Select-Object -First 1 "TikZ 自检 TIKZ_CHECK=$(if ($TIKZ_CHECK) { $TIKZ_CHECK } else { '（不可用，将跳过结构自检）' })" # xelatex（TikZ 编译器；不存在则本机无 TikZ 能力，跳过 TikZ 只出 HTML 图；本机 TeX Live 2025 已装） $XELATEX = (Get-Command xelatex -ErrorAction SilentlyContinue).Source "TikZ 编译器 XELATEX=$(if ($XELATEX) { $XELATEX } else { '（不可用，将跳过 TikZ 图）' })" ``` ## ⛔⛔⛔ Output Contract（最高优先级） **必须产出至少 1 张 `figures/fig_*.pdf`，并更新 `figures/latex_includes.tex`**。产物契约与 paper-figure-drawio **完全一致**（对账口径相同，两个 skill 可互换；DSH 下由下方校验块代行对账）： - 图名前缀固定：`fig_arch`（架构）/ `fig_flow`（流程，如 `fig_flow_q1`）/ `fig_roadmap`（技术路线）/ `fig_pipeline`（流水线）/ `fig_framework`（框架）。 - 中间产物是 `figures/fig_*.html`，最终产物是同名 `figures/fig_*.pdf`。 - ⛔ **图内绝不放标题**：标题一律由 LaTeX `\caption{}` 管理（避免标题重复、字体不一致）。 - ✅ **流程/算法/架构图里的公式可直接写在 HTML 里**：节点文字内用 `\( ... \)`（行内）或 `\[ ... \]`（独立行）写 LaTeX，出图时命令带 `--render-math`（见 Step 3），截图管线会注入 KaTeX 把它们渲染成真公式（矢量、可放大不糊）。不再需要为了几个公式就整张图退回 TikZ。 - ⛔ **只有"精密几何示意图"才走 TikZ**：需要按真实坐标画点/线/角度/向量场的几何图（如绳系摆几何、光路、受力分解），HTML 的 flex 相对布局摆不准，才用 TikZ 编译（见 Step 5.5）。产物 `figures/tikz_*.pdf` + 同名 `.tex`，写进 `latex_includes.tex`。⛔ 仅当规划清单明确要求这类几何图时才生成，无则跳过。 ⛔ **特殊豁免**：若 PAPER_PLAN.md 明确无架构图/流程图需求（纯文字论文/数据分析报告），允许跳过本 skill 的产物要求；但仍要保留已有 `figures/latex_includes.tex` 不破坏。 ⛔ **结束前必须跑产物校验**： ```powershell $PASS = $true New-Item -ItemType Directory -Force -Path figures | Out-Null $PDF_COUNT = (Get-ChildItem figures\fig_*.pdf -ErrorAction SilentlyContinue).Count $PLAN_NEEDS_DIAGRAM = 0 foreach ($f in @('PAPER_PLAN.md','PROBLEM_ANALYSIS.md')) { if (Test-Path $f) { $PLAN_NEEDS_DIAGRAM += (Select-String -Path $f -Pattern 'html|架构图|流程图|技术路线|fig_arch|fig_flow|fig_roadmap|fig_pipeline|fig_framework' -ErrorAction SilentlyContinue | Measure-Object).Count } } # ⛔ 优先按 FIGURE_MANIFEST 对账：规划的每张图必须产出 $PLAN_FILE = 'PROBLEM_ANALYSIS.md','PAPER_PLAN.md','MODELING_REPORT.md' | Where-Object { (Test-Path $_) -and (Select-String -Path $_ -Pattern '<!-- BEGIN FIGURE_MANIFEST -->' -SimpleMatch -Quiet) } | Select-Object -First 1 if ($PLAN_FILE) { $mani = (Get-Content $PLAN_FILE -Raw) -replace '(?s).*<!-- BEGIN FIGURE_MANIFEST -->', '' -replace '(?s)<!-- END FIGURE_MANIFEST -->.*', '' # ⛔ 按 manifest「HTML/DrawIO/TikZ 章节」标题抓该章节下的全部图名（权威），不靠文件名前缀白名单 $expected = @(); $cap = $false foreach ($line in ($mani -split "`n")) { if ($line -match '^\s*\*\*') { $cap = ($line -match '(?i)html|drawio|tikz'); continue } if ($cap -and $line -match '^\s*-\s+((?:fig_|tikz_)[a-zA-Z0-9_]+)') { $expected += $Matches[1] } } $missing = 0 foreach ($name in ($expected | Select-Object -Unique)) { # ⛔ 认 .pdf/.html/.png 三种：.pdf(最终产物)、.html(HTML中间产物)、 # .png(Word/docx 模式下 tikz_*.pdf/fig_*.pdf 被转 PNG 删 PDF 后的产物)。 # 只认 pdf/html 会把 docx 模式下已转 png 的 TikZ 图误判成 missing。 if (-not (Get-ChildItem "figures\$name.pdf", "figures\$name.html", "figures\$name.png" -ErrorAction SilentlyContinue)) { Write-Output "❌ MANIFEST: $name missing"; $missing++ } } if ($missing -gt 0) { Write-Output "⛔ FIGURE_MANIFEST 对账失败（缺 $missing 张）"; $PASS = $false } else { Write-Output "✅ FIGURE_MANIFEST 全部产出" } } elseif ($PDF_COUNT -ge 1) { Write-Output "✅ figures/fig_*.pdf = $PDF_COUNT" } elseif ($PLAN_NEEDS_DIAGRAM -eq 0) { Write-Output "✓ 规划无架构图/流程图需求，跳过" } else { Write-Output "❌ 规划要求架构图/流程图但未生成"; $PASS = $false } if (-not (Test-Path figures\latex_includes.tex)) { New-Item -ItemType File -Path figures\latex_includes.tex -Force | Out-Null } if ($PASS -ne $true) { Write-Output "⛔ Output verification FAILED — must complete before ending" } ``` ## Workflow ### Step 0: 恢复检查（断线重跑必读） ⛔ 本步骤可能因断线/手动重跑被多次启动。每次启动前**必须**先扫描已有产物： ```powershell Write-Output "=== 工作区扫描 ===" $HAS_HTML = (Get-ChildItem figures\fig_*.html -ErrorAction SilentlyContinue).Count $HAS_PDF = (Get-ChildItem figures\fig_*.pdf -ErrorAction SilentlyContinue).Count $HAS_TIKZ = (Get-ChildItem figures\tikz_*.pdf -ErrorAction SilentlyContinue).Count Write-Output " fig_*.html: $HAS_HTML, fig_*.pdf: $HAS_PDF, tikz_*.pdf: $HAS_TIKZ" Get-ChildItem figures\fig_*.pdf, figures\tikz_*.pdf -ErrorAction SilentlyContinue | Select-Object Name, Length, LastWriteTime | Format-Table -AutoSize ``` | 状态 | 行动 | |---|---| | 规划要求的图都已生成（含 .html + 对应 .pdf 且过 html_pdf_check；有公式图的 tikz_*.pdf 也在） | **跳到 Step 6（latex_includes 核对）**，验证通过即完成 | | 部分已生成 | **只生成缺失的**（已有的不重画） | | 啥都没有 | 从 Step 1 开始 | ⛔ **铁律**：已有的 `figures/fig_*.html` / `figures/fig_*.pdf` / `figures/tikz_*.pdf` 不要重写。 ### Step 1: 读规划 + 确定要画哪些图 + 算风格种子 1. 选规划文档（按存在性优先级）并确定语言： ```powershell # 规划文档（按存在性优先级） $PLAN_DOC = 'PROBLEM_ANALYSIS.md','PROPOSAL.md','PAPER_PLAN.md' | Where-Object { Test-Path $_ } | Select-Object -First 1 Write-Output "=== 使用规划文档: $(if ($PLAN_DOC) { $PLAN_DOC } else { '（无，将只画 1 张 fig_roadmap 兜底）' }) ===" # 文献综述工作流不需要架构图，直接跳过（若命中此分支：本 skill 到此结束，不再执行后续步骤） if ((Test-Path LITERATURE_REVIEW.md) -and (-not $PLAN_DOC)) { Write-Output "✅ 文献综述工作流不需要架构图，已跳过" } # 语言判定（comp_apmcm_zh 是中文赛项，先排除） $probe = @($PLAN_DOC, 'AGENTS.md') | Where-Object { $_ -and (Test-Path $_) } if (Select-String -Path $probe -Pattern 'comp_apmcm_zh' -SimpleMatch -Quiet) { $FIG_LANG = 'zh' } elseif (Select-String -Path $probe -Pattern 'MCM|ICM|APMCM|comp_mcm|comp_apmcm|Language.*English|语言.*English' -Quiet) { $FIG_LANG = 'en' } else { $FIG_LANG = 'zh' } Write-Output "图内文字语言: $FIG_LANG" Write-Output "=== 规划中的架构/流程图清单 ===" if ($PLAN_DOC) { $hits = Select-String -Path $PLAN_DOC -Pattern '^\s*-\s*\[ \]?\s*fig_(arch|flow|roadmap|pipeline|framework)' -ErrorAction SilentlyContinue if ($hits) { $hits | ForEach-Object { $_.Line.Trim() } } else { Write-Output "（未找到显式清单，按工作流类型决定）" } } # ⛔ 判断规划里有没有「精密几何示意图」需求（只有它才走 TikZ） # 注意：含公式的流程/算法/架构图不再走 TikZ —— 公式直接写进 HTML 节点，出图加 # --render-math 由 KaTeX 渲染（见 Step 3、产物契约）。TikZ 只留给需要按真实 # 坐标画点/线/角度/向量的几何图（绳系摆、光路、受力分解等）。 $NEED_TIKZ = 0 if ($PLAN_DOC) { if (Select-String -Path $PLAN_DOC -Pattern 'tikz|几何示意|几何图|受力分解|坐标.*示意|光路' -Quiet) { $NEED_TIKZ = 1 } if (Select-String -Path $PLAN_DOC -Pattern '^\s*-\s+tikz_' -Quiet) { $NEED_TIKZ = 1 } # manifest 里出现 tikz_ 图名也算 } Write-Output "需要 TikZ 几何图: $NEED_TIKZ（1=是，见 Step 5.5；0=否，跳过 TikZ）" Write-Output "（提示：含公式的流程/算法/架构图走 HTML+KaTeX，不计入 NEED_TIKZ）" ``` 2. **⛔ 输出 HTML PLAN CHECKLIST（后续步骤对照用，规划清单就是合同）：** 工作流类型决定数量： - **数模竞赛 / 科研流程**（有 PROBLEM_ANALYSIS.md）：**严格按规划清单生成，一张不多一张不少**，**至少 1 张 fig_roadmap 技术路线图**。 ⛔ **清单里没有 `fig_flow_q1/q2/…` 就一张都不要画，也不要"补齐每个问题"**——子问题流程图默认关闭 （用户可在前端开启，开启时规划清单里自然会有），清单没列即用户不要，自作主张补齐属于违规超产。 - **开题报告**（有 PROPOSAL.md）：**只生成 fig_roadmap**，不画 fig_flow_q1/q2。 - **课程/论文写作**（有 PAPER_PLAN.md）：按 PAPER_PLAN.md 列出的 fig_arch/fig_flow_*/fig_pipeline 生成。 - **精密几何图**（`NEED_TIKZ=1`）：另在 Step 5.5 生成 `tikz_*`（按坐标画点/线/角度/向量的几何示意，如绳系摆、光路、受力分解），HTML 图与 TikZ 图**互补不重复**——同一张图只归其中一种引擎。含公式的流程/架构图归 HTML（公式靠 KaTeX 渲染），不进 TikZ。 ``` HTML PLAN CHECKLIST (from $PLAN_DOC): [ ] 1. fig_roadmap — 技术路线图 (tpl_roadmap, HTML) [ ] 2. fig_flow_q1 — 问题一求解流程图 (tpl_flow, HTML；公式写 \(...\)，出图加 --render-math) [ ] 3. fig_flow_q2 — 问题二求解流程图 (tpl_flow, HTML) [ ] 4. fig_pipeline — 数据处理流水线 (tpl_pipeline, HTML)