From 311bfd6c0f85813fe56cf973412e0ddcc25943f0 Mon Sep 17 00:00:00 2001 From: Pigbibi <20649888+Pigbibi@users.noreply.github.com> Date: Wed, 3 Jun 2026 17:19:48 +0800 Subject: [PATCH] docs: split bilingual open-source readmes --- README.md | 366 +++++------------------------------------------- README.zh-CN.md | 293 +++++--------------------------------- 2 files changed, 66 insertions(+), 593 deletions(-) diff --git a/README.md b/README.md index 839a913..3a2e7fe 100644 --- a/README.md +++ b/README.md @@ -1,364 +1,64 @@ # ResearchSignalContextPipelines - +[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 | research pipeline | -| What it does | Builds research signal context artifacts for medium-horizon themes and AI shadow context. | -| 中文说明 | 研究信号上下文管线，输出主题、价格、波动和回撤等可审计上下文 artifact。 | -| Current status | Research-only. Outputs are context inputs, not orders or allocation instructions. | +ResearchSignalContextPipelines is a **Research context pipeline** in the QuantStrategyLab ecosystem. It builds research signal context artifacts for medium-horizon themes and long-horizon AI shadow context. -### 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 scheduled/report workflows only after confirming source freshness; do not connect outputs directly to execution. +Research-only artifact pipeline; outputs are context, not trade instructions. -### Strategy performance / evidence boundary +## Repository layout -See `docs/architecture.md` and overlay backtest tests for drawdown and overlay evaluation mechanics. +- `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. +- `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 - - -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 - - -## 中文摘要 - -- 完整中文版见 [`README.zh-CN.md`](README.zh-CN.md)；本节保留在英文文件顶部，方便从当前文件直接找到中文入口。 -- 用途：本文档围绕 `ResearchSignalContextPipelines`，用于理解 `ResearchSignalContextPipelines` 的配置、运行、部署、研究或验收边界。 -- 主要覆盖：`Repository Role`、`Boundary`、`Current Status`、`Operating Model`、`Name and Horizon Boundary`。 -- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。 -- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。 -- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。 -[English](README.md) | [简体中文](README.zh-CN.md) - -Research-only signal context artifact repository for QuantStrategyLab. - -Current schema validation requires newly generated and promoted shadow signal -artifacts to use the `1-3 years` horizon. Older pre-contract artifacts may keep -their original point-in-time horizon text, but they should be treated as legacy -records and not promoted as the current `latest_signal.json`. - -This repository does not place trades, store broker credentials, or own live -allocation policy. It prepares and validates shadow signal artifacts that can -later be consumed by sidecar plugins after a separate review and promotion -process. - -## Repository Role - -This is a research artifact repository, not an agent runner, model gateway, -execution service, or strategy plugin repository. - -Its job is to keep point-in-time research evidence reproducible: - -- build current-market context bundles -- create dated GitHub Issues for operator review -- store schema-valid shadow AI signal artifacts -- preserve `signal_history` for future walk-forward replay -- provide deterministic replay tooling around saved artifacts - -`CodexAuditBridge` remains the only bridge/runner for model providers and -cross-repository write automation. Future live or notification behavior belongs -in a separate deterministic plugin after the shadow artifacts have enough -evidence. - -## Boundary - -This repo owns: - -- long-horizon AI context bundle examples -- shadow signal JSON schema expectations -- validation tooling for `latest_signal.json` -- issue/workflow handoff to `QuantStrategyLab/CodexAuditBridge` -- replay-ready artifact records for later research review - -This repo does not own: - -- broker API access -- order placement -- live portfolio allocation -- deterministic strategy rules in `UsEquityStrategies` -- runtime plugin execution in `QuantStrategyPlugins` -- API keys for model providers -- Codex/OpenAI/Anthropic provider routing -- GitHub App token minting for source repository writes -- Telegram or broker-facing runtime notifications - -## Current Status - -This repository is in shadow research accumulation mode. The first saved -point-in-time artifact is `data/output/signal_history/2026-05-28.json`; the -current promoted artifact is `data/output/signal_history/2026-05-31.json` and -uses the long-horizon contract. - -Near-term work should focus on: - -- keeping the monthly workflow healthy -- accumulating saved `signal_history/*.json` artifacts -- replaying only saved artifacts, not regenerated historical AI judgments -- improving context quality before any downstream plugin integration - -Do not promote the output into runtime allocation or notifications until the -saved artifact history has enough walk-forward evidence to justify a separate -plugin contract. - -## Operating Model - -1. A monthly workflow builds a point-in-time context bundle from current market - prices. -2. The workflow creates or updates a dated long-horizon shadow-signal issue and - embeds the context bundle as review evidence. -3. The issue is dispatched to `QuantStrategyLab/CodexAuditBridge` with task - `long_horizon_signal_shadow`. -4. `CodexAuditBridge` tries self-hosted Codex first and uses its own OpenAI or - Anthropic API fallback only when configured. -5. Any AI-generated artifact must remain `mode=shadow` and pass local schema - validation. -6. Downstream runtimes must treat the artifact as advisory context only until a - separate deterministic policy engine explicitly consumes it. - - -## Name and Horizon Boundary - -`ResearchSignalContextPipelines` is the canonical repository name for this layer. -The name reflects its actual responsibility: maintaining reusable research -context artifacts, including medium-horizon theme momentum and long-horizon AI -shadow context. Short/medium/long final recommendations are still produced by -`QuantAdvisorResearch`, not by this repository. - - -## Horizon Boundary - -This repository does not directly produce short-term buy/sell recommendations. -The horizon split is: - -- Short term (`1-10 trading days`): handled by event evidence from `PoliticalEventTrackingResearch` plus deterministic Advisor rules. AI can explain context but should not decide short-term recommendations. -- Medium term (`2-12 weeks`): represented by `theme_momentum_snapshot.json` as `medium_horizon_theme_context`, including theme momentum, breadth, and strong members inside each theme. -- Long term (`1-3 years`): represented by `latest_signal.json` and `signal_history/*.json` as AI shadow context. - -`QuantAdvisorResearch` remains the only layer that combines these inputs into final short/medium/long recommendations. - -## GitHub Configuration - -The model API keys are centralized in `CodexAuditBridge`; do not add -`OPENAI_API_KEY` or `ANTHROPIC_API_KEY` to this repository. - -This repository needs only dispatch credentials for the bridge workflow: - -- preferred: `CROSS_REPO_GITHUB_APP_ID` variable and - `CROSS_REPO_GITHUB_APP_PRIVATE_KEY` secret with Actions write permission on - `CodexAuditBridge` -- fallback: `CODEX_AUDIT_DISPATCH_TOKEN` secret with permission to dispatch the - bridge workflow - -Configured non-secret variables: - -- `SELFHOSTED_CODEX_REVIEW_REPOSITORY=QuantStrategyLab/CodexAuditBridge` -- `SELFHOSTED_CODEX_REVIEW_PROVIDER=auto` -- `CROSS_REPO_GITHUB_APP_ID=3250578` - -## Notification Policy - -The GitHub issue created by `.github/workflows/dispatch_shadow_signal.yml` is the -initial operator notification channel. It is labeled `long-horizon-shadow`, -deduplicated by date, and receives the CodexAuditBridge result as comments or a -focused PR. - -Do not add Telegram, broker, or runtime plugin notifications at this stage. Those -belong downstream only after the signal graduates from shadow research to a -deterministic plugin contract. - -## Local Validation - -Validate the example artifact: +From a fresh clone: ```bash -python scripts/validate_latest_signal.py examples/latest_signal.example.json +python -m pip install -e . +python -m pytest -q ``` -Build a context bundle from a local price file: +If a command requires credentials, run it only after reading the relevant workflow or runbook and configuring secrets outside Git. -```bash -python scripts/build_context_bundle.py \ - --prices examples/price_history.example.csv \ - --symbols QQQ \ - --output data/output/context_bundle/latest_context_bundle.json -``` +## Deployment and operation -Without `--prices`, the script downloads recent daily prices for the default -universe through Yahoo's chart endpoint and writes a point-in-time context bundle -for the monthly shadow issue. The scheduled workflow uses -`--allow-download-errors`, so external data-source failures still create an -operator issue with the failure recorded instead of silently skipping the run. +Run the configured workflows or local commands to refresh artifacts. Review source coverage and artifact diffs before publishing downstream. -Validate the promoted latest artifact when it exists: +Prefer manual or dry-run execution first. Enable schedules or live execution only after logs, artifacts, permissions, and rollback steps are reviewed. -```bash -python scripts/validate_latest_signal.py -``` - -Run the synthetic overlay replay: - -```bash -python scripts/backtest_signal_overlay.py \ - --prices examples/price_history.example.csv \ - --signals examples/signal_history \ - --symbol QQQ -``` - -The replay tests a deterministic risk-reducing overlay only. It does not call -AI models and does not treat the example as production evidence. +## Strategy performance and evidence -Extract compact real-price input from an existing QuantStrategyLab price file: +Not a trading strategy repository. Evidence quality is measured by source traceability, freshness, and downstream review usefulness. -```bash -python scripts/extract_price_history.py \ - --source ../UsEquitySnapshotPipelines/data/output/tqqq_growth_income_real_full_archive_2026-05-26/price_history.csv \ - --target data/input/qqq_price_history.csv \ - --symbols QQQ -``` - -Then replay stored shadow signals against those prices: +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. -```bash -python scripts/backtest_signal_overlay.py \ - --prices data/input/qqq_price_history.csv \ - --signals data/output/signal_history \ - --symbol QQQ \ - --output data/output/tmp/replay_summary.json -``` +## Safety notes -The price loader accepts both this repository's compact `date,symbol,close` -schema and the existing QuantStrategyLab `symbol,as_of,close` schema. +- 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. -## Artifact Contract +## Contributing -The latest artifact path is: - -```text -data/output/latest_signal.json -``` - -Historical generated copies can be stored under: - -```text -data/output/signal_history/YYYY-MM-DD.json -``` - -All promoted latest artifacts must use `horizon: "1-3 years"`. To support -Advisor long-horizon buckets, current artifacts should also include versioned -theme context through `theme_bias`, `symbol_theme_exposure`, and optional -`symbol_bias` for symbols that need explicit long-context coverage. - -All artifacts must remain shadow-only. They cannot encode broker orders, target -quantities, or live allocation overrides. - -`candidate_bias` and `theme_bias` may use either the legacy compact form: - -```json -{"MU": "watch"} -``` - -or the structured audit form: - -```json -{ - "MU": { - "bias": "watch", - "confidence": 0.55, - "linked_themes": ["hbm_memory"], - "rationale": "Shadow context only; not a trade instruction." - } -} -``` - -`symbol_bias` is optional and uses the same structured shape for symbol-specific -long-horizon context. Downstream Advisor code treats these fields as context and -still blocks orders, target quantities, and portfolio weights. - -## Replay Contract - -Historical validation should replay stored signal artifacts instead of asking a -model to re-create old judgments. The current example policy is intentionally -conservative: - -- no active signal: keep baseline exposure -- `confidence < 0.55`: no-op -- `risk_off`: reduce exposure to `0.5` -- `mixed`: reduce exposure to `0.8` -- severe risk flags such as `liquidity_stress` cap exposure at `0.6` -- the overlay never increases exposure above the baseline +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. ## License -This repository is licensed under the MIT License. See [LICENSE](LICENSE). - -## Cross-Sector Theme Universe - -The repository now keeps a static, versioned cross-sector theme universe instead -of limiting long-horizon research to the current AI trade: - -```text -config/theme_taxonomy.csv -config/symbol_theme_exposure.csv -``` - -The taxonomy covers AI compute, HBM/memory, foundry policy, AI servers, -data-center power, cybersecurity, defense/aerospace, energy security, clean grid, -financial infrastructure, healthcare policy, consumer platforms, industrial -automation, crypto infrastructure, and EV/auto transition. - -Theme membership is research context, not a hot-list override. Monthly context -bundles embed `theme_context`; downstream use remains shadow-only and must replay -saved artifacts rather than regenerating historical AI judgments. - -## Scheduled Theme Momentum Refresh - -`.github/workflows/theme_momentum_snapshot.yml` runs weekly before the advisor -publication workflow. It builds `data/output/theme_momentum_snapshot.json` as -`medium_horizon_theme_context` for the `2-12 weeks` horizon and, -on scheduled runs, commits the changed snapshot back to the repository so -`QuantAdvisorResearch` can consume a point-in-time artifact. Manual runs can pass -`prices_path` to use an audited local CSV instead of Yahoo chart downloads. - -Yahoo chart downloads remain a temporary fallback only. The snapshot records -source metadata and file hashes when a local price CSV is used. Random free proxy -pools should not be used in this stable pipeline because they make replay, data -quality, and compliance review harder. - -## Theme Momentum Snapshot - -The static taxonomy only defines long-horizon theme membership. Ranking is done -by a separate theme momentum snapshot so the universe and weights are not changed -just because a currently popular symbol has moved. - -Build from a local price CSV: - -```bash -python scripts/build_theme_momentum_snapshot.py \ - --prices data/input/theme_price_history.csv \ - --symbols MU,INTC,DELL,NVDA,VRT,UNH,XOM,JPM,LMT \ - --output data/output/theme_momentum_snapshot.json -``` - -If `--prices` is omitted, the script downloads Yahoo chart data. Partial symbol -failures are recorded in `data_quality.missing_price_symbols` by default; -`--strict-downloads` turns those into hard failures. - -The snapshot records `artifact_type=medium_horizon_theme_context`, horizon metadata, fixed 12-1m, 6-1m, and 3m momentum windows, breadth, risk -penalties, top symbols per theme, source metadata, and a policy block that keeps -the artifact research-only. `data_quality.coverage` now records configured -symbol count, priced symbol count, price coverage ratio, and symbols with -insufficient price history. +See [LICENSE](LICENSE) if present in this repository. diff --git a/README.zh-CN.md b/README.zh-CN.md index 2bede02..4a2fb02 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,291 +1,64 @@ # ResearchSignalContextPipelines -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 - - -## English summary - -- Full English version: [`README.md`](README.md). This summary keeps an English entry point in the Chinese file. -- Purpose: this document covers `ResearchSignalContextPipelines` for `ResearchSignalContextPipelines`. -- Main topics: `仓库定位`, `边界`, `当前状态`, `运行模式`, `名称和周期边界`. -- 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) | [简体中文](README.zh-CN.md) - -QuantStrategyLab 的研究型信号上下文 artifact 仓库。 - -当前 schema validation 要求新生成和 promoted 的 shadow signal artifact 使用 `1-3 years` 周期。较早的 pre-contract 历史 artifact 可以保留原始点时 horizon 文本，但不应再作为当前 `latest_signal.json` 推广。 - -本仓库不下单、不保存券商凭证，也不拥有实盘仓位策略。它只负责准备、校验、保存和回放研究信号上下文，包括中线主题动量和长周期 AI shadow signal。任何未来的下游使用，都必须经过单独评审，并由确定性插件或策略显式消费。 - -## 仓库定位 - -这是一个 research artifact repository，不是 agent runner、模型网关、执行服务或策略插件仓。 - -本仓库的职责是让点时研究证据可复现： - -- 构建当前市场 context bundle -- 创建带日期的 GitHub Issue 供 operator 审阅 -- 保存 schema-valid 的 shadow AI signal artifacts -- 保存 `signal_history` 供未来 walk-forward replay -- 围绕已保存 artifacts 提供确定性 replay 工具 +[English README](README.md) -`CodexAuditBridge` 仍然是唯一的模型 provider bridge/runner，负责模型 API、跨仓写权限和 PR/Issue 自动化。未来如果要接入实盘或通知系统，应在积累足够 shadow evidence 后，另建确定性插件 contract。 - -## 边界 +> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 -本仓库负责： +## 这个项目做什么 -- 长周期 AI context bundle 示例和生成工具 -- 中线主题动量 taxonomy、symbol exposure 和 snapshot 生成工具 -- shadow signal JSON schema 约束 -- `latest_signal.json` 校验工具 -- 向 `QuantStrategyLab/CodexAuditBridge` 交接 issue/workflow -- 可 replay 的 artifact 记录 +ResearchSignalContextPipelines 是 QuantStrategyLab 体系中的**研究上下文流水线**。生成中期主题和长期 AI shadow context 使用的研究信号上下文产物。 -本仓库不负责： +## 适合谁使用 -- 券商 API 访问 -- 下单 -- 实盘组合配置 -- `UsEquityStrategies` 中的确定性策略规则 -- `QuantStrategyPlugins` 中的运行时插件执行 -- 模型 provider API keys -- Codex/OpenAI/Anthropic provider routing -- source repo 写权限的 GitHub App token minting -- Telegram 或券商侧运行时通知 +- 希望阅读、复现或扩展 QuantStrategyLab 相关模块的工程师和研究人员。 +- 在阅读详细 runbook 或 workflow 前，需要先理解项目入口的运维人员。 +- 在启用自动化前，需要确认项目职责、安全边界和证据要求的 reviewer。 ## 当前状态 -本仓库处于 shadow research accumulation mode。第一条已保存的点时 artifact 是： - -```text -data/output/signal_history/2026-05-28.json -``` - -当前 promoted artifact 是： - -```text -data/output/signal_history/2026-05-31.json -``` - -它使用长线 contract，并补充了 `theme_bias`、`symbol_theme_exposure` 和 `symbol_bias`，供 Advisor 判断长线背景是否可用。 - -近期工作重点： - -- 保持周度主题动量 workflow 和月度 AI shadow workflow 健康 -- 持续积累 `signal_history/*.json` -- 只 replay 已保存 artifacts，不让模型重新生成历史判断 -- 在任何下游插件集成前，先提升 context 质量并积累证据 - -在 `signal_history` 积累出足够 walk-forward evidence 之前，不应把输出接入运行时仓位或通知系统。 - -## 运行模式 - -1. 月度 workflow 根据当前市场价格构建 point-in-time context bundle。 -2. workflow 创建或更新带日期的 long-horizon shadow-signal issue，并把 context bundle 嵌入 issue 作为审阅证据。 -3. issue 被 dispatch 到 `QuantStrategyLab/CodexAuditBridge`，任务类型是 `long_horizon_signal_shadow`。 -4. `CodexAuditBridge` 优先运行 self-hosted Codex；只有在配置允许时才使用 OpenAI 或 Anthropic API fallback。 -5. 所有 AI 生成的 artifact 必须保持 `mode=shadow`，并通过本地 schema validation。 -6. 下游系统在单独的确定性 policy engine 显式消费前，只能把 artifact 当作 advisory context。 - - -## 名称和周期边界 - -`ResearchSignalContextPipelines` 是这一层的正式仓库名。这个名字对应它现在的真实职责：维护可复用的研究上下文 artifact，包括中线主题动量和长线 AI shadow context。短线/中线/长线最终推荐仍由 `QuantAdvisorResearch` 生成，本仓库不直接输出最终推荐。 - - -## 短中长线边界 - -本仓库不直接输出短线买卖推荐。周期分工保持如下： - -- 短线（1-10 个交易日）：由 `PoliticalEventTrackingResearch` 的事件和 `QuantAdvisorResearch` 的确定性规则处理；AI 只可作为解释背景，不直接决定短线。 -- 中线（2-12 周）：由本仓库的 `theme_momentum_snapshot.json` 提供 `medium_horizon_theme_context`，包括主题动量、主题广度和主题内强势标的。 -- 长线（1-3 年）：由本仓库的 `latest_signal.json` / `signal_history/*.json` 提供 AI shadow context。 - -最终短线、中线、长线推荐统一由 `QuantAdvisorResearch` 合成，本仓库仍不下单、不配仓、不输出账户级建议。 - -## GitHub 配置 - -模型 API key 集中在 `CodexAuditBridge`；不要把 `OPENAI_API_KEY` 或 `ANTHROPIC_API_KEY` 放到本仓库。 - -本仓库只需要 bridge workflow dispatch 凭证： - -- 推荐：`CROSS_REPO_GITHUB_APP_ID` variable 和 `CROSS_REPO_GITHUB_APP_PRIVATE_KEY` secret，且该 GitHub App 对 `CodexAuditBridge` 有 Actions write 权限 -- fallback：`CODEX_AUDIT_DISPATCH_TOKEN` secret，具备 dispatch bridge workflow 的权限 - -已配置的非 secret variables： - -- `SELFHOSTED_CODEX_REVIEW_REPOSITORY=QuantStrategyLab/CodexAuditBridge` -- `SELFHOSTED_CODEX_REVIEW_PROVIDER=auto` -- `CROSS_REPO_GITHUB_APP_ID=3250578` - -## 通知策略 - -`.github/workflows/dispatch_shadow_signal.yml` 创建的 GitHub Issue 是当前 operator notification channel。Issue 使用 `long-horizon-shadow` label，按日期去重，并接收 `CodexAuditBridge` 的审计回帖或 artifact PR。 - -当前阶段不要添加 Telegram、券商或 runtime plugin 通知。这些应在 shadow signal 晋级为确定性插件 contract 后，由下游系统负责。 - -## 本地验证 - -校验示例 artifact： - -```bash -python scripts/validate_latest_signal.py examples/latest_signal.example.json -``` - -从本地价格文件构建 context bundle： - -```bash -python scripts/build_context_bundle.py \ - --prices examples/price_history.example.csv \ - --symbols QQQ \ - --output data/output/context_bundle/latest_context_bundle.json -``` - -不传 `--prices` 时，脚本会通过 Yahoo chart endpoint 下载默认 universe 的近期日线价格，并写出月度 shadow issue 使用的 point-in-time context bundle。定时 workflow 使用 `--allow-download-errors`，所以外部数据源失败时仍会创建 operator issue，并把失败原因写入 context。 +只用于研究产物生成；输出是上下文，不是交易指令。 -校验已 promoted 的 latest artifact： +## 仓库结构 -```bash -python scripts/validate_latest_signal.py -``` - -运行合成 overlay replay： - -```bash -python scripts/backtest_signal_overlay.py \ - --prices examples/price_history.example.csv \ - --signals examples/signal_history \ - --symbol QQQ -``` +- `src/`：主要库代码和运行时代码。 +- `tests/`：单元测试和契约测试。 +- `docs/`：详细设计说明、运行手册和证据文档。 +- `.github/workflows/`：CI、定时任务和部署 workflow。 +- `scripts/`：运维脚本和本地辅助工具。 -这个 replay 只测试确定性的 risk-reducing overlay。它不调用 AI model，也不把示例结果当作生产证据。 +## 快速开始 -从现有 QuantStrategyLab 价格文件抽取紧凑 replay 输入： +从全新 clone 开始： ```bash -python scripts/extract_price_history.py \ - --source ../UsEquitySnapshotPipelines/data/output/tqqq_growth_income_real_full_archive_2026-05-26/price_history.csv \ - --target data/input/qqq_price_history.csv \ - --symbols QQQ +python -m pip install -e . +python -m pytest -q ``` -然后用已保存的 shadow signals replay： - -```bash -python scripts/backtest_signal_overlay.py \ - --prices data/input/qqq_price_history.csv \ - --signals data/output/signal_history \ - --symbol QQQ \ - --output data/output/tmp/replay_summary.json -``` - -price loader 同时支持本仓库的紧凑 `date,symbol,close` schema，以及现有 QuantStrategyLab 的 `symbol,as_of,close` schema。 - -## Artifact Contract - -latest artifact 路径： - -```text -data/output/latest_signal.json -``` - -历史副本路径： - -```text -data/output/signal_history/YYYY-MM-DD.json -``` +如果命令需要凭据，请先阅读相关 workflow 或 runbook，并把密钥配置在 Git 之外。 -所有 promoted latest artifacts 必须使用 `horizon: "1-3 years"`。为了支持 Advisor 的长线栏位，当前 artifact 应包含 `theme_bias`、`symbol_theme_exposure`，必要时用 `symbol_bias` 补充单个股票的长线背景。 +## 部署和运行 -所有 artifacts 必须保持 shadow-only。它们不能编码券商订单、目标数量或实盘 allocation override。 +通过配置好的 workflow 或本地命令刷新产物。发布到下游前，应检查来源覆盖和产物 diff。 -`candidate_bias` 和 `theme_bias` 支持两种写法。兼容旧的紧凑写法： +建议先手工运行或 dry-run。只有在日志、产物、权限和回滚步骤都检查过之后，才启用定时任务或 live 执行。 -```json -{"MU": "watch"} -``` +## 策略表现与证据边界 -也支持更适合审计的结构化写法： +这不是交易策略仓库。证据质量主要看来源可追溯性、 freshness 和下游审阅价值。 -```json -{ - "MU": { - "bias": "watch", - "confidence": 0.55, - "linked_themes": ["hbm_memory"], - "rationale": "只作为 shadow context，不是交易指令。" - } -} -``` +README 不应该承诺固定收益或过期指标。实际使用前，请重新运行对应测试、回测或流水线任务。 -`symbol_bias` 是可选字段，使用同样结构表达单个 symbol 的长线背景。下游 Advisor 只把这些字段当作上下文，仍然禁止订单、目标股数和组合权重。 +## 安全注意事项 -## Replay Contract +- 不要把 API key、券商凭据、OAuth token、Cookie 或账户标识提交到 Git。 +- 新策略或平台变更在 live 前必须先跑 dry-run 或 paper 流程。 +- 启用定时任务前，需要人工检查生成的订单、产物和日志。 -历史验证必须 replay 已保存 signal artifacts，而不是让模型重新生成过去的判断。当前示例 policy 有意保持保守： +## 参与贡献 -- 没有 active signal：保持 baseline exposure -- `confidence < 0.55`：no-op -- `risk_off`：降到 `0.5` -- `mixed`：降到 `0.8` -- 严重 risk flags，例如 `liquidity_stress`，把 exposure cap 到 `0.6` -- overlay 永远不能把 exposure 提高到 baseline 以上 +请保持改动小、可复现，并用最小必要测试覆盖。涉及策略的改动，需要附上验证行为的证据产物或命令。 ## 许可证 -本仓库使用 MIT License。详见 [LICENSE](LICENSE)。 - -## 跨板块主题 universe - -本仓库现在不仅覆盖 AI 主题，也固定维护一个跨板块长期主题 taxonomy： - -```text -config/theme_taxonomy.csv -config/symbol_theme_exposure.csv -``` - -覆盖方向包括 AI compute、HBM/存储、foundry/半导体政策、AI server、数据中心电力、网络安全、国防航天、能源安全、清洁电网、金融基础设施、医疗政策、消费平台、工业自动化、crypto 基础设施和 EV/汽车。 - -这些配置是长期研究上下文，不是热点追涨列表。月度 context bundle 会把主题暴露写入 `theme_context`，供 AI shadow review 使用；任何推荐或回测仍必须基于已保存 artifact，不能在回测时重新生成历史判断。 - -## 主题动量定时刷新 - -`.github/workflows/theme_momentum_snapshot.yml` 每周在 Advisor 发布前运行，生成 `data/output/theme_momentum_snapshot.json`。该 artifact 明确标记为 `medium_horizon_theme_context`，对应中线 2-12 周主题上下文。定时运行时如果快照有变化，会提交回仓库，供 `QuantAdvisorResearch` 读取点时 artifact。手工运行可以传 `prices_path`，使用可审计的本地价格 CSV，而不是临时下载。 - -Yahoo chart 下载仍然只是临时 fallback。使用本地价格 CSV 时，快照会记录来源和文件 hash。随机免费代理 IP 池不应进入稳定链路，因为它会增加 replay、数据质量和合规复核难度。 - -## 主题动量快照 - -跨板块主题 taxonomy 只是定义“股票属于哪些长期主题”。真正的排序由独立的主题动量快照完成，避免因为近期热门标的临时改 universe 或权重。 - -使用本地价格 CSV 生成快照： - -```bash -python scripts/build_theme_momentum_snapshot.py \ - --prices data/input/theme_price_history.csv \ - --symbols MU,INTC,DELL,NVDA,VRT,UNH,XOM,JPM,LMT \ - --output data/output/theme_momentum_snapshot.json -``` - -不传 `--prices` 时脚本会通过 Yahoo chart endpoint 下载价格。默认允许部分 symbol 下载失败，失败标的会进入 `data_quality.missing_price_symbols`；如果需要严格模式，传 `--strict-downloads`。 - -快照会输出： - -- `theme_ranks`：主题排名、动量分、breadth、风险惩罚和主题内 top symbols -- `methodology`：固定窗口和权重，便于后续 walk-forward replay -- `artifact_type`：`medium_horizon_theme_context`，表示中线主题上下文，不是短线 AI 推荐 -- `horizon` / `horizon_window`：`medium` / `2-12 weeks` -- `policy`：明确这是研究排序，不允许下单或仓位分配 -- `data_quality.coverage`：配置标的数、已有价格标的数、价格覆盖率和价格历史不足标的 - -当前固定窗口： - -- `12-1m`：252 个交易日 lookback，跳过最近 21 个交易日 -- `6-1m`：126 个交易日 lookback，跳过最近 21 个交易日 -- `3m`：63 个交易日近期动量 - -主题排名只说明“哪些主题值得研究”，不是买入信号。进入 Advisor 推荐仍需要事件证据、来源质量和风险检查。 +如仓库包含 [LICENSE](LICENSE)，请以该文件为准。