doc-atlas

---
name: doc-atlas
description: Turn one or more documents (PDF / Word / PPT / Excel / HTML / EPUB / Markdown…) into a single, polished, offline, self-contained HTML dashboard — a left fixed table-of-contents tree and right-side modular content (executive summary, big key-metric cards, logic/relationship diagrams, data charts, conflict comparison, chapter details). Use when the user has document files and wants to "distill / merge / visualize / make sense of / lay out / build a panel from" them. It highly distills the key points so the reader need not open the source, keeps every claim traceable back to file + page, and foregrounds the logic/relationship diagram as the centerpiece.
---

# 多格式文档 → 可视化信息面板（doc-atlas）

把一份或多份文档（PDF / Word / PPT / Excel / HTML / EPUB / Markdown…）**归一化为 Markdown 中间层 → 跨文件梳理合并成一个统一知识结构（model.json）→ 渲染成一个离线可开的单文件 `dashboard.html`**：左侧固定目录树，右侧按需出现的模块化内容（关键指标卡、核心要点、逻辑/关系图、数据图表、冲突对照、章节详情）。

**三条核心价值（一切取舍围绕它们）**：
1. **高度炼化**——读者看面板就够了，不必再翻原文；若做得杂乱无章，那还不如直接看 PDF。
2. **准确可溯**——零幻觉、每个数字/结论都能指回「哪个文件第几页」，不确定就诚实标注。
3. **逻辑图是主角**——把文档的核心逻辑/因果/关系做成醒目的大图，这是本工具最大的卖点。

**路径模型（重要）**：命令在**用户的文档文件夹里**运行（即当前工作目录 `cwd`，里面放着用户的 PDF/文档），**不要 `cd` 进 skill 目录**。脚本一律用绝对路径 `"$SKILL_DIR/scripts/..."` 调用；所有产物写到用户文件夹下的 `./doc-atlas-out/`。`SKILL_DIR` = 本 skill 的安装目录（即本 `SKILL.md` 所在目录），开工前设一次：

```bash
SKILL_DIR="$HOME/.claude/skills/doc-atlas"   # 本 skill 安装目录（按实际位置改）
OUT="./doc-atlas-out"                          # 产物目录，落在用户当前文件夹下
```

---

## 何时用本 skill

- 用户给了文档文件，并希望「梳理内容 / 生成面板 / 可视化总结 / 理清逻辑 / 多文件合并梳理」。
- 单文件也可用（跳过跨文件去重部分）；多文件时跨文件合并是核心价值。

**输出放哪**：默认建在用户当前文件夹下的 `./doc-atlas-out/`（里面含 `workspace/`、`model.json`、`dashboard.html`）；若用户指定了目录就沿用。

---

## 工作流总览（六步）

0. **扫描 + 一次性确认**：先扫描当前文件夹（只读无害），再**用一次 AskUserQuestion 同屏问两件事**——输出语言 + 纳入哪些文件。
1. **归一化**：每个被确认的文件 → `workspace/<name>/{content.md, assets/, meta.json}`（PDF 逐页文本带**页锚**、表格走结构化抽取保数值列；源未变自动跳过）。
2. **梳理合并（核心）**：通读、去重 / 识冲突 / 互补 / 判关系，重组成 `model.json`；写完做**完整性批判第二遍**并填 `distillation_report`（含数值字段）自检。
3. **事实核查（对抗式）**：对**对外/高风险**文档，派 subagent **回原件证伪**，修正 `❌/➖` 后再渲染（低风险单文件可内联自查）。
4. **渲染**：`model.json (+workspace) → dashboard.html`（单文件、零外链、断网可开；渲染前自动跑 `validate_model.py` 机器校验）。
5. **自检交付**：无头校验无报错、抽查溯源，并把炼化体检/核查结论讲给用户。

---

## 阶段零：扫描 + 一次性确认（语言与文件同屏问，减少往返）

### 0.1 先扫描目标文件夹（只读，无副作用）

```bash
python3 "$SKILL_DIR/scripts/scan_docs.py" .        # 或换成用户指定的文件夹路径
```

`scan_docs.py` 递归列出当前文件夹里所有候选文档（pdf / word / ppt / excel / html / epub / md / txt…），自动跳过隐藏目录、`.venv`、`node_modules`、`doc-atlas-out` 以及含 `SKILL.md` 的 skill 包目录。

### 0.2 一次 AskUserQuestion 同屏确认三件事（不要拆成多轮）

拿到清单后**必须与用户确认，不要擅自全量开跑**。把编号清单（文件名 / 类型 / 大小）呈现给用户，然后用**一次** AskUserQuestion 同时问：

1. **输出语言**：「你想要哪种语言的信息面板？ ① 中文 ② English ③ 跟随文档原语言 ④ 其他」
2. **文件取舍**：「以上文件是否都纳入梳理整合？要去掉哪些？有没有遗漏（比如埋在子目录里的）？」
3. **阅读目标**：「你最想从这批文档得到什么？ ① 决策参考（要做判断/取舍） ② 学习理解（搞懂讲了什么） ③ 风险审查（找坑/找问题） ④ 数据核对（提取关键数字） ⑤ 其他（自填）」

多文件时可在同一表单里追加第四问：它们大概什么关系（同主题不同版本 / 时间序列 / 总分 / 互相引用），有助于阶段二定合并策略。

**阅读目标记为 `READING_GOAL`，写进 `meta.reading_goal`，是整条流水线的"问题意识"**：
- 重要性分级（high/medium/low）按"对这个目标的重要性"打，不是按篇幅。
- `highlights` 选"回答这个目标最需要的 4–6 个数字"。
- `meta.one_liner`（定论）**直接回答这个目标**，不是泛泛总结。
- 用户跳过不答时缺省视为「学习理解」，不追问。

**语言选择记为 `UI_LANG`，贯穿全程**：
- `meta.ui_lang` = 用户选择；`meta.content_lang` = 文档主要语言（二者可不同）。
- **所有 AI 撰写的叙述性文案一律用 `UI_LANG`**（哪怕原文是另一种语言，也要在炼化时翻译/转写成 `UI_LANG`）。
- **事实保真不受影响**：数字、专有名词、逐字引用（quotes）保留原文，可在 `UI_LANG` 里补一句释义；溯源角标（文件名/页码）原样。
- 用户没明确表态时，缺省 = 跟随文档主要语言。

**等用户确认后**，用确认过的文件清单进入阶段一。

---

## 阶段一：归一化为 Markdown 中间层

### 1.0 环境检查与按需安装（首次使用，必须先征得用户同意）

归一化需要 markitdown + pymupdf（装在 `.venv` 里，约 290MB）。**先静默检查是否已就绪**：

```bash
VENV_PY="$SKILL_DIR/.venv/bin/python"
if [ -x "$VENV_PY" ] && "$VENV_PY" -c "import markitdown, fitz" 2>/dev/null; then
  echo READY
else
  echo NEED_INSTALL
fi
```

- 输出 `READY` → 环境已装好，直接进入 1.1，**不要重复安装**。
- 输出 `NEED_INSTALL` → **停下来，向用户说明并征求同意，绝不擅自安装**：
  > 首次使用需要安装文档解析依赖（markitdown + PyMuPDF，约 290MB，1–2 分钟，装到 `$SKILL_DIR/.venv`）。是否现在安装？
  - **用户同意** → 跑 `bash "$SKILL_DIR/scripts/bootstrap.sh"`，装完再继续 1.1。
  - **用户拒绝** → **不安装、也不继续**。明确告诉用户：没有这些依赖就无法解析文档，本次到此为止，等愿意安装时再来。不要尝试绕过或用系统 python 硬跑（markitdown 装不进系统 3.9）。

### 1.1 逐个文件归一化

对**每个被确认的**输入文件跑归一化（脚本用绝对路径调，人留在用户文件夹里）。**必须按确认清单顺序传 `--file-id f1/f2/...`**——阶段二 `model.json` 的 `files[].id` 要与之一致，`validate_model.py` 靠这条链做页码越界核查：

```bash
"$VENV_PY" "$SKILL_DIR/scripts/normalize.py" "输入文件.pdf" --out "$OUT/workspace/" --file-id f1
# 产出： $OUT/workspace/<name>/{content.md, assets/, meta.json}
# 源文件未变时自动跳过复用（--force 强制重跑）
```

三件套各司其职，缺一不可：
- `content.md` — 阶段二的唯一阅读对象。**PDF 走 PyMuPDF 逐页文本，每页前有页锚 `<!-- [doc-atlas] p.N -->`——写 SourceRef.page 时直接读锚，不许猜**；表格另按行×列结构化抽取，追加在文末「结构化抽取的表格」一节（保住数值列）。非 PDF 由 markitdown 转换（无页码概念，用 `loc` 定位）。
- `assets/` — 用 PyMuPDF 等额外提取的有信息量图片（图表 / 流程图 / 示意图），供 model 的 `image` block 引用。
- `meta.json` — `page_map`（页→偏移/首行）、标题索引、文件名、页数、字数、文档类型、日期（`date_source` 标注来源：`content` 可信 / `mtime` 兜底不可作权威性依据）、`tables`（表格登记：页码+行列数+置信度）、`table_extraction`（整体表格抽取状态），是 `SourceRef` 程序侧核查的依据。

**表格保真很关键**：很多"看似原文没写"的数值，其实是 markitdown 把表格列打乱/丢列造成的。`normalize.py` 用 `page.find_tables()` 把表格重抽成二维 Markdown 表并登记置信度——阶段二据此判断「原文确实没有」还是「我们没抽好、要回看 PDF 原图」（见阶段二纪律）。

**扫描版 PDF 的 OCR 回退**：当 PDF 是扫描件、markitdown 提不出文字层时，`normalize.py` 会自动走 OCR 回退把图片页转成文本（OCR 结果置信度较低，阶段二引用时倾向标注「（待核实）」）。

> 用 `$VENV_PY` 做归一化（markitdown/pymupdf 只装在 venv 里）；render / validate / selfcheck 用系统 `python3`（stdlib only，见阶段三、四、五）。两者不要混用。

---

## 阶段二：信息梳理与多文件整合（核心，AI 亲自做）

通读 `$OUT/workspace/*/content.md` 与各自 `meta.json`，**重新组织内容，而不是逐文件摘要**。详细方法见 `references/merge-and-structure.md`，要点：

- **去重**：同一概念/事实在多个文件出现 → 合并为一个节点，`sources` 标注所有出处。
- **识冲突**：同一事实说法不一致（数字/日期/结论）→ 不要静默选一个，写进 `conflicts[]`，列出各方 `positions` 与出处，给 `resolution` 和 `confidence`。
- **互补**：A 讲概述、B 讲细节 → 组织成同一章节的不同层级，而非两个并列章节。
- **判文件关系**：同主题不同版本？时间序列？总分？互相引用？据此定合并策略；多文件时填 `file_relations.mermaid`。

把合并结果写成唯一中间产物 **`$OUT/model.json`**（顶层 IR）。字段语义、调色板与完整示例见 `references/model-schema.md`，机器约束见 `schema/model.schema.json`：

- 必填：`meta`、`files`、`outline`、`chapters`；其余（`highlights`/`conflicts`/`keypoints`/`diagrams`/`charts`/`quotes`/`file_relations`/`distillation_report`）**按需出现**——给了才渲染，这就是右侧模块化的自由度。
- `outline` 是合并后的统一主题树（`1` / `1.1` / `1.2.1`），不是按文件罗列；每个一级 `outline` 节点对应一个 `chapters[]`。
- `chapters[].blocks` 从调色板自由编排：`paragraph` / `callout` / `keypoints` / `metric` / `quote` / `diagram`(Mermaid) / `chart`(Chart.js) / `table` / `image` / `subsections`。某章节有没有逻辑图/图表，全看它含不含对应 block。
- 每个 `SourceRef` 至少给 `page` 或 `loc` 之一，`file_id` 必须匹配某个 `files[].id`。

### 2.1 三层阅读模型（炼化 = 让人一眼看懂）

让每份 model.json 天然分三层，模板按层级默认展开/折叠，这样读者「10 秒抓主线、细节按需展开」：

| 层级 | 内容 | model.json 落点 | 默认呈现 |
|---|---|---|---|
| **L1 概览** | 一句话定论 + ≤5 句执行摘要 + 4–6 个核心数字 | `meta.one_liner` + `meta.executive_summary` + `highlights[]` | 首屏直接显示 |
| **L2 要点** | high/medium 要点、核心逻辑图、核心图表 | `keypoints[]` / `diagrams[]` / `charts[]` | 默认显示 |
| **L3 细节** | 章节正文、参数表、工况表、质保表 | `chapters[].blocks` | 章节体默认折叠，点开才看 |

- **`meta.one_liner`（定论，强烈建议给）**：面板首屏的 The Bottom Line 大字条。写法：直接回答
  `reading_goal`，把核心结论 + 最关键数字 + 转折压进一句话。缺省时面板回退用 `executive_summary[0]`。

- **`highlights[]`（顶层，强烈建议给）**：把全篇 4–6 个最关键数字做成首屏大号指标卡（如「8 小时 / 纯电驻车」「<3% / 占整车重」「22 万 / 10 年累计节省」）。这是"极少内容获取主要"的最直接实现。
- 章节内也可用 `metric` block 给局部关键数字一个大字号出口。
- 关键数字不要只埋在段落里——能抽成 `highlights` / `metric` / `chart` 的就抽出来。

### 2.2 逻辑/关系图是主角（核心卖点，务必做足）

- 通读后先问自己：**这份文档集的核心逻辑是什么？**（因果链 / 流程 / 决策树 / 组织关系 / 价值传导）把它做成 `diagrams[]` 里一张**主图**——清晰、信息量足、能讲清主线。宁可一张扎实的大图，也别堆十张零碎小图。
- 模板会把 `diagrams[]` / `file_relations` **整行大尺寸渲染并支持点击放大**，所以图要经得起放大看：节点命名清楚、箭头有动词标签、层次分明。
- 凡内容里出现**关系或顺序**就考虑画图（`flowchart` 流程/因果、`mindmap` 概念分解、`sequenceDiagram` 时序）；只是几条并列事实则用 `keypoints`，别硬画。
- 多文件时 `file_relations.mermaid` 画文件之间的关系（版本迭代/引用/互补）；内容主题关系进 `diagrams[]`。

### 2.3 图表语义不要丢

- **区间数据用区间表达**：如噪音「≥70 / <50」别画成定值 70/50（会误导）；用区间/堆叠，或在标签标「≥ / <」。
- **不同口径的并列柱要标清**：如「一次性投资 vs 10 年累计」并列时，标题/坐标轴/caption 必须醒目标注口径，避免被误读为同期可比。

### 2.4 炼化纪律（让"高度炼化"看得见、靠得住）

**"高度炼化" ≠ "变短"**，它要同时满足：①跨文件/跨章去重；②升维归纳（从"原文怎么说"升到"结论/因果/对比"）；③关键信息（数字/标准号/参数/前置条件）零丢失且溯源；④重要性分级反映"对 `reading_goal` 的重要性"。

- **概念清单要落盘（`$OUT/workspace/_concepts.jsonl`）**：阶段二边读边维护的"概念→出处"表不要只留在草稿里，写成 JSONL 正式中间产物，每行一条：
  `{"concept": "...", "statement": "...", "file_id": "f1", "page": 3, "loc": null, "disposition": "kept|merged|dropped", "target": "1.2"}`
  （`disposition` 记收/并/弃，`target` 记落到哪个 outline 节点/keypoint；弃收的写明原因。）
  好处：`claims_total` 等体检数字从清单**数出来**而不是拍出来；核查 agent 可审计"收了什么、弃了什么"；超长文档分批读可断点续作。多文件/长文任务**必做**，单短文件可省。

- **完整性批判第二遍（必做）**：第一遍写完 model.json 后，**重读 source 自问**："哪个**重要数字 / 前置条件 / 结论**原文有、model 却没有？" 把找到的补回去，循环到"再读一遍也挑不出新的"。
- **填 `distillation_report` 并自检阈值**（顶层可选字段，强烈建议给，交付时讲给用户）。**数值字段必须给全**（`sections_total/sections_mapped`、`claims_total/claims_with_source_count`、`todo_count/data_points`、`compression_ratio_x`），`validate_model.py` 据此机器执行纪律，展示文案字段可另给：
  - 章节覆盖 **必须 = 100%**（`sections_mapped == sections_total`），缺章回去补。
  - 待核实占比 `todo_count/data_points > 10%` → **先别交付**（校验器直接拦）：多半是表格数值列没抽好（看 `meta.tables` / `table_extraction`），回查 PDF 原图能补的补回来。
  - 溯源率 `claims_with_source_count < claims_total` → 有无源声明，要么补源要么删。
  - `compression_ratio_x` 落在 ~3 到 ~10 才算"既炼又不漏"；接近 1 = 只是搬运。
- **"待核实" 只用于「原文确实没写」**，**严禁用于「本工具没抽出来」**。后者要回查原件（`meta.json` 的页码 / `assets/` 原图 / 用 Read 工具 pages 参数读原 PDF）补回真值；分不清就当成"要回查"，不要默默标"待核实"后被当成"原文没有"。

**纪律**：一切结论溯源、不编造；PDF 的 `SourceRef.page` **必须来自 content.md 里的页锚**（`<!-- [doc-atlas] p.N -->`），不许凭印象写；超长文档**分批读**再汇总，别漏后半部分。写完**必须跑机器校验**（结构 / 交叉引用 / 页码越界 / 炼化阈值），全绿再进入阶段三：

```bash
python3 "$SKILL_DIR/scripts/validate_model.py" "$OUT/model.json" --workspace "$OUT/workspace/"
# 退出码 2=结构/引用错误必须修；1=炼化阈值未达标（按纪律先别交付）；0=通过
```

---

## 阶段二·五：事实核查（对抗式，回原件证伪）

draft 出 `model.json` 后、渲染之前，**加一道独立核查闸**——目标是**找错**，不是确认。按风险/规模分档，别对所有任务都开多 agent：

| 场景 | 核查方式 |
|---|---|
| 单文件、< ~15 页、低风险 | 主 AI **内联自查**（完整性批判第二遍即可，省 token） |
| 单文件、销售/合同/对外/高风险材料 | **1 个 subagent 专职核查** |
| 多文件 / 长文 / 有冲突表 | **按章节 fan-out 多个 subagent 并行核查 + 1 个汇总**，重点查 `conflicts[]` 完整性、跨文件数字一致性 |

给核查 agent 的指令要点：
- **对抗框架**："逐条挑 model.json 里的数字/事实/结论，**默认它可能错**，去原文找反证。"
- **核查清单**：每条 high/medium 的数字与结论，判定 `✅准确 / ⚠️偏差 / ❌错误或幻觉 / ➖遗漏`，并附原文出处。重点查三类：① 幻觉（原文没有却写了）② 遗漏（原文有却没收/误标待核实）③ **派生数字验算**（亲手重算节省额/CO₂/续航小时等，核口径自洽）。
- **关键纪律：核查 agent 必须能读原始文件（Read 工具 pages 参数 / 原图），不能只读 `content.md`**——因为 content.md 可能本身丢了表格数值列，只读它会和阶段二犯同样的盲区。

**核查结果落盘（产物契约）**：核查记录写成 `$OUT/factcheck.json`——一个数组，每条
`{"claim": "...", "verdict": "ok|deviation|error|missing", "source": {"file_id": "f2", "page": 12}, "note": "怎么处理的"}`
（与 `distillation_report.fact_check_items` 同构，`verdict` 对应 ✅/⚠️/❌/➖）。

**核查结果回流**：
- `❌ 错误 / 幻觉` → **必须改**，改完重渲染。
- `➖ 遗漏（原文确有）` → 补进 model.json。
- `⚠️ 偏差 / 口径问题` → 修正，或在文案/`callout` 里显式标注口径。
- 把核查摘要写进 `distillation_report.fact_check`（如"已核 23 条、修正 3 条、补回 2 条遗漏"），
  并把 `factcheck.json` 内容抄进 `distillation_report.fact_check_items`——面板附录会渲染成可展开的核查明细表，是"为什么可以信这份简报"的证据；阶段五讲给用户。

---

## 阶段三：渲染单文件面板

用**系统 python3**（stdlib only）渲染：

```bash
python3 "$SKILL_DIR/scripts/render_dashboard.py" "$OUT/model.json" "$OUT/dashboard.html" \
  --workspace "$OUT/workspace/" --self-check
```

- 渲染前**自动调用 `validate_model.py`**（结构/交叉引用/页码越界/炼化阈值），不过关直接退出码 2——先修 model.json，别用 `--skip-validate` 绕。
- 输出是**单文件** `dashboard.html`，**完全自包含、零外链、断网可开**：CSS/JS 内联，图片替换为 `data:` URI 内嵌，**Chart.js 与 Mermaid 也整体内联**（体积约 +3.5MB，是"离线可用 > 体积小"的既定取舍；确需外链瘦身可加 `--cdn`，但断网时图与图表只剩降级显示）。
- 图片 `src` 先按绝对路径找，找不到再按 `workspace/src` 找；缺图不报错，渲染占位并在 stderr 警告。
- 退出码 0 = 成功；非 0 = 失败并在 stderr 说明。加了 `--self-check` 会渲染后自动调用 selfcheck（即可省略阶段四的手动调用）。
- 默认 `--template` = `scripts/../templates/dashboard.html`，默认 `--workspace` = `model.json` 所在目录；上面显式写 `--workspace` 更稳。

---

## 阶段四 / 五：自检与交付

若阶段三没带 `--self-check`，单独跑：

```bash
python3 "$SKILL_DIR/scripts/selfcheck.py" "$OUT/dashboard.html"   # 加 --json 输出机器可读报告
```

- playwright 无头加载，捕获 console error / pageerror，统计 Mermaid 渲染出的 svg 数与 Chart canvas 数，校验注入 JSON 可解析、关键 section 存在；有错误则退出码非 0。
- 当前 python 缺 playwright 时，脚本会**自动切换到 skill `.venv` 的 python** 重跑（bootstrap 用 `--with-selfcheck` 装过即可用）。
- 浏览器获取顺序：先 `chromium.launch()`，失败再 `channel="chrome"`，再失败降级为静态解析检查并 warn。

**人工抽查**（自检脚本不能替代）：树节点引用的来源页码在 `meta.json` 里真实存在；要点里的数字与原文一致；去重没把不同概念误合并。

**交付**：把 `$OUT/dashboard.html` 给用户，并用 3–5 句话说明：讲了什么、几个文件、最关键的结论/冲突，以及**炼化体检与核查结论**（章节覆盖率、待核实占比、已核/修正了几条）——让用户看得见"为什么可以信这份面板、而不必回去翻 PDF"。

---

## 约束

- **不编造**：所有结论必须能溯源到某个文件的页码/位置；做不到就别写。
- **"待核实" 严格界定**：只用于「原文确实未写 / 来自 OCR / 多源冲突未定」；**不得**用于「本工具没抽出来」——后者必须回查原件补回真值。
- **分批**：单文件 ~100 页以上或 `content.md` 超长时分批读取再汇总，避免遗漏后半部分。
- **语言策略**：`meta.ui_lang`（界面 + AI 撰写文案）跟随**用户在阶段零选定的语言**；`meta.content_lang` 跟随文档主要语言；逐字 `quotes` 保留原文。
- 禁用 localStorage；输出面板**零外链、零网络请求**（Chart.js / Mermaid 已内联；仅 `--cdn` 模式例外，且须明示用户断网后果）。
- **界面风格固定为「纸本简报」皮肤**：暖米纸 + 蓝色强调（重点/风险保留朱红）+ 无衬线正文 + 日读；信息结构固定为一条主线——定论(one_liner) → 编号简报区（指标/摘要/逻辑图/图表/要点/冲突）→ 章节详情（折叠）→ 附录（源文件/关系/体检，降调）。由 `templates/dashboard.html` 决定；AI 不改皮肤、不提供外观切换面板。

---

## 参考文件索引

- `references/merge-and-structure.md` — 阶段二跨文件去重/冲突/互补/文件关系判定、三层阅读模型、逻辑图主角化、炼化体检与核查的操作指南。
- `references/model-schema.md` — `model.json` 的人类可读说明与完整示例（含 Block 调色板、`highlights`、`metric`、`distillation_report` 用法）。
- `schema/model.schema.json` — `model.json` 的 JSON Schema（draft-07）。
- `scripts/scan_docs.py` — 阶段零：扫描目标文件夹列出候选文档（stdlib only，供与用户确认）。
- `scripts/bootstrap.sh` — 建 `.venv` 并安装 markitdown + pymupdf（优先 uv，无 uv 回退 `python3 -m venv`；`--with-selfcheck` 顺带装 playwright + chromium）。
- `scripts/normalize.py` — 阶段一：单文件 → `workspace/<name>/{content.md, assets/, meta.json}`（PDF 逐页页锚 + 表格结构化抽取 + 扫描件 OCR 回退；增量跳过）。
- `scripts/validate_model.py` — 阶段二末尾 / 渲染前的机器校验闸：结构、交叉引用、页码越界、炼化阈值（stdlib only）。
- `scripts/render_dashboard.py` — 阶段三：`model.json (+workspace)` → 单文件 `dashboard.html`（stdlib only，图片 base64 内嵌，Chart.js/Mermaid 内联）。
- `scripts/selfcheck.py` — 阶段五：playwright 无头校验 `dashboard.html`（缺 playwright 自动切 `.venv` python，再不行降级静态检查）。
- `templates/dashboard.html` — 固定单文件前端模板（内联 CSS/JS + `__DASHBOARD_DATA__` / `__VENDOR_JS__` 注入位）。
- `templates/vendor/` — 内联用的 Chart.js / Mermaid 副本（版本与许可见其 README）。