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

package/README_CN.md

@@ -11,7 +11,7 @@
 
 **本扩展版仓库**: [git@github.com:byteuser1977/ColaMD-extend.git](https://github.com/byteuser1977/ColaMD-extend)
 
-[功能特性](#功能特性) | [显示插件](#显示插件系统) | [Plug 菜单](#plug-菜单--插件渲染控制) | [快速开始](#快速开始) | [主题系统](#主题系统) | [技术架构](#技术架构) | [English](README.md)
+[功能特性](#功能特性) | [显示插件](#显示插件系统) | [Plug 菜单](#plug-菜单--插件渲染控制) | [快速开始](#快速开始) | [移动端构建](#移动端构建--capacitor-6) | [主题系统](#主题系统) | [技术架构](#技术架构) | [English](README.md)
 
 ***
 
@@ -38,18 +38,50 @@ AI Agent 正在改变我们的工作方式。它们编辑文件、生成文档
 | 公式支持  | ❌                               | ✅ KaTeX 行内/块级公式，实时编辑，PNG 导出         |
 | 图表支持  | ❌                               | ✅ Mermaid 全类型图表（17+ 种），多主题适配，PNG 导出 |
 | 双模式切换 | N/A                             | ✅ 每个插件均支持 **渲染模式 / 源码编辑模式** 一键切换    |
+| 移动端平台 | ❌ 仅桌面端                        | ✅ **Android (.apk) + iOS (.ipa)** 通过 Capacitor 6 实现  |
 
 > 原版所有功能完整保留：Agent 实时同步、活动指示器、所见即所得编辑器、幻灯片系统、主题与导出等。
 
 ### 演示文档
 
-本项目包含一份完整的演示文档 [`demo.md`](demo.md)，涵盖：
+本项目包含多份演示文档，全面展示插件能力：
+
+#### 通用演示 — [`demo.md`](docs/demo.md)
+
+一份综合性演示文档，涵盖：
 
 - **Math 公式**：7 个行内公式 + 6 个块级公式（含方程组、矩阵、物理公式等）
 - **Mermaid 图表**：17 种图表类型全部覆盖（流程图、时序图、类图、状态图、ER 图、甘特图、饼图、用户旅程图、Git 图、思维导图、时间线、四象限图、XY 图表、C4 架构图、Sankey 图、Block 图、复杂聚群图）
 - **混合内容**：公式与图表在同一文档中协同渲染
 
-打开 `demo.md` 即可全面测试 ColaMD 扩展版的插件渲染、模式切换、源码编辑和 PNG 导出功能。
+在 ColaMD 中打开 [`demo.md`](docs/demo.md) 即可全面测试插件渲染、模式切换、源码编辑和 PNG 导出功能：
+
+```bash
+# 方式一：命令行启动时直接打开
+npm run dev docs/demo.md
+
+# 方式二：在 ColaMD 中使用菜单打开
+# File → Open... → 选择 docs/demo.md
+
+# 方式三：在 ColaMD 编辑器中 Cmd+点击 demo.md 链接
+# 直接在浏览器中查看源码：https://github.com/byteuser1977/ColaMD-extend/blob/main/docs/demo.md
+```
+
+#### 学术论文演示 — [`academic-demo.md`](docs/academic-demo.md) 🆕
+
+一份真实的学术论文示例，展示增强版**学术论文主题**（`academic-paper.css`）的完整效果：
+
+- **完整学术结构**：摘要、关键词、中图分类号、文献标识码、引言、方法论、表格、参考文献
+- **符合 GB/T 7713 规范**：遵循中文学术论文排版标准，正确的字体搭配（黑体标题 + 宋体正文）
+- **三线表格式**：学术标准表格样式（顶线 + 表头底线 + 底线，无竖线）
+- **Mermaid 图表**：复杂的组织架构图，采用打印优化的自定义配色方案
+- **混合内容**：数学公式、Mermaid 图表、表格、引用在同一文档中协同展示
+
+在 ColaMD 中打开 [`academic-demo.md`](docs/academic-demo.md) 并启用**学术论文主题**，即可看到完整效果。本演示文档展示了：
+- 专业学术排版（黑体标题、宋体正文、首行缩进）
+- 打印优化的 Mermaid 图表渲染
+- 学术场景下的代码块和引用块样式
+- 脚注与参考文献区域格式化
 
 ***
 
@@ -108,9 +140,54 @@ page: YOUR NAME
 
 ### 📤 导出能力
 
-- **PDF / HTML 导出**
-- **幻灯片导出** — 单文件 HTML（图片 Base64 内联）或文件夹形式（含视频资源）
-- **公式 / 图表 PNG 导出** — 右键菜单一键导出为高清 PNG 图片（2x 缩放）
+ColaMD 提供多种导出方式，满足不同场景需求：
+
+#### 导出为 HTML
+
+**菜单路径**：File → Export HTML...
+
+将当前编辑器内容导出为**独立 HTML 文件**，特性包括：
+
+- **主题完整保留** — 导出文件包含当前主题的所有 CSS 变量（背景色、文字色、代码块配色、引用样式等），打开即可还原编辑器中的视觉效果
+- **公式渲染保留** — KaTeX 渲染的数学公式以 HTML+CSS 形式完整保留，通过 CDN 引入 KaTeX 样式表
+- **Mermaid 图表内联** — 渲染后的 SVG 图表直接嵌入 HTML，无需额外依赖，离线可查看
+- **排版优化** — 正文最大宽度 780px 居中排版，行高 1.75，代码块圆角样式，表格边框等细节完整
+- **零依赖分享** — 生成的 HTML 文件可直接用浏览器打开，无需安装任何软件
+
+**使用方法**：
+
+1. 在 ColaMD 中打开 `.md` 文件
+2. 点击菜单 **File → Export HTML...**
+3. 选择保存路径，即可生成 `.html` 文件
+
+> 💡 移动端（Android/iOS）导出 HTML 后会自动调用系统分享面板，可直接发送到微信、邮件等应用。
+
+#### 导出为 PDF
+
+**菜单路径**：File → Export PDF...
+
+将当前编辑器内容导出为 **A4 尺寸 PDF 文件**，特性包括：
+
+- **所见即所得** — 导出内容与编辑器中看到的完全一致，包括数学公式和 Mermaid 图表
+- **A4 分页** — 使用 `@page { margin: 15mm; size: A4 }` 规范分页，适合打印
+- **背景色保留** — 通过 `printBackground: true` 确保深色主题导出时背景色不丢失
+- **智能隐藏** — 导出时自动隐藏加载占位符和错误提示，确保输出干净
+
+**使用方法**：
+
+1. 在 ColaMD 中打开 `.md` 文件
+2. 点击菜单 **File → Export PDF...**
+3. 选择保存路径，即可生成 `.pdf` 文件
+
+> 💡 移动端（Android）导出 PDF 时会调用系统打印对话框，可选择"保存为 PDF"生成文件。
+
+#### 幻灯片导出
+
+- **File → Export Slides...** — 导出可分享版本（单文件 HTML 或含视频的文件夹）
+
+#### 公式 / 图表 PNG 导出
+
+- **右键菜单** — 右键点击公式或图表，选择"Save as PNG"一键导出为高清 PNG 图片（2x 缩放）
 
 ### 🎨 主题与跨平台（继承自原版）
 
@@ -239,6 +316,7 @@ graph TD
 | **Dark** | GitHub Dark | 系统默认 | `#0d1117` 背景, `#8b949e` 边框文字 |
 | **Elegant** | 自定义暖色系 | 霞鹜文楷 | `#e8e2db` 背景, 暖棕色调 cScale |
 | **Newsprint** | 印刷风格 | PT Serif | 衬线字体, 新闻纸质感 |
+| **Forest Ink** (自定义) | 森林墨绿系 | Noto Serif SC | `#f5f1e8` 宣纸底, `#3d6b4a` 森林绿强调, 墨绿连线 |
 
 ---
 
@@ -377,6 +455,218 @@ npm run dist:linux    # Linux (.AppImage / .deb)
 | macOS | `.dmg` |
 | Windows | `.exe` |
 | Linux | `.AppImage` / `.deb` |
+| Android | `.apk`（通过 Capacitor 构建） |
+| iOS | `.ipa`（通过 Capacitor 构建，需 Xcode） |
+
+---
+
+## 移动端构建 — Capacitor 6
+
+> 从 v1.5.1 起，ColaMD 支持通过 **[Capacitor 6](https://capacitorjs.com/)** 构建原生移动应用 — Ionic 出品的跨平台运行时。驱动 Electron 桌面端的同一套代码，现在也能运行在 Android 和 iOS 设备上。
+
+### 架构：双平台桥接层
+
+ColaMD 采用 **自动检测桥接层**，在运行时无缝切换 Electron（桌面端）和 Capacitor（移动端）API：
+
+```
+┌─────────────────────────────────────┐
+│         src/renderer/main.ts         │
+│   api = electronAPI || capacitorAPI  │ ← 自动检测运行环境
+├──────────────┬──────────────────────┤
+│  Electron    │     Capacitor 6      │
+│  (桌面端)     │     (移动端)          │
+│              │                      │
+│ IPC 通信      │ Filesystem Plugin    │
+│ dialog       │ Share Plugin         │
+│ shell.open   │ App Plugin           │
+│ fs 模块      │ localStorage 存储    │
+└──────────────┴──────────────────────┘
+```
+
+**核心文件**：
+- [`capacitor-api.ts`](src/renderer/capacitor-api.ts) — 完整的 Capacitor 桥接层，实现与 `electronAPI` 相同的 API 接口
+- [`capacitor.config.ts`](capacitor.config.ts) — Capacitor 配置文件（appId、webDir、插件设置）
+- [`mobile.css`](src/renderer/mobile.css) — 触控优化的响应式样式
+- [`MainActivity.java`](android/app/src/main/java/cn/bytechain/colamd/MainActivity.java) — Android WebView 中文输入法支持
+
+### 移动端技术栈
+
+| 组件 | 技术 | 用途 |
+|------|------|------|
+| **运行时** | Capacitor 6.x | 跨平台原生桥接 |
+| **WebView 引擎** | Android WebView / iOS WKWebView | 渲染 Web 内容 |
+| **文件访问** | `@capacitor/filesystem` | 读写本地文件 |
+| **文件选择器** | `@capawesome/capacitor-file-picker` | 原生文件选择对话框 |
+| **分享** | `@capacitor/share` | 系统分享面板集成 |
+| **应用生命周期** | `@capacitor/app` | 处理应用事件（暂停、恢复） |
+| **状态栏** | `@capacitor/status-bar` | 状态栏样式控制 |
+| **触觉反馈** | `@capacitor/haptics` | 触觉反馈 |
+
+### 移动端构建环境要求
+
+| 平台 | 环境要求 |
+|------|----------|
+| **Android** | Android Studio + SDK (API 34+) + **Java 21** (`brew install openjdk@21`) |
+| **iOS** | Xcode 15+ + CocoaPods + macOS |
+
+### 快速开始 — Android
+
+```bash
+# 1. 安装依赖（包含 Capacitor 相关包）
+npm install
+
+# 2. 构建前端 Web 资源
+npm run build
+
+# 3. 同步到 Android 平台
+npx cap sync android
+
+# 4. 用 Android Studio 打开项目
+npx cap open android
+
+# 5. 或直接构建 APK
+npm run cap:build:android
+# 输出路径：android/app/build/outputs/apk/debug/app-debug.apk
+```
+
+### 快速开始 — iOS
+
+```bash
+# 1. 同步到 iOS 平台
+npx cap sync ios
+
+# 2. 用 Xcode 打开项目
+npx cap open ios
+
+# 3. 在 Xcode 中构建（⌘R）或使用：
+npm run cap:build:ios
+```
+
+### 构建命令
+
+| 命令 | 说明 | 输出 |
+|------|------|------|
+| `npm run cap:sync` | 同步 Web 资源到所有原生平台 | 更新 `android/` 和 `ios/` |
+| `npm run cap:open:android` | 用 Android Studio 打开 Android 项目 | — |
+| `npm run cap:open:ios` | 用 Xcode 打开 iOS 项目 | — |
+| `npm run cap:run:android` | 构建 → 同步 → 在设备/模拟器上运行 | 设备上的实时应用 |
+| `npm run cap:run:ios` | 构建 → 同步 → 在模拟器上运行 | 模拟器中的实时应用 |
+| `npm run cap:build:android` | 构建 **Debug APK** | `android/app/build/outputs/apk/debug/app-debug.apk` |
+| `npm run cap:build:android:release` | 构建 **Release APK**（已签名） | `android/app/build/outputs/apk/release/app-release.apk` |
+| `npm run cap:build:ios` | 准备 iOS 项目供 Xcode 构建 | — |
+
+### Release 构建 — Android
+
+生产环境发布版本构建，项目已包含签名配置：
+
+```bash
+# 构建已签名的 Release APK
+npm run cap:build:android:release
+
+# 输出位置
+android/app/build/outputs/apk/release/app-release.apk
+```
+
+Release 签名密钥位于 `android/app/release.keystore`，签名凭据存储在 `build.gradle` 中。
+
+### Release 构建 — iOS
+
+1. 在 Xcode 中打开项目：
+   ```bash
+   npx cap open ios
+   ```
+
+2. 在 Xcode 中：
+   - 选择 **Product → Archive**
+   - 归档完成后，点击 **Distribute App**
+   - 选择分发方式（App Store Connect、Ad Hoc 等）
+
+3. 提交到 App Store：
+   - 在 Xcode 中配置签名证书
+   - 通过 Xcode 或 Transporter 上传到 App Store Connect
+
+### 中文输入法支持（Android）
+
+ColaMD 针对 Android WebView 上的中文/日文/韩文输入法进行了特殊处理：
+
+**实现方式**（[`MainActivity.java`](android/app/src/main/java/cn/bytechain/colamd/MainActivity.java)）：
+- WebView 焦点优化，确保 IME 正确连接
+- 获得焦点时自动弹出软键盘
+- 启用触控模式的焦点能力
+
+**已知限制**：
+- ProseMirror/Milkdown 在 Android WebView 上存在已知的 IME 组合输入问题
+- 部分输入法可能需要点击编辑区域才能激活
+- 如果输入无响应，尝试点击其他区域后再回到编辑器
+
+### 文件选择器集成
+
+移动端使用 `@capawesome/capacitor-file-picker` 实现原生文件选择：
+
+```typescript
+// 内部使用示例
+const result = await FilePicker.pickFiles({
+  types: ['text/markdown', 'text/plain'],
+  multiple: false,
+  readData: true,
+})
+```
+
+**支持的文件类型**：`.md`、`.markdown`、`.txt`、`.css`（主题文件）
+
+### 移动端功能支持情况
+
+| 功能 | 状态 | 说明 |
+|------|------|------|
+| Markdown 编辑 ✏️ | ✅ 完整支持 | Milkdown 编辑器在 WebView 中正常运行 |
+| 数学公式渲染 (KaTeX) 📐 | ✅ 完整支持 | 与桌面端一致 |
+| Mermaid 图表渲染 🔀 | ✅ 完整支持 | SVG 在 WebView 中正常渲染 |
+| 插件系统 | ✅ 完整支持 | 通过 UI 切换，状态存储于 localStorage |
+| 主题系统 | ✅ 完整支持 | 所有主题在移动端均可正常工作 |
+| 文件打开/保存 | ✅ 支持 | 通过 FilePicker 插件使用原生文件选择器 |
+| 中文/日文/韩文输入 | ⚠️ 部分支持 | 已实现 IME 支持，可能存在边缘情况 |
+| 导出 HTML/PDF | ⚠️ 部分支持 | HTML 导出正常；PDF 使用 `window.print()` |
+| Agent 文件监听 | ⚠️ 轮询模式 | 使用 2 秒间隔轮询替代 `fs.watch` |
+| 幻灯片预览 | ⚠️ 受限 | 桌面端打开新浏览器窗口；移动端基础可用 |
+| 外部链接 | ✅ 支持 | 通过 `_system` target 在系统浏览器中打开 |
+
+### 响应式设计
+
+移动端 CSS ([`mobile.css`](src/renderer/mobile.css)) 提供：
+
+- **触控优化**：禁用点击高亮、正确的 touch-action 行为
+- **安全区域适配**：自动为刘海屏设备添加内边距（iPhone X+、现代 Android）
+- **响应式断点**：
+  - ≤768px：平板布局调整
+  - ≤480px：手机布局，更小的字号
+- **编辑器适配**：固定定位编辑器填充标题栏下方视口
+- **滚动行为**：`-webkit-overflow-scrolling: touch` 实现流畅滚动
+- **右键菜单**：触控友好的更大点击区域（12px 内边距、15px 字号）
+
+### 移动端问题排查
+
+**中文输入无法使用**：
+- 点击编辑区域确保获得焦点
+- 尝试切换到其他应用再切回来
+- 检查软键盘是否可见
+
+**文件选择器无法打开**：
+- 确保已授予存储权限
+- Android 11+ 上，检查存储权限是否设为"始终允许"
+
+**应用启动崩溃**：
+- 运行 `npx cap sync android` 确保使用最新的 Web 资源
+- 在 Android Studio 中查看 logcat 错误日志
+- 确认 Java 21 配置正确
+
+**构建失败**：
+```bash
+# 清理并重新构建
+cd android
+./gradlew clean
+cd ..
+npm run cap:build:android
+```
 
 ---
 
@@ -391,32 +681,57 @@ ColaMD 内置 **4 个主题**，所有显示插件均会跟随主题自动适配
 | **Elegant** | `theme-elegant` | 优雅主题，暖色衬线体风格（默认主题） |
 | **Newsprint** | `theme-newsprint` | 新闻印刷风格 |
 
-自定义主题支持：将 CSS 文件放入 `~/.colamd/themes/` 目录，通过 **Theme > Import Theme** 导入。导入的主题会持久化保存，重启后仍然可用。
+可下载的外置主题（位于 [`themes/`](themes/) 目录）：
 
-从 [`themes/`](themes/) 文件夹可以下载社区贡献的主题。
+| 主题文件 | 风格说明 |
+|----------|----------|
+| [elegant.css](themes/elegant.css) | 典雅暖调，朱砂红强调色、霞鹜文楷衬线体 |
+| [guizang.css](themes/guizang.css) | 归藏古风，赭石强调色、松烟墨代码块 |
+| [forest-ink.css](themes/forest-ink.css) | 🌲 森林墨，宣纸暖白底 + 松烟墨绿文字 + 森林绿强调色 |
+| [academic-paper.css](themes/academic-paper.css) | 📄 **学术论文（增强版）** — 符合 GB/T 7713 规范，黑体标题 + 宋体正文，三线表格式，打印优化的 Mermaid 图表，脚注与参考文献样式。完整示例见 [`academic-demo.md`](docs/academic-demo.md) |
+| [pixso-design.css](themes/pixso-design.css) | 🎨 Pixso 设计，现代设计系统风格 |
+| [swiss-design.css](themes/swiss-design.css) | 🇨🇭 **瑞士国际主义平面设计风格** — 纯粹的黑白红三色体系，几何无衬线字体（Helvetica/Inter），网格化排版与大量留白，形式服从功能。极简克制的审美，灵感源自 Swiss International Typographic Style |
+
+自定义主题支持：将 CSS 文件放入 `~/.colamd/themes/` 目录，通过 **Theme > Import Theme** 导入。导入的主题会持久化保存，重启后仍然可用。
 
 ---
 
 ## 技术架构
 
 ```
-┌─────────────────────────────────────────────┐
-│                  Electron Shell               │
-│  ┌──────────┐  ┌───────────┐  ┌───────────┐  │
-│  │ Main     │  │ Preload   │  │ Renderer  │  │
-│  │ Process  │──│ IPC Bridge│──│ Process   │  │
-│  └──────────┘  └───────────┘  └─────┬─────┘  │
-│                                    │         │
-│                         ┌──────────▼────────┐ │
-│                         │    Milkdown Editor │ │
-│                         │  (ProseMirror)      │ │
-│                         │  ┌──────────────┐  │ │
-│                         │  │ Plugin System │  │ │
-│                         │  │ ├─ 📐 Math    │  │ │
-│                         │  │ └─ 🔀 Mermaid │  │ │
-│                         │  └──────────────┘  │ │
-│                         └───────────────────┘ │
-└─────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────┐
+│                    ColaMD — 双平台架构                        │
+│                                                              │
+│  ┌──────────────────────┐   ┌────────────────────────────┐  │
+│  │    桌面端 (Electron)  │   │     移动端 (Capacitor 6)    │  │
+│  │                       │   │                            │  │
+│  │  ┌─────────┐ ┌──────┐ │   │  ┌──────────────────────┐  │  │
+│  │  │主进程   │ │Preload│ │   │  │  Capacitor 运行时    │  │  │
+│  │  │        │ │Bridge │ │   │  │ (WebView / WKWebView) │  │  │
+│  │  └────┬────┘ └──┬───┘ │   │  └──────────┬───────────┘  │  │
+│  │       │  IPC   │     │   │             │ 原生插件       │  │
+│  │       └────┬────┘     │   │             ├─ Filesystem    │  │
+│  │            ▼          │   │             ├─ Share         │  │
+│  │  ┌─────────────────┐  │   │             ├─ App           │  │
+│  │  │   渲染进程       │  │   │             ├─ StatusBar     │  │
+│  │  │                │◄─┼───┼─────────────┤               │  │
+│  │  └────────┬────────┘  │   │            └─ Haptics       │  │
+│  │           ▼           │   └──────────────┬───────────────┘  │
+│  │  ┌──────────────────┐ │                  │                  │
+│  │  │  Milkdown 编辑器 │◄┘                  │                  │
+│  │  │  (ProseMirror)   │                    │                  │
+│  │  │  ┌────────────┐  │                    │                  │
+│  │  │  │插件系统    │  │                    │                  │
+│  │  │  │├─ 📐 Math  │  │                    │                  │
+│  │  │  │└─ 🔀Mermaid│  │                    │                  │
+│  │  │  └────────────┘  │                    │                  │
+│  │  └──────────────────┘                    │                  │
+│  └──────────────────────┘                    │                  │
+│                   ┌──────────────────────────┘                  │
+│                   ▼                                             │
+│          自动检测：                                              │
+│          api = electronAPI || capacitorAPI                      │
+└─────────────────────────────────────────────────────────────┘
 ```
 
 ### 技术栈
@@ -424,6 +739,7 @@ ColaMD 内置 **4 个主题**，所有显示插件均会跟随主题自动适配
 | 技术 | 用途 | 版本 | 官方文档 |
 |------|------|------|----------|
 | [Electron](https://www.electronjs.org/) | 跨平台桌面应用框架 | ^34.0.0 | [📖 文档](https://www.electronjs.org/docs/latest/) |
+| [Capacitor](https://capacitorjs.com/) | 跨平台移动端运行时（Android/iOS） | ^6.2.1 | [📖 文档](https://capacitorjs.com/docs/) |
 | [Milkdown](https://milkdown.dev/) | WYSIWYG Markdown 编辑器内核（基于 ProseMirror） | ^7.19.2 | [📖 文档](https://milkdown.dev/docs) |
 | [ProseMirror](https://prosemirror.net/) | 底层富文本编辑引擎 | — | [📖 文档](https://prosemirror.net/docs/) |
 | [KaTeX](https://katex.org/) | 数学公式渲染引擎 | ^0.16.46 | [📖 文档](https://katex.org/docs/) |
@@ -432,7 +748,7 @@ ColaMD 内置 **4 个主题**，所有显示插件均会跟随主题自动适配
 | [electron-vite](https://electron-vite.org/) | Electron 构建工具链 | ^3.0.0 | [📖 文档](https://electron-vite.org/guide/) |
 | [Vite](https://vitejs.dev/) | 底层构建引擎 | ^6.0.0 | [📖 文档](https://vitejs.dev/guide/) |
 
-> 💡 **开发提示**：各库的官方文档是开发新插件和自定义功能的最佳参考。特别是 [KaTeX 支持的语法](https://katex.org/docs/supported.html) 和 [Mermaid 图表语法](https://mermaid.js.org/intro/syntax-reference.html) 对扩展插件功能至关重要。
+> 💡 **开发提示**：各库的官方文档是开发新插件和自定义功能的最佳参考。特别是 [KaTeX 支持的语法](https://katex.org/docs/supported.html)、[Mermaid 图表语法](https://mermaid.js.org/intro/syntax-reference.html) 和 [Capacitor 插件 API](https://capacitorjs.com/docs/apis) 对跨平台扩展功能至关重要。
 
 ### 项目结构
 
@@ -441,12 +757,15 @@ src/
 ├── main/
 │   └── index.ts              # 主进程：窗口管理、文件 I/O、菜单、文件监听
 ├── preload/
-│   └── index.ts              # 安全 IPC 桥接层
+│   └── index.ts              # 安全 IPC 桥接层（Electron）
 └── renderer/
  ├── index.html            # 入口 HTML
- ├── main.ts               # 渲染进程入口，连接编辑器和 IPC
+ ├── main.ts               # 渲染进程入口，自动检测 Electron 或 Capacitor
+ ├── capacitor-api.ts      # ★ Capacitor 桥接层（移动端替代 Electron API）
+ ├── mobile.css            # ★ 触控优化的响应式样式
  ├── editor/
  │   ├── editor.ts         # 编辑器编排核心（插件集成）
+ │   └── plugins/          # ★ 显示插件系统
  │   ├── html-view.ts      # HTML 内联节点视图
  │   └── plugins/          # ★ 显示插件系统
  │       ├── index.ts      # 插件管理器（注册/查询/启停）
@@ -469,6 +788,139 @@ src/
 
 ---
 
+## 内联 SVG 规范指南
+
+> ⚠️ **重要提示**：ColaMD 使用 remark/rehype 解析 Markdown，其中**空行会被当作段落分隔符**。为了让内联 SVG 正确渲染，整个 HTML 块（包括 `<div>`、`<svg>`、`<p>` 标签）**必须写在一行内，不能有任何换行符**。
+
+### 为什么必须使用单行格式？
+
+ColaMD 的解析流程：
+
+```
+Markdown 源文件
+    ↓
+remark-parse (Markdown → MDAST)
+    ↓
+remark 插件处理
+    ↓
+空行检测：遇到空行 → 创建新的 paragraph 节点
+    ↓
+rehype (MDAST → HAST)
+    ↓
+ProseMirror 序列化
+    ↓ 每个 paragraph → 独立的 htmlSchema.node
+    ↓
+html-view.ts 注入到 DOM
+    ↓
+最终输出：<span class="milkdown-html-inline">单个块</span>
+```
+
+**多行格式的后果**：
+
+```html
+<!-- 如果 SVG 分成多行（有空行） -->
+
+Markdown:
+<div>
+<svg>
+  <defs>...</defs>
+
+  <rect/>
+
+  <circle/>
+</svg>
+</div>
+
+导出 HTML:
+<p><span>...<svg><defs>...</defs></svg></span></p>  ← 块1
+<p><span>  <rect/></span></p>                        ← 块2（独立！）
+<p><span>  <circle/></span></p>                      ← 块3（独立！）
+
+结果：❌ SVG 被拆成碎片，无法正确渲染
+```
+
+**单行格式的效果**：
+
+```html
+<!-- 整个内容在一行（无空行） -->
+
+Markdown:
+<div><svg><defs>...</defs><rect/><circle/></svg><p>图注</p></div>
+
+导出 HTML:
+<p><span>
+  <div><svg>完整内容</svg><p>图注</p></div>
+</span></p>
+
+结果：✅ 完整的 SVG 正确渲染
+```
+
+### SVG 规范要求
+
+| # | 规则 | 重要级 | 说明 |
+|---|------|--------|------|
+| 1 | 🔴 **单行压缩** | **必须** | 整个 `<div>` 块不能有换行 |
+| 2 | ✅ **标签闭包** | 必须 | 所有标签正确闭合或自闭合 |
+| 3 | ✅ **命名空间** | 必须 | 包含 `xmlns="http://www.w3.org/2000/svg"` |
+| 4 | ✅ **尺寸匹配** | 必须 | `width`/`height` 与 `viewBox` 一致 |
+| 5 | ✅ **双引号** | 推荐 | 所有属性值使用双引号 |
+| 6 | ✅ **ASCII字符** | 推荐 | 避免特殊符号，用 `-` 代替 `→` |
+
+### 示例：复杂内联 SVG
+
+```html
+<div style="text-align: center; margin: 20px 0;"><svg width="600" height="400" viewBox="0 0 600 400" xmlns="http://www.w3.org/2000/svg" style="display: block; margin: 0 auto; background: #f5f5f5; border-radius: 12px;"><defs><linearGradient id="grad1" x1="0%" y1="0%" x2="100%" y2="100%"><stop offset="0%" style="stop-color:#4A90E2;stop-opacity:1"/><stop offset="100%" style="stop-color:#357ABD;stop-opacity:1"/></linearGradient><linearGradient id="grad2" x1="0%" y1="0%" x2="100%" y2="0%"><stop offset="0%" style="stop-color:#7ED321;stop-opacity:1"/><stop offset="100%" style="stop-color:#5DB80D;stop-opacity:1"/></linearGradient></defs><rect width="600" height="400" fill="#f5f5f5" rx="12"/><rect x="40" y="40" width="520" height="60" rx="8" fill="url(#grad1)"/><text x="300" y="78" fill="white" text-anchor="middle" font-size="22" font-weight="bold">内联 SVG 示例</text><circle cx="150" cy="180" r="50" fill="url(#grad1)"/><text x="150" y="188" fill="white" text-anchor="middle" font-size="16" font-weight="bold">节点 A</text><rect x="250" y="130" width="100" height="100" rx="10" fill="url(#grad2)"/><text x="300" y="185" fill="white" text-anchor="middle" font-size="16" font-weight="bold">节点 B</text><polygon points="450,130 500,180 450,230 400,180" fill="#E74C3C"/><text x="450" y="188" fill="white" text-anchor="middle" font-size="14" font-weight="bold">节点 C</text><line x1="200" y1="180" x2="250" y2="180" stroke="#666" stroke-width="2" stroke-dasharray="5,5"/><line x1="350" y1="180" x2="400" y2="180" stroke="#666" stroke-width="2" stroke-dasharray="5,5"/><rect x="100" y="280" width="400" height="80" rx="8" fill="white" stroke="#ddd" stroke-width="1"/><text x="300" y="310" fill="#333" text-anchor="middle" font-size="14" font-weight="bold">三级火箭模型</text><text x="300" y="335" fill="#666" text-anchor="middle" font-size="12">材料 - 制造 - 平台</text></svg><p style="font-size: 10pt; color: #666; margin-top: 12px;">图：复杂内联 SVG 示例（单行压缩格式）</p></div>
+```
+
+### 对比：内联 vs 外联 SVG
+
+| 特性 | 内联 SVG | 外联 SVG |
+|------|---------|---------|
+| **适用场景** | 演示、学习、简单图标 | 生产环境、复杂图形 |
+| **代码位置** | Markdown 文件内 | 独立 `.svg` 文件 |
+| **格式要求** | 🔴 **必须单行压缩** | 无特殊要求 |
+| **可维护性** | ⚠️ 困难（长行难读） | ✅ 优秀（独立文件） |
+| **复杂度上限** | 受限于单行长度 | 无限制 |
+| **浏览器缓存** | ❌ 无法缓存 | ✅ 自动缓存 |
+
+### 最佳实践
+
+#### 适合使用内联 SVG 的场景：
+- ✅ 演示和学习目的
+- ✅ 简单图标（< 10 个元素）
+- ✅ 需要单文件交付
+- ✅ 快速原型开发
+
+#### 适合使用外联 SVG 的场景：
+- ✅ 生产环境文档
+- ✅ 复杂图形（> 20 个元素）
+- ✅ 需要频繁编辑和维护
+- ✅ 团队协作项目
+
+### 维护技巧
+
+1. **编辑时使用临时换行**
+   ```html
+   <!-- 开发阶段：可读格式 -->
+   <svg ...>
+     <rect .../>
+     <circle .../>
+   </svg>
+
+   <!-- 保存前：压缩为一行 -->
+   <svg ...><rect .../><circle .../></svg>
+   ```
+
+2. **使用代码编辑器的"合并行"功能**
+   - VS Code: `Ctrl+J` (Windows) / `Cmd+J` (Mac)
+   - WebStorm: `Ctrl+Shift+J`
+
+3. **版本控制友好**
+   - Git diff 会显示整行变更
+   - 可考虑使用 `.gitattributes` 处理长行
+
+---
+
 ## 致谢与版权
 
 ### 原版项目