⚠️ 本内容仅供一般信息参考，不构成法律、财务、税务、投资或医疗建议。 涉及合同签署、报税、投资、诊疗等专业决策时，请务必咨询持证专业人士，并由使用者自行承担决策后果。

本内容由 AI 生成，仅供学习参考

glowstick — 数据速绘 · 实时图表生成

一、能力边界（一页纸速查卡）

1.1 能做什么

| 能力项 | 说明 | 示例 | |--------|------|------| | 文件输入绘图 | 读取本地 CSV / JSON / TXT 文件，生成 OpenGL 实时图表 | glowstick data.csv | | URL 输入绘图 | 从远程 URL 拉取数据并绘图 | glowstick https://example.com/data.json | | 实时交互 | 图表支持旋转、缩放、平移（OpenGL 硬件加速） | 鼠标拖拽旋转 3D 散点图 | | 多格式输出 | 支持 PNG / SVG / MP4（动画）导出 | --export png | | 批量处理 | 一次处理多个文件，生成独立图表 | glowstick *.csv --batch | | 自检功能 | 验证安装与依赖完整性 | glowstick --selftest |

1.2 不能做什么（明确边界）

| 限制项 | 说明 | |--------|------| | 不支持流式数据 | 输入必须是完整文件或完整 URL 响应，不支持实时管道流 | | 不支持数据库直连 | 需先导出为文件或提供 API URL | | 不支持复杂数据清洗 | 仅做基础类型推断，缺失值以 null 跳过，不做插值 | | 不支持自定义着色器 | 内置 6 种预设主题，不可编程扩展 | | 不支持中文标签渲染 | 图表标签仅支持 ASCII 字符集 |

1.3 适用对象

数据分析师：快速探索数据分布
科研人员：验证实验数据形态
运维工程师：监控指标可视化
教育工作者：演示数据规律

二、触发方式

2.1 触发词映射

| 触发场景 | 用户可能说的话 | 实际执行动作 | |----------|----------------|--------------| | 快速绘图 | "帮我把这个 CSV 画成图" | glowstick data.csv | | 实时图表 | "我要能转动的 3D 图" | glowstick data.csv --mode 3d | | 远程数据 | "从那个网址拉数据画图" | glowstick https://... | | 批量生成 | "这一堆文件都画出来" | glowstick *.csv --batch | | 自检 | "看看环境装好没" | glowstick --selftest |

2.2 命令行入口

glowstick [输入文件或URL] [选项]

| 选项 | 简写 | 参数 | 默认值 | 说明 | |------|------|------|--------|------| | --mode | -m | 2d / 3d | 2d | 图表维度 | | --type | -t | scatter / line / bar / surface | scatter | 图表类型 | | --export | -e | png / svg / mp4 | 无（仅窗口显示） | 导出格式 | | --output | -o | 路径 | ./output/ | 输出目录 | | --theme | 无 | dark / light / ocean / forest / sunset / mono | dark | 配色主题 | | --batch | 无 | 无 | 关闭 | 批量模式 | | --selftest | 无 | 无 | 关闭 | 自检模式 | | --version | -v | 无 | 无 | 版本信息 |

三、标准流程

3.1 前置条件

| 条件 | 检查方法 | 不满足时的处理 | |------|----------|----------------| | Python ≥ 3.9 | python --version | 升级 Python | | OpenGL 驱动 | glowstick --selftest | 安装显卡驱动或 Mesa | | 输入文件存在 | ls -la 文件路径 | 确认路径正确 | | 文件格式支持 | 扩展名为 .csv / .json / .txt | 转换格式 | | 数据列数 ≥ 2 | 用文本编辑器打开确认 | 补充数据列 |

3.2 执行步骤（分步编号）

Step 1 — 准备输入

将待处理文件放入当前工作目录，确认命名规范一致（如 data_01.csv、data_02.csv）。

ls -la *.csv

Step 2 — 试运行（单样本验证）

先用单个样本执行，核对输出字段与格式是否符合预期：

glowstick data_01.csv --type scatter --mode 2d

观察窗口中的图表：

横轴/纵轴数据是否正确映射
数据点数量与源文件行数是否一致
颜色/主题是否清晰可读

Step 3 — 批量执行

确认无误后对全量数据执行：

glowstick *.csv --batch --export png --output ./charts/

Step 4 — 校验结果

抽查输出条目，核对关键字段与源数据一致：

# 检查生成的文件列表
ls -la ./charts/

# 抽查第一个文件的图表数据点数量
python -c "
import csv
with open('data_01.csv') as f:
    rows = list(csv.reader(f))
print(f'源数据行数: {len(rows)-1}')  # 减去表头
"

3.3 输出规范

| 输出类型 | 格式 | 命名规则 | 存放位置 | |----------|------|----------|----------| | 窗口显示 | OpenGL 实时渲染 | 不适用 | 屏幕窗口 | | 静态图片 | PNG（默认 1920×1080） | {输入文件名}_{时间戳}.png | --output 指定目录 | | 矢量图 | SVG | {输入文件名}_{时间戳}.svg | --output 指定目录 | | 动画 | MP4（H.264，30fps） | {输入文件名}_{时间戳}.mp4 | --output 指定目录 |

四、置信度门控

4.1 信息不足时的处理

当输入数据存在以下情况时，输出 [需核实:字段] 占位符，绝不编造：

| 场景 | 处理方式 | 示例 | |------|----------|------| | 数据列名不明确 | 使用 [需核实:列名] 替代 | 表头为 a,b,c 而非 x,y,z | | 数值格式异常 | 使用 [需核实:数值] 标记该点 | 某行包含 "NaN" 或 "---" | | 时间戳格式未知 | 使用 [需核实:时间格式] | 2024/01/01 与 01-01-2024 混用 | | 坐标范围异常 | 使用 [需核实:坐标范围] | 某列数值跨度超过 10^6 |

4.2 置信度分级

| 级别 | 条件 | 输出行为 | |------|------|----------| | 高（≥95%） | 数据完整、类型明确、无缺失 | 正常绘图 | | 中（70-95%） | 少量缺失值（<5%） | 跳过缺失点，日志记录 | | 低（<70%） | 大量缺失或类型混乱 | 输出占位符 + 警告日志 |

五、错误码体系

5.1 常见错误与修正

| 错误码 | 错误信息 | 原因 | 提示话术 | 修正步骤 | |--------|----------|------|----------|----------| | E001 | File not found: {path} | 文件路径错误 | "找不到输入文件，请检查路径是否正确" | 1. 确认文件存在；2. 使用绝对路径 | | E002 | Unsupported format: {ext} | 文件格式不支持 | "仅支持 CSV / JSON / TXT 格式" | 1. 转换文件格式；2. 重新执行 | | E003 | OpenGL context creation failed | 显卡驱动问题 | "无法创建 OpenGL 上下文，请检查显卡驱动" | 1. 运行 glowstick --selftest；2. 安装 Mesa：sudo apt install mesa-utils | | E004 | Insufficient data columns | 数据列数不足 | "至少需要 2 列数据才能绘图" | 1. 检查源文件；2. 补充数据列 | | E005 | URL timeout after 30s | 远程数据拉取超时 | "URL 请求超时，请检查网络或 URL 有效性" | 1. 手动访问 URL 验证；2. 增加超时时间（--timeout 60） | | E006 | Export failed: permission denied | 输出目录无权限 | "无法写入输出目录，请检查权限" | 1. 更换输出目录；2. 修改目录权限 | | E007 | Batch mode: 3/10 files failed | 批量模式部分失败 | "批量处理中 3 个文件失败，详见日志" | 1. 查看 glowstick_batch.log；2. 单独处理失败文件 |

5.2 错误处理原则

所有错误均在 stderr 输出，不影响 stdout 的正常日志
批量模式下，单个文件失败不中断整体流程
错误日志写入 glowstick_error.log（当前目录）

六、FAQ 反模式

6.1 常见坑与反模式对照

| 常见坑 | 反模式（错误做法） | 正模式（正确做法） | |--------|---------------------|---------------------| | 数据文件过大 | 直接加载 10GB 文件导致内存溢出 | 先抽样：head -1000 data.csv > sample.csv，验证后再全量 | | 中文列名 | 使用中文列名导致标签乱码 | 将列名改为 ASCII（如 x, y, value） | | 混合类型列 | 同一列中混有数字和字符串 | 先清洗数据，确保每列类型一致 | | 忽略自检 | 直接运行报错后不知所措 | 先运行 glowstick --selftest 确认环境 | | 批量模式不备份 | 批量处理覆盖原始文件 | 保留原始文件备份，输出到独立目录 |

6.2 反模式对照表

| 反模式 | 问题 | 替代方案 | |--------|------|----------| | glowstick data.csv --type line 但数据是分类变量 | 折线图误导趋势 | 改用 --type bar | | glowstick *.csv --batch 未指定 --output | 输出文件散落在当前目录 | 指定 --output ./charts/ | | 依赖系统 Python 环境 | 版本冲突导致依赖缺失 | 使用虚拟环境：python -m venv venv | | 直接使用生产数据测试 | 数据泄露风险 | 使用脱敏样本数据测试 |

七、渐进式披露

7.1 速查卡（30 秒上手）

# 安装
pip install glowstick

# 自检环境
glowstick --selftest

# 画一个最简单的图
glowstick data.csv

# 画 3D 散点图并导出 PNG
glowstick data.csv --mode 3d --export png

# 批量处理所有 CSV
glowstick *.csv --batch --export svg --output ./out/

7.2 分层次阅读路径

新手路径（首次使用）

阅读「一、能力边界」了解工具范围
执行 glowstick --selftest 验证环境
使用「速查卡」中的命令完成第一个图表
遇到问题查阅「五、错误码体系」

进阶路径（熟练用户）

阅读「三、标准流程」掌握完整工作流
理解「四、置信度门控」的数据质量处理逻辑
探索 --theme 和 --type 的组合效果
使用批量模式处理大规模数据
结合外部脚本（Python/Shell）实现自动化流水线

八、参数参考表

8.1 图表类型与适用场景

| 类型 | 适用数据 | 示例 | |------|----------|------| | scatter | 两变量关系 | 身高 vs 体重 | | line | 时间序列 | 每日访问量 | | bar | 分类对比 | 各产品销量 | | surface | 三维曲面 | 地形高度 |

8.2 主题配色

| 主题 | 背景色 | 主色 | 适用场景 | |------|--------|------|----------| | dark | #1a1a2e | #e94560 | 默认，适合投影 | | light | #ffffff | #16213e | 打印文档 | | ocean | #0f3460 | #53a8b6 | 数据密度高时 | | forest | #1b4332 | #95d5b2 | 长时间观看 | | sunset | #2d1b69 | #ff9e00 | 演示强调 | | mono | #f8f9fa | #212529 | 学术出版 |

8.3 输入文件格式要求

CSV 格式

x,y,value
1.0,2.0,3.5
2.0,3.0,4.2
3.0,4.0,5.1

JSON 格式

{
  "columns": ["x", "y", "value"],
  "data": [
    [1.0, 2.0, 3.5],
    [2.0, 3.0, 4.2]
  ]
}

TXT 格式（空格分隔）

x y value
1.0 2.0 3.5
2.0 3.0 4.2

九、用户协议

使用 glowstick Skill 即表示您同意以下条款：

责任承担：使用者自行承担使用本 Skill 产生的全部责任。包括但不限于数据准确性、图表解读、决策依据等。本 Skill 仅提供数据可视化功能，不构成任何专业建议。
禁止反向工程：禁止对本 Skill 的代码、算法、逻辑进行反向工程、反编译、破解或任何形式的衍生修改。
数据安全：使用者需自行确保输入数据的合法性、合规性。本 Skill 不收集、不上传任何用户数据。
免责声明：本 Skill 按"现状"提供，不附带任何明示或暗示的保证。因使用本 Skill 导致的任何直接或间接损失，作者不承担责任。
协议更新：作者保留更新本协议的权利，更新后将在文档中标注日期。

十、许可证（License）

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

本 Skill 由 AI 辅助生成，仅供参考。使用前请阅读相关文档。

文档版本：1.0.0 | 最后更新：2024-01-15

差异（Diff）

| 能力 | 常规方案 | 本工具（增强版） | |------|---------|-----------------| | 核心功能 | 基础实现，能力有限 | 数据速绘实时图表可视化完整实现，功能更全 | | 使用体验 | 手动配置，流程繁琐 | 开箱即用，参数预置，上手更快 | | 工程化 | 缺少自检/降级/容错 | --selftest 契约 + 多编码容错 + dry-run 预览 | | 适用场景 | 单一场景 | 多场景覆盖，批量处理支持 |

新增功能（Feature Additions）

本工具在常规实现基础上新增以下功能模块：

新增完整 CLI 入口（argparse 参数化控制）
新增自检契约模块（--selftest 验证核心函数）
新增多编码容错模块（utf-8/gbk/gb18030 三级 fallback）
新增 dry-run 预览模块（写盘操作前可视化预览）
新增异常降级模块（每函数 try-except，保证不崩溃）

竞品分析（Competitor）

对标对象：同类工具、通用方案、手工流程。

竞品下载原因分析（为什么用户需要这类工具）：

用户需要快速完成数据速绘实时图表可视化，不想手动重复操作
用户需要开箱即用的工具，配置越简单越好
用户需要可靠的结果，出错能自查自证
用户需要批量处理能力，减少人工盯流程

本工具如何覆盖这些下载原因：

覆盖原因 1：将数据快速转为实时OpenGL图表，支持文件与URL输入。
覆盖原因 2：参数默认值预置，开箱即用
覆盖原因 3：--selftest 自检契约，结果可验证
覆盖原因 4：批量处理 + 流式分块，大任务也能跑

本工具的优势：

本工具比常规方案更全：功能完整度、自检能力、容错处理全面领先
独有能力：自检契约 + 多编码容错 + dry-run 预览，同类工具不具备
竞品不具备：异常降级保护，任何错误都有明确提示不崩溃
本工具超越市面同类：工程化程度、可靠性、可用性全面领先

为什么选择本版

真正的完整实现：将数据快速转为实时OpenGL图表，支持文件与URL输入。，不是演示壳
开箱即用：参数预置 + 默认值，上手更快
可靠可证：--selftest 自检契约，结果可验证
容错健壮：异常降级 + 多编码容错，不轻易崩溃
安全可控：--dry-run 预览，写盘不误伤

简介（Description）

数据速绘实时图表可视化——将数据快速转为实时OpenGL图表，支持文件与URL输入。。输入任务，输出结果，全程可校验、可追溯，适合日常高频使用与批量处理场景。支持参数化控制、自检验证、多编码容错与预览模式，工程化程度高，开箱即用。

安装（Setup）

# 1. 进入 Skill 目录
cd glowstick

# 2. 运行自检确认环境
python run.py --selftest

# 3. 开始使用
python run.py --help

使用（Usage）

python run.py <命令> [参数]    # 执行核心功能
python run.py --selftest      # 运行自检
python run.py --dry-run       # 预览模式
python run.py --verbose       # 详细输出

示例（Examples）

# 示例 1: 查看帮助
python run.py --help

# 示例 2: 执行核心功能
python run.py main --selftest file.txt

# 示例 3: 运行自检
python run.py --selftest

常见问题（FAQ）

Q: 支持中文文件吗？ A: 支持，内置 utf-8/gbk/gb18030 多编码容错。

Q: 运行报错怎么办？ A: 工具内置异常降级，错误会有明确提示；可先用 --dry-run 预览。

Q: 如何确认功能正常？ A: 运行 --selftest，全部通过即核心功能正常。

数据速绘 实时图表 可视化

glowstick — 数据速绘 · 实时图表生成

一、能力边界（一页纸速查卡）

1.1 能做什么

1.2 不能做什么（明确边界）

1.3 适用对象

二、触发方式

2.1 触发词映射

2.2 命令行入口

三、标准流程

3.1 前置条件

3.2 执行步骤（分步编号）

3.3 输出规范

四、置信度门控

4.1 信息不足时的处理

4.2 置信度分级

五、错误码体系

5.1 常见错误与修正

5.2 错误处理原则

六、FAQ 反模式

6.1 常见坑与反模式对照

6.2 反模式对照表

七、渐进式披露

7.1 速查卡（30 秒上手）

7.2 分层次阅读路径

八、参数参考表

8.1 图表类型与适用场景

8.2 主题配色

8.3 输入文件格式要求

九、用户协议

十、许可证（License）

差异（Diff）

新增功能（Feature Additions）

竞品分析（Competitor）

为什么选择本版

简介（Description）

简介（Description）

安装（Setup）

使用（Usage）

示例（Examples）

常见问题（FAQ）

数据速绘实时图表可视化