| name | visualize |
| description | 在 Codex CLI 里为学习/知识梳理类问答自动生成视觉化笔记 — 包括流程图、架构图、时序图、对比表、状态机、学习路径、交互卡片等。默认产出 Obsidian 兼容的 markdown 笔记(内嵌 SVG 或 dataviewjs 块);当最佳展示形式依赖浏览器交互且用户并未要求写入 Obsidian 时,也可以输出独立 .html / .svg。**务必在用户讨论概念、学习路线、系统架构、流程步骤、对比分析、数据关系等场景时主动触发本 skill**,哪怕用户没有明说"画一下""可视化""做个图"——只要内容具备空间结构、时序流程、分类对比或可交互演示特征,视觉化就能显著提升展示效果。凡是涉及 Obsidian 学习笔记、知识卡片、概念图、学习路径、架构梳理、流程整理、状态转移、知识对比等用户意图时,都要优先考虑使用本 skill。 |
Visualize — Codex CLI 的学习可视化助手
这个 skill 的目标:把 claude.ai 网页里那种"该用图就自动出图、该用交互就自动出交互"的体验搬到 codex cli。默认优先产出 Obsidian 笔记,但当最佳展示形式明显更适合浏览器交互、且用户没有要求写入 Obsidian 时,也可以输出独立 HTML / SVG,而不是被博客风网页或固定模板绑死。
核心理念
你(Codex)不是在做"图表生成器",你是在做学习笔记。文字是主体,视觉化是嵌入到文字里的"高辨识度模块",帮助读者在扫读时抓住结构。
三个底线:
- 默认 markdown,视觉化嵌入其中。不要生成独立 HTML 站点、博客模板或带导航栏的网页。
- 透明背景,样式尽量极简,依赖 Obsidian 当前主题的字色/背景。
- 不过度装饰。每个视觉块都要承载具体信息(结构、关系、流程、对比),而不是纯装饰性的分隔线、logo、emoji 墙。
最重要的品味原则:得意门生 vs 做题家
这个 skill 是从 claude.ai 网页的 visualize 工具移植来的。用户的期望是——你是得意门生,不是做题家。
做题家:看到"学习路线"就套阶段卡片模板,看到"架构"就套分层图。模板是答案。
得意门生:先理解内容的结构本质(这是序列?层次?关系?对比?状态?),再从设计词汇库里选择或组合最匹配的形式。模板是参考词汇,不是答案。
具体来说,每次要生成视觉块之前,先问自己三个问题:
- 这段内容的结构本质是什么? — 序列、层次、关系、对比、比例、状态、空间?
- 什么形式最能让读者"一看就懂"? — 不是最炫的,是最清楚的
- 用
patterns.md 里的模板能覆盖吗?还是要改造/组合/原创? — 不能覆盖就改造,别硬套
读 references/design-thinking.md,那里有详细的设计思维框架。这是 skill 的灵魂,不是附件。
决策流程
收到用户问题后,依次问自己:
Step 0 — 需要视觉化吗?
不是所有问题都需要视觉化,但只要某种视觉形式能明显更好地展示给用户、让读者更快抓住结构或差异,就应该使用。判断标准不是"做起来麻不麻烦",而是"展示效果是否更强":
应该视觉化的信号:
- 空间/结构关系(架构、层级、组件关系)
- 时序/流程(步骤、状态转移、生命周期、事件序列)
- 数据形状(分布、对比、趋势、分类)
- 多维度对比(方案 A vs B vs C 在多个维度上的差异)
- 学习路径(阶段、先后依赖、各阶段目标)
- 可交互演示(计算、参数调节、折叠展开)
- 分层揭示/逐步展开更清楚(先看总览,再点开细节)
- 多视角切换更清楚(按角色、阶段、维度、案例切换观察)
- 用户用了"画/看/展示/可视化/流程图/架构图/路线/对比/时序"等词
- 用户描述的本身就是一个视觉产物:"XX 对比表""XX 状态机""XX 注册表单"
不应该视觉化的信号:
- 纯定义、概念解释,一两段文字就能说清
- 执行性任务(修 bug、改代码、改配置、写邮件)
- 简单事实问答
- 情绪/闲聊
- 用户明确说"只要文字""不用图""简单点说"
判断标准:这种形式是否让读者更快抓住结构,或更顺手地探索内容?如果答案是"差不多",就不要加;如果交互/切换/展开能明显提升展示效果,不要因为实现更复杂就退回静态形式。
Step 1 — 输出到哪?
优先输出到 Obsidian 笔记,当以下任一条件成立时:
- 用户明确要做笔记、写入 Obsidian、保存到 vault
- 当前工作上下文明显是 Obsidian 学习笔记场景
- 最佳形式本身就是嵌在笔记里的静态图或 dataviewjs 块
此时写入:
C:\Users\34434\OneDrive\Obsidian\学习笔记\~Codex\
文件名:<主题>-YYYY-MM-DD.md,主题用中文,下划线或短横线分词。例:Redis进阶路线-2026-04-17.md。如果同一天同主题已存在,追加 -2, -3 后缀。
输出独立 .html / .svg 到桌面,当以下任一条件成立时:
- 用户明确说"导出 html""生成一个网页""单独一个 svg 文件""给我一份独立的图"
- 你判断最佳展示形式依赖浏览器原生交互(点击切换、筛选、局部展开、hover 细节、参数联动等),且用户没有要求写入 Obsidian
此时写入:
C:\Users\34434\Desktop\
这时按用户要求或最佳展示形式产出单独的 .html 或 .svg,文件名同上规则。
路径是给 Windows 的 codex 用的。如果运行环境是 WSL 或 git-bash,用对应的挂载路径(例如 /mnt/c/Users/34434/OneDrive/Obsidian/学习笔记\~Codex/)。先 ls 确认路径存在,不存在就让用户确认或创建。
Step 2 — 用哪种嵌入形式?
| 类型 | 用什么 | 理由 |
|---|
| Obsidian 笔记里的静态图(流程/架构/时序/对比/学习路径) | dataviewjs 包裹的 SVG | 保持 markdown 自包含,兼容 Obsidian 阅读视图 |
| Obsidian 笔记里的交互展示(点击展开、参数调节、动态过滤、视角切换) | dataviewjs 代码块 | 动态生成 DOM,能做状态管理 |
| 用户未要求 Obsidian,且最佳形式依赖浏览器交互 | 独立 HTML | 不受 dataviewjs 约束,更适合展示性更强的交互内容 |
| 表格型数据视图(任务清单、笔记索引) | dataview 查询块(非 JS) | 简单声明式,性能好 |
混合使用没问题——一篇笔记里可以既有 dataviewjs 包裹的 SVG,又有真正的 dataviewjs 交互块。
详细的嵌入细节、边界情况(比如 Obsidian 阅读/编辑视图差异、Dataview 插件启用检查)看 references/embedding-guide.md。
输出文件的结构模板
每篇笔记必须遵循这个结构(可以按需增减小节,但框架保持):
---
created: 2026-04-17
tags: [学习笔记, Codex生成, <主题标签>]
topic: <主题>
---
# <主题>
> <一句话概括这篇笔记在讲什么、读完能获得什么>
## 核心问题 / 起点
<用 1-3 句话点出读者来看这篇笔记是想解决什么。如果用户问题本身就是一个清晰的问题,就直接复述它>
## <主内容段 1>
<文字叙述>
<如果这一段需要视觉化,在文字之后插入 SVG 或 dataviewjs 块。先文字、再视觉——视觉是对文字的补强,不是替代>
## <主内容段 2>
...
## 关键要点
- 要点 1
- 要点 2
- 要点 3
## 延伸思考 / 下一步
<可选:后续可以深入的方向、相关主题、推荐练习>
绝对不要做的事:
- 不要生成
<!DOCTYPE html> 开头的完整 HTML 文件(除非用户明说要 html)
- 不要生成带导航栏、页脚、博客式版式的笔记(Obsidian 主题已经处理版式)
- 不要在 markdown 开头塞大段 CSS
<style> 块 — 阅读视图大概率会剥离它,样式应该内联到 SVG/HTML 元素上
- 不要插入外部 CDN 脚本(
<script src="https://...">)— Obsidian 不执行这些
- 不要在 .md 笔记里直接写
<svg> 标签——所有 SVG 必须用 dataviewjs 代码块包裹(见下面的"SVG 嵌入规范")
SVG 嵌入规范(静态图的主要形式)
核心规则(非常重要)
写进 Obsidian 笔记(.md)的 SVG,必须用 dataviewjs 代码块包裹。不允许直接把 <svg> 标签写到 markdown 里。
这条是用户的强要求,没有例外。唯一例外是用户明确要求输出独立 .svg 文件到桌面——那种情况下是纯 SVG 文件,不经过 markdown,自然也不用包裹。
包裹形式(方式 A:innerHTML)
```dataviewjs
const container = dv.el("div", "", { cls: "viz-svg" });
container.innerHTML = `
<svg viewBox="0 0 800 400" xmlns="http://www.w3.org/2000/svg"
style="width:100%;max-width:800px;height:auto;font-family:system-ui,sans-serif">
<!-- SVG 内容 -->
</svg>
`;
```
要点:
- 用反引号模板字符串(
`)包裹 SVG,方便多行写
- SVG 内容里如果有反引号或
${...},需要转义 —— 但学习笔记里的 SVG 基本不会出现这俩
container 不用写额外样式,让 SVG 自己撑开
SVG 自身的规范(和原来一样)
背景透明:SVG 根元素不设 background,让 Obsidian 主题背景透出来。
颜色从 tokens 取:不要随手写 fill="#4a7dc4",查 references/style-tokens.md,让一篇笔记里色系保持统一。
尺寸:用 viewBox,宽度用 width="100%" 或 max-width,让图在不同宽度的 Obsidian 窗口里自适应。
字体:不指定具体字体,用 font-family="inherit" 或 system-ui, sans-serif,跟随 Obsidian。
模板库
常见模式(学习路径卡片、流程图、架构图、状态机、时序图、对比表)的完整 SVG 模板 见 references/patterns.md。模板里给出的是纯 SVG 代码,使用时必须外层包一层 dataviewjs 块。
**重要:那些是参考词汇,不是限制。**看到内容不完全匹配某个模板时,改造它、组合它、或者原创一个。references/design-thinking.md 里列了 20+ 种设计模式、以及"如何从内容结构推出视觉形式"的思维框架。先想清楚,再动手。
前提提示
因为所有视觉块(静态 SVG + 交互块)都走 dataviewjs 管道,每篇笔记的开头都要加一行提示,让用户知道需要装插件:
> ℹ️ 本笔记使用 dataviewjs 渲染图表与交互块,需要启用 Obsidian 的 **Dataview 插件**(并在插件设置里打开 "Enable JavaScript Queries")。
dataviewjs 交互块规范(真·交互形式)
和"SVG 包裹"的区分
上一节讲的 dataviewjs 是静态 SVG 的容器——只是把 SVG 塞进去,没有交互。
这一节讲的是真正的交互——滑块、按钮、展开、动态筛选、参数调整等。
两者在代码形态上不同:
- 静态 SVG 容器:
container.innerHTML = \...`` — 一行搞定,SVG 塞进去就完事
- 真交互块:用 DOM API 创建控件、绑事件、做状态管理
何时用真交互
- 用户要调节参数看结果变化(例:大 O 复杂度滑块)
- 决策式问答(例:点击按钮选择,显示下一问)
- 动态筛选、折叠展开
- 参数化演示(例:哈希表装载因子)
- 同一内容需要在多个视角间切换才容易理解
- 总览与细节适合分层揭示,一次性平铺反而难看
- 用户虽然没点名"交互",但交互形式明显比静态图更有展示力
- 内容存在条件分叉,交互能把"会走哪条路 / 为什么走这条路"单独拎出来
- 内容是多概念辨析,交互能让读者一次只聚焦一个概念,避免术语串线
选择原则
不要按"实现复杂度"选形式,要按"展示效果"选形式:
- 如果静态图已经是最佳展示,就用静态图
- 如果交互块能明显提升理解和展示,就用交互
- 如果最佳交互依赖浏览器能力,而用户又没要求 Obsidian,就输出独立 HTML
一个关键反例:不要破坏"一眼总览"
有些内容的核心优势就是一眼看完整体流程。这类内容通常更适合静态流程图、时序图、总览图,不适合拆成逐步点击:
- 读者需要先看到完整主线,再回头看细节
- 静态图本来就已经足够直观
- 一旦改成交互,会把整体感拆碎,让读者来回点击
典型例子:完整的故障转移主线、端到端请求时序、总体架构总览。
判断标准:
- 如果交互会让读者失去"扫一眼就知道全貌"的能力,那就是过度交互
- 如果静态图最大的价值正是整体扫视,就保留静态,不要为了互动而互动
基本形态
```dataviewjs
const container = dv.el("div", "", { cls: "viz-interactive" });
container.style.cssText = "padding:16px;border-radius:12px;background:transparent;";
// 构建 DOM
// 绑定事件
// 用 createElement 而不是 innerHTML(真交互块里不要混用,方便状态重渲染)
```
详细示例(折叠卡片、参数调节、动态对比)看 examples/interactive-concept.md。
风格与色彩
极简 + 功能色。每一笔颜色都要承载语义,不是为了"好看"。
从 references/style-tokens.md 里挑配色。核心原则:
- 同一篇笔记里色系要统一,最多 2 套调色板(主 + 辅)
- 柔和粉彩(pastel)背景 + 饱和度适中的强调色,不要纯黑纯白对比
- 圆角统一 12px
- 卡片之间留白 16-20px
- 文字
#1F2937(深灰而非纯黑),辅助文字 #6B7280
工作流程(写一篇笔记时)
- 先理解用户问题,判断是否需要视觉化(Step 0)
- 起草文字内容——把要讲的东西用纯文字列大纲,确定哪几处会从视觉化中受益
- 识别结构本质——每个视觉化点,它的内容是序列?层次?关系?对比?状态?这一步决定形式
- 防滑向阶段卡片——读
design-thinking.md 最前面的"反模式警告"自检:这个内容是不是真的"有严格先后顺序"?如果只是"并列分工""循环迭代""历史主题差异",换形式
- 选择或设计形式——先看
references/design-thinking.md 的思维框架,再去 references/patterns.md 找匹配的模板。找不到完全匹配的,就改造/组合/原创
- 查 tokens——从
references/style-tokens.md 挑色,保持一篇笔记色系统一
- 写文件到目标路径(Step 1),所有进入 .md 的 SVG 都用 dataviewjs 包裹
- 自检(都要做,不要跳):
- SVG 语法完整(
<svg> 有对应闭合,每个 <g>、<rect>、<text> 都闭合)
- 相邻 text 元素的 y 坐标差 ≥ 行高(一般 font-size 12 → y 差至少 16),避免文字重叠
- SVG 图层顺序正确:架构图/流程图/状态机里连线先画、方块后画,避免线压在方块上(详见
design-thinking.md 的"线"小节)
- 所有 SVG 都在 dataviewjs 块内,不是裸写
- 笔记开头有 Dataview 插件提示
- markdown 结构清晰,没有孤立的 HTML tag
- 告诉用户文件位置和笔记核心结构,不要把整篇笔记正文复述一遍——用户点开文件自己看就行
示例索引
examples/ 目录下有 5 个完整示例,特意选择了 5 种不同的设计语言,让你看到可视化的形式谱系——不是每个问题都该套"阶段卡片":
learning-path.md — 阶段卡片堆叠:用于"顺序推进的学习路线"architecture-diagram.md — 分层 + 连线:用于"系统架构"interactive-concept.md — dataviewjs 滑块 + 条形:用于"参数探索类的交互概念"timeline-evolution.md — 水平时间线 + 事件卡片:用于"历史演进、版本迭代"concept-relations.md — 维恩图 + 决策树:用于"概念间的抽象关系、权衡取舍"
这五种设计语言有完全不同的空间组织。看完这几个示例你应该意识到:同样是"视觉化",形式差异巨大,选哪种完全取决于内容的结构本质。
第一次处理某一类需求时,找结构最接近的示例参考——但不要直接复制,理解它为什么这么设计,然后按你的内容调整。
反模式(做了就说明走偏了)
| 症状 | 说明 | 修正 |
|---|
| 生成了一个 index.html + style.css + script.js 的小网站 | 走成博客风了 | 改成单个 .md,内容内嵌 |
SVG 里把颜色都写死 fill="#123456" | 难维护,色系也容易乱 | 查 tokens,用命名色 |
| dataviewjs 里塞了几百行逻辑还没测 | 过度复杂 | 拆成更小的块,或者退回到静态 SVG |
笔记开头一大段 <style> | Obsidian 会剥离 | 样式内联到元素上 |
| 图片比文字还多 | 本末倒置 | 文字为主,图是补强 |
| 用了渐变、阴影、玻璃态、霓虹色 | 花哨但不增信息量 | 回归纯色 + 细边框 |
| 给每段都配了图 | 过度视觉化 | 只给真正需要视觉化的段落配图 |
最后
这个 skill 的精神是:让读者在 Obsidian 里扫读时,视觉块能像路标一样引导注意力。所有设计决策——色系、布局、透明背景、嵌入方式——都服务于这个目标。
有疑惑时,去读 references/ 和 examples/,那里有具体的怎么做。
