| name | siyuan-excalidraw |
| description | Excalidraw 图表生成器，为思源笔记创建流程图、思维导图、架构图等可视化内容，自动保存 SVG 到思源资源目录。当需要"绘图"、"画流程图"、"创建架构图"、"可视化"时使用此技能（应用层，依赖 siyuan 基础知识）。 |
| metadata | {"version":"2.0.0"} |
思源笔记 Excalidraw 图表生成器
为思源笔记生成 Excalidraw 风格的图表，直接输出 SVG 文件并自动保存到思源笔记资源目录。
工作流程
- 分析内容 - 识别概念、关系、层次结构
- 选择图表类型 - 根据内容特性选择最佳可视化形式
- 生成 SVG - 创建 Excalidraw 风格的 SVG 图表
- 保存文件 - 自动保存到思源笔记资源目录
- 返回路径 - 提供可直接在思源笔记中使用的资源路径
配置文件读取
必须首先读取 siyuan.json 配置文件，获取保存路径信息：
{
"local_path": "本地路径（优先使用）",
"remote_path": {
"webdav": true,
"url": "WebDAV 服务器地址",
"username": "用户名",
"password": "密码",
"assets_path": "资源目录路径"
}
}
路径选择规则
- 优先使用
local_path：如果 local_path 非空，直接保存到该路径下的 data/assets/ 目录
- 备选使用
remote_path：如果 local_path 为空，通过 WebDAV 上传到 remote_path.assets_path
图表类型选择指南
根据内容特性选择最合适的图表形式：
| 类型 | 英文 | 使用场景 | 设计要点 |
|---|
| 流程图 | Flowchart | 步骤说明、工作流程、任务执行顺序 | 箭头连接步骤，清晰表达流程走向 |
| 思维导图 | Mind Map | 概念发散、主题分类、灵感捕捉 | 中心向外发散，放射状结构 |
| 层级图 | Hierarchy | 组织结构、内容分级、系统拆解 | 自上而下或自左至右的层级节点 |
| 关系图 | Relationship | 要素影响、依赖、互动关系 | 图形间用连线表示关联 |
| 对比图 | Comparison | 方案或观点对照分析 | 左右两栏或表格形式 |
| 时间线图 | Timeline | 事件发展、项目进度 | 以时间为轴，标出关键时间点 |
| 矩阵图 | Matrix | 双维度分类、优先级定位 | X/Y 两个维度的坐标平面 |
| 自由布局 | Freeform | 零散内容、灵感记录 | 无结构限制，自由放置 |
SVG 输出格式
文件命名规范
格式：excalidraw-[主题]-[时间戳].svg
示例：
excalidraw-系统架构-20260125171200.svgexcalidraw-用户注册流程-20260125171200.svgexcalidraw-商业模式-20260125171200.svg
SVG 结构模板
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 1200 800"
width="1200"
height="800"
style="background-color: #ffffff;">
<defs>
<filter id="roughness">
<feTurbulence type="fractalNoise" baseFrequency="0.04" numOctaves="2" result="noise"/>
<feDisplacementMap in="SourceGraphic" in2="noise" scale="1" xChannelSelector="R" yChannelSelector="G"/>
</filter>
<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
<polygon points="0 0, 10 3.5, 0 7" fill="#1e1e1e"/>
</marker>
<style>
.excalidraw-text {
font-family: "Virgil", "Segoe UI Emoji", "Apple Color Emoji", sans-serif;
font-size: 20px;
fill: #1e1e1e;
}
.excalidraw-title {
font-family: "Virgil", "Segoe UI Emoji", "Apple Color Emoji", sans-serif;
font-size: 28px;
font-weight: bold;
fill: #1e40af;
}
.excalidraw-subtitle {
font-family: "Virgil", "Segoe UI Emoji", "Apple Color Emoji", sans-serif;
font-size: 20px;
fill: #3b82f6;
}
.excalidraw-body {
font-family: "Virgil", "Segoe UI Emoji", "Apple Color Emoji", sans-serif;
font-size: 16px;
fill: #374151;
}
</style>
</defs>
<g id="content">
</g>
</svg>
设计规范
颜色方案
| 用途 | 颜色代码 | 说明 |
|---|
| 标题 | #1e40af | 深蓝色 |
| 副标题/连接线 | #3b82f6 | 亮蓝色 |
| 正文文字 | #374151 | 深灰色 |
| 强调/重点 | #f59e0b | 金色 |
| 成功/完成 | #10b981 | 绿色 |
| 警告/注意 | #ef4444 | 红色 |
| 边框/线条 | #1e1e1e | 黑色 |
| 背景填充 | #f3f4f6 | 浅灰色 |
| 画布背景 | #ffffff | 白色 |
字体大小规范
- 标题：24-28px
- 副标题：18-20px
- 正文/说明：14-16px
- 标注/小字：12px
布局规范
- 画布尺寸：1200 x 800 像素（可根据内容调整）
- 边距：四周保留 40-60px 边距
- 元素间距：相邻元素间保持 20-40px 间距
- 对齐方式：使用网格对齐，保持视觉整洁
Excalidraw 手绘风格要点
- 线条：略带不规则，模拟手绘效果
- 圆角：矩形使用圆角（rx="8"）
- 填充：使用半透明或斜线填充
- 阴影：轻微的投影效果增加层次感
SVG 元素模板
矩形框（节点）
<g class="node">
<rect x="100" y="100" width="200" height="60"
rx="8" ry="8"
fill="#f3f4f6"
stroke="#1e1e1e"
stroke-width="2"/>
<text x="200" y="135" text-anchor="middle" class="excalidraw-text">节点文本</text>
</g>
椭圆（起止点）
<g class="terminal">
<ellipse cx="200" cy="100" rx="80" ry="40"
fill="#e0f2fe"
stroke="#1e1e1e"
stroke-width="2"/>
<text x="200" y="105" text-anchor="middle" class="excalidraw-text">开始</text>
</g>
菱形（判断）
<g class="decision">
<polygon points="200,50 280,100 200,150 120,100"
fill="#fef3c7"
stroke="#1e1e1e"
stroke-width="2"/>
<text x="200" y="105" text-anchor="middle" class="excalidraw-text">条件?</text>
</g>
箭头连接线
<line x1="300" y1="130" x2="400" y2="130"
stroke="#1e1e1e"
stroke-width="2"
marker-end="url(#arrowhead)"/>
曲线箭头
<path d="M 100 100 Q 150 50 200 100"
fill="none"
stroke="#1e1e1e"
stroke-width="2"
marker-end="url(#arrowhead)"/>
虚线连接
<line x1="100" y1="100" x2="200" y2="100"
stroke="#3b82f6"
stroke-width="2"
stroke-dasharray="8,4"/>
完整示例
示例 1：简单流程图
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 400" width="800" height="400" style="background-color: #ffffff;">
<defs>
<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
<polygon points="0 0, 10 3.5, 0 7" fill="#1e1e1e"/>
</marker>
<style>
.excalidraw-text { font-family: "Virgil", sans-serif; font-size: 16px; fill: #1e1e1e; }
.excalidraw-title { font-family: "Virgil", sans-serif; font-size: 24px; fill: #1e40af; font-weight: bold; }
</style>
</defs>
<text x="400" y="40" text-anchor="middle" class="excalidraw-title">用户注册流程</text>
<ellipse cx="100" cy="200" rx="60" ry="30" fill="#e0f2fe" stroke="#1e1e1e" stroke-width="2"/>
<text x="100" y="205" text-anchor="middle" class="excalidraw-text">开始</text>
<line x1="160" y1="200" x2="220" y2="200" stroke="#1e1e1e" stroke-width="2" marker-end="url(#arrowhead)"/>
<rect x="230" y="170" width="120" height="60" rx="8" fill="#f3f4f6" stroke="#1e1e1e" stroke-width="2"/>
<text x="290" y="205" text-anchor="middle" class="excalidraw-text">填写信息</text>
<line x1="350" y1="200" x2="410" y2="200" stroke="#1e1e1e" stroke-width="2" marker-end="url(#arrowhead)"/>
<polygon points="490,140 560,200 490,260 420,200" fill="#fef3c7" stroke="#1e1e1e" stroke-width="2"/>
<text x="490" y="205" text-anchor="middle" class="excalidraw-text">验证?</text>
<line x1="560" y1="200" x2="620" y2="200" stroke="#1e1e1e" stroke-width="2" marker-end="url(#arrowhead)"/>
<ellipse cx="700" cy="200" rx="60" ry="30" fill="#d1fae5" stroke="#1e1e1e" stroke-width="2"/>
<text x="700" y="205" text-anchor="middle" class="excalidraw-text">完成</text>
</svg>
示例 2：思维导图
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 600" width="1000" height="600" style="background-color: #ffffff;">
<defs>
<style>
.center { font-family: "Virgil", sans-serif; font-size: 24px; fill: #1e40af; font-weight: bold; }
.branch { font-family: "Virgil", sans-serif; font-size: 18px; fill: #3b82f6; }
.leaf { font-family: "Virgil", sans-serif; font-size: 14px; fill: #374151; }
</style>
</defs>
<ellipse cx="500" cy="300" rx="100" ry="50" fill="#dbeafe" stroke="#1e40af" stroke-width="3"/>
<text x="500" y="305" text-anchor="middle" class="center">核心主题</text>
<line x1="600" y1="280" x2="750" y2="150" stroke="#3b82f6" stroke-width="2"/>
<rect x="720" y="120" width="120" height="50" rx="25" fill="#f0f9ff" stroke="#3b82f6" stroke-width="2"/>
<text x="780" y="150" text-anchor="middle" class="branch">分支一</text>
<line x1="600" y1="320" x2="750" y2="450" stroke="#3b82f6" stroke-width="2"/>
<rect x="720" y="430" width="120" height="50" rx="25" fill="#f0f9ff" stroke="#3b82f6" stroke-width="2"/>
<text x="780" y="460" text-anchor="middle" class="branch">分支二</text>
<line x1="400" y1="280" x2="250" y2="150" stroke="#3b82f6" stroke-width="2"/>
<rect x="160" y="120" width="120" height="50" rx="25" fill="#f0f9ff" stroke="#3b82f6" stroke-width="2"/>
<text x="220" y="150" text-anchor="middle" class="branch">分支三</text>
<line x1="400" y1="320" x2="250" y2="450" stroke="#3b82f6" stroke-width="2"/>
<rect x="160" y="430" width="120" height="50" rx="25" fill="#f0f9ff" stroke="#3b82f6" stroke-width="2"/>
<text x="220" y="460" text-anchor="middle" class="branch">分支四</text>
</svg>
实现步骤
步骤 1：生成 SVG 内容
根据用户需求分析内容，选择合适的图表类型，生成 SVG 代码。
步骤 2：调用上传脚本
使用提供的 upload_asset.py 脚本上传 SVG 文件：
import subprocess
import json
result = subprocess.run([
'python', 'scripts/upload_asset.py', svg_content, topic
], capture_output=True, text=True)
if result.returncode == 0:
_, asset_path, message = result.stdout.strip().split('|', 2)
print(f"✅ {message}")
print(f"📍 资源路径：{asset_path}")
else:
error_msg = result.stdout.strip().split('|', 1)[1]
print(f"❌ {error_msg}")
步骤 3：返回资源路径
print(f"\n📖 在思源笔记中使用：")
print(f"")
输出确认模板
生成图表后，向用户报告：
✅ Excalidraw 图表已生成！
📍 保存位置：
assets/excalidraw-[主题]-[时间戳].svg
🎨 图表说明：
- 图表类型：[所选类型]
- 选择原因：[为什么选择这种类型]
- 包含元素：[主要内容概述]
📖 在思源笔记中使用：
在文档中插入以下 Markdown：
或者直接拖放 SVG 文件到编辑器中。
需要调整吗？比如修改布局、添加元素、调整配色？
注意事项
- 字体兼容性：SVG 使用 Virgil 字体模拟 Excalidraw 手写风格，如系统未安装会回退到 sans-serif
- 文件大小：保持 SVG 简洁，避免过于复杂的路径
- 编码格式：始终使用 UTF-8 编码
- 思源笔记兼容：生成的 SVG 可直接在思源笔记中显示
- WebDAV 安全：上传时使用 HTTPS（如可用）
依赖环境
运行 upload_asset.py 脚本需要以下环境：
Python 环境
- Python 3.6 或更高版本
- requests 库
安装依赖
pip install requests
配置文件
确保 siyuan.json 文件存在于项目根目录，包含以下字段：
{
"local_path": "本地路径（优先使用）",
"remote_path": {
"webdav": true,
"url": "WebDAV 服务器地址",
"username": "用户名",
"password": "密码",
"assets_path": "资源目录路径"
}
}
upload_asset.py 脚本说明
upload_asset.py 是专门为思源笔记 Excalidraw 资源上传设计的脚本，功能如下：
主要功能
- 自动选择保存方式：根据
siyuan.json 配置，优先使用本地保存，备选 WebDAV 上传
- 生成文件名：自动生成带时间戳的文件名，避免冲突
- 路径规范化：自动处理路径格式，确保与思源笔记兼容
- 错误处理：完善的异常处理和友好的错误提示
使用方法
命令行使用
python scripts/upload_asset.py <svg_content> <topic>
参数说明：
svg_content: SVG 内容（需用引号包裹）topic: 图表主题
示例：
python scripts/upload_asset.py "<?xml version='1.0'...?>" "系统架构"
作为模块使用
from scripts.upload_asset import upload_asset
success, asset_path, message = upload_asset(svg_content, "系统架构")
if success:
print(f"✅ {message}")
print(f"📍 资源路径：{asset_path}")
else:
print(f"❌ {message}")
返回格式
脚本的标准输出格式如下：
成功
ASSET_PATH|assets/excalidraw-系统架构-20260125171200.svg|已保存到本地: /path/to/siyuan/data/assets/excalidraw-系统架构-20260125171200.svg
失败
ERROR|上传失败: WebDAV 连接超时
路径选择逻辑
-
检查 local_path：如果 local_path 非空且有效，直接保存到本地
- 保存路径：
{local_path}/data/assets/{filename}
-
使用 WebDAV：如果 local_path 为空，检查 remote_path.webdav
- 上传 URL：
{remote_path.url}/{remote_path.assets_path}{filename}
- 使用 Basic Authentication 进行认证
-
失败处理：如果两者都不可用，返回错误信息
配置补充说明
local_path 应指向思源工作目录根目录，而不是 assets 目录本身- 如果思源运行在 Docker 中，只有当脚本也运行在容器内时才应填写容器路径；否则请填写宿主机挂载路径
- 不使用 WebDAV 时，只保留
local_path 即可；remote_path.webdav 可设为 false
WebDAV 上传详情
脚本使用 Python requests 库进行 WebDAV 上传：
- HTTP 方法：PUT
- 认证方式：Basic Authentication
- Content-Type：
image/svg+xml
- 超时时间：30 秒
依赖要求
pip install requests
参考资源
