concept-atlas-dense-explain 0.1.0

package/skill/assets/template/src/model/normalize-content.js

@@ -0,0 +1,238 @@
+import React, { Children, isValidElement } from 'react';
+
+/**
+ * Extracts structured node and relation data from MDX / React component elements
+ */
+export function extractConceptData(explainPageElement) {
+  // MDX exports a component rather than an already-expanded element.
+  // Resolve that wrapper before reading page metadata or its children.
+  explainPageElement = unwrapComponent(explainPageElement);
+
+  const result = {
+    meta: {
+      id: explainPageElement.props.id || 'explain-page',
+      title: explainPageElement.props.title || '',
+      summary: explainPageElement.props.summary || '',
+      rootId: null,
+      layout: explainPageElement.props.layout || 'editorial',
+      density: explainPageElement.props.density || 'reading',
+    },
+    nodes: [],
+    relations: []
+  };
+
+  function traverse(child) {
+    if (!child || !isValidElement(child)) return;
+
+    const componentName = getComponentName(child);
+
+    // MDX compiles to a component function. The element passed from main.jsx
+    // has no children until that function is evaluated, so unwrap non-semantic
+    // component wrappers before walking the semantic tree.
+    if (typeof child.type === 'function' && !isSemanticComponent(componentName)) {
+      traverse(child.type(child.props));
+      return;
+    }
+
+    if (componentName === 'ConceptGraph') {
+      if (child.props.root) {
+        result.meta.rootId = child.props.root;
+      }
+      Children.forEach(child.props.children, traverse);
+      return;
+    }
+
+    if (componentName === 'ConceptNode') {
+      const nodeData = parseConceptNode(child);
+      result.nodes.push(nodeData);
+      return;
+    }
+
+    if (componentName === 'Relation') {
+      result.relations.push({
+        from: child.props.from,
+        to: child.props.to,
+        type: child.props.type || 'depends-on',
+        label: child.props.label,
+        description: child.props.description || child.props.children || ''
+      });
+      return;
+    }
+
+    if (child.props && child.props.children) {
+      Children.forEach(child.props.children, traverse);
+    }
+  }
+
+  if (explainPageElement.props && explainPageElement.props.children) {
+    Children.forEach(explainPageElement.props.children, traverse);
+  }
+
+  return result;
+}
+
+function unwrapComponent(element) {
+  let current = element;
+  while (
+    current &&
+    isValidElement(current) &&
+    typeof current.type === 'function' &&
+    !isSemanticComponent(getComponentName(current))
+  ) {
+    current = current.type(current.props);
+  }
+  return current;
+}
+
+const SEMANTIC_COMPONENTS = new Set([
+  'ExplainPage',
+  'ConceptGraph',
+  'ConceptNode',
+  'ConceptRef',
+  'Children',
+  'Relation',
+  'Overview',
+  'Definition',
+  'Mechanism',
+  'Input',
+  'Output',
+  'Prerequisite',
+  'Implementation',
+  'Example',
+  'Counterexample',
+  'Boundary',
+  'Glossary',
+  'Mermaid',
+  'RelationMap',
+  'Insight',
+  'NoteGrid',
+  'Stack',
+  'Grid',
+  'Split',
+  'Tabs',
+  'RelationPath',
+  'LearningObjectives',
+  'KeyQuestion',
+  'Evidence',
+  'Invariant',
+  'FailureMode',
+  'Tradeoff',
+]);
+
+function isSemanticComponent(name) {
+  return SEMANTIC_COMPONENTS.has(name);
+}
+
+function getComponentName(element) {
+  if (!element || !element.type) return '';
+  if (typeof element.type === 'string') return element.type;
+  return element.type.displayName || element.type.name || '';
+}
+
+function parseConceptNode(nodeElement) {
+  const props = nodeElement.props;
+  const node = {
+    id: props.id,
+    title: props.title || props.id,
+    level: props.level || 'L2',
+    parent: props.parent !== undefined ? props.parent : null,
+    children: [],
+    summary: props.summary || '',
+    overview: null,
+    definition: null,
+    mechanism: null,
+    input: props.input || null,
+    output: props.output || null,
+    prerequisites: [],
+    implementation: null,
+    examples: [],
+    counterexamples: [],
+    boundaries: [],
+    glossary: [],
+    customSections: []
+  };
+
+  Children.forEach(props.children, child => {
+    if (!child || !isValidElement(child)) return;
+    const name = getComponentName(child);
+
+    switch (name) {
+      case 'Overview':
+        node.overview = child.props.children;
+        if (!node.summary && typeof child.props.children === 'string') {
+          node.summary = child.props.children.trim();
+        }
+        break;
+      case 'Definition':
+        node.definition = child.props.children;
+        break;
+      case 'Mechanism':
+        node.mechanism = child.props.children;
+        break;
+      case 'Input':
+        node.input = child.props.children;
+        break;
+      case 'Output':
+        node.output = child.props.children;
+        break;
+      case 'Prerequisite':
+        if (typeof child.props.children === 'string') {
+          node.prerequisites.push(child.props.children);
+        } else if (Array.isArray(child.props.children)) {
+          node.prerequisites.push(...child.props.children);
+        } else {
+          node.prerequisites.push(child.props.children);
+        }
+        break;
+      case 'Implementation':
+        node.implementation = {
+          language: child.props.language || 'text',
+          title: child.props.title || '代码实现',
+          code: child.props.children
+        };
+        break;
+      case 'Example':
+        node.examples.push({
+          title: child.props.title || '典型示例',
+          content: child.props.children
+        });
+        break;
+      case 'Counterexample':
+        node.counterexamples.push({
+          title: child.props.title || '边界反例 / 常见误区',
+          content: child.props.children
+        });
+        break;
+      case 'Boundary':
+        node.boundaries.push({
+          title: child.props.title || '边界条件 / 约束',
+          content: child.props.children
+        });
+        break;
+      case 'Glossary':
+        node.glossary.push({
+          term: child.props.term,
+          definition: child.props.children
+        });
+        break;
+      case 'Children':
+        Children.forEach(child.props.children, ref => {
+          if (isValidElement(ref) && (getComponentName(ref) === 'ConceptRef' || ref.props.id)) {
+            node.children.push(ref.props.id);
+          }
+        });
+        break;
+      case 'ConceptRef':
+        if (child.props.id) {
+          node.children.push(child.props.id);
+        }
+        break;
+      default:
+        // Semantic presentation components inside node
+        node.customSections.push(child);
+        break;
+    }
+  });
+
+  return node;
+}

package/skill/assets/template/src/model/relation-types.js

@@ -0,0 +1,90 @@
+export const RELATION_TYPES = {
+  'parent-child': {
+    label: '父子层级',
+    description: '表达概念归属与分解层级',
+    color: '#87a6ff',
+    strokeDasharray: 'none',
+    hasArrow: true,
+    isTree: true
+  },
+  'prerequisite': {
+    label: '前置知识',
+    description: '理解当前概念所需的前置基础',
+    color: '#f1bc74',
+    strokeDasharray: '4 4',
+    hasArrow: true,
+    isTree: false
+  },
+  'causes': {
+    label: '因果推动',
+    description: '引起或触发后续状态变化',
+    color: '#ef8585',
+    strokeDasharray: 'none',
+    hasArrow: true,
+    isTree: false
+  },
+  'produces': {
+    label: '产出生成',
+    description: '阶段处理后产出的产物或实体',
+    color: '#72d0a1',
+    strokeDasharray: 'none',
+    hasArrow: true,
+    isTree: false
+  },
+  'uses': {
+    label: '消费使用',
+    description: '调用或引用其他概念与数据',
+    color: '#38bdf8',
+    strokeDasharray: '6 3',
+    hasArrow: true,
+    isTree: false
+  },
+  'implements': {
+    label: '实现关系',
+    description: '具体机制或代码实现特定抽象',
+    color: '#c084fc',
+    strokeDasharray: 'none',
+    hasArrow: true,
+    isTree: false
+  },
+  'contrasts': {
+    label: '对比关系',
+    description: '概念间的异同对照或对立维度',
+    color: '#fb923c',
+    strokeDasharray: '2 2',
+    hasArrow: false,
+    isTree: false
+  },
+  'depends-on': {
+    label: '依赖关系',
+    description: '运行或生效依赖外部条件',
+    color: '#94a3b8',
+    strokeDasharray: '5 5',
+    hasArrow: true,
+    isTree: false
+  },
+  'exception-of': {
+    label: '异常/反例',
+    description: '特殊情况、破坏假定的边界或反例',
+    color: '#f43f5e',
+    strokeDasharray: '3 3',
+    hasArrow: true,
+    isTree: false
+  },
+  'precedes': {
+    label: '时序先后',
+    description: '时间或处理流水线的前后相继',
+    color: '#2dd4bf',
+    strokeDasharray: 'none',
+    hasArrow: true,
+    isTree: false
+  }
+};
+
+export const LEVEL_DEFS = {
+  L0: { name: '全局概览', tag: 'L0 · 全局概览', desc: '系统全貌与全局定位', color: '#818cf8' },
+  L1: { name: '主要阶段 / 子系统', tag: 'L1 · 子系统', desc: '主要生命周期阶段或子系统划分', color: '#38bdf8' },
+  L2: { name: '局部机制', tag: 'L2 · 局部机制', desc: '具体工作机制与逻辑流动', color: '#34d399' },
+  L3: { name: '实现细节', tag: 'L3 · 实现细节', desc: '算法、数据结构或代码实现', color: '#fbbf24' },
+  L4: { name: '边界与反例', tag: 'L4 · 边界反例', desc: '边界情况、异常分支与典型反例', color: '#f87171' }
+};