US-Market Research Agent MVP

这是一个本地优先的美股研究代理，面向 UTC+8 / Asia/Singapore 用户。它支持固定 watchlist 定时研究、自然语言按需研究、美股盘前简报、盘中新闻监控、盘后复盘、Telegram 通知、SQLite 记忆和 Markdown 报告。

本项目只做研究，不是交易系统：

• 不接券商 API
• 不下单
• 不生成订单规模
• 不做仓位或组合再平衡
• 不提供直接投资建议

安装

cd research-agent
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

环境变量

复制 .env.example：

copy .env.example .env

OpenAI-compatible provider，例如 OpenRouter/Groq/Gemini 兼容网关：

LLM_PROVIDER=openai_compatible
LLM_BASE_URL=https://openrouter.ai/api
LLM_API_KEY=your_api_key
LLM_MODEL=openrouter/free

Ollama：

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.1

公司网络证书拦截导致 SSL 失败时，可临时测试：

LLM_VERIFY_SSL=false
MARKET_VERIFY_SSL=false
RSS_VERIFY_SSL=false

SEC EDGAR 建议配置 User-Agent：

SEC_USER_AGENT=ResearchAgent/0.1 your_email@example.com

Telegram 通知可选：

TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

缺少 Telegram 凭证时程序会记录 warning 并跳过通知，不会崩溃。

配置

config.yaml 默认使用：

timezone: Asia/Singapore

market:
  primary_market: US
  market_timezone: America/New_York
  user_timezone: Asia/Singapore

schedule:
  us_pre_market_brief_time: "20:30"
  us_intraday_news_watch_time: "00:30"
  us_post_market_review_time: "05:30"
  passive_news_watch_time: "12:00"

这些时间都是新加坡时间。美股常规交易在新加坡夜间，报告里会明确使用 SGT。

默认 watchlist 聚焦美股、美股 ETF 和相关资产：

watchlist:
  - AAPL
  - MSFT
  - NVDA
  - AMZN
  - META
  - GOOGL
  - TSLA
  - SPY
  - QQQ
  - IWM
  - DIA
  - TLT
  - GLD
  - BTC-USD

命令

初始化数据库：

python main.py init-db

自然语言按需研究：

python main.py research "Analyze NVDA recent risks"
python main.py research "Why did Tesla stock move recently?"
python main.py research "Compare MSFT and GOOGL recent AI-related news"
python main.py research "Research US semiconductor sector risks this week"

输出 JSON：

python main.py research "Analyze NVDA recent risks" --json

美股盘前简报：

python main.py us-brief

盘中新闻监控：

python main.py news-watch

盘后复盘：

python main.py post-market-review

启动定时器：

python main.py scheduler

保留原有命令：

python main.py run-once
python main.py report-today
python main.py strategy-payload-today
python main.py cleanup

输出文件

按需研究：

reports/on_demand_YYYY-MM-DD_HHMMSS.md

美股盘前简报：

reports/us_pre_market_brief_YYYY-MM-DD_HHMMSS.md

美股盘后复盘：

reports/us_post_market_review_YYYY-MM-DD_HHMMSS.md

下游机器 payload：

strategy_payloads/strategy_payload_YYYY-MM-DD.json

数据来源

市场数据：

• yfinance
• Yahoo chart fallback

基本面：

• yfinance.Ticker.info
• SEC EDGAR companyfacts fallback

新闻：

• Yahoo Finance RSS
• MarketWatch RSS
• CNBC RSS

部分 RSS 源可能返回 429 或 403。系统会跳过失败源，继续用可用数据生成报告。

数据库

SQLite 表包括：

market_snapshots
fundamental_snapshots
news_items
research_views
agent_memory
research_requests
tool_runs
on_demand_reports
research_reports
alerts

Telegram

Telegram 支持：

• 盘前简报
• 高重要性盘中新闻提醒
• 盘后复盘摘要

重要性阈值在 config.yaml：

research:
  alert_importance_threshold: 4

通知始终包含 research-only 声明，不包含交易指令。

清理过期数据

python main.py cleanup

默认规则：

cleanup:
  market_snapshots_retention_days: 730
  fundamental_snapshots_retention_days: 730
  news_items_retention_days: 180
  research_views_retention_days: 730
  agent_memory_retention_days: 365
  keep_memory_importance_at_least: 4
  reports_retention_days: 730

测试

pytest

限制

• 免费数据源不稳定，可能被限流或字段缺失。
• RSS 关键词匹配是 MVP 规则，不等于完整新闻检索。
• LLM 输出会被校验和兜底，但仍可能受模型质量影响。
• 基本面 fallback 来自 SEC 年报事实，不能替代实时财报指引数据库。
• 本系统只生成研究背景、风险、事件和后续研究问题，不生成交易计划。