diff --git a/README.md b/README.md index bf3cb72..cf86a87 100644 --- a/README.md +++ b/README.md @@ -2,62 +2,82 @@ [Chinese README](README.zh-CN.md) -> ⚠️ Investing involves risk. This project does not provide investment advice and is for educational and research purposes only. +> Investing involves risk. This project does not provide investment advice and is for education, research, and engineering review only. -## What this project does +## What this repository is -CryptoStrategies is a **Strategy package** in the QuantStrategyLab ecosystem. It contains shared crypto strategy implementations and execution components for QuantStrategyLab platforms, including leader-rotation modules and loader metadata. +CryptoStrategies is the QuantStrategyLab crypto strategy package. It provides shared crypto strategy implementation and runtime metadata for the Binance execution platform. -## Who this is for +It is one layer of a multi-repository system: -- 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. +- **Strategy packages**: hold reusable strategy code, metadata, and runtime entrypoints. +- **Snapshot pipelines**: produce feature snapshots, rankings, backtests, and release evidence. +- **Platform runtimes**: connect strategies to brokers, dry-run checks, notifications, and live deployment controls. +- **Shared infrastructure**: keeps contracts, settings, adapters, plugins, and audit workflows reusable across repositories. -## Current status +This repository owns strategy code and metadata. It does not hold broker credentials, submit orders by itself, or replace the snapshot/backtest evidence required before a profile is enabled for live runtime settings. -Strategy package. Live use requires reproducible research evidence and platform-level risk controls. +## Strategy profiles -## Repository layout +### Direct runtime strategies -- `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. +These profiles can run from market history, portfolio snapshots, or other runtime inputs without a separate feature-snapshot build step. -## Quick start +No direct runtime strategies are exposed from this package. -From a fresh clone: +### Snapshot-backed strategies -```bash -python -m pip install -e . -python -m pytest -q -``` +These profiles depend on artifacts produced by `CryptoSnapshotPipelines` before downstream platforms should use them. + +| Profile | Name | Notes | +| --- | --- | --- | +| `crypto_leader_rotation` | Crypto Leader Rotation | runtime-enabled trend-following rotation fed by CryptoSnapshotPipelines release artifacts. | + +### Research-only candidates + +Research-only profiles may stay in code for reproducibility and future review, but they should not appear in current configurable live profiles. -If a command requires credentials, run it only after reading the relevant workflow or runbook and configuring secrets outside Git. +No direct runtime strategies are exposed from this package. -## Deployment and operation +## How this connects to execution -Install the package into a crypto execution platform, configure runtime settings there, and validate generated targets/orders in dry-run before live execution. +Execution platforms consume this package through strategy loaders and runtime metadata. Current downstream platforms: BinancePlatform. -Prefer manual or dry-run execution first. Enable schedules or live execution only after logs, artifacts, permissions, and rollback steps are reviewed. +Use the platform repositories for broker credentials, dry-run/live switches, order submission, and deployment settings. -## Strategy performance and evidence +## Evidence and live enablement -Evaluate crypto strategies with reproducible backtests and snapshot artifacts across multiple market regimes. Strategies that do not beat their benchmark after drawdown and turnover costs should remain research-only. +Use this README as a map of the project, not as live performance data. Before enabling or changing a live profile, rerun the relevant snapshot/backtest pipeline and review short, medium, and long windows: return, max drawdown, benchmark-relative return, turnover, data freshness, and artifact version. If evidence is stale, incomplete, or the profile is marked research-only, keep it out of live runtime settings. -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. +## Repository layout + +- `src/`: library and runtime code. +- `tests/`: unit, contract, and regression tests. +- `docs/`: runbooks, design notes, evidence, and integration contracts. +- `.github/workflows/`: CI, scheduled jobs, release, or deployment workflows. + +## Quick start + +```bash +python -m pip install -e . +python -m pytest -q +``` -## Safety notes +## Useful docs -- 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. +- [`docs/crypto_cross_platform_strategy_spec.md`](docs/crypto_cross_platform_strategy_spec.md) +- [`docs/crypto_cross_platform_strategy_spec.zh-CN.md`](docs/crypto_cross_platform_strategy_spec.zh-CN.md) +- [`docs/crypto_portability_checklist.md`](docs/crypto_portability_checklist.md) +- [`docs/crypto_portability_checklist.zh-CN.md`](docs/crypto_portability_checklist.zh-CN.md) +- [`docs/crypto_strategy_template.md`](docs/crypto_strategy_template.md) +- [`docs/crypto_strategy_template.zh-CN.md`](docs/crypto_strategy_template.zh-CN.md) -## Contributing +## Safety and contribution notes -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. +- Keep secrets, account identifiers, tokens, cookies, and broker credentials out of Git and logs. +- Prefer small, reviewable changes with tests or reproducible evidence. +- For strategy changes, include the command or artifact used to validate behavior. ## License -See [LICENSE](LICENSE) if present in this repository. +See [LICENSE](LICENSE). diff --git a/README.zh-CN.md b/README.zh-CN.md index 28fd200..783ea28 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -2,62 +2,82 @@ [English README](README.md) -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 +> 投资有风险。本项目不构成投资建议，仅用于学习、研究和工程审阅。 -## 这个项目做什么 +## 这个仓库是什么 -CryptoStrategies 是 QuantStrategyLab 体系中的**策略包**。提供 QuantStrategyLab 平台共用的加密货币策略实现和执行组件，包括 leader-rotation 模块和加载元数据。 +CryptoStrategies 是 QuantStrategyLab 的加密货币策略包。为 Binance 执行平台提供共享加密货币策略实现和运行元数据。 -## 适合谁使用 +它属于一套多仓库量化系统中的一层： -- 希望阅读、复现或扩展 QuantStrategyLab 相关模块的工程师和研究人员。 -- 在阅读详细 runbook 或 workflow 前，需要先理解项目入口的运维人员。 -- 在启用自动化前，需要确认项目职责、安全边界和证据要求的 reviewer。 +- **策略包**：保存可复用策略代码、元数据和运行入口。 +- **Snapshot 流水线**：生成 feature snapshot、ranking、回测和发布证据。 +- **执行平台**：把策略接到券商、dry-run 检查、通知和 live 部署控制。 +- **共享基础设施**：沉淀契约、配置、适配器、插件和审计 workflow，供多仓复用。 -## 当前状态 +本仓库负责策略代码和元数据，不保存券商凭据，不直接提交订单，也不替代 live enable 前需要看的 snapshot 和回测证据。 -策略包。live 使用需要可复现研究证据和平台侧风控。 +## 策略 profile -## 仓库结构 +### 普通 runtime 策略 -- `src/`：主要库代码和运行时代码。 -- `tests/`：单元测试和契约测试。 -- `docs/`：详细设计说明、运行手册和证据文档。 -- `.github/workflows/`：CI、定时任务和部署 workflow。 +这些 profile 可以基于 market history、portfolio snapshot 或其他运行时输入执行，不需要单独先生成 feature snapshot。 -## 快速开始 +本策略包当前不暴露普通 runtime 策略。 -从全新 clone 开始： +### Snapshot-backed 策略 -```bash -python -m pip install -e . -python -m pytest -q -``` +这些 profile 依赖 `CryptoSnapshotPipelines` 生成的 artifact；下游平台使用前，应先确认对应产物已经验证和提升。 + +| Profile | 名称 | 说明 | +| --- | --- | --- | +| `crypto_leader_rotation` | Crypto Leader Rotation | 由 CryptoSnapshotPipelines 发布产物驱动的趋势轮动策略。 | + +### 研究侧候选 + +研究侧 profile 可以保留在代码里用于复现和后续评审，但不应该出现在当前可配置 live profile 中。 -如果命令需要凭据，请先阅读相关 workflow 或 runbook，并把密钥配置在 Git 之外。 +本策略包当前不暴露普通 runtime 策略。 -## 部署和运行 +## 如何接到执行平台 -在加密货币执行平台中安装本包，在平台侧配置运行参数，并先用 dry-run 验证生成的目标和订单。 +执行平台通过 strategy loader 和 runtime metadata 消费本策略包。当前下游平台：BinancePlatform。 -建议先手工运行或 dry-run。只有在日志、产物、权限和回滚步骤都检查过之后，才启用定时任务或 live 执行。 +券商凭据、dry-run/live 开关、订单提交和部署配置都应放在执行平台仓库里，而不是放在策略仓库里。 -## 策略表现与证据边界 +## 策略证据和 live enablement -加密货币策略应通过可复现回测和快照产物，在多种市场环境下评估。考虑回撤和换手成本后无法跑赢基准的策略，应保留为研究策略。 +README 只作为项目地图，不替代最新表现数据。启用或调整 live profile 前，需要重新运行相关 snapshot/backtest pipeline，并分别看短、中、长周期的收益、最大回撤、相对基准收益、换手、数据新鲜度和 artifact 版本。证据过期、不完整，或者 profile 仍标记为 research-only，就不要放进 live runtime settings。 -README 不应该承诺固定收益或过期指标。实际使用前，请重新运行对应测试、回测或流水线任务。 +## 仓库结构 + +- `src/`：库代码和运行时代码。 +- `tests/`：单元测试、契约测试和回归测试。 +- `docs/`：运行手册、设计说明、证据和集成契约。 +- `.github/workflows/`：CI、定时任务、发布或部署 workflow。 + +## 快速开始 + +```bash +python -m pip install -e . +python -m pytest -q +``` -## 安全注意事项 +## 延伸文档 -- 不要把 API key、券商凭据、OAuth token、Cookie 或账户标识提交到 Git。 -- 新策略或平台变更在 live 前必须先跑 dry-run 或 paper 流程。 -- 启用定时任务前，需要人工检查生成的订单、产物和日志。 +- [`docs/crypto_cross_platform_strategy_spec.md`](docs/crypto_cross_platform_strategy_spec.md) +- [`docs/crypto_cross_platform_strategy_spec.zh-CN.md`](docs/crypto_cross_platform_strategy_spec.zh-CN.md) +- [`docs/crypto_portability_checklist.md`](docs/crypto_portability_checklist.md) +- [`docs/crypto_portability_checklist.zh-CN.md`](docs/crypto_portability_checklist.zh-CN.md) +- [`docs/crypto_strategy_template.md`](docs/crypto_strategy_template.md) +- [`docs/crypto_strategy_template.zh-CN.md`](docs/crypto_strategy_template.zh-CN.md) -## 参与贡献 +## 安全和贡献说明 -请保持改动小、可复现，并用最小必要测试覆盖。涉及策略的改动，需要附上验证行为的证据产物或命令。 +- 不要把密钥、账户标识、token、Cookie 或券商凭据提交到 Git，也不要写进日志。 +- 改动尽量小，并配套测试或可复现证据。 +- 涉及策略行为的改动，请附上验证命令或产物路径。 ## 许可证 -如仓库包含 [LICENSE](LICENSE)，请以该文件为准。 +详见 [LICENSE](LICENSE)。