这个文档记录了 DojoSDK 项目的整体代码结构、核心设计理念以及必须严格遵守的开发规范。作为辅助开发的 Agent,你在处理任何相关的需求和代码修改时,必须优先阅读并遵循本文件中的所有规则。
项目的主要代码位于 dojo/ 目录下:
dojo/client/: 客户端核心模块。base.py: 底层 HTTP 请求逻辑、错误封装和重试机制。sync.py: 同步客户端Dojo。async_client.py: 异步客户端AsyncDojo。
dojo/datasource/: 数据源抽象层。- 支持在线通过 HTTP API 获取数据(如
api.py)。 - 支持离线拉取数据:通过 HuggingFace 或 ModelScope 下载本地离线文件并解析 (Parquet 格式),主要逻辑在
huggingface.py及相关模块中。
- 支持在线通过 HTTP API 获取数据(如
dojo/resources/: 业务逻辑模块。每个文件对应一类 API 端点 (如stocks.py,forex.py,macro.py等),负责具体接口的路径定义、参数拼装和调用。dojo/types/: 数据类型定义。所有 API 接口的入参和出参必须在这里使用Pydantic进行严格类型校验与序列化定义。docs/: 文档治理与 MkDocs 源码(详见下方"文档分类"规则)。README.md: 仅供维护者阅读的文档治理说明。site/: 唯一可发布文档源码目录(assets/、zh/、en/)。
scripts/: 独立脚本(如compare_openapi.py、verify_kline_snapshot_backend.py)。
- 所有可发布的 Markdown 一律放在
docs/site/{zh,en}/下;禁止在docs/根目录新增独立设计或计划文档。 - 分类边界:
design/:某个具体子系统当前有效的设计、契约和行为边界。reference/:调用方可依赖的稳定接口、弃用安排和移除门槛。development/:如何开发、测试、验证和发布。plans/:尚未完成的方案、迁移顺序、backlog 或历史决策;它不是当前 API 契约。assets/:只存放站点共享静态资源(如assets/openapi/qdata_openapi.json),不存放 Markdown 正文。
- 中英文页面保持相同的相对路径;新增或移动已发布页面时,必须同步更新根目录
mkdocs.yml的导航。 - 计划实施完成后,把长期有效的结论迁移到
design/、reference/或development/,并删除或归档失效计划。不要让同一份权威说明同时存在于多个分类。
- 多数据源架构: 接口拉取数据不直接硬编码 HTTP 请求,而是通过统一的
DataSource协议 (fetch和fetch_df方法),使得 SDK 可以在线上的 API 请求和离线数据集模式之间透明、无缝地切换。 - 同步与异步并存: 借助
httpx和anyio,底层实现一份逻辑,同时对外提供一致的同步 (Dojo) 和异步 (AsyncDojo) API。 - 类型安全: 全面采用
pydantic模型和 Python 类型提示 (Type Hinting),保障数据传输和解析的正确性与安全性。
在执行开发任务时,你绝对不能违反以下操作规则:
- 绝对禁止使用任何
git相关命令:在这个项目中,你不能调用git add、git commit、git status等任何与 Git 版本控制相关的命令。 - 绝对禁止直接使用
python或pip运行脚本与测试:此项目使用uv管理依赖和环境,任何环境相关的命令或测试运行必须使用uv,例如:使用uv run pytest而不是pytest或python -m pytest。
- 网络请求: 所有网络请求逻辑只能使用
httpx。 - 数据类型: 所有数据实体、请求体、响应体必须使用
pydantic定义BaseModel。 - 异步兼容: 所有的并发逻辑应尽量借助
anyio,以保证最佳的异步环境兼容性(例如使用anyio.to_thread执行同步阻塞函数)。 - 离线数据源适配 (双端兼容): 当你需要修改
dojo/datasource/huggingface.py及离线下载相关的逻辑时,你必须同时考虑并兼容 HuggingFace 和 ModelScope 两个平台。任何针对单平台的优化(如重试机制、缓存目录清理逻辑等)都必须适配另一个平台。
Reminder: 在开始具体的代码修改前,请仔细核对本指南中的约束条件,确保没有遗漏(特别是
uv的使用和git命令的禁用要求)。