framework-pic · 框架图生成 Skill

一个把"手绘风格技术框架图 / 架构图"做成可重复执行、可编辑、可自检的工程化流水线的 Claude Code Skill。一次生成 SVG + PNG + drawio 三件套，全部从同一份数据源派生，视觉与可编辑性同步。

安装

npm i -g framework-pic && framework-pic init claude

这会把 skill 安装到 ~/.claude/skills/framework-pic/。重装并覆盖已有版本：

framework-pic init claude --force   # 先备份旧目录，再覆盖

使用

安装后，在 Claude Code 中输入 /framework-pic 即可调用。

运行依赖

skill 渲染时需要（npm 包本身零依赖，仅负责铺文件）：

• python3（引擎与校验器，标准库即可）
• PNG 渲染器（二选一）：
  • brew install librsvg（提供 rsvg-convert，推荐）
  • pip install cairosvg（兜底）

PNG 导出是硬要求：缺渲染器时 render.sh / autofix.py 直接 exit 2（因为自检步骤要读 PNG）。确实装不了且会用别的方式看图时，加 --allow-no-png 降级为警告。

卸载

npm rm -g framework-pic              # 移除 CLI
rm -rf ~/.claude/skills/framework-pic # 移除已安装的 skill

一、它解决什么问题

AI 不会自己设计漂亮的图，但 AI 可以一致地、可重复地、可自检自修地批量产出符合统一视觉契约的图，并且每张都给你一份 drawio 源文件继续修改。

视觉灵感来自 Mem0 的分层架构图：浅色分层容器 + 白底节点 + 角落 TAG + 几何小图标 + 四色语义箭头 + 底部 legend。它要解决的是 Mermaid 那种"一眼模板感、不可控、不好二次编辑"的痛点。

二、三大核心能力

1. Spec-driven 渲染（一份数据 → 三件套）

只写一份 Python SPEC dict 描述图的内容（层、节点、连线、注释、图例），渲染引擎自动产出：

| 产物 | 用途 | | --- | --- | | *.svg | 矢量原图，贴 wiki / 网页无限缩放 | | *.png | 2× 高分辨率位图，贴 PPT / 文档 | | *.drawio | 可在 diagrams.net 直接拖拽编辑的源文件 |

drawio 渲染器会把自由 SVG 片段（<rect> / <circle> / <line> / <path> / <text>）解析成可编辑的 mxCell，节点几何图标也内嵌为 image cell —— 这是和普通 Mermaid 渲染的关键差异。

SVG vs drawio 保真度：两份产物视觉一致（节点 / 层 / 图标 / 标签 / 图例 / 落点都对得上），但非逐像素相同。SVG/PNG 是呈现件（精确走线、投影、chips 胶囊）；drawio 是可编辑件——节点 / 层 / 文字 / 图例 / 图标全部保留且落点一致。唯一有意差异：拖动节点时连线会被 diagrams.net 自动重排，但标签钉死、不会漂。

2. 自检布局 + 自动修复（不依赖人眼，闭环收敛）

render.sh 默认进入 autofix 循环：每次渲染都 validate → patch → re-validate，最多 8 轮直到 0 issues。

自动扫描的问题：节点重叠、超出画布、超出分层、文字宽度超容器、注释压节点、circle 外置文字溢出。

对应确定性修复（保守、小步、不改语义）：扩画布、增大分层高度并同步下移、沿短轴推开重叠节点、加宽节点容纳标题、移动注释到节点上 / 下方。

修复在内存中对 SPEC 操作，不改 spec 源文件 —— 手写的设计意图永远保留。autofix 不会删节点、改连线、重排 layer、改图意；语义错误仍需人工改 spec。

渲染前 Preflight 门禁：引用不存在的节点、未实现的路由、非法端口、缺必填字段等错误，会在渲染前被精确定位（带边序号 + 坏值 + 合法取值）并 exit 2、不写半成品，而不是崩溃或静默画错图。

3. 视觉契约（一致性强制）

把"为什么一批图看起来像一家人"的规则写死，不允许自创色 / 改字体。

三、支持的图类型（都有现成模板）

架构（分层）、时序、状态机、类图、思维导图（放射）、甘特 / 时间线、对比列、流程 / 泳道、风险矩阵 —— 每种图都有真实 spec 模板，新图直接从最接近的模板复制改字段。

四、怎么用

触发方式：仅显式调用。 必须在 Claude Code 中输入 /framework-pic 才会加载。不会自动接管 —— 即使说"画个架构图 / 出 drawio / 重画这张图 / 字体重叠了 / 把 markdown 里的 mermaid 都重画一遍"，也要明确打 /framework-pic。

设计取舍：避免日常对话里一提"图"就误触发、抢占用户本来想用的 Mermaid 等工具。

五、依赖

见上方运行依赖。

六、成熟度

经四轮生产级加固 + 全程实测（回归 19/19 零漂移、drawio 与 PNG parity 比对吻合、preflight 与 autofix 真实工作）：对"按模板填 spec"这一定位已是生产级——崩溃路径堵死、静默错图堵死、校验覆盖齐、单一事实源。

已知取舍（非缺陷）：文字宽度仍是启发式估算（CJK×1.0 / ASCII×0.6），非真实字体度量；跨平台字体兜底、extras 注入转义等属面向"任意用户任意输入"才需补的尾巴，不影响团队 macOS 内使用。

License

MIT