tick-stock-panel 数据源插件开发完全教程plugin.yaml、Provider 契约与 stock-sdk 参考实现【免费下载链接】tick-stock-panelTSP自托管、零运维的 A 股「选股 监控 回测」量化工作台 | LLM能力驱使策略定制个股分析复盘 | 自由接入第三方数据源与个性化扩展数据 | 个人开源项目地址: https://gitcode.com/GitHub_Trending/ti/tick-stock-panelTSPtick-stock-panel是一个自托管、零运维的 A 股「选股 监控 回测」量化工作台其数据层采用插件化架构允许自由接入第三方数据源。本教程带你从零掌握tick-stock-panel 数据源插件开发的完整流程读懂plugin.yaml清单、实现 Provider 契约并以项目内置的stock-sdk 插件作为参考实现逐步拆解帮助你为自己的数据源快速落地一个合格插件。 如果你的数据源只是标准 HTTP 接口优先看无代码的 YAML 声明式接入docs/custom-data-source.md。本文面向需要用 Python/Node 写代码的高级场景。一、为什么插件化设计值得学习TSP 默认使用 TickFlow 数据源但 services 层kline_sync / quote_service / financial_sync全部通过统一路由点分流插件声明了某类数据集就走插件未声明的自动回退 TickFlow。这意味着两件事✅对开发者友好一个合格插件只需正确实现契约不需要改动任何 service / API 代码⚠️对数据口径严格框架不会替你转换单位与格式插件必须自己完成适配代码后缀、小数制涨跌幅、手/股单位等。插件注册后与用户 YAML 自定义源走完全相同的路由路径零额外集成代码。二、plugin.yaml 清单插件的身份证一个插件 一个目录 一个plugin.yaml清单backend/app/plugins/your_plugin/ ├── plugin.yaml # 清单必需 ├── provider.py # Provider 实现必需 └── ... # client/桥接/依赖文件按需核心字段速查以 backend/app/plugins/stocksdk/plugin.yaml 为例字段作用说明name唯一标识只允许[a-z0-9_]同时也是 provider namedisplay_name设置页显示名例如stock-sdkruntime运行时类型node/python/none仅用于 UI 展示entryProvider 导入路径如app.plugins.stocksdk.provider:StockSDKProvidercheck可用性检测函数可选返回(是否可用, 原因)datasets支持的数据集支持daily/adj_factor/minute/realtime/depth5/financial/full_minuteapi_key_envAPI Key 配置声明后设置页提供 Key 输入框先探后存install_hint安装提示依赖未装时展示给用户关键原则只声明真实提供的数据集。例如 stock-sdk 不支持财务数据就不声明financial该数据集会自动回退 TickFlow。不要声明做不了的数据集否则会污染路由。需要用户填 API Key用 api_key_env声明api_key_env后插件可在设置页数据源卡片中直接填写 Key流程为「先探后存」entry 模块提供probe_api_key(key) - (ok, reason)后端实探一次无效不落盘有效则写入data/user_data/secrets.json优先级高于.env保存后自动重载注册表插件即刻变为可切换。参考 backend/app/plugins/fuyao/plugin.yaml 中的api_key_env: FUYAO_API_KEY配置。三、Provider 契约路由层如何调用你的类Provider 是普通 Python 类无需继承基类方法签名对齐GenericHTTPProvider。只实现已声明数据集对应的方法其余可缺省。最小骨架class MyProvider: name my_source builtin True def __init__(self): self.config MyConfig() # 必须提供 .datasets 属性(dict) def get_daily(self, symbols, start_time, end_time, asset_typestock, on_chunk_doneNone): ... # 返回 polars DataFrameconfig.datasets是 services 层路由的开关provider_has_dataset(name, dataset)通过dataset in provider.config.datasets判断是否路由到你的插件。各数据集方法一览方法对应数据集返回get_dailydaily日K[symbol, date, OHLC, volume, amount]不复权get_adj_factorsadj_factor除权因子[symbol, trade_date, ex_factor]get_minuteminute1m 分钟Kdatetime 必须为北京墙钟naiveget_realtimerealtime全市场实时快照list[dict]失败软返回[]get_depth_batchdepth5五档盘口字典键为 symbolget_financialsfinancial财务表 DataFrame内部数据契约全项目红线金融数据错误往往不抛异常而是生成看似合理的错误结果因此这些口径是硬性要求字段契约常见踩坑symbol带交易所后缀600519.SH接口返回裸代码必须归一change_pct小数制0.0366 3.66%接口给百分数要显式/100volume手1手100股接口给股要显式/100amount元—日K OHLC不复权原始价复权由 enriched 管道处理provider 不得自行复权⚠️ 接口不提供的字段一律返回None禁止小于 1 就乘 100之类的启发式补全——那会掩盖真实的数据错误。完整契约含get_minute时区守卫、full_minute全量分钟、异常语义表详见官方文档docs/plugin-development.md。四、参考实现深度拆解stock-sdk 插件backend/app/plugins/stocksdk/ 是项目内置的Node 型插件它演示了三类最有代表性的开发场景跨语言桥接、依赖检测、能力声明。目录结构backend/app/plugins/stocksdk/ ├── plugin.yaml # 清单runtime: node, datasets 四项 ├── provider.py # Provider 实现归一化、分批、错误降级 ├── bridge.py # Python↔Node 桥接 availability 检测 ├── bridge.mjs # Node 端并发池、重试、SDK 解析 └── package.json # Node 依赖1️⃣ 跨语言桥接bridge.py后端是 Pythonstock-sdk 是 Node 包bridge.py 用subprocess把两者接起来每次调用 spawn 一个node bridge.mjs从 stdin 喂 JSON job从 stdout 读 JSON 结果。批内并发由 Node 端承担一次进程调用摊薄 node 启动开销。2️⃣ 可用性检测check 函数后端启动时调用check指向的availability()函数可用→ 插件注册进路由表设置页可切换不可用→ 设置页显示插件卡片但灰显展示install_hint。stock-sdk 的检测逻辑先找 node 可执行文件优先环境变量STOCK_SDK_NODE再确认 stock-sdk 已安装失败返回原因字符串且不抛异常。3️⃣ Provider 实现要点provider.pyprovider.py 展示了契约落地的几个关键细节_DATASETS元组 config shimdatasets声明与plugin.yaml严格一致让 loader 的provider_has_dataset能正确识别分批拉取每批 40 个 symbol 调桥接用on_chunk_done(i, total)反馈进度iter_daily场景下必须覆盖空批次归一化复用调用normalize_daily等公共归一函数把原始行转成项目标准 schema能力声明minute_history_days 5声明分钟历史深度仅 5 个交易日前端分时档位自动收窄为可行选项——这是浅源接入的标准做法错误降级单批桥接失败只记 warning 并继续下一批不中断整体同步。4️⃣ 合规与打包注意stock-sdk 抓取第三方财经网站接口存在版权与反爬风险因此Docker 默认不打包需构建时传--build-arg INCLUDE_STOCKSDK1启用。你的插件如有类似风险同样应在description与install_hint中明确告知用户。五、测试与发布检查清单插件 PR 必须带契约测试不依赖真实网络与 API Key用假 Client/桥接注入。以 backend/tests/test_fuyao_provider.py 为范本73 个用例至少覆盖✅字段映射与单位转换百分数→小数制、股→手、时区换算、缺失置 None✅响应结构变体实测结构 vs 官方文档示例双兼容✅分页多页合并、空页终止、页数上限✅软失败接口报错返回[]schema 变化有告警而非静默空数据✅能力声明未声明数据集provider_has_dataset为 False✅Key 语义先探后存、secrets.json 优先级、availability 两态✅loader 集成清单解析后正确注册。运行方式cd backend uv run --extra dev python -m pytest tests/test_your_plugin_provider.py -q uv run --extra dev python -m ruff check app/plugins/your_plugin/ tests/test_your_plugin_provider.py限频与性能建议实时快照默认 6s 轮询一轮优先确认服务端单次 limit 上限能一次拉全市场就不要分页分页必须有页数上限和空页终止条件拉取由 fetch 锁串行化实际刷新周期 轮询间隔 拉取耗时不要按6s 内必须完成设计。六、常见问题 FAQQ1插件和 YAML 声明式接入怎么选纯 HTTP 接口用 YAML 零代码接入docs/custom-data-source.md需要复杂逻辑跨语言、限速、本地缓存、Key 探测时写 Python 插件。Q2只覆盖 A 股股票指数/ETF 怎么办realtime声明是数据集级的未覆盖的指数行情自动降级为日线推导值非实时ETF 实时计数为 0。要么在数据里尽量覆盖要么在description中向用户说明覆盖范围。Q3分钟K时间写错会怎样入口守卫_enforce_minute_beijing_wallclock会兜底带时区自动换算naive 但呈 UTC 特征如 01:30自动 8 纠偏完全无法识别则拒收并回退 TickFlow。契约仍要求源头写对守卫只是最后防线。Q4路由是怎么工作的后端启动时loader.py扫描plugins/目录读plugin.yaml→hidden: true跳过 → 调check检测 → 动态 importentry指向的 Provider 类 → 注册。之后 services 层的provider_has_dataset/get_provider调用自动路由无需任何额外集成代码。总结tick-stock-panel 数据源插件开发的核心就三步——写好plugin.yaml清单声明能力、按 Provider 契约实现方法严格遵守单位与时区红线、以 fuyao / stock-sdk 为范本补上契约测试。更多细节部署、二次开发可继续参考 docs/plugin-development.md 与 docs/secondary-development.md。【免费下载链接】tick-stock-panelTSP自托管、零运维的 A 股「选股 监控 回测」量化工作台 | LLM能力驱使策略定制个股分析复盘 | 自由接入第三方数据源与个性化扩展数据 | 个人开源项目地址: https://gitcode.com/GitHub_Trending/ti/tick-stock-panel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考