html-paper-figure

name	html-paper-figure
description	用 HTML+CSS 绘制流程图/技术路线图/系统架构图/流水线/框架矩阵图，经 Electron printToPDF 输出矢量单页 PDF，供论文 \includegraphics 直接引用。当用户说"画HTML图"、"技术路线图"、"流程图"或需要论文非数据类示意图时使用。本版为 MetaMath Harness（DeepSeek Harness/DSH）专用适配版：命令经 pwsh 执行，视觉自检用 DSH 原生 read_image/vision_analyze。

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/，若存在），没有才回退安装目录。防御式解析，找不到再报错：

# ⛔ 这台机器必须用 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 不破坏。

⛔ 结束前必须跑产物校验：

$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: 恢复检查（断线重跑必读）

⛔ 本步骤可能因断线/手动重跑被多次启动。每次启动前必须先扫描已有产物：

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. 选规划文档（按存在性优先级）并确定语言：

# 规划文档（按存在性优先级）
$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)