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"
    }
  }
}

字段说明： | 字段 | 必需 | 说明 | |------|------|------| | enabled | 是 | 是否启用插件 | | rate_limit | 是 | API 调用频率限制（次/分钟） | | timeout | 是 | 请求超时时间（秒） | | retry_attempts | 是 | 重试次数 | | description | 是 | 插件描述 | | schedule | 否 | 调度配置 | | schedule.frequency | 否 | 调度频率：daily 或 weekly，默认 daily | | schedule.time | 否 | 执行时间，格式 HH:MM，默认 18:00 | | schedule.day_of_week | 否 | 仅 weekly 时有效，如 monday | | parameters | 否 | 插件特定参数 | | parameters_schema | 是 | 参数 schema，用于验证和前端展示 |

注意：依赖配置（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>
  

14) 测试 Agent 集成

• 向 Orchestrator 发送自然语言查询，应调用新插件的 service。
• 示例提问："查询 XXX 指数最近一周的行情数据"
• 验证：
  • Agent 正确识别意图并选择工具。
  • 工具调用从 ClickHouse 返回数据。
  • 响应格式化后返回给用户。

15) 验证集成点

• Service 自动发现，无需额外手动注册。
• MCP/HTTP 端点按生成的路由工作。

验证脚本说明

本 skill 提供以下验证脚本（位于 scripts/ 目录）：

| 脚本 | 用途 | |------|------| | validate_plugin.py | 综合验证插件是否符合规范 | | verify_clickhouse_connection.py | 测试数据库连接、列出表、验证数据 | | generate_create_table_sql.py | 根据 schema.json 生成建表 SQL | | run_plugin_test.py | 运行插件 ETL 并验证入库 | | verify_service_http.py | 测试 HTTP 服务端点 | | verify_mcp_tool.py | 验证 MCP 工具注册状态 |

---

插件验证流程

当用户要求验证已有插件（无论是自己编写还是生成的），执行以下步骤：

1) 运行综合验证脚本

# 验证单个插件
python .codebuddy/skills/tushare-plugin-builder/scripts/validate_plugin.py <plugin_name>

# 显示所有检查详情
python .codebuddy/skills/tushare-plugin-builder/scripts/validate_plugin.py <plugin_name> --verbose

# 列出所有可用插件
python .codebuddy/skills/tushare-plugin-builder/scripts/validate_plugin.py --list

# 验证所有插件
python .codebuddy/skills/tushare-plugin-builder/scripts/validate_plugin.py --all

2) 验证检查项

validate_plugin.py 会自动检查以下内容：

文件结构检查：

• [ ] __init__.py 存在且导出 Plugin/Service 类
• [ ] plugin.py 存在且继承 BasePlugin
• [ ] extractor.py 存在且使用 proxy_context
• [ ] service.py 存在且继承 BaseService
• [ ] schema.json 存在且包含必需字段
• [ ] config.json 存在且包含必需配置

代码规范检查：

• [ ] plugin.py 实现了 extract/validate/transform/load 方法
• [ ] plugin.py 添加了 version 和 _ingested_at 系统列
• [ ] plugin.py 实现了 get_category() 返回正确的 PluginCategory
• [ ] plugin.py 实现了 get_role() 返回正确的 PluginRole
• [ ] plugin.py 实现了 get_dependencies()（返回空列表或依赖插件名）
• [ ] plugin.py 实现了 get_optional_dependencies()（如有可选依赖）
• [ ] extractor.py 使用了重试逻辑（tenacity）
• [ ] service.py 使用参数化 SQL（无 SQL 注入风险）
• [ ] service.py 包含查询方法（get_/query_/fetch_*）

Schema 规范检查：

• [ ] 包含 table_name、columns、engine、order_by
• [ ] 使用 ReplacingMergeTree 引擎
• [ ] 包含 version 和 _ingested_at 系统列
• [ ] 设置了分区策略（partition_by）

运行时检查：

• [ ] 模块可正常导入
• [ ] 数据库表已创建
• [ ] 表中有数据（如已运行过 ETL）

3) 处理验证结果

根据验证结果采取行动：

✅ 通过：插件符合规范，可进行下一步测试。

⚠️ 警告：插件可运行但存在潜在问题，建议修复：

• 缺少重试逻辑 → 添加 tenacity 装饰器
• 未检测到参数化查询 → 检查 SQL 是否使用 %(param)s
• 表为空 → 运行数据拉取测试

❌ 失败：插件存在严重问题，必须修复：

• SQL 注入风险 → 改用参数化查询
• 缺少必需文件 → 补充缺失文件
• 未使用 proxy_context → API 调用将失败
• 缺少系统列 → 在 schema.json 和 plugin.py 中添加

4) 端到端验证

通过基础检查后，执行完整测试流程：

# 1. 验证数据库连接
python .codebuddy/skills/tushare-plugin-builder/scripts/verify_clickhouse_connection.py

# 2. 建表（如果表不存在）
python .codebuddy/skills/tushare-plugin-builder/scripts/generate_create_table_sql.py \
  src/stock_datasource/plugins/<plugin_name>/schema.json --execute

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

# 4. 测试 HTTP 服务
python .codebuddy/skills/tushare-plugin-builder/scripts/verify_service_http.py \
  --service <service_name> --method get_latest --params '{}'

# 5. 测试 MCP 工具
python .codebuddy/skills/tushare-plugin-builder/scripts/verify_mcp_tool.py \
  --pattern <service_name>

---

输出检查清单

• [ ] 插件目录已创建，包含所有必需文件。
• [ ] Extractor 使用 proxy_context() 和 tushare SDK。
• [ ] Plugin 实现了 get_category() 和 get_role() 方法。
• [ ] Plugin 实现了 get_dependencies() 和 get_optional_dependencies() 方法。
• [ ] Service 使用参数化 SQL。
• [ ] Schema 匹配 Tushare 输出字段。
• [ ] Config 包含频率限制、schedule 和参数 schema。
• [ ] ClickHouse 表已创建，数据已入库。
• [ ] 通过 SQL 查询验证 ClickHouse 中有数据。
• [ ] HTTP 服务端点已通过 curl 测试。
• [ ] MCP 工具已注册且可调用。
• [ ] Agent 可通过自然语言查询调用该服务。