name: alphasift description: "自动选股 Skill。Use when: 用户要按策略筛选 A 股、列出可用策略、运行双低/放量突破等选股，或保存运行并做 T+N 后验评估。通过 alphasift CLI 或 Python 接口输出候选股票列表。"

alphasift — 自动选股 Skill

按策略筛选、评分并排序 A 股候选股票。

定位：全市场候选发现与横向排序引擎。它站在 daily_stock_analysis 这类单股深度分析服务上游；DSA 只是可选 L3 后置分析器，不是主筛选依赖。

Use When

• 用户要列出当前可用策略
• 用户要按 dual_low、volume_breakout 这类策略筛选 A 股
• 用户要拿到结构化 JSON 结果，供后续 agent 继续分析
• 用户要保存选股运行，并在之后用最新快照评估结果
• 用户第一次接触本项目，想用 alphasift quickstart 一键看到全市场→候选→排名的最小闭环

Preconditions

• 默认 market="cn"；market="us" 也可用（yfinance 快照 + 日K，无 hotspot/board_heat/tushare 等 CN 专属数据源），但需使用声明了 market_scope 含 us 的策略，目前为 us_momentum_quality
• 需要先在仓库根目录安装包：pip install -e .
• 如需 LLM 排序，可设置 LITELLM_MODEL、LLM_CHANNELS、LITELLM_CONFIG 或旧变量 LLM_API_KEY/LLM_MODEL/LLM_BASE_URL
• 可直接复用 daily_stock_analysis 的 LiteLLM 配置字段，包括 OPENAI_*、GEMINI_*、DEEPSEEK_API_KEY、OLLAMA_API_BASE
• 策略 YAML 可通过 scoring_profile、risk_profile、portfolio_profile、scorecard_profile 覆盖默认规则
• 策略 YAML 可通过 event_profile 配置偏好/规避事件、公告类别和候选上下文来源权重
• LLM 会输出候选行业/主题标签；如候选提供 industry/concepts/board_heat_score/board_heat_trend_score，会作为 LLM、主题热度因子与组合分散层锚点；history sidecar 可回填持续性、降温和状态字段。默认组合分散层会用这些标签映射风险桶，降低同一拥挤交易重复占位
• L3 默认启用本地 scorecard 后置评分器，也可追加 dsa 或 external_http
• 如需 DSA 后置分析，设置 DSA_API_URL，默认调用 POST /api/v1/analysis/analyze
• 依赖日 K 的策略会在 L1 后自动对 Top N 候选做日 K 增强
• 日 K 数据源 DAILY_SOURCE 支持 akshare（默认）、baostock 或 auto，auto 会在 akshare 失败时自动降级到 baostock 作为免费兜底

Operations

1. 列出策略

alphasift strategies

1.1 一键演示（无 API key）

alphasift quickstart
alphasift quickstart --strategy balanced_alpha --max-output 8

2. 执行选股

alphasift screen dual_low --no-llm
alphasift screen volume_breakout --max-output 10
alphasift screen balanced_alpha --no-llm
alphasift screen capital_heat
alphasift screen balanced_alpha --context "今日券商板块放量，低估值金融获得资金回流"
alphasift --env-file /home/ubuntu/daily_ai_assistant/.env screen balanced_alpha
alphasift screen balanced_alpha --explain
alphasift screen balanced_alpha --candidate-context-file candidate_context.csv
alphasift screen dual_low --no-post-analysis
alphasift screen shrink_pullback --no-llm
alphasift screen dual_low --post-analyzer dsa
alphasift audit
alphasift industry-cache --output data/industry_map.csv --explain
alphasift screen dual_low --no-llm --save-run
alphasift runs
alphasift evaluate <run_id> --explain
alphasift evaluate-batch --limit 20 --explain
alphasift evaluate <run_id> --with-price-path --explain

3. Python 调用

from alphasift import evaluate_saved_run, evaluate_saved_runs, list_strategies, screen

list_strategies()
screen("dual_low", market="cn", use_llm=False)
evaluate_saved_run("<run_id>")
evaluate_saved_runs(limit=20)

Output

返回 ScreenResult JSON，核心字段有：

• strategy
• market
• strategy_version
• snapshot_count
• after_filter_count
• picks
• llm_ranked
• llm_market_view
• llm_selection_logic
• llm_portfolio_risk
• llm_coverage
• post_analyzers
• daily_enriched
• risk_enabled
• portfolio_concentration_notes
• degradation
• snapshot_source
• source_errors

每个 Pick 包含：

• rank
• code
• name
• final_score
• screen_score
• ranking_reason
• risk_summary
• price
• change_pct
• amount
• total_mv
• turnover_rate
• volume_ratio
• pe_ratio
• pb_ratio
• industry
• concepts
• board_heat_score
• board_heat_latest_score
• board_heat_trend_score
• board_heat_persistence_score
• board_heat_cooling_score
• board_heat_observations
• board_heat_state
• board_heat_summary
• change_60d
• signal_score
• macd_status
• rsi_status
• breakout_20d_pct
• range_20d_pct
• volume_ratio_20d
• body_pct
• pullback_to_ma20_pct
• consolidation_days_20d
• factor_scores
• llm_confidence
• llm_sector
• llm_theme
• llm_tags
• llm_catalysts
• llm_risks
• llm_thesis
• llm_style_fit
• llm_watch_items
• llm_invalidators
• risk_score
• risk_level
• risk_penalty
• risk_flags
• portfolio_penalty
• portfolio_flags
• post_analysis_status
• post_analysis_score_deltas
• deep_analysis_status
• deep_analysis_summary
• deep_analysis_result
• deep_analysis_signal_score
• deep_analysis_sentiment_score
• deep_analysis_operation_advice
• deep_analysis_trend_prediction
• deep_analysis_risk_flags

Boundaries

• 当前没有独立的远程 get_result 服务；本地用 --save-run、runs、evaluate、evaluate-batch 管理运行记录
• audit 用于自检策略 profile 覆盖、已知能力短板和下一步优先级
• --candidate-context-file 支持 CSV/JSON/JSONL，通过 code 对齐候选级新闻、公告、资金流或研究摘要，只注入当前候选池相关行；可选抓取会附带 source_count、source_confidence、source_weight_score、context_summary 和公告类别
• 候选级上下文会识别粗粒度事件标签和负面风险标签，供 LLM 横向排序参考
• industry-cache 会缓存行业/概念映射和板块热度字段，并写入 history sidecar；后续加载映射时可回填板块热度滚动趋势、持续性、降温和状态字段，供 LLM 上下文与 theme_heat 因子使用
• 组合分散层优先使用 LLM 返回的行业/主题标签，也可回退到候选 industry 字段；两者都缺失时不会改变规则分数
• L3 后置分析器只在最终候选上运行，不参与全市场初筛；本地 scorecard 默认启用，DSA 只是其中一个可追加后端
• T+N 评估基于保存价和评估时最新快照价，不等同完整复权回测；可扣减交易成本并输出突破/回踩形态后验标签；--with-price-path 会额外估算最大回撤和最大浮盈

AlphaSift

AlphaSift is an agent-friendly stock discovery and ranking engine. It scans a broad market universe, applies auditable YAML strategies, enriches candidates with optional market context, ranks them with deterministic factors and optional LLM judgment, and saves runs for later T+N evaluation.

This README is the default English version. A Chinese version is available at README.zh-CN.md.

Disclaimer

• This project is for learning, research, and engineering experiments only.
• It is not investment advice, a return guarantee, or a buy/sell instruction.
• Outputs depend on third-party market data, optional LLM providers, local configuration, and strategy parameters. They can be delayed, incomplete, wrong, or unsuitable for real trading.
• Users are responsible for independent research, compliance checks, transaction costs, liquidity risks, announcement timing, and all resulting decisions.

What AlphaSift does

• L1 deterministic screening: hard filters and factor scoring over the full market snapshot.
• L2 optional LLM ranking: structured cross-candidate reasoning, theses, catalysts, risks, confidence, and portfolio risk buckets.
• L3 pluggable post-analysis: local scorecard by default, with optional DSA or external HTTP analyzers.
• Hotspot discovery: topic/sector heat ranking, hotspot detail resolution, leader stock fallbacks, cache quality metadata, and history sidecars.
• Daily feature enrichment: optional candidate-level daily K-line features such as moving averages, MACD/RSI, breakout strength, volume ratio, pullback distance, and platform duration.
• Evaluation loop: save runs, evaluate later using newer snapshots, deduct transaction cost, tag follow-through / failed-breakout outcomes, review failure samples, and optionally fetch price paths for max drawdown / max favorable excursion.
• Agent-native interface: SKILL.md describes capabilities and callable interfaces for AI agents.

Quick start

# Install in editable mode
pip install -e .

# Copy configuration template
cp .env.example .env
# Edit .env if you want LLM ranking:
# GEMINI_API_KEY / OPENAI_API_KEY / DEEPSEEK_API_KEY
# or LITELLM_MODEL / LLM_CHANNELS / LITELLM_CONFIG

# List built-in strategies
alphasift strategies

# UI/agent overview: strategy groups, source health, recent runs
alphasift overview --explain

# Local read-only JSON API for dashboards/agents
alphasift serve --host 127.0.0.1 --port 8765

# Run the no-key demo
alphasift quickstart

# Screen without LLM ranking
alphasift screen dual_low --no-llm

# Screen with LLM ranking, if a provider key is configured
alphasift screen dual_low

# Reuse another project's environment file
alphasift --env-file /home/ubuntu/daily_ai_assistant/.env screen balanced_alpha

# Add market or theme context to the LLM prompt
alphasift screen balanced_alpha --context "Brokerage names are seeing volume expansion today."

# Add candidate-level news / announcement / fund-flow context
alphasift screen balanced_alpha --candidate-context-file candidate_context.csv

# Show local L3 scorecard explanations
alphasift screen balanced_alpha --explain

# Add DSA as an optional L3 analyzer; requires DSA_API_URL
alphasift screen dual_low --post-analyzer dsa

# Disable L3 post-analysis explicitly
alphasift screen dual_low --no-post-analysis

# Audit project and strategy configuration
alphasift audit

# Save a run and generate a Markdown review report
alphasift screen dual_low --no-llm --save-run
alphasift runs --json
alphasift report <run_id> --output data/reports/dual_low.md

Example output shape:

$ alphasift screen dual_low --no-llm
Universe 5190 -> filtered 337 -> output Top 5
rank  code    name       score  price   change   pe     pb
1     002039  黔源电力   72.7   20.72   -2.49%   14.76  1.99
2     002444  巨星科技   71.0   30.82   +0.29%   14.59  1.95
3     002128  电投能源   70.9   31.60   -2.41%   14.00  1.90

Screening examples

The following recorded examples were run on April 12, 2026, using the previous trading day's A-share close data from April 10, 2026. LLM ranking was disabled with --no-llm; these rows are examples of engine output, not recommendations.

Dual Low

Full market 5190 stocks -> 337 after hard filters -> Top 5 output.

Volume Breakout

Full market 5190 stocks -> 126 after hard filters -> Top 5 output.

Hotspot workflow

AlphaSift can discover current market hotspots and resolve a specific topic into a detail payload with raw timeline evidence, compact display-ready route events, leader stocks, source confidence, stale/fallback metadata, and quality diagnostics.

# Discover hotspot topics and write schema_version=2 cache/history sidecars
alphasift hotspots --provider akshare --top 12 --output data/hotspots.json --history data/hotspot.history.jsonl --explain

# Inspect a single hotspot topic
alphasift hotspot "AI compute" --top-stocks 10 --timeline --fallback-cache data/hotspots.json --explain

# Safe offline/no-network check
alphasift hotspots --provider none --explain

Hotspot cache files include:

• schema_version: currently 2
• generated_at
• metadata: provider, row count, source errors, stale/fallback state
• hotspots: normalized topic rows
• sidecars such as *.meta.json and JSONL history when requested

Leader stock fallbacks are intentionally explicit. When live constituent APIs fail and AlphaSift uses last-good/cache leaders, returned stocks carry fields such as source="last_good_cache.leader_stocks", source_confidence, and fallback_used=true instead of pretending to be live provider data.

Hotspot details keep the raw timeline for auditability and also expose a compact route list for applications. route is grouped by day, newest first, trimmed for UI display, and falls back to a short current heat/stage/leader summary when no timeline evidence is available.

Python API

from alphasift import screen

result = screen("dual_low", use_llm=False)
for pick in result.picks:
    print(f"{pick.rank}. {pick.code} {pick.name} score={pick.final_score:.1f}")

Saved-run evaluation helpers are also exported:

from alphasift import evaluate_saved_run, evaluate_saved_runs

Configuration

AlphaSift is designed to reuse LiteLLM-style configuration used by daily_stock_analysis and similar projects.

Example multi-channel LiteLLM config:

LLM_CHANNELS=primary
LLM_PRIMARY_PROTOCOL=openai
LLM_PRIMARY_BASE_URL=https://api.deepseek.com/v1
LLM_PRIMARY_API_KEYS=sk-xxx,sk-yyy
LLM_PRIMARY_MODELS=deepseek-chat,deepseek-reasoner
LITELLM_MODEL=openai/deepseek-chat
LITELLM_FALLBACK_MODELS=openai/gpt-4o-mini,anthropic/claude-3-5-sonnet

Example single-provider config:

GEMINI_API_KEY=...
LITELLM