QuantStrategyLab · Pigbibi · Jun 3, 2026 · Jun 3, 2026
@@ -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).
@@ -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)。