Flowy,AI 原生图表技能
Flowy 生成自包含的 HTML 文件,用于渲染交互式 SVG 图表。每个文件都包含嵌入式 CSS、JavaScript 和图表数据,零依赖,只需双击即可在任何浏览器中打开。
文件位置
- 图表文件:
docs/diagrams/*.html(例如docs/diagrams/upload-flow.html)。 首次使用时创建该文件夹;它可能尚不存在。如果项目已经将图表保存在其他位置,请遵循该项目的约定。 - HTML 模板:
${CLAUDE_SKILL_DIR}/references/html-template.html,这是规范渲染器,也是此技能提供的唯一参考文件。该路径会解析到此技能自己的文件夹(无论安装在插件、个人项目还是项目目录中),因此它不依赖于当前项目。
故意不包含 schema 文件、示例文件夹或可视化编辑器。此技能的早期版本指向了 flowy/schema.ts、flowy/examples/、flowy/editor.html 以及磁盘上的 Flowy 源码仓库。这些都不存在,路径已过时,遵循它们只会浪费时间。上面的 HTML 模板是结构的事实来源;在编写图表之前请先阅读它。
前置检查
在创建或编辑 Flowy 图表之前:
- 读取
${CLAUDE_SKILL_DIR}/references/html-template.html以获取当前渲染器代码 - 列出
docs/diagrams/中的现有图表,避免命名冲突 - 如果要更新现有图表,请先读取它并提取
DIAGRAM对象
Schema
每个图表都是一个具有三个字段的 JavaScript 对象:
{
meta: { title, description, type, tags[], created, updated },
nodes: [...],
edges: [...]
}
meta
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
| title | string | 是 | 人类可读的标题 |
| description | string | 否 | 图表展示的内容 |
| type | string | 是 | "flowchart" 或 "ui-mockup" |
| tags | string[] | 否 | 用于组织分类 |
| created | string | 否 | ISO 日期 (YYYY-MM-DD) |
| updated | string | 否 | ISO 日期,创建或更新时设为今天 |
nodes
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
| id | string | 是 | 唯一,snake_case(例如 "step1_upload") |
| type | string | 是 | "box"、"circle"、"diamond"、"note"、"group" |
| label | string | 是 | 形状中显示的主要文本 |
| sublabel | string | 否 | 鼠标悬停提示中显示的次要文本 |
| position | { x, y } | 是 | 左上角坐标(像素) |
| size | { width, height } | 是 | 尺寸(像素) |
| style | object | 否 | 参见下方的节点样式字段 |
| group | string | 否 | 父组节点的 id(仅用于视觉分组) |
节点样式字段:fill、stroke、strokeWidth、color(文本)、fontSize、borderRadius、opacity
edges
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
| id | string | 是 | 唯一(例如 "e_upload_to_extract") |
| source | string | 是 | 源节点 id |
| target | string | 是 | 目标节点 id |
| label | string | 否 | 箭头上的文本(例如 "yes"、"error") |
| sourceHandle | string | 否 | "top"、"right"、"bottom"(默认)、"left" |
| targetHandle | string | 否 | "top"(默认)、"right"、"bottom"、"left" |
| style | object | 否 | 参见下方的边缘样式字段 |
边缘样式字段:stroke、strokeWidth、strokeDasharray、markerEnd
节点渲染规则
| 类型 | SVG 元素 | 详情 |
|---|---|---|
| box | <rect> | 通过 rx/ry 从 borderRadius 实现圆角。默认值:8px |
| circle | <ellipse> | cx = x + width/2,cy = y + height/2,rx = width/2,ry = height/2 |
| diamond | <polygon> | 4 个点:顶部中心、右侧中心、底部中心、左侧中心 |
| note | <path> | 带有折叠角(右上角)的矩形。折叠大小:12px |
| group | <rect> | 虚线边框(stroke-dasharray: 6,3)。在所有其他节点之后渲染。标签位于左上角。低透明度 |
边缘渲染规则
- 计算源点:源节点指定手柄侧的中心(默认:底部)
- 计算目标点:目标节点指定手柄侧的中心(默认:顶部)
- 绘制三次贝塞尔曲线(
C命令),控制点沿手柄方向偏移 50px - 使用 SVG
<marker>定义添加箭头 - 如果设置了
strokeDasharray,则渲染为虚线 - 如果存在
label,则在贝塞尔曲线的中点渲染,并在其后方放置一个小白色背景矩形
布局规则
流向
- 流程图:从上到下(默认)
- UI 线框图:在组容器内从上到下,注释在右侧
间距
- 节点中心之间最小 70px 垂直距离
- 平行节点之间最小 60px 水平距离
- 组内边距:组边界内部 40px
决策菱形
- 左侧分支 = 主要路径 / 是路径
- 右侧分支 = 次要路径 / 否路径 / 错误路径
错误/警告注释
- 放置在主流向的右侧
- 使用红色虚线边缘连接(
strokeDasharray: "6,3",stroke:#991b1b)
标准尺寸
| 类型 | 宽度 | 高度 |
|---|---|---|
| box | 200 | 50 |
| circle | 90 | 40 |
| diamond | 120 | 60 |
| note | 180 | 44 |
颜色调色板
| 用途 | 填充 | 描边 | 文本 |
|---|---|---|---|
| 操作 | #ffffff | #2d6a4f | #1f2937 |
| 主要操作 | #d1fae5 | #065f46 | #065f46 |
| 决策 | #fef3c7 | #92400e | #1f2937 |
| 错误 | #fee2e2 | #991b1b | #991b1b |
| 终端 | #40916c | #2d6a4f | #ffffff |
| 组 | #f5f5f2 | #e6e4df | #374151 |
| 信息/次要 | #dbeafe | #1e40af | #1e40af |
| 默认边缘 | , | #6b7280 | , |
HTML 文件结构
每个 Flowy HTML 文件都遵循此结构。请阅读 HTML 模板参考文件以获取完整的可工作代码。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{图表标题}</title>
<style>
/* 所有 CSS 内联,工具栏、画布、工具提示、选择高亮 */
</style>
</head>
<body>
<div id="toolbar">
<!-- [适应] [-] 100% [+] 标题 徽章 [下载 JSON] -->
</div>
<div id="canvas-wrap">
<svg id="canvas">
<defs><!-- 箭头标记 --></defs>
<g id="diagram-root"></g>
</svg>
</div>
<div id="tooltip"></div>
<script>
const DIAGRAM = { meta: {...}, nodes: [...], edges: [...] };
// 渲染 + 交互代码
</script>
</body>
</html>
工具栏
- 固定在顶部,48px 高,白色背景,底部边框
- 左侧:缩放以适应按钮、缩小、缩放百分比、放大
- 中间:图表标题(粗体)+ 类型徽章(灰色药丸形状)
- 右侧:下载 JSON 按钮(蓝色)
交互功能(全部使用原生 JS)
- 缩放:鼠标滚轮缩放 SVG viewBox。范围:0.2x 到 5x。向光标位置缩放。
- 平移:在空白画布上点击拖拽以平移 viewBox。
- 悬停:悬停在节点上会在光标附近显示其
sublabel的工具提示。 - 点击:点击节点会高亮显示该节点(蓝色边框)及其所有连接的边缘。点击空白区域取消选择。
- 缩放以适应:按钮计算所有节点的包围盒,并设置带有 60px 内边距的 viewBox。
- 下载 JSON:将
DIAGRAM对象序列化为格式化的 JSON 并触发文件下载。
创建新图表
当用户要求创建新的流程图或 UI 线框图时:
- 读取模板:读取 HTML 模板参考文件以获取当前渲染器代码
- 分析请求:识别节点(步骤、决策、错误)和边缘(连接)
- 分配位置:使用布局规则(从上到下网格,标准间距)
- 应用颜色:使用颜色调色板(终端 = 绿色,决策 = 琥珀色,错误 = 红色等)
- 生成完整的 HTML 文件:复制模板结构,用新数据替换
DIAGRAM对象 - 保存到
docs/diagrams/{kebab-case-name}.html - 告知用户: