文件内容
docs/USAGE.md
# Usage Guide
Practical examples for using Stock Analysis v6.0 in real scenarios.
## Table of Contents
1. [Basic Stock Analysis](#basic-stock-analysis)
2. [Comparing Stocks](#comparing-stocks)
3. [Crypto Analysis](#crypto-analysis)
4. [Dividend Investing](#dividend-investing)
5. [Portfolio Management](#portfolio-management)
6. [Watchlist & Alerts](#watchlist--alerts)
7. [Performance Tips](#performance-tips)
8. [Interpreting Results](#interpreting-results)
---
## Basic Stock Analysis
### Single Stock
```bash
uv run scripts/analyze_stock.py AAPL
```
**Output:**
```
===========================================================================
STOCK ANALYSIS: AAPL (Apple Inc.)
Generated: 2024-02-01T10:30:00
===========================================================================
RECOMMENDATION: BUY (Confidence: 72%)
SUPPORTING POINTS:
• Beat by 8.2% - EPS $2.18 vs $2.01 expected
• Strong margin: 24.1%
• Analyst consensus: Buy with 12.3% upside (42 analysts)
• Momentum: RSI 58 (neutral)
• Sector: Technology uptrend (+5.2% 1m)
CAVEATS:
• Earnings in 12 days - high volatility expected
• High market volatility (VIX 24)
===========================================================================
DISCLAIMER: NOT FINANCIAL ADVICE.
===========================================================================
```
### JSON Output
For programmatic use:
```bash
uv run scripts/analyze_stock.py AAPL --output json | jq '.recommendation, .confidence'
```
### Verbose Mode
See what's happening under the hood:
```bash
uv run scripts/analyze_stock.py AAPL --verbose
```
---
## Comparing Stocks
### Side-by-Side Analysis
```bash
uv run scripts/analyze_stock.py AAPL MSFT GOOGL
```
Each stock gets a full analysis. Compare recommendations and confidence levels.
### Sector Comparison
Compare stocks in the same sector:
```bash
# Banks
uv run scripts/analyze_stock.py JPM BAC WFC GS
# Tech
uv run scripts/analyze_stock.py AAPL MSFT GOOGL AMZN META
```
---
## Crypto Analysis
### Basic Crypto
```bash
uv run scripts/analyze_stock.py BTC-USD
```
**Crypto-Specific Output:**
- Market cap classification (large/mid/small)
- Category (Smart Contract L1, DeFi, etc.)
- BTC correlation (30-day)
- Momentum (RSI, price range)
### Compare Cryptos
```bash
uv run scripts/analyze_stock.py BTC-USD ETH-USD SOL-USD
```
### Supported Cryptos
```
BTC, ETH, BNB, SOL, XRP, ADA, DOGE, AVAX, DOT, MATIC,
LINK, ATOM, UNI, LTC, BCH, XLM, ALGO, VET, FIL, NEAR
```
Use `-USD` suffix: `BTC-USD`, `ETH-USD`, etc.
---
## Dividend Investing
### Analyze Dividend Stock
```bash
uv run scripts/dividends.py JNJ
```
**Output:**
```
============================================================
DIVIDEND ANALYSIS: JNJ (Johnson & Johnson)
============================================================
Current Price: $160.50
Annual Dividend: $4.76
Dividend Yield: 2.97%
Payment Freq: quarterly
Ex-Dividend: 2024-02-15
Payout Ratio: 65.0% (moderate)
5Y Div Growth: +5.8%
Consecutive Yrs: 62
SAFETY SCORE: 78/100
INCOME RATING: GOOD
Safety Factors:
• Moderate payout ratio (65%)
• Good dividend growth (+5.8% CAGR)
• Dividend Aristocrat (62+ years)
Dividend History:
2023: $4.52
2022: $4.36
2021: $4.24
2020: $4.04
2019: $3.80
============================================================
```
### Compare Dividend Stocks
```bash
uv run scripts/dividends.py JNJ PG KO MCD VZ T
```
### Dividend Aristocrats Screen
Look for stocks with:
- Yield > 2%
- Payout < 60%
- Growth > 5%
- Consecutive years > 25
---
## Portfolio Management
### Create Portfolio
```bash
uv run scripts/portfolio.py create "Retirement"
```
### Add Holdings
```bash
# Stocks
uv run scripts/portfolio.py add AAPL --quantity 100 --cost 150.00
# Crypto
uv run scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000
```
### View Portfolio
```bash
uv run scripts/portfolio.py show
```
**Output:**
```
Portfolio: Retirement
====================
Assets:
AAPL 100 shares @ $150.00 = $15,000.00
Current: $185.00 = $18,500.00 (+23.3%)
BTC-USD 0.5 @ $40,000 = $20,000.00
Current: $45,000 = $22,500.00 (+12.5%)
Total Cost: $35,000.00
Current Value: $41,000.00
Total P&L: +$6,000.00 (+17.1%)
```
### Analyze Portfolio
```bash
# Full analysis of all holdings
uv run scripts/analyze_stock.py --portfolio "Retirement"
# With period returns
uv run scripts/analyze_stock.py --portfolio "Retirement" --period monthly
```
### Rebalance Check
The analysis flags concentration warnings:
```
⚠️ CONCENTRATION WARNINGS:
• AAPL: 45.1% (>30% of portfolio)
```
---
## Watchlist & Alerts
### Add to Watchlist
```bash
# Basic watch
uv run scripts/watchlist.py add NVDA
# With price target
uv run scripts/watchlist.py add NVDA --target 800
# With stop loss
uv run scripts/watchlist.py add NVDA --stop 600
# Alert on signal change
uv run scripts/watchlist.py add NVDA --alert-on signal
# All options
uv run scripts/watchlist.py add NVDA --target 800 --stop 600 --alert-on signal
```
### View Watchlist
```bash
uv run scripts/watchlist.py list
```
**Output:**
```json
{
"success": true,
"items": [
{
"ticker": "NVDA",
"current_price": 725.50,
"price_at_add": 700.00,
"change_pct": 3.64,
"target_price": 800.00,
"to_target_pct": 10.27,
"stop_price": 600.00,
"to_stop_pct": -17.30,
"alert_on_signal": true,
"last_signal": "BUY",
"added_at": "2024-01-15"
}
],
"count": 1
}
```
### Check Alerts
```bash
# Check for triggered alerts
uv run scripts/watchlist.py check
# Format for notification (Telegram)
uv run scripts/watchlist.py check --notify
```
**Alert Example:**
```
📢 Stock Alerts
🎯 NVDA hit target! $802.50 >= $800.00
🛑 TSLA hit stop! $195.00 <= $200.00
📊 AAPL signal changed: HOLD → BUY
```
### Remove from Watchlist
```bash
uv run scripts/watchlist.py remove NVDA
```
---
## Performance Tips
### Fast Mode
Skip slow analyses for quick checks:
```bash
# Skip insider trading + breaking news
uv run scripts/analyze_stock.py AAPL --fast
```
**Speed comparison:**
| Mode | Time | What's Skipped |
|------|------|----------------|
| Default | 5-10s | Nothing |
| `--no-insider` | 3-5s | SEC EDGAR |
| `--fast` | 2-3s | Insider + News |
### Batch Analysis
Analyze multiple stocks in one command:
```bash
uv run scripts/analyze_stock.py AAPL MSFT GOOGL AMZN META
```
### Caching
Market context is cached for 1 hour:
- VIX, SPY, QQQ trends
- Fear & Greed Index
- VIX term structure
- Breaking news
Second analysis of different stock reuses cached data.
---
## Interpreting Results
### Recommendation Thresholds
| Score | Recommendation |
|-------|----------------|
| > +0.33 | BUY |
| -0.33 to +0.33 | HOLD |
| < -0.33 | SELL |
### Confidence Levels
| Confidence | Meaning |
|------------|---------|
| > 80% | Strong conviction |
| 60-80% | Moderate conviction |
| 40-60% | Mixed signals |
| < 40% | Low conviction |
### Reading Caveats
**Always read the caveats!** They often contain critical information:
```
CAVEATS:
• Earnings in 5 days - high volatility expected ← Timing risk
• RSI 78 (overbought) + near 52w high ← Technical risk
• ⚠️ BREAKING NEWS: Fed emergency rate discussion ← External risk
• ⚠️ SECTOR RISK: China tensions affect tech ← Geopolitical
```
### When to Ignore the Signal
- **Pre-earnings:** Even BUY → wait until after
- **Overbought:** Consider smaller position
- **Risk-off:** Reduce overall exposure
- **Low confidence:** Do more research
### When to Trust the Signal
- **High confidence + no major caveats**
- **Multiple supporting points align**
- **Sector is strong**
- **Market regime is favorable**
---
## Common Workflows
### Morning Check
```bash
# Check watchlist alerts
uv run scripts/watchlist.py check --notify
# Quick portfolio update
uv run scripts/analyze_stock.py --portfolio "Main" --fast
```
### Research New Stock
```bash
# Full analysis
uv run scripts/analyze_stock.py XYZ
# If dividend stock
uv run scripts/dividends.py XYZ
# Add to watchlist for monitoring
uv run scripts/watchlist.py add XYZ --alert-on signal
```
### Weekly Review
```bash
# Full portfolio analysis
uv run scripts/analyze_stock.py --portfolio "Main" --period weekly
# Check dividend holdings
uv run scripts/dividends.py JNJ PG KO
```
---
## Troubleshooting
### "Invalid ticker"
- Check spelling
- For crypto, use `-USD` suffix
- Non-US stocks may not work
### "Insufficient data"
- Stock might be too new
- ETFs have limited data
- OTC stocks often fail
### Slow Performance
- Use `--fast` for quick checks
- Insider trading is slowest
- Breaking news adds ~2s
### Missing Data
- Not all stocks have analyst coverage
- Some metrics require options chains
- Crypto has no sentiment data