Tushare Plugin Builder

目的

将 Tushare 文档 URL 转换为本仓库的生产级插件，包含数据抽取、ClickHouse 表结构、查询服务，以及可测试的 curl 示例。

何时使用

• 用户提供 Tushare 文档 URL 或页面内容，要求生成插件。
• 用户需要基于某个 Tushare 接口生成插件 + 入库 + service + Agent/MCP 调用。
• 验证已有插件：用户要求检查某个插件是否符合规范。

工作流程

1) 收集必要输入

• 确保用户提供了 Tushare 文档 URL。若无法访问，请求截图或复制的文档内容。
• 若未指定插件名，询问用户。使用 snake_case 命名，与现有 tushare_* 插件保持一致。

2) 从文档提取 API 规格

• 解析接口名称、输入参数、输出字段、使用说明（频率限制、分页、数据量限制）。
• 记录字段命名差异（如 pct_change vs pct_chg）及所需转换。

3) 规划插件结构（参考 references/plugin_conventions.md）

• 目录：src/stock_datasource/plugins/<plugin_name>/
• 文件：__init__.py、plugin.py、extractor.py、service.py、schema.json、config.json、<plugin_name>.md
• 以现有 tushare_* 插件为模板。

4) 实现 extractor

• 使用 tushare SDK，API 调用需用 proxy_context() 包裹。
• 实现频率限制、超时、重试（tenacity）。
• 根据 API 特性支持 trade_date 或 start_date/end_date。

5) 实现 plugin

• 实现 extract_data、validate_data、transform_data、load_data。
• 插入前添加 version 和 _ingested_at 列。
• 转换数值类型，trade_date 转为 Date。

插件分类与角色

必须实现以下方法指定插件的分类和角色：

from stock_datasource.core.base_plugin import PluginCategory, PluginRole

def get_category(self) -> PluginCategory:
    """插件分类 - 按市场划分"""
    return PluginCategory.CN_STOCK  # 或 HK_STOCK, INDEX, ETF_FUND, SYSTEM

def get_role(self) -> PluginRole:
    """插件角色"""
    return PluginRole.PRIMARY  # 或 BASIC, DERIVED, AUXILIARY

分类说明：

• CN_STOCK: A股相关数据
• HK_STOCK: 港股相关数据
• INDEX: 指数相关数据
• ETF_FUND: ETF/基金相关数据
• SYSTEM: 系统数据（如交易日历）

角色说明：

• PRIMARY: 主数据（如 daily 行情）
• BASIC: 基础数据（如 stock_basic）
• DERIVED: 衍生数据（如复权因子）
• AUXILIARY: 辅助数据（如指数权重）

依赖配置

在 plugin.py 中实现依赖方法（不是在 config.json 中配置）：

def get_dependencies(self) -> List[str]:
    """必须依赖 - 这些插件的数据必须存在才能运行当前插件。
    
    例如：tushare_daily 依赖 tushare_stock_basic 提供股票代码列表。
    """
    return ["tushare_stock_basic"]

def get_optional_dependencies(self) -> List[str]:
    """可选依赖 - 同步主插件时默认会同步这些依赖，用户可选择禁用。
    
    例如：tushare_daily 可选同步 tushare_adj_factor 复权因子。
    """
    return ["tushare_adj_factor"]

依赖规则：

• 必须依赖：在运行当前插件前，会检查依赖插件表中是否有数据
• 可选依赖：前端展示时会显示可勾选的关联插件，默认勾选

6) 实现 service 查询

• 至少提供一个日期范围查询和一个最新数据查询。
• 必须使用参数化查询（禁止字符串拼接）。
• 返回 JSON 可序列化结构。

7) 定义 schema/config

• schema.json：使用 ReplacingMergeTree，partition_by 为 toYYYYMM(trade_date)，order_by 为主键。
• config.json：包含完整的插件配置。

config.json 完整结构

{
  "enabled": true,
  "rate_limit": 120,
  "timeout": 30,
  "retry_attempts": 3,
  "description": "插件描述",
  "schedule": {
    "frequency": "daily",
    "time": "18:00",
    "day_of_week": "monday"
  },
  "parameters": {
    "max_empty_days": 5,
    "validate_prices": true
  },
  "parameters_schema": {
    "trade_date": {
      "type": "string",
      "format": "date",
      "required": true,
      "description": "Trade date in YYYYMMDD format"
    }
  }
}

字段说明：

注意：依赖配置（dependencies、optional_dependencies）不在 config.json 中定义，而是通过 plugin.py 中的 get_dependencies() 和 get_optional_dependencies() 方法实现。

8) 创建 ClickHouse 表

• 根据 schema.json 生成 CREATE TABLE SQL。
• 使用脚本：

  # 仅生成 SQL
  python .codebuddy/skills/tushare-plugin-builder/scripts/generate_create_table_sql.py \
    src/stock_datasource/plugins/<plugin_name>/schema.json
  
  # 生成并执行
  python .codebuddy/skills/tushare-plugin-builder/scripts/generate_create_table_sql.py \
    src/stock_datasource/plugins/<plugin_name>/schema.json --execute

9) 验证数据库连接

• 执行前先验证 ClickHouse 连接是否正常：

  # 测试连接
  python .codebuddy/skills/tushare-plugin-builder/scripts/verify_clickhouse_connection.py
  
  # 列出所有表
  python .codebuddy/skills/tushare-plugin-builder/scripts/verify_clickhouse_connection.py --list
  
  # 验证指定表是否存在
  python .codebuddy/skills/tushare-plugin-builder/scripts/verify_clickhouse_connection.py --table <table_name>

10) 运行数据拉取测试

• 执行插件拉取并存储样本数据（如某一交易日）。
• 代理配置：运行前确保 runtime_config.json 中代理设置正确。
• 使用脚本：

  # 运行插件并验证
  python .codebuddy/skills/tushare-plugin-builder/scripts/run_plugin_test.py \
    <plugin_name> --date 20250110 --verify

• 或使用模块方式：

  python -m stock_datasource.plugins.<plugin_name>.plugin --date 20250110

11) 验证 ClickHouse 数据

• 查询 ClickHouse 确认数据已存储：

  # 使用脚本验证
  python .codebuddy/skills/tushare-plugin-builder/scripts/verify_clickhouse_connection.py \
    --table <table_name> --date 20250110

• 或手动查询：

  SELECT count(*), min(trade_date), max(trade_date)
  FROM <table_name>
  WHERE trade_date = '2025-01-10';

12) 测试 HTTP 服务端点

• 若未运行，启动 HTTP 服务：python -m stock_datasource.services.http_server
• 使用脚本：

  # 列出所有 API 路由
  python .codebuddy/skills/tushare-plugin-builder/scripts/verify_service_http.py --list
  
  # 测试指定服务方法
  python .codebuddy/skills/tushare-plugin-builder/scripts/verify_service_http.py \
    --service <service_name> \
    --method get_by_date_range \
    --params '{"ts_code":"XXX","start_date":"20250101","end_date":"20250110"}'
  
  # 仅生成 curl 命令
  python .codebuddy/skills/tushare-plugin-builder/scripts/verify_service_http.py \
    --service <service_name> --method get_latest --params '{}' --curl

13) 测试 MCP 工具可用性

• 若未运行，启动 MCP 服务：python -m stock_datasource.services.mcp_server
• 使用脚本：

  # 列出所有 MCP 工具
  python .codebuddy/skills/tushare-plugin-builder/scripts/verify_mcp_tool.py --list
  
  # 搜索相关工具
  python .codebuddy/skills/tushare-plugin-builder/scripts/verify_mcp_tool.py --pattern <service_name>
  
  # 验证指定工具
  python .codebuddy/skills/tushare-plugin-builder/scripts/verify_mcp_tool.py --tool <tool_name>