Viz Charts

viz-charts: 报告内嵌图表与 3D 知识图谱

为 biz-html-viz（终端风）和 viz-deck（讲演风）两个报告 skill 提供图表渲染与项目可视化能力。七类视觉表达 + 双模渲染 + 双主题 + MP4 视频导出。

七类视觉表达

| 类型 | 类型数 | 路径 | |---|---|---| | Mermaid 关系/流程图 | 11 | templates/mermaid/*.mmd | | ECharts 数据图表 | 25+ | templates/echarts/*.json | | 轻量自研组件 SVG/CSS | 5 | components/{kpi,sparkline,gauge,progress,tag-cloud}/ | | 3D 知识图谱 WebGL | 3 viewer | templates/kg3d/{code,doc,data}-graph.html | | SVG 知识图谱 环形 Context Graph / Circos 弦图 | 2 form | references/svg-kg-guide.md | | Motion 图表 → MP4/GIF | 3 模式 | templates/motion/*.html + references/motion-charts.md | | Native PPTX 图表（v3） | 8 chart types | scripts/echarts_to_pptx.py + references/pptx-charts.md |

两种渲染模式

| 模式 | 适用 | 实现 | 限制 | |---|---|---|---| | inline （默认） | 浏览器查看、嵌入 HTML 报告 | CDN 加载 mermaid + echarts + 3d-force-graph，jsdelivr→unpkg 双 fallback | 需联网；大图首次加载略慢 | | offline | 离线归档、打印、邮件附件 | Node 脚本 SSR：ECharts 内置 SVG 渲染器，Mermaid 三档兜底（mermaid-isomorphic → mmdc → placeholder） | 3D KG 无离线模式（WebGL 不能 SVG 化） |

两套主题

| 主题 | 配色 | 字体 | 适配 | |---|---|---|---| | terminal | 黑 #0a0a0a + 酸黄 #d4ff00 + 灰阶 | JetBrains Mono | biz-html-viz | | deck | 深空 #030711 + 青 #42e8ff + 金 #ffd987 | Inter | viz-deck |

主题文件：themes/terminal.js / themes/deck.js，均导出 echartsTheme / mermaidTheme / componentTheme 三组配置。

工作流程

Step 1 — 强制读决策树

references/decision-tree.md 是数据形态 → 视觉类型的选型映射。任何图表/KG 请求先读这个再选模板。

Step 2 — 选模板与契约

读 references/chart-cookbook.md 找出对应模板的数据契约。

Step 3 — 选渲染模式

Inline 模式（默认）：

往用户 HTML 报告里嵌入 Mermaid/ECharts/组件块，并在 `` 前加：

  window.VIZ_CHARTS_OPTS = {
    mermaidTheme: /* terminal | deck mermaidTheme 对象 */,
    echartsTheme: /* 同上的 echartsTheme 对象 */
  };

Offline 模式（仅 Mermaid + ECharts，不含 3D KG）：

cd .claude/skills/viz-charts/renderers/node
npm install --silent
# Mermaid 离线渲染需要 chromium（仅首次）
npx playwright install chromium

node render-mermaid.mjs --input arch.mmd --output arch.svg --theme terminal
node render-echarts.mjs --input trend.json --output trend.svg --theme deck
node batch.mjs --input-dir ./charts --output-dir ./svgs --theme terminal

Step 4 — 3D KG（特殊路径，只 inline）

读 references/kg-builder-guide.md 后：

node builders/code-kg.mjs --repo ./my-app --output code-kg.json --group-by dir
node builders/doc-kg.mjs --input ./docs --output doc-kg.json
# 渲染：把 JSON 替换进 viewer 模板的 {{KG_DATA_JSON}}
# 见 kg-builder-guide.md 的 "一键渲染脚本"

Step 4b — SVG 知识图谱（环形 Context Graph / Circos · 纯 SVG · 可交互）

当关系图要嵌进报告主流且要可交互、或需要矢量可缩放 / 可导出而非 WebGL 时，用纯 SVG 两形态（读 references/svg-kg-guide.md）：

• 环形 Context Graph —— 每个 category 一个独立环，节点排在环周，跨类贝塞尔连线、同类环内弧。数据/渲染解耦的 {categories, entities, relationships} 模型。交互：拖拽节点 · 滚轮缩放 · 拖背景平移 · 点节点 BFS 邻域高亮 · 搜索定位，外加环形 ↔ 力导向切换、按类过滤。适合"读类内结构 + 跨类关系密度"。
• Circos 弦图 —— 一个大环切成扇区（每类一段 ideogram），外圈柱状 track 记权重，内部 ribbon 连关系。交互：悬停实体/扇区高亮其全部 ribbon。适合"在一张图里读全局关系 + 每实体权重"。

两者都是单段 SVG + 原生 JS（无 WebGL、无第三方图库），可直接落进 HTML 报告或 deck 的 ``。何时用 3D vs SVG：节点多、要空间感 → 3D WebGL；要嵌报告、要交互/可导出/打印 → SVG 环形或 Circos。

Step 5 — Motion → MP4（讲演 / 路演 / 演示视频）

仅当需求是动画图表 + 录制视频时启用。先读 references/motion-charts.md 选 motion 类型，再读 references/mp4-export.md 走 huashu-design 桥接。终端风（biz-html-viz）禁用 motion——决策签字报告必须零动效。

# 1) 生成 motion stage HTML（用 templates/motion/motion-stage-template.html）
# 2) 用 huashu-design 录制（CLI 风格：位置参数 + --key=value；输出自动同名 .mp4）
node ~/.claude/skills/huashu-design/scripts/render-video.js \
  ./output/trend-motion.html \
  --duration=6 --width=1920 --height=1080
# 3) 25fps + 60fps + GIF 三件套
bash ~/.claude/skills/huashu-design/scripts/convert-formats.sh ./output/trend-motion.mp4

时长 / 缓动 / 帧率请用 themes/motion.js 的 preset，保证多个动图节奏一致。

Step 6 — 一致性检查

• 同一份报告内所有图表用同一主题（不要 terminal+deck 混搭）
• ECharts 系列 ≤ 7 个，Mermaid 节点 ≤ 30，超过转 ECharts graph 或 3D KG
• 每张图都有 `` 或 markdown 说明
• offline 输出的 SVG 含 viewBox 保证响应式
• 3D KG 单页不超过 1 个（多 WebGL canvas 同页性能崩）

标准嵌入结构

Mermaid

  
flowchart LR
    A[Event] --> B{Risk Gate}
    B -->|approved| C[Execute]
  
  
  图 1 · 主流程

ECharts

  
  图 2 · 季度营收

自研组件

3D KG

通常独立链接或iframe 嵌入，不掺主报告 main flow：

  项目代码 KG (3D 交互)
  点击在新窗口打开 · 142 文件 · 387 处依赖

反模式

• ❌ 同一报告里混用 terminal + deck 主题
• ❌ 用 3D 图表（炫技）—— 仅在信息密度需要时用 3D 知识图谱
• ❌ Mermaid 节点 > 30 还硬画
• ❌ 直接把 ECharts option 写一大段 inline ` 而不用 data-echarts-option` 契约
• ❌ Offline 输出的 SVG 缺 viewBox
• ❌ 跳过 decision-tree.md 凭直觉选图
• ❌ 把"关键单值"用 ECharts 渲染（应该用 kpi-card 组件）
• ❌ 单页放多个 3D KG（WebGL 资源冲突）
• ❌ 在 terminal 主题 / 决策签字报告里加 motion 动画（违反 biz-html-viz 的"零动效"禁令）
• ❌ 一份 motion stage > 15 秒（观众注意力不够，分段）
• ❌ 录制画布 ≠ 1920×1080（上台投影/嵌入 keynote 会拉伸）
• ❌ 在 motion stage 里嵌多个图表（一 stage 一焦点，方便录制窗口对齐）

文件结构

viz-charts/
├── SKILL.md                          这份
├── README.md                         安装与速查
├── references/
│   ├── decision-tree.md              图表选型决策树（必读）
│   ├── chart-cookbook.md             36+ 视觉的数据契约
│   ├── integration-guide.md          如何集成进 biz-html-viz / viz-deck
│   ├── kg-builder-guide.md           3D KG 构建指南
│   ├── svg-kg-guide.md               环形 Context Graph + Circos 弦图（纯 SVG · 可交互）
│   ├── motion-charts.md              v2 新增 · motion 图表三类模式
│   └── mp4-export.md                 v2 新增 · 视频导出工具链桥接
├── themes/
│   ├── terminal.js                   biz-html-viz 配色
│   ├── deck.js                       viz-deck 配色
│   └── motion.js                     v2 新增 · 动画时长/缓动/帧率 preset
├── components/                       5 自研轻量组件
│   ├── kpi/kpi-card.html
│   ├── sparkline/sparkline.html
│   ├── gauge/mini-gauge.html
│   ├── progress/progress-bar.html
│   └── tag-cloud/tag-cloud.html
├── templates/
│   ├── mermaid/                      11 种 .mmd 模板
│   ├── echarts/                      25 种 .json 模板
│   ├── kg3d/                         3 种 3D KG viewer
│   │   ├── code-graph.html
│   │   ├── doc-graph.html
│   │   └── data-graph.html
│   └── motion/                       v2 新增 · motion stage 模板
│       └── motion-stage-template.html
├── builders/                         3D KG 数据生成器
│   ├── code-kg.mjs                   从 git repo 抽代码图
│   └── doc-kg.mjs                    从 markdown 抽文档图
├── vendor/loaders/
│   └── cdn-loader.js                 inline 模式：双 CDN fallback
├── renderers/node/                   offline 模式
│   ├── package.json
│   ├── render-mermaid.mjs
│   ├── render-echarts.mjs
│   └── batch.mjs
└── examples/
    ├── inline-terminal.html          完整 demo（终端风内联）
    ├── inline-deck.html              完整 demo（讲演风内联）
    ├── kg-doc-demo.html              3D 文档 KG 演示
    └── kg-code-demo.html             3D 代码 KG 演示

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ZimaBlueAI
• Source: ZimaBlueAI/skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.