docs: 定位与同类项目对比 + 消费端复权指南

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]`

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