diff --git a/README.md b/README.md index 738a54e..7e0344e 100644 --- a/README.md +++ b/README.md @@ -2,63 +2,46 @@ [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 -QuantAdvisorResearch is a **Research advisory system** in the QuantStrategyLab ecosystem. It publishes research-oriented advisory content from web/RSS evidence without placing orders or providing account-specific advice. +QuantAdvisorResearch is a QuantStrategyLab research publishing system. It publishes research-oriented advisory content from web and RSS evidence without placing orders. -## Who this is for +It produces research, audit, or orchestration artifacts. It should not submit broker orders or mutate live allocations by itself. -- 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. +## Output boundary -## Current status - -Research and publishing system; outputs require human review before use. +- Treat generated reports as evidence or review material, not automatic trading instructions. +- Keep source traceability and artifact timestamps visible. +- Require human review before using outputs in downstream strategy or platform changes. +- Keep credentials, private data, and external service tokens out of Git and logs. ## Repository layout -- `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. +- `src/`: library and runtime code. +- `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. ## Quick start -From a fresh clone: - ```bash python -m pip install -e . 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 data sources, publishing credentials, and scheduled workflows. Start with a manual run, inspect generated content and citations, then enable schedule. - -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 - -Not a trading strategy repository. Evaluate it by evidence quality, citation accuracy, freshness, and whether outputs avoid account-specific investment advice. - -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/advisory_contract.md`](docs/advisory_contract.md) +- [`docs/data_factor_roadmap.md`](docs/data_factor_roadmap.md) +- [`docs/data_factor_roadmap.zh-CN.md`](docs/data_factor_roadmap.zh-CN.md) +- [`docs/notification_format.md`](docs/notification_format.md) +- [`docs/notification_format.zh-CN.md`](docs/notification_format.zh-CN.md) +- [`docs/system_design.md`](docs/system_design.md) +- [`docs/system_design.zh-CN.md`](docs/system_design.zh-CN.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 bb694d6..d2dc153 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -2,63 +2,46 @@ [English README](README.md) -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 +> 投资有风险。本项目不构成投资建议，仅用于学习、研究和工程审阅。 -## 这个项目做什么 +## 这个仓库是什么 -QuantAdvisorResearch 是 QuantStrategyLab 体系中的**研究顾问系统**。基于网页/RSS 证据发布研究型顾问内容，不下单，也不提供面向具体账户的建议。 +QuantAdvisorResearch 是 QuantStrategyLab 的研究发布系统。基于网页和 RSS 证据发布研究型内容，不执行订单。 -## 适合谁使用 +它产出研究、审计或编排类 artifact，不应自行提交券商订单，也不应直接修改 live allocation。 -- 希望阅读、复现或扩展 QuantStrategyLab 相关模块的工程师和研究人员。 -- 在阅读详细 runbook 或 workflow 前，需要先理解项目入口的运维人员。 -- 在启用自动化前，需要确认项目职责、安全边界和证据要求的 reviewer。 +## 输出边界 -## 当前状态 - -研究与发布系统；输出内容使用前需要人工复核。 +- 生成报告应作为证据或审阅材料，不是自动交易指令。 +- 保留来源可追溯性和 artifact 时间戳。 +- 输出用于下游策略或平台改动前，需要人工 review。 +- 凭据、私人数据和外部服务 token 不能提交到 Git，也不能写入日志。 ## 仓库结构 -- `src/`：主要库代码和运行时代码。 -- `tests/`：单元测试和契约测试。 -- `docs/`：详细设计说明、运行手册和证据文档。 -- `.github/workflows/`：CI、定时任务和部署 workflow。 +- `src/`：库代码和运行时代码。 +- `tests/`：单元测试、契约测试和回归测试。 +- `docs/`：运行手册、设计说明、证据和集成契约。 +- `.github/workflows/`：CI、定时任务、发布或部署 workflow。 - `scripts/`：运维脚本和本地辅助工具。 ## 快速开始 -从全新 clone 开始： - ```bash python -m pip install -e . python -m pytest -q ``` -如果命令需要凭据，请先阅读相关 workflow 或 runbook，并把密钥配置在 Git 之外。 - -## 部署和运行 - -配置数据源、发布凭据和定时 workflow。先手工运行，检查生成内容和引用，再启用定时任务。 - -建议先手工运行或 dry-run。只有在日志、产物、权限和回滚步骤都检查过之后，才启用定时任务或 live 执行。 - -## 策略表现与证据边界 - -这不是交易策略仓库。评估重点是证据质量、引用准确性、时效性，以及是否避免具体账户投资建议。 - -README 不应该承诺固定收益或过期指标。实际使用前，请重新运行对应测试、回测或流水线任务。 - -## 安全注意事项 - -- 不要把 API key、券商凭据、OAuth token、Cookie 或账户标识提交到 Git。 -- 新策略或平台变更在 live 前必须先跑 dry-run 或 paper 流程。 -- 启用定时任务前，需要人工检查生成的订单、产物和日志。 - -## 参与贡献 +## 延伸文档 -请保持改动小、可复现，并用最小必要测试覆盖。涉及策略的改动，需要附上验证行为的证据产物或命令。 +- [`docs/advisory_contract.md`](docs/advisory_contract.md) +- [`docs/data_factor_roadmap.md`](docs/data_factor_roadmap.md) +- [`docs/data_factor_roadmap.zh-CN.md`](docs/data_factor_roadmap.zh-CN.md) +- [`docs/notification_format.md`](docs/notification_format.md) +- [`docs/notification_format.zh-CN.md`](docs/notification_format.zh-CN.md) +- [`docs/system_design.md`](docs/system_design.md) +- [`docs/system_design.zh-CN.md`](docs/system_design.zh-CN.md) ## 许可证 -如仓库包含 [LICENSE](LICENSE)，请以该文件为准。 +详见 [LICENSE](LICENSE)。