QuantStrategyLab · Pigbibi · Jun 3, 2026 · Jun 3, 2026
@@ -1,241 +1,63 @@
 # CryptoStrategies
 
-<!-- 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 | strategy package |
-| What it does | Shared crypto strategy implementations and metadata for QuantStrategyLab crypto runtimes. |
-| 中文说明 | 加密资产策略实现与元数据包，供 Binance 等 crypto runtime 加载。 |
-| Current status | Strategy package; execution happens in platform repositories such as BinancePlatform. |
+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.
 
-### 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
 
-Do not deploy from this repo directly. Update downstream runtime configs and run platform dry-runs first.
+Strategy package. Live use requires reproducible research evidence and platform-level risk controls.
 
-### Strategy performance / evidence boundary
+## Repository layout
 
-Performance and backtest evidence should be reviewed in the strategy docs or CryptoSnapshotPipelines artifacts before runtime enablement.
+- `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:
 
-> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。
+```bash
+python -m pip install -e .
+python -m pytest -q
+```
 
-[English](#english) | [中文](#中文)
+If a command requires credentials, run it only after reading the relevant workflow or runbook and configuring secrets outside Git.
 
----
+## Deployment and operation
 
-<a id="english"></a>
-## English
+Install the package into a crypto execution platform, configure runtime settings there, and validate generated targets/orders in dry-run before live execution.
 
-Standalone crypto strategy repository for QuantStrategyLab platforms.
+Prefer manual or dry-run execution first. Enable schedules or live execution only after logs, artifacts, permissions, and rollback steps are reviewed.
 
-This repository owns pure strategy logic and strategy metadata. The downstream execution repo still owns exchange access, market-data fetches, runtime state, circuit breakers, Flexible Earn handling, notifications, and order placement.
+## Strategy performance and evidence
 
-Monthly report review, AI audit, and automated remediation workflows belong to snapshot artifact repositories such as `CryptoSnapshotPipelines`. This repository does not run monthly report audit automation directly.
+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.
 
-Recommended entry docs:
+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.
 
-- `docs/crypto_cross_platform_strategy_spec.md`
-- `docs/crypto_strategy_template.md`
-- `docs/crypto_portability_checklist.md`
+## Safety notes
 
-### Contract boundary
+- 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.
 
-The supported downstream surface is now the manifest-backed unified entrypoint for each live profile.
+## Contributing
 
-- `CryptoStrategies` owns pure decision logic and manifest metadata
-- `BinancePlatform` loads that entrypoint through `QuantPlatformKit`
-- shared outputs stay inside `StrategyDecision`
-- exchange-specific safety checks, order sequencing, and artifact freshness handling stay in the execution repo
-- monthly report audit and remediation workflows stay in snapshot artifact repositories
+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.
 
-Legacy `core` / `rotation` modules may still exist as internal implementation details, but downstream runtimes should not bind to those component names anymore.
+## License
 
-### Strategy index
-
-| Profile | Downstream runtime today | Core idea |
-| --- | --- | --- |
-| `crypto_leader_rotation` | `BinancePlatform` | BTC core budget plus monthly altcoin leader rotation |
-
-These strategies are consumed by platform repositories through `QuantPlatformKit` strategy contracts and component loaders.
-
-### crypto_leader_rotation
-
-**Objective**
-- Keep BTC as the core asset while giving the non-BTC sleeve to a selective trend-following rotation.
-- Avoid holding a broad alt basket all the time; only deploy into names that are strong both absolutely and versus BTC.
-
-**Repository boundary**
-- This repository owns:
-  - BTC target-ratio and base-order budgeting helpers
-  - trend-pool ranking and monthly refresh / lock logic
-  - candidate selection, inverse-vol weighting, and sell-reason rules
-- `BinancePlatform` currently owns:
-  - AHR999 and Z-Score data fetches
-  - DCA buy / trim execution
-  - exchange safety checks, balance handling, and circuit breaker behavior
-  - Flexible Earn subscribe / redeem flow and Telegram notifications
-
-**BTC core budget logic**
-- Target BTC weight grows with equity:
-  - `btc_target_ratio = 0.14 + 0.16 * ln(1 + total_equity / 10000)`
-  - capped at `65%`
-- Base daily BTC order size is:
-  - `max(15 USDT, total_equity × 0.0012)`
-- `compute_allocation_budgets(...)` splits available USDT between:
-  - the trend sleeve (`trend_usdt_pool`)
-  - the BTC accumulation sleeve (`dca_usdt_pool`)
-- This lets the downstream executor size BTC accumulation and trend allocation from one equity-aware budget framework.
-
-**Current live BTC execution rules in BinancePlatform**
-- `AHR999 < 0.45` → buy multiplier `5x`
-- `0.45 <= AHR999 < 0.8` → buy multiplier `2x`
-- `0.8 <= AHR999 < 1.2` → buy multiplier `1x`
-- `AHR999 >= 1.2` → no scheduled BTC buy
-- If `Z-Score > sell_trigger`, the runtime trims BTC.
-- Trim size is currently `10%`, `30%`, or `50%` as the overvaluation rises (`trigger`, `>4`, `>5`).
-
-**Trend-pool construction**
-- The live stack prefers an upstream published monthly pool, but this repository also contains the internal ranking logic used to rebuild or validate that pool.
-- Current live Binance defaults:
-  - pool size `5`
-  - minimum history `365` days
-  - minimum `180d` average quote volume `8,000,000`
-  - existing-pool membership bonus `0.10`
-- Ranking factors include:
-  - trend quality (`price vs SMA20 / 60 / 200`)
-  - persistence
-  - liquidity and liquidity stability
-  - relative strength vs BTC
-  - risk-adjusted momentum
-- The pool score is a weighted sum of normalized ranks, with a small bonus for names already in the previous pool.
-
-**Rotation-entry rules**
-- The BTC regime gate must be on.
-- A candidate must be above `SMA20`, `SMA60`, and `SMA200`.
-- Relative strength vs BTC must be positive.
-- Absolute momentum (`0.5×ROC20 + 0.3×ROC60 + 0.2×ROC120`) must also be positive.
-- The top `2` candidates are selected by relative score.
-- Default weighting is inverse volatility, so lower-vol winners receive slightly more capital.
-
-**Exit and defense rules**
-- A held symbol can be sold for three reasons:
-  - it rotated out of the selected top names
-  - price fell below `SMA60`
-  - price broke the ATR trailing stop: `highest_price - ATR_MULTIPLIER × ATR14`
-- The current live Binance profile uses `ATR_MULTIPLIER = 2.5`.
-- Pool membership is locked by upstream `version` / `as_of_date` state so the live pool does not churn mid-month unless a refresh is intended.
-
----
-
-<a id="中文"></a>
-## 中文
-
-这是 `QuantStrategyLab` 的独立加密货币策略仓。
-
-这个仓库负责纯策略逻辑和策略元数据。下游执行仓库继续负责交易所接入、行情获取、运行时状态、熔断、Flexible Earn、通知和实际下单。
-
-建议先读这些文档：
-
-- `docs/crypto_cross_platform_strategy_spec.zh-CN.md`
-- `docs/crypto_strategy_template.zh-CN.md`
-- `docs/crypto_portability_checklist.zh-CN.md`
-
-### 契约边界
-
-当前正式对下游开放的是每个 live profile 的 manifest 驱动统一 entrypoint。
-
-- `CryptoStrategies` 负责纯决策逻辑和 manifest 元数据
-- `BinancePlatform` 通过 `QuantPlatformKit` 加载这个 entrypoint
-- 共享输出保持在 `StrategyDecision` 契约内
-- 交易所专属安全检查、下单顺序和 artifact 新鲜度校验继续放在执行仓库
-
-旧的 `core` / `rotation` 模块可以继续作为仓库内部实现细节存在，但下游运行时不应再绑定这些组件名。
-
-### 策略索引
-
-| 策略档位 | 当前下游运行仓库 | 核心思路 |
-| --- | --- | --- |
-| `crypto_leader_rotation` | `BinancePlatform` | 以 BTC 为核心仓，再叠加月度山寨币强者轮动 |
-
-这些策略通过 `QuantPlatformKit` 提供的策略契约和组件加载接口，被各个平台仓库引用。
-
-### crypto_leader_rotation
-
-**策略目标**
-- 让 BTC 继续作为核心资产，同时把非 BTC 仓位交给一套有筛选的趋势轮动。
-- 不长期被动持有一篮子山寨币，只把资金部署到绝对趋势和相对 BTC 强度都过关的标的上。
-
-**仓库边界**
-- 这个仓库负责：
-  - BTC 目标仓位和基础下单预算的计算
-  - 趋势池打分、月度刷新和锁定逻辑
-  - 候选币筛选、逆波动率权重、卖出原因判断
-- 当前 `BinancePlatform` 负责：
-  - `AHR999` 和 `Z-Score` 数据获取
-  - BTC 定投 / 分档止盈执行
-  - 交易所安全检查、余额处理和熔断
-  - Flexible Earn 申购 / 赎回，以及 Telegram 通知
-
-**BTC 核心仓预算逻辑**
-- BTC 目标权重会随总权益增长：
-  - `btc_target_ratio = 0.14 + 0.16 * ln(1 + total_equity / 10000)`
-  - 上限 `65%`
-- BTC 每日基础下单额是：
-  - `max(15 USDT, total_equity × 0.0012)`
-- `compute_allocation_budgets(...)` 会把可用 USDT 拆成：
-  - 趋势层预算 `trend_usdt_pool`
-  - BTC 累积预算 `dca_usdt_pool`
-- 这样下游执行层就能在同一个按权益变化的预算框架里，同时管理 BTC 核心仓和趋势层。
-
-**当前 Binance live 执行层里的 BTC 规则**
-- `AHR999 < 0.45` → 买入倍率 `5x`
-- `0.45 <= AHR999 < 0.8` → 买入倍率 `2x`
-- `0.8 <= AHR999 < 1.2` → 买入倍率 `1x`
-- `AHR999 >= 1.2` → 当轮不做计划内 BTC 买入
-- 当 `Z-Score > sell_trigger` 时，运行层会触发 BTC 分档止盈。
-- 当前止盈比例是 `10% / 30% / 50%` 三档，对应高估程度继续抬升（`trigger`、`>4`、`>5`）。
-
-**趋势池构建**
-- live 链路优先消费上游发布的月度池，但这个仓库也保留了内部打分逻辑，用于重建或校验该池。
-- 当前 Binance live 默认参数：
-  - 池大小 `5`
-  - 最少历史数据 `365` 天
-  - `180 日`平均成交额下限 `8,000,000`
-  - 上月已入池标的加分 `0.10`
-- 打分因子包括：
-  - 趋势质量（`price vs SMA20 / 60 / 200`）
-  - 趋势持续性
-  - 流动性和流动性稳定度
-  - 相对 BTC 强度
-  - 风险调整后动量
-- 最终分数是各个归一化 rank 的加权和，再叠加一小段旧池成员加分。
-
-**趋势层入场规则**
-- 必须先满足 BTC 闸门开启。
-- 候选币必须站上 `SMA20`、`SMA60`、`SMA200`。
-- 相对 BTC 强度必须为正。
-- 绝对动量 `0.5×ROC20 + 0.3×ROC60 + 0.2×ROC120` 也必须为正。
-- 按相对得分选出前 `2` 名。
-- 默认用逆波动率分配权重，所以波动更低的赢家会拿到略高一点的资金。
-
-**退出和防守规则**
-- 已持有的币会因为 3 类原因卖出：
-  - 已经轮出当前 Top 名单
-  - 价格跌破 `SMA60`
-  - 价格跌破 ATR 跟踪止损：`highest_price - ATR_MULTIPLIER × ATR14`
-- 当前 Binance live profile 使用 `ATR_MULTIPLIER = 2.5`。
-- 趋势池会按上游 `version / as_of_date` 做锁定，避免在月中因为偶发刷新造成 live 池频繁抖动。
+See [LICENSE](LICENSE) if present in this repository.
@@ -0,0 +1,63 @@
+# CryptoStrategies
+
+[English README](README.md)
+
+> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。
+
+## 这个项目做什么
+
+CryptoStrategies 是 QuantStrategyLab 体系中的**策略包**。提供 QuantStrategyLab 平台共用的加密货币策略实现和执行组件，包括 leader-rotation 模块和加载元数据。
+
+## 适合谁使用
+
+- 希望阅读、复现或扩展 QuantStrategyLab 相关模块的工程师和研究人员。
+- 在阅读详细 runbook 或 workflow 前，需要先理解项目入口的运维人员。
+- 在启用自动化前，需要确认项目职责、安全边界和证据要求的 reviewer。
+
+## 当前状态
+
+策略包。live 使用需要可复现研究证据和平台侧风控。
+
+## 仓库结构
+
+- `src/`：主要库代码和运行时代码。
+- `tests/`：单元测试和契约测试。
+- `docs/`：详细设计说明、运行手册和证据文档。
+- `.github/workflows/`：CI、定时任务和部署 workflow。
+
+## 快速开始
+
+从全新 clone 开始：
+
+```bash
+python -m pip install -e .
+python -m pytest -q
+```
+
+如果命令需要凭据，请先阅读相关 workflow 或 runbook，并把密钥配置在 Git 之外。
+
+## 部署和运行
+
+在加密货币执行平台中安装本包，在平台侧配置运行参数，并先用 dry-run 验证生成的目标和订单。
+
+建议先手工运行或 dry-run。只有在日志、产物、权限和回滚步骤都检查过之后，才启用定时任务或 live 执行。
+
+## 策略表现与证据边界
+
+加密货币策略应通过可复现回测和快照产物，在多种市场环境下评估。考虑回撤和换手成本后无法跑赢基准的策略，应保留为研究策略。
+
+README 不应该承诺固定收益或过期指标。实际使用前，请重新运行对应测试、回测或流水线任务。
+
+## 安全注意事项
+
+- 不要把 API key、券商凭据、OAuth token、Cookie 或账户标识提交到 Git。
+- 新策略或平台变更在 live 前必须先跑 dry-run 或 paper 流程。
+- 启用定时任务前，需要人工检查生成的订单、产物和日志。
+
+## 参与贡献
+
+请保持改动小、可复现，并用最小必要测试覆盖。涉及策略的改动，需要附上验证行为的证据产物或命令。
+
+## 许可证
+
+如仓库包含 [LICENSE](LICENSE)，请以该文件为准。