微信扫一扫核心规则
1. 数据处理 → 生成
- 理解原始格式 — 检查数据格式（HTML/CVS/XML/专有格式），确认变量类型和分布
- 写单次解析脚本 — 用 Python 将原始数据提取为标准 JSON（格式见
references/data-formats.md），输出到.opencode/.tmp/ - 选模板 — 从 10 种图表类型中选取或告知 AI 需求，AI 匹配合适类型
- 自定义参数 — 调整主题
--theme（nature/lancet/conservative/default）、配色、尺寸、标注等 - 生成输出 — SVG + PDF + TIFF (600 dpi)，可选 PNG，确认后生成
2. 调用方式
CLI 模式（推荐）：
python scripts/generate_figure.py --type bar --data data.json --output ./figure --theme nature
自动推荐模式（根据数据格式匹配合适类型）：
python scripts/generate_figure.py --auto --data data.csv --output ./figure --theme nature
数据预览模式（不生成图表，仅打印分析）：
python scripts/generate_figure.py --profile --data data.csv
JSON spec 模式（向后兼容）：
python scripts/generate_figure.py spec.json ./output
3. 图表类型
| 类型 | 说明 | 关键参数 |
|------|------|----------|
| bar | 柱状图（分组/堆叠） | --stacked, 误差线, 显著性标记 |
| line | 折线图（误差带） | --ci, --markers |
| scatter | 散点图（趋势线/置信区间） | --trend, --ci |
| scatter3d | 3D 散点图 | --color_column, --label_column |
| box | 箱线图（散点抖动） | --jitter |
| violin | 小提琴图 | — |
| heatmap | 热力图（矩阵/带注释） | --cmap, --annotate |
| forest | 森林图（效应量+置信区间） | JSON 专用 |
| histogram | 直方图 | bins |
| pie | 饼图 | — |
4. 配置须知
- 主题：nature / lancet / conservative / default
- 输出：SVG（可编辑矢量）+ PDF（出版提交）+ TIFF（600 dpi），可选 PNG
- CJK：自动检测中文字符，检测失败手动加
--cjk - 环境：conda 环境通过
chartkit.json声明（默认Python313），依赖 matplotlib 3.10+ - 不做：交互式图表、非科学插图、跨语言回退
- 缺失依赖：运行时检测 matplotlib 是否可用，不可用则报 blocker
何时使用
用户需要从模板生成论文级科学图表，或对已有模板自定义参数调整样式时。
所需权限
| 权限 | 值 | 说明 |
|------|----|------|
| read | allow | 读取用户提供的数据文件 |
| write | allow | 写入生成的图表文件 |
| bash | allow | 执行 Python 脚本生成图表 |
| external_directory | ask | CSV 和 spec 路径可能在项目外 |
数据存储
图表文件输出到用户指定目录。chartkit.json 为运行时配置（conda 环境名等），不进出发布包。临时测试文件写入 .opencode/.tmp/。
常见陷阱
| 陷阱 | 解决 |
|------|------|
| 跳过自定义直接生成 | 步骤 4 前应确认参数再生成 |
| 手动转录原始数据 | 永远写解析脚本提取，不手工复制粘贴到 JSON |
| 中文标签显示为方块 | 脚本自动检测 CJK 字体；未检测到时手动加 --cjk |
| SVG 文本不可编辑 | svg.fonttype: none 确保文字可编辑 |
| 路径硬编码 | 通过 conda env name 而不是路径声明环境 |
| 解析脚本输出用系统临时目录 | 所有临时文件指向 .opencode/.tmp/ |
反馈
在 opencode-skill-suite 提交 Issue 或 PR。