concept-atlas-dense-explain 0.10.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Concept Atlas contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# concept-atlas-dense-explain
+
+Compile semantic MDX into a standalone, interactive Concept Atlas HTML page. The
+same workflow ships as an AI-agent skill, so an agent can generate, validate and
+render a "dense explainer" without hand-writing any layout.
+
+Two page shells share one component library:
+
+- `atlas` — concept graph with node navigation (`ExplainPage` → `ConceptGraph` → `ConceptNode`)
+- `scroll` — continuous document with an auto-built table of contents
+
+## CLI
+
+```bash
+# Learn the components from a real, compilable reference
+npx concept-atlas-dense-explain guide --mode atlas -o atlas-guide.mdx
+npx concept-atlas-dense-explain guide --mode scroll -o scroll-guide.mdx
+
+# Scaffold a document skeleton
+npx concept-atlas-dense-explain create topic.mdx --mode atlas
+
+# Validate structure before building
+npx concept-atlas-dense-explain validate topic.mdx --mode atlas
+
+# Compile to a standalone HTML file beside the MDX
+npx concept-atlas-dense-explain topic.mdx --mode atlas
+```
+
+`guide` and `create` refuse to overwrite an existing file unless `--force` is
+passed. Use `-o` to choose the output path (a directory when passing several
+inputs). Validation errors abort the build; `--no-validate` forces a knowingly
+broken build.
+
+Mermaid loads from a CDN at runtime by default (fast builds, needs network);
+`--inline-mermaid` bakes it into the HTML for a fully offline single file, and
+`--mermaid-cdn` overrides the CDN URL. Appearance defaults can be baked with
+`--skin`, `--default-mode` and `--style`; readers can still switch in the UI.
+
+Run `npx concept-atlas-dense-explain help` for the full flag list.
+
+## Links
+
+- Repository: https://github.com/wurenrumian/concept-atlas
+- Framework guide: [`docs/FRAMEWORK.md`](https://github.com/wurenrumian/concept-atlas/blob/main/docs/FRAMEWORK.md)
+- Usage recipes: [`docs/USAGE.md`](https://github.com/wurenrumian/concept-atlas/blob/main/docs/USAGE.md)
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -114,14 +114,14 @@ if (command === 'guide') {
     console.error(`Refusing to overwrite ${output}; pass --force to replace it.`);
     process.exit(1);
   }
-  const source = path.join(templateRoot, 'guides', `${mode}-guide.mdx`);
+  const source = path.join(templateRoot, 'references', `${mode}-guide.mdx`);
   if (!(await exists(source))) {
     console.error(`Guide for mode "${mode}" is missing from the package.`);
     process.exit(1);
   }
   await mkdir(path.dirname(output), { recursive: true });
   await copyFile(source, output);
-  const assetsSource = path.join(templateRoot, 'guides', 'assets');
+  const assetsSource = path.join(templateRoot, 'references', 'assets');
   const assetsTarget = path.join(path.dirname(output), 'assets');
   if (await exists(assetsSource) && path.resolve(assetsSource) !== path.resolve(assetsTarget) && (args.includes('--force') || !(await exists(assetsTarget)))) {
     await cp(assetsSource, assetsTarget, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concept-atlas-dense-explain",
-  "version": "0.10.0",
+  "version": "1.1.0",
   "description": "Portable dense-explanation skill and MDX concept atlas template",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
   "files": [
     "bin",
     "template",
-    "skill"
+    "packaged-skill"
   ],
   "dependencies": {
     "@mdx-js/rollup": "^3.0.1",
@@ -34,6 +34,18 @@
     "dense-explain",
     "concept-map"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wurenrumian/concept-atlas.git",
+    "directory": "packages/concept-atlas-dense-explain"
+  },
+  "homepage": "https://github.com/wurenrumian/concept-atlas#readme",
+  "bugs": {
+    "url": "https://github.com/wurenrumian/concept-atlas/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "publishConfig": {
     "access": "public"
   },

package/{skill → packaged-skill}/SKILL.md

@@ -1,21 +1,29 @@
 ---
 name: concept-atlas-dense-explain
-description: Turn a topic or an existing document into an interactive Concept Atlas explainer. Generate AI-editable MDX with the concept-atlas-dense-explain npm CLI, validate its structure, and compile standalone HTML with concept nodes, relation graphs, math (KaTeX), charts, figures, citations, and reading aids. Use when a technical explanation, concept map, layered knowledge page, dense explainer, or interactive teaching page is requested.
+description: Turn a topic or an existing document into an interactive Concept Atlas explainer. Generate AI-editable MDX with the concept-atlas-dense-explain CLI, validate its structure, and compile standalone HTML with concept nodes, relation graphs, math (KaTeX), charts, figures, citations, and reading aids. Use when a technical explanation, concept map, layered knowledge page, dense explainer, or interactive teaching page is requested.
 ---
 
 # Concept Atlas Dense Explain
 
-Drive everything through the `concept-atlas-dense-explain` npm CLI. This skill is intentionally lightweight: do not copy implementation files from the skill directory or recreate the React/Vite app. If a command name is unclear, run `npx concept-atlas-dense-explain help`. If the user only wants the prompt/methodology and not files, still choose a shell and emit valid MDX; the CLI is needed only to compile.
+Drive everything through the `concept-atlas-dense-explain` CLI, always via `npx`. Everything you need is in this file and the bundled `references/`; do not read the framework repository or installed package files, do not copy implementation files from the skill directory, and do not recreate the React/Vite app. If a command name is unclear, run `npx concept-atlas-dense-explain help`. If the user only wants the prompt/methodology and not files, still choose a shell and emit valid MDX; the CLI is needed only to validate and compile.
+
+## Running the CLI
+
+Always invoke the CLI through `npx`, from any directory:
+
+```bash
+npx concept-atlas-dense-explain <args>
+```
+
+This is the only runner — there is nothing to look for. Do not search for a local binary, a repository checkout, or an installed copy, and do not run the framework's own `npm` scripts. The first call downloads the package from the npm registry; say so once, then continue.
 
 ## Workflow
 
 1. Choose one page shell: `atlas` (concept graph with node navigation) or `scroll` (continuous document). Recommend `atlas` when the reader drills into concepts or follows relations, `scroll` for linear argument, tutorials, and reports. The library is shared. If an `.mdx` already exists, detect its shell and work with it.
-2. **Learn the components from the canonical guide before authoring.** Generate it for the chosen shell and read it:
-   ```bash
-   npx concept-atlas-dense-explain guide --mode atlas -o ./concept-atlas-atlas-guide.mdx
-   npx concept-atlas-dense-explain guide --mode scroll -o ./concept-atlas-scroll-guide.mdx
-   ```
-   It is real, compilable MDX showing that shell's components and their exact props; search it for a component name instead of guessing. Delete it when done.
+2. **Learn the components from the bundled reference before authoring.** The only reference you need is the guide that ships with this skill:
+   - `references/atlas-guide.mdx` (atlas) or `references/scroll-guide.mdx` (scroll)
+   It is real, compilable MDX showing that shell's components and their exact props; search it for a component name instead of guessing, and do not look for component documentation anywhere else. Do not run `guide` for this.
+   Run `npx concept-atlas-dense-explain guide --mode <mode> -o <file>` only when you specifically need a project-local copy to compile beside the page, and delete that copy when done.
 3. Start from a skeleton when useful: `npx concept-atlas-dense-explain create <file>.mdx --mode atlas|scroll`. `create` and `guide` refuse to overwrite an existing file unless `--force` is passed.
 4. Write the semantic MDX into the user's `.mdx` file (see Authoring rules).
 5. Validate before rendering:
@@ -70,4 +78,4 @@ Drive everything through the `concept-atlas-dense-explain` npm CLI. This skill i
 - Every node has `title` + `summary`; every `Relation` has a `label`.
 - The HTML file exists at the reported path.
 
-If the CLI or npm registry is unavailable, report the blocker instead of copying the implementation into the skill.
+If `npx` cannot reach the registry, report the blocker. Never copy implementation files into the skill directory.

package/{template/guides → packaged-skill/references}/scroll-guide.mdx

@@ -100,6 +100,38 @@ npm run dev`}</CodeBlock>
     <RelationMap title="关系速览" items={[{from:'MDX',type:'produces',to:'Graph',note:'生成关系图'},{from:'Node',type:'uses',to:'Mermaid',note:'展示局部流程'}]} />
   </ScrollSection>
 
+  <ScrollSection title="附录：大图的框内适配与放大阅读">
+    <ScrollProse>较大的流程图会被等比收进框内，而不是画出边框。点击图面或标题栏的「放大阅读」可以打开全屏视图，用滚轮缩放、拖拽平移、Esc 关闭。</ScrollProse>
+    <Mermaid title="图谱生成管线" width="100%" height="360px" chart={`flowchart TD
+  S[MDX 源文件] --> P[解析与校验]
+  P --> G[概念图谱]
+  P --> F[图表与公式]
+  G --> D[节点探索]
+  G --> R[关系图谱]
+  D --> M[Mermaid 局部流程图]
+  R --> M
+  F --> M
+  M --> Z[框内自适应缩放]
+  Z --> O[点击放大阅读]
+  O --> W[拖拽平移]
+  O --> K[滚轮缩放]
+  O --> E[Esc 关闭]
+  style S fill:#172554,stroke:#38bdf8,color:#e0f2fe
+  style Z fill:#14532d,stroke:#34d399,color:#ecfdf5
+  style O fill:#78350f,stroke:#fbbf24,color:#fffbeb`} />
+    <ScrollGrid columns="2">
+      <Mermaid title="窄栏中的纵向长图" width="100%" height="220px" chart={`flowchart TD
+  A[读取] --> B[解析]
+  B --> C[建模]
+  C --> D[渲染]
+  D --> E[校验]
+  E --> F[发布]
+  F --> G[归档]
+  G --> H[复盘]`} />
+      <RelationPath title="阅读路径" steps={[{level:'L0',node:'总览',note:'建立直觉',tone:'info'},{level:'L1',node:'机制',note:'理解过程',tone:'success'},{level:'L2',node:'边界',note:'检查反例',tone:'warn'}]} />
+    </ScrollGrid>
+  </ScrollSection>
+
   <ScrollSection title="参考文献">
     <References title="本页引用" items={[{id:'tufte1983',authors:'Tufte, E. R.',year:'1983',title:'The Visual Display of Quantitative Information',source:'Graphics Press',note:'关于以图形压缩与呈现证据的经典论述。'}]} />
   </ScrollSection>

package/template/index.html

@@ -1,42 +1,42 @@
-<!doctype html>
-<html lang="zh-CN">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Ctext y='.9em' font-size='90'%3E📃%3C/text%3E%3C/svg%3E" />
-    <title>Concept Atlas · 概念缩放式知识图谱</title>
-    <script>
-      (function () {
-        var doc = document.documentElement;
-        var stored = null;
-        try { stored = JSON.parse(localStorage.getItem('concept_atlas_appearance') || 'null'); } catch (e) {}
-        var legacy = localStorage.getItem('concept_atlas_theme');
-        // Placeholders are replaced at build time when --skin/--default-mode
-        // (or CONCEPT_ATLAS_* env vars) are configured; otherwise the runtime
-        // fallbacks below keep the carrier defaults.
-        var skin = '__ATLAS_DEFAULT_SKIN__';
-        if (/^__.+__$/.test(skin)) skin = 'aurora';
-        var mode = '__ATLAS_DEFAULT_MODE__';
-        if (/^__.+__$/.test(mode)) mode = 'light';
-        var style = '__ATLAS_DEFAULT_STYLE__';
-        if (/^__.+__$/.test(style)) style = 'manuscript';
-        if (stored && (stored.mode === 'light' || stored.mode === 'dark')) {
-          mode = stored.mode;
-        } else if (mode !== 'light' && mode !== 'dark') {
-          mode = legacy === 'light' || legacy === 'dark' ? legacy : 'light';
-        }
-        doc.setAttribute('data-skin', stored && stored.skin ? stored.skin : skin);
-        doc.setAttribute('data-theme', mode);
-        doc.setAttribute('data-style', stored && stored.style ? stored.style : style);
-      })();
-    </script>
-    <!-- Google Fonts for Academic / Editorial Knowledge style -->
-    <link rel="preconnect" href="https://fonts.googleapis.com">
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-    <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;700&family=Lora:ital,wght@0,500;0,600;0,700;1,400&family=Plus+Jakarta+Sans:wght@400;500;600;700;800&family=Noto+Serif+SC:wght@500;600;700;900&display=swap" rel="stylesheet">
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.jsx"></script>
-  </body>
-</html>
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Ctext y='.9em' font-size='90'%3E📃%3C/text%3E%3C/svg%3E" />
+    <title>Concept Atlas · 概念缩放式知识图谱</title>
+    <script>
+      (function () {
+        var doc = document.documentElement;
+        var stored = null;
+        try { stored = JSON.parse(localStorage.getItem('concept_atlas_appearance') || 'null'); } catch (e) {}
+        var legacy = localStorage.getItem('concept_atlas_theme');
+        // Placeholders are replaced at build time when --skin/--default-mode
+        // (or CONCEPT_ATLAS_* env vars) are configured; otherwise the runtime
+        // fallbacks below keep the carrier defaults.
+        var skin = '__ATLAS_DEFAULT_SKIN__';
+        if (/^__.+__$/.test(skin)) skin = 'aurora';
+        var mode = '__ATLAS_DEFAULT_MODE__';
+        if (/^__.+__$/.test(mode)) mode = 'light';
+        var style = '__ATLAS_DEFAULT_STYLE__';
+        if (/^__.+__$/.test(style)) style = 'manuscript';
+        if (stored && (stored.mode === 'light' || stored.mode === 'dark')) {
+          mode = stored.mode;
+        } else if (mode !== 'light' && mode !== 'dark') {
+          mode = legacy === 'light' || legacy === 'dark' ? legacy : 'light';
+        }
+        doc.setAttribute('data-skin', stored && stored.skin ? stored.skin : skin);
+        doc.setAttribute('data-theme', mode);
+        doc.setAttribute('data-style', stored && stored.style ? stored.style : style);
+      })();
+    </script>
+    <!-- Google Fonts for Academic / Editorial Knowledge style -->
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;700&family=Lora:ital,wght@0,500;0,600;0,700;1,400&family=Plus+Jakarta+Sans:wght@400;500;600;700;800&family=Noto+Serif+SC:wght@500;600;700;900&display=swap" rel="stylesheet">
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/template/package.json

@@ -1,22 +1,5 @@
-{
-  "name": "my-concept-atlas",
-  "private": true,
-  "version": "0.1.0",
-  "type": "module",
-  "scripts": { "dev": "vite", "validate": "node scripts/validate-content.mjs", "build": "npm run validate && node scripts/build.mjs", "clean:temp": "node scripts/clean-temp.mjs" },
-  "dependencies": {
-    "@mdx-js/rollup": "^3.0.1",
-    "clsx": "^2.1.1",
-    "d3": "^7.9.0",
-    "katex": "^0.16.47",
-    "lucide-react": "^0.475.0",
-    "mermaid": "^11.17.2",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1"
-  },
-  "devDependencies": {
-    "@vitejs/plugin-react": "^4.3.4",
-    "vite": "^5.4.14",
-    "vite-plugin-singlefile": "^2.1.0"
-  }
-}
+{
+  "name": "my-concept-atlas",
+  "private": true,
+  "type": "module"
+}

package/template/references/assets/sample-diagram.svg

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 240" role="img" aria-label="Concept zoom levels">
+  <defs>
+    <linearGradient id="band" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#6366f1" stop-opacity="0.9"/>
+      <stop offset="1" stop-color="#06b6d4" stop-opacity="0.75"/>
+    </linearGradient>
+  </defs>
+  <rect x="0" y="0" width="720" height="240" rx="14" fill="#0f172a"/>
+  <g fill="none" stroke="#334155" stroke-width="1">
+    <line x1="40" y1="176" x2="680" y2="176"/>
+  </g>
+  <g font-family="Segoe UI, Helvetica, Arial, sans-serif" fill="#e2e8f0" font-size="13">
+    <g>
+      <rect x="48" y="60" width="152" height="86" rx="8" fill="url(#band)"/>
+      <text x="124" y="96" text-anchor="middle" font-size="15" font-weight="700">L0</text>
+      <text x="124" y="118" text-anchor="middle" font-size="12">全局主题</text>
+    </g>
+    <g>
+      <rect x="236" y="76" width="152" height="70" rx="8" fill="#1e293b" stroke="#475569"/>
+      <text x="312" y="106" text-anchor="middle" font-size="15" font-weight="700">L1</text>
+      <text x="312" y="126" text-anchor="middle" font-size="12">主要分支</text>
+    </g>
+    <g>
+      <rect x="424" y="92" width="152" height="54" rx="8" fill="#1e293b" stroke="#475569"/>
+      <text x="500" y="115" text-anchor="middle" font-size="15" font-weight="700">L2</text>
+      <text x="500" y="134" text-anchor="middle" font-size="12">局部机制</text>
+    </g>
+    <g>
+      <rect x="612" y="96" width="0" height="0"/>
+    </g>
+  </g>
+  <g fill="#94a3b8" font-family="Segoe UI, Helvetica, Arial, sans-serif" font-size="11">
+    <text x="48" y="200">L3 实现细节与 L4 边界反例继续向右下钻</text>
+  </g>
+  <g fill="none" stroke="#64748b" stroke-width="1.5" marker-end="url(#arrow)">
+  </g>
+  <defs>
+    <marker id="arrow" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto">
+      <path d="M0,0 L6,3 L0,6 Z" fill="#64748b"/>
+    </marker>
+  </defs>
+  <g fill="none" stroke="#64748b" stroke-width="1.5">
+    <line x1="200" y1="103" x2="232" y2="111" marker-end="url(#arrow)"/>
+    <line x1="388" y1="111" x2="420" y2="119" marker-end="url(#arrow)"/>
+  </g>
+</svg>

package/template/references/atlas-guide.mdx

@@ -0,0 +1,169 @@
+<ExplainPage id="components-demo" title="Concept Atlas 组件展厅" summary="一页看懂框架提供的全部组件：从知识结构、语义内容到公式、图表、配图与引用。" layout="editorial" density="reading">
+  <ConceptGraph root="showroom">
+    <ConceptNode id="showroom" title="组件展厅：每个组件只承担一种表达职责" level="L0" input="知识内容与结构意图" output="可导航的概念页面与关系图" summary="组件不是装饰卡片，而是把定义、证据、模型、关系和布局分别交给最合适的语义工具。">
+      <Overview>本页专门展示框架能力。点击左侧或下方节点逐组查看组件效果，再切换右下角关系图观察它们如何组织成一套知识系统。</Overview>
+      <Definition>Concept Atlas 将 MDX 组件分为知识结构、内容语义、验证判断、经典模型、展示布局、关系可视化和扩展能力七个家族。</Definition>
+      <Input>主题、关键元素、证据、关系和布局意图。</Input>
+      <Output>节点探索页、全局关系图、可缩放 Mermaid 图、公式与图表以及可复用的模型表达。</Output>
+      <LearningObjectives items={['认识全部组件家族', '理解组件之间的职责边界', '选择合适组件编写自己的 MDX']} />
+      <KeyQuestion>我需要表达的是一个事实、一种关系，还是一种组织信息的结构？</KeyQuestion>
+      <Callout type="success" title="展厅导航">先看“知识结构”，再看“内容语义”和“经典模型”；最后打开“可视化与布局”和“扩展能力”，就能覆盖完整能力。</Callout>
+      <Children><ConceptRef id="structure-family" /><ConceptRef id="content-family" /><ConceptRef id="verification-family" /><ConceptRef id="concept-models" /><ConceptRef id="presentation-family" /><ConceptRef id="visual-family" /><ConceptRef id="extension-family" /></Children>
+    </ConceptNode>
+
+    <ConceptNode id="structure-family" title="知识结构组件：搭出可下钻的概念树" level="L1" parent="showroom" summary="页面、图谱、节点、子节点和跨节点关系共同构成导航骨架。">
+      <Definition>结构组件负责“有什么节点、节点如何归属、哪些概念彼此关联”，不负责替代节点内部的知识内容。</Definition>
+      <FrameworkModel title="结构组件家族" type="layers" elements={[{title:'ExplainPage',description:'页面元信息'},{title:'ConceptGraph',description:'图谱容器与根节点'},{title:'ConceptNode',description:'可下钻概念节点'},{title:'Children / ConceptRef',description:'树层级入口'},{title:'Relation',description:'跨分支语义边'}]} />
+      <Children><ConceptRef id="node-anatomy" /><ConceptRef id="relation-anatomy" /></Children>
+    </ConceptNode>
+    <ConceptNode id="node-anatomy" title="ConceptNode：一个节点承载一个可命名概念" level="L2" parent="structure-family" summary="节点用 id、title、level、parent、summary 和语义子组件描述一个认知单元。">
+      <Definition>ConceptNode 是所有内容的承载边界；L0 到 L4 分别对应全局概览、子系统、机制、实现细节和边界反例。</Definition>
+      <Example title="最小节点">`<ConceptNode id="idea" title="一个判断" level="L2" parent="root" summary="一句话结论">…</ConceptNode>`</Example>
+      <Glossary term="L0–L4">概念缩放层级，不是视觉字号等级。</Glossary>
+    </ConceptNode>
+    <ConceptNode id="relation-anatomy" title="Relation：把跨分支意义显式画出来" level="L2" parent="structure-family" summary="Relation 不改变树层级，而是表达前置、因果、产出、依赖和对比。">
+      <Definition>关系边使用白名单类型：prerequisite、causes、produces、uses、implements、contrasts、depends-on、exception-of、precedes。</Definition>
+      <RelationMap title="关系类型示例" items={[{from:'Definition',type:'implements',to:'ConceptNode',note:'内容具体化节点'},{from:'Evidence',type:'supports',to:'Claim',note:'由证据支撑判断'}]} />
+      <Boundary>不要用 Relation 表达 parent-child；父子边由 parent 和 Children 自动生成。</Boundary>
+    </ConceptNode>
+
+    <ConceptNode id="content-family" title="内容语义组件：让节点内容有明确职责" level="L1" parent="showroom" summary="不同语义组件分别回答是什么、怎么做、输入输出是什么以及边界在哪里。">
+      <Definition>内容组件将长段落拆为可识别的信息类型，NodeExplorer 会按语义将它们放入对应区域。</Definition>
+      <Stack gap="sm"><Definition>Definition：严格定义。</Definition><Mechanism>Mechanism：过程与因果。</Mechanism><Boundary>Boundary：限制与失效条件。</Boundary></Stack>
+      <Children><ConceptRef id="meaning-blocks" /><ConceptRef id="context-blocks" /></Children>
+    </ConceptNode>
+    <ConceptNode id="meaning-blocks" title="定义与机制：先说清楚是什么，再说如何发生" level="L2" parent="content-family" summary="Overview 建立直觉，Definition 收紧边界，Mechanism 解释过程。">
+      <Overview>Overview 适合首屏快速认知。</Overview>
+      <Definition>Definition 给出概念的必要特征。</Definition>
+      <Mechanism>Mechanism 解释输入如何经过状态变化产生输出。</Mechanism>
+      <Implementation language="javascript" title="Implementation 示例">const result = input.map(transform);</Implementation>
+    </ConceptNode>
+    <ConceptNode id="context-blocks" title="上下文组件：输入、输出、示例和术语补足理解" level="L2" parent="content-family" summary="Input、Output、Example、Counterexample、Prerequisite 和 Glossary 负责补全概念上下文。">
+      <Prerequisite>需要先理解“节点”和“关系”。</Prerequisite>
+      <Input>原始材料、问题和约束。</Input>
+      <Output>可验证的结论或下一步行动。</Output>
+      <Example title="正例">用具体案例说明抽象概念如何落地。</Example>
+      <Counterexample title="反例">指出看似相同但不满足定义的情况。</Counterexample>
+      <Glossary term="semantic">让术语拥有局部定义。</Glossary>
+    </ConceptNode>
+
+    <ConceptNode id="verification-family" title="验证与判断组件：让结论不止是漂亮话" level="L1" parent="showroom" summary="证据、不变量、故障模式、权衡和学习目标把内容连接到行动。">
+      <Definition>这一组组件专门呈现可检查的依据、稳定约束、风险、取舍和阅读目标。</Definition>
+      <Evidence command="npm run validate" observes="确认 MDX 节点数量、层级、关系类型与必需字段。" />
+      <Invariant title="组件契约">语义组件表达知识，模板负责布局；内容不直接写 CSS、坐标或 SVG。</Invariant>
+      <FailureMode symptom="页面看似完整但难以使用" cause="节点缺少摘要、边界或关系" evidence="检查节点是否只有一段泛化说明" remedy="补充证据与下钻入口" />
+      <Tradeoff title="信息密度与可读性" options={[{name:'展开细节',benefit:'证据更完整',cost:'首屏更长',when:'复杂机制'}, {name:'压缩摘要',benefit:'扫描更快',cost:'上下文较少',when:'总览节点'}]} />
+      <LearningObjectives items={['识别证据', '发现边界', '做出取舍']} />
+    </ConceptNode>
+
+    <ConceptNode id="concept-models" title="概念模型组件：把推理结构变成可读的形状" level="L1" parent="showroom" summary="五个模型组件分别表达并列、二维定位、变量关系、论证层级与收敛过程。">
+      <Definition>概念模型不是装饰图形。选择模型时先判断信息的组织关系，再选择能够让这层关系一眼可见的组件。</Definition>
+      <FrameworkModel title="FrameworkModel：并列要素" type="elements" elements={[{title:'问题',description:'明确要解释的对象'},{title:'机制',description:'说明变化如何发生'},{title:'证据',description:'给出可验证依据'}]} />
+      <MatrixModel title="MatrixModel：影响 / 成本" xLabel="实施成本" yLabel="预期影响" cells={[{title:'优先投入',description:'高影响 / 低成本',tone:'success'},{title:'审慎评估',description:'高影响 / 高成本',tone:'warn'},{title:'快速验证',description:'低影响 / 低成本'},{title:'暂缓处理',description:'低影响 / 高成本',tone:'danger'}]} />
+      <FormulaModel title="FormulaModel：用户价值" formula="用户价值 = 新体验 - 旧体验 - 替换成本" variables={[{symbol:'新体验',description:'方案带来的增量收益'},{symbol:'旧体验',description:'现有替代方案的价值'},{symbol:'替换成本',description:'学习、迁移与风险'}]} />
+      <PyramidModel title="PyramidModel：论证层级" levels={[{title:'结论',description:'需要读者带走的判断'},{title:'理由',description:'支撑判断的关键分组'},{title:'证据',description:'事实、数据与案例'}]} />
+      <FunnelModel title="FunnelModel：从输入到行动" steps={[{title:'收集',description:'汇集候选信息'},{title:'筛选',description:'排除不满足约束的项'},{title:'验证',description:'检查关键假设'},{title:'行动',description:'形成下一步决策'}]} />
+      <Children><ConceptRef id="framework-demo" /><ConceptRef id="matrix-demo" /><ConceptRef id="formula-demo" /><ConceptRef id="pyramid-funnel-demo" /></Children>
+    </ConceptNode>
+    <ConceptNode id="framework-demo" title="FrameworkModel：承载并列、阶段、层级与循环" level="L2" parent="concept-models" summary="一个组件通过 type 区分要素、阶段、层级和循环。">
+      <FrameworkModel title="PDCA 循环" type="cycle" elements={[{title:'Plan',description:'计划'},{title:'Do',description:'执行'},{title:'Check',description:'检查'},{title:'Act',description:'改进'}]} />
+      <Details summary="何时使用">当结构重点是元素数量和组织方式，而不是具体节点之间的关系时使用。</Details>
+    </ConceptNode>
+    <ConceptNode id="matrix-demo" title="MatrixModel：二维象限让优先级一眼可见" level="L2" parent="concept-models" summary="用 xLabel、yLabel 和 cells 描述两个维度及其组合。">
+      <MatrixModel title="影响 / 成本矩阵" xLabel="实施成本" yLabel="预期影响" cells={[{title:'优先投资',description:'高影响 / 低成本',tone:'success'},{title:'谨慎评估',description:'高影响 / 高成本',tone:'warn'},{title:'快速试验',description:'低影响 / 低成本'},{title:'暂缓',description:'低影响 / 高成本',tone:'danger'}]} />
+      <DecisionMatrix title="参数契约" headers={['参数','用途','形态']} rows={[['title','模型标题','string'],['cells','象限内容','array'],['tone','视觉提示','info / warn / danger']]} />
+    </ConceptNode>
+    <ConceptNode id="formula-demo" title="FormulaModel：把多变量关系压缩成一个判断" level="L2" parent="concept-models" summary="公式适合表达变量之间明确的加减乘除关系。">
+      <FormulaModel title="用户价值" formula="用户价值 = 新体验 − 旧体验 − 替换成本" variables={[{symbol:'新体验',description:'新方案带来的增量收益'},{symbol:'旧体验',description:'用户现有替代方案'},{symbol:'替换成本',description:'迁移与学习付出'}]} />
+      <NoteGrid notes={[{title:'优点',content:'关系直接'}, {title:'边界',content:'不替代真实测量'}]} />
+    </ConceptNode>
+    <ConceptNode id="pyramid-funnel-demo" title="PyramidModel 与 FunnelModel：分层和收敛是两种不同逻辑" level="L2" parent="concept-models" summary="金字塔从基础归纳到结论，漏斗从大量输入逐步筛选到行动。">
+      <PyramidModel title="金字塔论证" levels={[{title:'结论',description:'核心判断'},{title:'理由',description:'关键分组'},{title:'证据',description:'事实与案例'}]} />
+      <FunnelModel title="AIDA 漏斗" steps={[{title:'Attention',description:'注意'},{title:'Interest',description:'兴趣'},{title:'Desire',description:'欲望'},{title:'Action',description:'行动'}]} />
+    </ConceptNode>
+
+    <ConceptNode id="presentation-family" title="展示与布局组件：组织复杂内容的阅读节奏" level="L1" parent="showroom" summary="Compare、Flow、Timeline、Tabs、Grid 等组件负责并列、时序、折叠和空间组织。">
+      <Compare items={[{label:'流式阅读',rows:['信息密度','适用场景'],values:['高','定义与论证']},{label:'分栏对比',rows:['信息密度','适用场景'],values:['中','方案比较']}]} />
+      <Flow steps={['输入', '组织', '渲染', '验证']} />
+      <Timeline events={[{label:'T0',content:'定义目标'}, {label:'T1',content:'选择模型'}, {label:'T2',content:'验证结果'}]} />
+      <Children><ConceptRef id="layout-demo" /><ConceptRef id="compact-demo" /></Children>
+    </ConceptNode>
+    <ConceptNode id="layout-demo" title="布局原语：Stack、Grid、Split、Columns 让信息有秩序" level="L2" parent="presentation-family" summary="布局组件只表达空间意图，具体样式由模板统一接管。">
+      <Definition>布局原语表达信息之间的空间关系；它们负责组织内容，不负责改变内容本身的语义。</Definition>
+      <Columns><Split ratio="1fr 1fr"><Callout title="左列">结论与定义。</Callout><Callout title="右列">证据与边界。</Callout></Split></Columns>
+      <Grid columns="auto" gap="sm"><Insight title="局部判断">Grid 中的短信息。</Insight><Insight title="另一判断" tone="warn">不要混用职责。</Insight></Grid>
+    </ConceptNode>
+    <ConceptNode id="compact-demo" title="压缩阅读：Tabs、Details、Callout、Insight、NoteGrid" level="L2" parent="presentation-family" summary="这些组件适合把结论、提示、细节和短信息压缩在首屏。">
+      <Definition>压缩组件通过折叠、分组和短提示降低首屏负担，同时保留继续阅读所需的上下文。</Definition>
+      <Tabs items={[{label:'结论',content:'先展示最重要的判断。'},{label:'证据',content:'再展开可验证依据。'}]} />
+      <Details summary="展开更多">Details 将次要信息收起，避免首屏过载。</Details>
+      <Insight title="关键判断" tone="success">一个组件只承担一种信息组织方式。</Insight>
+    </ConceptNode>
+
+    <ConceptNode id="visual-family" title="关系与可视化组件：把结构变成可探索画布" level="L1" parent="showroom" summary="Mermaid、RelationMap、RelationPath、Insight 和 NoteGrid 让关系、路径和结论可视化。">
+      <Mermaid title="组件协作流" width="100%" height="220px" chart={`flowchart LR
+  A[MDX 内容] --> B[语义组件]
+  B --> C[数据模型]
+  C --> D[节点探索]
+  C --> E[关系图谱]
+  D --> F[可观察结论]
+  E --> F
+  style A fill:#172554,stroke:#38bdf8,color:#e0f2fe
+  style F fill:#14532d,stroke:#34d399,color:#ecfdf5`} />
+      <RelationPath title="阅读路径" steps={[{level:'L0',node:'组件展厅',note:'总览',tone:'info'},{level:'L1',node:'模型组件',note:'选择结构',tone:'success'},{level:'L2',node:'MatrixModel',note:'定位决策',tone:'warn'}]} />
+      <RelationMap title="可视化摘要" items={[{from:'MDX',type:'produces',to:'Graph',note:'生成关系图'},{from:'Node',type:'uses',to:'Mermaid',note:'展示局部流程'}]} />
+    </ConceptNode>
+
+    <ConceptNode id="extension-family" title="扩展能力：公式、图表、图片、代码与引用" level="L1" parent="showroom" summary="数学公式、数据图表、配图题注、代码块和参考文献五项能力，让讲解可以带上推导、数据、实现与出处。">
+      <Definition>扩展组件把文本之外的证据接进页面：Math/MathBlock 渲染数学、Chart 绘制数据、Figure 承载配图、CodeBlock 展示代码或命令、Cite/References 保留出处。</Definition>
+      <Children><ConceptRef id="math-demo" /><ConceptRef id="chart-demo" /><ConceptRef id="figure-demo" /><ConceptRef id="code-demo" /><ConceptRef id="citation-demo" /></Children>
+    </ConceptNode>
+
+    <ConceptNode id="math-demo" title="Math 与 MathBlock：把推导写进正文" level="L2" parent="extension-family" summary="Math 用于行内符号，MathBlock 用于独立公式并支持变量说明。">
+      <Definition>两者都用 KaTeX 渲染 LaTeX。行内用 Math，独立成块并需要解释变量时用 MathBlock。</Definition>
+      <Overview>例如信息量的定义 <Math>\log_2 N</Math> 表示 N 种等可能结果所需要的比特数。</Overview>
+      <MathBlock title="香农信息量" formula="I(x) = -\log_2 p(x)" variables={[{symbol:'p(x)',description:'事件 x 发生的概率'},{symbol:'I(x)',description:'观察 x 后获得的信息量，单位为比特'}]} />
+      <Boundary>公式是 LaTeX 字符串，不要在里面写 Markdown 或 HTML。</Boundary>
+    </ConceptNode>
+
+    <ConceptNode id="chart-demo" title="Chart：用同一数据切换三种图形" level="L2" parent="extension-family" summary="bar、line、pie 三种类型共享数据形状，按比较、趋势或占比选择。">
+      <Definition>Chart 接收 data（`{label, value}` 数组）或 series + labels，在 SVG 中绘制并跟随主题色。</Definition>
+      <Chart title="各阶段耗时" type="bar" unit="小时" data={[{label:'收集',value:6},{label:'分析',value:14},{label:'验证',value:9},{label:'落地',value:4}]} />
+      <Chart title="留存趋势" type="line" labels={['第1周','第2周','第3周','第4周']} series={[{name:'留存率',values:[100,72,58,49]}]} />
+    </ConceptNode>
+
+    <ConceptNode id="figure-demo" title="Figure：图片与题注一起出现" level="L2" parent="extension-family" summary="Figure 把图片、题注编号和说明绑定，构建时把本地图片内联进单文件。">
+      <Definition>相对路径的图片会在构建时转成 base64 内联，远程 URL 保持不变；label 提供“图 1”这样的编号。</Definition>
+      <Figure src="./assets/sample-diagram.svg" alt="概念缩放示意" label="图 1" caption="概念缩放：同一主题可以从 L0 全局逐层下钻到 L4 边界反例。" />
+      <Boundary>大图会显著增大单文件 HTML；截图类内容建议控制尺寸。</Boundary>
+    </ConceptNode>
+
+    <ConceptNode id="code-demo" title="CodeBlock：把命令、配置或伪代码放进正文" level="L2" parent="extension-family" summary="与绑定节点的 Implementation 不同，CodeBlock 可以出现在任何位置，并支持标题、题注、换行和行号。">
+      <Definition>CodeBlock 通过 code（或子内容）接收字符串，language 决定语言标记，title 与 caption 提供说明，lineNumbers 和 wrap 控制逐行讲解与长行折行。</Definition>
+      <CodeBlock language="bash" title="校验与构建" caption="命令行、伪代码或配置都可以用它承载，不依附于某个概念节点。" lineNumbers>{`npm run validate
+npm run sync
+npm run build`}</CodeBlock>
+      <CodeBlock language="javascript" title="语义优先" wrap>{`const explain = concept => concept.mechanism ?? concept.definition ?? concept.overview;`}</CodeBlock>
+      <Boundary>代码里的反引号、花括号请放在模板字符串中传入，避免被 MDX 当作表达式解析。</Boundary>
+    </ConceptNode>
+
+    <ConceptNode id="citation-demo" title="Cite 与 References：让结论可以追溯" level="L2" parent="extension-family" summary="行内用 Cite 标记引用，文末用 References 列出完整出处，编号自动对应。">
+      <Definition>Cite 的 id 与 References 条目的 id 对应，渲染时显示条目在列表中的序号，并链接到该条目。</Definition>
+      <Overview>信息密度的价值在于可验证性<Cite id="shannon1948" />，而可验证性依赖清晰的出处<Cite id="tufte1983" />。</Overview>
+      <Boundary>在 atlas 中，把 Cite 和 References 放在同一个节点内，否则未访问的节点里引用编号无法解析。</Boundary>
+      <References title="本节点引用" items={[{id:'shannon1948',authors:'Shannon, C. E.',year:'1948',title:'A Mathematical Theory of Communication',source:'Bell System Technical Journal'},{id:'tufte1983',authors:'Tufte, E. R.',year:'1983',title:'The Visual Display of Quantitative Information',source:'Graphics Press'}]} />
+    </ConceptNode>
+
+    <Relation from="structure-family" to="content-family" type="precedes" label="先搭骨架" />
+    <Relation from="content-family" to="verification-family" type="uses" label="补充证据" />
+    <Relation from="concept-models" to="presentation-family" type="implements" label="结构落地" />
+    <Relation from="verification-family" to="visual-family" type="produces" label="形成可见结论" />
+    <Relation from="visual-family" to="structure-family" type="depends-on" label="依赖图谱数据" />
+    <Relation from="extension-family" to="content-family" type="uses" label="补充证据形态" />
+    <Relation from="extension-family" to="verification-family" type="produces" label="提供可追溯依据" />
+    <Relation from="matrix-demo" to="formula-demo" type="contrasts" label="维度 vs 公式" />
+    <Relation from="pyramid-funnel-demo" to="framework-demo" type="contrasts" label="分层 vs 循环" />
+    <Relation from="math-demo" to="formula-demo" type="contrasts" label="LaTeX vs 纯文本公式" />
+    <Relation from="chart-demo" to="matrix-demo" type="contrasts" label="连续数据 vs 二维定位" />
+  </ConceptGraph>
+</ExplainPage>