diff --git a/README.md b/README.md index 25ea070..738a54e 100644 --- a/README.md +++ b/README.md @@ -1,453 +1,64 @@ # QuantAdvisorResearch - +[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 publisher | -| What it does | Publishes advisory research reports from web/RSS, market confirmation and review artifacts without creating orders. | -| 中文说明 | 投研报告生成与发布系统，整合新闻/RSS、市场确认和复盘，不生成订单或账户建议。 | -| Current status | Research-only publisher. It must stay separate from execution systems. | +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. -### 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 its publishing workflows after checking sources and output destination. Do not store API keys in README or artifacts. +Research and publishing system; outputs require human review before use. -### Strategy performance / evidence boundary +## Repository layout -Recommendation review artifacts track absolute/relative returns for accountability; see `docs/system_design.md` and `.zh-CN.md`. +- `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)；本节保留在英文文件顶部，方便从当前文件直接找到中文入口。 -- 用途：本文档围绕 `QuantAdvisorResearch`，用于理解 `QuantAdvisorResearch` 的配置、运行、部署、研究或验收边界。 -- 主要覆盖：`Repository Role`、`Horizon Source Split`、`Boundary`、`AI Usage`、`Local Example`。 -- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。 -- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。 -- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。 -[English](README.md) | [简体中文](README.zh-CN.md) - -Intelligent advisory research system for QuantStrategyLab. - -This repository combines deterministic event evidence, theme momentum, market -confirmation, and saved AI shadow context into investor-readable advisory -research reports. It does not place orders, store broker credentials, manage -portfolios, or personalize advice for a specific investor. - -## Repository Role - -`QuantAdvisorResearch` is the coordinator for the Intelligent Advisory Research -System: - -- consume political/public-event context from `PoliticalEventTrackingResearch` -- consume saved AI shadow context from `ResearchSignalContextPipelines` -- keep other strategy and snapshot repositories independent from this pipeline -- leave broker execution in platform repositories - -The current operating cadence is a weekly public intelligent-advisory snapshot, -supported by weekly event/theme refreshes and monthly long-horizon AI shadow -context. Monthly review reports are generated separately for change review and -month-end inspection. They do not replace the weekly publication while -short-horizon windows are part of the contract. - -Live site: - - - -Key documents: - -- [System design](docs/system_design.md) / [系统设计](docs/system_design.zh-CN.md) -- [Data and factor roadmap](docs/data_factor_roadmap.md) / [数据源与因子路线](docs/data_factor_roadmap.zh-CN.md) -- [Notification format](docs/notification_format.md) / [通知格式](docs/notification_format.zh-CN.md) -- [Artifact contract](docs/advisory_contract.md) - - -## Horizon Source Split - -Advisor is the final composition layer. Source ownership by horizon is: - -- Short term (`1-10 trading days`): event and policy/news catalysts plus generated `market_confirmation.csv`, focused on relative strength, volume, drawdown, and volatility. -- Medium term (`2-12 weeks`): `theme_momentum_snapshot.json` from `ResearchSignalContextPipelines`, now explicitly marked as `medium_horizon_theme_context`, focused on theme momentum and symbol momentum. -- Long term (`1-3 years`): `latest_signal.json` / `signal_history/*.json` from `ResearchSignalContextPipelines` as AI shadow context. - -Final recommendations are still deterministic Intelligent Advisory outputs. The signal context repository does not directly produce short-term recommendations or replace the final decision engine. Advisor records separate short/medium/long horizon scores and gates for each final pick, plus JSON diagnostics that explain whether long-horizon context was actually available. Public pages render short and medium columns from the pick's primary horizon, while the long column can also show long-horizon context when no primary long bucket exists. Horizon actions remain in JSON as diagnostics, but they are not all promoted to public short/medium columns. - -## Boundary - -This repository owns: - -- intelligent advisory artifact schemas -- deterministic scoring and review policy -- daily/weekly/monthly report generation -- evidence and risk summaries -- intelligent advisory history for later review - -This repository does not own: - -- broker API access or order placement -- target quantities, portfolio weights, or account rebalancing -- investor-specific suitability decisions -- model provider routing or prompt execution -- raw paid market-data redistribution - -## AI Usage - -This repository does not call Codex, OpenAI, Anthropic, or any other model API. -It only consumes saved `mode=shadow` artifacts from `ResearchSignalContextPipelines`. -The only repository in this three-repo flow that can involve AI is -`ResearchSignalContextPipelines`, and even there provider execution is delegated to -`QuantStrategyLab/CodexAuditBridge`. Model API keys and fallback routing belong -there, not in this repository. - -## Local Example - -Build the full artifact set the same way GitHub Actions does: - -```bash -python scripts/build_advisory_artifacts.py \ - --as-of 2026-05-30 \ - --cadence weekly \ - --political-events examples/political_events.example.csv \ - --political-watchlist examples/political_watchlist.example.csv \ - --ai-signal examples/research_signal_context.example.json \ - --theme-momentum examples/theme_momentum_snapshot.example.json \ - --market-no-network \ - --market-cache-dir .cache/market-data \ - --recommendation-review \ - --output-dir data/output/weekly_advisory_review \ - --site-output-dir site -``` - -This single command can generate market confirmation, the advisory JSON/Markdown, -manifest, optional monthly review, optional recommendation follow-up review, and -optional static site output. The weekly, monthly, and Pages workflows all use -this shared build path so report generation does not drift between publication -modes. - -The lower-level report builder is still available for focused debugging: - -```bash -python scripts/build_advisory_report.py \ - --as-of 2026-05-30 \ - --cadence weekly \ - --political-events examples/political_events.example.csv \ - --political-watchlist examples/political_watchlist.example.csv \ - --ai-signal examples/research_signal_context.example.json \ - --output-json data/output/advisory_report.example.json \ - --output-md data/output/advisory_report.example.md -``` - -The command also writes `data/output/advisory_report.example.json.manifest.json`. - -Run tests: +From a fresh clone: ```bash +python -m pip install -e . python -m pytest -q ``` -Build the weekly report from sibling checkouts: - -```bash -python scripts/build_advisory_report.py \ - --as-of 2026-05-30 \ - --cadence weekly \ - --political-events ../PoliticalEventTrackingResearch/examples/political_events.example.csv \ - --political-watchlist ../PoliticalEventTrackingResearch/examples/political_watchlist.example.csv \ - --ai-signal ../ResearchSignalContextPipelines/data/output/latest_signal.json \ - --output-json data/output/weekly_advisory_review/advisory_report_2026-05-30.json \ - --output-md data/output/weekly_advisory_review/advisory_report_2026-05-30.md -``` - -`.github/workflows/weekly_advisory_review.yml` runs the same command on a weekly -schedule and uploads the report as a GitHub Actions artifact. It does not commit -files, create orders, or notify investors. - -`.github/workflows/publish_advisory_site.yml` publishes the HTML/JSON/RSS site on -a weekly schedule. If `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are configured -as repository secrets, the workflow sends a short intelligent-advisory Telegram -summary after a successful Pages deployment. If either secret is missing, the -notification step is skipped without failing the publication. Telegram delivery -errors are logged and do not block Pages/RSS output. - -The weekly publication cadence is intentional: the report contract still -contains short-horizon (`1-10 trading days`) and medium-horizon (`2-12 weeks`) -windows, so a monthly-only public report would make short-horizon conclusions -stale. The AI shadow input remains monthly because it is long-horizon context, -not a weekly trading signal. - -Build the separate monthly review artifact: - -```bash -python scripts/build_monthly_review.py \ - --current-report data/output/weekly_advisory_review/advisory_report_2026-05-30.json \ - --output-json data/output/monthly_advisory_review/monthly_review_2026-05-30.json \ - --output-md data/output/monthly_advisory_review/monthly_review_2026-05-30.md -``` - -`.github/workflows/monthly_advisory_review.yml` runs monthly and uploads the -monthly report/review artifacts only. It is intentionally separate from the -weekly public HTML/RSS publication. - -Publish a static HTML + RSS preview: - -```bash -python scripts/publish_advisory_site.py \ - --reports data/output/weekly_advisory_review/advisory_report_2026-05-30.json \ - --output-dir site \ - --site-url https://quantstrategylab.github.io/QuantAdvisorResearch -``` - -Open `site/index.html` locally or subscribe to `site/feed.xml`. The static site also writes `site/archive.html` and `site/reports_index.json`: the homepage keeps the latest report plus the most recent 12 historical entries, while the archive page keeps all generated reports grouped by month. The RSS feed keeps the most recent 20 items. The workflow -`.github/workflows/publish_advisory_site.yml` deploys the same output to -GitHub Pages: - - - -The published HTML, RSS feed title, and Telegram summary default to Simplified -Chinese (`zh-CN`) and use the public-facing Intelligent Advisory Research System wording because the current audience is Chinese-language retail research readers. JSON field names remain stable English contract keys. - -The scheduled publish workflow defaults to live source artifacts inside sibling -repositories. Manual dispatch can normally pass only `as_of`; override paths only -when intentionally testing a different artifact: - -```bash -gh workflow run "Publish Intelligent Advisory Site" \ - --repo QuantStrategyLab/QuantAdvisorResearch \ - -f as_of=2026-05-30 -``` - -Notification channel rules are documented in -[`docs/notification_format.md`](docs/notification_format.md) and -[`docs/notification_format.zh-CN.md`](docs/notification_format.zh-CN.md). - -Backfill a local static archive from downloaded workflow artifacts: - -```bash -python scripts/backfill_site_archive.py \ - --artifact-root path/to/downloaded/actions/artifacts \ - --output-dir site \ - --site-url https://quantstrategylab.github.io/QuantAdvisorResearch -``` - -Run a deterministic cross-repository smoke test without live price downloads: +If a command requires credentials, run it only after reading the relevant workflow or runbook and configuring secrets outside Git. -```bash -python scripts/run_cross_repo_smoke.py \ - --as-of 2026-05-30 \ - --political-events ../PoliticalEventTrackingResearch/data/live/political_events.csv \ - --political-watchlist ../PoliticalEventTrackingResearch/data/live/political_watchlist.csv \ - --ai-signal ../ResearchSignalContextPipelines/data/output/latest_signal.json \ - --theme-momentum ../ResearchSignalContextPipelines/data/output/theme_momentum_snapshot.json \ - --work-dir data/output/cross_repo_smoke -``` +## Deployment and operation -`.github/workflows/cross_repo_smoke.yml` runs the same no-network smoke on a -weekly schedule and uploads the generated report/site artifacts for inspection. +Configure data sources, publishing credentials, and scheduled workflows. Start with a manual run, inspect generated content and citations, then enable schedule. -## Market Confirmation +Prefer manual or dry-run execution first. Enable schedules or live execution only after logs, artifacts, permissions, and rollback steps are reviewed. -`scripts/build_market_confirmation.py` collects symbols from the watchlist, -signal context, and theme momentum snapshot, then writes a -`market_confirmation.csv` file: - -```bash -python scripts/build_market_confirmation.py \ - --as-of 2026-05-30 \ - --political-watchlist examples/political_watchlist.example.csv \ - --ai-signal examples/research_signal_context.example.json \ - --theme-momentum examples/theme_momentum_snapshot.example.json \ - --output data/output/market_confirmation_2026-05-30.csv -``` +## Strategy performance and evidence -The generated columns include `return_5d`, `return_20d`, `return_63d`, -relative returns versus SPY, volume z-score, 63-day drawdown, 21-day annualized -volatility, `market_score`, `price_age_days`, `confirmation_quality`, data -source, row count, and warnings. The weekly/monthly/publish workflows generate -this file automatically before building advisory reports. +Not a trading strategy repository. Evaluate it by evidence quality, citation accuracy, freshness, and whether outputs avoid account-specific investment advice. -Optional proxy inputs: +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. -- `--proxy-urls`: comma/newline-separated proxy URLs. -- `--proxy-list`: local text file with one proxy per line. -- `--proxy-pool-url`: public text URL returning one proxy per line. -- `--cache-dir`: local directory for saved point-in-time Yahoo daily bars. -- `--cache-max-age-days`: maximum accepted cache staleness when live fetches fail. +## Safety notes -The scheduled workflows also read repository variables `MARKET_DATA_PROXY_URLS` -and `MARKET_DATA_PROXY_POOL_URL`. The script tries direct Yahoo access first and -then retries through proxies. Logs record proxy indexes only, not full proxy -URLs. - -Yahoo chart is currently the no-dependency free price endpoint. If it is -unavailable, the script falls back to price-momentum fields already saved in -`theme_momentum_snapshot.json`, so report generation continues. Random free -proxy pools can be used as an emergency supplement, but should not be treated as -a stable production data source; prefer organization-owned price snapshots, -caches, or auditable controlled proxies. The scheduled workflows restore and -save `.cache/market-data` with GitHub Actions cache, so one successful price run -can support later recommendation review and temporary Yahoo outages. - -## Recommendation Follow-up Review - -`scripts/build_recommendation_review.py` reviews past final recommendations -against cached point-in-time prices. It is a research audit artifact, not a new -recommendation list. - -```bash -python scripts/build_recommendation_review.py \ - --as-of 2026-06-30 \ - --reports data/output/weekly_advisory_review/advisory_report_2026-05-30.json \ - --benchmark SPY \ - --cache-dir .cache/market-data \ - --output-json data/output/recommendation_review_2026-06-30.json \ - --output-md data/output/recommendation_review_2026-06-30.md -``` +- 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. -The review calculates absolute return, benchmark-relative return, outcome -labels, horizon summaries, and data-quality warnings. The unified build command -can generate it with `--recommendation-review`; the Pages workflow also includes -recovered published reports when available, so the review improves as history -accumulates. +## Contributing -## Output Contract - -The main JSON artifact is `ModelRecommendationReport`: - -```text -schema_version = 5 -as_of -generated_at -mode = model_recommendations -cadence = daily | weekly | monthly -audience_scope = non_personalized_model_research -policy.non_personalized_recommendations_allowed = true -policy.execution_allowed = false -policy.portfolio_allocation_allowed = false -policy.account_specific_advice_allowed = false -recommendations[] -theme_first_candidates[] -``` - -Each recommendation carries: - -```text -symbol -rating -rating_label -recommendation_tier -recommendation_tier_label -primary_horizon -primary_horizon_label -primary_horizon_window -horizon_note -suitable_horizons[] -suitable_horizon_windows{} -strategy_style -score -evidence_score -risk_score -source_confidence -source_confidence_label -reasons[] -risk_notes[] -evidence_refs[] -review_checklist[] -``` - -`theme_first_candidates[]` is an optional internal explanation artifact derived -from the theme momentum snapshot. The current public HTML, RSS, and Telegram -outputs show only final recommendations; theme candidates remain available in -JSON/Markdown for audit and future review. They are still research-only and must -not encode orders, target weights, or account-level advice. - -Default horizon windows: - -- short: `1-10 trading days` -- medium: `2-12 weeks` -- long: `1-3 years` -- not_applicable: source check, defer, or background tracking only - -## Versioning - -The Python package version is `0.1.3`. Report artifacts are versioned separately: - -- report schema: `schema_version = 5` -- report contract: `model_recommendations.v5` -- report manifest: `.manifest.json` - -The manifest records the JSON and Markdown SHA256 hashes, `as_of`, cadence, -source artifacts, policy boundary, Git SHA, GitHub run id, and contract version. -This mirrors the snapshot and AI artifact repos without turning recommendations -into executable strategy targets. - -## Source Mode - -Reports built from `examples/` inputs are still marked `source_mode=fixture` in -JSON, but public HTML/RSS/Telegram output no longer displays fixture or source-mode -badges. Scheduled weekly/monthly and Pages workflows default to `data/live/*` -inputs from `PoliticalEventTrackingResearch`, so published reports should be -`source_mode=operator_supplied` in the audit artifact. - -`source_mode` remains in the JSON contract for auditability only. - -## Regulatory Boundary - -Even when no orders or allocations are generated, specific securities -recommendations can still raise investment-adviser or broker-dealer obligations -depending on compensation, audience, personalization, and business model. This -repository therefore keeps recommendations non-personalized and blocks execution, -allocation, and account-specific advice. - -See: - -- SEC investment adviser definition: -- SEC automated investment advice resources: -- FINRA Regulation Best Interest: -- FINRA suitability: - -## Theme Momentum Display - -`build_advisory_report.py` accepts an optional theme momentum snapshot: - -```bash -python scripts/build_advisory_report.py \ - --as-of 2026-05-30 \ - --cadence weekly \ - --political-events examples/political_events.example.csv \ - --political-watchlist examples/political_watchlist.example.csv \ - --ai-signal examples/research_signal_context.example.json \ - --theme-momentum examples/theme_momentum_snapshot.example.json \ - --market-confirmation examples/market_confirmation.example.csv \ - --output-json data/output/advisory_report.example.json \ - --output-md data/output/advisory_report.example.md -``` +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. -Theme momentum is explanation-first context: it highlights strong themes and -creates `theme_first_candidates[]` for JSON/Markdown audit material. The public -HTML, RSS, and Telegram outputs stay focused on final recommendations only, so -theme candidates are not mistaken for a buy list. The base `recommendations[]` -rating still comes from event/watchlist/AI evidence; `final_decisions` can use -medium-horizon theme momentum plus optional market confirmation to rank the final -public list. It never changes allocation or execution policy. Workflows skip this -context when the snapshot file is absent. +## License -Yahoo chart downloads are only a temporary fallback. Do not rely on random free -proxy pools for the stable pipeline; prefer audited price snapshots, cache files, -or a controlled proxy/data provider. +See [LICENSE](LICENSE) if present in this repository. diff --git a/README.zh-CN.md b/README.zh-CN.md index 16d982b..bb694d6 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,298 +1,64 @@ # QuantAdvisorResearch -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 - - -## English summary - -- Full English version: [`README.md`](README.md). This summary keeps an English entry point in the Chinese file. -- Purpose: this document covers `QuantAdvisorResearch` for `QuantAdvisorResearch`. -- Main topics: `仓库定位`, `短中长线来源分工`, `当前 MVP`, `版本管理`, `来源模式`. -- 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 的“智慧投顾研究系统”协调仓库。它把事件证据、主题动量、市场确认和 AI shadow 背景整理成普通投资者能读懂的研究结论；不下单、不管理仓位、不接券商凭证，也不做账户级个性化建议。 - -线上站点： - -主要文档： - -- [系统设计](docs/system_design.zh-CN.md) / [System design](docs/system_design.md) -- [数据源与因子路线](docs/data_factor_roadmap.zh-CN.md) / [Data and factor roadmap](docs/data_factor_roadmap.md) -- [通知格式](docs/notification_format.zh-CN.md) / [Notification format](docs/notification_format.md) -- [Artifact contract](docs/advisory_contract.md) - -当前运行节奏是：**周度公开智慧投顾研究 + 周度事件/主题刷新 + 月度 AI shadow 背景 + 单独月度复盘 artifact**。月度复盘只做变化回顾和月末检查；只要报告里仍保留短线 `1-10个交易日` 和中线 `2-12周` 窗口，公开推荐就不应改成月更。 - -## 仓库定位 - -这个仓库把事件研究、主题动量、市场确认和 AI shadow 产物组合成智慧投顾研究 artifact： - -- `PoliticalEventTrackingResearch`：政治/公开事件事实、催化剂、来源置信度。 -- `ResearchSignalContextPipelines`：已保存的长周期 AI shadow context。 -- 其他量化策略/快照仓库：保持独立，不作为当前推荐链路的直接输入。 -- 各券商平台仓库：继续只负责执行链路；本仓库不调用它们。 - - -## 短中长线来源分工 - -智慧投顾研究系统由本仓库做最终合成，三个周期的输入分工如下： - -- 短线（1-10 个交易日）：事件/新闻政策催化 + 自动生成的 `market_confirmation.csv`，重点看相对强度、成交量、回撤和波动。 -- 中线（2-12 周）：`ResearchSignalContextPipelines` 的 `theme_momentum_snapshot.json`，现在明确标记为 `medium_horizon_theme_context`，重点看主题动量和个股动量。 -- 长线（1-3 年）：`ResearchSignalContextPipelines` 的 `latest_signal.json` / `signal_history/*.json`，作为 AI shadow 背景。 - -最终研究结论仍由本仓库确定性合成。信号上下文仓库不直接输出短线推荐，也不替代本仓库的最终决策。本仓库会为最终推荐记录短/中/长线独立评分和独立门槛，并在 JSON 里记录长线背景是否可用。公开页面的短线和中线栏只展示主周期归类，避免把辅助周期评分误读成最终短线/中线结论；长线栏在没有主周期长线标的时，可以展示长线背景成立的最终推荐。`horizon_actions` 仍保留在 JSON 里作为诊断，不全部提升为公开分栏。 - -## 当前 MVP - -当前实现一个确定性的智慧投顾研究报告生成器。推荐先使用和 GitHub Actions 相同的统一构建入口： - -```bash -python scripts/build_advisory_artifacts.py \ - --as-of 2026-05-30 \ - --cadence weekly \ - --political-events examples/political_events.example.csv \ - --political-watchlist examples/political_watchlist.example.csv \ - --ai-signal examples/research_signal_context.example.json \ - --theme-momentum examples/theme_momentum_snapshot.example.json \ - --market-no-network \ - --market-cache-dir .cache/market-data \ - --recommendation-review \ - --output-dir data/output/weekly_advisory_review \ - --site-output-dir site -``` - -这个入口可以一次生成市场确认、投顾研究 JSON/Markdown、manifest、可选月度复盘、可选推荐跟踪复盘和可选静态站点。weekly、monthly 和 Pages 发布 workflow 都走同一条构建路径，避免不同发布方式里复制逻辑后发生偏移。 - -底层报告生成器仍保留，适合排查单个报告： - -```bash -python scripts/build_advisory_report.py \ - --as-of 2026-05-30 \ - --cadence weekly \ - --political-events examples/political_events.example.csv \ - --political-watchlist examples/political_watchlist.example.csv \ - --ai-signal examples/research_signal_context.example.json \ - --output-json data/output/advisory_report.example.json \ - --output-md data/output/advisory_report.example.md -``` - -命令会同时写出 `data/output/advisory_report.example.json.manifest.json`。 - -输出包括： - -- 推荐标的 -- 推荐等级：重点推荐、观察、先核验来源、暂缓、背景跟踪 -- 推荐层级：一级推荐、二级推荐、观察名单、来源核验 -- 适合周期：短线、中线、长线，并明确时间窗口 -- 周期窗口：短线=1-10个交易日，中线=2-12周，长线=1-3年 -- 周期说明：短线风险、事件驱动验证周期、长期观察理由 -- 来源可信度：高、中、低、混合、无事件 -- 中长线、价值、事件、宏观等策略风格标签 -- 证据分数和风险分数 -- 推荐理由、风险、复核清单 -- 日/周/月复盘 cadence - -## 版本管理 +[English README](README.md) -- Python 包版本：`0.1.3` -- 报告 schema：`schema_version = 5` -- 报告 contract：`model_recommendations.v5` -- 报告 manifest：`.manifest.json` - -manifest 会记录 JSON/Markdown 的 SHA256、`as_of`、cadence、来源 artifact、政策边界、Git SHA、GitHub run id 和 contract version。这样和快照/AI artifact 仓库保持同类版本纪律，但不会把推荐输出变成可执行策略 target。 - -## 来源模式 - -如果报告输入来自 `examples/`，JSON 里仍会标记 `source_mode=fixture`，但公开 HTML/RSS/Telegram 不再显示 fixture 或来源模式标签。周度/月度和 Pages 发布 workflow 默认读取 `PoliticalEventTrackingResearch` 的 `data/live/*`，因此正式发布的审计 artifact 应为 `source_mode=operator_supplied`。 - -`source_mode` 继续保留在 JSON 契约里用于审计，不作为公开页面文案。 - -## 边界 - -本仓库负责： - -- 智慧投顾研究 artifact schema -- 确定性评分和复核规则 -- 日/周/月报告生成 -- 历史智慧投顾研究记录和后续复盘入口 +> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 -本仓库不负责： +## 这个项目做什么 -- 券商 API、下单、调仓 -- 目标仓位、目标股数、账户级资产配置 -- 投资者适当性判断 -- 模型 provider 路由或 prompt 执行 -- 付费行情原始数据再分发 +QuantAdvisorResearch 是 QuantStrategyLab 体系中的**研究顾问系统**。基于网页/RSS 证据发布研究型顾问内容，不下单，也不提供面向具体账户的建议。 -## AI 使用边界 +## 适合谁使用 -本仓库不直接调用 Codex、OpenAI、Anthropic 或其他模型 API。它只读取 `ResearchSignalContextPipelines` 已保存的 `mode=shadow` artifact。 +- 希望阅读、复现或扩展 QuantStrategyLab 相关模块的工程师和研究人员。 +- 在阅读详细 runbook 或 workflow 前，需要先理解项目入口的运维人员。 +- 在启用自动化前，需要确认项目职责、安全边界和证据要求的 reviewer。 -这三个仓库里，只有 `ResearchSignalContextPipelines` 的月度 shadow signal 流程会涉及 AI，而且模型执行也委托给 `QuantStrategyLab/CodexAuditBridge`。模型 API key 和 fallback provider routing 都应集中在那里，不应放到本仓库。 +## 当前状态 -## 合规提醒 +研究与发布系统；输出内容使用前需要人工复核。 -“不下单、不管仓位”会降低执行风险，但不自动消除投顾/推荐监管风险。只要面向投资者提供具体证券推荐，在不同商业模式下仍可能触发投资顾问、经纪推荐、适当性或 Reg BI 义务。 +## 仓库结构 -因此当前默认： +- `src/`：主要库代码和运行时代码。 +- `tests/`：单元测试和契约测试。 +- `docs/`：详细设计说明、运行手册和证据文档。 +- `.github/workflows/`：CI、定时任务和部署 workflow。 +- `scripts/`：运维脚本和本地辅助工具。 -- `non_personalized_recommendations_allowed=true` -- `execution_allowed=false` -- `portfolio_allocation_allowed=false` -- `personalized_advice_allowed=false` -- `account_specific_advice_allowed=false` -- `audience_scope=non_personalized_model_research` +## 快速开始 -## 测试 +从全新 clone 开始： ```bash +python -m pip install -e . python -m pytest -q ``` -## 周度复盘 +如果命令需要凭据，请先阅读相关 workflow 或 runbook，并把密钥配置在 Git 之外。 -`.github/workflows/weekly_advisory_review.yml` 会 checkout 本仓库、`PoliticalEventTrackingResearch` -和 `ResearchSignalContextPipelines`，生成周度 `model_recommendations` 智慧投顾研究报告并上传为 GitHub Actions artifact。 +## 部署和运行 -它不会提交文件、不会通知投资者、不会创建订单。 +配置数据源、发布凭据和定时 workflow。先手工运行，检查生成内容和引用，再启用定时任务。 -`.github/workflows/publish_advisory_site.yml` 会每周发布 HTML/JSON/RSS 站点。如果仓库 secrets 配置了 `TELEGRAM_BOT_TOKEN` 和 `TELEGRAM_CHAT_ID`，Pages 部署成功后会发送一条智慧投顾研究 Telegram 摘要；如果没配置，通知步骤会跳过；Telegram 发送异常会记录在日志里，但不阻断网页/RSS 发布。 +建议先手工运行或 dry-run。只有在日志、产物、权限和回滚步骤都检查过之后，才启用定时任务或 live 执行。 -周度发布是有意保留的：短线结论如果只月更会过期；月度 AI shadow 只提供长周期背景，不作为每周追热点的模型输入。 +## 策略表现与证据边界 -## 月度复盘 +这不是交易策略仓库。评估重点是证据质量、引用准确性、时效性，以及是否避免具体账户投资建议。 -`.github/workflows/monthly_advisory_review.yml` 每月生成一次 `monthly_advisory_review` artifact，用来检查本月最终推荐、短/中/长线分布，以及相对上一份报告的新增、移除和保留标的。 +README 不应该承诺固定收益或过期指标。实际使用前，请重新运行对应测试、回测或流水线任务。 -本地生成： +## 安全注意事项 -```bash -python scripts/build_monthly_review.py \ - --current-report data/output/weekly_advisory_review/advisory_report_2026-05-30.json \ - --output-json data/output/monthly_advisory_review/monthly_review_2026-05-30.json \ - --output-md data/output/monthly_advisory_review/monthly_review_2026-05-30.md -``` +- 不要把 API key、券商凭据、OAuth token、Cookie 或账户标识提交到 Git。 +- 新策略或平台变更在 live 前必须先跑 dry-run 或 paper 流程。 +- 启用定时任务前，需要人工检查生成的订单、产物和日志。 -如果传入 `--previous-report`，会输出新增、移除和保留标的；不传时仍能生成本月快照，但会记录数据质量提示。这个 workflow 只上传 artifact，不发布网页，也不替代周度公开推荐。 +## 参与贡献 -## RSS / 静态页面 +请保持改动小、可复现，并用最小必要测试覆盖。涉及策略的改动，需要附上验证行为的证据产物或命令。 -生成 HTML + RSS 预览： - -```bash -python scripts/publish_advisory_site.py \ - --reports data/output/weekly_advisory_review/advisory_report_2026-05-30.json \ - --output-dir site \ - --site-url https://quantstrategylab.github.io/QuantAdvisorResearch -``` - -本地打开 `site/index.html`，RSS 文件是 `site/feed.xml`。静态站点同时生成 `site/archive.html` 和 `site/reports_index.json`：首页只保留最新报告和最近 12 期历史报告，完整历史按月份保留在归档页；RSS 默认保留最近 20 条。 -`.github/workflows/publish_advisory_site.yml` 会部署到 GitHub Pages： - - -当前公开页面、RSS 标题和 Telegram 摘要默认使用简体中文（`zh-CN`），并统一使用“智慧投顾研究系统”的对外表述。 -JSON 字段名继续保持英文契约键，避免破坏下游程序读取。 - -发布 workflow 默认已经读取 `PoliticalEventTrackingResearch` 内的真实 CSV。手工触发通常只需要传日期；只有刻意测试其他 artifact 时才覆盖路径： - -```bash -gh workflow run "Publish Intelligent Advisory Site" \ - --repo QuantStrategyLab/QuantAdvisorResearch \ - -f as_of=2026-05-30 -``` - -通知格式设计见 [docs/notification_format.zh-CN.md](docs/notification_format.zh-CN.md)。 -数据源和因子完善路线见 [docs/data_factor_roadmap.zh-CN.md](docs/data_factor_roadmap.zh-CN.md)。 - -如果本地下载了历史 GitHub Actions artifact，可以回填静态归档： - -```bash -python scripts/backfill_site_archive.py \ - --artifact-root path/to/downloaded/actions/artifacts \ - --output-dir site \ - --site-url https://quantstrategylab.github.io/QuantAdvisorResearch -``` - -跨仓库 smoke 测试可以在不下载实时行情的情况下验证三仓库 artifact 是否能合成报告和页面： - -```bash -python scripts/run_cross_repo_smoke.py \ - --as-of 2026-05-30 \ - --political-events ../PoliticalEventTrackingResearch/data/live/political_events.csv \ - --political-watchlist ../PoliticalEventTrackingResearch/data/live/political_watchlist.csv \ - --ai-signal ../ResearchSignalContextPipelines/data/output/latest_signal.json \ - --theme-momentum ../ResearchSignalContextPipelines/data/output/theme_momentum_snapshot.json \ - --work-dir data/output/cross_repo_smoke -``` - -`.github/workflows/cross_repo_smoke.yml` 会每周运行同样的 no-network smoke，并上传生成的报告和页面 artifact，方便检查三仓库接口有没有变坏。 - -## 主题动量展示 - -`build_advisory_report.py` 支持可选的主题动量快照输入： - -```bash -python scripts/build_advisory_report.py \ - --as-of 2026-05-30 \ - --cadence weekly \ - --political-events examples/political_events.example.csv \ - --political-watchlist examples/political_watchlist.example.csv \ - --ai-signal examples/research_signal_context.example.json \ - --theme-momentum examples/theme_momentum_snapshot.example.json \ - --market-confirmation examples/market_confirmation.example.csv \ - --output-json data/output/advisory_report.example.json \ - --output-md data/output/advisory_report.example.md -``` - -主题动量会生成 `theme_first_candidates[]`，作为 JSON/Markdown 中的解释和审计材料。公开页面、RSS 和 Telegram 摘要默认只显示最终推荐，避免把候选池误读为买入清单。 - -基础 `recommendations[]` 评级仍来自事件、watchlist 和 AI 背景；`final_decisions` 会用中线主题动量和可选市场确认对最终公开列表排序。候选池不改变仓位或执行状态。 -线上 workflow 如果找不到 `data/output/theme_momentum_snapshot.json`，会自动跳过这个展示区块。 - -## 市场确认 - -`scripts/build_market_confirmation.py` 会从 watchlist、信号上下文和主题动量快照收集股票代码，生成 `market_confirmation.csv`： - -```bash -python scripts/build_market_confirmation.py \ - --as-of 2026-05-30 \ - --political-watchlist examples/political_watchlist.example.csv \ - --ai-signal examples/research_signal_context.example.json \ - --theme-momentum examples/theme_momentum_snapshot.example.json \ - --output data/output/market_confirmation_2026-05-30.csv -``` - -字段包括 `return_5d`、`return_20d`、`return_63d`、相对 SPY 收益、成交量 z-score、63 日回撤、21 日年化波动、`market_score`、`price_age_days`、`confirmation_quality`、数据源、观测数量和 warnings。线上 weekly/monthly/publish workflow 会自动生成该文件，再传给报告生成器。 - -可选代理参数： - -- `--proxy-urls`：逗号或换行分隔的代理列表。 -- `--proxy-list`：本地代理列表文件。 -- `--proxy-pool-url`：公共代理池文本 URL，一行一个代理。 -- `--cache-dir`：保存 Yahoo 日线价格缓存的本地目录。 -- `--cache-max-age-days`：实时下载失败时，允许使用的最大缓存陈旧天数。 - -线上 workflow 也支持仓库变量 `MARKET_DATA_PROXY_URLS` 和 `MARKET_DATA_PROXY_POOL_URL`。脚本会先直连 Yahoo，失败后再尝试代理；日志只记录代理序号，不输出代理完整地址。 - -Yahoo chart 下载只是当前无依赖的免费行情入口；如果不可用，脚本会退回到 `theme_momentum_snapshot.json` 里的价格动量信息，报告仍能生成。免费公共代理池可以作为应急补充，但不应当作稳定生产数据源；它有稳定性、数据污染、封禁、隐私和合规风险。更稳的做法是使用本组织已有价格快照、缓存文件，或可审计的自有代理/数据源。线上 weekly/monthly/Pages workflow 会用 GitHub Actions cache 恢复和保存 `.cache/market-data`，让一次成功的价格下载可以继续支撑后续推荐复盘，也能降低 Yahoo 临时不可用的影响。 - -## 推荐跟踪复盘 - -`scripts/build_recommendation_review.py` 会用缓存价格复盘历史最终推荐的后续表现。它是研究审计 artifact，不是新的推荐清单。 - -```bash -python scripts/build_recommendation_review.py \ - --as-of 2026-06-30 \ - --reports data/output/weekly_advisory_review/advisory_report_2026-05-30.json \ - --benchmark SPY \ - --cache-dir .cache/market-data \ - --output-json data/output/recommendation_review_2026-06-30.json \ - --output-md data/output/recommendation_review_2026-06-30.md -``` +## 许可证 -复盘会计算绝对收益、相对 SPY 收益、结果状态、按周期汇总和数据质量提示。统一构建入口可以通过 `--recommendation-review` 生成该 artifact；Pages 发布 workflow 在能恢复已发布历史报告时，也会把历史报告纳入复盘，所以历史越完整，复盘越有用。 +如仓库包含 [LICENSE](LICENSE)，请以该文件为准。