From c8b79f057bba2a848f81f8a23f8011dcdb1d267c Mon Sep 17 00:00:00 2001
From: Pigbibi <20649888+Pigbibi@users.noreply.github.com>
Date: Wed, 3 Jun 2026 17:16:28 +0800
Subject: [PATCH] docs: split bilingual open-source readmes
---
README.md | 521 ++++--------------------------------------------
README.zh-CN.md | 387 ++++-------------------------------
2 files changed, 69 insertions(+), 839 deletions(-)
diff --git a/README.md b/README.md
index 21a5b7b..6135dfc 100644
--- a/README.md
+++ b/README.md
@@ -1,517 +1,64 @@
# BinancePlatform
-
+[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 | execution platform |
-| What it does | Binance execution platform for crypto strategies, with self-hosted workflow orchestration and external strategy loading. |
-| 中文说明 | Binance 加密资产执行平台，负责交易所连接、VPS/工作流编排和策略加载。 |
-| Current status | Execution platform. Exchange API keys and order paths are production-sensitive. |
+BinancePlatform is an **Execution platform** in the QuantStrategyLab ecosystem. It runs QuantStrategyLab crypto strategies against Binance-facing execution workflows, with external strategy loading, broker/runtime adapters, and CI-operated orchestration.
-### 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
-Use dry-run and self-hosted runner checks first; verify API permissions, symbol filters and order sizing before enabling live.
+Production-oriented platform code; run in dry-run or paper mode before enabling real orders.
-### Strategy performance / evidence boundary
+## Repository layout
-Crypto strategy performance is owned by CryptoStrategies/CryptoSnapshotPipelines, not the exchange adapter.
+- `application/`, `entrypoints/`, `infra/`, `reporting/`: Python package code.
+- `tests/`: unit and contract tests.
+- `docs/`: detailed design notes, runbooks, and evidence docs.
+- `.github/workflows/`: CI, scheduled jobs, and deployment workflows.
+- `scripts/`: operator scripts and local helpers.
-> 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
-
-
-> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。
-
-Language: [English](#english) | [简体中文](#中文) | [中文详版](README.zh-CN.md)
-
----
-
-
-## English
-
-Automated crypto quant for Binance spot: BTC DCA core plus altcoin trend rotation. Uses valuation (AHR999, Z-Score) and trend gates (MA200, slope). Compatible with Binance flexible earn (auto redeem/subscribe), USDT buffer, BNB fuel, Telegram alerts, and Firestore state.
-
-**Trend universe source:** Prefer the upstream published pool from CryptoSnapshotPipelines. This repository validates upstream payload freshness and contract shape before using it, keeps a last known good upstream payload in state, and only uses the static fallback in degraded mode.
-
-The current `crypto_leader_rotation` pure strategy modules are sourced from `CryptoStrategies`.
-
-Full strategy documentation now lives in [`CryptoStrategies`](https://github.com/QuantStrategyLab/CryptoStrategies#crypto_leader_rotation). The sections below focus on downstream execution assumptions and runtime behavior.
-
-**Artifact contract:** Local replay and monitoring helpers now follow an explicit strategy artifact contract: runtime payload, Firestore payload, `STRATEGY_ARTIFACT_FILE`, repo-local `artifacts/live_pool_legacy.json`, then compatible fallback candidates. The old `TREND_POOL_*` settings remain compatibility aliases for `crypto_leader_rotation`. A sibling `../CryptoSnapshotPipelines` checkout is only one fallback candidate, not the sole default source; the old `../CryptoLeaderRotation` checkout name remains accepted for compatibility.
-
-**Python runtime:** Prefer Python `3.11`. CI is pinned to 3.11, and local helper commands now prefer `python3.11` when available while still falling back to `python3`.
-
-## Execution Engine Boundary
-
-`BinancePlatform` is the downstream execution engine in this two-repo setup.
-
-Upstream inputs it expects from `CryptoSnapshotPipelines`:
-
-- validated monthly `live_pool.json` / `live_pool_legacy.json`
-- publish metadata such as `as_of_date`, `version`, `mode`, `pool_size`, and `source_project`
-- Firestore summary payloads that carry the same stable contract
-
-Responsibilities owned here:
-
-- upstream artifact freshness, schema, and contract validation
-- degraded-mode fallback ladder and state persistence
-- exchange execution, order safety checks, and balance handling
-- circuit-breaker logic, runtime error handling, and minimal Telegram alerts
-- fixed-input replay and operator smoke checks for the execution path
-
-Non-goals:
-
-- monthly research reporting
-- upstream release review packages or artifact change narratives
-- deep strategy-analysis commentary beyond the execution decision needed for this cycle
-
-The live mainline now stays on one unified path:
-
-- `strategy_runtime.py` loads the manifest-backed strategy entrypoint
-- `strategy_runtime.py` now builds canonical crypto inputs through the strategy runtime adapter
-- `entrypoint.evaluate(ctx)` returns a shared `StrategyDecision`
-- `decision_mapper.py` turns that decision into execution-side BTC and trend plans
-
-Repo-local `strategy_core.py` and `strategy/rotation.py` shims are no longer part of the runtime boundary.
-
-Profile status quick check:
-
-```bash
-python3 scripts/print_strategy_profile_status.py
-python3 scripts/print_strategy_profile_status.py --json
-python3 scripts/print_strategy_switch_env_plan.py --profile crypto_leader_rotation
-python3 scripts/print_strategy_switch_env_plan.py --profile crypto_leader_rotation --json
-```
-
-## Repo Shape
-
-- `main.py` is the live orchestration entrypoint.
-- `strategy_runtime.py` loads the unified strategy entrypoint and explicit artifact contract.
-- `research/` contains optional audit-only backtest tools and is not part of the hourly execution path.
-- `run_*` scripts are local operators' helpers for fixed-input replay and maintenance.
-- `tests/fixtures/` contains fixed inputs used by the replay regression tests.
-
-## Layout
-
-- **main.py** — Live script (run hourly).
-- **strategy_runtime.py** — Unified strategy entrypoint loader and artifact-contract runtime surface.
-- **decision_mapper.py** — Maps shared `StrategyDecision` objects into execution-side allocation and rotation plans.
-- **runtime_support.py** — Runtime/report helpers shared by live execution and dry-run replay.
-- **runtime_config_support.py** — Environment parsing and live-runtime bootstrap helpers so `main.py` can stay orchestration-focused.
-- **market_snapshot_support.py** — Market snapshot assembly helpers used by the live cycle and replay regression tests.
-- **degraded_mode_support.py** — Degraded-mode fallback ladder and trend-pool source state helpers.
-- **live_services.py** — Firestore state and Telegram notification adapters for live operation.
-- **QuantPlatformKit.binance** — Shared Binance client bootstrap, balance helpers, market-data snapshots, and quantity-format helpers.
-- **trend_pool_support.py** — Upstream trend-pool contract parsing, validation, and fallback helpers.
-- **trade_state_support.py** — Trade-state normalization and retired-position tracking helpers.
-- **research/backtest.py** — Optional audit-only backtest / strategy-comparison runner; not part of the live execution contract.
-- **run_cycle_replay.py** — Fixed-input dry-run executor for one full strategy cycle using local fixtures.
-- **requirements.txt** — Human-maintained top-level Python deps.
-- **requirements-lock.txt** — Pinned dependency set used by CI/deploy when present.
-
-Generated local outputs under `reports/` are intentionally not committed. Fixed-input fixtures under `tests/fixtures/` are committed because they are part of the dry-run regression harness.
-
-## Execution Logging
-
-Each hourly run pushes the full execution report JSON to an orphan `logs` branch under `hourly/{YYYY-MM}/{YYYY-MM-DDTHHMM}.json`.
-
-Recurring monthly execution audits are intentionally not part of this downstream execution repo. Runtime problems should be handled incident-first from failed Runtime / CI checks, Telegram alerts, or operator-observed symptoms. Strategy and snapshot review remains upstream in `CryptoSnapshotPipelines`.
-
-`Runtime Heartbeat` (`.github/workflows/runtime-heartbeat.yml`) is the missed-run
-guard for the VPS/self-hosted execution path. It runs on GitHub-hosted runners,
-does not touch Binance, and checks whether the `Runtime` workflow (`main.yml`)
-has completed successfully within the recent lookback window. If the external
-VPS cron stops dispatching `main.yml`, the self-hosted runner is offline, or the
-latest Runtime run failed, it sends Telegram through `TG_TOKEN` and
-`GLOBAL_TELEGRAM_CHAT_ID`.
-
-### Workflows
-
-| Workflow | File | Trigger | Runner |
-|----------|------|---------|--------|
-| Runtime | `main.yml` | `workflow_dispatch` | self-hosted |
-| CI | `ci.yml` | push to main | ubuntu-latest |
-
-### Required Secrets
-
-| Secret | Used by |
-|--------|---------|
-| `BINANCE_API_KEY` | Runtime |
-| `BINANCE_API_SECRET` | Runtime |
-| `TG_TOKEN` | Runtime |
-
-## Strategy Overview
-
-- **BTC core:** Valuation-based DCA (AHR999) and scaled take-profit (Z-Score vs dynamic threshold). Target weight grows with equity.
-- **Trend layer:** Monthly refreshed pool (upstream or internal fallback logic), then Top 2 by relative-BTC strength, inverse-vol weighted. Only active when BTC gate is on.
-
-Runs hourly; signals are daily trend and risk, not high-frequency.
-
-## BTC Core
-
-**Indicators:** MA200, MA200 slope, AHR999, Z-Score, dynamic Z-Score sell threshold.
-
-**Logic:** Stronger DCA when AHR999 low; normal when neutral; scaled sells when Z-Score above threshold. Higher Z-Score → larger sell fraction.
-
-**Target weight:** `btc_target_ratio = 0.14 + 0.16 * ln(1 + total_equity / 10000)`, capped. Larger equity → more BTC, less trend.
-
-**DCA size:** Daily base order scales with total equity.
-
-## Trend Rotation
-
-**Universe:** Prefer the upstream live pool. Source hierarchy is: fresh upstream Firestore payload → last known good upstream payload from state → validated local upstream file fallback → static universe emergency fallback.
-
-**Official input pool:** Upstream publishes a 5-coin production pool; this repo consumes that pool as the monthly official input set.
-
-**Actual rotation target:** The live trend sleeve still acts only on the final top-2 rotation decision, or on a defensive "no candidate / keep current stance" outcome when no symbol qualifies.
-
-**Factors:** SMA20/60/200, 20/60/120d returns, 20d vol, ATR14, 30/90/180d avg quote volume, trend persistence, relative BTC strength, risk-adjusted momentum.
-
-**Holdings:** Top 2 from pool by relative-BTC score; inverse-vol weights.
-
-**Entry:** BTC gate on; price above SMA20/60/200; positive relative-BTC score; positive absolute momentum.
-
-**Exit:** Below SMA60; ATR trailing stop; rotated out of Top 2.
-
-## Risk
-
-- **BTC gate:** Trend layer only when `BTC price > MA200` and `MA200 slope > 0`.
-- **Circuit breaker:** If trend-layer daily PnL ≤ threshold, flatten trend book; BTC core unchanged. (Daily PnL is computed from real trend holdings value only, excluding the allocated USDT cash pool.)
-- **External USDT flows:** Manual USDT deposits or withdrawals reset the daily PnL bases instead of being treated as a loss event. Flexible Earn subscribe or redeem does not trigger this reset because the runtime tracks total USDT rather than spot-only USDT.
-- **BNB:** Auto top-up for fees; not in trend rotation.
-
-## Earn Compatibility
-
-- Check spot before orders; redeem from flexible earn if needed.
-- Maintain USDT spot buffer (subscribe excess, redeem shortfall).
-- Flexible Earn subscribe or redeem moves USDT between spot and earn only; it does not count as an external balance shock and does not trigger the circuit breaker.
-
-## State (Firestore)
-
-- Trend positions, high-water prices, circuit state, DCA last buy/sell date, monthly pool id, pool symbols. Retired symbols (dropped from pool but still held) tracked until closed.
-
-## Upstream Pool
-
-**Default:** CryptoSnapshotPipelines monthly output.
-
-1. Firestore `strategy` / `CRYPTO_LEADER_ROTATION_LIVE_POOL` (override: `STRATEGY_ARTIFACT_FIRESTORE_COLLECTION`, `STRATEGY_ARTIFACT_FIRESTORE_DOCUMENT`; legacy aliases: `TREND_POOL_FIRESTORE_COLLECTION`, `TREND_POOL_FIRESTORE_DOCUMENT`).
-2. Last known good upstream payload persisted in Firestore state after a successful accepted upstream read.
-3. Local `live_pool_legacy.json` or `live_pool.json` style file (override: `STRATEGY_ARTIFACT_FILE`; legacy alias: `TREND_POOL_FILE`).
-4. Static `TREND_UNIVERSE` as emergency fallback only.
-
-**Stable upstream contract fields:**
-
-- `as_of_date`
-- `version`
-- `mode`
-- `pool_size`
-- `symbols`
-- `symbol_map`
-- `source_project`
-
-**Accepted legacy-compatible format (`live_pool_legacy.json`):**
-
-```json
-{
- "as_of_date": "2026-03-13",
- "version": "2026-03-13-core_major",
- "mode": "core_major",
- "pool_size": 5,
- "symbols": {
- "TRXUSDT": {"base_asset": "TRX"},
- "ETHUSDT": {"base_asset": "ETH"},
- "BCHUSDT": {"base_asset": "BCH"},
- "NEARUSDT": {"base_asset": "NEAR"},
- "LTCUSDT": {"base_asset": "LTC"}
- },
- "symbol_map": {
- "TRXUSDT": {"base_asset": "TRX"},
- "ETHUSDT": {"base_asset": "ETH"},
- "BCHUSDT": {"base_asset": "BCH"},
- "NEARUSDT": {"base_asset": "NEAR"},
- "LTCUSDT": {"base_asset": "LTC"}
- },
- "source_project": "crypto-leader-rotation"
-}
-```
-
-In runtime output, keep these layers separate:
-
-- upstream official pool: the monthly symbols accepted from the upstream contract
-- current monthly execution pool: the local pool retained for this upstream release before final buy gating
-- current execution targets: the symbols that actually qualify for this cycle
-- degraded source status: whether the cycle is using fresh upstream, last-known-good, local-file, or static fallback
-
-The monthly execution pool is rebuilt when the accepted upstream `version` / `as_of_date` changes, then reused across cycles until the next accepted upstream release.
-
-**Validation and degraded mode:**
-
-- Upstream payloads must have a non-empty symbol set, a parseable `as_of_date`, and an acceptable `mode`.
-- Freshness is validated with `STRATEGY_ARTIFACT_MAX_AGE_DAYS` against the upstream `as_of_date`; `TREND_POOL_MAX_AGE_DAYS` remains a compatibility alias.
-- If the fresh upstream payload is stale or malformed, the runtime does not silently treat weaker fallbacks as equivalent.
-- In degraded mode, the script prefers the last known good upstream payload, then a validated local file fallback, and pauses new trend buys by default unless `STRATEGY_ARTIFACT_ALLOW_NEW_ENTRIES_ON_DEGRADED=1` or the legacy alias `TREND_POOL_ALLOW_NEW_ENTRIES_ON_DEGRADED=1`.
-- Retired symbols stay in state until sold; active pool changes are source-tagged in state for auditability.
-
-## Environment
-
-Required:
-
-| Variable | Description |
-|----------|-------------|
-| `BINANCE_API_KEY` | Binance API key |
-| `BINANCE_API_SECRET` | Binance API secret |
-| `TG_TOKEN` | Telegram bot token |
-| `GLOBAL_TELEGRAM_CHAT_ID` | Telegram chat ID for alerts. |
-| `GOOGLE_APPLICATION_CREDENTIALS` | Path to GCP credentials for local runs (the GitHub runtime workflow now gets credentials from OIDC automatically) |
-
-Across multiple quant repositories, `GLOBAL_TELEGRAM_CHAT_ID` and `NOTIFY_LANG` are reasonable shared settings. `TG_TOKEN`, Binance API keys, and GCP credential material should stay repository-specific.
-
-Optional:
-
-| Variable | Description |
-|----------|-------------|
-| `STRATEGY_PROFILE` | Strategy profile selector (default: `crypto_leader_rotation`; supported value: `crypto_leader_rotation`) |
-| `STRATEGY_ARTIFACT_FILE` | Local live-pool artifact path; legacy alias: `TREND_POOL_FILE` |
-| `STRATEGY_ARTIFACT_MANIFEST_FILE` | Optional local artifact manifest path for operator tooling |
-| `STRATEGY_ARTIFACT_FIRESTORE_COLLECTION` | Firestore collection for the live artifact (default `strategy`; legacy alias: `TREND_POOL_FIRESTORE_COLLECTION`) |
-| `STRATEGY_ARTIFACT_FIRESTORE_DOCUMENT` | Firestore document for the live artifact (default `CRYPTO_LEADER_ROTATION_LIVE_POOL`; legacy alias: `TREND_POOL_FIRESTORE_DOCUMENT`) |
-| `STRATEGY_ARTIFACT_MAX_AGE_DAYS` | Max allowed upstream `as_of_date` age before payload is stale (default `45`; legacy alias: `TREND_POOL_MAX_AGE_DAYS`) |
-| `STRATEGY_ARTIFACT_ACCEPTABLE_MODES` | Comma-separated acceptable upstream modes (default `core_major`; legacy alias: `TREND_POOL_ACCEPTABLE_MODES`) |
-| `STRATEGY_ARTIFACT_EXPECTED_SIZE` | Expected live-pool size for contract checks (default `5`; legacy alias: `TREND_POOL_EXPECTED_SIZE`) |
-| `STRATEGY_ARTIFACT_ALLOW_NEW_ENTRIES_ON_DEGRADED` | Allow trend buys while using last-known-good or fallback sources (default `false`; legacy alias: `TREND_POOL_ALLOW_NEW_ENTRIES_ON_DEGRADED`) |
-| `BTC_STATUS_REPORT_INTERVAL_HOURS` | Interval for BTC status report (default `24`) |
-| `NOTIFY_LANG` | Log and notification language: `en` (English, default) or `zh` (Chinese) |
-
----
-
-
-## 中文
-
-这是一个运行在 Binance 现货上的自动化量化仓库，核心由两部分组成：
-
-- BTC 核心仓定投与分档止盈
-- 山寨币趋势轮动层
-
-项目使用估值指标（`AHR999`、`Z-Score`）和趋势闸门（`MA200`、均线斜率），并兼容 Binance Flexible Earn、USDT 缓冲、BNB 手续费仓、Telegram 通知和 Firestore 状态存储。
-
-当前 `crypto_leader_rotation` 的纯策略模块来自 `CryptoStrategies`。
-
-完整策略说明现在放在 [`CryptoStrategies`](https://github.com/QuantStrategyLab/CryptoStrategies#crypto_leader_rotation)。下面这些章节主要保留下游执行侧的约束、运行时行为和运维说明。
-
-### 执行边界
-
-`BinancePlatform` 负责：
-
-- 上游月池 payload 校验和降级逻辑
-- 交易执行、安全检查和余额处理
-- 运行时状态、Telegram 通知和回放工具
-
-它不负责：
-
-- 上游月度研究和发布说明
-- 超出执行所需范围的深度策略分析
-
-### 仓库结构
-
-- `main.py`：小时级 live 编排入口
-- `strategy_runtime.py`：加载统一策略入口，并暴露显式 artifact contract 运行时信息
-- `research/`：研究和审计工具，不参与 live 执行
-- `run_*`：本地固定输入回放和维护脚本
-- `tests/fixtures/`：回放回归的固定输入
-
-### 运行环境
-
-必需环境变量：
-
-- `BINANCE_API_KEY`
-- `BINANCE_API_SECRET`
-- `TG_TOKEN`
-- `GLOBAL_TELEGRAM_CHAT_ID`
-- `GOOGLE_APPLICATION_CREDENTIALS`
-
-可选环境变量、趋势池契约、日志和月度审阅的完整中文说明，见 [README.zh-CN.md](README.zh-CN.md)。
-
-## Notification Format
-
-Runtime logs and Telegram notifications use the same language switch. Set `NOTIFY_LANG=zh` for Chinese or leave default for English.
-
-`STRATEGY_PROFILE` is now kept as a thin future strategy-switch entry. Today this repo only supports `crypto_leader_rotation`, and its current strategy domain is `crypto`.
-
-**Strategy heartbeat:**
-```
-💓 【Strategy Heartbeat】
-🕐 UTC Time: 2026-03-24 00:00
-━━━━━━━━━━━━━━━━━━
-💰 Total Equity: $12,500.00
-📈 Trend Holdings: $3,200.00 (1.25%)
-₿ BTC Price: $87,000.00
-━━━━━━━━━━━━━━━━━━
-AHR999: 0.850
-Z-Score: 1.20 / Threshold 3.00
-🎯 BTC Target Allocation: 28.5%
-🚦 BTC Gate: ON
-━━━━━━━━━━━━━━━━━━
-💡 Note: BTC valuation is neutral; follow the system cadence.
-```
-
-**Trade notifications:**
-```
-✅ 【Trend Buy】 ETHUSDT
-Price: $3,450.00
-Budget: $800.00
-Rotation Weight: 60%
-Relative BTC Score: 0.85
-
-📉 【Trend Sell】 SOLUSDT
-Reason: ATR trailing stop ($142.50)
-Price: $138.20
-
-🛡️ 【BTC DCA Buy】 BTC
-AHR999: 0.45
-Target Allocation: 28.5%
-Quantity: 0.00125 BTC
-```
-
-## Deploy (self-hosted runner + workflow)
-
-The repo is intended to run on a **self-hosted GitHub Actions runner** (e.g. a VPS). The runtime workflow checks out code, authenticates to Google Cloud with GitHub OIDC + Workload Identity Federation, prepares dependencies, and then runs `main.py`. The runner is expected to receive `workflow_dispatch` requests from one external scheduler instead of relying on GitHub's built-in hourly scheduler.
-
-This repository uses `QuantPlatformKit` for Binance client bootstrap, balance helpers, market-data snapshots, and quantity-format helpers. The runner executes this repository directly; `QuantPlatformKit` is not deployed separately.
-
-### 1. Self-hosted runner
-
-- In the repo: **Settings → Actions → Runners**, add a new self-hosted runner (Linux recommended).
-- On the machine (e.g. Oracle Cloud VPS): install the runner, register it, and keep it running so it can pick up jobs.
-
-### 2. Workflow and runtime trigger
-
-- **`.github/workflows/ci.yml`** is the push/manual validation workflow. It runs on GitHub-hosted runners and is limited to install/compile/test checks.
-- **`.github/workflows/main.yml`** is the runtime workflow. It runs on the self-hosted runner, authenticates to Google Cloud with OIDC, prepares the local `venv`, and runs `venv/bin/python main.py`.
-- **`.github/workflows/runtime-heartbeat.yml`** is the GitHub-hosted heartbeat. It checks recent `main.yml` success and alerts on missed or failed Runtime runs.
-- **Triggers:** `ci.yml` runs on `push` to `main` and `workflow_dispatch`; `main.yml` runs on `workflow_dispatch` only.
-- **Runtime cadence:** GitHub Actions no longer schedules hourly runtime execution for this repo. The expected production model is one external scheduler, such as VPS cron + `curl`, calling the GitHub `workflow_dispatch` API for `main.yml`.
-- Use `Actions -> Runtime -> Run workflow` for one-off manual runs.
-- For a safe self-hosted auth smoke test, dispatch `main.yml` with `validate_only=true`. That validates GitHub OIDC + Firestore access without running live trades.
-- If you automate dispatch from a VPS, keep a single scheduler of record and avoid firing a new dispatch while the previous runtime job is still running.
-- Recommended runtime service name on the VPS side: `binance-quant`.
-- For the shared deployment model and naming rules across Cloud Run and VPS workloads, see [`QuantPlatformKit/docs/deployment_model.md`](../QuantPlatformKit/docs/deployment_model.md).
-
-Example API dispatch:
+From a fresh clone:
```bash
-curl -L \
- -X POST \
- -H "Accept: application/vnd.github+json" \
- -H "Authorization: Bearer $GITHUB_TOKEN" \
- https://api.github.com/repos///actions/workflows/main.yml/dispatches \
- -d '{"ref":"main"}'
+python -m pip install -r requirements.txt
+python -m pytest -q
```
-### 3. Repository secrets
+If a command requires credentials, run it only after reading the relevant workflow or runbook and configuring secrets outside Git.
-In **Settings → Secrets and variables → Actions**, add:
+## Deployment and operation
-| Secret | Description |
-|--------|-------------|
-| `BINANCE_API_KEY` | Binance API key |
-| `BINANCE_API_SECRET` | Binance API secret |
-| `TG_TOKEN` | Telegram bot token |
-| `GLOBAL_TELEGRAM_CHAT_ID` | Telegram chat ID for alerts. |
+Configure GitHub Actions secrets/variables for Binance credentials, runtime settings, notifications, and strategy source. Run the workflow manually in dry-run mode first, review logs/artifacts, then enable the scheduled workflow only after credentials and risk controls are verified.
-The runtime workflow passes these into the `Run trading strategy` step; it does not use a `.env` file on the runner.
+Prefer manual or dry-run execution first. Enable schedules or live execution only after logs, artifacts, permissions, and rollback steps are reviewed.
-It now also requires these repo or organization Variables:
-
-- `GLOBAL_TELEGRAM_CHAT_ID` from repo/org Variables
-- `NOTIFY_LANG` from repo/org Variables
-
-`TG_TOKEN` and Binance API keys should still remain repository-specific. Google Cloud auth for the runtime workflow now uses GitHub OIDC instead of a repository JSON key.
-
-### 4. GCP / Firestore
-
-- The GitHub runtime workflow now uses GitHub OIDC + Workload Identity Federation to impersonate `binance-platform-runtime@binancequant.iam.gserviceaccount.com`.
-- That runtime service account must have **Firestore** access (read/write) for the project that hosts the Firestore database used by this app.
-
-### Local run (optional)
-
-For local testing only:
-
-```bash
-cd /path/to/BinancePlatform
-python3 -m venv venv && source venv/bin/activate
-REQ_FILE="requirements-lock.txt"
-if [ ! -f "$REQ_FILE" ]; then REQ_FILE="requirements.txt"; fi
-pip install -r "$REQ_FILE"
-export BINANCE_API_KEY=... BINANCE_API_SECRET=... TG_TOKEN=... GLOBAL_TELEGRAM_CHAT_ID=...
-export GOOGLE_APPLICATION_CREDENTIALS=/path/to/gcp-sa.json
-python main.py
-```
-
-### Local research backtest
-
-For audit-only local research work outside the live execution path:
-
-```bash
-python3 -m research.backtest
-```
-
-### Fixed-input cycle replay
-
-To execute one fully dry-run strategy cycle from local fixtures, without live Binance or Firestore writes:
-
-```bash
-python3 run_cycle_replay.py --run-id local-check
-```
-
-This emits a structured JSON report with:
-
-- selected upstream pool and execution candidates
-- trend buy/sell intents
-- BTC DCA intents
-- earn subscribe/redeem intents
-- explicit gating / no-trade reason counts
-- zero-trade diagnostics grouped by strategy sleeve and gate
-- suppressed vs executed side-effect counts
-
-### Tests
-
-Committed unit tests can be run with:
-
-```bash
-python3 -m unittest \
- tests.test_strategy_core \
- tests.test_cycle_replay_runtime \
- tests.test_market_snapshot_support \
- tests.test_trend_pool_loading \
- -v
-```
+## Strategy performance and evidence
-Repository hygiene:
+This repository does not rank strategies. Strategy return, drawdown, and live eligibility must come from the strategy repositories and their snapshot/backtest artifacts before this platform is allowed to place orders.
-- ignore local/runtime artifacts such as `reports/`, `venv/`, `.venv/`, `gcp-key.json`, and `.venv_requirements_hash`
-- keep `tests/fixtures/` tracked so the cycle replay stays reproducible across machines
+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.
-Operational behavior for degraded mode, Firestore failures, Binance API failures, Telegram failures, and workflow secret handling is documented in `docs/operator_runbook.md`.
+## Safety notes
-## Notes
+- 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 upstream CryptoSnapshotPipelines project is the primary selector and contract owner for the monthly live pool.
-- Local stable-quality pool ranking logic in this repo remains as a runtime fallback and execution convenience, not the preferred healthy input.
-- Monthly research reporting, shadow candidate evaluation, and monthly release review should live in the upstream CryptoSnapshotPipelines project, not in this downstream execution repo.
+## Contributing
-## Telegram
+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.
-Alerts: trend buys/sells, BTC DCA, earn redeems, circuit breaker, errors. Optional periodic BTC status (AHR999, Z-Score, gate, trend PnL). Default once per day at UTC 00:00; set `BTC_STATUS_REPORT_INTERVAL_HOURS` to change.
+## License
-All notifications support `NOTIFY_LANG` (`en` default, `zh` for Chinese). See [Notification Format](#notification-format) for examples.
+See [LICENSE](LICENSE) if present in this repository.
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 7b85847..7ced498 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,381 +1,64 @@
# BinancePlatform
-> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。
-
-
-## English summary
-
-- Full English version: [`README.md`](README.md). This summary keeps an English entry point in the Chinese file.
-- Purpose: this document covers `BinancePlatform` for `BinancePlatform`.
-- Main topics: `仓库形态`, `文件说明`, `执行日志`, `工作流`, `所需 Secrets`.
-- 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.md) | 简体中文
-
-这是一个运行在 Binance 现货上的自动化量化项目，核心由两部分组成：
-
-- BTC 核心仓定投与分档止盈
-- 山寨币趋势轮动层
-
-项目使用估值指标（`AHR999`、`Z-Score`）和趋势闸门（`MA200`、均线斜率），并兼容 Binance Flexible Earn、USDT 现货缓冲、BNB 手续费燃料仓、Telegram 通知和 Firestore 状态存储。
-
-**趋势池来源：** 优先消费上游 `CryptoSnapshotPipelines` 发布的月度 live pool。本仓库会先校验上游 payload 的新鲜度和契约字段，再决定是否采用；同时会把成功接受过的上游 payload 作为 last known good 保存在状态中；只有前面几层都不可用时才会退化到本地静态 fallback。
-
-当前 `crypto_leader_rotation` 的纯策略模块来自 `CryptoStrategies`。
-
-完整策略说明现在放在 [`CryptoStrategies`](https://github.com/QuantStrategyLab/CryptoStrategies#crypto_leader_rotation)。下面这些章节主要保留下游执行侧的约束、运行时行为和运维说明。
-
-**artifact contract：** 本地 replay、monitor 和 review 工具现在按显式 strategy artifact contract 取数：runtime 注入 payload、Firestore payload、`STRATEGY_ARTIFACT_FILE`、仓库内 `artifacts/live_pool_legacy.json`，最后才是兼容 fallback 候选。旧的 `TREND_POOL_*` 仍作为 `crypto_leader_rotation` 的兼容别名。`../CryptoSnapshotPipelines` 只是不保证存在的候选之一，不再是默认唯一来源；旧的 `../CryptoLeaderRotation` checkout 名称仍保留兼容。
-
-**Python 版本：** 推荐 `Python 3.11`。CI 固定在 `3.11`，本地辅助命令会优先使用 `python3.11`，没有时回退到 `python3`。
-
-**执行边界：** 当前 live 主线已经统一为 `strategy_runtime.py -> entrypoint.evaluate(ctx) -> decision_mapper.py`。仓库内原先的 `strategy_core.py` 和 `strategy/rotation.py` shim 已不再属于运行时边界。
-
-## 仓库形态
-
-- `main.py` 是 live 交易编排入口。
-- `strategy_runtime.py` 负责加载统一策略入口，并暴露显式 artifact contract 运行时信息。
-- `research/` 放研究、审计和历史分析工具。
-- 各种 `run_*` 脚本用于本地固定输入回放和维护辅助。
-- `tests/fixtures/` 放固定输入，用于 dry-run replay 回归测试。
-
-## 文件说明
-
-- **main.py** — live 主脚本，按小时运行。
-- **strategy_runtime.py** — 统一策略入口加载器，并暴露 artifact contract 相关运行时接口。
-- **decision_mapper.py** — 把共享 `StrategyDecision` 映射成执行侧需要的 allocation / rotation plan。
-- **runtime_support.py** — live / dry-run 共用的运行时和执行报告辅助。
-- **live_services.py** — Firestore 状态和 Telegram 通知适配层。
-- **QuantPlatformKit.binance** — 复用 Binance 客户端初始化、余额辅助、行情快照和下单数量格式化。
-- **trend_pool_support.py** — 上游趋势池 payload 解析、校验和 fallback 辅助。
-- **trade_state_support.py** — 持仓状态标准化、退役仓位跟踪、重复动作保护。
-- **research/backtest.py** — 研究和审计用回测，不参与 live 小时执行。
-- **run_cycle_replay.py** — 用固定 fixtures 执行单轮 dry-run。
-- **requirements.txt** — 人工维护的顶层依赖。
-- **requirements-lock.txt** — CI / deploy 优先使用的锁定依赖版本。
-
-`reports/` 下的本地生成物默认不提交。`tests/fixtures/` 会提交，因为它们属于可复现回归测试的一部分。
-
-## 执行日志
-
-每次小时运行后，完整的执行报告 JSON 会推送到 orphan `logs` 分支，路径为 `hourly/{YYYY-MM}/{YYYY-MM-DDTHHMM}.json`。
-
-下游执行仓库不再保留周期性月度执行审计。运行问题按 incident-first 方式处理：Runtime / CI 失败、Telegram 告警或操作员观察到异常后再主动修复。策略和 snapshot 审阅留在上游 `CryptoSnapshotPipelines`。
-
-`Runtime Heartbeat`（`.github/workflows/runtime-heartbeat.yml`）是 VPS /
-self-hosted 执行链路的漏跑保护。它跑在 GitHub-hosted runner 上，不连接 Binance，
-只检查 `Runtime` workflow（`main.yml`）在最近窗口内是否成功完成。如果 VPS cron 不再
-dispatch、self-hosted runner 离线，或最新 Runtime run 失败，它会通过 `TG_TOKEN` 和
-`GLOBAL_TELEGRAM_CHAT_ID` 发 Telegram。
-
-### 工作流
-
-| 工作流 | 文件 | 触发方式 | 运行器 |
-|--------|------|---------|--------|
-| 运行时 | `main.yml` | `workflow_dispatch` | self-hosted |
-| CI | `ci.yml` | 推送到 main | ubuntu-latest |
-
-### 所需 Secrets
-
-| Secret | 使用者 |
-|--------|--------|
-| `BINANCE_API_KEY` | 运行时 |
-| `BINANCE_API_SECRET` | 运行时 |
-| `TG_TOKEN` | 运行时 |
-
-## 策略概览
-
-- **BTC 核心层：** 依据估值做定投（`AHR999`）和分档止盈（`Z-Score` 对动态阈值），目标仓位随总权益增长而提高。
-- **趋势层：** 月度刷新候选池（优先上游 live pool，其次内部稳定质量排序 fallback），从中选出相对 BTC 最强的 Top 2，并按逆波动率分配权重。只有在 BTC 闸门开启时才允许趋势层工作。
-
-系统按小时运行，但信号逻辑本身仍然是日频趋势和风险管理，不是高频交易。
-
-## BTC 核心层
-
-**指标：** `MA200`、`MA200 slope`、`AHR999`、`Z-Score`、动态 `Z-Score` 止盈阈值。
-
-**逻辑：**
-
-- `AHR999` 越低，定投力度越强
-- 估值中性时维持正常节奏
-- `Z-Score` 高于阈值时分档止盈
-- `Z-Score` 越高，卖出比例越大
-
-**目标仓位：**
-
-`btc_target_ratio = 0.14 + 0.16 * ln(1 + total_equity / 10000)`，并有上限控制。组合越大，BTC 核心仓占比越高，趋势层占比越低。
-
-**定投基准金额：** 每日 base order 随总权益增长。
-
-## 趋势轮动层
-
-**候选池来源：** 优先使用上游 live pool。读取顺序为：
-
-1. 新鲜的上游 Firestore payload（主配置：`STRATEGY_ARTIFACT_FIRESTORE_COLLECTION` / `STRATEGY_ARTIFACT_FIRESTORE_DOCUMENT`；兼容别名：`TREND_POOL_FIRESTORE_COLLECTION` / `TREND_POOL_FIRESTORE_DOCUMENT`）
-2. Firestore 状态中记录的 last known good 上游 payload
-3. 通过校验的本地 upstream 文件 fallback（主配置：`STRATEGY_ARTIFACT_FILE`；兼容别名：`TREND_POOL_FILE`）
-4. 静态 `TREND_UNIVERSE` 紧急 fallback
-
-**官方输入池：** 上游发布 5 币 live pool，本仓库把这 5 个币视为月度官方输入集。
-
-**观察面板：** 本仓库也可能展示本地 stable-quality 排名，仅用于观察和诊断，不等于上游官方月池，也不是最终执行目标。
-
-**最终执行目标：** live 趋势层只对最终 Top 2 轮动结果执行，或者在没有合格候选时进入防守状态。
-
-**因子：**
-
-- `SMA20 / SMA60 / SMA200`
-- `20 / 60 / 120` 日收益
-- `20` 日波动率
-- `ATR14`
-- `30 / 90 / 180` 日均成交额
-- 趋势持续性
-- 相对 BTC 强弱
-- 风险调整后的动量
-
-**持仓规则：** 从月池里选相对 BTC 最强的 Top 2，按逆波动率分配。
-
-**开仓条件：**
-
-- BTC 闸门开启
-- 价格在 `SMA20 / SMA60 / SMA200` 之上
-- 相对 BTC 分数为正
-- 绝对动量为正
-
-**出场条件：**
+[English README](README.md)
-- 跌破 `SMA60`
-- 触发 `ATR` 跟踪止损
-- 被轮动出 Top 2
-
-## 风险控制
-
-- **BTC 闸门：** 只有 `BTC price > MA200` 且 `MA200 slope > 0` 时，趋势层才允许工作。
-- **趋势熔断：** 如果趋势层当日收益低于阈值，则清空趋势层，BTC 核心仓保持不变。
-- **外部 USDT 划转：** 手动充值或提现 USDT 时，会重置当日收益基准，不会把这类资金流当成策略亏损或熔断信号。
-- **BNB 燃料仓：** 自动补仓用于手续费，不参与趋势轮动。
-
-## Earn 兼容
-
-- 下单前先检查现货余额，不够时从 Flexible Earn 赎回
-- 维护 USDT 现货缓冲水位，多余则自动申购，短缺则自动赎回
-- Flexible Earn 的自动申购和赎回只是在现货与理财之间搬动 USDT；因为运行时统计的是总 USDT，所以这类动作不会触发熔断，也不会触发外部资金流重置。
-
-## 状态存储（Firestore）
-
-会保存：
-
-- 趋势持仓和最高价
-- 熔断状态
-- DCA 最近买卖日期
-- 月池标识和池内币种
-- 已从月池移除但仍持有的退役仓位
-
-## 上游趋势池契约
-
-**默认来源：** `CryptoSnapshotPipelines` 的月度输出。
-
-读取顺序：
-
-1. Firestore `strategy` / `CRYPTO_LEADER_ROTATION_LIVE_POOL`（主配置：`STRATEGY_ARTIFACT_FIRESTORE_COLLECTION` / `STRATEGY_ARTIFACT_FIRESTORE_DOCUMENT`；兼容别名：`TREND_POOL_FIRESTORE_COLLECTION` / `TREND_POOL_FIRESTORE_DOCUMENT`）
-2. 状态里保存的 last known good 上游 payload
-3. 本地 `live_pool_legacy.json` 或 `live_pool.json`（主配置：`STRATEGY_ARTIFACT_FILE`；兼容别名：`TREND_POOL_FILE`）
-4. 静态 `TREND_UNIVERSE`
-
-**稳定字段：**
-
-- `as_of_date`
-- `version`
-- `mode`
-- `pool_size`
-- `symbols`
-- `symbol_map`
-- `source_project`
-
-**降级模式规则：**
-
-- 上游 payload 必须有非空币种列表、可解析的 `as_of_date`、可接受的 `mode`
-- 新鲜度由 `STRATEGY_ARTIFACT_MAX_AGE_DAYS` 和 `as_of_date` 控制；`TREND_POOL_MAX_AGE_DAYS` 仍可兼容使用
-- 如果 fresh upstream 过期或格式错误，不会把弱 fallback 当成等价替代
-- 进入 degraded mode 后，默认暂停新的趋势买入，除非显式设置 `STRATEGY_ARTIFACT_ALLOW_NEW_ENTRIES_ON_DEGRADED=1`，或使用兼容别名 `TREND_POOL_ALLOW_NEW_ENTRIES_ON_DEGRADED=1`
-- 已退役币种会保留在状态中直到真正卖出
-
-## 环境变量
-
-必需：
-
-| 变量 | 说明 |
-|---|---|
-| `BINANCE_API_KEY` | Binance API Key |
-| `BINANCE_API_SECRET` | Binance API Secret |
-| `TG_TOKEN` | Telegram Bot Token |
-| `GLOBAL_TELEGRAM_CHAT_ID` | 这个服务使用的 Telegram Chat ID。 |
-| `GOOGLE_APPLICATION_CREDENTIALS` | GCP 服务账号 JSON 路径 |
-
-如果你在多个 quant 仓库之间保留一层共享配置，通常只建议共享 `GLOBAL_TELEGRAM_CHAT_ID` 和 `NOTIFY_LANG`。`TG_TOKEN`、Binance API Key、GCP 凭据这些仍然应该由这个仓库自己管理。
-
-可选：
-
-| 变量 | 说明 |
-|---|---|
-| `BTC_STATUS_REPORT_INTERVAL_HOURS` | BTC 状态报告间隔，默认 `24` |
-| `STRATEGY_PROFILE` | 策略 profile 选择器，当前默认并仅支持 `crypto_leader_rotation` |
-| `STRATEGY_ARTIFACT_FILE` | 本地 live-pool artifact 路径；兼容别名：`TREND_POOL_FILE` |
-| `STRATEGY_ARTIFACT_MANIFEST_FILE` | 可选本地 artifact manifest 路径，供运维工具使用 |
-| `STRATEGY_ARTIFACT_FIRESTORE_COLLECTION` | live artifact 的 Firestore collection，默认 `strategy`；兼容别名：`TREND_POOL_FIRESTORE_COLLECTION` |
-| `STRATEGY_ARTIFACT_FIRESTORE_DOCUMENT` | live artifact 的 Firestore document，默认 `CRYPTO_LEADER_ROTATION_LIVE_POOL`；兼容别名：`TREND_POOL_FIRESTORE_DOCUMENT` |
-| `STRATEGY_ARTIFACT_MAX_AGE_DAYS` | 上游 `as_of_date` 允许的最大天数，默认 `45`；兼容别名：`TREND_POOL_MAX_AGE_DAYS` |
-| `STRATEGY_ARTIFACT_ACCEPTABLE_MODES` | 可接受的上游 mode，默认 `core_major`；兼容别名：`TREND_POOL_ACCEPTABLE_MODES` |
-| `STRATEGY_ARTIFACT_EXPECTED_SIZE` | 上游 live pool 期望数量，默认 `5`；兼容别名：`TREND_POOL_EXPECTED_SIZE` |
-| `STRATEGY_ARTIFACT_ALLOW_NEW_ENTRIES_ON_DEGRADED` | degraded mode 下是否允许趋势新开仓，默认 `false`；兼容别名：`TREND_POOL_ALLOW_NEW_ENTRIES_ON_DEGRADED` |
-| `NOTIFY_LANG` | 日志和通知语言: `en`（英文，默认）或 `zh`（中文） |
-
-## 通知格式
-
-运行日志和 Telegram 通知共用同一个语言开关。设置 `NOTIFY_LANG=zh` 切换为中文，不设置则默认英文。
-
-**策略心跳:**
-```
-💓 【策略心跳】
-🕐 UTC 时间: 2026-03-24 00:00
-━━━━━━━━━━━━━━━━━━
-💰 总净值: $12,500.00
-📈 趋势层持仓: $3,200.00 (1.25%)
-₿ BTC 价格: $87,000.00
-━━━━━━━━━━━━━━━━━━
-AHR999: 0.850
-Z-Score: 1.20 / 阈值 3.00
-🎯 BTC 目标配比: 28.5%
-🚦 BTC 闸门: 开启
-━━━━━━━━━━━━━━━━━━
-💡 建议: BTC 估值中性，跟随系统节奏即可。
-```
-
-**交易通知:**
-```
-✅ 【趋势买入】 ETHUSDT
-价格: $3,450.00
-预算: $800.00
-轮动权重: 60%
-相对BTC得分: 0.85
-
-📉 【趋势卖出】 SOLUSDT
-原因: ATR trailing stop ($142.50)
-价格: $138.20
-
-🛡️ 【BTC 定投买入】 BTC
-AHR999: 0.45
-目标配比: 28.5%
-数量: 0.00125 BTC
-```
-
-## 部署
-
-本仓库默认运行在 **self-hosted GitHub Actions runner** 上，例如 VPS。workflow 会拉代码，通过 GitHub OIDC + Workload Identity Federation 登录 Google Cloud，安装依赖，然后运行 `main.py`。不是“手动下载后本地 cron”那种流程。
-
-这个仓库通过 `QuantPlatformKit` 复用 Binance 客户端初始化、余额辅助、行情快照和下单数量格式化。runner 直接执行这个仓库，`QuantPlatformKit` 不单独部署。
-
-### 1. Self-hosted runner
-
-- 在仓库 `Settings -> Actions -> Runners` 中添加 runner
-- 在机器上安装并注册 runner，保持其长期运行
-
-### 2. Workflow 和调度
-
-- [`.github/workflows/main.yml`](./.github/workflows/main.yml) 负责 checkout、通过 OIDC 登录 Google Cloud、准备 venv、执行 `main.py`
-- `push` 只触发校验类 job；真正执行策略的步骤默认只在 `workflow_dispatch` 下运行
-- `.github/workflows/runtime-heartbeat.yml` 跑在 GitHub-hosted runner 上，检查最近的
- `main.yml` 是否成功完成，并对漏跑或失败 Runtime run 发 Telegram
-- 如需安全验证 self-hosted runner 上的 Google Cloud 登录，可用 `validate_only=true` 手动触发 `main.yml`；这不会下实盘单
-- VPS 侧推荐的运行单元名：`binance-quant`
-- Cloud Run / VPS 的统一部署规则和命名建议见 [`QuantPlatformKit/docs/deployment_model.md`](../QuantPlatformKit/docs/deployment_model.md)
-
-### 3. Repository secrets
-
-需要设置：
-
-- `BINANCE_API_KEY`
-- `BINANCE_API_SECRET`
-- `TG_TOKEN`
-- `GLOBAL_TELEGRAM_CHAT_ID`
+> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。
-现在 runtime workflow 要求这两个仓库/组织 Variables 已经提供：
+## 这个项目做什么
-- `GLOBAL_TELEGRAM_CHAT_ID`
-- `NOTIFY_LANG`
-- `STRATEGY_PROFILE`（建议设为 `crypto_leader_rotation`）
+BinancePlatform 是 QuantStrategyLab 体系中的**执行平台**。面向 Binance 执行 QuantStrategyLab 加密货币策略，负责外部策略加载、运行时适配、交易执行编排和 CI 运维。
-也就是说，如果你在多个 quant 仓库之间保留一层很小的共享配置，这个仓库直接使用组织级 `GLOBAL_TELEGRAM_CHAT_ID` 和 `NOTIFY_LANG`。`TG_TOKEN` 和 Binance API key 仍然应该留在这个仓库自己的 secrets 里。Google Cloud 登录现在走 GitHub OIDC，不再需要 `GCP_SA_KEY`。
+## 适合谁使用
-`STRATEGY_PROFILE` 当前只支持 `crypto_leader_rotation`；对应的策略域是 `crypto`。
+- 希望阅读、复现或扩展 QuantStrategyLab 相关模块的工程师和研究人员。
+- 在阅读详细 runbook 或 workflow 前，需要先理解项目入口的运维人员。
+- 在启用自动化前，需要确认项目职责、安全边界和证据要求的 reviewer。
-### 4. GCP / Firestore
+## 当前状态
-- GitHub runtime workflow 现在通过 OIDC + Workload Identity Federation 代理 `binance-platform-runtime@binancequant.iam.gserviceaccount.com`
-- 这个 runtime 服务账号必须具备 Firestore 读写权限
+偏生产运行的执行平台代码；启用真实下单前必须先跑 dry-run 或 paper 流程。
-## 本地运行
+## 仓库结构
-仅供本地测试：
+- `application/`, `entrypoints/`, `infra/`, `reporting/`：Python 包代码。
+- `tests/`：单元测试和契约测试。
+- `docs/`：详细设计说明、运行手册和证据文档。
+- `.github/workflows/`：CI、定时任务和部署 workflow。
+- `scripts/`：运维脚本和本地辅助工具。
-```bash
-cd /path/to/BinancePlatform
-python3 -m venv venv && source venv/bin/activate
-pip install -r requirements.txt
-export BINANCE_API_KEY=... BINANCE_API_SECRET=... TG_TOKEN=... GLOBAL_TELEGRAM_CHAT_ID=...
-export GOOGLE_APPLICATION_CREDENTIALS=/path/to/gcp-sa.json
-python main.py
-```
+## 快速开始
-## 本地研究回测
+从全新 clone 开始：
```bash
-python3 -m research.backtest
+python -m pip install -r requirements.txt
+python -m pytest -q
```
-## 单轮 Dry-run Replay
-
-```bash
-python3 run_cycle_replay.py --run-id local-check
-```
+如果命令需要凭据，请先阅读相关 workflow 或 runbook，并把密钥配置在 Git 之外。
-它会输出结构化 JSON，包含：
+## 部署和运行
-- 采用的上游池和最终候选
-- 趋势买卖意图
-- BTC DCA 意图
-- Earn 申购/赎回意图
-- 被执行与被抑制的 side effect 计数
+在 GitHub Actions 中配置 Binance 凭据、运行参数、通知和策略来源。先手工触发 dry-run，检查日志和产物，再在确认凭据与风控后启用定时 workflow。
-## 测试
+建议先手工运行或 dry-run。只有在日志、产物、权限和回滚步骤都检查过之后，才启用定时任务或 live 执行。
-```bash
-python3 -m unittest \
- tests.test_strategy_core \
- tests.test_cycle_replay_runtime \
- tests.test_trend_pool_loading \
- -v
-```
+## 策略表现与证据边界
-仓库卫生建议：
+本仓库不负责策略排名。收益、回撤和 live 资格必须来自策略仓库及其快照/回测产物，平台只能执行已经通过门禁的策略。
-- 忽略 `reports/`、`venv/`、`.venv/`、`gcp-key.json`、`.venv_requirements_hash` 等本地产物
-- 保留 `tests/fixtures/`，确保 replay 回归测试可复现
+README 不应该承诺固定收益或过期指标。实际使用前，请重新运行对应测试、回测或流水线任务。
-上游 `CryptoSnapshotPipelines` 负责月度发布、shadow candidate 评估和月度研究报告；本仓库只保留交易执行与必要的固定输入回放工具。
+## 安全注意事项
-## Telegram
+- 不要把 API key、券商凭据、OAuth token、Cookie 或账户标识提交到 Git。
+- 新策略或平台变更在 live 前必须先跑 dry-run 或 paper 流程。
+- 启用定时任务前，需要人工检查生成的订单、产物和日志。
-Telegram 通知会覆盖：
+## 参与贡献
-- 趋势买入 / 卖出
-- BTC DCA
-- Earn 申赎
-- 熔断
-- 异常错误
+请保持改动小、可复现，并用最小必要测试覆盖。涉及策略的改动，需要附上验证行为的证据产物或命令。
-另外还支持可选的 BTC 周期性状态报告，默认每天 UTC 00:00 发送一次，可通过 `BTC_STATUS_REPORT_INTERVAL_HOURS` 调整。
+## 许可证
-所有通知支持 `NOTIFY_LANG` 切换语言（`en` 默认英文，`zh` 中文）。参见 [通知格式](#通知格式) 示例。
+如仓库包含 [LICENSE](LICENSE)，请以该文件为准。