Obsidian 可视化技能包技术分析

一、概述

1. 项目背景

axton-obsidian-visual-skills 是一个专为 Claude Code 设计的 Obsidian 可视化技能包，由 AI 教育者 Axton Liu 开发。该项目通过简单的 Markdown 技能文件，赋予 Claude Code 生成 Excalidraw、Mermaid 和 Canvas 三种类型可视化图表的能力。

2. 核心价值

传统可视化方案通常需要复杂的 MCP 服务器配置，而该项目采用基于 prompt 的技能扩展方式，用户只需复制 Markdown 文件到 Claude Code 技能目录即可使用。这种轻量级的设计理念，降低了 AI 辅助可视化工具的使用门槛。

3. 技术定位

项目目前处于实验性阶段（Experimental Status），主要用于演示工具和系统如何协同工作。作者明确表示，输出质量会根据模型版本和输入结构有所波动，暂未覆盖所有输入规模和边界情况。

二、系统架构

1. 整体架构

该技能包采用模块化设计，包含三个独立的技能模块，每个模块对应一种可视化类型。架构清晰，各模块职责明确，可以独立安装和使用。

graph TB
    User[用户输入] --> Claude[Claude Code]
    Claude --> Skills{技能路由}
    Skills -->|Excalidraw| E[Excalidraw Diagram]
    Skills -->|Mermaid| M[Mermaid Visualizer]
    Skills -->|Canvas| C[Canvas Creator]
    E --> Output1[.md with JSON]
    M --> Output2[Mermaid Code]
    C --> Output3[.canvas File]

2. 核心组件

A. Excalidraw Diagram Generator

生成手绘风格图表，输出为包含 Excalidraw JSON 的 Markdown 文件，可直接在 Obsidian 中打开编辑。

B. Mermaid Visualizer

将文本内容转换为专业的 Mermaid 图表，内置语法错误预防机制，适用于演示和文档场景。

C. Obsidian Canvas Creator

创建交互式 Obsidian Canvas 文件，支持 MindMap 和 Freeform 两种布局模式。

三、技术特性分析

1. Excalidraw 模块

A. 支持的图表类型

B. 核心特性

• 自动保存为 Excalidraw 插件兼容的 Markdown 文件
• 使用 Excalifont（fontFamily: 5）实现手绘美学效果
• 完整支持中文文本，正确处理中文字符
• 一致的调色板和样式指南

C. 触发词

Excalidraw、diagram、flowchart、mind map、画图、流程图、思维导图、可视化

2. Mermaid 模块

A. 支持的图表类型

• Process Flow（流程图）：展示工作流程、决策树、AI Agent 架构
• Circular Flow（循环图）：展示循环过程、反馈回路、持续改进
• Comparison Diagram（对比图）：前后对比、A vs B 分析
• Mindmap（思维导图）：层次概念、知识组织
• Sequence Diagram（时序图）：组件交互、API 调用、消息流
• State Diagram（状态图）：系统状态、状态转换、生命周期

B. 核心特性

• 内置语法错误预防（列表冲突、subgraph 命名、特殊字符处理）
• 可配置布局：垂直/水平、简单/标准/详细
• 专业的配色方案，具有语义含义
• 兼容 Obsidian、GitHub 和其他 Mermaid 渲染器

C. 触发词

Mermaid、visualize、flowchart、sequence diagram、可视化

3. Canvas 模块

A. 布局模式

B. 核心特性

• 基于内容长度的智能节点尺寸
• 自动创建带标签的关系边
• 6 种预设颜色 + 自定义十六进制颜色
• 防重叠的间距算法
• 支持节点分组进行视觉组织

C. 触发词

Canvas、mind map、visual diagram、思维导图

四、技术实现原理

1. 技能机制

Claude Code 的技能系统基于 prompt 扩展，而非传统的代码插件。每个技能是一个 SKILL.md 文件，Claude 会根据用户输入自动加载匹配的技能。

sequenceDiagram
    participant U as 用户
    participant C as Claude Code
    participant S as Skills 目录
    participant E as Excalidraw 插件
    participant O as Obsidian

    U->>C: 输入可视化需求
    C->>S: 检查触发词
    S-->>C: 返回匹配技能
    C->>C: 执行技能 prompt
    C->>E: 生成 Excalidraw JSON
    C->>O: 创建 .md 文件
    O->>E: 打开并渲染

2. 文件结构

项目采用清晰的模块化结构：

axton-obsidian-visual-skills/
├── excalidraw-diagram/
│   ├── SKILL.md              # 主技能定义
│   ├── assets/               # 示例输出
│   └── references/           # Excalidraw JSON 规范
├── mermaid-visualizer/
│   ├── SKILL.md
│   └── references/           # 语法规则和错误预防
├── obsidian-canvas-creator/
│   ├── SKILL.md
│   ├── assets/               # 模板 Canvas 文件
│   └── references/           # Canvas 规范和布局算法
├── README.md
├── README_CN.md
└── LICENSE

3. JSON Canvas 格式

Canvas 模块输出符合 JSON Canvas 开放格式的文件，这是一种用于无限画布的开放文件格式（MIT 许可证）。格式包含节点、边和组等核心元素。

graph LR
    A[Canvas 文件] --> B[节点 Nodes]
    A --> C[边 Edges]
    A --> D[组 Groups]
    B --> E[文本节点]
    B --> F[文件节点]
    C --> G[连接关系]
    D --> H[节点分组]

五、使用场景分析

1. 适用场景

A. 知识管理

使用 MindMap 和 Canvas 功能，将零散的知识点组织成层次化的思维导图，便于理解和记忆。

B. 技术文档

使用 Mermaid 和 Excalidraw 生成流程图、架构图和时序图，增强技术文档的可读性。

C. 会议记录

使用 Canvas 的 Freeform 模式，快速记录会议讨论要点和关系，支持后期整理。

D. 项目规划

使用 Timeline 和 Matrix 图表，规划项目里程碑和优先级排序。

2. 技术优势

A. 低门槛

无需配置复杂的 MCP 服务器，只需复制 Markdown 文件即可使用。

B. 模块化

三个技能相互独立，用户可根据需求选择性安装。

C. 可扩展

基于 prompt 的设计使得技能易于修改和扩展，用户可以自定义图表样式和布局。

3. 技术限制

A. 实验性状态

项目标注为实验性质，暂未覆盖所有输入规模和边界情况。

B. 输出波动

输出质量会根据模型版本和输入结构有所波动。

C. 维护有限

作者的主要目标是演示工具协同工作，而非长期维护此代码库。

六、技术对比分析

1. 与 MCP 服务器对比

2. 与手动绘图对比

七、技术展望

1. 潜在改进方向

A. 输出质量稳定性

通过优化 prompt 模板和增加示例，提高不同模型版本下的输出一致性。

B. 图表类型扩展

增加更多图表类型，如实体关系图、类图、甘特图等。

C. 样式自定义

支持用户自定义配色方案、字体样式等视觉元素。

2. 生态影响

该项目展示了基于 prompt 的 AI 扩展模式，为 Claude Code 生态提供了一种轻量级的扩展思路。随着 AI 模型能力的提升，这种模式可能成为主流的 AI 工具扩展方式。

3. 技术趋势

AI 辅助可视化正在从简单的图表生成向智能推荐、自动布局、风格迁移等方向发展。该项目的模块化设计为后续功能扩展预留了空间。

八、实施建议

1. 安装步骤

# 克隆仓库
git clone https://github.com/axtonliu/axton-obsidian-visual-skills.git

# 复制技能到 Claude Code 目录
cp -r axton-obsidian-visual-skills/excalidraw-diagram ~/.claude/skills/
cp -r axton-obsidian-visual-skills/mermaid-visualizer ~/.claude/skills/
cp -r axton-obsidian-visual-skills/obsidian-canvas-creator ~/.claude/skills/

2. 前置条件

• 已安装 Claude Code CLI
• 已安装 Obsidian
• 已安装 Excalidraw 插件（用于 Excalidraw 技能）

3. 使用示例

# Excalidraw 流程图
"Create an Excalidraw flowchart showing the CI/CD pipeline"

# Mermaid 时序图
"Visualize this process as a Mermaid diagram"

# Canvas 思维导图
"Turn this article into an Obsidian Canvas"

九、参考资料

参考资料

1. axton-obsidian-visual-skills - GitHub
2. Excalidraw - Hand-drawn style whiteboard
3. Mermaid - Diagram and chart generation
4. JSON Canvas - Open file format for infinite canvas
5. Obsidian - Knowledge base application