Smart Stock Selector
Multi-market stock selection with AKShare + SQLite caching. Covers A-shares, HK, US, and funds (ETF/LOF).
Core promise
Given a stock code, market, or investment theme, return actionable signals with scores. All analysis is script-driven and cache-backed. First fetch the pool if cache is cold.
Triggers
Activate on any of these user intents:
| Keyword / pattern | Likely intent |
|---|---|
Code like 600519, AAPL, 0700.HK, 510300 |
Single stock analysis or diagnosis |
Chinese name like 贵州茅台 |
Resolve from pool, then analyze |
分析, 评分, signal, BUY/SELL/HOLD |
Run analysis or diagnosis |
选股, scan, top, ranking |
Market scan (A/HK/US/FUND) |
组合, portfolio, 分配 |
Portfolio construction |
回测, backtest, 验证 |
Strategy backtest |
因子, 动量, alpha, momentum |
Alpha momentum scan |
基金, fund, ETF |
Fund/ETF screening |
情绪, sentiment, 行情 |
Sentiment / breadth check |
刷新, fetch, 缓存, cache |
Data operations |
Before you start
Refresh all data pools on first run:
python scripts/run.py fetch pool
Workflows
1. Single stock analysis
Normalize code by convention: 6xxxxx/0xxxxx/3xxxxx -> A, xxxx.HK -> HK, plain ticker -> US.
python scripts/run.py analyze 600519 --market A # terminal output
python scripts/run.py analyze 600519 --market A --format json # JSON only
python scripts/run.py analyze 600519 --market A --format md # save MD report
Output: PE/PB/ROE/Dividend, composite factor scores, strategy signal.
2. Deep diagnosis
Comprehensive BUY/SELL/HOLD with risk assessment:
python scripts/run.py diagnose 600519 --market A
python scripts/run.py diagnose 600519 --market A --output-dir ./reports
JSON structure: final_decision.signal, adjusted_score, factors, strategy, technical, sentiment, fundamentals, risks.
Present results:
- BUY -> include stop-loss and take-profit references
- SELL -> explain risk factors
- HOLD -> explain what would need to change
3. Market scan
python scripts/run.py scan A --top 20 # top 20 A-shares
python scripts/run.py scan HK --top 10 --format json
python scripts/run.py scan FUND --top 20 --output-dir ./reports
If scan returns all zeros, fall back to alpha mode:
python scripts/run.py alpha A --top 10 --candidates 200
For sector-filtered scanning:
python -c "from advisor.scanner import MarketScanner; MarketScanner().scan_by_sector('A', top_n=5)"
4. Alpha momentum scan
Full multi-factor ranking with thread-parallel scoring:
python scripts/run.py alpha A --top 10 --candidates 200
Results include ranked list with scores, signals, F-Score, and BUY summary. Explain which factors drove top rankings (momentum + low-vol + quality ~73% combined).
5. Portfolio construction
python scripts/run.py portfolio --codes 600519,000858,002475 --capital 1000000
python scripts/run.py portfolio-enhanced --capital 1000000
For custom methods (equal weight, risk parity, min variance), see references/python-api.md.
6. Backtest
python scripts/run.py backtest # standard Alpha Momentum
python scripts/run.py backtest-enhanced # enhanced core-satellite
Requires >= 1500 trading days cached. Report CAGR, Sharpe, MaxDD.
7. Fund/ETF screening
python scripts/run.py scan FUND --top 20
For deeper programmatic access:
from data_engine import get_fund_pool, get_fund_nav
8. Data operations
python scripts/run.py fetch pool # full pool refresh
python scripts/run.py fetch kline 600519 # single stock K-line
python scripts/run.py fetch fundamentals 600519 # single stock fundamentals
Output guidelines
Terminal output (auto-detected):
Use emoji indicators for scannability:
600519 贵州茅台
评分 82.3/100 | 信号: BUY (F=8)
核心驱动: 质量(88.7) + 动量(76.5)
风险: 低
参考止损/止盈: 1480.50 / 1980.00
Full diagnosis report format:
- Decision signal and score
- Top-3 driving factors
- Strategy that triggered the signal
- Sentiment adjustment if >5% impact
- Risk level and key risks
- Stop-loss and take-profit reference prices
JSON output (--format json):
All scripts accept --format {json,md,both,none}. JSON for programmatic use, MD for readable reports.
Language:
Use Chinese for A-share content unless the user writes in English. Use English for US/HK.
Gotchas
| Symptom | Cause | Fix |
|---|---|---|
ModuleNotFoundError: No module named 'config' |
Wrong working directory | Run from project root (where scripts/ is) |
| Scan returns 0 results | Cache empty | python scripts/run.py fetch pool first |
| "Daily API limit reached" | AKShare rate limit (500/day) | Wait; use cached data |
| No BUY signals | Market weakness or cold cache | Run diagnose on individual stocks |
import akshare fails |
Not installed | pip install akshare efinance baostock |
| Code not found | Pool not fetched | python scripts/run.py fetch pool |
| Backtest fails | Insufficient data | Ensure >= 1500 trading days cached |
Key principles
- Cache first, fetch on miss — SQLite cache before AKShare API. Refresh on TTL expiry.
- Multi-factor, multi-strategy — Weighted vote across 6 strategies from 7 factor dimensions.
- Script-driven — Run
python scripts/run.py, never reimplement logic. - Parallel scoring — Thread pool (8 workers) for alpha scans.
- Graceful degradation — Cache-only mode on API limit. Partial results over failures.
Reference files
Load only when needed:
- Factor weights & scoring: references/factors.md
- Strategy weights & signals: references/strategies.md
- Sentiment adjustment: references/sentiment.md
- Python API & code: references/python-api.md
- Enhanced Momentum: references/enhanced-momentum.md
- Market sources: references/market-source-playbook.md
- AKShare docs: references/akshare_official_docs.md
- Output style: references/output-style-and-language.md
- Research: references/research-sources.md
- Risk & compliance: references/risk-and-compliance.md
- Dialogue protocol: references/serenity-dialogue-protocol.md
Output file specs
- Path:
./reports/ - Naming:
{YYYY-MM-DD-HHMM}_{Short Title}.{json,md} - Format: Standard Markdown with hierarchy
Risk disclaimer
For investment reference only, not investment advice. Data sources are third-party public platforms with 10-15 minute delay. Past performance does not guarantee future returns.