diff --git a/README.md b/README.md index 8bb0dd3..cca7e4e 100644 --- a/README.md +++ b/README.md @@ -1,164 +1,62 @@ # QuantRuntimeSettings - +[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 | runtime settings | -| What it does | Runtime settings schema and tooling for QuantStrategyLab deployments. | -| 中文说明 | 运行时配置 schema 与工具，帮助各部署统一账户、profile、dry-run/live 参数。 | -| Current status | Configuration tooling. It should not contain secrets or live account identifiers. | +QuantRuntimeSettings is a **Runtime configuration package** in the QuantStrategyLab ecosystem. It defines schemas and tooling for shared QuantStrategyLab runtime settings. -### 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 -Consume generated settings from platform repositories; validate redaction and environment-specific overrides before use. +Shared configuration contract; changes can affect multiple platforms. -### Strategy performance / evidence boundary +## Repository layout -Not a strategy repository; correctness is schema/test coverage and safe downstream consumption. +- `tests/`: unit and contract tests. +- `.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 - - -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 - -[English](#english) | [中文](#中文) - ---- - - -## English - -Declarative runtime settings tooling for QuantStrategyLab deployments. - -This repository provides the schema and tooling for "which platform runs which strategy". It does not contain live runtime assignments, strategy logic, broker execution code, credentials, or secrets. - -## Public Repository Policy - -Live target files must not be committed to this public repository. Keep real deployment choices in GitHub Variables/Environments, GitHub Secrets, Secret Manager, or ignored local files under `local/`. - -Use repository or environment variables for non-secret runtime choices such as `TARGET_SPEC_JSON`, `RUNTIME_TARGET_JSON`, and plugin mount declarations. Use secrets only for credentials, tokens, and private keys. - -If a deployment needs private validation policy, keep it in ignored local files such as `local/policy.json`. - -## Boundaries - -- `UsEquityStrategies` owns allocation logic, strategy defaults, and risk rules. -- Platform repositories own broker adapters, runtime input collection, notifications, and execution. -- This repository owns runtime target schemas, examples, validation, and rendering tools. -- Secret values are intentionally excluded. Use secret names or platform repository secrets when needed. - -## Commands - -Validate examples, or local targets when `local/targets/**/*.json` exists: - -```bash -python3 scripts/runtime_settings.py validate -``` - -Render assignments for an example: - -```bash -python3 scripts/runtime_settings.py render examples/targets/schwab/live.example.json -``` - -Preview GitHub variable updates for an ignored local target: - -```bash -python3 scripts/runtime_settings.py apply local/targets/longbridge/sg.json -``` - -Apply GitHub variable updates: +From a fresh clone: ```bash -python3 scripts/runtime_settings.py apply --yes local/targets/longbridge/sg.json +python -m pip install -e . +python -m pytest -q ``` -`RUNTIME_TARGET_JSON` is canonical. Compatibility variables such as `STRATEGY_PROFILE` are generated from it so they cannot drift independently. - -For daily strategies that want both a precheck pass and an execution pass, declare them in `runtime_target.execution_windows`. Keep the strategy logic unchanged; let the platform layer decide whether a window is `notify_only`, `dry_run`, `paper`, or `live`. - -## Architecture - -This repo acts as a small bridge between strategy selection and platform deployment without exposing live assignments: - -- A target file declares the desired runtime target. -- The validator checks that required runtime fields and plugin mounts are coherent. -- Optional ignored local policy can add private strategy/plugin requirements. -- The renderer converts the declaration into platform-specific GitHub variables. -- Platform repositories keep their existing adapter code and consume the generated variables. - ---- - - -## 中文 +If a command requires credentials, run it only after reading the relevant workflow or runbook and configuring secrets outside Git. -QuantStrategyLab 部署运行设置的声明式 schema 和工具仓库。 +## Deployment and operation -这个仓库用于描述和校验“哪个平台运行哪个策略”的配置格式，但不保存真实线上运行分配、策略逻辑、券商执行代码、凭据或密钥。 +Use the schemas in platform repositories and CI validation. Roll out setting changes through review, dry-run validation, and controlled platform deployment. -## 公开仓库策略 +Prefer manual or dry-run execution first. Enable schedules or live execution only after logs, artifacts, permissions, and rollback steps are reviewed. -真实 target 文件不能提交到这个公开仓库。真实部署选择应保存在 GitHub Variables / Environments、GitHub Secrets、Secret Manager，或放在被忽略的 `local/` 目录下。 +## Strategy performance and evidence -非敏感运行选择，例如 `TARGET_SPEC_JSON`、`RUNTIME_TARGET_JSON` 和插件挂载声明，可以放在 repository 或 environment variables 中。凭据、token、private key 等必须使用 secrets。 +Not a strategy repository. Quality is measured by compatibility, validation coverage, and reducing configuration mistakes. -如果某个部署需要私有校验策略，请放在被忽略的本地文件里，例如 `local/policy.json`。 +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. -## 边界 - -- `UsEquityStrategies` 负责分配逻辑、策略默认值和风险规则。 -- 平台仓库负责券商 adapter、运行时输入采集、通知和执行。 -- 本仓库负责运行 target 的 schema、示例、校验和渲染工具。 -- 本仓库不保存 secret value；需要时只引用 secret name 或平台仓库自身的 secret。 - -## 命令 - -校验示例；如果存在 `local/targets/**/*.json`，则优先校验本地 target： - -```bash -python3 scripts/runtime_settings.py validate -``` - -渲染一个示例 target： - -```bash -python3 scripts/runtime_settings.py render examples/targets/schwab/live.example.json -``` - -预览被忽略本地 target 对应的 GitHub variable 更新： - -```bash -python3 scripts/runtime_settings.py apply local/targets/longbridge/sg.json -``` - -实际应用 GitHub variable 更新： - -```bash -python3 scripts/runtime_settings.py apply --yes local/targets/longbridge/sg.json -``` +## Safety notes -`RUNTIME_TARGET_JSON` 是唯一 canonical source。兼容变量，例如 `STRATEGY_PROFILE`，由它生成，避免多个配置源互相漂移。 +- 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. -对于希望同时有预检和执行两次运行的日频策略，可以在 `runtime_target.execution_windows` 里显式声明两个窗口。策略逻辑保持不变，由平台层决定某个窗口是 `notify_only`、`dry_run`、`paper` 还是 `live`。 +## Contributing -## 架构 +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. -这个仓库在策略选择和平台部署之间提供一个轻量 bridge，同时避免公开真实运行分配： +## License -- target 文件声明期望的运行目标。 -- validator 检查必填运行字段和插件挂载是否一致。 -- 可选的 ignored local policy 可以添加私有策略/插件要求。 -- renderer 把声明转换成平台专属 GitHub variables。 -- 平台仓库保持现有 adapter 代码，并消费生成后的变量。 +See [LICENSE](LICENSE) if present in this repository. diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..b5a17e9 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,62 @@ +# QuantRuntimeSettings + +[English README](README.md) + +> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 + +## 这个项目做什么 + +QuantRuntimeSettings 是 QuantStrategyLab 体系中的**运行配置包**。定义 QuantStrategyLab 共享运行配置的 schema 和工具。 + +## 适合谁使用 + +- 希望阅读、复现或扩展 QuantStrategyLab 相关模块的工程师和研究人员。 +- 在阅读详细 runbook 或 workflow 前，需要先理解项目入口的运维人员。 +- 在启用自动化前，需要确认项目职责、安全边界和证据要求的 reviewer。 + +## 当前状态 + +共享配置契约；改动可能影响多个执行平台。 + +## 仓库结构 + +- `tests/`：单元测试和契约测试。 +- `.github/workflows/`：CI、定时任务和部署 workflow。 +- `scripts/`：运维脚本和本地辅助工具。 + +## 快速开始 + +从全新 clone 开始： + +```bash +python -m pip install -e . +python -m pytest -q +``` + +如果命令需要凭据，请先阅读相关 workflow 或 runbook，并把密钥配置在 Git 之外。 + +## 部署和运行 + +在平台仓库和 CI 校验中使用这些 schema。配置变更应经过 review、dry-run 验证和受控平台发布。 + +建议先手工运行或 dry-run。只有在日志、产物、权限和回滚步骤都检查过之后，才启用定时任务或 live 执行。 + +## 策略表现与证据边界 + +这不是策略仓库。质量标准是兼容性、校验覆盖和减少配置错误。 + +README 不应该承诺固定收益或过期指标。实际使用前，请重新运行对应测试、回测或流水线任务。 + +## 安全注意事项 + +- 不要把 API key、券商凭据、OAuth token、Cookie 或账户标识提交到 Git。 +- 新策略或平台变更在 live 前必须先跑 dry-run 或 paper 流程。 +- 启用定时任务前，需要人工检查生成的订单、产物和日志。 + +## 参与贡献 + +请保持改动小、可复现，并用最小必要测试覆盖。涉及策略的改动，需要附上验证行为的证据产物或命令。 + +## 许可证 + +如仓库包含 [LICENSE](LICENSE)，请以该文件为准。