AI 标签建议需要模型 Key
ai_suggestion.py 背后是模型调用，而 config.json 里的 moonshot_api_key 与 qwen_api_key 默认都是空的。没配 Key 时这部分能力不可用，不影响纯规则标签。
ZVT 项目研究站 · 标签与定时任务
ZVT 的自动化层：股票池 + 标签 + 六个 runner，把研究变成日常流程
除了取数、因子和策略，ZVT 还有一层容易被忽略的自动化能力：用股票池组织关注对象，用标签给标的打标记，用 runner 定时把数据与信号更新一遍。README 只给了四个脚本链接，本页把 src/zvt/tasks/ 与 src/zvt/tag/ 的实际内容整理清楚。
ZVT 的 runner、标签服务与接口样例怎么串起来
6 个 runner初始化 / 股票池 / 数据 / 信号
tag 服务标签读写与统计
AI 建议依赖 moonshot / qwen key
REST 样例api-tests/*.http
src/zvt/tasks/、src/zvt/tag/ 与 api-tests/ 的文件清单自绘（非官方架构图）；节点名逐字取自目录文件名。Runners
ZVT 的六个 runner：各自解决什么问题
README 只列了其中四个的链接，实际目录里有六个。下表按文件名与用途整理。
| runner | 作用 | 典型使用场景 | 前置条件 | 注意点 |
|---|---|---|---|---|
init_tag_system.py | 初始化标签体系所需的表与基础数据 | 第一次搭建自动化环境时执行一次 | 无特殊账号 | 属于一次性初始化，不是常驻任务；重复执行前先确认是否幂等 |
stock_pool_runner.py | 按规则维护股票池 | 每日维护关注池、按标签或条件刷新成分 | 股票池相关表已初始化 | README 把「股票池」与「标签」并列为新 UI 的基础，两者要配合使用 |
qmt_data_runner.py | 通过 QMT 拉取行情数据 | 需要实时/准实时数据时定时运行 | QMT 授权 + 本机 QMT 目录 | 没有授权时此 runner 不可用；配置里 qmt_mini_data_path 默认指向 Windows 路径 |
qmt_tick_runner.py | 通过 QMT 拉取逐笔（tick）数据 | 日内研究、盘口分析 | 同上，门槛更高 | tick 数据量与写入压力远大于日线，先估算存储 |
today_shoot_runner.py | 当日「射击」类信号（按目录命名推断的当日快筛） | 盘后快速筛出当日关注标的 | 依赖已写入的行情与因子数据 | 命名来自项目内部术语，具体逻辑以源码为准 |
today_top_runner.py | 当日排行榜类任务（同上） | 盘后生成当日榜单 | 同上 | 与上一个 runner 属于同一组当日任务，建议一起放进定时计划 |
怎么安排运行顺序：先
init_tag_system（一次），再数据类 runner（qmt_data_runner），然后股票池与当日信号类 runner，最后是消费侧（界面或接口）。顺序颠倒会导致信号任务读到空数据。Tag service
ZVT 标签体系的九个文件分工
src/zvt/tag/ 是这个项目里少见的「完整应用层」——有模型、服务、统计与 AI 建议。
| 文件 | 职责 | 什么时候会用到 | 注意点 |
|---|---|---|---|
tagger.py | 打标签的执行入口 | 需要给标的批量打标记时 | 标签来源可以是规则，也可以是外部输入 |
tag_service.py | 标签读写服务层 | 二次开发时最常用的入口 | 表结构与写入约定以它为准 |
tag_models.py / tag_schemas.py | 标签的数据模型与 schema | 要查标签表、写自定义标签时 | 与 REST 侧的标签接口一一对应 |
tag_stats.py | 标签统计 | 统计某标签在股票池内的分布 | 对应 api-tests 里的 get_tag_suggestions_stats 样例 |
tag_utils.py / common.py | 工具与公共定义 | 扩展标签逻辑时 | —— |
ai_suggestion.py | AI 标签建议 | 想用大模型辅助打标签时 | 需要 API Key：配置文件里 moonshot_api_key 与 qwen_api_key 默认为空 |
REST samples
REST 侧的真实接口样例：四组、二十余个 .http
仓库根目录有一个 api-tests/ 目录，用 .http 文件的形式给出了接口调用样例。这是官方文档里没有的“活文档”。
| 分组 | 样例文件（部分） | 能做什么 | 适用场景 | 注意点 |
|---|---|---|---|---|
| 股票池 | create_stock_pools.http、get_stock_pools.http、get_stock_pool_info.http、create_stock_pool_info.http、del_stock_pool.http、get_main_tags_in_stock_pool.http | 创建/查询/删除股票池，查池内主要标签 | 把研究标的按主题分组管理 | 样例里的主机与端口需按本机 zvt_server 调整 |
| 标签 | tag/batch_set_stock_tags.http 等 | 批量给标的打标签 | 把研究结论沉淀成可检索的标记 | 标签是项目内部约定，命名要自己统一 |
| 因子 | factor/get_factors.http、factor/query_factor_result.http | 查因子定义与因子计算结果 | 把因子结果接到外部程序或界面 | 返回结构与 /docs 中的模型一致 |
| 事件与主题 | event/create_stock_topic.http、query_stock_topic.http、update_stock_topic.http、get_stock_event.http、get_stock_news_analysis.http、get_tag_suggestions_stats.http、ignore_stock_news.http | 维护股票主题、查事件与新闻分析、看标签建议统计 | 把公告新闻与标签体系联动 | 新闻分析属于 AI 能力，依赖已配置的模型 Key |
用法：把
zvt_server 起来后，用支持 .http 的客户端直接导入这些文件即可逐个试接口，比照 README 猜参数快得多。它们同时暴露了接口的字段命名约定，是做二次开发时很有用的参考。Scheduling
把这套东西排进日常：三种调度方式
框架自带 apscheduler 依赖，但长期运行不一定非要用它。
| 方式 | 怎么做 | 适合 | 优势 | 注意点 |
|---|---|---|---|---|
| 系统计划任务 | Windows 任务计划 / cron 调用 runner 脚本 | 个人研究机、单机部署 | 与框架解耦，日志与失败重试由系统管 | 要自己处理虚拟环境路径与工作目录 |
| 框架的 apscheduler | 在代码里注册定时任务 | 常驻进程式的部署 | 与框架同进程，便于共享配置 | 进程退出就停；依赖的 19 项里已包含它 |
| 手动按需执行 | 想更新时自己跑一次 | 低频研究、验证阶段 | 最简单，不会产生意外的写入 | 数据新鲜度依赖你的习惯，容易忘记 |
排序建议：无论用哪种方式，任务顺序都应固定为「数据 → 股票池/标签 → 信号/榜单 → 消费」。把顺序写进脚本而不是靠记忆，是让结果可复现的前提。
Pitfalls
自动化层最容易踩的四件事
这四条分别来自配置、目录命名与依赖清单。
两个 qmt runner 有硬门槛
qmt_data_runner 与 qmt_tick_runner 依赖 QMT 授权与本机 QMT 目录；没有授权时这两个 runner 直接不可用。这不是配置技巧能绕过的，需要先联系作者开通。
runner 名称是项目内部术语
today_shoot_runner、today_top_runner 这类命名来自作者自己的研究习惯，官方文档没有解释它们的判定逻辑。使用前先读源码确认它到底筛什么。
写入行为需要幂等保护
定时任务的常见事故是「重复跑导致重复写入」。官方示例里用 finish_date 这类属性做保护，说明框架层面不会自动去重——调度前先确认每个 runner 是否幂等。
证据边界：本页对 runner 用途的描述基于目录命名与源码位置的合理推断，官方文档没有逐条说明；「今日射击/榜单」这类内部术语的确切逻辑请以源码为准。本站未运行这些 runner。
FAQ
标签与定时任务常见问题
以 src/zvt/tasks、src/zvt/tag 目录与 api-tests/ 样例为准。
必须要用 QMT 才能用这些 runner 吗？
不是。六个 runner 里只有 qmt_data_runner 与 qmt_tick_runner 依赖 QMT；初始化、股票池、当日信号类 runner 用的是已经写进本地库的数据，走其它 provider（如东财）也可以。
标签体系和股票池是什么关系？
股票池是「一组标的的集合」，标签是「贴在标的上的标记」，两者组合使用：可以用标签规则刷新股票池成分，也可以查询某个池子里的主要标签分布（对应 api-tests 里的 get_main_tags_in_stock_pool）。具体表结构以 tag 模块的 schema 为准。
AI 标签建议需要额外付费吗？
需要自己提供模型服务：配置文件里留了 moonshot_api_key 与 qwen_api_key 两个位置，默认是空的。费用与配额取决于你使用的模型服务商，本站不做推荐也不代答。
可以把这些任务放进 crontab 吗？
可以，而且更常见。框架依赖里虽然有 apscheduler，但把 runner 交给系统计划任务能避免常驻进程，也便于看日志与失败重试。要注意把虚拟环境的解释器路径与工作目录写全。
接口样例可以直接用吗？
可以直接导入到支持 .http 的客户端使用，但要先把请求里的主机与端口改成自己 zvt_server 的地址（默认 8090），并注意部分接口需要先有股票池或标签数据才能返回非空结果。
这套自动化能力在 EasyClaw 里有对应物吗？
没有已证实集成。本机的 stock-monitor 技能做的是预警监控（7 类规则、分级提醒），形态是常驻监控脚本，与 ZVT 的 runner + 股票池 + 标签体系不是同一套东西。可对照但不可混用。