From 2f97f451b8ee81036feac6a0eb9f686a5abe328d Mon Sep 17 00:00:00 2001 From: Pigbibi <20649888+Pigbibi@users.noreply.github.com> Date: Wed, 3 Jun 2026 17:56:25 +0800 Subject: [PATCH] docs: rewrite open-source readmes --- README.md | 65 ++++++++++++++++++++----------------------------- README.zh-CN.md | 65 ++++++++++++++++++++----------------------------- 2 files changed, 54 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index f2f4982..e9842e1 100644 --- a/README.md +++ b/README.md @@ -2,63 +2,52 @@ [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 -LongBridgePlatform is an **Execution platform** in the QuantStrategyLab ecosystem. It executes QuantStrategyLab US and Hong Kong equity strategies through LongBridge-compatible runtime services, with region settings, dry-run controls, and cloud deployment workflows. +LongBridgePlatform is a QuantStrategyLab LongBridge US/HK equity execution platform. It runs US and HK equity profiles through LongBridge-compatible runtime services and regional deployment settings. -## Who this is for +It is an execution layer, not a strategy research repository. Strategy logic comes from `UsEquityStrategies / HkEquityStrategies`; snapshot and validation artifacts come from `UsEquitySnapshotPipelines / HkEquitySnapshotPipelines` when a profile requires them. -- 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. +## Runtime boundary -## Current status +- Loads only runtime-enabled strategy profiles exposed by the strategy packages. +- Handles broker/API connectivity, dry-run checks, notifications, and deployment settings. +- Must keep credentials in GitHub Secrets, cloud secret stores, or the broker-specific secret system, never in Git. +- Should start with dry-run or paper mode before any live order path is enabled. -Production-oriented platform code for brokerage execution; start with dry-run and smallest possible scope. +## Direct vs snapshot-backed profiles + +Direct runtime profiles can usually run from market history or portfolio state. Snapshot-backed profiles need a current artifact bundle from the matching snapshot pipeline before this platform should execute them. The platform should not invent strategy eligibility; it should consume the status and artifacts published by the strategy and snapshot repositories. + +## Deploy safely + +1. Configure secrets and runtime variables outside Git. +2. Run the workflow or service in dry-run mode. +3. Review generated orders, logs, notifications, and reconciliation output. +4. Confirm rollback steps and artifact versions. +5. Enable scheduled or live execution only after the above checks are clear. ## Repository layout -- `application/`, `entrypoints/`, `notifications/`, `strategy/`: Python package code. -- `tests/`: unit and contract tests. -- `docs/`: detailed design notes, runbooks, and evidence docs. -- `.github/workflows/`: CI, scheduled jobs, and deployment workflows. +- `tests/`: unit, contract, and regression tests. +- `docs/`: runbooks, design notes, evidence, and integration contracts. +- `.github/workflows/`: CI, scheduled jobs, release, or deployment workflows. - `scripts/`: operator scripts and local helpers. +- `research/`: research configs and non-live candidate artifacts. ## Quick start -From a fresh clone: - ```bash python -m pip install -r requirements.txt python -m pytest -q ``` -If a command requires credentials, run it only after reading the relevant workflow or runbook and configuring secrets outside Git. - -## Deployment and operation - -Configure GitHub Actions or cloud runtime variables for LongBridge credentials, account scope, strategy package, and dry-run mode. Deploy from the provided workflows or Cloud Run configuration after a successful dry-run. - -Prefer manual or dry-run execution first. Enable schedules or live execution only after logs, artifacts, permissions, and rollback steps are reviewed. - -## Strategy performance and evidence - -This platform consumes live-enabled strategy metadata; it does not decide whether a strategy is good. Use the relevant US/HK strategy and snapshot repositories for return, drawdown, and benchmark evidence. - -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. - -## Safety 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. - -## Contributing +## Useful docs -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. +- [`docs/hk_equity_runtime.md`](docs/hk_equity_runtime.md) ## 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 e2c347f..d49b88b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -2,63 +2,52 @@ [English README](README.md) -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 +> 投资有风险。本项目不构成投资建议，仅用于学习、研究和工程审阅。 -## 这个项目做什么 +## 这个仓库是什么 -LongBridgePlatform 是 QuantStrategyLab 体系中的**执行平台**。通过 LongBridge 运行 QuantStrategyLab 的美股和港股策略，包含区域配置、dry-run 控制和云端部署 workflow。 +LongBridgePlatform 是 QuantStrategyLab 的LongBridge 美股/港股执行平台。通过 LongBridge 运行服务和区域部署配置执行美股与港股 profile。 -## 适合谁使用 +它属于执行层，不是策略研究仓库。策略逻辑来自 `UsEquityStrategies / HkEquityStrategies`；如果 profile 依赖 snapshot，验证和产物来自 `UsEquitySnapshotPipelines / HkEquitySnapshotPipelines`。 -- 希望阅读、复现或扩展 QuantStrategyLab 相关模块的工程师和研究人员。 -- 在阅读详细 runbook 或 workflow 前，需要先理解项目入口的运维人员。 -- 在启用自动化前，需要确认项目职责、安全边界和证据要求的 reviewer。 +## 运行边界 -## 当前状态 +- 只加载策略包暴露的 runtime-enabled profile。 +- 负责券商/API 连接、dry-run 检查、通知和部署配置。 +- 凭据必须放在 GitHub Secrets、云密钥系统或券商专用密钥系统中，不能提交到 Git。 +- 任何 live 下单路径启用前，都应先从 dry-run 或 paper mode 开始。 -面向券商执行的生产型平台代码；上线前应先从 dry-run 和最小范围开始。 +## 普通 profile 与 snapshot-backed profile + +普通 runtime profile 通常可以直接基于 market history 或 portfolio state 执行。Snapshot-backed profile 需要先从对应 snapshot pipeline 获取当前 artifact bundle，平台才应该执行。平台不应该自行判断策略资格，而应消费策略仓和 snapshot 仓发布的状态与产物。 + +## 安全部署顺序 + +1. 在 Git 之外配置 secrets 和 runtime variables。 +2. 先以 dry-run 模式运行 workflow 或服务。 +3. 检查生成订单、日志、通知和 reconciliation 输出。 +4. 确认回滚步骤和 artifact 版本。 +5. 上述检查清楚后，再启用定时任务或 live 执行。 ## 仓库结构 -- `application/`, `entrypoints/`, `notifications/`, `strategy/`：Python 包代码。 -- `tests/`：单元测试和契约测试。 -- `docs/`：详细设计说明、运行手册和证据文档。 -- `.github/workflows/`：CI、定时任务和部署 workflow。 +- `tests/`：单元测试、契约测试和回归测试。 +- `docs/`：运行手册、设计说明、证据和集成契约。 +- `.github/workflows/`：CI、定时任务、发布或部署 workflow。 - `scripts/`：运维脚本和本地辅助工具。 +- `research/`：研究配置和非 live 候选产物。 ## 快速开始 -从全新 clone 开始： - ```bash python -m pip install -r requirements.txt python -m pytest -q ``` -如果命令需要凭据，请先阅读相关 workflow 或 runbook，并把密钥配置在 Git 之外。 - -## 部署和运行 - -在 GitHub Actions 或云运行环境中配置 LongBridge 凭据、账户范围、策略包和 dry-run 开关。dry-run 成功后，再通过仓库内 workflow 或 Cloud Run 配置部署。 - -建议先手工运行或 dry-run。只有在日志、产物、权限和回滚步骤都检查过之后，才启用定时任务或 live 执行。 - -## 策略表现与证据边界 - -本平台消费已经 live enable 的策略元数据，不判断策略优劣。收益、回撤和基准比较应以美股/港股策略仓库与快照仓库的证据为准。 - -README 不应该承诺固定收益或过期指标。实际使用前，请重新运行对应测试、回测或流水线任务。 - -## 安全注意事项 - -- 不要把 API key、券商凭据、OAuth token、Cookie 或账户标识提交到 Git。 -- 新策略或平台变更在 live 前必须先跑 dry-run 或 paper 流程。 -- 启用定时任务前，需要人工检查生成的订单、产物和日志。 - -## 参与贡献 +## 延伸文档 -请保持改动小、可复现，并用最小必要测试覆盖。涉及策略的改动，需要附上验证行为的证据产物或命令。 +- [`docs/hk_equity_runtime.md`](docs/hk_equity_runtime.md) ## 许可证 -如仓库包含 [LICENSE](LICENSE)，请以该文件为准。 +详见 [LICENSE](LICENSE)。