concept-atlas-dense-explain 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concept-atlas-dense-explain",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Portable dense-explanation skill and MDX concept atlas template",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -1,20 +1,47 @@
 ---
 name: concept-atlas-dense-explain
-description: Generate high-density, navigable concept explanations as semantic MDX for the Concept Atlas template. Use when a user asks for dense explanations, concept maps, layered knowledge, mechanism breakdowns, or a searchable interactive explanation page.
+description: Build high-density, navigable Concept Atlas webpages with the bundled React/Vite/MDX template. Use this skill whenever the user asks for a dense technical explanation, concept map, layered knowledge page, interactive explanation, or webpage resembling the bundled compile-runtime exemplar. Never replace the template with a custom JSX, HTML, CSS, or vertically-scrolling Markdown page.
 ---
 
 # Concept Atlas Dense Explain
 
-Use the bundled template to turn knowledge into a concept tree, semantic relations, and compact reading blocks. The AI writes knowledge semantics; the template owns layout, CSS, graph rendering, navigation, zoom, search, and responsive behavior.
+This is an Agent Skills-compatible skill. Keep the instructions and generated content portable across Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Cline, GitHub Copilot, and other agents that support `SKILL.md`.
+
+Use the bundled template to turn knowledge into a concept tree, semantic relations, and compact reading blocks. The AI writes knowledge semantics; the template owns layout, CSS, graph rendering, navigation, zoom, search, and responsive behavior. The required deliverable is a built Concept Atlas webpage, normally `dist/index.html`, not a standalone mockup.
+
+## Mandatory preflight and no-fallback rule
+
+Before generating content, resolve the directory containing this `SKILL.md` and verify that these bundled files are readable:
+
+- `assets/template/content/compile-runtime.mdx`
+- `assets/template/src/app/App.jsx`
+- `assets/template/src/components/MDXComponents.jsx`
+- `assets/template/src/model/normalize-content.js`
+- `references/components.md`
+
+Read the exemplar and the component contract before writing. If the bundled template is unavailable, stop and report that the Concept Atlas template cannot be accessed. Do not create a custom JSX app, standalone HTML, CSS layout, Mermaid-only page, or vertically scrolling Markdown page as a substitute.
+
+The template is the implementation boundary. Do not edit `src/`, styles, `index.html`, Vite configuration, or package dependencies for a content task. Only replace the MDX content after the template has been copied into the task workspace.
+
+## Step 0 — Read the exemplar before writing
+
+Read [assets/template/content/compile-runtime.mdx](assets/template/content/compile-runtime.mdx) in full first. It is the **reference standard**, not just a file to overwrite. Study its shape before generating anything:
+
+- 1 `L0` root, ~5 `L1` branches, 2–3 children per branch, descending to `L3`/`L4` where the topic deserves it.
+- Every `title` is a claim ("ABI 破坏：能链接，不等于能调用"), and every `summary` is a one-sentence judgment.
+- Important nodes carry 3–6 semantic components, not one lone paragraph.
+- Claims are backed by concrete commands, numbers, or named artifacts (`readelf -Ws`, `nm -C`, `objdump -dr`, `.bss`, ASLR).
+- Cross-branch meaning is encoded as labeled `Relation`s, not prose.
 
 ## Workflow
 
-1. Model one `L0` root, then `L1` structure, `L2` mechanisms, and optional `L3/L4` boundaries or failures. Keep each node focused on one claim.
-2. Add `parent`/`Children` for hierarchy and `Relation` for cross-branch meaning. Never encode layout, coordinates, CSS, or SVG in MDX.
-3. Give important nodes a definition, input/output, mechanism, one concrete example, and at least one boundary or evidence item.
-4. Prefer horizontal semantic components (`Grid`, `Split`, `Flow`, `Compare`, `Timeline`, `Tradeoff`) for comparisons and sequences. Use `Details` for secondary detail; do not turn every fact into a card.
-5. Use `LearningObjectives`, `KeyQuestion`, `Evidence`, `Invariant`, and `FailureMode` when they improve understanding or verification. Keep the first screen to the core claim plus 3–5 key facts.
-6. Build with the bundled template and verify node switching, graph mode, search, URL `#node=...`, keyboard navigation, and responsive layout.
+1. Resolve and copy the complete `assets/template` directory into the task workspace; preserve its React, CSS, graph, and build files.
+2. Read the exemplar above and [references/components.md](references/components.md) for the component and relation contract.
+3. Replace only `content/compile-runtime.mdx`. Model one `L0` root, then `L1` structure, `L2` mechanisms, and optional `L3/L4` boundaries or failures. Keep each node focused on one claim.
+4. Add `parent`/`Children` for hierarchy and `Relation` for cross-branch meaning. Never encode layout, coordinates, CSS, or SVG in MDX.
+5. Give important nodes a definition, input/output, mechanism, one concrete example, and at least one boundary or evidence item.
+6. Run the bundled content validator, then run `npm install` and `npm run build`. If validation or build fails, revise the MDX and do not return a substitute page.
+7. Verify node switching, graph mode, search, URL `#node=...`, keyboard navigation, and responsive layout. Return the built `dist/index.html` path.
 
 ## Content rules
 
@@ -22,10 +49,25 @@ Use the bundled template to turn knowledge into a concept tree, semantic relatio
 - Use tables/flows for comparison and causality; use short paragraphs only for explanation.
 - Every dense block should contain a conclusion, evidence, or limitation.
 - Prefer 2–4 columns on wide screens and natural stacking on narrow screens.
-- Do not invent unsupported components. Read `references/components.md` for the supported semantic API.
+- Do not invent unsupported components or relation types. Read [references/components.md](references/components.md) for the supported semantic API.
+- Aim for the exemplar's scale: roughly 1 root, 4–5 `L1` branches, ~15–25 nodes total. A thin graph (few nodes, one paragraph each) is a failure, not a shortcut.
+
+## Self-check before finishing
+
+Run this checklist and revise until every item passes. If an item fails, fix the content instead of adding decoration.
+
+- [ ] One `L0` root; every `L1` belongs to it; depth reaches `L3`/`L4` where warranted.
+- [ ] Every key node has a claim-style `title`, a one-line `summary`, and at least one of `Definition` / `Mechanism` / `Example` / `Evidence` / `Boundary`.
+- [ ] Several nodes carry concrete, verifiable evidence (real commands, metrics, or named artifacts) rather than generic filler.
+- [ ] Cross-branch meaning is encoded with `Relation` using only the whitelisted types in `references/components.md`.
+- [ ] First screen shows the core claim plus 3–5 key facts; long detail lives in `Details` / `Tabs`.
+- [ ] No CSS, coordinates, SVG, or layout instructions appear in the MDX.
+- [ ] Only the template's MDX content was changed; no replacement JSX or vertical article page was created.
+- [ ] The bundled validator passes before the build.
+- [ ] The template builds and node switching, graph mode, search, `#node=...`, and keyboard navigation all work.
 
 ## Portable template
 
-The self-contained React/Vite/MDX implementation is in [assets/template](assets/template). Copy it into a project, replace `content/compile-runtime.mdx`, run `npm install`, then `npm run build`. The template has no dependency on the source repository's absolute paths.
+The self-contained React/Vite/MDX implementation is in [assets/template](assets/template). Copy it into a project, replace `content/compile-runtime.mdx` **after studying it**, run `npm install`, then `npm run build`. The template has no dependency on the source repository's absolute paths. If the host agent cannot access or copy the template, stop and report the missing template; do not return a substitute webpage.
 
-For the component contract and request priorities, read [references/components.md](references/components.md). For AI prompt wording and component selection, read [references/prompting.md](references/prompting.md).
+For the component contract, relation whitelist, and level semantics, read [references/components.md](references/components.md). For the exemplar breakdown, density targets, and prompt wording, read [references/prompting.md](references/prompting.md).

package/skill/assets/template/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "version": "0.1.0",
   "type": "module",
-  "scripts": { "dev": "vite", "build": "node scripts/build.mjs", "clean:temp": "node scripts/clean-temp.mjs" },
+  "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",

package/skill/assets/template/scripts/validate-content.mjs

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(scriptDir, '..');
+const contentPath = path.join(rootDir, 'content', 'compile-runtime.mdx');
+const source = fs.readFileSync(contentPath, 'utf8');
+const failures = [];
+const nodePattern = /<ConceptNode\b([^>]*)>([\s\S]*?)<\/ConceptNode>/g;
+const relationPattern = /<Relation\b([^>]*)\/>/g;
+const attributes = text => Object.fromEntries([...text.matchAll(/([\w-]+)=(?:"([^"]*)"|'([^']*)')/g)].map(match => [match[1], match[2] ?? match[3] ?? '']));
+const nodes = [...source.matchAll(nodePattern)].map(match => ({ ...attributes(match[1]), body: match[2] }));
+const relations = [...source.matchAll(relationPattern)].map(match => attributes(match[1]));
+const ids = new Set(nodes.map(node => node.id));
+const allowedRelations = new Set(['prerequisite', 'causes', 'produces', 'uses', 'implements', 'contrasts', 'depends-on', 'exception-of', 'precedes']);
+
+if (!source.includes('<ExplainPage')) failures.push('missing ExplainPage');
+if (!source.includes('<ConceptGraph')) failures.push('missing ConceptGraph');
+if (nodes.filter(node => node.level === 'L0').length !== 1) failures.push('expected exactly one L0 root');
+if (nodes.filter(node => node.level === 'L1').length < 4) failures.push('expected at least four L1 branches');
+if (nodes.length < 15) failures.push(`expected at least 15 nodes, found ${nodes.length}`);
+if (!nodes.some(node => ['L3', 'L4'].includes(node.level))) failures.push('expected L3 or L4 depth');
+if (relations.length < 8) failures.push(`expected at least 8 relations, found ${relations.length}`);
+
+for (const node of nodes) {
+  if (!node.id) failures.push('node is missing id');
+  if (!node.title) failures.push(`${node.id || '<unknown>'} is missing title`);
+  if (!node.summary) failures.push(`${node.id || '<unknown>'} is missing summary`);
+  if (node.parent && !ids.has(node.parent)) failures.push(`${node.id} references missing parent ${node.parent}`);
+  if (!/(<(Definition|Mechanism|Example|Evidence|Boundary|Details|Callout|Counterexample|Glossary|Input|Output)\b)/.test(node.body)) {
+    failures.push(`${node.id} lacks a core semantic component`);
+  }
+}
+
+for (const relation of relations) {
+  if (!ids.has(relation.from) || !ids.has(relation.to)) failures.push(`relation references missing node: ${relation.from} -> ${relation.to}`);
+  if (!allowedRelations.has(relation.type)) failures.push(`unsupported relation type: ${relation.type}`);
+  if (!relation.label) failures.push(`relation ${relation.from} -> ${relation.to} is missing label`);
+}
+
+if (failures.length) {
+  console.error('Concept Atlas content validation failed:');
+  for (const failure of failures) console.error(`- ${failure}`);
+  process.exit(1);
+}
+
+console.log(`Concept Atlas content validation passed (${nodes.length} nodes, ${relations.length} relations).`);

package/skill/references/components.md

@@ -22,6 +22,43 @@ High-value verification components: `LearningObjectives`, `KeyQuestion`, `Eviden
 
 Presentation components: `Stack`, `Grid`, `Split`, `Tabs`, `Flow`, `Compare`, `DecisionMatrix`, `Timeline`, `Callout`, `Details`, `RelationMap`, `RelationPath`, `Insight`, and `NoteGrid`.
 
+## Relation types (whitelist — only these render)
+
+Write cross-branch `Relation`s with `type` from this exact list. Any other value renders no styled edge.
+
+| type | label | use for |
+| --- | --- | --- |
+| `prerequisite` | 前置知识 | knowledge required before this concept |
+| `causes` | 因果推动 | one concept triggers a state change in another |
+| `produces` | 产出生成 | a stage outputs an artifact or entity |
+| `uses` | 消费使用 | a concept consumes or calls another |
+| `implements` | 实现关系 | a concrete mechanism implements an abstraction |
+| `contrasts` | 对比关系 | side-by-side contrast (no arrowhead) |
+| `depends-on` | 依赖关系 | runtime/effect depends on an external condition |
+| `exception-of` | 异常/反例 | a boundary case, counterexample, or broken assumption |
+| `precedes` | 时序先后 | pipeline or temporal ordering |
+
+Do **not** write `parent-child` as a `Relation`; the tree edge is generated automatically from `parent` / `Children`. Add a short `label` to every relation so the graph edge is readable.
+
+## Levels L0–L4
+
+| Level | name | role | typical components |
+| --- | --- | --- | --- |
+| `L0` | 全局概览 | system-wide framing and the root claim | `Definition`, `Prerequisite`, `LearningObjectives`, `KeyQuestion`, `Input`/`Output`, `Callout`, `Tabs` |
+| `L1` | 主要阶段 / 子系统 | major lifecycle stage or subsystem | `Definition`, `Input`/`Output`, `Example`, `Children` |
+| `L2` | 局部机制 | concrete mechanism and flow | `Definition`, `Mechanism`, `Details`, `Evidence`, `Invariant`, `Tradeoff`, `FailureMode` |
+| `L3` | 实现细节 | algorithm, data structure, or code | `Definition`, `Example`, `Glossary` |
+| `L4` | 边界与反例 | boundary, exception, or counterexample | `Callout(danger/warn)`, `Example`, `FailureMode` |
+
+## Density targets
+
+Match the exemplar (`assets/template/content/compile-runtime.mdx`):
+
+- 1 `L0` root, 4–5 `L1` branches, 2–3 children per branch, ~15–25 nodes total.
+- Every key node: 3–6 semantic components; `L3`/`L4` nodes may be leaner but still concrete.
+- At least a few nodes per document carry `Evidence`, `Invariant`, or `FailureMode` with a real command/observation.
+- ~8–15 cross-branch `Relation`s, each with a `label`.
+
 ## Request priorities
 
 The portable template covers the core `req.md` contract, node exploration, graph view, semantic relations, search, level/relation filters, URL node state, browsing history, keyboard shortcuts, Mermaid zoom, and responsive rendering. Evidence-oriented components and compact tradeoffs cover the highest-value `request.md` enhancements without adding permanent side panels.

package/skill/references/prompting.md

@@ -3,14 +3,52 @@
 Include this contract when asking an AI to generate or revise a dense explanation:
 
 ```text
+先通读 content/compile-runtime.mdx（黄金样例），再产出；不要跳过、不要直接覆盖。
 输出语义 MDX，不要输出 CSS、HTML 布局、坐标、SVG 或交互脚本。
 先给一个 L0 根节点，再用 L1/L2/L3/L4 表达结构、机制、实现细节和边界。
 父子层级使用 parent/Children；跨分支含义使用 Relation。
+Relation 的 type 只能是：prerequisite, causes, produces, uses, implements, contrasts, depends-on, exception-of, precedes；每条都要带 label。
 每个关键节点优先提供：summary、Definition、Input/Output、Mechanism、一个 Example，以及 Evidence 或 Boundary。
 只在确实有帮助时使用组件：Flow 表示顺序，Compare/Tradeoff 表示选择，Timeline 表示时间，Evidence 表示验证，Invariant 表示必须保持的条件，FailureMode 表示故障定位。
 首屏只保留核心结论和 3–5 个关键事实；次要解释放进 Details。不要为了“看起来丰富”堆卡片。
+规模对齐样例：1 个根、4–5 个 L1、总计约 15–25 个节点、8–15 条 Relation。
+证据要具体：真实命令、指标或命名的产物，不要泛泛而谈。
 ```
 
+## Template availability gate
+
+Use this gate before the contract above:
+
+```text
+先确认当前 skill 目录中的 assets/template 可访问，并读取黄金样例与模板源码。
+如果模板不可访问，立即停止并说明缺少 Concept Atlas 模板；禁止自行用 JSX、HTML、CSS 或普通 Markdown 页面替代。
+模板可访问后，复制完整模板，只修改 content/compile-runtime.mdx，最后运行 npm run validate 和 npm run build。
+交付物必须是模板构建出的 dist/index.html。
+```
+
+## What "good" looks like (from the exemplar)
+
+`assets/template/content/compile-runtime.mdx` is the reference standard. Extract these patterns:
+
+- **Scale**: 1 `L0` + 5 `L1` + ~20 nodes, descending to `L4`.
+- **Titles are claims, not nouns**: 「缺页风暴与抖动」, 「ABI 破坏：能链接，不等于能调用」.
+- **Every node opens with a one-sentence judgment** in `summary`, then 3–6 components.
+- **Concrete evidence**: `readelf -Ws`, `nm -C`, `objdump -dr app.o`, `.bss`, ASLR, build-id.
+- **Semantic relations carry the cross-branch meaning**: `produces`, `precedes`, `causes`, `depends-on`, `exception-of`, each labeled.
+- **Detail is layered**: first screen = core claim + 3–5 facts; deep detail lives in `Details`, `Tabs`, `Glossary`.
+
+## Density targets
+
+| Metric | Target | Thin (failure) |
+| --- | --- | --- |
+| `L0` roots | 1 | 0 or many |
+| `L1` branches | 4–5 | 1–2 |
+| Nodes total | ~15–25 | < 8 |
+| Components per key node | 3–6 | 1 |
+| Cross-branch `Relation`s | 8–15 | 0–3 |
+| Nodes with concrete evidence | several | none |
+| Max depth | `L3`/`L4` | only `L0`/`L1` |
+
 ## Component selection
 
 | Information shape | Component |
@@ -29,10 +67,24 @@ Avoid using more than one primary presentation component in a single node unless
 ## Minimal generation skeleton
 
 ```mdx
-<ConceptNode id="mechanism" title="机制" level="L2" parent="structure" summary="一句话结论">
+<ConceptNode id="mechanism" title="机制：输入如何在约束下变成输出" level="L2" parent="structure" summary="一句话结论">
   <Definition>它是什么，以及为什么重要。</Definition>
   <Mechanism>输入 → 转换 → 输出。</Mechanism>
+  <Example title="一个具体案例">名称 + 数值 + 结果，而不是泛指。</Example>
   <Evidence command="tool --inspect target" observes="验证哪个不变量或产物。" />
   <Boundary>何时不成立，或哪些实现细节会改变结论。</Boundary>
 </ConceptNode>
 ```
+
+## Anti-patterns
+
+- **Thin graph**: a handful of nodes with one paragraph each. Fix by adding `L2`/`L3`/`L4` depth.
+- **Noun titles / no judgment**: `"缓存"` instead of `"缓存一致性与内存序"`; `summary` missing or restating the title.
+- **Generic filler**: "性能会受到影响" instead of a named command, metric, or artifact.
+- **Card stacking**: five decorative blocks with no conclusion, evidence, or limitation.
+- **Invented types**: `Relation type="related"` — not in the whitelist, renders nothing.
+- **Prose instead of structure**: cross-branch links described in a paragraph instead of a labeled `Relation`.
+
+## Before returning the result
+
+Verify the self-check list in `SKILL.md`. In short: 1 root, claim titles, one-line summaries, 3–6 components per key node, concrete evidence, whitelisted relations, layered detail, no layout in MDX, template builds.