version: "1.0.1"

<!-- 名称 -->

名称

name: visualization

<!-- 描述 -->

# 描述

description: 构建并路由 A 股可视化任务到 utils/visualizers 与 utils/visualizer_manager.py 的正确图表管线。用于用户请求个股、指数、板块、市场情绪或模型结果图表，且需要判断所需输入字段、方法选择与输出格式（嵌入式 HTML 或 ECharts 选项）。

<!-- A 股可视化 -->

# A 股可视化

将可视化请求路由到稳定的图表 API。 在绘图前校验数据契约，并输出前端可直接使用的结果。

<!-- 工作流程 -->

# 工作流程

1. 按领域分类请求。
2. 选择精确的图表 API。
3. 校验必需字段与数据质量。
4. 生成符合约定的输出格式。
5. 报告限制与降级行为。

<!-- 步骤 1：分类请求 -->

# 步骤 1：分类请求

将请求映射到一个领域：

• stock：个股 K 线、换手率、多股对比、新高股视图
• index：指数 K 线、多指数对比、盘中成交量对比
• sector：板块 K 线、成交额榜、排行、分布
• market：情绪、涨跌停、炸板、连板梯队
• model：模型选股结果可视化

不确定时先查看 references/api-map.md。

<!-- 步骤 2：选择 API -->

# 步骤 2：选择 API

优先使用 VisualizerManager 的门面方法。 仅在管理器未覆盖所需变体时直接调用可视化器方法。 关键路由规则：

• K 线相关优先使用 UniversalKlineChart.plot_kline_with_volume 系列。
• 前端需要 ECharts 选项时使用 IndexVisualizer.get_multi_index_kline_options。
• 前端需要嵌入式 HTML 时使用 plot_*().render_embed() 路径。

<!-- 步骤 3：校验数据契约 -->

# 步骤 3：校验数据契约

绘图前执行以下检查：

• 数据框非空。
• 必需字段存在。
• 日期字段排序与字符串格式归一。

<!-- 使用方法 -->

# 使用方法

使用：

• ChartUtils.validate_data_columns
• ChartUtils.prepare_chart_data

所需字段参考 references/data-contracts.md。

<!-- 步骤 4：生成输出 -->

# 步骤 4：生成输出

返回以下之一：

• embedded_html：render_embed() 返回的字符串，用于直接页面渲染
• echarts_option：前端自定义渲染使用的 dict
• chart_map：多组件 HTML 字典（市场元数据组）

必须说明：

• 使用的方法
• 必需输入字段
• 已知限制或降级模式

<!-- 步骤 5：处理失败 -->

# 步骤 5：处理失败

失败需要明确、可执行：

• 空输入：返回简洁的“无数据”提示。
• 缺字段：列出缺失字段。
• 不支持请求：给出最接近的可支持图表及所需补充数据。

避免静默失败。

<!-- 参考资料 -->

# 参考资料

• references/api-map.md：领域到方法的路由表
• references/data-contracts.md：各图表所需字段契约
• references/output-contract.md：返回类型与前端集成约定

<!-- 资源文件 -->

# 资源文件

• assets/visualization-request-template.md：可复用的请求模板

<!-- 脚本扩展 -->

# 脚本扩展（新增图表能力）

新增图表函数请放在：

• scripts/chart_*.py
• 每个脚本通过 CHART_SPECS 暴露图表函数（推荐）或使用 plot_* 函数自动注册

运行时入口：

• scripts/visualization_gateway.py
• utils/visualizer_manager.py
• VisualizerManager.list_skill_charts()
• VisualizerManager.render_skill_chart(chart_id, **kwargs)

建议约定：

• 图表函数返回 embedded_html（字符串）或 echarts_option（dict）
• 函数参数使用显式命名，避免隐式全局状态
• 对空数据/缺字段返回清晰错误信息