From 0addd415fc752fa77b6afcb86b3d885f3182008e Mon Sep 17 00:00:00 2001 From: Pigbibi <20649888+Pigbibi@users.noreply.github.com> Date: Wed, 3 Jun 2026 17:21:10 +0800 Subject: [PATCH] docs: split bilingual open-source readmes --- README.md | 145 +++++++++++------------------------------------- README.zh-CN.md | 114 ++++++++++++------------------------- 2 files changed, 68 insertions(+), 191 deletions(-) diff --git a/README.md b/README.md index 73dfc56..f96ef71 100644 --- a/README.md +++ b/README.md @@ -1,142 +1,63 @@ # QuantPlatformKit - +[Chinese README](README.zh-CN.md) -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 > ⚠️ Investing involves risk. This project does not provide investment advice and is for educational and research purposes only. -## Open-source overview / 开源项目入口 +## What this project does -| Item | Description | -| --- | --- | -| Project type | shared runtime kit | -| What it does | Shared broker adapters, strategy contracts, runtime interfaces and notification utilities used across QuantStrategyLab platforms. | -| 中文说明 | 共享运行时工具包，提供券商适配、策略契约、组件加载和通知工具。 | -| Current status | Library/infrastructure. It does not own strategy alpha or backtest performance. | +QuantPlatformKit is a **Shared platform library** in the QuantStrategyLab ecosystem. It contains shared broker adapters, runtime contracts, strategy-loading interfaces, and notification utilities used by QuantStrategyLab platforms. -### Quick start +## Who this is for -- `python -m pip install -e '.[test]'` -- `python -m pytest -q` +- Engineers and researchers who want to inspect, reproduce, or extend this part of the QuantStrategyLab stack. +- Operators who need a clear entry point before reading the deeper runbooks or workflow files. +- Reviewers who need to understand the repository purpose, safety boundary, and evidence requirements before enabling automation. -### Deploy / operate safely +## Current status -Publish through package/version pins consumed by downstream repos; verify compatibility before bumping platform dependencies. +Shared library; changes should stay backward compatible unless a coordinated platform migration is planned. -### Strategy performance / evidence boundary +## Repository layout -No standalone strategy performance. Validate behavior through downstream strategy and platform tests. +- `src/`: main library and runtime code. +- `tests/`: unit and contract tests. +- `docs/`: detailed design notes, runbooks, and evidence docs. +- `.github/workflows/`: CI, scheduled jobs, and deployment workflows. -> Detailed runbooks, migration notes, workflow internals, and historical decisions are kept below. Start with this overview before using the lower-level operational sections. +## Quick start - +From a fresh clone: -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 - - -## 中文摘要 - -- 完整中文版见 [`README.zh-CN.md`](README.zh-CN.md)；本节保留在英文文件顶部，方便从当前文件直接找到中文入口。 -- 用途：本文档围绕 `QuantPlatformKit`，用于理解 `QuantPlatformKit` 的配置、运行、部署、研究或验收边界。 -- 主要覆盖：`What This Repository Is`、`Repository Workflow`、`Strategy Plugins`、`Package Layout`、`Development`。 -- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。 -- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。 -- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。 -Shared platform contracts, broker adapters, strategy-plugin helpers, and notification primitives for QuantStrategyLab repositories. - -[中文](./README.zh-CN.md) - -## What This Repository Is - -`QuantPlatformKit` is the public shared platform layer. It keeps cross-repository interfaces stable so strategy repositories and broker platform repositories can evolve without copying runtime glue. - -It contains: - -- common domain models and runtime target helpers -- narrow ports for market data, portfolio snapshots, order execution, notifications, and state -- reusable broker adapter utilities -- QuantConnect Cloud deployment helpers for hybrid hosted/self-hosted runtimes -- strategy loading, strategy-plugin, and alert-message contracts -- optional strategy-plugin alert channels for email, SMS, push, and Telegram providers -- synthetic-data tests for public behavior - -It does not contain private runtime wiring or generated strategy outputs. - -## Repository Workflow - -QuantStrategyLab repositories are split by responsibility: - -- Strategy repositories own strategy metadata, input requirements, and `manifest + evaluate(ctx)` entrypoints. -- Platform repositories own broker sessions, runtime config loading, runtime entrypoints, decision mapping, and order submission. -- Snapshot or data pipeline repositories own generated artifacts and their publication process. -- `QuantPlatformKit` owns the shared contracts and helper APIs used by those repositories. - -The normal flow is: - -```text -Platform repository - builds StrategyContext from broker/runtime inputs - loads a strategy entrypoint from a strategy repository - receives a StrategyDecision - maps that decision into broker-specific execution and notifications - -QuantPlatformKit - provides shared contracts, loaders, adapters, and plugin alert helpers +```bash +python -m pip install -e . +python -m pytest -q ``` -Strategy code should not branch on a broker platform, and platform code should not duplicate strategy rules. - -## Strategy Plugins - -Strategy plugins are sidecar artifacts that platform repositories may read when a strategy profile opts in. This repository defines the public plugin contract, compatibility checks, alert-message building, optional alert delivery helpers, and duplicate-suppression helpers. +If a command requires credentials, run it only after reading the relevant workflow or runbook and configuring secrets outside Git. -Generated plugin artifacts and platform-specific notification routing stay with the producing pipeline or consuming platform repository. Tests in this repository use synthetic price history and synthetic payloads only. +## Deployment and operation -Plugin artifacts may carry display-only `strategy_plugin_messages.v1` and -`strategy_plugin_log.v1` localized notification/log text. Platform renderers can -use those strings, while strategy and platform logic should continue to depend -on machine fields such as `canonical_route`, `suggested_action`, -`reason_codes`, and `position_control`. -General notification artifacts are loaded through `notification_targets`, not -through synthetic strategy mounts; they can trigger alerts but never attach -position controls to a strategy runtime. +Install this library from platform repositories. Run platform tests after changing contracts, adapters, or notification behavior. -Plugin alert delivery is provider-neutral at the platform boundary. Platform repositories pass runtime settings into `publish_strategy_plugin_alerts`; this repository handles configured `email`, `sms`, `push`, and `telegram` channels without coupling plugin logic to a broker platform. +Prefer manual or dry-run execution first. Enable schedules or live execution only after logs, artifacts, permissions, and rollback steps are reviewed. -## Package Layout +## Strategy performance and evidence -```text -src/quant_platform_kit/ - common/ - ibkr/ - binance/ - schwab/ - longbridge/ - quantconnect/ - notifications/ -tests/ -``` - -See [docs/quantconnect.md](./docs/quantconnect.md) for the public QuantConnect connector contract and placeholder-only examples. -See [docs/strategy_plugin_runtime_contract.md](./docs/strategy_plugin_runtime_contract.md) -for the strategy-plugin runtime contract and -[docs/strategy_plugin_runtime_contract.zh-CN.md](./docs/strategy_plugin_runtime_contract.zh-CN.md) -for the Chinese version. +Not a strategy repository. It supports execution reliability; strategy performance belongs to strategy and snapshot repositories. -## Development +README files are intentionally not a source of dated performance promises. Re-run the relevant tests, backtests, or pipeline jobs before relying on any result. -Run the public test suite: +## Safety notes -```bash -PYTHONPATH=src pytest -``` +- Never commit API keys, broker credentials, OAuth tokens, cookies, or account identifiers. +- Run new strategies and platform changes in dry-run or paper mode before any live execution. +- Review generated orders, artifacts, and logs manually before enabling schedules. -Run linting: +## Contributing -```bash -PYTHONPATH=src ruff check . -``` +Keep changes small, reproducible, and covered by the narrowest useful tests. For strategy-facing changes, include the evidence artifact or command used to validate behavior. ## License -MIT License. See [LICENSE](./LICENSE). +See [LICENSE](LICENSE) if present in this repository. diff --git a/README.zh-CN.md b/README.zh-CN.md index f89cae9..0ac81df 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,107 +1,63 @@ # QuantPlatformKit -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 - - -## English summary - -- Full English version: [`README.md`](README.md). This summary keeps an English entry point in the Chinese file. -- Purpose: this document covers `QuantPlatformKit` for `QuantPlatformKit`. -- Main topics: `这个仓库是什么`, `和其他仓库如何协作`, `策略插件`, `目录结构`, `开发`. -- Read the boundaries, inputs, outputs, and permission requirements before running commands, CI jobs, dry-runs, releases, or runtime switches. -- For live trading, secrets, Cloud Run, exchange, or broker API changes, validate in test or dry-run mode first and do not change production only from examples. -- If this summary differs from the detailed Chinese body, follow the concrete commands, configuration keys, and constraints in the body. +[English README](README.md) -`QuantPlatformKit` 是 QuantStrategyLab 的共享平台契约、券商适配工具、策略插件 helper 和通知基础能力仓库。 - -[English](./README.md) +> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 -## 这个仓库是什么 +## 这个项目做什么 -这是一个公开的共享平台层仓库。它负责稳定跨仓库接口，让策略仓库和券商平台仓库可以各自演进，而不需要复制运行时胶水代码。 +QuantPlatformKit 是 QuantStrategyLab 体系中的**共享平台库**。提供 QuantStrategyLab 平台共用的券商适配器、运行时契约、策略加载接口和通知工具。 -这个仓库包含： +## 适合谁使用 -- 通用领域模型和运行目标 helper -- 市场数据、持仓快照、订单执行、通知、状态存储等窄接口 -- 可复用的券商适配工具 -- 面向混合托管/自托管运行时的 QuantConnect Cloud 部署 helper -- 策略加载、策略插件、告警消息契约 -- 可选的策略插件 email、SMS、push 和 Telegram 告警通道 -- 使用合成数据的公开测试 +- 希望阅读、复现或扩展 QuantStrategyLab 相关模块的工程师和研究人员。 +- 在阅读详细 runbook 或 workflow 前，需要先理解项目入口的运维人员。 +- 在启用自动化前，需要确认项目职责、安全边界和证据要求的 reviewer。 -它不包含私有运行时接线和生成的策略输出。 +## 当前状态 -## 和其他仓库如何协作 +共享库；除非有协同迁移计划，否则改动应保持向后兼容。 -QuantStrategyLab 的仓库按职责拆分： +## 仓库结构 -- 策略仓库负责策略 metadata、输入需求，以及 `manifest + evaluate(ctx)` 入口。 -- 平台仓库负责券商 session、运行时配置加载、运行入口、决策映射和下单。 -- 快照或数据流水线仓库负责生成 artifact 以及发布流程。 -- `QuantPlatformKit` 负责这些仓库共同使用的契约和 helper API。 +- `src/`：主要库代码和运行时代码。 +- `tests/`：单元测试和契约测试。 +- `docs/`：详细设计说明、运行手册和证据文档。 +- `.github/workflows/`：CI、定时任务和部署 workflow。 -典型工作流是： +## 快速开始 -```text -平台仓库 - 从券商/运行时输入构造 StrategyContext - 从策略仓库加载策略入口 - 得到 StrategyDecision - 映射为券商专属执行和通知 +从全新 clone 开始： -QuantPlatformKit - 提供共享契约、加载器、适配器和插件告警 helper +```bash +python -m pip install -e . +python -m pytest -q ``` -策略代码不按券商平台分支；平台代码不复制策略规则。 +如果命令需要凭据，请先阅读相关 workflow 或 runbook，并把密钥配置在 Git 之外。 -## 策略插件 +## 部署和运行 -策略插件是平台仓库按需读取的 sidecar artifact。这个仓库只定义公开插件契约、兼容性校验、告警消息构造、可选告警发送 helper 和重复告警抑制 helper。 +由各执行平台安装使用。本库变更了契约、适配器或通知行为后，应同步运行平台侧测试。 -生成的插件 artifact 和平台专属通知路由由生成它的 pipeline 或消费它的平台仓库管理。这个仓库的测试只使用合成价格历史和合成 payload。 +建议先手工运行或 dry-run。只有在日志、产物、权限和回滚步骤都检查过之后，才启用定时任务或 live 执行。 -插件 artifact 可以携带展示层 `strategy_plugin_messages.v1` 和 -`strategy_plugin_log.v1` 中英文通知 / 日志文案。平台 renderer 可以使用这些文案，但策略和平台逻辑应继续依赖 `canonical_route`、`suggested_action`、`reason_codes`、`position_control` 等机器字段。 -通用通知 artifact 通过 `notification_targets` 加载，不再通过 synthetic strategy -挂载；它们可以触发告警，但永远不会把仓位控制附加到策略 runtime。 +## 策略表现与证据边界 -插件告警发送在平台边界保持 provider-neutral。平台仓库只把 runtime settings 传入 `publish_strategy_plugin_alerts`；这个仓库负责按配置发送 `email`、`sms`、`push` 和 `telegram`，不让插件逻辑耦合某个券商平台。 +这不是策略仓库。它服务于执行可靠性；策略表现应在策略仓库和快照仓库中评估。 -## 目录结构 +README 不应该承诺固定收益或过期指标。实际使用前，请重新运行对应测试、回测或流水线任务。 -```text -src/quant_platform_kit/ - common/ - ibkr/ - binance/ - schwab/ - longbridge/ - quantconnect/ - notifications/ -tests/ -``` +## 安全注意事项 -公开的 QuantConnect 连接器契约和仅含占位符的示例见 [docs/quantconnect.md](./docs/quantconnect.md)。 -策略插件运行时契约见 -[docs/strategy_plugin_runtime_contract.zh-CN.md](./docs/strategy_plugin_runtime_contract.zh-CN.md)， -英文版见 [docs/strategy_plugin_runtime_contract.md](./docs/strategy_plugin_runtime_contract.md)。 +- 不要把 API key、券商凭据、OAuth token、Cookie 或账户标识提交到 Git。 +- 新策略或平台变更在 live 前必须先跑 dry-run 或 paper 流程。 +- 启用定时任务前，需要人工检查生成的订单、产物和日志。 -## 开发 +## 参与贡献 -运行公开测试： - -```bash -PYTHONPATH=src pytest -``` - -运行 lint： - -```bash -PYTHONPATH=src ruff check . -``` +请保持改动小、可复现，并用最小必要测试覆盖。涉及策略的改动，需要附上验证行为的证据产物或命令。 -## License +## 许可证 -MIT License. 见 [LICENSE](./LICENSE)。 +如仓库包含 [LICENSE](LICENSE)，请以该文件为准。