From dfbe078938ff5989ffc9c231ceeff7b0d0e8fa8e Mon Sep 17 00:00:00 2001 From: xbfighting Date: Tue, 7 Jul 2026 15:51:17 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E5=AE=9A=E4=BD=8D=E4=B8=8E?= =?UTF-8?q?=E5=90=8C=E7=B1=BB=E9=A1=B9=E7=9B=AE=E5=AF=B9=E6=AF=94=20+=20?= =?UTF-8?q?=E6=B6=88=E8=B4=B9=E7=AB=AF=E5=A4=8D=E6=9D=83=E6=8C=87=E5=8D=97?= =?UTF-8?q?=20(#36)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README 新增"定位与同类项目"：差异化四要点（增量幂等自愈/status 可观测/无幸存者偏差/agent 契约）+ 五个同类项目事实性对比表 - AGENTS.md 新增消费端复权指南：涨跌幅复权 factor 法（引 rustdx 实现与原理文章），注明与券商口径的已知差异；数据契约不变 - 来源：2026-07-07 对标调研（easy_tdx/tdx-api/rustdx/mootdx） Co-Authored-By: Claude Fable 5 --- AGENTS.md | 12 +++++++++++- README.md | 21 +++++++++++++++++++++ 2 files changed, 32 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 3b5580b..2d87c04 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -77,9 +77,19 @@ SELECT WHERE date < (SELECT MAX(date) FROM daily_data))) AS prev_n; ``` +## 需要复权时（消费端自助，库本身永远不复权） + +窗口内有分红除权的股票，不复权价格会出现跳空——这是数据特征不是 bug。消费端自助复权的成熟做法是**涨跌幅复权 factor 法**（参考 [rustdx 的实现与 SQL 范例](https://github.com/zjp-CN/rustdx#通达信数据)，原理见其作者的[《涨跌幅复权与前复权》](https://zjp-cn.github.io/posts/qfq/)）： + +1. 从除权除息信息（通达信 gbbq 股本变迁文件，或任意财经数据源）算出除权日调整后的 preclose +2. factor = 每日 (close / preclose) 累乘；增量维护时新 factor = 昨日 factor × (今收 / 今前收)，永不重算历史 +3. 前复权价 = factor × (最新 close / 最新 factor)，任意周期涨幅 = 末 factor / 首 factor × 首 close / 首 preclose + +注意：该算法与券商软件的前复权存在小的口径/浮点差异（rustdx issue #32/#37 有讨论），做形态对比时留意；做收益率计算则完全够用。 + ## 数据契约（不要试图"修复"这些） -- 不复权，默认口径永不改变 +- 不复权，默认口径永不改变（复权见上一节，消费端处理） - `daily_data`/`minute*` 的 code 保持 6 位纯数字 - 行情表不存股票名称 - 均线窗口固定为 `[5,10,13,21,34,55,60,89,144,233,250]` diff --git a/README.md b/README.md index 3d6585d..286d55b 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,27 @@ 读取本地通达信股票数据（日线 + 5/15/30/60 分钟线），增量同步到数据库。适合想用 SQL / pandas 做 A 股量化分析、又不想依赖收费行情 API 的人。 +## 定位与同类项目 + +tdx2db 做一件事：**把通达信本地数据变成你自己的 SQL 数据库资产**。差异化在管道可靠性： + +- **增量幂等、断点自愈**：起点按股票、按表分别计算，中断重跑不丢数据不重复；衍生分钟表缺口增量重跑自动补齐 +- **状态可观测**：`tdx2db status` 一眼确认每表行数/覆盖/日期范围，"退出码 0 ≠ 数据进去了"有官方验证手段 +- **无幸存者偏差**：数据来自本地 vipdoc 文件，已退市股票的历史仍在 +- **AI agent 就绪**：`AGENTS.md` + Claude Code skill 提供显式的 agent 使用契约 + +与同类开源项目的分工（事实性对比，各有侧重）： + +| 项目 | 数据来源 | 产出形态 | 状态* | +|------|----------|----------|------| +| **tdx2db** | 本地 vipdoc 文件 | PostgreSQL / MySQL / SQLite（增量同步） | 活跃 | +| [easy_tdx](https://github.com/handsomejustin/easy_tdx) | 通达信协议在线直连 | DataFrame / JSON / REST（含指标、回测） | 活跃 | +| [tdx-api](https://github.com/oficcejo/tdx-api) | 通达信协议在线直连 | Docker 部署的 REST 实时接口 | 活跃 | +| [rustdx](https://github.com/zjp-CN/rustdx) | 本地 .day + 东方财富 | CSV / ClickHouse / MongoDB（含复权因子） | 低频维护 | +| [mootdx](https://github.com/mootdx/mootdx) / [pytdx](https://github.com/rainx/pytdx) | 本地文件 + 在线协议 | DataFrame 读取库 | 已停更 | + +\* 状态为 2026-07 快照。需要实时行情选在线直连类项目；需要可 SQL 查询、可增量维护的历史数据资产，选 tdx2db。 + ## 安装 ```bash From 76cd9a41400920565d39559a5fabde5cb879c959 Mon Sep 17 00:00:00 2001 From: xbfighting Date: Tue, 7 Jul 2026 15:56:52 +0800 Subject: [PATCH 2/2] =?UTF-8?q?fix:=20rustdx=20=E9=93=BE=E6=8E=A5=E9=94=9A?= =?UTF-8?q?=E7=82=B9=E6=94=B9=E4=B8=BA=E5=AE=9E=E9=99=85=E5=AD=98=E5=9C=A8?= =?UTF-8?q?=E7=9A=84=E7=AB=A0=E8=8A=82=EF=BC=88review=20=E4=BF=AE=E5=A4=8D?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 2d87c04..bd945c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,7 +79,7 @@ SELECT ## 需要复权时（消费端自助，库本身永远不复权） -窗口内有分红除权的股票，不复权价格会出现跳空——这是数据特征不是 bug。消费端自助复权的成熟做法是**涨跌幅复权 factor 法**（参考 [rustdx 的实现与 SQL 范例](https://github.com/zjp-CN/rustdx#通达信数据)，原理见其作者的[《涨跌幅复权与前复权》](https://zjp-cn.github.io/posts/qfq/)）： +窗口内有分红除权的股票，不复权价格会出现跳空——这是数据特征不是 bug。消费端自助复权的成熟做法是**涨跌幅复权 factor 法**（参考 [rustdx 的实现与 SQL 范例](https://github.com/zjp-CN/rustdx#使用示例)，原理见其作者的[《涨跌幅复权与前复权》](https://zjp-cn.github.io/posts/qfq/)）： 1. 从除权除息信息（通达信 gbbq 股本变迁文件，或任意财经数据源）算出除权日调整后的 preclose 2. factor = 每日 (close / preclose) 累乘；增量维护时新 factor = 昨日 factor × (今收 / 今前收)，永不重算历史