tushare-plugin-builder

Name: tushare-plugin-builder
Author: Yourdaylight

168stars50forks

How to install tushare-plugin-builder?

yourdaylight/stock_datasource/tushare-plugin-builder

$npx -y skills add Yourdaylight/stock_datasource --skill tushare-plugin-builder

Installs into the current project.

Summary

This skill should be used when the user provides a Tushare API document URL and asks to generate a full plugin in this codebase, including extractor, schema, config, query service, and agent/MCP/http usage with testable curl examples.

Files · 1

View on GitHub

SKILL.md

1	## 目的
2	将 Tushare 文档 URL 转换为本仓库的生产级插件，包含数据抽取、ClickHouse 表结构、查询服务，以及可测试的 `curl` 示例。
3
4	## 何时使用
5	- 用户提供 Tushare 文档 URL 或页面内容，要求生成插件。
6	- 用户需要基于某个 Tushare 接口生成插件 + 入库 + service + Agent/MCP 调用。
7	- 验证已有插件：用户要求检查某个插件是否符合规范。
8
9	## 工作流程
10
11	### 1) 收集必要输入
12	- 确保用户提供了 Tushare 文档 URL。若无法访问，请求截图或复制的文档内容。
13	- 若未指定插件名，询问用户。使用 snake_case 命名，与现有 `tushare_*` 插件保持一致。
14
15	### 2) 从文档提取 API 规格
16	- 解析接口名称、输入参数、输出字段、使用说明（频率限制、分页、数据量限制）。
17	- 记录字段命名差异（如 `pct_change` vs `pct_chg`）及所需转换。
18
19	### 3) 规划插件结构（参考 `references/plugin_conventions.md`）
20	- 目录：`src/stock_datasource/plugins/<plugin_name>/`
21	- 文件：`__init__.py`、`plugin.py`、`extractor.py`、`service.py`、`schema.json`、`config.json`、`<plugin_name>.md`
22	- 以现有 `tushare_*` 插件为模板。
23
24	### 4) 实现 extractor
25	- 使用 `tushare` SDK，API 调用需用 `proxy_context()` 包裹。
26	- 实现频率限制、超时、重试（tenacity）。
27	- 根据 API 特性支持 `trade_date` 或 `start_date`/`end_date`。
28
29	### 5) 实现 plugin
30	- 实现 `extract_data`、`validate_data`、`transform_data`、`load_data`。
31	- 插入前添加 `version` 和 `_ingested_at` 列。
32	- 转换数值类型，`trade_date` 转为 `Date`。
33
34	#### 插件分类与角色
35	必须实现以下方法指定插件的分类和角色：
36
37	```python
38	from stock_datasource.core.base_plugin import PluginCategory, PluginRole
39
40	def get_category(self) -> PluginCategory:
41	"""插件分类 - 按市场划分"""
42	return PluginCategory.CN_STOCK # 或 HK_STOCK, INDEX, ETF_FUND, SYSTEM
43
44	def get_role(self) -> PluginRole:
45	"""插件角色"""
46	return PluginRole.PRIMARY # 或 BASIC, DERIVED, AUXILIARY
47	```
48
49	分类说明：
50	- `CN_STOCK`: A股相关数据
51	- `HK_STOCK`: 港股相关数据
52	- `INDEX`: 指数相关数据
53	- `ETF_FUND`: ETF/基金相关数据
54	- `SYSTEM`: 系统数据（如交易日历）
55
56	角色说明：
57	- `PRIMARY`: 主数据（如 daily 行情）
58	- `BASIC`: 基础数据（如 stock_basic）
59	- `DERIVED`: 衍生数据（如复权因子）
60	- `AUXILIARY`: 辅助数据（如指数权重）
61
62	#### 依赖配置
63	在 `plugin.py` 中实现依赖方法（不是在 config.json 中配置）：
64
65	```python
66	def get_dependencies(self) -> List[str]:
67	"""必须依赖 - 这些插件的数据必须存在才能运行当前插件。
68
69	例如：tushare_daily 依赖 tushare_stock_basic 提供股票代码列表。
70	"""
71	return ["tushare_stock_basic"]
72
73	def get_optional_dependencies(self) -> List[str]:
74	"""可选依赖 - 同步主插件时默认会同步这些依赖，用户可选择禁用。
75
76	例如：tushare_daily 可选同步 tushare_adj_factor 复权因子。
77	"""
78	return ["tushare_adj_factor"]
79	```
80
81	依赖规则：
82	- 必须依赖：在运行当前插件前，会检查依赖插件表中是否有数据
83	- 可选依赖：前端展示时会显示可勾选的关联插件，默认勾选
84
85	### 6) 实现 service 查询
86	- 至少提供一个日期范围查询和一个最新数据查询。
87	- 必须使用参数化查询（禁止字符串拼接）。
88	- 返回 JSON 可序列化结构。
89
90	### 7) 定义 schema/config
91	- `schema.json`：使用 `ReplacingMergeTree`，`partition_by` 为 `toYYYYMM(trade_date)`，`order_by` 为主键。
92	- `config.json`：包含完整的插件配置。
93
94	#### config.json 完整结构
95	```json
96	{
97	"enabled": true,
98	"rate_limit": 120,
99	"timeout": 30,
100	"retry_attempts": 3,
101	"description": "插件描述",
102	"schedule": {
103	"frequency": "daily",
104	"time": "18:00",
105	"day_of_week": "monday"
106	},
107	"parameters": {
108	"max_empty_days": 5,
109	"validate_prices": true
110	},
111	"parameters_schema": {
112	"trade_date": {
113	"type": "string",
114	"format": "date",
115	"required": true,
116	"description": "Trade date in YYYYMMDD format"
117	}
118	}
119	}
120	```
121
122	字段说明：
123	\| 字段 \| 必需 \| 说明 \|
124	\|------\|------\|------\|
125	\| `enabled` \| 是 \| 是否启用插件 \|
126	\| `rate_limit` \| 是 \| API 调用频率限制（次/分钟） \|
127	\| `timeout` \| 是 \| 请求超时时间（秒） \|
128	\| `retry_attempts` \| 是 \| 重试次数 \|
129	\| `description` \| 是 \| 插件描述 \|
130	\| `schedule` \| 否 \| 调度配置 \|
131	\| `schedule.frequency` \| 否 \| 调度频率：`daily` 或 `weekly`，默认 `daily` \|
132	\| `schedule.time` \| 否 \| 执行时间，格式 `HH:MM`，默认 `18:00` \|
133	\| `schedule.day_of_week` \| 否 \| 仅 `weekly` 时有效，如 `monday` \|
134	\| `parameters` \| 否 \| 插件特定参数 \|
135	\| `parameters_schema` \| 是 \| 参数 schema，用于验证和前端展示 \|
136
137	注意：依赖配置（`dependencies`、`optional_dependencies`）不在 config.json 中定义，而是通过 `plugin.py` 中的 `get_dependencies()` 和 `get_optional_dependencies()` 方法实现。
138
139	### 8) 创建 ClickHouse 表
140	- 根据 `schema.json` 生成 `CREATE TABLE` SQL。
141	- 使用脚本：
142	```bash
143	# 仅生成 SQL
144	python .codebuddy/skills/tushare-plugin-builder/scripts/generate_create_table_sql.py \
145	src/stock_datasource/plugins/<plugin_name>/schema.json
146
147	# 生成并执行
148	python .codebuddy/skills/tushare-plugin-builder/scripts/generate_create_table_sql.py \
149	src/stock_datasource/plugins/<plugin_name>/schema.json --execute
150	```
151
152	### 9) 验证数据库连接
153	- 执行前先验证 ClickHouse 连接是否正常：
154	```bash
155	# 测试连接
156	python .codebuddy/skills/tushare-plugin-builder/scripts/verify_clickhouse_connection.py
157
158	# 列出所有表
159	python .codebuddy/skills/tushare-plugin-builder/scripts/verify_clickhouse_connection.py --list
160
161	# 验证指定表是否存在
162	python .codebuddy/skills/tushare-plugin-builder/scripts/verify_clickhouse_connection.py --table <table_name>
163	```
164
165	### 10) 运行数据拉取测试
166	- 执行插件拉取并存储样本数据（如某一交易日）。
167	- 代理配置：运行前确保 `runtime_config.json` 中代理设置正确。
168	- 使用脚本：
169	```bash
170	# 运行插件并验证
171	python .codebuddy/skills/tushare-plugin-builder/scripts/run_plugin_test.py \
172	<plugin_name> --date 20250110 --verify
173	```
174	- 或使用模块方式：
175	```bash
176	python -m stock_datasource.plugins.<plugin_name>.plugin --date 20250110
177	```
178
179	### 11) 验证 ClickHouse 数据
180	- 查询 ClickHouse 确认数据已存储：

People who liked this also viewed

6 picks

Type

tushare-plugin-builder

168stars50forks

View on GitHub

How to install tushare-plugin-builder?

yourdaylight/stock_datasource/tushare-plugin-builder

$npx -y skills add Yourdaylight/stock_datasource --skill tushare-plugin-builder

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	## 目的
2	将 Tushare 文档 URL 转换为本仓库的生产级插件，包含数据抽取、ClickHouse 表结构、查询服务，以及可测试的 `curl` 示例。
3
4	## 何时使用
5	- 用户提供 Tushare 文档 URL 或页面内容，要求生成插件。
6	- 用户需要基于某个 Tushare 接口生成插件 + 入库 + service + Agent/MCP 调用。
7	- 验证已有插件：用户要求检查某个插件是否符合规范。
8
9	## 工作流程
10
11	### 1) 收集必要输入
12	- 确保用户提供了 Tushare 文档 URL。若无法访问，请求截图或复制的文档内容。
13	- 若未指定插件名，询问用户。使用 snake_case 命名，与现有 `tushare_*` 插件保持一致。
14
15	### 2) 从文档提取 API 规格
16	- 解析接口名称、输入参数、输出字段、使用说明（频率限制、分页、数据量限制）。
17	- 记录字段命名差异（如 `pct_change` vs `pct_chg`）及所需转换。
18
19	### 3) 规划插件结构（参考 `references/plugin_conventions.md`）
20	- 目录：`src/stock_datasource/plugins/<plugin_name>/`
21	- 文件：`__init__.py`、`plugin.py`、`extractor.py`、`service.py`、`schema.json`、`config.json`、`<plugin_name>.md`
22	- 以现有 `tushare_*` 插件为模板。
23
24	### 4) 实现 extractor
25	- 使用 `tushare` SDK，API 调用需用 `proxy_context()` 包裹。
26	- 实现频率限制、超时、重试（tenacity）。
27	- 根据 API 特性支持 `trade_date` 或 `start_date`/`end_date`。
28
29	### 5) 实现 plugin
30	- 实现 `extract_data`、`validate_data`、`transform_data`、`load_data`。
31	- 插入前添加 `version` 和 `_ingested_at` 列。
32	- 转换数值类型，`trade_date` 转为 `Date`。
33
34	#### 插件分类与角色
35	必须实现以下方法指定插件的分类和角色：
36
37	```python
38	from stock_datasource.core.base_plugin import PluginCategory, PluginRole
39
40	def get_category(self) -> PluginCategory:
41	"""插件分类 - 按市场划分"""
42	return PluginCategory.CN_STOCK # 或 HK_STOCK, INDEX, ETF_FUND, SYSTEM
43
44	def get_role(self) -> PluginRole:
45	"""插件角色"""
46	return PluginRole.PRIMARY # 或 BASIC, DERIVED, AUXILIARY
47	```
48
49	分类说明：
50	- `CN_STOCK`: A股相关数据
51	- `HK_STOCK`: 港股相关数据
52	- `INDEX`: 指数相关数据
53	- `ETF_FUND`: ETF/基金相关数据
54	- `SYSTEM`: 系统数据（如交易日历）
55
56	角色说明：
57	- `PRIMARY`: 主数据（如 daily 行情）
58	- `BASIC`: 基础数据（如 stock_basic）
59	- `DERIVED`: 衍生数据（如复权因子）
60	- `AUXILIARY`: 辅助数据（如指数权重）
61
62	#### 依赖配置
63	在 `plugin.py` 中实现依赖方法（不是在 config.json 中配置）：
64
65	```python
66	def get_dependencies(self) -> List[str]:
67	"""必须依赖 - 这些插件的数据必须存在才能运行当前插件。
68
69	例如：tushare_daily 依赖 tushare_stock_basic 提供股票代码列表。
70	"""
71	return ["tushare_stock_basic"]
72
73	def get_optional_dependencies(self) -> List[str]:
74	"""可选依赖 - 同步主插件时默认会同步这些依赖，用户可选择禁用。
75
76	例如：tushare_daily 可选同步 tushare_adj_factor 复权因子。
77	"""
78	return ["tushare_adj_factor"]
79	```
80
81	依赖规则：
82	- 必须依赖：在运行当前插件前，会检查依赖插件表中是否有数据
83	- 可选依赖：前端展示时会显示可勾选的关联插件，默认勾选
84
85	### 6) 实现 service 查询
86	- 至少提供一个日期范围查询和一个最新数据查询。
87	- 必须使用参数化查询（禁止字符串拼接）。
88	- 返回 JSON 可序列化结构。
89
90	### 7) 定义 schema/config
91	- `schema.json`：使用 `ReplacingMergeTree`，`partition_by` 为 `toYYYYMM(trade_date)`，`order_by` 为主键。
92	- `config.json`：包含完整的插件配置。
93
94	#### config.json 完整结构
95	```json
96	{
97	"enabled": true,
98	"rate_limit": 120,
99	"timeout": 30,
100	"retry_attempts": 3,
101	"description": "插件描述",
102	"schedule": {
103	"frequency": "daily",
104	"time": "18:00",
105	"day_of_week": "monday"
106	},
107	"parameters": {
108	"max_empty_days": 5,
109	"validate_prices": true
110	},
111	"parameters_schema": {
112	"trade_date": {
113	"type": "string",
114	"format": "date",
115	"required": true,
116	"description": "Trade date in YYYYMMDD format"
117	}
118	}
119	}
120	```
121
122	字段说明：
123	\| 字段 \| 必需 \| 说明 \|
124	\|------\|------\|------\|
125	\| `enabled` \| 是 \| 是否启用插件 \|
126	\| `rate_limit` \| 是 \| API 调用频率限制（次/分钟） \|
127	\| `timeout` \| 是 \| 请求超时时间（秒） \|
128	\| `retry_attempts` \| 是 \| 重试次数 \|
129	\| `description` \| 是 \| 插件描述 \|
130	\| `schedule` \| 否 \| 调度配置 \|
131	\| `schedule.frequency` \| 否 \| 调度频率：`daily` 或 `weekly`，默认 `daily` \|
132	\| `schedule.time` \| 否 \| 执行时间，格式 `HH:MM`，默认 `18:00` \|
133	\| `schedule.day_of_week` \| 否 \| 仅 `weekly` 时有效，如 `monday` \|
134	\| `parameters` \| 否 \| 插件特定参数 \|
135	\| `parameters_schema` \| 是 \| 参数 schema，用于验证和前端展示 \|
136
137	注意：依赖配置（`dependencies`、`optional_dependencies`）不在 config.json 中定义，而是通过 `plugin.py` 中的 `get_dependencies()` 和 `get_optional_dependencies()` 方法实现。
138
139	### 8) 创建 ClickHouse 表
140	- 根据 `schema.json` 生成 `CREATE TABLE` SQL。
141	- 使用脚本：
142	```bash
143	# 仅生成 SQL
144	python .codebuddy/skills/tushare-plugin-builder/scripts/generate_create_table_sql.py \
145	src/stock_datasource/plugins/<plugin_name>/schema.json
146
147	# 生成并执行
148	python .codebuddy/skills/tushare-plugin-builder/scripts/generate_create_table_sql.py \
149	src/stock_datasource/plugins/<plugin_name>/schema.json --execute
150	```
151
152	### 9) 验证数据库连接
153	- 执行前先验证 ClickHouse 连接是否正常：
154	```bash
155	# 测试连接
156	python .codebuddy/skills/tushare-plugin-builder/scripts/verify_clickhouse_connection.py
157
158	# 列出所有表
159	python .codebuddy/skills/tushare-plugin-builder/scripts/verify_clickhouse_connection.py --list
160
161	# 验证指定表是否存在
162	python .codebuddy/skills/tushare-plugin-builder/scripts/verify_clickhouse_connection.py --table <table_name>
163	```
164
165	### 10) 运行数据拉取测试
166	- 执行插件拉取并存储样本数据（如某一交易日）。
167	- 代理配置：运行前确保 `runtime_config.json` 中代理设置正确。
168	- 使用脚本：
169	```bash
170	# 运行插件并验证
171	python .codebuddy/skills/tushare-plugin-builder/scripts/run_plugin_test.py \
172	<plugin_name> --date 20250110 --verify
173	```
174	- 或使用模块方式：
175	```bash
176	python -m stock_datasource.plugins.<plugin_name>.plugin --date 20250110
177	```
178
179	### 11) 验证 ClickHouse 数据
180	- 查询 ClickHouse 确认数据已存储：

People who liked this also viewed

6 picks

Type