Files
pytdxdata/docs/ai.md
T
openbot-coder 1bee6b0fc7 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 实际收集用例数)
2026-09-15 14:55:07 +08:00

68 lines
3.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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) — 参数到底该填几