axton-obsidian-visual-skills 常见陷阱清单：文字偏移、元素重叠与中文手写字体失效的真相与解法

axton-obsidian-visual-skills 常见陷阱清单：文字偏移、元素重叠与中文手写字体失效的真相与解法

【免费下载链接】axton-obsidian-visual-skillsVisual Skills Pack for Obsidian: generate Canvas, Excalidraw, and Mermaid diagrams from text with Claude Code项目地址: https://gitcode.com/gh_mirrors/ax/axton-obsidian-visual-skills

axton-obsidian-visual-skills是一个面向 Claude Code 的 Obsidian 可视化 Skills 套装：用自然语言就能生成 Excalidraw 手绘图、Mermaid 流程图和 Canvas 思维导图。它内置了大量"防坑"规则，但实际使用中仍常遇到文字偏移、元素重叠、中文手写字体失效这三类典型问题。本文结合仓库中的规则文档，逐条讲清现象背后的真相，并给出可直接照做的解法 🛠️

三件套概览：陷阱在哪里埋着

💡 想本地体验：通过 Claude Code 插件市场安装，或克隆仓库后将三个 Skill 文件夹复制到~/.claude/skills/：git clone https://gitcode.com/gh_mirrors/ax/axton-obsidian-visual-skills

下图是 Excalidraw 技能生成的手绘风格关系图（中文手写字体正常加载时的效果）：

陷阱一：文字偏移——独立文本不会自动居中

现象：标题或标签没有落在图形正中央，整体偏向一侧。

真相：Excalidraw 的独立text元素没有自动居中机制，x坐标是文字的左边缘而不是中心点。若不手动计算，文字必然偏移。

解法（技能文档已内置此规则，规则见 excalidraw-diagram/SKILL.md）：

1. 估算文字宽度：文字宽度 ≈ 字符数 × 字号 × 0.5（中文等 CJK 字符按× 1.0估算）
2. 居中公式：x = 中心点 - 估算宽度 ÷ 2

例：字号 20 的英文 "Hello"（5 字符）居中于 x=300 → 宽度 50 →x = 300 - 25 = 275。

另外两个连带坑：箭头标签溢出（长标签超出短箭头，保持标签简短）和标题未居中于整图（标题应居中于图表整体宽度，而非固定在 x=0），详见 excalidraw-diagram/SKILL.md 的常见错误清单。

陷阱二：元素重叠——间距不是"看着差不多"

现象：节点堆在一起、卡片互相压盖，整张图显得杂乱。

真相：AI 生成坐标时若凭"感觉"放点，y 坐标相近的元素极易堆叠。仓库为此定义了硬性间距标准，而非模糊经验：

• Excalidraw：元素间最小间距20–30px，画布四周留50–80px内边距（SKILL.md）
• Canvas：节点中心点之间最小横向 320px、纵向 200px，并定义了碰撞检测公式——放置每个节点前先算中心距，距离小于"两节点宽度之和的一半 + 间距"即判定重叠（references/layout-algorithms.md）

解法：

1. 生成后按 obsidian-canvas-creator/references/layout-algorithms.md 的碰撞检测思路自查一遍
2. 层级顺序别搞反：输出 JSON 时分组（group）先输出、子分组次之、文本节点最后，避免视觉层级错乱（SKILL.md）
3. 节点文字别贪多：单节点超过 2 行就考虑拆节点或改用文件节点

下图是 Canvas 技能输出的彩色卡片布局，节点间距均匀、无压盖：

陷阱三：中文手写字体失效——字体其实要联网加载

现象：英文是 Excalifont 手写体，中文却回退成了系统默认字体。

真相（README.md 的 Troubleshooting 章节）：技能正确写入了fontFamily: 5（Excalifont），但Excalifont 只覆盖拉丁字符；中文手写字体（小赖字体）需要运行时从 Excalidraw.com 动态加载。所以这不是技能生成的问题，而是网络问题：

• 离线、内网、防火墙拦截 Excalidraw.com，都会导致加载失败

两种解法：

顺带避坑：Mermaid 渲染失败的三个惯犯

Mermaid 技能的规则文档把最常见的解析错误总结成了三条铁律（mermaid-visualizer/references/syntax-rules.md）：

1. 1. 文字触发列表冲突：节点文本写成1. 感知会被解析成 Markdown 有序列表，报错Unsupported markdown: list。改成① 感知、(1) 感知或去掉点号即可
2. 子图名带空格必须加 ID：写subgraph 核心流程会解析失败，正确写法是subgraph core["核心流程"]，且连线时引用 ID 而不是显示名
3. 引号与括号转义：文本中的"和()容易破坏解析，统一替换为『』和「」

下图是 Mermaid 技能输出的层级流程图，节点文本、连线与配色均通过语法校验：

一页自检清单：生成后先过一遍再交付

• 独立文本已用"居中公式"手算过 x 坐标，没有整体偏移
• 相邻元素间距 ≥ 20–30px（Canvas 节点中心距 ≥ 320/200px），四周留有边距
• 中文字体显示为手写体；离线环境已配置本地 CJK 字体并重启 Obsidian
• Mermaid 节点文本无数字. 空格模式；子图均使用ID["显示名"]格式
• 引号已替换为『』/「」，JSON 可正常解析
• 字号未低于 14px、正文 ≥ 16px；白底文字颜色不浅于#757575
• 图表文本中没有 Emoji（用颜色或图形代替视觉标记）
• Excalidraw 元素未混入frameId、index、versionNonce等额外字段（可能导致 excalidraw.com 打开异常，见 excalidraw-diagram/SKILL.md）

延伸阅读：这些规则文件的正确打开方式

• excalidraw-diagram/SKILL.md — 三种输出模式、配色规范与"常见错误"清单
• excalidraw-diagram/references/excalidraw-schema.md — 全部元素类型与字段模板
• mermaid-visualizer/references/syntax-rules.md — 完整语法参考与报错对照表
• obsidian-canvas-creator/references/layout-algorithms.md — 碰撞检测、放射布局与网格分区算法
• obsidian-canvas-creator/references/canvas-spec.md — JSON Canvas 格式规范
• README.md — 官方故障排查（含中文字体离线方案）

⚠️ 该项目处于**实验性（Experimental）**阶段：输出质量会受模型版本和输入结构影响。遇到问题时，建议按仓库要求提交"输入 + 输出文件 + 复现步骤"，帮助定位是技能规则还是环境配置的问题。

把上面三个真相记住——文本要手算居中、间距要有硬标准、中文字体依赖网络——再配合文末的自检清单，大部分"图坏了"的情况都能在你打开文件之前就被拦下来 ✅

【免费下载链接】axton-obsidian-visual-skillsVisual Skills Pack for Obsidian: generate Canvas, Excalidraw, and Mermaid diagrams from text with Claude Code项目地址: https://gitcode.com/gh_mirrors/ax/axton-obsidian-visual-skills