CZSC / 可视化
czsc 可视化：单周期、权重与自包含 HTML 三种产出
缠论结构如果不画出来，很难判断识别得对不对。官方把可视化统一收敛到两条技术栈上：交互式图表库用于单周期与权重，前端图表库用于生成可以离开发送的自包含 HTML。这一页说明三种产出各自适合什么，以及怎么导出。
三种产出，形态完全不同
官方把可视化收敛成两条技术栈：一条输出交互式图表对象，另一条输出自包含的 HTML 文件。下表按官方 README 的可视化表整理。
| 模块 | 产出形态 | 能看到什么 | 适用场景 | 注意点 |
|---|---|---|---|---|
| 单周期 K 线模块 | 交互式图表对象 | K 线与缠论结构 | 检查结构识别是否合理 | 在笔记本里可直接显示；要外发需另存为 HTML |
| 权重时序模块 | 交互式图表对象 | 权重随时间的变化 | 核对策略的目标仓位 | 它画的是目标权重，不是成交记录 |
| 轻量图表模块 | 自包含 HTML 文件 | 多周期联立 + 信号叠加 | 分享、嵌入、离线查看 | 文件自包含，不依赖外部资源，可直接双击打开 |
| 回测报告 | 可交互 HTML | 绩效与回撤等汇总视图 | 回测结束后的整体复盘 | 它由外部回测包的函数产出，不是本库的绘图模块 |
| 其他汇总视图 | 按需自绘 | 累计收益、回撤、月度热力图等 | 需要在报告里自定义板块时 | 官方说明这类视图改用外部报告函数或直接基于交互图表库实现 |
导出 HTML 的分步流程
官方给出的三个入口都能产出 HTML：单周期结构、多周期联立、以及把信号画到主图上。下面以多周期联立为例。
准备分析对象
先用结构分析对象或交易器把数据跑出结果。预期得到含笔、中枢等结构信息的对象，或含持仓状态的交易器对象。
调用绘图入口
单周期用结构对象对应的绘图函数；多周期联立用交易器对应的绘图函数；需要把信号标在图上时用信号叠加的绘图入口。预期拿到 HTML 字符串或生成文件。
写出文件并打开
指定输出路径写出 HTML，然后用浏览器打开。预期看到交互式图表，且断网也能正常显示（文件自包含）。
交付或归档
把 HTML 直接发给同事或归档，对方无需安装任何环境。预期对方打开即可查看同一份结果。
选型对照：什么时候用哪种
三种产出没有优劣，只是用途不同。按「结果给谁看、要不要改」来选最快。
| 你的场景 | 选哪种 | 理由 | 需要接受的代价 |
|---|---|---|---|
| 调试结构识别对不对 | 单周期 K 线图 | 能直接在画布上核对笔与中枢的位置 | 只覆盖当前周期 |
| 检查策略仓位变化 | 权重时序图 | 一眼看出仓位何时变化、幅度多大 | 不显示成交细节 |
| 把多周期结果分享给别人 | 自包含 HTML | 对方无需环境、离线可看 | 文件体积随数据量增长 |
| 回测结束做整体复盘 | 回测报告 HTML | 绩效与回撤视图一次到位 | 样式随外部包版本变化 |
| 要在报告里加自定义板块 | 基于交互图表库自绘 | 完全可控 | 需要自己维护绘图代码 |
| 只要一张静态图放进文档 | 导出图片 | 便于插入文档与聊天工具 | 丢失交互与缩放 |
命令行入口的八个子命令
除编程接口外，官方还提供命令行入口，实测包含以下子命令模块。适合做批处理与快速查看。
| 子命令 | 用途 | 适用场景 | 注意点 |
|---|---|---|---|
| analyze | 结构分析 | 命令行查看一段数据的结构结果 | 参数与输出格式以实际帮助信息为准 |
| backtest | 回测 | 批处理回测 | 回测能力来自外部包，参数口径要核对 |
| bench | 性能基准 | 本地评估吞吐量 | 官方有配套的基准案例与指标速查表 |
| data | 数据相关操作 | 取数与格式处理 | 需要先配置好数据源凭据 |
| plot | 绘图 | 命令行直接产出图表或 HTML | 输出路径要显式指定 |
| research | 批量研究 | 多品种批量任务 | 耗时随品种数增长 |
| schema | 结构定义查看 | 查看可用的字段与结构 | 便于写配置时对照 |
| signals | 信号相关操作 | 查看与导出信号 | 仓库另有导出信号目录与详情的脚本可用 |
可视化排查表
绘图不报错但结果不对的情况很常见，下表按现象倒查。
| 现象 | 可能原因 | 核对方法 | 处理方向 |
|---|---|---|---|
| 图上结构明显不对 | 成笔参数与环境变量不一致，或数据时间刻度偏移 | 对照构造参数与数据时间列 | 先修数据与参数，再重画；图本身不会修正逻辑 |
| 多周期图里某个周期是空的 | 信号涉及的周期没有被纳入合成列表 | 用信号周期提取接口核对需要哪些周期 | 补齐周期后再生成 |
| 权重曲线与预期不符 | 图画的是目标权重而非成交后仓位 | 区分目标状态与实际持仓两个概念 | 需要成交口径时改用持仓与成交数据 |
| HTML 打开空白 | 数据为空或写出路径有误 | 检查输入数据长度与目标文件大小 | 先用模拟数据跑通再换真实数据 |
| 图能看但不方便外发 | 产出的是交互图表对象而不是 HTML | 确认调用的是输出 HTML 的入口 | 改用自包含 HTML 的导出方式 |
| 回测报告样式与文档不一致 | 报告由外部回测包生成，随其版本变化 | 核对外部包版本 | 锁版本再复现 |
出图这一段，两条路线怎么选
画图本身不难，区别在于数据从哪里来、是否需要交互。
| 维度 | 本库的可视化 | EasyClaw 出图类技能 | 怎么选 |
|---|---|---|---|
| 产出形态 | 交互式图表对象与自包含 HTML | 出版级静态图表图片 | 要交互用前者，要插图用后者 |
| 图形内容 | 缠论结构、权重、多周期联立与信号叠加 | 折线、柱状、面积、蜡烛图、热力图等通用图表 | 要叠加缠论结构只能自建 |
| 数据来源 | 来自你已接入的数据与结构分析结果 | 来自提问中得到的数据 | 数据已在代码里就用前者 |
| 分享方式 | HTML 文件直接发送，离线可看 | 图片文件直接发送 | 两者都无需对方装环境 |
常见问题
可视化相关的模块归属与产出形态以官方 README 可视化表与使用案例为准。
官方提供哪几种可视化？
按 README 的表，主要三类：单周期 K 线加缠论结构（交互式图表对象）、权重时序图（交互式图表对象）、以及多周期联立与信号叠加的自包含 HTML。此外回测报告由外部回测包的函数一键产出。
自包含 HTML 是什么意思？
官方文档的描述是「自包含 HTML，离线即可打开」。也就是说图表所需资源都写在这个文件里，不依赖外部链接。发给别人时对方无需安装 Python 或联网加载资源，双击就能看。
为什么图上的结构和我预期不一样？
图只是把计算结果画出来，它不会修正逻辑。结构不对通常有两个原因：一是成笔参数或环境变量与你的预期不一致（注意 1.0.1 之前该环境变量是无效的），二是数据时间刻度存在偏移。建议先核对参数与数据，再重画。
多周期图里为什么有周期是空的？
多半是信号涉及的周期没有被计入 K 线合成的周期列表。可以用官方的信号周期提取接口先确认需要哪些周期，再回到合成环节补齐，重新生成图表。
有没有命令行方式出图？
有。官方提供命令行入口，实测包含分析、回测、基准、数据、绘图、研究、结构定义与信号八个子命令模块。具体参数请以你安装版本的帮助输出为准，本文只列出子命令的存在与职责。
只想出一张图放进文档，走哪条路？
如果图表内容就是通用图表（折线、蜡烛图之类），用 EasyClaw 的出图类技能更直接，生成的是静态图片，插入文档方便；如果你要把缠论结构或权重曲线画出来，就必须先在本库侧算出结果再绘图导出。两者没有已证实的集成关系。