@bytechain.cn/colamd 1.5.0 → 1.5.1-beta.2

package/docs/demo.md

@@ -0,0 +1,546 @@
+# ColaMD 插件演示文档
+
+> 本文档用于演示 ColaMD 扩展版的 **Math 公式渲染** 与 **Mermaid 图表渲染** 能力。\
+> 每个插件均支持 **Rendered（渲染模式）** 和 **Raw（源码模式）** 一键切换。
+
+***
+
+## 一、Math 数学公式
+
+### 1.1 行内公式（Inline Math）
+
+行内公式使用单个 `$` 包裹，可嵌入段落中：
+
+* 质能方程：$E = mc^2$
+
+* 欧拉公式：$e^{i\pi} + 1 = 0$
+
+* 勾股定理：$a^2 + b^2 = c^2$
+
+* 导数定义：$f'(x) = \lim_{h \to 0} \frac{f(x+h) - f(x)}{h}$
+
+* 求和公式：$\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n$
+
+* 积分公式：$\int_a^b f(x)\,dx = F(b) - F(a)$
+
+### 1.2 块级公式（Block Math）
+
+块级公式使用 `$$` 包裹，居中显示：
+
+**二次方程求根公式：**
+
+$$
+x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
+$$
+
+**高斯积分：**
+
+$$
+\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
+$$
+
+**傅里叶变换：**
+
+$$
+\hat{f}(\xi) = \int_{-\infty}^{\infty} f(x)\, e^{-2\pi i x \xi}\, dx
+$$
+
+**麦克斯韦方程组（微分形式）：**
+
+$$
+\begin{cases}
+\nabla \cdot \mathbf{E} = \dfrac{\rho}{\varepsilon_0} \\[8pt]
+\nabla \cdot \mathbf{B} = 0 \\[8pt]
+\nabla \times \mathbf{E} = -\dfrac{\partial \mathbf{B}}{\partial t} \\[8pt]
+\nabla \times \mathbf{B} = \mu_0 \mathbf{J} + \mu_0 \varepsilon_0 \dfrac{\partial \mathbf{E}}{\partial t}
+\end{cases}
+$$
+
+**爱因斯坦场方程：**
+
+$$
+G_{\mu\nu} + \Lambda g_{\mu\nu} = \frac{8\pi G}{c^4} T_{\mu\nu}
+$$
+
+**矩阵形式：**
+
+$$
+\mathbf{A} = \begin{bmatrix}
+a_{11} & a_{12} & a_{13} \\
+a_{21} & a_{22} & a_{23} \\
+a_{31} & a_{32} & a_{33}
+\end{bmatrix},
+\quad
+\mathbf{A}^{-1} = \frac{1}{\det(\mathbf{A})} \begin{bmatrix}
+C_{11} & C_{21} & C_{31} \\
+C_{12} & C_{22} & C_{32} \\
+C_{13} & C_{23} & C_{33}
+\end{bmatrix}
+$$
+
+***
+
+## 二、Mermaid 图表
+
+### 2.1 流程图（Flowchart / Graph）
+
+```mermaid
+graph TD
+    A[开始] --> B{条件判断}
+    B -->|条件成立| C[执行操作1]
+    B -->|条件不成立| D[执行操作2]
+    C --> E[结束]
+    D --> E
+```
+
+### 2.2 时序图（Sequence Diagram）
+
+```mermaid
+sequenceDiagram
+    participant U as 用户
+    participant C as ColaMD
+    participant A as AI Agent
+    participant F as 文件系统
+
+    U->>C: 打开 .md 文件
+    C->>F: fs.watch 监听文件
+    A->>F: 修改文件内容
+    F-->>C: 触发变更事件
+    C-->>U: 实时刷新显示
+    U->>C: 切换 Rendered/Raw 模式
+    C-->>U: 渲染公式与图表
+```
+
+### 2.3 类图（Class Diagram）
+
+```mermaid
+classDiagram
+    class PluginManager {
+        +Map plugins
+        +register(plugin)
+        +get(id)
+        +toggle(id, mode)
+    }
+
+    class MathPlugin {
+        +String id = "math"
+        +render(node)
+        +toRaw(node)
+        +exportPNG(node)
+    }
+
+    class MermaidPlugin {
+        +String id = "mermaid"
+        +render(node)
+        +toRaw(node)
+        +exportPNG(node)
+    }
+
+    PluginManager --> MathPlugin : manages
+    PluginManager --> MermaidPlugin : manages
+```
+
+### 2.4 状态图（State Diagram）
+
+```mermaid
+stateDiagram-v2
+    [*] --> 编辑中
+    编辑中 --> 渲染中 : 输入完成
+    渲染中 --> 渲染成功 : KaTeX/Mermaid 渲染成功
+    渲染中 --> 渲染失败 : 语法错误
+    渲染失败 --> 编辑中 : 修正代码
+    渲染成功 --> 编辑中 : 点击 Raw 模式
+    渲染成功 --> [*] : 导出 PNG
+```
+
+### 2.5 ER 图（Entity Relationship）
+
+```mermaid
+erDiagram
+    USER ||--o{ DOCUMENT : creates
+    USER {
+        string id PK
+        string name
+        string email
+    }
+    DOCUMENT {
+        string id PK
+        string title
+        string content
+        datetime created_at
+        string user_id FK
+    }
+    DOCUMENT ||--o{ PLUGIN_NODE : contains
+    PLUGIN_NODE {
+        string id PK
+        string type
+        string raw_content
+        string document_id FK
+    }
+```
+
+### 2.6 甘特图（Gantt Chart）
+
+```mermaid
+gantt
+    title ColaMD 扩展版开发计划
+    dateFormat  YYYY-MM-DD
+
+    section 基础架构
+    插件系统设计           :a1, 2026-01-01, 14d
+    插件管理器实现         :a2, after a1, 10d
+
+    section Math 插件
+    KaTeX 集成             :b1, after a2, 7d
+    行内/块级公式渲染       :b2, after b1, 10d
+    PNG 导出功能           :b3, after b2, 5d
+
+    section Mermaid 插件
+    Mermaid.js 集成        :c1, after a2, 7d
+    多图表类型支持         :c2, after c1, 14d
+    主题适配               :c3, after c2, 7d
+
+    section 测试与发布
+    集成测试               :d1, after b3, 7d
+    文档编写               :d2, after c3, 5d
+    版本发布               :d3, after d1, 3d
+```
+
+### 2.7 饼图（Pie Chart）
+
+```mermaid
+pie title ColaMD 用户操作系统分布
+    "macOS" : 45
+    "Windows" : 35
+    "Linux" : 15
+    "其他" : 5
+```
+
+### 2.8 用户旅程图（User Journey）
+
+```mermaid
+journey
+    title 用户使用 ColaMD 的工作流
+    section 打开文件
+      启动应用: 5: 用户
+      打开 .md: 5: 用户
+    section 编辑内容
+      输入 Markdown: 4: 用户
+      插入公式: 4: 用户, AI
+      插入图表: 4: 用户, AI
+    section 查看效果
+      实时渲染: 5: 用户
+      切换模式: 4: 用户
+      导出 PNG: 3: 用户
+```
+
+### 2.9 Git 图（Git Graph）
+
+```mermaid
+gitGraph
+    commit id: "初始提交"
+    branch develop
+    checkout develop
+    commit id: "添加 Math 插件"
+    commit id: "添加 Mermaid 插件"
+    checkout main
+    merge develop id: "合并插件系统" tag: "v2.0.0"
+    branch hotfix
+    checkout hotfix
+    commit id: "修复渲染 bug"
+    checkout main
+    merge hotfix id: "应用热修复" tag: "v2.0.1"
+    checkout develop
+    commit id: "新增主题适配"
+```
+
+### 2.10 思维导图（Mindmap）
+
+```mermaid
+mindmap
+  root((ColaMD))
+    编辑器
+      所见即所得
+      实时同步
+      智能换行
+    插件系统
+      Math 公式
+        行内公式
+        块级公式
+        PNG 导出
+      Mermaid 图表
+        流程图
+        时序图
+        类图
+        甘特图
+    导出功能
+      PDF
+      HTML
+      幻灯片
+    主题系统
+      Light
+      Dark
+      Elegant
+      Newsprint
+```
+
+### 2.11 时间线（Timeline）
+
+```mermaid
+timeline
+    title ColaMD 版本演进
+    2024 Q1 : v1.0 发布
+            : 基础编辑器功能
+    2024 Q2 : v1.2 发布
+            : 实时文件热更新
+            : 主题系统
+    2024 Q3 : v1.4 发布
+            : 幻灯片系统
+    2025 Q1 : v1.5 发布
+            : 幻灯片导出
+    2026 Q1 : v2.0 发布
+            : 显示插件系统
+            : Math + Mermaid
+```
+
+### 2.12 四象限图（Quadrant Chart）
+
+```mermaid
+quadrantChart
+    title 编辑器功能优先级矩阵
+    x-axis 低影响 --> 高影响
+    y-axis 低紧迫性 --> 高紧迫性
+    quadrant-1 立即实施
+    quadrant-2 计划实施
+    quadrant-3 低优先级
+    quadrant-4 考虑放弃
+
+    "实时同步": [0.9, 0.95]
+    "Math 公式": [0.85, 0.8]
+    "Mermaid 图表": [0.8, 0.75]
+    "主题系统": [0.6, 0.5]
+    "云同步": [0.4, 0.3]
+    "协作编辑": [0.3, 0.2]
+```
+
+### 2.13 XY 图表 / 柱状图（XY Chart）
+
+```mermaid
+xychart-beta
+    title "ColaMD 月活跃用户增长"
+    x-axis ["1月", "2月", "3月", "4月", "5月", "6月"]
+    y-axis "用户数 (千)" 0 --> 50
+    bar [12, 18, 25, 32, 40, 48]
+    line [12, 18, 25, 32, 40, 48]
+```
+
+### 2.14 C4 架构图（C4Context）
+
+```mermaid
+C4Context
+    title ColaMD 系统上下文图
+
+    Person(user, "用户", "使用 ColaMD 编辑 Markdown 文件")
+    System(colamd, "ColaMD", "Agent Native Markdown 编辑器")
+    System_Ext(agent, "AI Agent", "Claude Code / Cursor / Copilot 等")
+    System_Ext(filesystem, "文件系统", "本地 .md 文件")
+
+    Rel(user, colamd, "打开、编辑、查看文件")
+    Rel(agent, filesystem, "读写 .md 文件")
+    Rel(colamd, filesystem, "fs.watch 监听变更")
+    Rel(filesystem, colamd, "推送文件变更事件")
+```
+
+### 2.15 Sankey 图（Sankey Diagram）
+（桑吉图目前支持 beta 版本）
+```mermaid
+    sankey-beta
+    Agricultural 'waste',Bio-conversion,124.729
+    Bio-conversion,Liquid,0.597
+    Bio-conversion,Losses,26.862
+    Bio-conversion,Solid,280.322
+    Bio-conversion,Gas,81.144
+    Biofuel imports,Liquid,35
+    Biomass imports,Solid,35
+    Coal imports,Coal,11.606
+    Coal reserves,Coal,63.965
+    Coal,Solid,75.571
+    District heating,Industry,10.639
+    District heating,Heating and cooling - commercial,22.505
+    District heating,Heating and cooling - homes,46.184
+    Electricity grid,Over generation / exports,104.453
+    Electricity grid,Heating and cooling - homes,113.726
+    Electricity grid,H2 conversion,27.14
+    Electricity grid,Industry,342.165
+    Electricity grid,Road transport,37.797
+    Electricity grid,Agriculture,4.412
+    Electricity grid,Heating and cooling - commercial,40.858
+    Electricity grid,Losses,56.691
+    Electricity grid,Rail transport,7.863
+    Electricity grid,Lighting & appliances - commercial,90.008
+    Electricity grid,Lighting & appliances - homes,93.494
+    Gas imports,NGas,40.719
+    Gas reserves,NGas,82.233
+    Gas,Heating and cooling - commercial,0.129
+    Gas,Losses,1.401
+    Gas,Thermal generation,151.891
+    Gas,Agriculture,2.096
+    Gas,Industry,48.58
+    Geothermal,Electricity grid,7.013
+    H2 conversion,H2,20.897
+    H2 conversion,Losses,6.242
+    H2,Road transport,20.897
+    Hydro,Electricity grid,6.995
+    Liquid,Industry,121.066
+    Liquid,International shipping,128.69
+    Liquid,Road transport,135.835
+    Liquid,Domestic aviation,14.458
+    Liquid,International aviation,206.267
+    Liquid,Agriculture,3.64
+    Liquid,National navigation,33.218
+    Liquid,Rail transport,4.413
+    Marine algae,Bio-conversion,4.375
+    NGas,Gas,122.952
+    Nuclear,Thermal generation,839.978
+    Oil imports,Oil,504.287
+    Oil reserves,Oil,107.703
+    Oil,Liquid,611.99
+    Other waste,Solid,56.587
+    Other waste,Bio-conversion,77.81
+    Pumped heat,Heating and cooling - homes,193.026
+    Pumped heat,Heating and cooling - commercial,70.672
+    Solar PV,Electricity grid,59.901
+    Solar Thermal,Heating and cooling - homes,19.263
+    Solar,Solar Thermal,19.263
+    Solar,Solar PV,59.901
+    Solid,Agriculture,0.882
+    Solid,Thermal generation,400.12
+    Solid,Industry,46.477
+    Thermal generation,Electricity grid,525.531
+    Thermal generation,Losses,787.129
+    Thermal generation,District heating,79.329
+    Tidal,Electricity grid,9.452
+    UK land based bioenergy,Bio-conversion,182.01
+    Wave,Electricity grid,19.013
+    Wind,Electricity grid,289.366
+```
+
+### 2.16 Block 图（Block Diagram）
+
+```mermaid
+block-beta
+    columns 3
+    space:2
+    block:plugin_group:1
+        columns 1
+        math["Math Plugin"]
+        mermaid["Mermaid Plugin"]
+    end
+    space:2
+    editor["ColaMD Editor"]
+    space:2
+    user["用户"]
+    space:2
+
+    editor --> plugin_group
+    user --> editor
+```
+
+### 2.17 复杂流程图（带聚群）
+
+```mermaid
+graph TB
+    subgraph 输入层
+        A1[键盘输入]
+        A2[文件拖拽]
+        A3[Agent 修改]
+    end
+
+    subgraph 处理层
+        B1[Markdown 解析]
+        B2[Plugin 识别]
+        B3[渲染引擎]
+    end
+
+    subgraph 输出层
+        C1[富文本显示]
+        C2[源码显示]
+        C3[PNG 导出]
+    end
+
+    A1 --> B1
+    A2 --> B1
+    A3 --> B1
+    B1 --> B2
+    B2 -->|Math| B3
+    B2 -->|Mermaid| B3
+    B3 --> C1
+    B3 --> C2
+    B3 --> C3
+```
+
+***
+
+## 三、混合内容演示
+
+以下段落同时包含 **行内公式**、**块级公式** 和 **Mermaid 图表**，展示插件的协同工作能力：
+
+在机器学习领域，线性回归模型的损失函数定义为：
+
+$$
+J(\theta) = \frac{1}{2m} \sum_{i=1}^{m} \left( h_\theta(x^{(i)}) - y^{(i)} \right)^2
+$$
+
+其中 $h_\theta(x) = \theta^T x$ 是假设函数，$m$ 是样本数量。梯度下降算法的更新规则为：
+
+$$
+\theta_j := \theta_j - \alpha \frac{\partial}{\partial \theta_j} J(\theta)
+$$
+
+下面是一个机器学习工作流的流程图：
+
+```mermaid
+graph LR
+    A[原始数据] --> B[数据预处理]
+    B --> C[特征工程]
+    C --> D[模型训练]
+    D --> E{模型评估}
+    E -->|准确率达标| F[模型部署]
+    E -->|准确率不足| G[调参优化]
+    G --> D
+    F --> H[预测服务]
+```
+
+神经网络的反向传播可以用矩阵形式表示。设第 $l$ 层的误差为 $\delta^{(l)}$，则：
+
+$$
+\delta^{(l)} = \left( (W^{(l)})^T \delta^{(l+1)} \right) \odot \sigma'(z^{(l)})
+$$
+
+其中 $\odot$ 表示 Hadamard 积，$\sigma'$ 是激活函数的导数。
+
+***
+
+## 四、操作指南
+
+### 切换渲染模式
+
+1. 点击顶部菜单栏 **Plug**
+2. 选择 **Math** 或 **Mermaid**
+3. 点击 **Rendered** 查看渲染效果，或 **Raw** 查看/编辑源码
+
+### 导出为 PNG
+
+* **Math 公式**：右键点击公式 → **Save Equation as PNG**
+
+* **Mermaid 图表**：右键点击图表 → **Save Diagram as PNG**
+
+### 编辑源码
+
+1. 切换到 **Raw** 模式
+2. 在文本框中直接修改 LaTeX 或 Mermaid 代码
+3. 点击编辑器其他区域失焦，自动保存并重新渲染
+
+***
+
+> **提示**：本文档中的所有公式和图表均可在 **Rendered** 和 **Raw** 模式之间自由切换，体验 ColaMD 的插件渲染控制能力。