release: v0.5.0(文档站 + README 瘦身 + AI 助手技能)
新增 - 文档站(MkDocs + Material + mkdocstrings),push main 自动构建并部署 GitHub Pages - SKILL.md:面向 AI 编程助手的技能文件(三条必守约定 / 枚举取值表 / 任务→方法决策表 / 9 条陷阱) - docs/ai.md:文档站的「AI 助手接入」页 - tests/test_check_docs.py(10 项):漂移检查器自身的自测 变更 - README 361 → 125 行,只保留入口层;CLI 手册 / API 表 / 通道路由 / 架构树 / 扩展市场 / easy-tdx 对比 / Changelog 全部移交文档站与 CHANGELOG.md - README 相对链接改为绝对 URL(PyPI 渲染不重写相对链接,原本在 PyPI 页面全 404) - check_docs.py 扩展为两档:MUST_LIST_ALL(须列全)+ MUST_NOT_BE_STALE(只需无过时引用), 并把 SKILL.md / README / llms.txt / 教程类页面纳入;白名单放行 config 的模块级函数 - 版本号 0.4.0 → 0.5.0;包元数据 Documentation 指向文档站 - uv.lock 同步 修复 - ExMarket 成员数 52 → 46(实测 IntEnum 成员数),4 处文档同步更正 - docs/ai.md 的 3 处相对链接 + CHANGELOG 的 SKILL.md 链接(会导致 mkdocs --strict 失败) - README 标注的测试数量 85 → 109(pytest 实际收集用例数)
This commit is contained in:
1 parent
c4dd61665b
commit
1bee6b0fc7
14 files changed
+516
-321
No files matched your search
@@ -1,6 +1,6 @@
|
||||
# pytdxdata 对外接口清单
|
||||
|
||||
> 以 `src/pytdxdata` 源码为准整理(v0.4.0)。分四类:Python API / 数据模型 / 辅助模块 / CLI。
|
||||
> 以 `src/pytdxdata` 源码为准整理(v0.5.0)。分四类:Python API / 数据模型 / 辅助模块 / CLI。
|
||||
>
|
||||
> 方法与代码的一致性由 `scripts/check_docs.py` 在 CI 中校验。
|
||||
|
||||
@@ -144,7 +144,7 @@ from pytdxdata import (
|
||||
| `Market` | SZ=0 / SH=1 / BJ=2 |
|
||||
| `KlinePeriod` | MIN_5=0 / MIN_15=1 / MIN_30=2 / MIN_60=3 / DAY=4 / WEEK=5 / MONTH=6 / MIN_1=7 / MIN_3=8 / YEAR=9 / SEASON=10 / YEAR_ALT=11(`is_minute` 属性) |
|
||||
| `Adjust` | NONE=0 / QFQ=1 / HFQ=2 |
|
||||
| `ExMarket` | 52 个扩展市场:HK_MAIN_BOARD=31 / US_STOCK=74 / CFFEX_FUTURES=47 / ZZ_FUTURES=28 / DL_FUTURES=29 / SH_FUTURES=30 / GZ_FUTURES=66 / SH_STOCK_OPTION=8 / SZ_STOCK_OPTION=9 等 |
|
||||
| `ExMarket` | 46 个扩展市场:HK_MAIN_BOARD=31 / US_STOCK=74 / CFFEX_FUTURES=47 / ZZ_FUTURES=28 / DL_FUTURES=29 / SH_FUTURES=30 / GZ_FUTURES=66 / SH_STOCK_OPTION=8 / SZ_STOCK_OPTION=9 等 |
|
||||
|
||||
**dataclass(均为 `@dataclass(slots=True)`)**
|
||||
|
||||
|
||||
+67
@@ -0,0 +1,67 @@
|
||||
# AI 助手接入
|
||||
|
||||
pytdxdata 的枚举取值**完全没有直觉**(`KlinePeriod.DAY` 是 `4` 不是 `0`),
|
||||
所以 AI 助手凭常识写代码**几乎必错**。为此项目提供两条 AI 通道,分工不同:
|
||||
|
||||
| 文件 | 面向 | 内容 |
|
||||
|---|---|---|
|
||||
| [`llms.txt`](https://openbot-coder.github.io/pytdxdata/llms.txt) | AI 爬虫 / 问答型模型 | 心智模型、能力分组、关键陷阱,自动随站点发布 |
|
||||
| [`SKILL.md`](https://github.com/openbot-coder/pytdxdata/blob/main/SKILL.md) | AI **编程**助手 | 必守约定、枚举取值表、可运行模板、任务→方法决策表、9 条陷阱 |
|
||||
|
||||
`llms.txt` 解决「这个库能干什么」,`SKILL.md` 解决「代码该怎么写对」。
|
||||
|
||||
## 装载 SKILL.md
|
||||
|
||||
把文件放进你所用的 AI 助手的 skills 目录即可:
|
||||
|
||||
```bash
|
||||
# WorkBuddy / Claude Code 风格
|
||||
mkdir -p ~/.workbuddy/skills/pytdxdata
|
||||
curl -o ~/.workbuddy/skills/pytdxdata/SKILL.md \
|
||||
https://raw.githubusercontent.com/openbot-coder/pytdxdata/main/SKILL.md
|
||||
```
|
||||
|
||||
也可以直接在提示词里附上该文件的 URL,或把它作为项目级 skill 放进你的仓库。
|
||||
|
||||
## 里面有什么
|
||||
|
||||
- **三条必守约定** —— 唯一入口是 `TdxData` 且必须 `async with`;`market` 是整数枚举而不是字符串;
|
||||
返回值是 `list[dataclass]` 而不是 DataFrame
|
||||
- **枚举取值表** —— `Market` / `KlinePeriod` / `Adjust` / `ExMarket` 的准确取值
|
||||
- **可运行模板** —— K 线、复权、报价、逐笔、分时、批量,全部是能直接跑的代码
|
||||
- **「想做什么 → 用哪个方法」决策表** —— 21 个常见需求的直接映射
|
||||
- **9 条真实陷阱** —— 每条都注明后果和正确做法(如 `SH 000001` 是上证指数、`SZ 000001` 才是平安银行)
|
||||
|
||||
## 为什么值得让 AI 读
|
||||
|
||||
同一个 6 位代码在不同市场含义不同、枚举值与直觉完全脱节、复权/1 分钟线会静默切换通道——
|
||||
这些都不是「读一眼签名就能猜到」的信息。不加载技能,AI 通常会写出:
|
||||
|
||||
```python
|
||||
# ❌ 三种典型错误
|
||||
await td.get_kline("sh", "600000", 0, count=240) # market 传字符串;0 是 5 分钟线不是日线
|
||||
td.get_kline(1, "600000", KlinePeriod.DAY) # 忘了 await,且没在 async with 内
|
||||
df = bars.to_dataframe() # 返回值是 list[dataclass],没有这个方法
|
||||
```
|
||||
|
||||
装载技能后这类错误基本消失。
|
||||
|
||||
## 给文档/模型作者的提示
|
||||
|
||||
改接口后请同步这几处(CI 会自动校验漂移):
|
||||
|
||||
- 手写清单(必须列全):[`docs/api/index.md`](api/index.md)、[`docs/API_REFERENCE.md`](API_REFERENCE.md)
|
||||
- 入口与教程(只要求无过时引用):`SKILL.md`、`README.md`、`llms.txt`、`getting-started`、`cookbook`、`faq`、`cli`
|
||||
|
||||
校验命令:
|
||||
|
||||
```bash
|
||||
python scripts/check_docs.py # 退出码 1 = 存在漂移
|
||||
python scripts/check_docs.py --list # 打印全部公开方法名
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- [接口总览](api/index.md) — 有哪些能力
|
||||
- [TdxData 方法](api/tdxdata.md) — 完整签名(docstring 自动生成)
|
||||
- [枚举速查](api/enums.md) — 参数到底该填几
|
||||
+1
-1
@@ -92,7 +92,7 @@
|
||||
|
||||
??? question "支持哪些市场?"
|
||||
**标准通道**:沪 / 深 / 北(A 股)、指数、ETF、可转债。
|
||||
**EX 通道**:港股、美股、期货、期权等 **52 个市场**,完整清单见 [枚举速查](api/enums.md#exmarket)。
|
||||
**EX 通道**:港股、美股、期货、期权等 **46 个市场**,完整清单见 [枚举速查](api/enums.md#exmarket)。
|
||||
|
||||
??? question "美股期权 / 港股期权能拿吗?"
|
||||
不能。通达信协议内**无美股 / 港股期权数据**。
|
||||
|
||||
+10
-1
@@ -70,10 +70,18 @@ asyncio.run(main())
|
||||
|
||||
---
|
||||
|
||||
51 个公开方法,从 docstring 实时生成,不会过期。
|
||||
51 个数据方法(另有 `start` / `close`),从 docstring 实时生成,不会过期。
|
||||
|
||||
[:octicons-arrow-right-24: API 参考](api/index.md)
|
||||
|
||||
- **让 AI 助手写对代码**
|
||||
|
||||
---
|
||||
|
||||
枚举取值反直觉,AI 凭常识几乎必错。装载 `SKILL.md` 就能一次写对。
|
||||
|
||||
[:octicons-arrow-right-24: AI 助手接入](ai.md)
|
||||
|
||||
</div>
|
||||
|
||||
## 设计取舍
|
||||
@@ -127,6 +135,7 @@ asyncio.run(main())
|
||||
- [连接池与缓存](internals/cache-pool.md)
|
||||
|
||||
- **其他**
|
||||
- [AI 助手接入](ai.md)
|
||||
- [常见问题](faq.md)
|
||||
- [更新日志](changelog.md)
|
||||
- [参与贡献](contributing.md)
|
||||
|
||||
@@ -100,6 +100,7 @@ tdx financial gpcw20260331.zip --limit 5
|
||||
|
||||
## 可选
|
||||
|
||||
- [SKILL.md](https://raw.githubusercontent.com/openbot-coder/pytdxdata/main/SKILL.md):面向 AI **编程**助手的技能文件(必守约定 / 枚举取值表 / 决策表 / 陷阱清单),比本文件更适合指导写代码
|
||||
- [完整接口清单](https://openbot-coder.github.io/pytdxdata/API_REFERENCE/):手工维护的全量清单,含参数默认值
|
||||
- [更新日志](https://github.com/openbot-coder/pytdxdata/blob/main/CHANGELOG.md)
|
||||
- [GitHub 仓库](https://github.com/openbot-coder/pytdxdata)
|
||||
|
||||
Reference in new issue
Block a user