Skip to content

docs: split bilingual open-source readmes #81

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Pigbibi merged 1 commit into from
Jun 3, 2026
Merged

docs: split bilingual open-source readmes #81

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 33 additions & 112 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,142 +1,63 @@
# QuantPlatformKit

<!-- qsl-doc-overview:start -->
[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

<!-- qsl-doc-overview:end -->
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.
114 changes: 35 additions & 79 deletions README.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)，请以该文件为准。