systems-diagramming

# 系统逻辑制图 ## 稳定执行契约 - **执行目标**：构建技术路线、模型关系、系统结构与算法流程等非数据型示意资产。 - **调用参数**：[figure-plan-or-data-path]。 - **权威输入**：问题分析.md、建模报告.md、计算结果.md及既有图表计划。 - **允许交付**：图表/中的 DrawIO、TikZ 与导出图，以及图表引用.tex中的对应入口。 - **禁止写入**：不得越权修改已冻结的上游事实、用户原始文件或本协议未授权的目录。 - **可用工具边界**：Bash(*), Read, Write, Edit, Grep, Glob, Agent。 - **最小交付**：结构清晰、节点可读、关系正确、源文件可编辑、导出结果可编译。 - **恢复入口**：优先读取当前工作、状态记录和已有产物，从最近一次通过门禁的位置继续。 - **失败回退**：结构关系不明确时回退查阅建模报告；不得用装饰性连线掩盖逻辑缺口。 - **收口顺序**：先核对输入，再完成产物，再运行本环节门禁，最后登记状态；门禁未通过不得宣告完成。 Produce DrawIO architecture diagrams and TikZ visuals for: **$ARGUMENTS** This is a **lightweight sub-step** split from evidence-visualization. It ONLY handles non-data diagrams (DrawIO + TikZ). Data visuals (matplotlib/seaborn) were already generated in the previous evidence-visualization step. ## 运行参数 - **FIG_DIR = `图表/`** - **CUSTOM_REQUIREMENTS** — User-specified requirements, highest priority. ## ⛔⛔⛔ 交付契约（最高优先级） **Must produce at least 1 `图表/*.drawio` or `图表/tikz_*.tex` and corresponding PDF, plus updated `图表/图表引用.tex`**. ⛔ **特殊豁免**：若 论文规划.md 清晰标明无架构图/过程图需求（纯文字论文/数据分析报告），准许跳过此 skill 的产物要求；但仍要保留已有的 `图表/图表引用.tex` 不破坏。 ⛔ **MUST run output verification prior to ending**: ```bash PASS=true mkdir -p 图表 PDF_COUNT=$(ls 图表/*.pdf 2>/dev/null | wc -l) DRAWIO_COUNT=$(ls 图表/*.drawio 2>/dev/null | wc -l) TIKZ_COUNT=$(ls 图表/tikz_*.tex 2>/dev/null | wc -l) PLAN_NEEDS_DIAGRAM=$(grep -iE 'drawio|tikz|架构图|流程图|fig_arch|fig_flow|技术路线图|fig_er' 论文规划.md 2>/dev/null | wc -l) if [ "$PDF_COUNT" -ge 1 ] || [ "$DRAWIO_COUNT" -ge 1 ] || [ "$TIKZ_COUNT" -ge 1 ]; then echo "✅ diagrams: PDF=$PDF_COUNT drawio=$DRAWIO_COUNT tikz=$TIKZ_COUNT" elif [ "$PLAN_NEEDS_DIAGRAM" -eq 0 ]; then echo "✓ 规划无架构图/流程图需求, 跳过" else echo "❌ 规划要求架构图/流程图但未生成" PASS=false fi [ -f 图表/图表引用.tex ] || touch 图表/图表引用.tex [ "$PASS" != true ] && echo "⛔ Output verification FAILED — must complete before ending" ``` ## 执行流程 ### 工作节点 0：恢复核验（断线重跑必读） ⛔ **当前环节可能由于断线/人工重跑被多次启动**。每一次启动前**务必**先扫描已有产物： ```bash echo "=== 工作区扫描 ===" HAS_DRAWIO=$(ls 图表/*.drawio 2>/dev/null | wc -l) HAS_TIKZ_TEX=$(ls 图表/tikz_*.tex 2>/dev/null | wc -l) HAS_TIKZ_PDF=$(ls 图表/tikz_*.pdf 2>/dev/null | wc -l) HAS_FIG_PDF_FROM_DRAWIO=$(ls 图表/fig_*.pdf 2>/dev/null | wc -l) echo " *.drawio: $HAS_DRAWIO, tikz_*.tex: $HAS_TIKZ_TEX, tikz_*.pdf: $HAS_TIKZ_PDF" echo " fig_*.pdf (含 drawio 导出): $HAS_FIG_PDF_FROM_DRAWIO" ``` **依据扫描结果决定行动**： | 运行状态 | 行动 | |---|---| | 规划要求的全部 drawio + tikz 都已产出（含 .drawio + 相应 .pdf） | **跳到 Phase 8 (latex_includes 核对)**，校验通过即完成 | | 部分已产出 | **只产出缺失的**（已有的避免重画） | | 啥都没有 | 从 Phase 1 启动 | ⛔ **铁律**：已有 `图表/*.drawio` / `图表/tikz_*.tex` / `图表/tikz_*.pdf` 避免重写。 ### 工作节点 1：Read existing state + DrawIO plan 1. Validate what already exists from the previous evidence-visualization step: ```bash echo "=== Existing figures ===" ls -la 图表/*.pdf 2>/dev/null | head -30 echo "" echo "=== Existing .drawio files ===" ls -la 图表/*.drawio 2>/dev/null echo "" echo "=== 图表引用.tex exists? ===" [ -f 图表/图表引用.tex ] && echo "YES" || echo "NO" ``` 2. Extract the DrawIO/TikZ plan from planning docs: ```bash # 自动选择规划文档（按存在性优先级）： # 问题分析.md（数模竞赛/科研流程） > 研究方案.md（开题报告） # > 论文规划.md（论文写作/课程报告） > 文献综述.md（文献综述，跳过） PLAN_DOC="" for f in 问题分析.md 研究方案.md 论文规划.md; do if [ -f "$f" ]; then PLAN_DOC="$f" break fi done echo "=== 使用规划文档: $PLAN_DOC ===" # 文献综述工作流不需要架构图，直接跳过 if [ -f 文献综述.md ] && [ -z "$PLAN_DOC" ]; then echo "✅ 文献综述工作流不需要架构图，已跳过" exit 0 fi # 如果没有任何规划文档，退化为"画 1 张 技术路线图 兜底" if [ -z "$PLAN_DOC" ]; then echo "⚠ 无规划文档，将只生成 技术路线图.png 兜底" PLAN_DOC="" fi echo "=== DrawIO plan from $PLAN_DOC ===" grep -A 50 'DrawIO' "$PLAN_DOC" 2>/dev/null | grep -E 'DrawIO-[0-9]|^\- \[ \] fig_(arch|er|flow|module|roadmap|pipeline|framework|index|gantt|network)' || echo "No DrawIO plan found in $PLAN_DOC" echo "" echo "=== TikZ plan ===" grep -E 'TikZ-[0-9]|模型架构|变量关系|因果路径|算法流程|几何示意' "$PLAN_DOC" 2>/dev/null || echo "No TikZ plan found" echo "" echo "=== AI Image failures (need DrawIO fallback) ===" # 读取前一步 evidence-visualization 持久化的 AI Image 状态 if [ -f 图表/_aiimg_status.txt ]; then AIIMG_STATUS=$(cat 图表/_aiimg_status.txt) echo "AI Image status: $AIIMG_STATUS" if [ "$AIIMG_STATUS" = "ALL_SUCCESS" ]; then echo "All AI Image figures succeeded — only generate DrawIO for figures NOT covered by AI Image" elif [ "$AIIMG_STATUS" = "SOME_FAILED" ]; then AIIMG_FAILED=$(cat 图表/_aiimg_failed.txt 2>/dev/null) echo "AI Image failures: $AIIMG_FAILED — generate DrawIO for these" elif [ "$AIIMG_STATUS" = "ALL_FAILED" ]; then echo "All AI Image attempts failed (API Key missing or network error) — generate DrawIO for ALL non-data figures" else echo "AI Image disabled — generate DrawIO for ALL non-data figures" fi else echo "No AI Image status file — generate DrawIO for ALL non-data figures (default)" fi echo "" # Determine language（注意：comp_apmcm_zh 是中文赛项，必须先排除） if grep -qi 'comp_apmcm_zh' "$PLAN_DOC" META_MODEL_AGENT.md 2>/dev/null; then DRAWIO_LANG="zh" elif grep -qi 'MCM\|ICM\|APMCM\|comp_mcm\|comp_apmcm\|comp_certcup_en\|comp_shuwei_en\|语言.*English\|Language.*English' "$PLAN_DOC" META_MODEL_AGENT.md 2>/dev/null; then DRAWIO_LANG="en" else DRAWIO_LANG="zh" fi echo "DrawIO language: $DRAWIO_LANG" ``` **⛔ 读完规划后，务必交付一个 DRAWIO PLAN CHECKLIST（后续环节对照用）：** 工作流类别决定数量： - **数模竞赛 / 科研过程**（有 问题分析.md）：按 DrawIO 清单全部产出（roadmap + flow_q1/q2/pipeline 等） - **开题报告**（有 研究方案.md）：**只产出 技术路线图**，其他 问题流程图_1/q2 避免画 - **课程论文/报告**（有 论文规划.md，无 问题分析.md）：按 论文规划.md 中 `## 架构图（drawio）规划` 段落列出的 fig_arch/fig_er/fig_flow_* 产出 - **论文写作**（有 论文规划.md，无 问题分析.md）：按 论文规划.md 列出的图产出 ``` DRAWIO PLAN CHECKLIST (from $PLAN_DOC): [ ] 1. 技术路线图 — 技术路线图 (DrawIO) [ ] 2. 问题流程图_1 — 问题一求解流程图 (DrawIO) [ ] 3. 问题流程图_2 — 问题二求解流程图 (DrawIO) [ ] 4. fig_pipeline — 数据处理 Pipeline (DrawIO) [ ] 5. tikz_architecture — 模型架构图 (TikZ, if planned) Total: N DrawIO + M TikZ ``` **每一条都务必在后续环节中产出。规划清单就是合同。** **⛔ DrawIO 图中全部文字务必与论文语言保持一致。** **⛔ 数模竞赛论文务必至少产出 1 张 DrawIO 技术路线图。其他 DrawIO 图按规划清单产出。** **⛔ 开题报告 / 文献综述 不画 问题流程图_1/q2 这些数模专用图。开题只画 技术路线图，文献综述不画。** **⛔ 若规划清单里有 N 条 DrawIO 图，当前环节结束时务必有 N 个 .drawio 文件和 N 个相应的 .pdf。缺一不可。** ### 工作节点 2：Read DrawIO rules **MANDATORY**: Consult the DrawIO rules prior to writing ANY .drawio XML: ```bash cat 工具/drawio_rules.md 2>/dev/null || cat skills/shared-scripts/drawio_rules.md ``` ### 工作节点 3：Produce .drawio XML files **⛔ CRITICAL: DrawIO XML 文件很大（200-500行），务必分段写入，防止交付截断导致空工具调用。** **无误写法（分 3 段写入）：** ```bash # 第 1 段：写文件头 + 前半部分节点 cat << 'XMLEOF' > 图表/技术路线图.drawio <mxfile> <diagram name="Page-1"> <mxGraphModel> <root> <mxCell id="0"/> <mxCell id="1" parent="0"/> <!-- 前半部分节点（顶部标题栏 + 左栏 + 前几个阶段） --> XMLEOF # 第 2 段：追加中间节点 cat << 'XMLEOF' >> 图表/技术路线图.drawio <!-- 中间部分节点（核心阶段 + 右栏方法） --> XMLEOF # 第 3 段：追加剩余节点 + 连线 + 闭合标签 cat << 'XMLEOF' >> 图表/技术路线图.drawio <!-- 连线和底部 --> </root> </mxGraphModel> </diagram> </mxfile> XMLEOF ``` **每段不超过 150 行。** 一张技术路线图分 3 段，一张过程图分 2-3 段。 **⛔ 避免用 Write 工具写大 XML——Write 工具的 content 参数也会被截断。用 Bash heredoc 分段追加最可靠。** 按规划清单逐条产出，每张图一个 `.drawio` 文件： **⛔ 配色与风格自由发挥原则：** - 依据论文主题自主选取柔和高级的配色方案，避免每一次都用默认学术蓝 - 不同子问题的过程图用不同配色，形成视觉区分 - 推荐风格：白底、灰阶边框和一个低饱和强调色；禁止装饰渐变与阴影 - 技术路线图：在三栏结构基础上优先采用黑白灰阶，通过边框粗细、虚实、留白和箭头形态建立层级；仅允许极少量低饱和强调色 - 求解过程图：按语义保留六边形、平行四边形、圆柱、菱形等形状；所有普通矩形和矩形容器必须为直角，禁止圆角矩形 - 布局可灵活：纵向、横向、L 形拐弯、泳道分区都可，依据内容选最合适的 - **关键约束不变**：三栏结构（技术路线图）、判定分支+并行+循环（过程图）、双行节点、html=1、无 shadow | 图类别 | 文件名示例 | 内容要点 | |--------|-----------|---------| | 技术路线图 | `技术路线图.drawio` | 按节点数量与依赖拓扑选择模板，保持三栏结构和节点居中；禁止随机选模板 | | 子问题求解过程图 | `问题流程图_1.drawio` | ⛔ 务必涵盖：(1) 判定分支（菱形+是/否）(2) 并行分叉 (3) 循环反馈箭头 (4) 节点双行。**避免画右侧工具/方法注释栏**（技术路线图才需） | | 数据处理 Pipeline | `fig_pipeline.drawio` | 横向多阶段、每阶段工具/方法标注 | | 概念框架图 | `fig_framework.drawio` | 理论模块分层展示，层间大箭头 | | 指标体系层次图 | `fig_index_hierarchy.drawio` | 目标层→准则层→指标层的树形结构 | | 模型选取决策树 | `fig_model_decision.drawio` | 从数据特征出发的分支判定 | | 甘特图/调度方案图 | `fig_gantt.drawio` | 横轴时间+纵轴工作项/资源 | | 网络拓扑/路线图 | `fig_network.drawio` | 节点+边的网络结构 | ⛔ 以下图类别**避免用 DrawIO**，用 TikZ 产出：模型架构图、变量关系图、算法过程图（带公式）、几何示意图。 **⛔ 完整 XML 示例**：产出前按节点数量和依赖拓扑选择一个模板参考 XML 结构，不得随机选择。当前有 4 个拓扑示例： - `example_roadmap_stats.drawio`（B：灰阶简版四阶段拓扑） - `example_roadmap_stats_warm.drawio`（B-warm：灰阶简版替代拓扑） - `example_roadmap_hex.drawio`（C：灰阶完整六阶段拓扑） - `example_roadmap_hex_cool.drawio`（C-cool：蓝色高对比，完整六阶段） **⛔ 产出技术路线图前务必实施：** ```bash echo "=== 按节点数量和依赖拓扑选择技术路线图模板（禁止随机）===" TEMPLATE=$(python3 -c "import random; print(random.choice(['B','B-warm','C','C-cool']))" 2>/dev/null || echo "C") echo "本次使用模板: $TEMPLATE" case "$TEMPLATE" in B) FILE=example_roadmap_stats.drawio ;; B-warm) FILE=example_roadmap_stats_warm.drawio ;; C) FILE=example_roadmap_hex.drawio ;; C-cool) FILE=example_roadmap_hex_cool.drawio ;; esac echo "--- 参考模板: $FILE ---" cat 工具/$FILE 2>/dev/null | head -80 echo "... (参考完整 XML 结构和配色后再生成 技术路线图.drawio)" ``` ⛔ **配色避免混搭**：选定模板后，整张图沿用该模板的配色方案，避免把不同模板的颜色混在一起。 **⛔ 产出求解过程图前务必实施：** ```bash echo "=== 读取求解流程图示例 ===" cat 工具/example_flow.drawio 2>/dev/null | head -50 echo "... (参考完整 XML 结构后再生成)" ``` **⛔ 每张图产出后立即校验文件出现：** ```bash [ -f 图表/技术路线图.drawio ] && echo "✅ 技术路线图.drawio created" || echo "❌ MISSING"