tdx2db: Instructions file for Codex

AGENTS.md

面向 AI agent 的 tdx2db 使用指南。你（agent）在装有 tdx2db 的环境中同步、查询 A 股行情数据时，本文档是首要参考。贡献代码请另见 CLAUDE.md 与 CONTRIBUTING.md。

这是什么

tdx2db 读取本地通达信（TDX）行情软件的数据文件，增量同步到 PostgreSQL / MySQL / SQLite。产出物是一个可直接 SQL 查询的行情数据库——你不需要通过 tdx2db 读数据，直接查库即可；tdx2db 只负责写入。

通达信盘后数据下载 → tdx2db sync → 数据库 ← 你的 SQL 查询

CLI 速查

tdx2db sync                  # 日常唯一命令：增量同步日线 + 5/15/30/60 分钟线
tdx2db status                # 只读：每表行数/覆盖股票数/日期范围（不需要 TDX_PATH）
tdx2db status --json         # 机器可读，优先用这个
tdx2db stock-list --db-only  # 同步股票列表

配置经 .env（从当前工作目录向上逐级查找）或全局参数 --tdx-path / --db-type / --db-name 等。密码只能放 .env，无命令行参数。退出码：0 成功，非 0 失败——但退出码 0 不代表数据写入成功，必须用 status 验证（见下"同步后验证"）。

数据库 Schema

表	唯一约束	说明
daily_data	(code, date)	日线 OHLCV + 11 条均线
minute{5,15,30,60}_data	(code, datetime)	分钟线；15/30/60 由 5 分钟重采样
stock_info	code	股票列表：真实名称、zgb/ltag 总股本/流通A股（万股）、capital_date/list_date
block_stock_relation	(block_type, block_name, code)	板块-个股关系，全量快照；block_type ∈ 行业/概念/指数/地区/风格/特殊

• 行情表通用列：code, market, datetime, date, open, high, low, close, volume, amount, ma5, ma10, ma13, ma21, ma34, ma55, ma60, ma89, ma144, ma233, ma250
• 均线：ma13/21/34/55/89/144/233 是斐波那契窗口（缠论强弱分析主力），ma233 常被当作年线；上市天数不足窗口的行为 NULL
• 周线/月线没有表，由日线 resample 得到
• 收录范围：深市 000/001/002/300/301、沪市 60xxxx/688xxx；无北交所、ETF、指数

典型查询（内部项目验证过的形态）

-- 1. 单票日线区间 + 均线
SELECT date, open, high, low, close, volume, amount,
       ma5, ma13, ma21, ma34, ma55, ma89, ma144, ma233
FROM daily_data
WHERE code = '600036' AND date BETWEEN '2026-01-01' AND '2026-07-01'
ORDER BY date;

-- 2. 某日全市场截面（maN IS NOT NULL 兼作"数据成熟"哨兵，排除上市不足 N 日的新股）
SELECT code, close, ma5, ma13, ma233
FROM daily_data
WHERE date = '2026-07-03' AND ma233 IS NOT NULL;

-- 3. 最新交易日探测（加 ma5 条件确保当日指标已计算完成）
SELECT MAX(date) FROM daily_data WHERE ma5 IS NOT NULL;

-- 4. 按板块取成分（行业含一/二/三级；block_level=2 ≈ 通达信导出 CSV 的行业口径）
SELECT code FROM block_stock_relation
WHERE block_type = '行业' AND block_name = '煤炭开采';

SELECT DISTINCT block_name FROM block_stock_relation
WHERE block_type = '行业' AND block_level = 2;   -- 全部二级行业（板块强弱迭代口径）

-- 5. 按个股查板块归属
SELECT block_type, block_code, block_name FROM block_stock_relation
WHERE code = '000001';

-- 6. 换手率(%)：volume(手) / ltag(万股) 单位差恰好抵消
SELECT d.date, d.volume / s.ltag AS turnover_pct
FROM daily_data d JOIN stock_info s ON RIGHT(s.code, 6) = d.code
WHERE d.code = '000001' ORDER BY d.date DESC LIMIT 20;
-- 注意：股本为当前快照，股本变动点之前的历史换手率失真（精确历史需 gbbq）
-- list_date 上市日期可用于次新股过滤：WHERE s.list_date < CURRENT_DATE - 500