Skip to content

docs: split bilingual open-source readmes #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Pigbibi merged 1 commit into from
Jun 3, 2026
Merged

docs: split bilingual open-source readmes #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 32 additions & 134 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,164 +1,62 @@
# QuantRuntimeSettings

<!-- 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 | 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

<!-- qsl-doc-overview:end -->

> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。

[English](#english) | [中文](#中文)

---

<a id="english"></a>
## 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.

---

<a id="中文"></a>
## 中文
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.
62 changes: 62 additions & 0 deletions README.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)，请以该文件为准。