Skills
▥NYC
skills/smithery/ai/tushare-plugin-builder

tushare-plugin-builder

SKILL.md

目的

将 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 可通过自然语言查询调用该服务。
Weekly Installs
1
Repository
smithery/ai
First Seen
13 days ago
Security Audits
Gen Agent Trust HubPass
SnykWarn
Installed on
codex1