akshare-stock-analysis

- "How is AAPL doing?"
- "Compare 000001 and 600036 by relative strength"

## Defaults (baked-in)

| Parameter | Default |
|---|---|
| Market | Auto-detect; only ask if unresolvable or genuinely ambiguous |
| K-line period | Daily (primary) + Weekly & Monthly for multi-timeframe |
| Time range | Last 6 months (today − 182 days) for daily; auto-extend for weekly/monthly |
| Price adjust | `qfq` for A-share; none for HK/US |
| Indicators | MA5/MA20/MA60, Bollinger Bands (20,2), MACD (12/26/9), RSI-14, ATR-14 |
| Language | Bilingual: Chinese label + English explanation |

User overrides these defaults at any time.

## Market Auto-Detection Rules

| Code pattern | Inferred market |
|---|---|
| 6-digit starting with 6 | A-share Shanghai |
| 6-digit starting with 0 or 3 | A-share Shenzhen |
| 5-digit starting with 0 | HK (prefix `0`) |
| 4–5 chars, letters | US (NYSE/NASDAQ) |
| Name only | Search A-share first, then HK; disambiguate if needed |

If detection confidence is low, list top-2 candidates and ask once.

## AkShare API Reference

| Market | AkShare function |
|---|---|
| A-share daily | `ak.stock_zh_a_hist(symbol, period="daily", start_date, end_date, adjust="qfq")` |
| A-share real-time | `ak.stock_zh_a_spot_em()` (network may fail — wrap in try/except) |
| HK daily | `ak.stock_hk_daily(symbol, adjust="qfq")` |
| US daily | `ak.stock_us_daily(symbol, adjust="qfq")` |
| A-share symbol list | `ak.stock_info_a_code_name()` |
| Financial indicators | `ak.stock_financial_analysis_indicator(symbol, start_year)` — EPS, ROE, margins (use this; `stock_a_lg_indicator` does NOT exist) |
| Latest earnings summary | `ak.stock_yjbb_em(date="YYYYMMDD")` — EPS, revenue, net profit YoY, industry |
| Industry PE | `ak.stock_industry_pe_ratio_cninfo(symbol)` |
| Macro calendar | `ak.news_economic_baidu()` — date column is `datetime.date` objects; data may be stale (up to ~2 months behind current date) |

## Scripts

All implementation code lives in `scripts/` next to this file. You can run a full analysis end-to-end with:

```bash
python .github/skills/stock-kline-analysis/scripts/run_analysis.py 000063
python .github/skills/stock-kline-analysis/scripts/run_analysis.py 贵州茅台
python .github/skills/stock-kline-analysis/scripts/run_analysis.py AAPL --out-dir /tmp/reports
```

| Script | Purpose |
|---|---|
| `scripts/run_analysis.py` | CLI orchestrator — runs all steps end-to-end |
| `scripts/fetch_kline.py` | Step 2 — multi-timeframe K-line fetch with retry/fallback |
| `scripts/indicators.py` | Step 3 — compute MA/BB/MACD/RSI/ATR for all timeframes |
| `scripts/chart.py` | Step 4 — 4-panel matplotlib chart (K线+BB \| Vol \| MACD \| RSI-14) |
| `scripts/valuation.py` | Step 5 — fetch EPS/revenue/ratios and compute PE/PB |
| `scripts/events.py` | Step 7 — macro events with hardcoded fallback calendar |

Each script has a `__main__` smoke-test (e.g. `python fetch_kline.py 000063`).

---

## Workflow

### Step 1 — Resolve Identifier

1. Apply market auto-detection rules to the raw input.
2. If code is numeric and 6-digit, run `ak.stock_info_a_code_name()` to confirm name.
3. If name is given, filter symbol list for closest match.
4. If ambiguous (>1 high-confidence match), show max 3 options and ask.
5. If unresolvable, report clearly and stop.

Completion check: one confirmed `{code, name, market}` tuple before fetching any data.

---

### Step 2 — Fetch K-Line Data

See **`scripts/fetch_kline.py`** — `fetch_all_timeframes(code, adjust="qfq")` returns `(df_daily, df_weekly, df_monthly)`, all normalized.

Key implementation notes (do NOT get wrong):
- `stock_zh_a_hist` returns **12 Chinese-named columns** — always use explicit `rename(col_map)`, never positional assignment.
- Windows: daily = last 182 days, weekly = last 365 days, monthly = last 3 years.

```python
from scripts.fetch_kline import fetch_all_timeframes
df_daily, df_weekly, df_monthly = fetch_all_timeframes(code)
```

Fallback logic:
- On network error, retry once.
- If daily fetch is empty: report (suspended / delisted / wrong symbol / holiday) and stop.
- Weekly/monthly failures: skip that timeframe and note it in output.

Completion check: `len(df_daily) > 20` and all OHLCV columns present and non-null.

---

### Step 3 — Compute Indicators

See **`scripts/indicators.py`** — `add_indicators(df)` and `add_tf_indicators(df_weekly, df_monthly)`.

Critical notes:
- `bb_width` = `(upper − lower) / mid * 100` — result is a **percentage** (e.g. 12.7, not 0.127).
- RSI must use a standalone helper; do **not** chain `.diff()` twice on the same series.
- Support/resistance stored in `df.attrs["support"]` / `df.attrs["resistance"]`.

```python
from scripts.indicators import add_indicators, add_tf_indicators
df_daily = add_indicators(df_daily)
df_weekly, df_monthly = add_tf_indicators(df_weekly, df_monthly)
```

If fewer than 60 bars exist on daily, use all available and note the limitation. Bollinger Bands require minimum 20 bars.

---

### Step 4 — Build K-Line Chart

**Primary path — matplotlib** (4-panel: K线+布林带 | 成交量 | MACD | RSI-14):

See **`scripts/chart.py`** — `plot_kline(df, code, name, out_path, market_label, dpi)` returns the saved path.

> `mplfinance` is **NOT installed** in the base environment. `chart.py` calls `matplotlib.use("Agg")` at module level — always import before pyplot.

```python
from scripts.chart import plot_kline
chart_path = plot_kline(df_daily, code=code, name=name, market_label="A股",
                        out_path=f"{code}_kline.png")
```

Fallback (text table — only if matplotlib is also unavailable), latest 20 bars:
```
date        close   MA20    BB_up   BB_low  RSI14   ATR%
2026-02-10  15.38   14.90   16.20   13.60   58.3    1.4%
...
```

---

### Step 5 — Valuation Context

See **`scripts/valuation.py`** — `fetch_valuation(code)` and `compute_pe_pb(result, last_close)`.

> `ak.stock_a_lg_indicator` and `ak.stock_a_indicator_lg` **do not exist** — use `stock_yjbb_em` + `stock_financial_analysis_indicator` instead (both implemented in `valuation.py`).

```python
from scripts.valuation import fetch_valuation, compute_pe_pb
val = fetch_valuation(code)
val = compute_pe_pb(val, last_close=float(df_daily["close"].iloc[-1]))
# val keys: eps, revenue, revenue_yoy, net_profit, net_profit_yoy,
#           book_value_per_share, roe, gross_margin, industry,
#           report_date, fin_df, pe_ttm, pb
```

For HK/US: skip valuation section or note it as unavailable.

Report:
- Current PE (TTM, computed from EPS), PB.
- ROE and net profit margin.
- Revenue/profit YoY growth from latest report.
- Industry classification.
- Note: historical PE percentile not available without `stock_a_lg_indicator`; skip that sub-bullet and state the reason.

---

### Step 6 — Portfolio / Relative Strength Mode

Activated when user provides multiple symbols (e.g. "compare 600519 and 000858").

1. Fetch 6-month daily data for all symbols (same window as default).
2. Compute normalized 6-month return (base=100 on start date).
3. Compute 20-day rolling volatility and ATR% for each symbol.
4. Rank by: return, Sharpe-proxy (return/vol), RSI, and ATR% (lower = more stable).
5. Produce a comparison table and identify the relative leader.

Single-symbol mode: compare to its own industry index if identifiable.

---

### Step 7 — Event-Aware Risk Overlay

See **`scripts/events.py`** — `fetch_events(lookback_days, lookahead_days, min_importance)` returns a list of formatted strings.

> `news_economic_baidu()` date column is `datetime.date` objects — compare natively. Data **lags 4–8 weeks**; `events.py` always appends a hardcoded China macro calendar (PMI, Two Sessions, earnings windows) regardless of API success.

```python
from scripts.events import fetch_events
event_lines = fetch_events()  # returns list[str] ready to print
```

Overlay on analysis:
- Note any major macro event dates near current price levels.
- Flag the applicable earnings season window relative to today.
- Highlight price behavior around large news days visible in the K-line.

If event API is unavailable, note it and manually annotate the known calendar dates above.

---

### Step 8 — Deliver Structured Output

Return in this exact order:

```
[Symbol Summary]
名称/代码:           e.g. 贵州茅台 (600519) · A-Share Shanghai
分析区间:            2025-09-12 → 2026-03-12 (daily 6M, qfq-adjusted)
多周期确认:          Weekly trend: Uptrend | Monthly trend: Consolidation

[K-Line Snapshot]
最新收盘:           ¥1,580.00
1日涨跌:           +1.2% (+18.80)
MA5 / MA20 / MA60: ¥1,572 / ¥1,540 / ¥1,490   (排列多头 Bullish stack)
布林带 Bollinger:  Upper ¥1,640 | Mid ¥1,540 | Lower ¥1,440  (Width: 12.7%)
ATR-14 (波动幅):   ¥22.4 / day  (1.4% of price — moderate volatility)
20日区间:           ¥1,420 – ¥1,610
成交量 vs 20日均:   +35%  (放量)

[Technical View — 技术面]
趋势 Trend:         Daily Uptrend — MA5 > MA20 > MA60, price above all MAs
                    Weekly confirm: above weekly MA20 ✓
                    Monthly confirm: testing monthly MA20 resistance ⚠
动量 Momentum:     5D: +3.1% | 10D: +5.8% | 20D: +8.2% | Ann.Vol: 18%
MACD:              MACD line above signal, histogram expanding → bullish momentum
RSI-14:            68 — approaching overbought; momentum still intact
布林挤压 BB Squeeze: Width 12.7% — expanding (breakout in progress, not overextended)
支撑 Support:      ¥1,490 (MA60 + BB lower + prior swing low)
阻力 Resistance:   ¥1,640 (BB upper) / ¥1,650 (6M high zone)
ATR止损参考:       Trailing stop = last close − 1.5×ATR = ¥1,580 − ¥33.6 ≈ ¥1,546

[Valuation — 估值]
PE (TTM):          28x — 3-year 40th percentile (moderate)
PB:                8.2x
行业 PE 中位:      25x (white spirits industry) → slight premium to peers

[Relative Strength]  (if multi-symbol mode)
Symbol   6M Return  Vol    Sharpe  RSI   ATR%   Rank
600519   +22%       18%    1.22    68    1.4%   1st ← Leader
000858   +14%       21%    0.67    55    1.7%   2nd

[Event Overlay — 事件]
- 2026-03-15: NPC economic policy announcement (macro risk)
- 2026-04-30: Q1 earnings release window (re-rating trigger)
- No major gap days observed in 6M K-line window.

[Risk & Watchpoints — 风险]
- 多单失效: If price closes below MA20 (¥1,540) on volume → trend weakening
- 布林下轨破位: Price below BB lower (¥1,440) = volatility expansion to downside
- 超买风险: RSI near 70; daily overbought but weekly RSI 58 = room still exists
- ATR止损: Position sizing reference — 1 ATR = ¥22.4; adjust size accordingly
- 突破条件: Break above BB upper (¥1,640) + volume >+50% avg → momentum continuation
```

## Quality Criteria

- Market mapping is stated and auditable.
- All indicator values are computed from actual fetched data, not estimated.
- Valuation section states data source and percentile basis.
- Event overlay explicitly covers ±30 days around analysis date.
- No language implying guaranteed price direction or investment advice.
- If any section fails (e.g. valuation API times out), skip it with an explicit note.

## Example Prompts

- "Use stock-kline-analysis to analyze 600519."
- "Use stock-kline-analysis for 贵州茅台 — show K-line with Bollinger Bands, MACD, RSI, and ATR stop-loss."
- "Use stock-kline-analysis on AAPL — multi-timeframe trend: are daily/weekly/monthly aligned?"
- "Use stock-kline-analysis to compare 600036 and 601318 by relative strength and ATR-based risk."
- "Use stock-kline-analysis for 000858 — show Bollinger squeeze and flag any upcoming earnings event."
- "Use stock-kline-analysis for TSLA — is price near Bollinger upper band? What does ATR say about position sizing?"