concept-atlas-dense-explain

概念图谱密集讲解

所有操作都通过 concept-atlas-dense-explain CLI 完成，并且始终使用 npx。所需内容都在本文件和随附的 references/ 中；请勿读取框架仓库或已安装的软件包文件，不要从技能目录复制实现文件，也不要重新创建 React/Vite 应用。如果不清楚命令名称，请运行 npx concept-atlas-dense-explain help。如果用户只想要提示词／方法论而不需要文件，仍需选择一种 shell 并输出有效的 MDX；CLI 仅用于验证和编译。

运行 CLI

始终通过 npx 调用 CLI，可从任意目录运行：

npx concept-atlas-dense-explain <args>

这是唯一的运行方式——无需查找其他内容。请勿搜索本地二进制文件、仓库检出目录或已安装的副本，也不要运行框架自身的 npm 脚本。首次调用会从 npm registry 下载软件包；说明一次后继续即可。

工作流

1. 选择一种页面外壳：atlas（带节点导航的概念图）或 scroll（连续文档）。如果读者会深入探索概念或追随关联，推荐使用 atlas；如果内容是线性论述、教程和报告，则推荐使用 scroll。两种外壳共享同一个库。如果 .mdx 文件已存在，请检测其外壳并基于它进行处理。
2. 编写内容前先了解组件。 references/components.md 是组件目录——按组件名称搜索其属性和结构，不要凭猜测编写。references/atlas-guide.mdx（atlas）或 references/scroll-guide.mdx（scroll）是真实、可编译的 MDX，展示了该外壳的组件如何组合成页面。不要在其他地方查找组件文档，也不要为此运行 guide。 仅当你确实需要一份项目本地副本，以便与页面一起编译时，才运行 npx concept-atlas-dense-explain guide --mode <mode> -o <file>；用完后删除该副本。
3. 如有需要，可从骨架开始：npx concept-atlas-dense-explain create <file>.mdx --mode atlas|scroll（--mode 默认为 scroll）。create 和 guide 会覆盖输出，因此切勿将输出指向需要保留的文件。
4. 将语义化 MDX 写入用户的 .mdx 文件（参见编写规则）。
5. 渲染前先验证：

   npx concept-atlas-dense-explain validate <file>.mdx --mode atlas|scroll
   npx concept-atlas-dense-explain validate <file>.mdx --json
   

   诊断格式为 CODE line:column message。修复所有 error 并重新运行；有条件时也应处理警告。
6. 编译：npx concept-atlas-dense-explain <file>.mdx --mode atlas|scroll [-o out.html] [--skin <id>] [--default-mode dark|light|system] [--style <id>]。除非指定 -o，否则会在 MDX 文件旁生成独立的 HTML。验证错误会中止构建（--no-validate 会强制执行明知有问题的构建）。<Mermaid> 图表由 Pele 渲染并内嵌到 HTML 中，因此页面是完全离线的单文件，无需调用 CDN——不需要任何标志。
7. 外观（可选）： 页面自带面向读者的外观菜单——调色板（aurora 靛蓝、ember 金色、verdant 森林绿、sakura 粉梅色、noir 墨色）、深色／浅色切换，以及组件样式包（manuscript 编辑式边注、classic 带边框卡片、shadcn 细线边框极简 UI、elastic 带边框的可观测性面板）。默认配置为 aurora × manuscript × light；选择会通过 localStorage 在两种载体间持久保存。使用 --skin ember --default-mode dark --style classic（或在仓库构建中使用 CONCEPT_ATLAS_SKIN / CONCEPT_ATLAS_DEFAULT_MODE / CONCEPT_ATLAS_STYLE）设置不同的编译时默认值；--default-mode 接受 dark／light，并会将 system 解析为载体默认值（light）。只有用户提出要求时才设置默认外观——内容 MDX 不会设置外观。
8. 处理多份文档时，在一次调用中传入全部文件：npx concept-atlas-dense-explain a.mdx b.mdx c.mdx -o dist [--concurrency 3]（此时 -o 指定目录；所有文件先完成验证，然后并行构建）。构建时只会打包内容实际使用的渲染器：不使用 <Math> 就不会内嵌 KaTeX 的约 1.4MB 字体；不使用 <Mermaid> 就会完全省略 Pele。切勿添加虚设的 <Math>／<Mermaid> 节点来“启用”它们。
9. 报告页面外壳、输出路径、验证结果（错误／警告）和限制。不要声称验证过未经确认的交互。

承载结构

• atlas：ExplainPage → ConceptGraph → ConceptNode，以及 Children/ConceptRef 和跨分支的 Relation。恰好有一个 L0 根节点、多个 L1 分支，深度可达 L3/L4。共享组件位于节点内部。ConceptNode 还接受可选的 kind（参见编写规则），用于标记节点的知识角色，与节点层级无关。
• scroll：ScrollDocument → ScrollHeader + ScrollSection（+ ScrollProse、ScrollGrid）。共享组件位于章节内部。外壳会根据章节标题自动生成目录和阅读进度——不要手动构建导航。
• 浏览器标签页标题来自外壳，而非构建标志：ExplainPage title（atlas）或 ScrollHeader title（scroll）会成为 <title>，因此请使用真实、具体的名称——不要使用“主题名称”之类的占位符。每个页面都使用固定的 📃 图标。
• 绝不要让同一个 MDX 文件同时使用两种外壳。切换外壳时，只转换外层结构。

组件和属性参考

组件目录、所有属性的结构以及语法陷阱都在 references/components.md 中。编写内容前请先阅读；页面中遇到新标签时，务必按组件名称查阅——属性名称和结构不能靠猜。图表、学习循环、来源信息、数据／行为和结构组件都在其中有完整说明；下文只重复每个页面都必须遵守的规则。

编写规则

• 保持 MDX 语义。绝不编写 CSS、坐标、SVG 或替代应用代码；绝不虚构组件名称或属性。
• 为每个重要节点提供一个体现主张的标题、一句 summary，以及实际内容（Definition、Mechanism、Example、Boundary、Evidence、模型、图表或数学公式）。不要在 Overview、Definition 和 Insight 中重复相同文本。
• kind（可选，atlas）：独立于 level，标记节点的知识角色。可选值为 system、stage、mechanism、artifact、failure、tool、boundary、decision 之一。它会启用图谱的“知识类型”筛选器和节点徽标，因此只在角色明确时使用，不要给每个节点都添加。声明 kind 后，会触发两项可选契约：kind="mechanism" 应包含 Invariant 或 Evidence；kind="failure" 应包含 FailureMode（带有 symptom/cause/evidence/remedy）。
• 数组属性必须是对象数组：Flow steps={[{title, description}]}、Timeline events={[{label, content}]}、MatrixModel cells={[{title, description, tone}]}、DecisionMatrix headers={[...]} rows={[[...]]}、Chart data={[{label, value}]}、References items={[{id, authors, year, title, url, source}]}。如果数组属性接收字符串或非数组，验证器会发出警告（PROP_EXPECTS_ARRAY）。
• Relation type 必须是 prerequisite、causes、produces、uses、implements、contrasts、depends-on、exception-of、precedes 之一，并且每个 Relation 都需要 label。父子层级是隐式的（通过 parent 和 Children/ConceptRef 表示）——不要用 Relation 表达。
• 数学公式：MDX 会将子内容中的 { ... } 解析为表达式，因此要通过 formula 传入带花括号或反斜杠的 LaTeX：<Math formula="r_{\text{ann}} = (1 + r)^{12} - 1" />、<MathBlock formula="I(x) = -\log_2 p(x)" variables={[{symbol, description}]} />。不含花括号的子内容（如 <Math>\log_2 N</Math>）可以直接使用。验证器会发出警告（MATH_CHILDREN_BRACES）。
• 代码：将代码作为字符串通过 code 传入（或作为子内容传入），并用模板字面量包裹，以免 MDX 将其解析为表达式：<CodeBlock language="bash" lineNumbers>{npm run validate}</CodeBlock>。徽标、说明文字和换行规则见 references/components.md。
• 图示：始终设置 alt；使用 id 和 <FigureRef> 编号，绝不要手动写“图 N”；相对链接与 --inline-assets 之间需要权衡文件大小——应与用户商定，不要擅自决定。
• 引用/参考文献：<Cite id="..." /> 会根据对应条目在 <References items={...} /> 中的位置，渲染为 [n]。在 atlas 中，引用和 References 区块必须放在同一节点，因为只有在节点展开时，节点内容才会渲染。
• 连续阅读效果通过外壳配置，而非手动编写 CSS：使用 spacing="compact|comfortable|airy" 设置阅读节奏，使用 fontSize="compact|normal|large|xlarge"（或数值形式的 scale/lineHeight）设置文字大小。

验证诊断

validate 和构建过程会输出 CODE line:column message。构建前修复所有 error；references/diagnostics.md 列出了可能遇到的代码，并区分错误和警告。NO_ROOT_LEVEL、MULTIPLE_ROOT_LEVEL、MECHANISM_KIND_UNVERIFIED 和 FAILURE_KIND_UNSTRUCTURED 都是警告，但 --strict 会将其升级为错误。

报告前检查

• 所有 error 诊断均已解决（或已明确说明使用 --no-validate 的理由）。
• 所有 ConceptRef、Relation 端点和 ConceptGraph root 均指向现有节点 ID。
• 每个节点都有 title + summary；每个 Relation 都有 label。
• 含有 <Mermaid> 的页面已完全离线：Pele 使用内联资源，因此无需 CDN 标志。
• HTML 文件存在于报告的路径下。

如果 npx 无法连接到注册表，请报告这一阻碍。绝不要将实现文件复制到 skill 目录。