@363045841yyt/klinechart 0.1.5 → 0.2.0

package/README.md

@@ -2,16 +2,28 @@
 
 [English](README_EN.md) | 简体中文
 
-这是一个基于 Vue 3 和 Canvas 的金融图表绘制库，专注于提供高性能的 K 线图展示功能。该库支持横向滚动、移动平均线（MA）显示以及从多种数据源（包括 **BaoStock**、AKTools）获取金融数据。
+这是一个基于 Canvas 的金融图表绘制库，提供 Vue 组件封装。专注于高性能 K 线图渲染，支持**语义化 JSON 配置**，便于 AI Agent 直接控制图表渲染。特性包括横向滚动、多种技术指标（MA/BOLL/MACD/RSI 等）、自定义标记标注、多数据源支持（BaoStock、东方财富）。
 
-<img src="https://s2.loli.net/2026/02/01/7j9uHWIvrAGxFBC.png" alt="示例图片" style="border-radius: 8px;">
+![pasted-image-1775748542822.webp](https://files.seeusercontent.com/2026/04/09/u0nK/pasted-image-1775748542822.webp)
 
 
 ## 功能特性
 
 - **基于 Canvas**：使用 Canvas 实现高性能的 K 线图绘制
 - **响应式设计**：适配不同屏幕尺寸，支持所有设备像素比（DPR），不同 DPR 下绘制清晰
+- **影线处理**：统一 DPR 坐标计算，底层保证影线在不同 DPR 屏幕下绝对居中并绘制清晰
+- **像素对齐**：统一坐标源，在物理坐标层面实现像素对齐，消除亚像素渲染，确保线条锐利清晰
 - **框架无关**：核心逻辑完全独立，不依赖特定框架
+- **插件化架构**：渲染器插件支持动态注册、配置和生命周期管理
+- **量价关系标注**：自动识别并标注量价齐升、量价背离、量增价跌、量缩价跌四种形态
+
+### Agent 语义化控制
+
+- **JSON 配置驱动**：通过 `semanticConfig` prop 接收 JSON 配置，AI Agent 可直接控制图表渲染
+- **自定义标记**：支持 6 种预设形状（arrow_up、arrow_down、flag、circle、rectangle、diamond），标记大小随 K 线缩放自适应
+- **完整指标支持**：主图 MA/BOLL，副图 MACD/RSI/CCI/STOCH 等
+- **安全校验**：JSON Schema 校验、原型污染防护、颜色 XSS 防护、输入边界检查
+- **日期友好格式**：使用 `YYYY-MM-DD` 自然日期格式，便于 Agent 输出
 
 ## 技术栈
 
@@ -21,146 +33,66 @@
 - [Canvas API](https://developer.mozilla.org/zh-CN/docs/Web/API/Canvas_API)
 - [Vitest](https://vitest.dev/) - 单元测试框架
 
-## 数据源
-- [BaoStock](http://baostock.com/) - 开源金融数据接口，每日支持十万次 API 调用
-- [AKTools](https://github.com/akfamily/aktools) - 开源金融数据接口库（可能存在反爬限制）
-
-## 使用 NPM 安装组件库
-```bash
-npm i @363045841yyt/klinechart
-```
-
-
 ## 项目结构
 
 ```
 src/
-├── api/                 # API 接口定义
-│   └── data/
-│       ├── kLine.ts     # 东财/AKTools K 线数据接口
-│       └── baostock.ts  # BaoStock K 线数据接口（推荐）
-├── components/          # 组件
-│   └── KLineChart.vue   # K 线图主组件
-├── core/                # 核心渲染引擎
-│   ├── chart.ts         # 图表控制器
-│   ├── draw/            # 像素对齐工具
-│   │   └── pixelAlign.ts
-│   ├── renderers/       # 渲染器
-│   │   ├── candle.ts    # K 线渲染器
-│   │   └── ...
-│   ├── scale/           # 缩放控制
-│   └── viewport/        # 视口管理
-├── types/               # 类型定义
-│   ├── kLine.ts         # K 线类型定义
-│   └── price.ts         # 价格类型定义
-├── utils/               # 工具函数
-│   ├── kLineDraw/       # K 线绘制工具
-│   ├── kline/           # K 线数据处理
-│   └── mock/            # 模拟数据生成
-├── stores/              # 状态管理 (Pinia)
-└── assets/              # 静态资源
+├── api/                     # API 接口定义
+│   └── data/                # 数据源接口
+├── components/              # Vue 组件
+│   ├── KLineChart.vue       # K 线图主组件
+│   ├── IndicatorSelector.vue # 指标选择器
+│   └── IndicatorParams.vue  # 指标参数编辑
+├── core/                    # 核心渲染引擎
+│   ├── chart.ts             # 图表控制器
+│   ├── renderers/           # 渲染器插件
+│   │   ├── candle.ts        # K 线渲染器
+│   │   ├── ma.ts            # MA 均线渲染器
+│   │   ├── boll.ts          # BOLL 布林带渲染器
+│   │   ├── macd.ts          # MACD 指标渲染器
+│   │   ├── volume.ts        # 成交量渲染器
+│   │   └── ...              # 其他渲染器
+│   ├── theme/               # 主题配置
+│   ├── marker/              # 标记点系统
+│   └── utils/               # 核心工具
+├── semantic/                # 语义化配置模块（Agent 控制）
+│   ├── types.ts             # 类型定义
+│   ├── schema.json          # JSON Schema
+│   ├── validator.ts         # 校验器
+│   ├── controller.ts        # 控制器
+│   └── drawShape.ts         # 形状绘制
+├── plugin/                  # 插件系统
+│   ├── types.ts             # 类型定义
+│   ├── PluginHost.ts        # 插件宿主
+│   ├── EventBus.ts          # 事件总线
+│   ├── HookSystem.ts        # 钩子系统
+│   └── rendererPluginManager.ts  # 渲染器管理
+├── types/                   # 类型定义
+└── utils/                   # 工具函数
 ```
 
-### BaoStock（推荐）
-
-BaoStock 是免费开源的 Python 证券数据接口，提供稳定可靠的金融数据服务。  
-
-- 官方文档：[http://www.baostock.com/mainContent?file=stockKData.md](http://www.baostock.com/mainContent?file=stockKData.md)
+## 数据源
 
-#### 快速开始
+- [BaoStock](http://baostock.com/) - 开源金融数据接口，每日支持十万次 API 调用
+- [AKTools](https://github.com/akfamily/aktools) - 开源金融数据接口库（可能存在反爬限制）
 
-```bash
-# 安装
-uv pip install baostock
-```
+## 使用 NPM 安装组件库
 
-由于 BaoStock 未提供 AkTools 的后端接口，需要自行搭建 FastAPI 服务：
 ```bash
-git clone https://github.com/363045841/stockbao.git
-
-# 启动服务
-python server.py
+npm i @363045841yyt/klinechart
 ```
 
-### AKShare
-
-AKShare 基于 Python 的开源财经数据接口库，数据来源于东方财富等公开渠道。
-
-- GitHub：[https://github.com/akfamily/akshare](https://github.com/akfamily/akshare)
-
-> **⚠️ 注意：** 该库采取直连API，容易触发反爬机制，频繁请求可能导致 IP 被封禁
-
-#### 快速开始
+## 快速开始
 
 ```bash
-# 安装
-uv pip install aktools
-
-# 启动服务
-uv run python -m aktools
-
-# 或通过本项目脚本启动
-pnpm aktools
-```
-
-### 后端数据源配置
-
-#### Vite 代理配置
-
-本项目已配置双数据源代理：
-
-```ts
-// vite.config.ts
-proxy: {
-  '/api/stock': {          // BaoStock (端口 8000)
-    target: 'http://127.0.0.1:8000',
-    changeOrigin: true,
-  },
-  '/api/public': {         // AKTools (端口 8080)
-    target: 'http://127.0.0.1:8080',
-    changeOrigin: true,
-  },
-}
-```
-
-#### 统一接口使用
-
-```vue
-<script setup lang="ts">
-import { fetchKLineData, type KLineDataSourceConfig } from '@/api/data'
-
-const DATA_SOURCE: 'baostock' | 'dongcai' = 'baostock'
-
-// AKshare要求日期为YYYYMMDD格式, BaoStock要求日期为YYYY-MM-DD格式
-const config: KLineDataSourceConfig = {
-  symbol: '601360',       
-  startDate: '2024-01-01',
-  endDate: '2024-12-31',
-  period: 'daily',
-  adjust: 'qfq',
-}
-
-const data = await fetchKLineData(DATA_SOURCE, config)
-</script>
-```
-
-## 使用方法
-
-### 1. 安装依赖
-
-```sh
+# 安装依赖
 pnpm install
-```
-
-### 2. 启动开发服务器
 
-```sh
+# 启动开发服务器
 pnpm dev
 ```
 
-### 3. 在组件中使用 K 线图
-
-#### 方式一：使用 BaoStock 数据源（推荐）
+## 使用示例
 
 ```vue
 <template>
@@ -177,100 +109,117 @@ pnpm dev
 <script setup lang="ts">
 import { ref, onMounted } from 'vue'
 import KLineChart from '@/components/KLineChart.vue'
-import { getKlineDataBaoStock } from '@/api/data/baostock'
 import type { KLineData } from '@/types/price'
-import { cache } from '@/utils/cache'
 
 const klineData = ref<KLineData[]>([])
 
 onMounted(async () => {
-  const params = {
-    symbol: 'sh.601360',      // 三六零股票代码（带市场前缀）
-    start_date: '2024-01-01', // YYYY-MM-DD 格式
-    end_date: '2024-12-31',
-    period: 'daily' as const,
-    adjust: 'qfq' as const,   // 前复权
-  }
-
-  // 缓存键
-  const cacheKey = `kline:${params.symbol}:${params.start_date}:${params.end_date}`
-
-  // 先尝试从缓存获取（1小时有效期）
-  const cached = cache.get<KLineData[]>(cacheKey)
-  if (cached) {
-    klineData.value = cached
-    return
-  }
-
-  // 从 API 获取
-  const data = await getKlineDataBaoStock(params)
+  // 从数据源获取 K 线数据
+  const data = await fetchKLineData('baostock', {
+    symbol: 'sh.601360',
+    startDate: '2024-01-01',
+    endDate: '2024-12-31',
+    period: 'daily',
+    adjust: 'qfq',
+  })
   klineData.value = data
-
-  // 存入缓存
-  cache.set(cacheKey, data)
 })
 </script>
 ```
 
-#### 方式二：使用 AKTools 数据源
+### 语义化 JSON 控制（Agent 模式）
+
+通过 `semanticConfig` prop，AI Agent 可以用 JSON 配置完整控制图表渲染：
 
 ```vue
-<script setup lang="ts">
-import { getKlineDataDongCai } from '@/api/data/kLine'
-import { toKLineData } from '@/types/price'
+<template>
+  <KLineChart :semanticConfig="config" />
+</template>
 
-onMounted(async () => {
-  const raw = await getKlineDataDongCai({
-    symbol: '601360',
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { SemanticChartConfig } from '@363045841yyt/klinechart'
+
+const config = ref<SemanticChartConfig>({
+  version: '1.0.0',
+  data: {
+    source: 'baostock',
+    symbol: '600519',
+    exchange: 'SH',
+    startDate: '2025-01-01',
+    endDate: '2025-04-18',
     period: 'daily',
-    start_date: '20250501',   // YYYYMMDD 格式
-    end_date: '20251230',
     adjust: 'qfq',
-  })
-  klineData.value = toKLineData(raw)
+  },
+  indicators: {
+    main: [{ type: 'MA', enabled: true, params: { periods: [5, 10, 20] } }],
+    sub: [{ type: 'MACD', enabled: true }],
+  },
+  markers: {
+    customMarkers: [
+      {
+        id: 'buy_001',
+        date: '2025-02-15',
+        shape: 'arrow_up',
+        label: { text: '买入' },
+        style: { fillColor: '#52c41a' },
+      },
+    ],
+  },
 })
 </script>
 ```
 
-### 组件属性
+详细配置说明请参阅 [语义化配置文档](./docs/semantic-config.md)。
 
-| 属性              | 类型        | 默认值                                | 说明                           |
-| ----------------- | ----------- | ------------------------------------- | ------------------------------ |
-| data              | KLineData[] | []                                    | K 线数据数组                   |
-| kWidth            | number      | 10                                    | K 线实体宽度                   |
-| kGap              | number      | 2                                     | K 线间距                       |
-| yPaddingPx        | number      | 60                                    | Y 轴上下留白像素               |
-| showMA            | MAFlags     | { ma5: true, ma10: true, ma20: true } | 是否显示移动平均线             |
-| autoScrollToRight | boolean     | true                                  | 数据更新后是否自动滚动到最右侧 |
+## 数据源配置
 
-## 环境要求
+### BaoStock（推荐）
 
-- Node.js: ^20.19.0 || >=22.12.0
-- pnpm: 包管理器
-- Python: 用于运行 AKTools 服务（可选）
-- uv: Python 包管理器
+免费开源的 Python 证券数据接口，每日支持十万次 API 调用。
 
-## 构建与部署
+```bash
+uv pip install baostock
+git clone https://github.com/363045841/stockbao.git
+python server.py  # 启动服务
+```
+
+### AKTools
 
-### 生产环境构建
+基于 Python 的开源财经数据接口，数据来源于东方财富等公开渠道。
 
-```sh
-pnpm build
+```bash
+uv pip install aktools
+uv run python -m aktools  # 启动服务
 ```
 
-### 预览生产包
+> ⚠️ 注意：AKTools 采取直连 API，频繁请求可能触发反爬机制
 
-```sh
-pnpm preview
-```
+### 组件属性
 
-## 贡献
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| data | KLineData[] | [] | K 线数据数组 |
+| semanticConfig | SemanticChartConfig | - | 语义化配置（Agent 模式，唯一数据源） |
+| kWidth | number | 10 | K 线实体宽度 |
+| kGap | number | 2 | K 线间距 |
+| yPaddingPx | number | 60 | Y 轴上下留白像素 |
+| showMA | MAFlags | { ma5: true, ma10: true, ma20: true } | 移动平均线配置 |
+| autoScrollToRight | boolean | true | 数据更新后自动滚动到最右侧 |
 
-欢迎提交 Issue 和 Pull Request 来改进这个项目。
+## 环境要求
 
-## 许可证
+- Node.js: ^20.19.0 || >=22.12.0
+- pnpm: 包管理器
+- Python: 用于运行数据源服务（可选）
+- uv: Python 包管理器
 
-本项目采用 MIT 许可证，详情请见 [LICENSE](./LICENSE) 文件。
+## 构建与部署
+
+```bash
+pnpm build    # 生产环境构建
+pnpm preview  # 预览生产包
+```
 
 ## 相关链接
 
@@ -278,6 +227,10 @@ pnpm preview
 - [Vite 官方文档](https://vite.dev/guide/)
 - [BaoStock 官方文档](http://baostock.com/)
 - [AKTools 官方文档](https://github.com/akfamily/aktools)
-- [AKShare 官方文档](https://akshare.akfamily.xyz/)
 - [Canvas API MDN 文档](https://developer.mozilla.org/zh-CN/docs/Web/API/Canvas_API)
-- [Vitest 官方文档](https://vitest.dev/)
+- [Vitest 官方文档](https://vitest.dev/)
+- [语义化配置文档](./docs/semantic-config.md) - Agent JSON 配置说明
+
+## 许可证
+
+本项目采用 MIT 许可证，详情请见 [LICENSE](./LICENSE) 文件。

package/dist/components/IndicatorParams.vue.d.ts

@@ -0,0 +1,28 @@
+export interface ParamConfig {
+    key: string;
+    label: string;
+    type: 'number';
+    min?: number;
+    max?: number;
+    step?: number;
+    default?: number;
+    /** 参数描述 */
+    description?: string;
+}
+type __VLS_Props = {
+    visible: boolean;
+    indicatorId: string;
+    indicatorName: string;
+    /** 指标描述 */
+    indicatorDescription?: string;
+    params: ParamConfig[];
+    values: Record<string, number>;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    close: () => any;
+    confirm: (values: Record<string, number>) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onClose?: (() => any) | undefined;
+    onConfirm?: ((values: Record<string, number>) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/components/IndicatorSelector.vue.d.ts

@@ -1,17 +1,27 @@
+import { ParamConfig } from './IndicatorParams.vue';
 export interface Indicator {
     id: string;
     label: string;
     name: string;
+    pane: 'main' | 'sub';
+    /** 指标描述 */
+    description?: string;
+    params?: ParamConfig[];
 }
 type __VLS_Props = {
     /** 当前选中的指标列表 */
     activeIndicators?: string[];
+    /** 指标参数配置 */
+    indicatorParams?: Record<string, Record<string, number>>;
 };
 declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
     toggle: (indicatorId: string, active: boolean) => any;
+    updateParams: (indicatorId: string, params: Record<string, number>) => any;
 }, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
     onToggle?: ((indicatorId: string, active: boolean) => any) | undefined;
+    onUpdateParams?: ((indicatorId: string, params: Record<string, number>) => any) | undefined;
 }>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
     scrollContainerRef: HTMLDivElement;
+    itemRefs: HTMLDivElement[];
 }, HTMLDivElement>;
 export default _default;

package/dist/components/KLineChart.vue.d.ts

@@ -1,18 +1,11 @@
-import { KLineData } from '../types/price';
-type MAFlags = {
-    ma5?: boolean;
-    ma10?: boolean;
-    ma20?: boolean;
-    ma30?: boolean;
-    ma60?: boolean;
-};
+import { SemanticChartConfig } from '../semantic';
+import { SubIndicatorType } from '../core/renderers/Indicator';
 type __VLS_Props = {
-    data: KLineData[];
+    /** 语义化配置（必需，唯一控制源） */
+    semanticConfig: SemanticChartConfig;
     kWidth?: number;
     kGap?: number;
     yPaddingPx?: number;
-    showMA?: MAFlags;
-    autoScrollToRight?: boolean;
     minKWidth?: number;
     maxKWidth?: number;
     /** 右侧价格轴宽度 */
@@ -21,26 +14,30 @@ type __VLS_Props = {
     bottomAxisHeight?: number;
     /** 价格标签额外宽度（用于显示涨跌幅，默认 60px） */
     priceLabelWidth?: number;
-    /** Pane 高度比例（主/副），默认 [0.85, 0.15] */
-    paneRatios?: [number, number];
 };
 declare function scheduleRender(): void;
+declare function addSubPane(indicatorId?: SubIndicatorType, params?: Record<string, number>): boolean;
+declare function removeSubPane(paneId: string): void;
+declare function clearAllSubPanes(): void;
+declare function switchSubIndicator(paneId: string, newIndicatorId: SubIndicatorType): void;
 declare function scrollToRight(): void;
 declare const _default: import('vue').DefineComponent<__VLS_Props, {
     scheduleRender: typeof scheduleRender;
     scrollToRight: typeof scrollToRight;
+    addSubPane: typeof addSubPane;
+    removeSubPane: typeof removeSubPane;
+    switchSubIndicator: typeof switchSubIndicator;
+    clearAllSubPanes: typeof clearAllSubPanes;
+    plugin: import('..').PluginHostImpl | undefined;
 }, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
-    yPaddingPx: number;
     kWidth: number;
     kGap: number;
-    showMA: MAFlags;
+    yPaddingPx: number;
     rightAxisWidth: number;
     bottomAxisHeight: number;
     minKWidth: number;
     maxKWidth: number;
     priceLabelWidth: number;
-    autoScrollToRight: boolean;
-    paneRatios: [number, number];
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
     containerRef: HTMLDivElement;
     canvasLayerRef: HTMLDivElement;

package/dist/components/MarkerTooltip.vue.d.ts

@@ -0,0 +1,10 @@
+import { MarkerEntity, CustomMarkerEntity } from '../core/marker/registry';
+type __VLS_Props = {
+    marker: MarkerEntity | CustomMarkerEntity | null;
+    pos: {
+        x: number;
+        y: number;
+    };
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;