锁定版本，别追最新
项目 2019 年建仓、2026 年仍在更新，但 README 明确不保证兼容，且主要维护者只有一位。把 zvt 与 19 项依赖一起锁定，是让研究可复现的前提；升级按需而不是习惯。
ZVT 项目研究站 · 报错与边界
ZVT 的边界与排查：四条硬边界，五类常见报错
把 ZVT 当作万能框架是最常见的误判来源。本页先讲清四条硬边界——不保证向后兼容、实时行情依赖 QMT、没有实盘交易能力、数据不是随代码一起免费——再给出一张按场景查的排查表。本站没有在本机运行 ZVT，所以只写官方文件与源码能支撑的内容。
ZVT 首次运行的五个卡点
代理默认值127.0.0.1:1087
缺 uvicornREST 路线
依赖钉版本19 项
recorders 测试需真实数据源
QMT 授权实时行情
config.json、requirements.txt 与 README 自绘（非官方排查图）；本站未在本机运行 ZVT，不宣称这些修复已被验证。Hard boundaries
ZVT 的四条硬边界：先知道做不到什么
这四条都能在官方材料里找到明确依据，比任何参数技巧都重要。
| 边界 | 官方依据 | 对使用者的实际影响 | 可以怎么办 | 注意点 |
|---|---|---|---|---|
| 不保证向后兼容 | README 的 Declaration 段：「本项目目前不保证任何向后兼容，升级请谨慎」 | 升级可能直接破坏你的策略代码与本地数据结构 | 锁定版本、备份 zvt_home、升级前读 changelog 与 diff | 仓库里还有 sql/ 目录的手工库维护脚本，说明存在需要人工干预的变更 |
| 实时行情依赖 QMT | README：「新 UI 的实时行情基于 QMT 数据源，需要开通的同学请联系作者」；配置里实时表的 provider 只有 qmt | 没有授权就拿不到实时数据，界面里的实时部分为空 | 先用日线做研究；确有实时需求时走 QMT 开通流程或另接行情源 | 这不是配置能绕过的限制 |
| 没有实盘交易能力证据 | 官方材料只涉及数据、因子、回测与界面，未提供交易接口或报单模块说明 | 不能把它当作实盘系统 | 当作研究与回测工具使用 | 本站不宣称任何实盘能力 |
| 代码免费 ≠ 数据免费 | 代码为 MIT；但聚宽等 provider 需要账号，各数据源有自身条款 | 研究可以自由开始，获取数据仍受各源授权约束 | 用无账号来源起步（东财、新浪、交易所）；有账号的按条款使用 | 数据使用范围由数据源方决定，本站不代答 |
许可现状（证据冲突如实记录）：仓库根目录有
LICENSE 文件、GitHub API 返回 spdx_id = MIT；但 PyPI 的 info.license 字段是空的，只有 classifier 声明 MIT。合规要求严格时建议以仓库 LICENSE 原文为准，必要时保留该文件副本。Troubleshooting
ZVT 报错排查表：六类真实场景
下表把官方文件里能查到的原因与对应检查列清楚。这些检查项来自源码与文档，不是本机验证过的修复步骤。
| 现象 | 最可能的原因 | 怎么查 | 处理方向 | 注意点 |
|---|---|---|---|---|
| 取数长时间无响应或直接连接失败 | config.json 里默认开启本地代理 127.0.0.1:1087，而本机没有代理服务 | 打开框架的 config.json 看 http_proxy / https_proxy 两行的值 | 按实际网络环境修改或清空代理配置 | 新装环境最常见的一条；也是「装完了却什么都取不到」的头号原因 |
zvt_server 起不来，提示缺模块 | uvicorn 不在 requirements.txt 的 19 项依赖里 | 看报错模块名；对照 requirements.txt | 先 pip install uvicorn 再启动 | README 的 REST 章节写了这一步，但容易被跳过 |
| 安装时依赖解析冲突或把现有环境改坏 | 19 项依赖全部钉死版本，与既有环境冲突 | 装之前记录现有 pandas / numpy / SQLAlchemy 版本 | 用独立虚拟环境安装；必要时回滚 | 不建议装进系统解释器 |
| 跑 pytest 时大量失败或卡住 | recorders 用例需要真实数据源与凭据 | 看失败用例是否集中在 tests/recorders/ | 按官方命令加 --ignore=tests/recorders/ | 这是官方 README 明确给的参数，不是绕过测试 |
| 界面或接口里没有实时数据 | 实时表只登记了 qmt 一个 provider，且需要授权 | 查 config.json 的 storage.schema_providers 中 stock_quote 一项 | 先走 QMT 开通流程；或把实时部分从研究流程里剥离 | 提示「没有开通」而不是报错时，先确认自己是不是在找实时数据 |
| 升级后代码报错、表结构对不上 | README 明确不保证向后兼容 | 对比升级前后的版本号与改动文件 | 回滚到旧版本；或用 sql/ 目录里的维护脚本手工处理 | 升级前务必备份整个 zvt_home |
Diagnosis order
ZVT 出问题时按这个顺序查，别一上来就重装
报错信息通常不在控制台，而在日志目录；顺序对了能省掉大量重复劳动。
先看日志，不看控制台
ZVT 把日志写到
log_path下。取数失败的原始报错（限流、解析失败、连接被拒）通常只在日志里，控制台可能只有一行提示。预期：找到明确的异常类型与堆栈。确认数据到底有没有落盘
去看 ZVT 的
data_path目录。空目录说明写库没成功，问题在取数层；有数据但查不到，问题在查询条件或时间字段口径。预期：能把问题归类到「取不到」或「查不出」。检查代理与 provider 凭据
ZVT 的代理默认值是
127.0.0.1:1087；聚宽一侧需要账号，QMT 一侧需要授权。预期：明确知道自己这次取数走的是哪家、需要什么凭据。换一个 provider 交叉验证
同一个 schema 往往注册了多个 provider，换一个能立刻区分「框架问题」还是「某个源失效」。预期：换源后能取到数据，说明是单源问题。
最后才考虑重装或降级
重装会丢失环境里的其它依赖关系，且不能修复数据源失效这类外部问题。真要做，先备份
zvt_home与虚拟环境清单。预期：每一步都可回滚。
证据边界：本站没有在本机运行 ZVT，以上排查顺序基于官方文件给出的配置项与 README 说明，属于可验证的检查清单，不是已验证的修复方案。
Ownership
问题归属：四类故障该找谁
排错最耗时的部分不是修，而是找错方向。下表按问题归属给出判断依据——ZVT 只对其中一类负责。
| 问题类型 | 典型表现 | 该找谁 | 判断依据 | 注意点 |
|---|---|---|---|---|
| 框架自身的缺陷 | 同一版本、同一输入在别人机器上也不能重现地失败 | ZVT 仓库的 Issue | 仓库当前有 14 个待处理 Issue，先检索是否已有人报告 | 提问时附版本号与日志原文，否则很难被回应 |
| 数据源变更或限制 | 只有某一家 provider 失败，换源就正常 | 数据源方 / 等待 recorder 更新 | 用同 schema 的另一个 provider 交叉验证即可判断 | 框架无法控制第三方站点改版，这是长期风险 |
| 本机环境配置 | 装不上、起不来、连不上 | 自己（按上方排查顺序） | 代理默认值、uvicorn 缺失、依赖钉版本这三类占多数 | 不要把它们当成框架 bug 去提 Issue |
| 策略与因子逻辑 | 能跑完但结果不符合预期 | 自己 | 框架只提供执行与记录，不判断逻辑对错 | 先检查复权口径与时间轴口径是否一致 |
| 账户与授权 | 聚宽数据取不到、实时行情为空 | 账号提供方 | 聚宽需账号与配额，QMT 需向作者申请开通 | 授权类问题与代码无关，改代码不会生效 |
Maintenance
长期使用 ZVT 的三个维护动作
这个项目的更新节奏与维护者规模决定了：长期用它，维护动作比功能探索更重要。
备份数据目录而不是只备份代码
研究价值大部分在本地库里：多年日线、财务、标签与交易记录。备份 zvt_home 整目录比备份代码更重要——代码可以从 PyPI 重装，数据要重新抓取的成本高得多。
给数据源失效留预案
多数 provider 依赖公开站点，改版就会失效。做法是：同一份关键数据尽量有两个来源可用、把失效检测做进日常任务（例如关键表行数为 0 就告警），而不是等下次研究才发现。
FAQ
边界与许可常见问题
回答以官方文件为准；涉及合规的部分本站只陈述证据，不给法律意见。
ZVT 是免费的吗？可以商用吗？
代码是 MIT 许可，仓库根目录有 LICENSE 文件，可自由使用、修改、分发（保留版权声明）。两点提醒：PyPI 的 license 字段为空、只有 classifier 声明 MIT，合规严格时以仓库 LICENSE 为准；数据本身受各数据源条款约束，与代码许可无关。
「不保证向后兼容」具体意味着什么？
意味着作者升级时可能改动类名、参数名甚至表结构，且不提供迁移保证。对使用者的实际要求是：锁定版本、备份数据目录、升级前先在测试环境跑一遍自己的策略。
没有 QMT 授权还能用什么？
可以用东财、新浪、交易所等不需要账号的来源做日线级研究，股票池、标签、因子与回测这条链路都不依赖实时行情；只是「实时」这部分能力缺失，需要实时数据的部分要另想办法。
能取到多少年的历史数据？
取决于数据源，而不是框架。README 的示例里美股 AAPL 的日线可以回溯到 1984 年，A 股示例标的数据从 2007 年开始——这些是示例输出，不代表每一只标的都能拿到同样长度。要确认某个标的的历史深度，必须自己查一次。
项目还活跃吗？会不会停止维护？
截至 2026-09-18 核验：最近一次代码推送是 2026-07-01，最近一个发布版本是 2026-01-18 的 0.13.5，仓库未归档。但 README 自己提示过「随着作者想法变化，一些曾经重要的东西可能不再维护」——长期依赖它需要接受这种不确定性。
遇到问题去哪里问？
官方渠道是 GitHub Issues（截图显示有 14 个待处理 Issue）与作者的联系方式（README 里给了微信与知乎专栏）。提问前建议先按上面的排查顺序自查，并把日志原文与版本信息一起附上。
本站为什么不提供运行结果？
因为本站没有在本机安装或运行 ZVT，任何「运行截图」都会是伪造的。页面只写官方文件、源码结构与本机 EasyClaw 技能目录能核实的事实；ZVT 与 EasyClaw 也没有已证实集成。