visualization

# 统一可视化 把可视化视为「**任务目标 × 素材 × 呈现方式**」的组合，而不是机械地"有数据就画图"。先判断用户想讲清什么，再判断图示是否真的增益，最后选择最少但足够的呈现模块。 ## 何时可视化（判断收益） **触发**：用户明确要求画图/图表/图解；或任务虽未明说，但内容涉及趋势、占比、多对象比较、流程顺序、复杂结构，且图示明显增益。 **不触发**：纯文字已足够清楚；确认/翻译/改写类任务；原子事实问答；用户明确只要文字。 ## 与 ui-card 技能的分工（不要互相抢） - **少量结构化条目**（几行对比、一个榜单、几个大数字、日程/进度列表）→ 交给 `ui-card` 技能的 `ui_card` 工具，别用图表硬装清单。 - **图表与图形类**（趋势/占比/分布需要坐标和比例；流程/架构/关系需要连线）→ 本技能，别用卡片硬装图表。 - 判断特征：条目少、文字为主、无坐标轴 → 卡片；多数据点、有坐标/比例/连线 → 图形。 ## 呈现方式路由 ```text 用户请求 ├─ 短小结构化内容（对比/排行/统计/时间轴/进度/清单） │ → ui_card 工具（固定模板优先，card 参数填结构化数据） ├─ 精确数值、趋势、占比、分布（多数据点、需要坐标/比例） │ → generate_chart 工具（内置，Web 端出交互图表卡片 + PNG 降级） │ → 工具不可用/不适用（自定义布局、组合图、主题适配）时手写 HTML/Chart.js/SVG ├─ 概念、机制、流程、关系（非精确数值） │ → SVG 示意图 / mermaid（Web 端原生渲染 mermaid 代码块）/ 结构化文字图 ├─ 需要可编辑图文件落盘（Obsidian vault / .excalidraw / 手绘风 / 动画图） │ → Excalidraw 工作流（见 references/excalidraw.md） ├─ 参数变化、状态迁移、步骤演示（动态本身有价值） │ → HTML 交互 └─ 图示收益不足 → 纯文字 ``` ## 内置工具与 Excalidraw 工作流 - **generate_chart 工具（对话内数据图表首选）**：Chart.js 语法，Web 端渲染交互图表卡片，同时产 PNG 供飞书等渠道降级。折线/柱状/饼/环/雷达都走它，别手写 HTML 重复造轮子；只有工具参数表达不了（复杂组合图、特殊布局、主题深度适配）才手写。 - **Excalidraw 工作流（落盘文件）**：用户要"在 Obsidian 里画图"、要 .excalidraw 文件、要可拖拽微调的手绘风图或动画图时使用，产出落盘到 Obsidian vault 的可编辑文件。完整流程（DSL 快速模式 / JSON 完整模式 / 三种输出模式 / 设计规范 / 避坑指南）见 [references/excalidraw.md](references/excalidraw.md)，DSL 语法见 [references/dsl-syntax.md](references/dsl-syntax.md)。 - 判断口诀：**对话里看 → generate_chart / mermaid / SVG；vault 里存 → Excalidraw**。 分支可组合（如「卡片给结论摘要 + 图表给趋势细节」），但默认一个主模块，复杂任务最多加一个辅助模块，且每个模块必须表达不同信息。 ## 路由硬规则 - **数据不可生图**：精确数值、比例、统计关系、坐标不得用生成式图片承担——一律确定性渲染（代码画图/卡片）。 - **不编造**：真实数据、年份、排名必须来自用户材料或已核验结果。无法核验时降级为明确标注的示例数据，并说明是示例。 - **先结论后图**：先给用户最需要的结论，再给图表和必要解读；不在图前铺垫大段文字。 - **交互要有因果价值**：仅当点击/拖动/切换能增加理解时用交互；静态内容不包装成无意义按钮。 - **用户格式优先**：明确要求某种格式（如"给我 mermaid""用表格"）时服从用户。 - **中文语境配色**：涨红跌绿（A 股惯例），货币默认 ¥。 - **可读性**：浅色主题下用浅底深字，深色主题下用深底浅字；文字必须跟随主题，不得硬编码与主题冲突的颜色。 ## 质量自检（输出前过一遍） - 图中的每个数字都能追溯到来源（用户给的 / 检索核实的 / 明确标注的示例）。 - 图和文字讲的是同一件事，没有图文不符。 - 移动端/窄屏下文字不截断（控制标签长度，旋转或省略策略）。 - 图表类型匹配数据形态：趋势用折线、占比用饼/环（≤6 项）、比较用柱状、关系用网络/流程——不硬套。