用途
Viz 是一个研究可视化助手技能，目标是通过六阶段工作流帮助研究者创建研究级（research-quality）的可视化图表。其核心哲学是：在决定要说什么之前先让数据说话；在接触任何生产代码之前，先内化你想展示什么以及为什么；最后验证图表实际表达的内容是否与你的意图一致。
主要能力（六种模式）
- /viz ingest — 理解你手头有什么：数据结构（schema）、形状、质量（结构性）。
- /viz explore — 用一次性图表从多个角度观察数据，建立直觉。
- /viz brainstorm — 思考你究竟想可视化什么（哲学性）。
- /viz plan — 决定如何实现：图表类型、布局、数据来源（机制性）。
- /viz execute — 生成并运行代码（操作性）。
- /viz analyze — 反思图表，并对照你的假设进行验证（批判性）。
并非每张图都需要全部六个模式。早期模式（Ingest、Explore、Brainstorm）旨在帮助建立有经验研究者本就具备的直觉。如果你已经了解自己的数据并有清晰的可视化意图，可以直接跳到 /viz plan——也可以自行编写 braindump.md 记录意图，Plan 和 Execute 会自动读取。
如果用户不带模式调用 /viz，技能会评估其当前所处阶段并给出建议：有原始数据但不确定内容 → 建议 /viz ingest；了解数据但尚未查看 → 建议 /viz explore；已探索但未明确想展示什么 → 建议 /viz brainstorm；明确知道需要什么图 → 建议 /viz plan；已有 plot_context.md → 建议 /viz execute；已有图表想要反馈 → 建议 /viz analyze。
使用方式
模式 0：Ingest —“你有什么？”
目的是在视觉查看之前先理解数据的结构、形状和质量。这是机械性的基础——不理解结构就无法探索。
从命令行开始，而不是 Python。在导入任何东西之前，先用基本 Unix 工具查看原始数据，建立对文件内容的直接、未经中介的感觉。步骤包括：
- 定位数据：询问数据路径（CSV、Parquet、JSON、pickle 或结果目录）。
- CLI 初看：对 CSV/TSV 文件运行命令，例如
wc -l data.csv（行数）、ls -lh data.csv（文件大小）、head -5 data.csv、tail -5 data.csv、head -1 data.csv | tr ',' '\n' | nl（编号列名）、head -1 data.csv | awk -F',' '{print NF}'（列数）、cut -d, -f3 data.csv | tail -n+2 | sort | uniq -c | sort -rn | head -10（分类列频次）、cut -d, -f4 data.csv | tail -n+2 | sort -n | head -1（数值列最小值）、grep -c ',,' data.csv（空字段）、sort data.csv | uniq -d | wc -l（重复行）。完整 CLI 速查表见 reference/cli_data_inspection.md。二进制格式（Parquet、pickle）跳过 CLI 步骤。 - 读取并报告 schema：在 Python 中加载数据，报告列名、数据类型、行数、明显问题（NaN 计数、混合类型、可疑的 min/max），并询问列含义、单位、数据来源、实验条件编码、是否需要过滤。
- 标记数据质量问题：缺失数据、尺度问题（跨多个数量级）、重复或近似重复、类型不匹配、可疑值。
- 保存 data_summary.md：结构化摘要，包含来源、schema 表格、形状、质量说明。
输出：data_summary.md 文件。
模式 1：Explore —“让数据说话”
目的是在形成假设或确定图表类型之前，通过快速、一次性的可视化建立对数据的直觉（Tukey 的核心原则）。此模式生成的图表是丢弃式的——速度与覆盖面优先，不追求美观，使用 seaborn 默认样式。
关键：Explore 模式的代码不得带入生产图表。论文图表样式违规的最常见来源就是把探索代码（使用 sns.set_theme() 和 seaborn 默认值）复制到最终绘图脚本中。sns.set_theme() 会覆盖所有 matplotlib rcParams。进入 Execute 模式时，应从零编写生产脚本，使用实验室的 rcParams 设置。
步骤：
- 单变量概览：对每个数值列生成分布视图，例如
sns.histplot(df, x="column_name", kde=True)、sns.displot(df, x="column_name", kind="ecdf")、sns.kdeplot(df, x="column_name", hue="group_column")、sns.displot(df, x="column_name", col="group_column", kde=True)。选择建议：histplot 适合首次查看与计数，但受 bin 大小影响；kdeplot 适合跨组平滑比较，但在离散数据上可能误导；ecdfplot 是最安全的“直接展示数据”选项。同时检查摘要统计（均值、中位数、标准差、min、max、均值/中位数比）、对数尺度检查（跨 2 个数量级以上时）、分类列用sns.countplot。 - 双变量关系：
sns.pairplot(df, hue="group_column")、sns.scatterplot、sns.jointplot、sns.lmplot、sns.heatmap(df.select_dtypes("number").corr(), annot=True)、sns.boxplot、sns.swarmplot（仅小数据集）、sns.violinplot。分类比较选择：boxplot 适合快速摘要但看不到完整分布形状；violinplot 适合看完整分布形状但每组 N 很小时无意义；swarmplot/stripplot 适合看每个数据点但 N 大时重叠；barplot 比较均值但会隐藏分布，需谨慎。 - 时间或序列结构：
sns.relplot(df, x="time_column", y="value_column", kind="line")及带 hue/col 的变体。同时检查平稳性（滚动均值/标准差）、不同时间尺度（放大缩小）、噪声数据（平滑线加原始数据背景）。 - 询问学生注意到了什么：什么最突出？什么让你惊讶？缺了什么？数据看起来对吗（伪影、离群值、实验本身的问题）？如果数据有缺陷，明确提示可能需要在做图前重新审视实验。
- 保存 exploration_log.md：记录数据、关键观察、意外发现（最有价值的部分）、数据质量顾虑、提出的问题。
输出：exploration_log.md 和一组一次性图表。
模式 2：Brainstorm —“你想看到什么？”
目的是在任何代码编写之前帮助学生内化可视化目标。此模式是互动式、苏格拉底式的——你提问，学生回答，共同细化直到可视化意图完全清晰。此模式不写任何代码，也不建议图表类型。
步骤：
- 以 Tukey 问题开场：数据是什么？一个观测是什么？一个批次/组是什么？每组多少观测？你想回答什么问题（不是“想做什么图”，而是关于世界的什么问题）？你是在探索还是确认？
- 预测与意外：你预期看到什么？写下预测。什么会让你惊讶？这是最重要的问题。如果去掉明显的模式，剩下什么？
- 受众与论点：图表给谁看（自己的笔记本、给导师的 Slack、论文草稿、演示）？如果是论文：这张图支持哪一句话？能否指向正文中的确切论断？
- 综合、确认并保存 braindump：用 3–4 句话总结所学并回述给学生。
（资料在此处截断，后续 Plan、Execute、Analyze 模式的详细步骤暂未提供。）
适用场景
- 科研数据分析与论文图表制作。
- 需要从原始数据出发、逐步建立可视化意图的研究工作流。
- 使用 Python（pandas、seaborn、matplotlib）进行数据探索与绘图的环境。
- 需要区分探索性图表与生产级图表的场景。
限制
- 资料仅完整描述了 Ingest、Explore、Brainstorm 三个模式；Plan、Execute、Analyze 的详细步骤暂未提供。
- 依赖命令行工具与 Python 环境；二进制格式跳过 CLI 步骤。
- 探索模式图表为一次性产物，不适合直接用于正式展示。
- 具体安装方式、收费模式、支持平台等信息暂未提供。