openclaw-stock-analysis 0.2.2 → 0.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +2 -2
  3. package/dist/index.js +228 -30
  4. package/index.ts +246 -33
  5. package/openclaw.plugin.json +13 -1
  6. package/package.json +1 -1
  7. package/schemas/report_schema.json +3 -3
  8. package/scripts/ci-resolve-llm-host.mjs +29 -0
  9. package/scripts/setup-python.mjs +11 -13
  10. package/skills/bull-trend/SKILL.md +34 -10
  11. package/skills/bull-trend/references/fat-tails.md +91 -0
  12. package/skills/bull-trend/scripts/tail_analysis.py +132 -0
  13. package/skills/event-driven/SKILL.md +8 -0
  14. package/skills/growth-quality/SKILL.md +8 -0
  15. package/skills/hot-theme/SKILL.md +3 -2
  16. package/skills/stock-analysis/SKILL.md +31 -3
  17. package/skills/stock-screener/SKILL.md +21 -1
  18. package/skills/strategy-backtest/SKILL.md +15 -5
  19. package/skills/wisburg-research/SKILL.md +2 -0
  20. package/strategies/examples/bottom_volume.yaml +5 -0
  21. package/strategies/examples/box_oscillation.yaml +5 -0
  22. package/strategies/examples/bull_trend.yaml +11 -3
  23. package/strategies/examples/dragon_head.yaml +4 -2
  24. package/strategies/examples/emotion_cycle.yaml +5 -0
  25. package/strategies/examples/ma_crossover.yaml +10 -3
  26. package/strategies/examples/rsi_oversold.yaml +5 -0
  27. package/strategies/examples/shrink_pullback.yaml +7 -1
  28. package/strategies/examples/volume_breakout.yaml +7 -1
  29. package/templates/stock_analysis/brief.md.j2 +4 -1
  30. package/templates/stock_analysis/full.md.j2 +6 -3
  31. package/tools/_cache.py +61 -0
  32. package/tools/_subproc.py +49 -0
  33. package/tools/alert_rules.py +51 -13
  34. package/tools/anomaly_detect.py +24 -35
  35. package/tools/backtest.py +202 -104
  36. package/tools/capabilities.py +16 -5
  37. package/tools/diagnostics.py +12 -6
  38. package/tools/gather.py +33 -19
  39. package/tools/import_parser.py +2 -5
  40. package/tools/lixinger.py +100 -0
  41. package/tools/market_regime.py +34 -38
  42. package/tools/market_review.py +57 -9
  43. package/tools/name_resolver.py +2 -5
  44. package/tools/pattern.py +2 -5
  45. package/tools/position_context.py +22 -7
  46. package/tools/report_renderer.py +12 -6
  47. package/tools/requirements.txt +2 -1
  48. package/tools/risk_screening.py +73 -39
  49. package/tools/screener.py +90 -20
  50. package/tools/search_intel.py +5 -13
  51. package/tools/sec_edgar.py +346 -0
  52. package/tools/sec_holders.py +263 -0
  53. package/tools/signal_tracker.py +144 -25
  54. package/tools/stock_data.py +600 -186
  55. package/tools/technical.py +152 -42
  56. package/tools/trading_calendar.py +78 -18
  57. package/tools/value_data.py +1527 -0
  58. package/tools/volume_analysis.py +2 -5
  59. package/tools/watchlist.py +26 -6
  60. package/tools/watchlist_context.py +9 -8
@@ -5,20 +5,24 @@ import argparse
5
5
  import contextlib
6
6
  import hashlib
7
7
  import json
8
+ import math
9
+ import os
8
10
  import re
9
11
  import sys
10
12
  import tempfile
11
13
  import time
12
- from datetime import datetime, timedelta
14
+ from datetime import date, datetime, timedelta
13
15
  from pathlib import Path
14
16
 
15
17
  sys.path.insert(0, str(Path(__file__).resolve().parent))
16
- from _subproc import run_tool # noqa: E402
18
+ from _cache import DAY, WEEK, cached # noqa: E402
19
+ from _subproc import run_tool, scrub_secrets, socket_timeout, utf8_stdio # noqa: E402
17
20
 
18
21
  # Explicitly exchange-prefixed A-share codes (sh600519 / sz000858 / bj920001).
19
22
  # Bare 6-digit codes are always stocks; the prefix is the disambiguation escape
20
23
  # hatch for index codes (sh000001 = 上证指数, not 平安银行).
21
24
  _A_PREFIXED_RE = re.compile(r"(?:sh|sz|bj)\d{6}", re.IGNORECASE)
25
+ _A_INDEX_RE = re.compile(r"(?:sh000\d{3}|sz399\d{3})", re.IGNORECASE)
22
26
 
23
27
 
24
28
  def detect_market(symbol: str) -> str:
@@ -40,7 +44,7 @@ def detect_market(symbol: str) -> str:
40
44
 
41
45
  def normalize_stock_code(symbol: str) -> dict:
42
46
  """Classify A-share stock code into board/type with limit-up/down ratio."""
43
- info = {"market": detect_market(symbol), "board": "main", "is_st": False, "is_etf": False, "limit_pct": 0.10}
47
+ info = {"market": detect_market(symbol), "board": "main", "is_etf": False, "limit_pct": 0.10}
44
48
  if info["market"] != "A":
45
49
  info["limit_pct"] = None
46
50
  return info
@@ -66,7 +70,7 @@ def normalize_stock_code(symbol: str) -> dict:
66
70
 
67
71
 
68
72
  def calc_limit_price(pre_close: float, ratio: float, direction: str = "up") -> float:
69
- """Calculate limit-up or limit-down price with banker's rounding."""
73
+ """Calculate limit-up or limit-down price with exchange rounding (round-half-up: floor(x*100+0.5)/100)."""
70
74
  import numpy as np
71
75
 
72
76
  sign = 1 if direction == "up" else -1
@@ -115,7 +119,7 @@ def _failover(sources: list, label: str):
115
119
  _disk_cache_set(f"sticky-{chain}", name)
116
120
  return result
117
121
  except Exception as e:
118
- errors.append(f"{name}: {type(e).__name__}: {e}")
122
+ errors.append(f"{name}: {type(e).__name__}: {scrub_secrets(str(e))}")
119
123
  if errors:
120
124
  raise RuntimeError(f"{label}: {'; '.join(errors)}")
121
125
  return None
@@ -140,7 +144,7 @@ def _kline_efinance(symbol: str, period: str, count: int) -> list:
140
144
  import efinance as ef
141
145
 
142
146
  freq_map = {"daily": 101, "weekly": 102, "monthly": 103}
143
- df = ef.stock.get_quote_history(symbol, klt=freq_map.get(period, 101))
147
+ df = ef.stock.get_quote_history(symbol, klt=freq_map.get(period, 101), fqt=1)
144
148
  if df is None or df.empty:
145
149
  raise ValueError("efinance returned empty data")
146
150
  col_map = {
@@ -204,6 +208,7 @@ def _kline_baostock(symbol: str, period: str, count: int) -> list:
204
208
  for c in ["open", "high", "low", "close", "volume"]:
205
209
  if c in df.columns:
206
210
  df[c] = pd.to_numeric(df[c], errors="coerce")
211
+ df["volume"] /= 100 # Baostock uses shares; the A-share CLI contract uses lots.
207
212
  keep = [c for c in ["date", "open", "high", "low", "close", "volume", "turnover", "change_pct"] if c in df.columns]
208
213
  df = df[keep].tail(count)
209
214
  return [_clean_row(r) for r in df.to_dict("records")]
@@ -276,6 +281,7 @@ def _tencent_payload_row(f: list, symbol: str) -> dict:
276
281
  """Build the quote row from one Tencent `~`-separated payload (already split).
277
282
  Shared by _quote_tencent (single) and _tencent_batch_quotes (snapshot leg)."""
278
283
  f += [""] * (50 - len(f)) # pad optional tail fields (pe/pb/market_cap/volume_ratio…) on short payloads
284
+ hk = detect_market(symbol) == "HK"
279
285
  turnover = _parse_float(f[37])
280
286
  market_cap = _parse_float(f[45])
281
287
  return {
@@ -284,42 +290,50 @@ def _tencent_payload_row(f: list, symbol: str) -> dict:
284
290
  "price": _parse_float(f[3]),
285
291
  "change": _parse_float(f[31]),
286
292
  "change_pct": _parse_float(f[32]),
287
- "volume": _parse_float(f[6]), # 手, same as akshare
288
- "turnover": turnover * 1e4 if turnover is not None else None,
293
+ "volume": _parse_float(f[6]), # A: 手; HK: shares, same as yfinance
294
+ "turnover": turnover * (1 if hk else 1e4) if turnover is not None else None,
289
295
  "high": _parse_float(f[33]),
290
296
  "low": _parse_float(f[34]),
291
297
  "open": _parse_float(f[5]),
292
298
  "prev_close": _parse_float(f[4]),
293
299
  "market_cap": market_cap * 1e8 if market_cap is not None else None,
294
300
  "pe": _parse_float(f[39]),
295
- "pb": _parse_float(f[46]),
296
- "turnover_rate": _parse_float(f[38]),
297
- "volume_ratio": _parse_float(f[49]),
301
+ # Tencent's HK map labels f[47] DY and f[49] WK52_Low; neither is an A-share ratio.
302
+ "pb": None if hk else _parse_float(f[46]),
303
+ "turnover_rate": None if hk else _parse_float(f[38]),
304
+ "volume_ratio": None if hk else _parse_float(f[49]),
298
305
  "amplitude": _parse_float(f[43]),
299
306
  }
300
307
 
301
308
 
302
309
  def _quote_tencent(symbol: str) -> dict:
303
- """Tencent quote via qt.gtimg.cn. GBK-encoded `v_sh600519="1~name~code~..."` fields.
310
+ """Tencent A/HK quote via qt.gtimg.cn, with a GBK-encoded `~` payload.
304
311
 
305
- Units differ from akshare: turnover arrives in 万元 and market_cap in 亿元 —
306
- both are normalized to 元 to match the rest of the chain."""
312
+ A-share turnover is 万元; HK turnover is already HKD. Market cap is 亿元
313
+ (CNY/HKD respectively); normalize monetary fields to currency units."""
307
314
  import requests
308
315
 
309
- resp = requests.get(f"https://qt.gtimg.cn/q={_cn_code(symbol)}", timeout=10)
316
+ hk = detect_market(symbol) == "HK"
317
+ if hk and not re.fullmatch(r"[0-9]{1,5}\.HK", symbol, re.IGNORECASE):
318
+ raise ValueError(f"invalid HK symbol: {symbol}")
319
+ # Tencent's hk feed is delayed 15 minutes; r_hk uses the same fields for live quotes.
320
+ code = f"r_hk{symbol[:-3].zfill(5)}" if hk else _cn_code(symbol)
321
+ resp = requests.get(f"https://qt.gtimg.cn/q={code}", timeout=10)
322
+ resp.raise_for_status()
310
323
  f = _gbk_var_payload(resp.content).split("~")
311
324
  if len(f) < 35 or not f[1]:
312
325
  raise ValueError(f"tencent returned no quote for {symbol}")
313
- row = _tencent_payload_row(f, symbol)
326
+ row = _clean_row(_tencent_payload_row(f, symbol))
327
+ if hk and (row["price"] is None or row["price"] <= 0):
328
+ raise ValueError(f"tencent returned no quote for {symbol}")
314
329
  if normalize_stock_code(symbol)["is_etf"]:
315
330
  row["is_etf"] = True
316
- return _clean_row(row)
331
+ return row
317
332
 
318
333
 
319
334
  def _kline_tencent(symbol: str, period: str, count: int) -> list:
320
335
  """Tencent kline via web.ifzq.gtimg.cn. Rows are [date, open, close, high, low,
321
- volume(手)] ascending; qfq-adjusted like akshare. When a symbol has no qfq series
322
- (e.g. BSE codes) the endpoint returns the raw `day/week/month` key instead."""
336
+ volume(手)] ascending; raw series are accepted only for explicit indices."""
323
337
  import requests
324
338
 
325
339
  p_map = {"daily": "day", "weekly": "week", "monthly": "month"}
@@ -334,9 +348,9 @@ def _kline_tencent(symbol: str, period: str, count: int) -> list:
334
348
  if data.get("code") != 0:
335
349
  raise ValueError(f"tencent kline failed: {data.get('msg', '')}")
336
350
  node = data.get("data", {}).get(code, {})
337
- rows = node.get(f"qfq{p}") or node.get(p)
351
+ rows = node.get(p) if _A_INDEX_RE.fullmatch(symbol) else node.get(f"qfq{p}")
338
352
  if not rows:
339
- raise ValueError("tencent kline returned empty data")
353
+ raise ValueError("tencent kline returned empty data for required adjustment")
340
354
  return [
341
355
  _clean_row(
342
356
  {
@@ -429,16 +443,16 @@ def _sanitize(obj):
429
443
  import numpy as np
430
444
  import pandas as pd
431
445
 
432
- if isinstance(obj, (pd.Timestamp, datetime)):
433
- return obj.strftime("%Y-%m-%d")
446
+ if isinstance(obj, (pd.Timestamp, datetime, date)):
447
+ return None if pd.isna(obj) else obj.strftime("%Y-%m-%d")
434
448
  if isinstance(obj, (np.integer,)):
435
449
  return int(obj)
436
450
  if isinstance(obj, (np.floating,)):
437
- return None if np.isnan(obj) else round(float(obj), 4)
451
+ return round(float(obj), 4) if np.isfinite(obj) else None
438
452
  if isinstance(obj, (np.bool_,)):
439
453
  return bool(obj)
440
454
  if isinstance(obj, float):
441
- return None if obj != obj else round(obj, 4)
455
+ return round(obj, 4) if np.isfinite(obj) else None
442
456
  return obj
443
457
 
444
458
 
@@ -450,27 +464,26 @@ def _clean_row(d: dict) -> dict:
450
464
 
451
465
 
452
466
  def kline_a(symbol: str, period: str, count: int) -> list:
453
- """A-share kline with failover: akshare → tushare → efinance → tencent → sina → pytdx → baostock.
467
+ """A-share qfq kline: akshare → tushare → efinance → tencent → baostock.
454
468
 
455
- Explicitly-prefixed symbols (sh000001, typically indices) skip the eastmoney
456
- sources — they take bare 6-digit codes only and would fail slowly first."""
457
- if _A_PREFIXED_RE.fullmatch(symbol):
469
+ Explicit indices keep raw points; unadjusted stock sources never enter the chain."""
470
+ if _A_INDEX_RE.fullmatch(symbol):
458
471
  sources = [
459
472
  ("tencent", lambda: _kline_tencent(symbol, period, count)),
460
473
  ("sina", lambda: _kline_sina(symbol, period, count)),
461
474
  ("baostock", lambda: _kline_baostock(symbol, period, count)),
462
475
  ]
463
476
  else:
477
+ symbol = symbol[2:] if _A_PREFIXED_RE.fullmatch(symbol) else symbol
464
478
  sources = [
465
479
  ("akshare", lambda: _kline_akshare(symbol, period, count)),
466
480
  ("tushare", lambda: _kline_tushare(symbol, period, count)),
467
481
  ("efinance", lambda: _kline_efinance(symbol, period, count)),
468
482
  ("tencent", lambda: _kline_tencent(symbol, period, count)),
469
- ("sina", lambda: _kline_sina(symbol, period, count)),
470
- ("pytdx", lambda: _kline_pytdx(symbol, period, count)),
471
483
  ("baostock", lambda: _kline_baostock(symbol, period, count)),
472
484
  ]
473
- return _failover(sources, label=f"kline_a:{symbol}")
485
+ with socket_timeout(25):
486
+ return _failover(sources, label=f"kline_a:{symbol}")
474
487
 
475
488
 
476
489
  def _kline_akshare(symbol: str, period: str, count: int) -> list:
@@ -514,7 +527,7 @@ def _kline_akshare(symbol: str, period: str, count: int) -> list:
514
527
 
515
528
 
516
529
  def _kline_tushare(symbol: str, period: str, count: int) -> list:
517
- """Tushare kline via HTTP API. Requires TUSHARE_TOKEN."""
530
+ """Tushare qfq kline via daily factors or the adjusted week/month endpoint."""
518
531
  import os
519
532
 
520
533
  import pandas as pd
@@ -524,23 +537,29 @@ def _kline_tushare(symbol: str, period: str, count: int) -> list:
524
537
  if not token:
525
538
  raise ValueError("TUSHARE_TOKEN not set")
526
539
 
527
- api_name_map = {"daily": "daily", "weekly": "weekly", "monthly": "monthly"}
540
+ if normalize_stock_code(symbol)["is_etf"]:
541
+ raise ValueError("tushare stock adjustment does not cover ETFs")
528
542
  end = datetime.now()
529
543
  start = end - timedelta(days=count * 7 if period == "weekly" else count * 31 if period == "monthly" else count * 2)
530
544
 
531
- ts_code = f"{symbol}.SH" if symbol.startswith(("6", "9", "5")) else f"{symbol}.SZ"
545
+ ts_code = f"{symbol}.{_cn_code(symbol)[:2].upper()}"
546
+ params = {
547
+ "ts_code": ts_code,
548
+ "start_date": start.strftime("%Y%m%d"),
549
+ "end_date": end.strftime("%Y%m%d"),
550
+ }
551
+ prices = ["open", "high", "low", "close"]
552
+ if period != "daily":
553
+ params["freq"] = "week" if period == "weekly" else "month"
554
+ fields = prices if period == "daily" else [f"{c}_qfq" for c in prices]
532
555
 
533
556
  resp = requests.post(
534
557
  "http://api.tushare.pro",
535
558
  json={
536
- "api_name": api_name_map.get(period, "daily"),
559
+ "api_name": "daily" if period == "daily" else "stk_week_month_adj",
537
560
  "token": token,
538
- "params": {
539
- "ts_code": ts_code,
540
- "start_date": start.strftime("%Y%m%d"),
541
- "end_date": end.strftime("%Y%m%d"),
542
- },
543
- "fields": "trade_date,open,high,low,close,vol,amount,pct_chg",
561
+ "params": params,
562
+ "fields": ",".join(["trade_date", *fields, "vol", "amount", "pct_chg"]),
544
563
  },
545
564
  timeout=15,
546
565
  )
@@ -549,12 +568,36 @@ def _kline_tushare(symbol: str, period: str, count: int) -> list:
549
568
  raise ValueError(f"tushare returned no data: {data.get('msg', '')}")
550
569
 
551
570
  df = pd.DataFrame(data["data"]["items"], columns=data["data"]["fields"])
571
+ if not set(fields).issubset(df.columns):
572
+ raise ValueError("tushare returned incomplete adjusted prices")
573
+ df[fields] = df[fields].apply(pd.to_numeric, errors="coerce")
574
+ if period == "daily":
575
+ factor_resp = requests.post(
576
+ "http://api.tushare.pro",
577
+ json={"api_name": "adj_factor", "token": token, "params": params, "fields": "trade_date,adj_factor"},
578
+ timeout=15,
579
+ ).json()
580
+ if factor_resp.get("code") != 0 or not factor_resp.get("data", {}).get("items"):
581
+ raise ValueError("tushare returned no adjustment factors")
582
+ factors = pd.DataFrame(factor_resp["data"]["items"], columns=factor_resp["data"]["fields"])
583
+ factors["adj_factor"] = pd.to_numeric(factors["adj_factor"], errors="coerce")
584
+ if not (factors["adj_factor"].gt(0) & factors["adj_factor"].lt(float("inf"))).all():
585
+ raise ValueError("tushare returned invalid adjustment factors")
586
+ latest_factor = factors.sort_values("trade_date").iloc[-1]["adj_factor"]
587
+ df = df.merge(factors, on="trade_date", how="left", validate="one_to_one")
588
+ if df["adj_factor"].isna().any():
589
+ raise ValueError("tushare adjustment factors missing for price dates")
590
+ df[prices] = df[prices].mul(df["adj_factor"] / latest_factor, axis=0)
591
+ else:
592
+ df = df.drop(columns=prices, errors="ignore")
593
+ df = df.rename(columns={f"{c}_qfq": c for c in prices})
594
+ if not df[prices].abs().lt(float("inf")).all().all():
595
+ raise ValueError("tushare returned invalid adjusted prices")
552
596
  col_map = {"trade_date": "date", "vol": "volume", "amount": "turnover", "pct_chg": "change_pct"}
553
597
  df = df.rename(columns=col_map)
554
598
  df = df.sort_values("date")
555
- for c in ["open", "high", "low", "close", "volume"]:
556
- if c in df.columns:
557
- df[c] = pd.to_numeric(df[c], errors="coerce")
599
+ if "volume" in df.columns:
600
+ df["volume"] = pd.to_numeric(df["volume"], errors="coerce")
558
601
  keep = [c for c in ["date", "open", "high", "low", "close", "volume", "turnover", "change_pct"] if c in df.columns]
559
602
  df = df[keep].tail(count)
560
603
  return [_clean_row(r) for r in df.to_dict("records")]
@@ -631,41 +674,6 @@ def _pytdx_connect(api) -> None:
631
674
  raise ConnectionError(f"pytdx failed to connect to any TDX server ({'; '.join(errors)})")
632
675
 
633
676
 
634
- def _kline_pytdx(symbol: str, period: str, count: int) -> list:
635
- """pytdx kline from TDX market servers. No credentials needed."""
636
- from pytdx.hq import TdxHq_API
637
-
638
- market = 1 if symbol.startswith(("6", "9", "5")) else 0
639
- freq_map = {"daily": 9, "weekly": 5, "monthly": 6}
640
-
641
- api = TdxHq_API()
642
- try:
643
- _pytdx_connect(api)
644
- data = api.get_security_bars(freq_map.get(period, 9), market, symbol, 0, count)
645
- finally:
646
- api.disconnect()
647
-
648
- if not data:
649
- raise ValueError("pytdx returned empty data")
650
-
651
- rows = []
652
- for bar in data:
653
- rows.append(
654
- _clean_row(
655
- {
656
- "date": bar["datetime"][:10],
657
- "open": bar["open"],
658
- "high": bar["high"],
659
- "low": bar["low"],
660
- "close": bar["close"],
661
- "volume": bar["vol"],
662
- "turnover": bar.get("amount"),
663
- }
664
- )
665
- )
666
- return rows[-count:]
667
-
668
-
669
677
  def _quote_pytdx(symbol: str) -> dict:
670
678
  """pytdx realtime quote from TDX market servers."""
671
679
  from pytdx.hq import TdxHq_API
@@ -870,7 +878,7 @@ def _kline_alphavantage(symbol: str, period: str, count: int) -> list:
870
878
  "function": fn_map.get(period, fn_map["daily"]),
871
879
  "symbol": symbol,
872
880
  "apikey": api_key,
873
- "outputsize": "compact",
881
+ "outputsize": "full" if count > 100 else "compact",
874
882
  },
875
883
  timeout=20,
876
884
  )
@@ -884,14 +892,19 @@ def _kline_alphavantage(symbol: str, period: str, count: int) -> list:
884
892
 
885
893
  rows = []
886
894
  for date_str, vals in sorted(ts.items()):
895
+ close = float(vals["4. close"])
896
+ adjusted = float(vals.get("5. adjusted close", "nan"))
897
+ if not math.isfinite(close) or not math.isfinite(adjusted) or close <= 0 or adjusted <= 0:
898
+ raise ValueError("alphavantage returned invalid adjustment prices")
899
+ factor = adjusted / close
887
900
  rows.append(
888
901
  _clean_row(
889
902
  {
890
903
  "date": date_str,
891
- "open": float(vals["1. open"]),
892
- "high": float(vals["2. high"]),
893
- "low": float(vals["3. low"]),
894
- "close": float(vals["4. close"]),
904
+ "open": float(vals["1. open"]) * factor,
905
+ "high": float(vals["2. high"]) * factor,
906
+ "low": float(vals["3. low"]) * factor,
907
+ "close": adjusted,
895
908
  "volume": int(vals.get("6. volume", vals.get("5. volume", 0))),
896
909
  }
897
910
  )
@@ -965,6 +978,9 @@ def cmd_kline(args):
965
978
  try:
966
979
  if market == "A":
967
980
  data = kline_a(args.symbol, args.period, args.count)
981
+ if data:
982
+ adjusted = "none" if _A_INDEX_RE.fullmatch(args.symbol) else "qfq"
983
+ data = [dict(row, adjusted=adjusted) for row in data]
968
984
  else:
969
985
  data = kline_yf(args.symbol, args.period, args.count)
970
986
  return data
@@ -984,7 +1000,8 @@ def quote_a(symbol: str) -> dict:
984
1000
  (quote_a_etf) so a stock-side winner never demotes the fund-spot source."""
985
1001
  if _A_PREFIXED_RE.fullmatch(symbol):
986
1002
  sources = [("tencent", lambda: _quote_tencent(symbol)), ("sina", lambda: _quote_sina(symbol))]
987
- return _failover(sources, label=f"quote_a:{symbol}")
1003
+ with socket_timeout(25):
1004
+ return _failover(sources, label=f"quote_a:{symbol}")
988
1005
  is_etf = normalize_stock_code(symbol)["is_etf"]
989
1006
  sources = []
990
1007
  if is_etf:
@@ -998,11 +1015,18 @@ def quote_a(symbol: str) -> dict:
998
1015
  ("pytdx", lambda: _quote_pytdx(symbol)),
999
1016
  ]
1000
1017
  chain = "quote_a_etf" if is_etf else "quote_a"
1001
- return _failover(sources, label=f"{chain}:{symbol}")
1018
+ with socket_timeout(25):
1019
+ return _failover(sources, label=f"{chain}:{symbol}")
1002
1020
 
1003
1021
 
1004
1022
  def _quote_akshare_etf(symbol: str) -> dict:
1005
- """A-share ETF realtime quote via akshare fund_etf_spot_em."""
1023
+ """A-share ETF realtime quote via akshare fund_etf_spot_em.
1024
+
1025
+ On top of the stock-shaped fields, the same spot row carries fund-native
1026
+ columns: iopv (盘中实时估值) and fund_shares (最新份额). premium_discount_rate
1027
+ is derived here as (price - iopv) / iopv * 100 — positive = 溢价 (price above
1028
+ IOPV), negative = 折价; None when the fund publishes no intraday IOPV (money/
1029
+ bond ETFs)."""
1006
1030
  import akshare as ak
1007
1031
 
1008
1032
  df = _akshare_retry(ak.fund_etf_spot_em)
@@ -1010,7 +1034,7 @@ def _quote_akshare_etf(symbol: str) -> dict:
1010
1034
  if row.empty:
1011
1035
  raise ValueError(f"ETF {symbol} not found in akshare fund spot")
1012
1036
  r = row.iloc[0]
1013
- return _clean_row(
1037
+ result = _clean_row(
1014
1038
  {
1015
1039
  "symbol": symbol,
1016
1040
  "name": r.get("名称"),
@@ -1027,8 +1051,13 @@ def _quote_akshare_etf(symbol: str) -> dict:
1027
1051
  "turnover_rate": r.get("换手率"),
1028
1052
  "volume_ratio": r.get("量比"),
1029
1053
  "is_etf": True,
1054
+ "iopv": r.get("IOPV实时估值"),
1055
+ "fund_shares": r.get("最新份额"),
1030
1056
  }
1031
1057
  )
1058
+ price, iopv = result.get("price"), result.get("iopv")
1059
+ result["premium_discount_rate"] = round((price - iopv) / iopv * 100, 4) if price is not None and iopv else None
1060
+ return result
1032
1061
 
1033
1062
 
1034
1063
  def _quote_akshare(symbol: str) -> dict:
@@ -1116,7 +1145,17 @@ def _quote_finnhub(symbol: str) -> dict:
1116
1145
 
1117
1146
 
1118
1147
  def quote_yf(symbol: str) -> dict:
1119
- """HK/US/JP/KR/TW quote. Failover: yfinance → finnhub/longbridge (HK/US) → alphavantage (US only)."""
1148
+ """HK adds Tencent after yfinance; US/JP/KR/TW keep their existing failover chains."""
1149
+ if detect_market(symbol) == "HK":
1150
+ return _failover(
1151
+ [
1152
+ ("yfinance", lambda: _quote_yfinance(symbol)),
1153
+ ("tencent", lambda: _quote_tencent(symbol)),
1154
+ ("finnhub", lambda: _quote_finnhub(symbol)),
1155
+ ("longbridge", lambda: _quote_longbridge(symbol)),
1156
+ ],
1157
+ label=f"quote:{symbol}",
1158
+ )
1120
1159
  return _yf_failover(
1121
1160
  symbol,
1122
1161
  lambda: _quote_yfinance(symbol),
@@ -1228,8 +1267,12 @@ def cmd_capital_flow(args):
1228
1267
  try:
1229
1268
  import akshare as ak
1230
1269
 
1231
- market = "sh" if args.symbol.startswith("6") else "sz"
1232
- df = _akshare_retry(ak.stock_individual_fund_flow, stock=args.symbol, market=market)
1270
+ # Exchange via the shared prefix helper: bare 9/5-prefix SH codes, BSE
1271
+ # (43/81-83/87/88/92) and explicitly-prefixed input (sh600519) all resolve;
1272
+ # akshare wants the bare 6-digit stock plus market ∈ {sh, sz, bj}.
1273
+ code = _cn_code(args.symbol)
1274
+ market, stock = code[:2], code[2:]
1275
+ df = _akshare_retry(ak.stock_individual_fund_flow, stock=stock, market=market)
1233
1276
  col_map = {
1234
1277
  "日期": "date",
1235
1278
  "主力净流入-净额": "main_net_inflow",
@@ -1332,39 +1375,113 @@ def cmd_news(args):
1332
1375
  # --------------- financials ---------------
1333
1376
 
1334
1377
 
1335
- def financials_a(symbol: str) -> dict:
1378
+ def _financials_a_row(r) -> dict:
1379
+ return _clean_row(
1380
+ {
1381
+ "report_date": r.get("日期"),
1382
+ "roe": r.get("净资产收益率(%)"),
1383
+ "net_profit_margin": r.get("销售净利率(%)"),
1384
+ "gross_margin": r.get("销售毛利率(%)"),
1385
+ "debt_ratio": r.get("资产负债率(%)"),
1386
+ "current_ratio": r.get("流动比率"),
1387
+ }
1388
+ )
1389
+
1390
+
1391
+ def _cached_frame(key, fetch):
1392
+ import pandas as pd
1393
+
1394
+ rows = cached(key, DAY, lambda: [_clean_row(r) for r in fetch().to_dict("records")])
1395
+ return pd.DataFrame(rows)
1396
+
1397
+
1398
+ def _yf_info(symbol, ticker):
1399
+ def fetch():
1400
+ info = ticker.info
1401
+ if not isinstance(info, dict) or not any(
1402
+ info.get(k) for k in ("shortName", "longName", "currency", "exchange")
1403
+ ):
1404
+ raise ValueError("Yahoo basic information unavailable")
1405
+ return info
1406
+
1407
+ return cached(f"yf-basic-info:{_yf_hk_symbol(symbol)}", DAY, fetch)
1408
+
1409
+
1410
+ def _financials_a_frame(symbol):
1336
1411
  import akshare as ak
1337
1412
 
1413
+ df = _cached_frame(
1414
+ f"financial-source:{symbol}", lambda: _akshare_retry(ak.stock_financial_analysis_indicator, symbol=symbol)
1415
+ )
1416
+ return df.sort_values("日期", ascending=False) if "日期" in df.columns else df
1417
+
1418
+
1419
+ def financials_a(symbol: str, periods: int = 1, annual: bool = False) -> dict:
1338
1420
  try:
1339
- df = _akshare_retry(ak.stock_financial_analysis_indicator, symbol=symbol)
1421
+ df = _financials_a_frame(symbol)
1422
+ if annual and not df.empty:
1423
+ df = df[df["日期"].astype(str).str.endswith("12-31")]
1340
1424
  if df is None or df.empty:
1341
- return {"symbol": symbol, "error": "No financial data"}
1342
- r = df.iloc[0]
1343
- return _clean_row(
1344
- {
1345
- "symbol": symbol,
1346
- "report_date": r.get("日期"),
1347
- "roe": r.get("净资产收益率(%)"),
1348
- "net_profit_margin": r.get("销售净利率(%)"),
1349
- "gross_margin": r.get("销售毛利率(%)"),
1350
- "debt_ratio": r.get("资产负债率(%)"),
1351
- "current_ratio": r.get("流动比率"),
1352
- }
1353
- )
1425
+ # error + note coexist (additive): consumers check either key
1426
+ return {"symbol": symbol, "error": "No financial data", "note": "No financial data"}
1427
+ result = {"symbol": symbol, **_financials_a_row(df.iloc[0])}
1428
+ if periods > 1:
1429
+ result["periods"] = [_financials_a_row(r) for r in df.head(periods).to_dict("records")]
1430
+ result["available_periods"] = len(result["periods"])
1431
+ return result
1354
1432
  except Exception:
1355
- return {"symbol": symbol, "note": "Financial data unavailable"}
1433
+ return {"symbol": symbol, "error": "Financial data unavailable", "note": "Financial data unavailable"}
1356
1434
 
1357
1435
 
1358
- def financials_yf(symbol: str) -> dict:
1436
+ def _yf_financial_periods(t, periods: int) -> list:
1437
+ """Best-effort annual history from yfinance's income statement (t.info is a
1438
+ snapshot only). Silent [] on any failure — multi-period is a bonus, never a blocker."""
1439
+ try:
1440
+ fin = t.financials
1441
+ if fin is None or fin.empty:
1442
+ return []
1443
+ rows = []
1444
+ for col in list(fin.columns)[:periods]:
1445
+ revenue = _sanitize(_parse_float(fin[col].get("Total Revenue")))
1446
+ profit = _sanitize(_parse_float(fin[col].get("Net Income")))
1447
+ gross = _sanitize(_parse_float(fin[col].get("Gross Profit")))
1448
+ rows.append(
1449
+ _clean_row(
1450
+ {
1451
+ "period_end": col,
1452
+ "total_revenue": revenue,
1453
+ "net_income": profit,
1454
+ "net_profit_margin": profit / revenue * 100
1455
+ if profit is not None and revenue and revenue > 0
1456
+ else None,
1457
+ "gross_margin": gross / revenue * 100
1458
+ if gross is not None and revenue and revenue > 0
1459
+ else None,
1460
+ }
1461
+ )
1462
+ )
1463
+ return rows
1464
+ except Exception:
1465
+ return []
1466
+
1467
+
1468
+ def financials_yf(symbol: str, periods: int = 1, annual: bool = False) -> dict:
1359
1469
  import yfinance as yf
1360
1470
 
1361
1471
  t = yf.Ticker(_yf_hk_symbol(symbol))
1362
- info = t.info
1363
- return _clean_row(
1472
+ warnings = []
1473
+ try:
1474
+ info = _yf_info(symbol, t)
1475
+ except Exception:
1476
+ info = {}
1477
+ warnings.append("Yahoo snapshot unavailable")
1478
+ result = _clean_row(
1364
1479
  {
1365
1480
  "symbol": symbol,
1366
1481
  "name": info.get("shortName"),
1482
+ "currency": info.get("financialCurrency"),
1367
1483
  "market_cap": info.get("marketCap"),
1484
+ "market_cap_currency": info.get("currency"),
1368
1485
  "pe": info.get("trailingPE"),
1369
1486
  "forward_pe": info.get("forwardPE"),
1370
1487
  "pb": info.get("priceToBook"),
@@ -1376,12 +1493,94 @@ def financials_yf(symbol: str) -> dict:
1376
1493
  "dividend_yield": info.get("dividendYield"),
1377
1494
  }
1378
1495
  )
1496
+ if warnings:
1497
+ result["warnings"] = warnings
1498
+ if periods > 1 or (annual and detect_market(symbol) == "HK"):
1499
+ history = cached(f"yf-income-history:{_yf_hk_symbol(symbol)}", DAY, lambda: _yf_financial_periods(t, 40))[
1500
+ :periods
1501
+ ]
1502
+ if detect_market(symbol) == "HK" and annual:
1503
+ try:
1504
+ import akshare as ak
1505
+
1506
+ hk_symbol = _yf_hk_symbol(symbol).split(".")[0].zfill(5)
1507
+ df = _cached_frame(
1508
+ f"hk-annual-indicators:{hk_symbol}",
1509
+ lambda: _akshare_retry(
1510
+ ak.stock_financial_hk_analysis_indicator_em, symbol=hk_symbol, indicator="年度"
1511
+ ),
1512
+ )
1513
+ if df.empty:
1514
+ raise ValueError("HK annual indicators unavailable")
1515
+ if df is not None and not df.empty:
1516
+ df = df.sort_values("REPORT_DATE", ascending=False)
1517
+ history = [
1518
+ _clean_row(
1519
+ {
1520
+ "report_date": str(r.get("REPORT_DATE"))[:10],
1521
+ "roe": r.get("ROE_AVG"),
1522
+ "gross_margin": r.get("GROSS_PROFIT_RATIO"),
1523
+ "net_profit_margin": r.get("NET_PROFIT_RATIO"),
1524
+ "currency": r.get("CURRENCY"),
1525
+ }
1526
+ )
1527
+ for r in df.head(periods).to_dict("records")
1528
+ ]
1529
+ except Exception:
1530
+ result.setdefault("warnings", []).append(
1531
+ "HK annual indicators unavailable; available Yahoo history retained"
1532
+ )
1533
+ if history:
1534
+ result["periods"] = history
1535
+ result["available_periods"] = len(history)
1536
+ result["requested_periods"] = periods
1537
+ result["history_units"] = {"roe": "percent", "gross_margin": "percent", "net_profit_margin": "percent"}
1538
+ if not info and not result.get("periods"):
1539
+ result["error"] = "Financial data unavailable"
1540
+ return result
1379
1541
 
1380
1542
 
1381
1543
  def cmd_financials(args):
1544
+ periods = getattr(args, "periods", 1)
1545
+ if not 1 <= periods <= 40:
1546
+ return {"error": f"periods must be between 1 and 40, got {periods}"}
1547
+ annual = getattr(args, "annual", False)
1382
1548
  market = detect_market(args.symbol)
1383
1549
  try:
1384
- return financials_a(args.symbol) if market == "A" else financials_yf(args.symbol)
1550
+ if market == "HK":
1551
+ if os.environ.get("LIXINGER_TOKEN"):
1552
+ try:
1553
+ from lixinger import financials_hk
1554
+
1555
+ result = financials_hk(args.symbol, periods, annual)
1556
+ snapshot = financials_yf(args.symbol, 1, False)
1557
+ result.update(
1558
+ {
1559
+ key: value
1560
+ for key, value in snapshot.items()
1561
+ if key not in ("warnings", "error") and (not snapshot.get("error") or value is not None)
1562
+ }
1563
+ )
1564
+ result["snapshot_available"] = not snapshot.get("error")
1565
+ result["snapshot_source"] = "yfinance" if result["snapshot_available"] else None
1566
+ if result["snapshot_available"]:
1567
+ result["report_date"] = snapshot.get("report_date")
1568
+ if snapshot.get("warnings"):
1569
+ result.setdefault("warnings", []).extend(snapshot["warnings"])
1570
+ return result
1571
+ except Exception:
1572
+ warning = "Lixinger HK unavailable (permissions/company type/provider); existing sources retained"
1573
+ else:
1574
+ warning = "LIXINGER_TOKEN not configured; extended HK financial history unavailable"
1575
+ result = financials_yf(args.symbol, periods, annual)
1576
+ result.setdefault("warnings", []).append(warning)
1577
+ result.setdefault("source", "yfinance/eastmoney")
1578
+ if len(result.get("periods", [])) < periods:
1579
+ result["warnings"].append("Requested HK financial history incomplete")
1580
+ return result
1581
+ return (
1582
+ financials_a(args.symbol, periods, annual) if market == "A" else financials_yf(args.symbol, periods, annual)
1583
+ )
1385
1584
  except Exception as e:
1386
1585
  return {"error": str(e)}
1387
1586
 
@@ -1390,29 +1589,21 @@ def cmd_financials(args):
1390
1589
 
1391
1590
 
1392
1591
  def snapshot_a() -> list:
1393
- import socket
1394
-
1395
- # akshare/efinance leave requests timeout-less — on a blackholed network a leg
1396
- # hangs until the kernel TCP timeout (~2min), and the chain would overrun the
1397
- # caller's subprocess budget before ever reaching the tencent leg. Bound each
1398
- # blocking socket op for the chain's duration (explicit per-request timeouts,
1399
- # like the tencent leg's, still win).
1400
- old_timeout = socket.getdefaulttimeout()
1401
- socket.setdefaulttimeout(25)
1592
+ # akshare/efinance leave requests timeout-less — the chain-wide socket bound
1593
+ # (socket_timeout) is what lets the tencent leg get its turn on a dead network.
1402
1594
  try:
1403
- return _failover(
1404
- [
1405
- ("akshare", _snapshot_akshare),
1406
- ("efinance", _snapshot_efinance),
1407
- ("sina", _snapshot_sina),
1408
- ("tencent", _snapshot_tencent),
1409
- ],
1410
- label="snapshot_a",
1411
- )
1595
+ with socket_timeout(25):
1596
+ return _failover(
1597
+ [
1598
+ ("akshare", _snapshot_akshare),
1599
+ ("efinance", _snapshot_efinance),
1600
+ ("sina", _snapshot_sina),
1601
+ ("tencent", _snapshot_tencent),
1602
+ ],
1603
+ label="snapshot_a",
1604
+ )
1412
1605
  except Exception as e:
1413
1606
  return [{"error": f"A-share snapshot unavailable from all sources: {e}"}]
1414
- finally:
1415
- socket.setdefaulttimeout(old_timeout)
1416
1607
 
1417
1608
 
1418
1609
  def _snapshot_efinance() -> list:
@@ -1573,8 +1764,9 @@ def snapshot_hk() -> list:
1573
1764
  df = df.rename(columns=col_map)
1574
1765
  keep = [c for c in col_map.values() if c in df.columns]
1575
1766
  return [_clean_row(r) for r in df[keep].to_dict("records")]
1576
- except Exception:
1577
- return [{"error": "HK snapshot unavailable"}]
1767
+ except Exception as e:
1768
+ # summary only (type + short message) — never a stack trace or response body
1769
+ return [{"error": f"HK snapshot unavailable: {type(e).__name__}: {scrub_secrets(str(e))}"[:200]}]
1578
1770
 
1579
1771
 
1580
1772
  def snapshot_us() -> list:
@@ -1595,8 +1787,8 @@ def snapshot_us() -> list:
1595
1787
  df = df.rename(columns=col_map)
1596
1788
  keep = [c for c in col_map.values() if c in df.columns]
1597
1789
  return [_clean_row(r) for r in df[keep].to_dict("records")]
1598
- except Exception:
1599
- return [{"error": "US snapshot unavailable"}]
1790
+ except Exception as e:
1791
+ return [{"error": f"US snapshot unavailable: {type(e).__name__}: {scrub_secrets(str(e))}"[:200]}]
1600
1792
 
1601
1793
 
1602
1794
  def cmd_market_snapshot(args):
@@ -2004,6 +2196,12 @@ def sector_constituents_a(sector: str, board_type: str = "auto") -> dict:
2004
2196
 
2005
2197
 
2006
2198
  def cmd_sector_constituents(args):
2199
+ return cached(
2200
+ f"sector-constituents:{args.sector.strip()}:{args.board_type}", WEEK, lambda: _sector_constituents(args)
2201
+ )
2202
+
2203
+
2204
+ def _sector_constituents(args):
2007
2205
  # argparse 保证属性存在;空串仍可传入
2008
2206
  sector = args.sector.strip()
2009
2207
  if not sector:
@@ -2012,9 +2210,6 @@ def cmd_sector_constituents(args):
2012
2210
  # Sector names are user input — hash them instead of sanitizing, so names that
2013
2211
  # differ only in whitespace/punctuation (创新药 vs 创新 药) can't collide.
2014
2212
  cache_key = hashlib.sha256(f"{sector}|{board_type}".encode()).hexdigest()[:16]
2015
- cached = _disk_cache_get(cache_key)
2016
- if cached is not None:
2017
- return cached
2018
2213
  try:
2019
2214
  result = sector_constituents_a(sector, board_type)
2020
2215
  except Exception as e:
@@ -2118,13 +2313,17 @@ def _stock_boards_cninfo(symbol: str) -> list:
2118
2313
  def _stock_boards_from_cache(symbol: str) -> list:
2119
2314
  """Reverse lookup against the get_sector_constituents disk cache — the honest
2120
2315
  fallback when eastmoney blocks the caller's IP and xueqiu has no token (the two
2121
- live A-share sources are both eastmoney-flavored). Reads every unexpired
2122
- constituents payload in the cache dir and returns one entry per cached sector
2316
+ live A-share sources are both eastmoney-flavored). Reads week-lived user-directory entries plus legacy temporary payloads,
2317
+ and returns one entry per cached sector
2123
2318
  containing the symbol. Cold cache → []; malformed cache files are skipped
2124
2319
  (_disk_cache_get returns None on expiry, bad JSON, or read errors)."""
2320
+ from itertools import chain
2321
+
2322
+ from _cache import cached_values
2323
+
2125
2324
  boards = []
2126
- for path in _DATA_CACHE_DIR.glob("*.json"):
2127
- data = _disk_cache_get(path.stem)
2325
+ legacy = (_disk_cache_get(path.stem) for path in _DATA_CACHE_DIR.glob("*.json"))
2326
+ for data in chain(legacy, cached_values("sector-constituents", WEEK)):
2128
2327
  if not isinstance(data, dict):
2129
2328
  continue
2130
2329
  sector = data.get("sector")
@@ -2132,7 +2331,9 @@ def _stock_boards_from_cache(symbol: str) -> list:
2132
2331
  continue
2133
2332
  for row in data.get("constituents") or []:
2134
2333
  if isinstance(row, dict) and str(row.get("code")) == symbol:
2135
- boards.append(_board_entry(sector, "cache", data.get("board_type", "")))
2334
+ board = _board_entry(sector, "cache", data.get("board_type", ""))
2335
+ if board not in boards:
2336
+ boards.append(board)
2136
2337
  break
2137
2338
  return boards
2138
2339
 
@@ -2177,6 +2378,12 @@ def _resolve_leg_down(name: str) -> bool:
2177
2378
 
2178
2379
 
2179
2380
  def resolve_stock_sectors(symbol: str, info_map=None) -> dict:
2381
+ if info_map is not None:
2382
+ return _resolve_stock_sectors(symbol, info_map)
2383
+ return cached(f"stock-sectors:{symbol}", WEEK, lambda: _resolve_stock_sectors(symbol, info_map))
2384
+
2385
+
2386
+ def _resolve_stock_sectors(symbol: str, info_map=None) -> dict:
2180
2387
  """Reverse map: stock → boards it belongs to (A/HK). Sources are merged (a single
2181
2388
  source failing is not fatal — the others' boards are still returned) rather than
2182
2389
  first-hit failover: each source covers a different flavor (industry vs concept).
@@ -2220,29 +2427,22 @@ def resolve_stock_sectors(symbol: str, info_map=None) -> dict:
2220
2427
  except _DataMiss as e:
2221
2428
  # per-symbol miss (provider answered but doesn't cover this code) —
2222
2429
  # not an outage: never poison the leg for every other symbol
2223
- errors.append(f"{name}: {type(e).__name__}: {e}")
2430
+ errors.append(f"{name}: {type(e).__name__}: {scrub_secrets(str(e))}")
2224
2431
  except Exception as e:
2225
- errors.append(f"{name}: {type(e).__name__}: {e}")
2432
+ errors.append(f"{name}: {type(e).__name__}: {scrub_secrets(str(e))}")
2226
2433
  if negative_cache and not offline_em:
2227
2434
  _disk_cache_set(f"resolve-down-{name}", time.time())
2228
2435
 
2229
2436
  if market == "A":
2230
2437
  # akshare/efinance leave requests timeout-less — on a blackholed network a leg
2231
- # hangs until the kernel TCP timeout (snapshot_a has the same guard). Bound
2232
- # each blocking socket op so every leg gets its turn within the caller's
2233
- # subprocess budget.
2234
- import socket
2235
-
2236
- old_timeout = socket.getdefaulttimeout()
2237
- socket.setdefaulttimeout(25)
2238
- try:
2438
+ # hangs until the kernel TCP timeout; the chain-wide socket bound
2439
+ # (socket_timeout) gives every leg its turn within the caller's budget.
2440
+ with socket_timeout(25):
2239
2441
  run_legs(sources, negative_cache=True)
2240
2442
  # cninfo last: the token-free non-eastmoney active fallback (issue #35),
2241
2443
  # tried only when everything above yielded nothing
2242
2444
  if not sectors:
2243
2445
  run_legs([("cninfo", lambda: _stock_boards_cninfo(symbol))], negative_cache=True)
2244
- finally:
2245
- socket.setdefaulttimeout(old_timeout)
2246
2446
  else:
2247
2447
  run_legs(sources, negative_cache=False)
2248
2448
  seen = set()
@@ -2260,6 +2460,8 @@ def resolve_stock_sectors(symbol: str, info_map=None) -> dict:
2260
2460
  result["error"] = error
2261
2461
  return result
2262
2462
  result["sectors"] = deduped
2463
+ if errors:
2464
+ result["warnings"] = errors
2263
2465
  return result
2264
2466
 
2265
2467
 
@@ -2273,9 +2475,15 @@ def cmd_stock_info(args):
2273
2475
  import akshare as ak
2274
2476
 
2275
2477
  result = {"symbol": args.symbol, "market": "A"}
2478
+ is_etf = normalize_stock_code(args.symbol)["is_etf"]
2479
+ if is_etf:
2480
+ result["is_etf"] = True
2276
2481
  info_map = None
2277
2482
  try:
2278
- df = _akshare_retry(ak.stock_individual_info_em, symbol=args.symbol)
2483
+ df = _cached_frame(
2484
+ f"a-basic-info:{args.symbol}",
2485
+ lambda: _akshare_retry(ak.stock_individual_info_em, symbol=args.symbol),
2486
+ )
2279
2487
  if df is not None and not df.empty:
2280
2488
  info_map = {}
2281
2489
  for _, row in df.iterrows():
@@ -2287,22 +2495,51 @@ def cmd_stock_info(args):
2287
2495
  result["float_shares"] = info_map.get("流通股")
2288
2496
  result["total_market_cap"] = info_map.get("总市值")
2289
2497
  result["float_market_cap"] = info_map.get("流通市值")
2498
+ else:
2499
+ result.setdefault("warnings", []).append("basic information unavailable")
2290
2500
  except Exception:
2291
- pass
2501
+ result.setdefault("warnings", []).append("basic information unavailable")
2292
2502
  try:
2293
2503
  # boards 复用 resolve_stock_sectors;info_map 透传避免东财二次拉取
2294
2504
  resolved = resolve_stock_sectors(args.symbol, info_map=info_map)
2295
2505
  boards = [s["name"] for s in resolved.get("sectors", [])]
2296
2506
  if boards:
2297
2507
  result["boards"] = boards[:10]
2508
+ if resolved.get("error") or resolved.get("warnings"):
2509
+ result.setdefault("warnings", []).append("sector mapping incomplete")
2298
2510
  except Exception:
2299
- pass
2511
+ result.setdefault("warnings", []).append("sector mapping unavailable")
2512
+ if is_etf:
2513
+ try:
2514
+ # ETF 最新净值(天天基金-场内基金历史净值明细)。窄日期窗口 → 单页返回
2515
+ end = datetime.now()
2516
+ start = end - timedelta(days=30)
2517
+ nav_df = _cached_frame(
2518
+ f"etf-basic-nav:{args.symbol}",
2519
+ lambda: _akshare_retry(
2520
+ ak.fund_etf_fund_info_em,
2521
+ fund=args.symbol,
2522
+ start_date=start.strftime("%Y%m%d"),
2523
+ end_date=end.strftime("%Y%m%d"),
2524
+ ),
2525
+ )
2526
+ if nav_df is not None and not nav_df.empty:
2527
+ latest = nav_df.iloc[-1]
2528
+ result["nav"] = latest.get("单位净值")
2529
+ result["accumulated_nav"] = latest.get("累计净值")
2530
+ nav_date = latest.get("净值日期")
2531
+ if nav_date is not None:
2532
+ result["nav_date"] = str(nav_date)[:10] # datetime.date/Timestamp → ISO date
2533
+ else:
2534
+ result.setdefault("warnings", []).append("ETF NAV unavailable")
2535
+ except Exception:
2536
+ result.setdefault("warnings", []).append("ETF NAV unavailable")
2300
2537
  return _clean_row(result)
2301
2538
  else:
2302
2539
  import yfinance as yf
2303
2540
 
2304
2541
  t = yf.Ticker(_yf_hk_symbol(args.symbol))
2305
- info = t.info
2542
+ info = _yf_info(args.symbol, t)
2306
2543
  return _clean_row(
2307
2544
  {
2308
2545
  "symbol": args.symbol,
@@ -2470,7 +2707,7 @@ def cmd_fundamental_context(args):
2470
2707
  result["valuation"] = {}
2471
2708
 
2472
2709
  try:
2473
- df = _akshare_retry(ak.stock_financial_analysis_indicator, symbol=args.symbol)
2710
+ df = _financials_a_frame(args.symbol)
2474
2711
  if df is not None and len(df) >= 1:
2475
2712
  r0 = df.iloc[0]
2476
2713
  profitability = {
@@ -2744,24 +2981,6 @@ def _hot_stocks_em() -> list:
2744
2981
  return [_strip_exchange_prefix(_clean_row(r)) for r in df[keep].to_dict("records")]
2745
2982
 
2746
2983
 
2747
- def _hot_stocks_xq() -> list:
2748
- """Xueqiu follow ranking via akshare stock_hot_follow_xq. No 涨跌幅 column;
2749
- rank is the row position. Codes arrive SH/SZ-prefixed like eastmoney's."""
2750
- import akshare as ak
2751
-
2752
- df = _akshare_retry(ak.stock_hot_follow_xq, symbol="最热门")
2753
- if df is None or df.empty:
2754
- return []
2755
- col_map = {
2756
- "股票代码": "code",
2757
- "股票简称": "name",
2758
- "最新价": "price",
2759
- }
2760
- df = df.rename(columns=col_map)
2761
- keep = [c for c in col_map.values() if c in df.columns]
2762
- return [{"rank": i, **_strip_exchange_prefix(_clean_row(r))} for i, r in enumerate(df[keep].to_dict("records"), 1)]
2763
-
2764
-
2765
2984
  def _hot_stocks_baidu() -> list:
2766
2985
  """Baidu 股市通热搜 via akshare stock_hot_search_baidu. No code/price columns —
2767
2986
  only the stock name — and 涨跌幅 strings carry a % suffix."""
@@ -2783,10 +3002,13 @@ def _hot_stocks_baidu() -> list:
2783
3002
 
2784
3003
 
2785
3004
  def cmd_hot_stocks(args):
2786
- """A-share popularity ranking (人气榜): eastmoney → xueqiu → baidu."""
3005
+ """A-share popularity ranking (人气榜): eastmoney → baidu.
3006
+
3007
+ The xueqiu leg was dropped: akshare's stock_hot_follow_xq accepts no user token
3008
+ and its built-in xq_a_token is stale (xueqiu answers 400016), so the leg could
3009
+ never win — failover errors now name only the sources that actually ran."""
2787
3010
  sources = [
2788
3011
  _sourced("eastmoney", _hot_stocks_em),
2789
- _sourced("xueqiu", _hot_stocks_xq),
2790
3012
  _sourced("baidu", _hot_stocks_baidu),
2791
3013
  ]
2792
3014
  try:
@@ -2799,6 +3021,188 @@ def cmd_hot_stocks(args):
2799
3021
  return {"count": len(items), "items": items, "source": rows[0]["source"]}
2800
3022
 
2801
3023
 
3024
+ # --------------- margin_trading / northbound_flow (A-share only) ---------------
3025
+
3026
+ # Exchange margin-detail column layouts differ: SSE carries 融资偿还额/融券偿还量,
3027
+ # SZSE carries 融券余额/融资融券余额 — the output keys below follow the source.
3028
+ _MARGIN_DETAIL_SSE_COLS = {
3029
+ "标的证券代码": "symbol",
3030
+ "标的证券简称": "name",
3031
+ "融资余额": "margin_balance",
3032
+ "融资买入额": "margin_buy",
3033
+ "融资偿还额": "margin_repay",
3034
+ "融券余量": "short_balance_shares",
3035
+ "融券卖出量": "short_sell_shares",
3036
+ "融券偿还量": "short_repay_shares",
3037
+ }
3038
+
3039
+ _MARGIN_DETAIL_SZSE_COLS = {
3040
+ "证券代码": "symbol",
3041
+ "证券简称": "name",
3042
+ "融资买入额": "margin_buy",
3043
+ "融资余额": "margin_balance",
3044
+ "融券卖出量": "short_sell_shares",
3045
+ "融券余量": "short_balance_shares",
3046
+ "融券余额": "short_balance",
3047
+ "融资融券余额": "total_balance",
3048
+ }
3049
+
3050
+
3051
+ def cmd_margin_trading(args):
3052
+ """Per-stock margin trading detail (融资融券) for the last N trading days.
3053
+
3054
+ akshare has no per-stock margin history endpoint — the exchange detail lists
3055
+ (stock_margin_detail_sse / stock_margin_detail_szse) are per-day, all-stock
3056
+ tables, so each trading day is fetched and filtered to the symbol. Daily fetches
3057
+ are independent and run concurrently (5 workers; a serial 60-day run would
3058
+ overrun the host's 120s subprocess budget), then re-sorted newest-first — the
3059
+ output never depends on completion order. A day that fails or has no data is
3060
+ skipped (两融明细 T 日晚间才发布 — a morning run always misses the latest day);
3061
+ only when every day failed is an error returned. Days where the symbol is
3062
+ absent (non-margin underlying that day) are skipped; if no day yields a row the
3063
+ symbol is reported as not covered."""
3064
+ if detect_market(args.symbol) != "A":
3065
+ return {"error": "margin_trading only available for A-shares"}
3066
+ days = getattr(args, "days", 10)
3067
+ if days < 1:
3068
+ return {"error": f"days must be a positive integer, got {days}"}
3069
+ # One akshare call per day — cap the fan-out so a slow source can't overrun
3070
+ # the host's subprocess budget (rows carry their dates; truncation is evident).
3071
+ days = min(days, 60)
3072
+ code = _cn_code(args.symbol)
3073
+ exchange, bare = code[:2], code[2:]
3074
+ try:
3075
+ import concurrent.futures
3076
+
3077
+ import akshare as ak
3078
+ from trading_calendar import prev_trading_days
3079
+
3080
+ if exchange == "sh":
3081
+ col_map = _MARGIN_DETAIL_SSE_COLS
3082
+ detail_fn = ak.stock_margin_detail_sse
3083
+ elif exchange == "sz":
3084
+ col_map = _MARGIN_DETAIL_SZSE_COLS
3085
+ detail_fn = ak.stock_margin_detail_szse
3086
+ else:
3087
+ return {"error": f"margin_trading: {args.symbol} is a BSE code; only SSE/SZSE margin detail is available"}
3088
+ trade_days = prev_trading_days("CN", days)
3089
+ if not trade_days:
3090
+ return {"error": "margin_trading: trading calendar unavailable"}
3091
+
3092
+ def fetch_day(date_iso):
3093
+ """Fetch + filter one day's all-stock table, fault-isolated per day."""
3094
+ try:
3095
+ df = _akshare_retry(detail_fn, date=date_iso.replace("-", ""))
3096
+ except Exception as e:
3097
+ return date_iso, [], f"{date_iso}: {type(e).__name__}: {scrub_secrets(str(e))}"
3098
+ if df is None or df.empty:
3099
+ return date_iso, [], None
3100
+ df = df.rename(columns=col_map)
3101
+ keep = [c for c in col_map.values() if c in df.columns]
3102
+ hit = df[df["symbol"].astype(str) == bare] if "symbol" in df.columns else df.iloc[0:0]
3103
+ return date_iso, [{"date": date_iso, **_clean_row(r)} for r in hit[keep].to_dict("records")], None
3104
+
3105
+ rows = []
3106
+ failures = []
3107
+ with socket_timeout(25), concurrent.futures.ThreadPoolExecutor(max_workers=5) as pool:
3108
+ for _date_iso, day_rows, failure in pool.map(fetch_day, trade_days):
3109
+ if failure:
3110
+ failures.append(failure)
3111
+ rows.extend(day_rows)
3112
+ rows.sort(key=lambda r: r["date"], reverse=True)
3113
+ if not rows:
3114
+ if failures:
3115
+ msg = f"margin detail fetch failed for all {len(trade_days)} day(s): {'; '.join(failures)}"
3116
+ return {"symbol": args.symbol, "error": msg}
3117
+ return {"symbol": args.symbol, "error": f"no margin trading data for {args.symbol} (可能不是两融标的)"}
3118
+ if getattr(args, "include_ratio", False):
3119
+ try:
3120
+ with socket_timeout(25):
3121
+ history = (
3122
+ _failover(
3123
+ [
3124
+ ("akshare", lambda: _kline_akshare(bare, "daily", days + 10)),
3125
+ ("efinance", lambda: _kline_efinance(bare, "daily", days + 10)),
3126
+ ("baostock", lambda: _kline_baostock(bare, "daily", days + 10)),
3127
+ ],
3128
+ label=f"margin_turnover:{bare}",
3129
+ )
3130
+ or []
3131
+ )
3132
+ turnovers = {str(r.get("date"))[:10]: _sanitize(_parse_float(r.get("turnover"))) for r in history}
3133
+ except Exception:
3134
+ turnovers = {}
3135
+ for row in rows:
3136
+ turnover = turnovers.get(row["date"])
3137
+ buy = _sanitize(_parse_float(row.get("margin_buy")))
3138
+ row["turnover"] = turnover
3139
+ row["margin_buy_ratio_pct"] = (
3140
+ round(buy / turnover * 100, 4) if buy is not None and turnover and turnover > 0 else None
3141
+ )
3142
+ if row["margin_buy_ratio_pct"] is None:
3143
+ row["margin_buy_ratio_note"] = "matching-date CNY turnover unavailable"
3144
+ return rows
3145
+ except Exception as e:
3146
+ return {"error": str(e)}
3147
+
3148
+
3149
+ def _northbound_row_is_shell(row: dict) -> bool:
3150
+ """停披期空壳行:date 之外每个数据字段都是 None。持股市值在停披后被回填 0.0
3151
+ (北向持仓市值约 1.9 万亿,0 是缺失哨兵而非真实值),视同 None。"""
3152
+ for k, v in row.items():
3153
+ if k == "date" or v is None:
3154
+ continue
3155
+ if k == "hold_market_cap" and not v:
3156
+ continue
3157
+ return False
3158
+ return True
3159
+
3160
+
3161
+ def cmd_northbound_flow(args):
3162
+ """Market-level northbound (北向资金) flow history via eastmoney hsgt history.
3163
+
3164
+ Data caliber: the exchanges stopped publishing daily northbound net-buy after
3165
+ 2024-08-16 — later rows are shells (date only, flow fields all None,
3166
+ 持股市值 backfilled 0.0) except quarter-end rows, which still disclose
3167
+ 持股市值. Shell rows are filtered out of the tail(days) window; when nothing
3168
+ real remains, a clean error explains the disclosure stop (increase days to
3169
+ reach pre-2024-08 history). The series comes back ascending — returned
3170
+ newest-first."""
3171
+ days = getattr(args, "days", 10)
3172
+ if days < 1:
3173
+ return {"error": f"days must be a positive integer, got {days}"}
3174
+ try:
3175
+ import akshare as ak
3176
+
3177
+ with socket_timeout(25):
3178
+ df = _akshare_retry(ak.stock_hsgt_hist_em, symbol="北向资金")
3179
+ if df is None or df.empty:
3180
+ return {"error": "northbound flow data unavailable"}
3181
+ col_map = {
3182
+ "日期": "date",
3183
+ "当日成交净买额": "net_buy",
3184
+ "买入成交额": "buy_turnover",
3185
+ "卖出成交额": "sell_turnover",
3186
+ "历史累计净买额": "accum_net_buy",
3187
+ "持股市值": "hold_market_cap",
3188
+ }
3189
+ df = df.rename(columns=col_map)
3190
+ keep = [c for c in col_map.values() if c in df.columns]
3191
+ rows = [_clean_row(r) for r in df[keep].tail(days).to_dict("records")]
3192
+ rows = [r for r in rows if not _northbound_row_is_shell(r)]
3193
+ if not rows:
3194
+ return {
3195
+ "error": (
3196
+ "北向资金日度净买额自 2024-08-16 起交易所停止披露,仅此前历史数据可用"
3197
+ f"(当前 days={days} 窗口内无有效数据,加大 days 可取历史)"
3198
+ )
3199
+ }
3200
+ rows.reverse()
3201
+ return rows
3202
+ except Exception as e:
3203
+ return {"error": str(e)}
3204
+
3205
+
2802
3206
  # --------------- CLI ---------------
2803
3207
 
2804
3208
 
@@ -2828,6 +3232,8 @@ def main():
2828
3232
 
2829
3233
  p_fin = sub.add_parser("financials")
2830
3234
  p_fin.add_argument("symbol")
3235
+ p_fin.add_argument("--periods", type=int, default=1)
3236
+ p_fin.add_argument("--annual", action="store_true", help="Select annual reports; periods=10 requests ten years")
2831
3237
 
2832
3238
  p_snap = sub.add_parser("market_snapshot")
2833
3239
  p_snap.add_argument("--market", default="A", choices=["A", "HK", "US"])
@@ -2869,6 +3275,14 @@ def main():
2869
3275
  p_hot = sub.add_parser("hot_stocks")
2870
3276
  p_hot.add_argument("--top", type=int, default=20)
2871
3277
 
3278
+ p_margin = sub.add_parser("margin_trading")
3279
+ p_margin.add_argument("symbol")
3280
+ p_margin.add_argument("--days", type=int, default=10)
3281
+ p_margin.add_argument("--include-ratio", action="store_true", help="Add same-day margin buys / CNY turnover")
3282
+
3283
+ p_nb = sub.add_parser("northbound_flow")
3284
+ p_nb.add_argument("--days", type=int, default=10)
3285
+
2872
3286
  args = parser.parse_args()
2873
3287
  if not args.command:
2874
3288
  parser.print_help()
@@ -2892,18 +3306,18 @@ def main():
2892
3306
  "limit_up_pool": cmd_limit_up_pool,
2893
3307
  "dragon_tiger": cmd_dragon_tiger,
2894
3308
  "hot_stocks": cmd_hot_stocks,
3309
+ "margin_trading": cmd_margin_trading,
3310
+ "northbound_flow": cmd_northbound_flow,
2895
3311
  }
2896
3312
  # Provider libraries (baostock etc.) print prose to stdout on failure,
2897
3313
  # which would corrupt the JSON-only contract — divert that noise to stderr.
2898
3314
  with contextlib.redirect_stdout(sys.stderr):
2899
3315
  result = dispatch[args.command](args)
2900
3316
  output(result)
3317
+ if isinstance(result, dict) and "error" in result:
3318
+ sys.exit(1)
2901
3319
 
2902
3320
 
2903
3321
  if __name__ == "__main__":
2904
- # Windows defaults stdio to a legacy code page (cp1252) that cannot encode the
2905
- # Chinese text these tools emit — force UTF-8 so stdout never crashes there.
2906
- for _s in (sys.stdout, sys.stderr):
2907
- if hasattr(_s, "reconfigure"):
2908
- _s.reconfigure(encoding="utf-8")
3322
+ utf8_stdio()
2909
3323
  main()