stock-analysis-plugin 0.2.11 → 0.2.12

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 (47) hide show
  1. package/README.md +231 -381
  2. package/docs/mcp.md +60 -0
  3. package/hermes/__init__.py +35 -0
  4. package/hermes/plugin.yaml +131 -0
  5. package/hermes/schemas.py +6 -0
  6. package/hermes/tools.py +630 -0
  7. package/mcp_host/__init__.py +1 -0
  8. package/mcp_host/__main__.py +3 -0
  9. package/mcp_host/server.py +222 -0
  10. package/package.json +7 -1
  11. package/pi/index.ts +52 -2906
  12. package/scripts/cli-json.mjs +23 -0
  13. package/scripts/exec-process.mjs +89 -0
  14. package/scripts/setup-python.mjs +37 -4
  15. package/scripts/tool-calls.mjs +489 -0
  16. package/skills/event-driven/SKILL.md +2 -2
  17. package/skills/growth-quality/SKILL.md +1 -1
  18. package/skills/stock-analysis/SKILL.md +8 -6
  19. package/skills/stock-analysis/references/stateless-analysis.md +9 -1
  20. package/tools/_cache.py +13 -0
  21. package/tools/_subproc.py +46 -0
  22. package/tools/alert_rules.py +2 -2
  23. package/tools/backtest.py +3 -3
  24. package/tools/capabilities.py +32 -9
  25. package/tools/cli_budgets.json +2 -0
  26. package/tools/diagnostics.py +3 -4
  27. package/tools/gather.py +2 -6
  28. package/tools/import_parser.py +3 -4
  29. package/tools/lixinger.py +119 -27
  30. package/tools/market_regime.py +5 -2
  31. package/tools/market_review.py +5 -6
  32. package/tools/name_resolver.py +66 -7
  33. package/tools/report_renderer.py +3 -3
  34. package/tools/requirements.txt +5 -4
  35. package/tools/risk_screening.py +3 -2
  36. package/tools/screener.py +6 -4
  37. package/tools/search_intel.py +79 -10
  38. package/tools/sec_edgar.py +266 -0
  39. package/tools/sec_holders.py +6 -0
  40. package/tools/signal_tracker.py +5 -5
  41. package/tools/stateless_analysis.py +115 -0
  42. package/tools/stock_data.py +455 -201
  43. package/tools/tiaa_disclosures.py +4 -0
  44. package/tools/tool_schemas.json +2704 -0
  45. package/tools/trading_calendar.py +65 -30
  46. package/tools/value_data.py +366 -134
  47. package/tools/watchlist.py +43 -5
@@ -3,27 +3,28 @@
3
3
 
4
4
  import argparse
5
5
  import contextlib
6
- import hashlib
7
6
  import json
8
7
  import math
9
8
  import os
10
9
  import re
11
10
  import sys
12
- import tempfile
13
11
  import time
14
12
  from datetime import date, datetime, timedelta, timezone
15
13
  from pathlib import Path
16
14
  from zoneinfo import ZoneInfo
17
15
 
18
16
  sys.path.insert(0, str(Path(__file__).resolve().parent))
19
- from _cache import DAY, WEEK, atomic_write, cached # noqa: E402
20
- from _subproc import run_tool, scrub_secrets, socket_timeout, utf8_stdio # noqa: E402
17
+ from _cache import CACHE_DIR, DAY, WEEK, atomic_write, cached, cached_values # noqa: E402
18
+ from _subproc import error_message, run_tool, scrub_secrets, socket_timeout, utf8_stdio # noqa: E402
19
+ from trading_calendar import market_now # noqa: E402
21
20
 
22
21
  # Explicitly exchange-prefixed A-share codes (sh600519 / sz000858 / bj920001).
23
22
  # Bare 6-digit codes are always stocks; the prefix is the disambiguation escape
24
23
  # hatch for index codes (sh000001 = 上证指数, not 平安银行).
25
24
  _A_PREFIXED_RE = re.compile(r"(?:sh|sz|bj)\d{6}", re.IGNORECASE)
26
25
  _A_INDEX_RE = re.compile(r"(?:sh000\d{3}|sz399\d{3})", re.IGNORECASE)
26
+ # Yahoo has no Hang Seng Tech index; Tencent serves its live quote and daily history.
27
+ _TENCENT_HK_INDEX = {"^HSTECH": "hkHSTECH"}
27
28
 
28
29
 
29
30
  def detect_market(symbol: str) -> str:
@@ -88,7 +89,6 @@ def calc_limit_price(pre_close: float, ratio: float, direction: str = "up") -> f
88
89
  _STICKY_CHAINS = {
89
90
  "kline_a",
90
91
  "quote_a",
91
- "quote_a_etf",
92
92
  "snapshot_a",
93
93
  "sector_constituents",
94
94
  "sina",
@@ -108,16 +108,19 @@ def _failover(sources: list, label: str, evidence: bool = False):
108
108
  entry costs one failed attempt, then the new winner replaces it (self-healing).
109
109
  """
110
110
  chain = label.split(":", 1)[0]
111
+ sticky = None
111
112
  if chain in _STICKY_CHAINS:
112
113
  sticky = _disk_cache_get(f"sticky-{chain}")
113
114
  if sticky:
114
- sources = sorted(sources, key=lambda s: s[0] != sticky)
115
+ # Single-symbol A quotes always try Tencent first; sticky only reorders the fallbacks behind it.
116
+ first = "tencent" if chain == "quote_a" else sticky
117
+ sources = sorted(sources, key=lambda s: (s[0] != first, s[0] != sticky))
115
118
  errors = []
116
119
  for name, fn in sources:
117
120
  try:
118
121
  result = fn()
119
122
  if result:
120
- if chain in _STICKY_CHAINS:
123
+ if chain in _STICKY_CHAINS and name != sticky:
121
124
  _disk_cache_set(f"sticky-{chain}", name)
122
125
  if evidence:
123
126
  fetched_at = datetime.now(timezone.utc).isoformat()
@@ -225,7 +228,7 @@ def _kline_baostock(symbol: str, period: str, count: int) -> list:
225
228
  import pandas as pd
226
229
 
227
230
  freq_map = {"daily": "d", "weekly": "w", "monthly": "m"}
228
- end = datetime.now()
231
+ end = _cn_now()
229
232
  start = end - timedelta(days=count * 7 if period == "weekly" else count * 31 if period == "monthly" else count * 2)
230
233
  # baostock login/logout print status lines to stdout — silence them so the
231
234
  # tool's JSON output on stdout stays clean for the calling host.
@@ -331,9 +334,9 @@ def _unix_quote_time(value) -> str | None:
331
334
  return None
332
335
 
333
336
 
334
- def _quote_time(value: str, fmt: str) -> str | None:
337
+ def _quote_time(value: str, fmt: str, tz=timezone(timedelta(hours=8))) -> str | None:
335
338
  try:
336
- return datetime.strptime(value, fmt).replace(tzinfo=timezone(timedelta(hours=8))).isoformat()
339
+ return datetime.strptime(value, fmt).replace(tzinfo=tz).isoformat()
337
340
  except ValueError:
338
341
  return None
339
342
 
@@ -342,9 +345,14 @@ def _tencent_payload_row(f: list, symbol: str) -> dict:
342
345
  """Build the quote row from one Tencent `~`-separated payload (already split).
343
346
  Shared by _quote_tencent (single) and _tencent_batch_quotes (snapshot leg)."""
344
347
  f += [""] * (50 - len(f)) # pad optional tail fields (pe/pb/market_cap/volume_ratio…) on short payloads
345
- hk = detect_market(symbol) == "HK"
348
+ market = detect_market(symbol)
349
+ foreign = market in ("HK", "US") # HK and US share currency-unit turnover and lack the A-share ratio fields
346
350
  turnover = _parse_float(f[37])
347
351
  market_cap = _parse_float(f[45])
352
+ if market == "US":
353
+ as_of = _quote_time(f[30], "%Y-%m-%d %H:%M:%S", ZoneInfo("America/New_York"))
354
+ else:
355
+ as_of = _quote_time(f[30], "%Y/%m/%d %H:%M:%S" if foreign else "%Y%m%d%H%M%S")
348
356
  return {
349
357
  "symbol": symbol,
350
358
  "name": f[1],
@@ -352,7 +360,7 @@ def _tencent_payload_row(f: list, symbol: str) -> dict:
352
360
  "change": _parse_float(f[31]),
353
361
  "change_pct": _parse_float(f[32]),
354
362
  "volume": _parse_float(f[6]), # A: 手; HK: shares, same as yfinance
355
- "turnover": turnover * (1 if hk else 1e4) if turnover is not None else None,
363
+ "turnover": turnover * (1 if foreign else 1e4) if turnover is not None else None,
356
364
  "high": _parse_float(f[33]),
357
365
  "low": _parse_float(f[34]),
358
366
  "open": _parse_float(f[5]),
@@ -360,50 +368,94 @@ def _tencent_payload_row(f: list, symbol: str) -> dict:
360
368
  "market_cap": market_cap * 1e8 if market_cap is not None else None,
361
369
  "pe": _parse_float(f[39]),
362
370
  "pe_basis": "unknown",
363
- # Tencent's HK map labels f[47] DY and f[49] WK52_Low; neither is an A-share ratio.
364
- "pb": None if hk else _parse_float(f[46]),
365
- "turnover_rate": None if hk else _parse_float(f[38]),
366
- "volume_ratio": None if hk else _parse_float(f[49]),
371
+ # Tencent's HK map labels f[47] DY and f[49] WK52_Low, and US f[46] is the English name.
372
+ "pb": None if foreign else _parse_float(f[46]),
373
+ "turnover_rate": None if foreign else _parse_float(f[38]),
374
+ "volume_ratio": None if foreign else _parse_float(f[49]),
367
375
  "amplitude": _parse_float(f[43]),
368
- "data_as_of": _quote_time(f[30], "%Y/%m/%d %H:%M:%S" if hk else "%Y%m%d%H%M%S"),
376
+ "data_as_of": as_of,
369
377
  }
370
378
 
371
379
 
372
- def _quote_tencent(symbol: str) -> dict:
373
- """Tencent A/HK quote via qt.gtimg.cn, with a GBK-encoded `~` payload.
380
+ def _tencent_hk_code(symbol: str) -> str:
381
+ if not re.fullmatch(r"[0-9]{1,5}\.HK", symbol, re.IGNORECASE):
382
+ raise ValueError(f"invalid HK symbol: {symbol}")
383
+ return f"hk{symbol[:-3].zfill(5)}"
374
384
 
375
- A-share turnover is 万元; HK turnover is already HKD. Market cap is 亿元
376
- (CNY/HKD respectively); normalize monetary fields to currency units."""
385
+
386
+ def _tencent_us_code(symbol: str) -> str:
387
+ """Tencent spells class shares with a dot (BRK.B) where Yahoo uses a dash (BRK-B)."""
388
+ if not re.fullmatch(r"[A-Za-z]{1,6}(?:[.-][A-Za-z])?", symbol):
389
+ raise ValueError(f"invalid US symbol: {symbol}")
390
+ return "us" + symbol.upper().replace("-", ".")
391
+
392
+
393
+ def _tencent_fields(code: str) -> list:
377
394
  import requests
378
395
 
379
- hk = detect_market(symbol) == "HK"
380
- if hk and not re.fullmatch(r"[0-9]{1,5}\.HK", symbol, re.IGNORECASE):
381
- raise ValueError(f"invalid HK symbol: {symbol}")
382
- # Tencent's hk feed is delayed 15 minutes; r_hk uses the same fields for live quotes.
383
- code = f"r_hk{symbol[:-3].zfill(5)}" if hk else _cn_code(symbol)
384
396
  resp = requests.get(f"https://qt.gtimg.cn/q={code}", timeout=10)
385
397
  resp.raise_for_status()
386
- f = _gbk_var_payload(resp.content).split("~")
398
+ return _gbk_var_payload(resp.content).split("~")
399
+
400
+
401
+ def _quote_tencent(symbol: str) -> dict:
402
+ """Tencent A/HK/US quote via qt.gtimg.cn, with a GBK-encoded `~` payload.
403
+
404
+ A-share turnover is 万元; HK/US turnover is already HKD/USD. Market cap is 亿
405
+ in the quote currency; normalize monetary fields to currency units."""
406
+ market = detect_market(symbol)
407
+ if market == "HK":
408
+ # Tencent's hk feed is delayed 15 minutes; r_hk uses the same fields for live quotes.
409
+ code = f"r_{_tencent_hk_code(symbol)}"
410
+ elif market == "US":
411
+ code = _tencent_us_code(symbol)
412
+ else:
413
+ code = _cn_code(symbol)
414
+ f = _tencent_fields(code)
387
415
  if len(f) < 35 or not f[1]:
388
416
  raise ValueError(f"tencent returned no quote for {symbol}")
389
417
  row = _clean_row(_tencent_payload_row(f, symbol))
390
- if hk and (row["price"] is None or row["price"] <= 0):
418
+ if market != "A" and (row["price"] is None or row["price"] <= 0):
391
419
  raise ValueError(f"tencent returned no quote for {symbol}")
392
420
  if normalize_stock_code(symbol)["is_etf"]:
393
- row["is_etf"] = True
421
+ # f[73] is total fund shares and f[78] the intraday IOPV (blank for money/bond ETFs);
422
+ # premium matches _quote_akshare_etf.
423
+ iopv = _parse_float(f[78]) if len(f) > 78 else None
424
+ price = row.get("price")
425
+ row.update(
426
+ is_etf=True,
427
+ fund_shares=_parse_float(f[73]) if len(f) > 73 else None,
428
+ iopv=iopv,
429
+ premium_discount_rate=round((price - iopv) / iopv * 100, 4) if price is not None and iopv else None,
430
+ )
394
431
  return row
395
432
 
396
433
 
397
434
  def _kline_tencent(symbol: str, period: str, count: int) -> list:
398
435
  """Tencent kline via web.ifzq.gtimg.cn. Rows are [date, open, close, high, low,
399
- volume(手)] ascending; raw series are accepted only for explicit indices."""
436
+ volume] ascending (A: 手, HK/US: shares); raw series are accepted only for explicit indices.
437
+ HK/US stocks need the hk/us endpoints: the generic one ignores qfq for them."""
400
438
  import requests
401
439
 
402
440
  p_map = {"daily": "day", "weekly": "week", "monthly": "month"}
403
441
  p = p_map.get(period, "day")
404
- code = _cn_code(symbol)
442
+ market = detect_market(symbol)
443
+ hk_index = symbol.upper() in _TENCENT_HK_INDEX
444
+ endpoint = "fqkline"
445
+ if hk_index:
446
+ code = _TENCENT_HK_INDEX[symbol.upper()]
447
+ elif market == "HK":
448
+ endpoint, code = "hkfqkline", _tencent_hk_code(symbol)
449
+ elif market == "US":
450
+ # usfqkline only adjusts the exchange-suffixed code (AAPL.OQ) that the quote API reports.
451
+ f = _tencent_fields(_tencent_us_code(symbol))
452
+ if len(f) < 3 or not f[2]:
453
+ raise ValueError(f"tencent returned no quote for {symbol}")
454
+ endpoint, code = "usfqkline", f"us{f[2]}"
455
+ else:
456
+ code = _cn_code(symbol)
405
457
  resp = requests.get(
406
- "https://web.ifzq.gtimg.cn/appstock/app/fqkline/get",
458
+ f"https://web.ifzq.gtimg.cn/appstock/app/{endpoint}/get",
407
459
  params={"param": f"{code},{p},,,{count},qfq"},
408
460
  timeout=10,
409
461
  )
@@ -411,9 +463,11 @@ def _kline_tencent(symbol: str, period: str, count: int) -> list:
411
463
  if data.get("code") != 0:
412
464
  raise ValueError(f"tencent kline failed: {data.get('msg', '')}")
413
465
  node = data.get("data", {}).get(code, {})
414
- rows = node.get(p) if _A_INDEX_RE.fullmatch(symbol) else node.get(f"qfq{p}")
466
+ raw = _A_INDEX_RE.fullmatch(symbol) or hk_index
467
+ rows = node.get(p) if raw else node.get(f"qfq{p}")
415
468
  if not rows:
416
469
  raise ValueError("tencent kline returned empty data for required adjustment")
470
+ extra = {} if market == "A" else {"adjusted": "none" if raw else "qfq"}
417
471
  return [
418
472
  _clean_row(
419
473
  {
@@ -423,6 +477,7 @@ def _kline_tencent(symbol: str, period: str, count: int) -> list:
423
477
  "low": _parse_float(r[4]),
424
478
  "close": _parse_float(r[2]),
425
479
  "volume": _parse_float(r[5]),
480
+ **extra,
426
481
  }
427
482
  )
428
483
  for r in rows[-count:]
@@ -520,6 +575,10 @@ def _sanitize(obj):
520
575
  return obj
521
576
 
522
577
 
578
+ def _cn_now() -> datetime:
579
+ return market_now("CN")
580
+
581
+
523
582
  def _clean_row(d: dict) -> dict:
524
583
  return {k: _sanitize(v) for k, v in d.items()}
525
584
 
@@ -554,11 +613,16 @@ def _kline_akshare(symbol: str, period: str, count: int) -> list:
554
613
  import akshare as ak
555
614
 
556
615
  period_map = {"daily": "daily", "weekly": "weekly", "monthly": "monthly"}
557
- end = datetime.now()
616
+ end = _cn_now()
558
617
  start = end - timedelta(days=count * 7 if period == "weekly" else count * 31 if period == "monthly" else count * 2)
559
618
 
560
- # ETFs (51/52/56/58/15/16/18xxxx) are not covered by stock_zh_a_hist
561
- hist_fn = ak.fund_etf_hist_em if normalize_stock_code(symbol)["is_etf"] else ak.stock_zh_a_hist
619
+ # ETFs (51/52/56/58/15/16/18xxxx) are not covered by stock_zh_a_hist.
620
+ # akshare 1.20.44-1.20.46 renamed several APIs; py3.10 stays below 1.20.40 with the old names.
621
+ hist_fn = (
622
+ ak.fund_etf_hist_em
623
+ if normalize_stock_code(symbol)["is_etf"]
624
+ else getattr(ak, "stock_zh_a_hist_em", None) or ak.stock_zh_a_hist
625
+ )
562
626
  df = _akshare_retry(
563
627
  hist_fn,
564
628
  symbol=symbol,
@@ -603,7 +667,7 @@ def _kline_tushare(symbol: str, period: str, count: int) -> list:
603
667
 
604
668
  if normalize_stock_code(symbol)["is_etf"]:
605
669
  raise ValueError("tushare stock adjustment does not cover ETFs")
606
- end = datetime.now()
670
+ end = _cn_now()
607
671
  start = end - timedelta(days=count * 7 if period == "weekly" else count * 31 if period == "monthly" else count * 2)
608
672
 
609
673
  ts_code = f"{symbol}.{_cn_code(symbol)[:2].upper()}"
@@ -718,69 +782,6 @@ def _quote_tushare(symbol: str) -> dict:
718
782
  )
719
783
 
720
784
 
721
- # Public TDX quote servers, tried in order — a datacenter IP often gets only
722
- # some of them refused, so a single hardcoded endpoint is a needless failure mode.
723
- _TDX_SERVERS = [
724
- ("119.147.212.81", 7709), # Tencent, Shenzhen
725
- ("180.153.18.170", 7709), # Shanghai
726
- ("202.108.253.130", 7709), # Beijing
727
- ("59.173.18.69", 7709), # Wuhan
728
- ]
729
-
730
-
731
- def _pytdx_connect(api) -> None:
732
- """Connect to the first reachable TDX server.
733
-
734
- pytdx's connect() returns True/False instead of raising (and is not a context
735
- manager), so wrap it here to keep a failed connection from surfacing as a
736
- misleading TypeError downstream.
737
- """
738
- errors = []
739
- for ip, port in _TDX_SERVERS:
740
- try:
741
- if api.connect(ip, port):
742
- return
743
- errors.append(f"{ip}:{port} refused")
744
- except Exception as e:
745
- errors.append(f"{ip}:{port} {e}")
746
- raise ConnectionError(f"pytdx failed to connect to any TDX server ({'; '.join(errors)})")
747
-
748
-
749
- def _quote_pytdx(symbol: str) -> dict:
750
- """pytdx realtime quote from TDX market servers."""
751
- from pytdx.hq import TdxHq_API
752
-
753
- market = 1 if symbol.startswith(("6", "9", "5")) else 0
754
-
755
- api = TdxHq_API()
756
- try:
757
- _pytdx_connect(api)
758
- data = api.get_security_quotes([(market, symbol)])
759
- finally:
760
- api.disconnect()
761
-
762
- if not data:
763
- raise ValueError("pytdx quote returned empty")
764
-
765
- q = data[0]
766
- prev_close = q.get("last_close")
767
- price = q.get("price")
768
- return _clean_row(
769
- {
770
- "symbol": symbol,
771
- "name": q.get("name", ""),
772
- "price": price,
773
- "change": (price - prev_close) if price and prev_close else None,
774
- "change_pct": ((price / prev_close) - 1) * 100 if price and prev_close else None,
775
- "volume": q.get("vol"),
776
- "high": q.get("high"),
777
- "low": q.get("low"),
778
- "open": q.get("open"),
779
- "prev_close": prev_close,
780
- }
781
- )
782
-
783
-
784
785
  def _kline_yfinance(symbol: str, period: str, count: int) -> list:
785
786
  import yfinance as yf
786
787
 
@@ -1028,25 +1029,38 @@ def _quote_alphavantage(symbol: str) -> dict:
1028
1029
  )
1029
1030
 
1030
1031
 
1031
- def _yf_failover(symbol: str, yfinance, finnhub, longbridge, alphavantage, label: str, evidence: bool = False):
1032
- """Shared HK/US/JP/KR/TW failover chain: yfinance → finnhub/longbridge (HK/US) → alphavantage (US only).
1032
+ def _yf_failover(symbol: str, yfinance, tencent, finnhub, longbridge, alphavantage, label: str, evidence: bool = False):
1033
+ """Shared HK/US/JP/KR/TW failover chain. HK: yfinance → tencent → finnhub → longbridge;
1034
+ US: yfinance → finnhub → longbridge → tencent → alphavantage; JP/KR/TW: yfinance only.
1033
1035
 
1036
+ Keyless Tencent backs up HK first (finnhub's free tier has no HK). For US, configured
1037
+ keyed sources go first and Tencent precedes alphavantage to spare its 25 calls/day.
1034
1038
  Each provider is a zero-arg callable; callers bind their own symbol/period/count.
1035
1039
  """
1036
1040
  market = detect_market(symbol)
1037
1041
  sources = [("yfinance", yfinance)]
1038
- if market in ("HK", "US"):
1039
- sources += [("finnhub", finnhub), ("longbridge", longbridge)]
1040
- if market == "US":
1041
- sources.append(("alphavantage", alphavantage))
1042
+ if market == "HK":
1043
+ sources += [("tencent", tencent), ("finnhub", finnhub), ("longbridge", longbridge)]
1044
+ elif market == "US":
1045
+ sources += [
1046
+ ("finnhub", finnhub),
1047
+ ("longbridge", longbridge),
1048
+ ("tencent", tencent),
1049
+ ("alphavantage", alphavantage),
1050
+ ]
1042
1051
  return _failover(sources, label=label, evidence=evidence)
1043
1052
 
1044
1053
 
1045
1054
  def kline_yf(symbol: str, period: str, count: int, evidence: bool = False) -> list:
1046
- """HK/US/JP/KR/TW kline. Failover: yfinance → finnhub/longbridge (HK/US) → alphavantage (US only)."""
1055
+ """HK/US/JP/KR/TW kline; see _yf_failover for the chain."""
1056
+ if symbol.upper() in _TENCENT_HK_INDEX:
1057
+ with socket_timeout(25):
1058
+ sources = [("tencent", lambda: _kline_tencent(symbol, period, count))]
1059
+ return _failover(sources, label=f"kline_hk_index:{symbol}", evidence=evidence)
1047
1060
  return _yf_failover(
1048
1061
  symbol,
1049
1062
  lambda: _kline_yfinance(symbol, period, count),
1063
+ lambda: _kline_tencent(symbol, period, count),
1050
1064
  lambda: _kline_finnhub(symbol, period, count),
1051
1065
  lambda: _kline_longbridge(symbol, period, count),
1052
1066
  lambda: _kline_alphavantage(symbol, period, count),
@@ -1067,34 +1081,34 @@ def cmd_kline(args):
1067
1081
  data = kline_yf(args.symbol, args.period, args.count, evidence=True)
1068
1082
  return data
1069
1083
  except Exception as e:
1070
- return {"error": str(e)}
1084
+ return {"error": error_message(e)}
1071
1085
 
1072
1086
 
1073
1087
  # --------------- quote ---------------
1074
1088
 
1075
1089
 
1076
1090
  def quote_a(symbol: str, evidence: bool = False) -> dict:
1077
- """A-share quote with failover: akshare → tushare → efinance → tencent → sina → pytdx. ETFs try fund spot first.
1091
+ """A-share quote with failover: tencent → akshare → tushare → efinance → sina; ETFs add fund spot after tencent.
1092
+
1093
+ Tencent answers one symbol per request; the eastmoney spot sources page the whole
1094
+ market (~55 requests) to return one row, so they only serve as fallbacks.
1078
1095
 
1079
1096
  Explicitly-prefixed symbols (sh000001, typically indices) go straight to
1080
- tencent/sina — the eastmoney sources take bare 6-digit codes only, and pytdx
1081
- can't place prefixed codes either. ETF quotes use their own sticky chain key
1097
+ tencent/sina — the eastmoney sources take bare 6-digit codes only. ETF quotes use their own sticky chain key
1082
1098
  (quote_a_etf) so a stock-side winner never demotes the fund-spot source."""
1083
1099
  if _A_PREFIXED_RE.fullmatch(symbol):
1084
1100
  sources = [("tencent", lambda: _quote_tencent(symbol)), ("sina", lambda: _quote_sina(symbol))]
1085
1101
  with socket_timeout(25):
1086
1102
  return _failover(sources, label=f"quote_a:{symbol}", evidence=evidence)
1087
1103
  is_etf = normalize_stock_code(symbol)["is_etf"]
1088
- sources = []
1104
+ sources = [("tencent", lambda: _quote_tencent(symbol))]
1089
1105
  if is_etf:
1090
1106
  sources.append(("akshare_etf", lambda: _quote_akshare_etf(symbol)))
1091
1107
  sources += [
1092
1108
  ("akshare", lambda: _quote_akshare(symbol)),
1093
1109
  ("tushare", lambda: _quote_tushare(symbol)),
1094
1110
  ("efinance", lambda: _quote_efinance(symbol)),
1095
- ("tencent", lambda: _quote_tencent(symbol)),
1096
1111
  ("sina", lambda: _quote_sina(symbol)),
1097
- ("pytdx", lambda: _quote_pytdx(symbol)),
1098
1112
  ]
1099
1113
  chain = "quote_a_etf" if is_etf else "quote_a"
1100
1114
  with socket_timeout(25):
@@ -1231,21 +1245,14 @@ def _quote_finnhub(symbol: str) -> dict:
1231
1245
 
1232
1246
 
1233
1247
  def quote_yf(symbol: str, evidence: bool = False) -> dict:
1234
- """HK adds Tencent after yfinance; US/JP/KR/TW keep their existing failover chains."""
1235
- if detect_market(symbol) == "HK":
1236
- return _failover(
1237
- [
1238
- ("yfinance", lambda: _quote_yfinance(symbol)),
1239
- ("tencent", lambda: _quote_tencent(symbol)),
1240
- ("finnhub", lambda: _quote_finnhub(symbol)),
1241
- ("longbridge", lambda: _quote_longbridge(symbol)),
1242
- ],
1243
- label=f"quote:{symbol}",
1244
- evidence=evidence,
1245
- )
1248
+ """HK/US/JP/KR/TW quote; see _yf_failover for the chain."""
1249
+ if symbol.upper() in _TENCENT_HK_INDEX:
1250
+ sources = [("tencent", lambda: {"symbol": symbol, **_quote_tencent_hk_index(symbol.upper())})]
1251
+ return _failover(sources, label=f"quote_hk_index:{symbol}", evidence=evidence)
1246
1252
  return _yf_failover(
1247
1253
  symbol,
1248
1254
  lambda: _quote_yfinance(symbol),
1255
+ lambda: _quote_tencent(symbol),
1249
1256
  lambda: _quote_finnhub(symbol),
1250
1257
  lambda: _quote_longbridge(symbol),
1251
1258
  lambda: _quote_alphavantage(symbol),
@@ -1392,11 +1399,15 @@ def _quote_tiaa(symbol: str) -> dict:
1392
1399
  def cmd_quote(args):
1393
1400
  if re.fullmatch(r"TIAA\d{6}", args.symbol, re.IGNORECASE):
1394
1401
  return _quote_tiaa(args.symbol.upper())
1395
- market = detect_market(args.symbol)
1402
+ # detect_market reads every ^index as US; known region indices keep their own calendar for freshness.
1403
+ market = next(
1404
+ (region.upper() for region, symbols in _REGION_INDEX_SYMBOLS.items() if args.symbol.upper() in symbols),
1405
+ None,
1406
+ ) or detect_market(args.symbol)
1396
1407
  try:
1397
1408
  result = quote_a(args.symbol, evidence=True) if market == "A" else quote_yf(args.symbol, evidence=True)
1398
1409
  except Exception as e:
1399
- result = {"error": str(e)}
1410
+ result = {"error": error_message(e)}
1400
1411
  # Exchange quotes cannot see open-end funds. Stock-only prefixes (SH 60/68, ChiNext 30, BSE) keep the bare error.
1401
1412
  if (
1402
1413
  isinstance(result, dict)
@@ -1499,7 +1510,7 @@ def cmd_fund_quote(args):
1499
1510
  latest = nav_rows[-1]
1500
1511
  nav_date = _fund_nav_date(latest["x"])
1501
1512
  accumulated_by_date = {_fund_nav_date(row[0]): row[1] for row in accumulated_rows}
1502
- today = datetime.now(ZoneInfo("Asia/Shanghai")).date().isoformat()
1513
+ today = _cn_now().date().isoformat()
1503
1514
  estimate = {
1504
1515
  "estimated_nav": None,
1505
1516
  "estimated_change_pct": None,
@@ -1538,7 +1549,7 @@ def cmd_fund_quote(args):
1538
1549
  result["warnings"] = warnings
1539
1550
  return result
1540
1551
  except Exception as e:
1541
- return {"error": str(e)}
1552
+ return {"error": error_message(e)}
1542
1553
 
1543
1554
 
1544
1555
  # --------------- capital_flow ---------------
@@ -1576,7 +1587,7 @@ def cmd_capital_flow(args):
1576
1587
  try:
1577
1588
  import akshare as ak
1578
1589
 
1579
- df = _akshare_retry(ak.stock_sector_fund_flow_rank)
1590
+ df = _akshare_retry(getattr(ak, "stock_fund_flow_sector_rank_em", None) or ak.stock_sector_fund_flow_rank)
1580
1591
  if df is None or df.empty:
1581
1592
  return {"error": "Sector fund flow data unavailable"}
1582
1593
  col_map = {
@@ -1591,7 +1602,7 @@ def cmd_capital_flow(args):
1591
1602
  keep = [c for c in col_map.values() if c in df.columns]
1592
1603
  return [_clean_row(r) for r in df[keep].head(20).to_dict("records")]
1593
1604
  except Exception as e:
1594
- return {"error": str(e)}
1605
+ return {"error": error_message(e)}
1595
1606
 
1596
1607
  if detect_market(args.symbol) != "A":
1597
1608
  return {"error": "capital_flow only available for A-shares"}
@@ -1603,7 +1614,9 @@ def cmd_capital_flow(args):
1603
1614
  # akshare wants the bare 6-digit stock plus market ∈ {sh, sz, bj}.
1604
1615
  code = _cn_code(args.symbol)
1605
1616
  market, stock = code[:2], code[2:]
1606
- df = _akshare_retry(ak.stock_individual_fund_flow, stock=stock, market=market)
1617
+ # Positional: the 1.20.45 rename also renamed `stock=` to `symbol=`.
1618
+ flow = getattr(ak, "stock_fund_flow_individual_hist_em", None) or ak.stock_individual_fund_flow
1619
+ df = _akshare_retry(flow, stock, market)
1607
1620
  col_map = {
1608
1621
  "日期": "date",
1609
1622
  "主力净流入-净额": "main_net_inflow",
@@ -1642,7 +1655,7 @@ def cmd_capital_flow(args):
1642
1655
  try:
1643
1656
  return _capital_flow_efinance(args.symbol)
1644
1657
  except Exception as e2:
1645
- return {"error": str(e2)}
1658
+ return {"error": error_message(e2)}
1646
1659
 
1647
1660
 
1648
1661
  # --------------- news ---------------
@@ -1650,7 +1663,9 @@ def cmd_capital_flow(args):
1650
1663
 
1651
1664
  def _news_search_intel_fallback(symbol: str) -> list:
1652
1665
  """Fallback: use search_intel to find news when primary sources fail."""
1653
- data = run_tool("search_intel.py", ["search", f"{symbol} 最新消息"], timeout=30)
1666
+ data = run_tool("search_intel.py", ["search", f"{symbol} 最新消息"])
1667
+ if isinstance(data, dict):
1668
+ data = data.get("results", [])
1654
1669
  if isinstance(data, list):
1655
1670
  return [{"title": item.get("title", ""), "url": item.get("url", ""), "source": "search"} for item in data[:10]]
1656
1671
  return []
@@ -1674,7 +1689,7 @@ def cmd_news(args):
1674
1689
  }
1675
1690
  df = df.rename(columns=col_map)
1676
1691
  keep = [c for c in col_map.values() if c in df.columns]
1677
- cutoff = datetime.now() - timedelta(days=args.days)
1692
+ cutoff = _cn_now() - timedelta(days=args.days)
1678
1693
  df = df[keep]
1679
1694
  if "datetime" in df.columns:
1680
1695
  import pandas as pd
@@ -1691,15 +1706,18 @@ def cmd_news(args):
1691
1706
  raise ValueError("yfinance news empty")
1692
1707
  results = []
1693
1708
  for item in news[:20]:
1709
+ content = item.get("content") or item # yfinance >= 0.2.50 nests fields under `content`
1694
1710
  results.append(
1695
1711
  {
1696
- "title": item.get("title", ""),
1697
- "publisher": item.get("publisher", ""),
1698
- "url": item.get("link", ""),
1699
- "published": item.get("providerPublishTime", ""),
1700
- "type": item.get("type", ""),
1712
+ "title": content.get("title") or item.get("title", ""),
1713
+ "publisher": (content.get("provider") or {}).get("displayName") or item.get("publisher", ""),
1714
+ "url": (content.get("canonicalUrl") or {}).get("url") or item.get("link", ""),
1715
+ "published": content.get("pubDate") or item.get("providerPublishTime", ""),
1716
+ "type": content.get("contentType") or item.get("type", ""),
1701
1717
  }
1702
1718
  )
1719
+ if not any(r["title"] for r in results):
1720
+ raise ValueError("yfinance news has no titles")
1703
1721
  return results
1704
1722
  except Exception:
1705
1723
  return _news_search_intel_fallback(args.symbol)
@@ -1880,19 +1898,175 @@ def financials_yf(symbol: str, periods: int = 1, annual: bool = False) -> dict:
1880
1898
  return result
1881
1899
 
1882
1900
 
1901
+ def _yf_dcf_inputs(symbol: str, periods: int) -> dict:
1902
+ import yfinance as yf
1903
+
1904
+ if detect_market(symbol) == "A":
1905
+ code = _cn_code(symbol)
1906
+ if code.startswith("bj"):
1907
+ raise ValueError("Yahoo has no Beijing Stock Exchange statements")
1908
+ ticker = yf.Ticker(f"{code[2:]}.{'SS' if code.startswith('sh') else 'SZ'}")
1909
+ else:
1910
+ ticker = yf.Ticker(_yf_hk_symbol(symbol))
1911
+ tables = [ticker.income_stmt, ticker.cashflow, ticker.balance_sheet]
1912
+ warnings = ["Yahoo standardized annual statements; verify against filings before valuation."]
1913
+ try:
1914
+ currency, reason = _yf_info(symbol, ticker).get("financialCurrency"), "not reported"
1915
+ except Exception as e:
1916
+ currency, reason = None, error_message(e)
1917
+ if not currency:
1918
+ warnings.append(f"Yahoo financial currency unavailable ({reason}); rows cannot fill other sources")
1919
+ fields = {
1920
+ "revenue": (0, "Total Revenue"),
1921
+ "operating_income": (0, "Operating Income"),
1922
+ "pretax_income": (0, "Pretax Income"),
1923
+ "income_tax": (0, "Tax Provision"),
1924
+ "diluted_shares": (0, "Diluted Average Shares"),
1925
+ "operating_cash_flow": (1, "Operating Cash Flow"),
1926
+ "capital_expenditure": (1, "Capital Expenditure"),
1927
+ "depreciation_amortization": (1, "Depreciation And Amortization"),
1928
+ "cash": (2, "Cash And Cash Equivalents"),
1929
+ "lease_liabilities": (2, "Capital Lease Obligations"),
1930
+ "minority_interest": (2, "Minority Interest"),
1931
+ "shares_outstanding": (2, "Ordinary Shares Number"),
1932
+ }
1933
+ ends = sorted(
1934
+ {str(col)[:10] for table in tables if table is not None and not table.empty for col in table.columns},
1935
+ reverse=True,
1936
+ )[:periods]
1937
+ rows = []
1938
+ for end in ends:
1939
+ entry = {"period_end": end, "currency": currency}
1940
+
1941
+ def cell(index, label, end=end):
1942
+ table = tables[index]
1943
+ column = next((col for col in getattr(table, "columns", []) if str(col)[:10] == end), None)
1944
+ return (
1945
+ _sanitize(_parse_float(table.loc[label, column]))
1946
+ if column is not None and label in table.index
1947
+ else None
1948
+ )
1949
+
1950
+ for key, (index, label) in fields.items():
1951
+ value = cell(index, label)
1952
+ entry[key] = abs(value) if key == "capital_expenditure" and value is not None else value
1953
+ # Yahoo "Total Debt" adds lease liabilities; SEC/Lixinger total_debt excludes them.
1954
+ debt = [value for value in (cell(2, "Current Debt"), cell(2, "Long Term Debt")) if value is not None]
1955
+ entry["total_debt"] = sum(debt) if debt else None
1956
+ rows.append(entry)
1957
+ if not rows:
1958
+ raise ValueError("Yahoo annual statements unavailable")
1959
+ return {
1960
+ "source": "yfinance",
1961
+ "periods": rows,
1962
+ "warnings": warnings + ["lease_liabilities is Yahoo Capital Lease Obligations (may omit operating leases)."],
1963
+ }
1964
+
1965
+
1966
+ DCF_FIELDS = (
1967
+ "revenue",
1968
+ "operating_income",
1969
+ "pretax_income",
1970
+ "income_tax",
1971
+ "operating_cash_flow",
1972
+ "capital_expenditure",
1973
+ "depreciation_amortization",
1974
+ "cash",
1975
+ "total_debt",
1976
+ "lease_liabilities",
1977
+ "minority_interest",
1978
+ "diluted_shares",
1979
+ "shares_outstanding",
1980
+ )
1981
+
1982
+
1983
+ def _fill_dcf_rows(result: dict, fallback: dict | None) -> dict:
1984
+ """Fill null primary fields from Yahoo for the same fiscal period and currency, recording each field's source."""
1985
+ for row in result["periods"]:
1986
+ match = None
1987
+ if fallback:
1988
+ end = datetime.fromisoformat(row["period_end"]).date()
1989
+ match = next(
1990
+ (
1991
+ other
1992
+ for other in fallback["periods"]
1993
+ if abs((datetime.fromisoformat(other["period_end"]).date() - end).days) <= 10
1994
+ and other.get("currency")
1995
+ and other.get("currency") == row.get("currency")
1996
+ ),
1997
+ None,
1998
+ )
1999
+ sources = {}
2000
+ for key in DCF_FIELDS:
2001
+ # Yahoo leases are finance-lease-only "Capital Lease Obligations"; never mix them into another source.
2002
+ if row.get(key) is None and match and match.get(key) is not None and key != "lease_liabilities":
2003
+ row[key], sources[key] = match[key], fallback["source"]
2004
+ elif row.get(key) is not None:
2005
+ sources[key] = result["source"]
2006
+ else:
2007
+ row[key] = None
2008
+ pretax, tax = row["pretax_income"], row["income_tax"]
2009
+ row["effective_tax_rate"] = tax / pretax if tax is not None and pretax and pretax > 0 else None
2010
+ row["field_sources"] = sources
2011
+ row["missing_fields"] = [key for key in DCF_FIELDS if row[key] is None]
2012
+ result["units"] = {"amounts": "reported currency units", "shares": "shares", "effective_tax_rate": "ratio"}
2013
+ return result
2014
+
2015
+
2016
+ def _dcf_inputs(symbol: str, periods: int) -> dict:
2017
+ market = detect_market(symbol)
2018
+ if market not in ("A", "HK", "US"):
2019
+ return {"error": "DCF inputs support A, HK and US stocks only"}
2020
+ warnings, primary = [], None
2021
+ if market == "US" or os.environ.get("LIXINGER_TOKEN"):
2022
+ label = "SEC companyfacts" if market == "US" else f"Lixinger {market}"
2023
+ try:
2024
+ if market == "US":
2025
+ import sec_edgar
2026
+
2027
+ primary = sec_edgar.dcf_inputs(symbol, periods)
2028
+ else:
2029
+ import lixinger
2030
+
2031
+ code = _cn_code(symbol)[2:] if market == "A" else symbol.split(".")[0].zfill(5)
2032
+ primary = lixinger.dcf_inputs("cn" if market == "A" else "hk", code, periods)
2033
+ except Exception as e:
2034
+ warnings.append(f"{label} unavailable: {error_message(e)}; Yahoo fallback used")
2035
+ try:
2036
+ yahoo = _yf_dcf_inputs(symbol, periods)
2037
+ except Exception as e:
2038
+ if primary is None:
2039
+ return {"error": f"DCF inputs unavailable: {error_message(e)}", "warnings": warnings}
2040
+ yahoo = None
2041
+ warnings.append(f"Yahoo fill unavailable: {error_message(e)}")
2042
+ result = _fill_dcf_rows(primary or yahoo, yahoo if primary else None)
2043
+ result["warnings"] = warnings + result["warnings"]
2044
+ return result
2045
+
2046
+
1883
2047
  def cmd_financials(args):
1884
2048
  periods = getattr(args, "periods", 1)
1885
2049
  if not 1 <= periods <= 40:
1886
2050
  return {"error": f"periods must be between 1 and 40, got {periods}"}
1887
2051
  annual = getattr(args, "annual", False)
1888
2052
  market = detect_market(args.symbol)
2053
+ result = _financials_without_dcf(args, periods, annual, market)
2054
+ if getattr(args, "include_dcf_inputs", False) and "error" not in result:
2055
+ result["dcf_inputs"] = _dcf_inputs(args.symbol, periods)
2056
+ return result
2057
+
2058
+
2059
+ def _financials_without_dcf(args, periods, annual, market):
1889
2060
  try:
1890
2061
  if market == "HK":
1891
2062
  if os.environ.get("LIXINGER_TOKEN"):
1892
2063
  try:
1893
2064
  from lixinger import financials_hk
1894
2065
 
1895
- result = financials_hk(args.symbol, periods, annual)
2066
+ result = {
2067
+ "symbol": args.symbol,
2068
+ **financials_hk(args.symbol.split(".")[0].zfill(5), periods, annual),
2069
+ }
1896
2070
  snapshot = financials_yf(args.symbol, 1, False)
1897
2071
  result.update(
1898
2072
  {
@@ -1922,7 +2096,7 @@ def cmd_financials(args):
1922
2096
  financials_a(args.symbol, periods, annual) if market == "A" else financials_yf(args.symbol, periods, annual)
1923
2097
  )
1924
2098
  except Exception as e:
1925
- return {"error": str(e)}
2099
+ return {"error": error_message(e)}
1926
2100
 
1927
2101
 
1928
2102
  # --------------- market_snapshot ---------------
@@ -1943,7 +2117,7 @@ def snapshot_a() -> list:
1943
2117
  label="snapshot_a",
1944
2118
  )
1945
2119
  except Exception as e:
1946
- return [{"error": f"A-share snapshot unavailable from all sources: {e}"}]
2120
+ return [{"error": f"A-share snapshot unavailable from all sources: {error_message(e)}"}]
1947
2121
 
1948
2122
 
1949
2123
  def _snapshot_efinance() -> list:
@@ -1977,7 +2151,7 @@ def _snapshot_sina() -> list:
1977
2151
  import akshare as ak
1978
2152
  import pandas as pd
1979
2153
 
1980
- df = _akshare_retry(ak.stock_zh_a_spot)
2154
+ df = _akshare_retry(getattr(ak, "stock_zh_a_spot_sina", None) or ak.stock_zh_a_spot)
1981
2155
  if df is None or df.empty:
1982
2156
  raise ValueError("sina snapshot empty")
1983
2157
  df["代码"] = df["代码"].astype(str).str.replace(r"^(?:sh|sz|bj)", "", regex=True)
@@ -2116,6 +2290,13 @@ def snapshot_hk() -> list:
2116
2290
  return [{"error": f"HK snapshot unavailable: {type(e).__name__}: {scrub_secrets(str(e))}"[:200]}]
2117
2291
 
2118
2292
 
2293
+ def normalize_us_symbol(value) -> str:
2294
+ symbol = str(value).strip().upper()
2295
+ symbol = re.sub(r"^(?:105|106|107)[.]", "", symbol)
2296
+ symbol = re.sub(r"[.](?:OQ|N|A)$", "", symbol)
2297
+ return re.sub(r"[._]", "-", symbol) # Eastmoney writes class shares as BRK_B; yfinance wants BRK-B
2298
+
2299
+
2119
2300
  def snapshot_us() -> list:
2120
2301
  try:
2121
2302
  import akshare as ak
@@ -2134,8 +2315,7 @@ def snapshot_us() -> list:
2134
2315
  }
2135
2316
  df = df.rename(columns=col_map)
2136
2317
  if "symbol" in df.columns:
2137
- symbols = df["symbol"].astype(str).str.upper().str.replace(r"\.(?:OQ|N|A)$", "", regex=True)
2138
- df["symbol"] = symbols.str.replace(".", "-", regex=False)
2318
+ df["symbol"] = df["symbol"].map(normalize_us_symbol)
2139
2319
  df["pe_basis"] = "unknown"
2140
2320
  keep = [c for c in col_map.values() if c in df.columns] + ["pe_basis"]
2141
2321
  return [_clean_row(r) for r in df[keep].to_dict("records")]
@@ -2154,7 +2334,7 @@ def cmd_market_snapshot(args):
2154
2334
  return snapshot_us()
2155
2335
  return {"error": f"Unknown market: {m}"}
2156
2336
  except Exception as e:
2157
- return {"error": str(e)}
2337
+ return {"error": error_message(e)}
2158
2338
 
2159
2339
 
2160
2340
  # --------------- market_indices ---------------
@@ -2169,6 +2349,31 @@ _REGION_INDEX_SYMBOLS = {
2169
2349
  }
2170
2350
 
2171
2351
 
2352
+ def _quote_tencent_hk_index(symbol: str) -> dict:
2353
+ """Tencent r_hk index quote, using the same `~` field positions as _tencent_payload_row.
2354
+ Volume is omitted: the index feed's volume field has no confirmed unit."""
2355
+ import requests
2356
+
2357
+ resp = requests.get(f"https://qt.gtimg.cn/q=r_{_TENCENT_HK_INDEX[symbol]}", timeout=10)
2358
+ resp.raise_for_status()
2359
+ f = _gbk_var_payload(resp.content).split("~")
2360
+ price = _parse_float(f[3]) if len(f) > 34 else None
2361
+ if price is None or price <= 0:
2362
+ raise ValueError(f"tencent returned no quote for {symbol}")
2363
+ return {
2364
+ "price": price,
2365
+ "change": _parse_float(f[31]),
2366
+ "change_pct": _parse_float(f[32]),
2367
+ "high": _parse_float(f[33]),
2368
+ "low": _parse_float(f[34]),
2369
+ "open": _parse_float(f[5]),
2370
+ "prev_close": _parse_float(f[4]),
2371
+ "source": "tencent",
2372
+ "data_as_of": _quote_time(f[30], "%Y/%m/%d %H:%M:%S"),
2373
+ "fetched_at": datetime.now(timezone.utc).isoformat(),
2374
+ }
2375
+
2376
+
2172
2377
  def cmd_market_indices(args):
2173
2378
  region = args.region.lower()
2174
2379
  try:
@@ -2185,10 +2390,10 @@ def cmd_market_indices(args):
2185
2390
  ]
2186
2391
  results = []
2187
2392
  try:
2188
- df = _akshare_retry(ak.stock_zh_index_spot_em)
2393
+ df = _akshare_retry(getattr(ak, "index_zh_spot_em", None) or ak.stock_zh_index_spot_em)
2189
2394
  except Exception:
2190
2395
  # eastmoney refuses datacenter/proxy IPs (RemoteDisconnected) — sina is the fallback
2191
- df = _akshare_retry(ak.stock_zh_index_spot_sina)
2396
+ df = _akshare_retry(getattr(ak, "index_zh_spot_sina", None) or ak.stock_zh_index_spot_sina)
2192
2397
  for code, name in indices:
2193
2398
  clean_code = code[2:] if code[:2] in ("sh", "sz") else code
2194
2399
  row = df[df["代码"] == clean_code]
@@ -2226,6 +2431,8 @@ def cmd_market_indices(args):
2226
2431
  def fetch_index(item):
2227
2432
  sym, name = item
2228
2433
  try:
2434
+ if sym in _TENCENT_HK_INDEX:
2435
+ return _clean_row({"code": sym, "name": name, **_quote_tencent_hk_index(sym)})
2229
2436
  info = yf.Ticker(sym).info
2230
2437
  return _clean_row(
2231
2438
  {
@@ -2252,7 +2459,7 @@ def cmd_market_indices(args):
2252
2459
  return list(pool.map(fetch_index, symbols.items()))
2253
2460
  return {"error": f"Unknown region: {region}"}
2254
2461
  except Exception as e:
2255
- return {"error": str(e)}
2462
+ return {"error": error_message(e)}
2256
2463
 
2257
2464
 
2258
2465
  # --------------- sector_rankings ---------------
@@ -2383,24 +2590,72 @@ def _sector_rankings_sina(indicator: str) -> list:
2383
2590
  return [_clean_row(r) for r in df[keep].to_dict("records")]
2384
2591
 
2385
2592
 
2593
+ US_SECTOR_ETFS = {
2594
+ "XLK": "Technology",
2595
+ "XLF": "Financials",
2596
+ "XLV": "Health Care",
2597
+ "XLY": "Consumer Discretionary",
2598
+ "XLP": "Consumer Staples",
2599
+ "XLE": "Energy",
2600
+ "XLI": "Industrials",
2601
+ "XLB": "Materials",
2602
+ "XLU": "Utilities",
2603
+ "XLRE": "Real Estate",
2604
+ "XLC": "Communication Services",
2605
+ }
2606
+
2607
+
2608
+ def _sector_rankings_us() -> list:
2609
+ """S&P 500 sector proxies from the SPDR Select Sector ETFs' last two daily closes."""
2610
+ import yfinance as yf
2611
+
2612
+ closes = yf.download(list(US_SECTOR_ETFS), period="10d", auto_adjust=False, progress=False)["Close"]
2613
+ rows = []
2614
+ for symbol, name in US_SECTOR_ETFS.items():
2615
+ series = closes[symbol].dropna() if symbol in closes else []
2616
+ if len(series) < 2:
2617
+ continue
2618
+ rows.append(
2619
+ {
2620
+ "name": name,
2621
+ "etf": symbol,
2622
+ "close": round(float(series.iloc[-1]), 4),
2623
+ "change_pct": round(float(series.iloc[-1] / series.iloc[-2] - 1) * 100, 4),
2624
+ "as_of": str(series.index[-1])[:10],
2625
+ }
2626
+ )
2627
+ if not rows:
2628
+ raise ValueError("US sector ETF quotes unavailable")
2629
+ return rows
2630
+
2631
+
2386
2632
  def cmd_sector_rankings(args):
2387
2633
  board_type = getattr(args, "board_type", "industry")
2388
2634
  direction = getattr(args, "direction", "top")
2389
- sources = [_sourced("eastmoney", lambda: _sector_rankings_em(board_type))]
2390
- if board_type == "industry":
2391
- # efinance has no concept boards — it stays an industry-only leg
2392
- sources.append(_sourced("ths", _sector_rankings_ths))
2393
- sources.append(_sourced("efinance", _sector_rankings_efinance))
2635
+ market = getattr(args, "market", "A")
2636
+ if market == "US" and board_type != "industry":
2637
+ return {"error": "US sector rankings support board_type=industry only"}
2638
+ if market == "US":
2639
+ sources = [_sourced("yfinance", _sector_rankings_us)]
2394
2640
  else:
2395
- sources.append(_sourced("sina", lambda: _sector_rankings_sina("概念")))
2641
+ sources = [_sourced("eastmoney", lambda: _sector_rankings_em(board_type))]
2642
+ if board_type == "industry":
2643
+ # efinance has no concept boards — it stays an industry-only leg
2644
+ sources += [_sourced("ths", _sector_rankings_ths), _sourced("efinance", _sector_rankings_efinance)]
2645
+ else:
2646
+ sources.append(_sourced("sina", lambda: _sector_rankings_sina("概念")))
2396
2647
  try:
2397
- rows = _failover(sources, label=f"sector_rankings:{board_type}")
2648
+ rows = _failover(
2649
+ sources, label="sector_rankings_us:industry" if market == "US" else f"sector_rankings:{board_type}"
2650
+ )
2398
2651
  if not rows:
2399
2652
  raise ValueError(f"no {board_type} board rankings data")
2400
2653
  except Exception as e:
2401
- return {"error": str(e)}
2654
+ return {"error": error_message(e)}
2402
2655
  for r in rows:
2403
2656
  r["board_type"] = board_type
2657
+ if market == "US":
2658
+ r.update(market="US", proxy="SPDR Select Sector ETF")
2404
2659
 
2405
2660
  def _pct(row, default):
2406
2661
  v = row.get("change_pct")
@@ -2418,10 +2673,9 @@ def cmd_sector_rankings(args):
2418
2673
 
2419
2674
  # --------------- sector constituents / stock sectors (issue #18) ---------------
2420
2675
 
2421
- # Disk cache lives in tempdir — cross-platform (Windows has no ~/.cache). Stores
2422
- # sector constituents (24h TTL; membership changes slowly) and sticky failover
2423
- # winners (keys prefixed `sticky-`, see _failover).
2424
- _DATA_CACHE_DIR = Path(tempfile.gettempdir()) / "pi-stock-analysis"
2676
+ # Small routing state (24h TTL) beside the user-private slow-data cache: sticky failover
2677
+ # winners (`sticky-`, see _failover) and per-leg outage markers (`resolve-down-`).
2678
+ _DATA_CACHE_DIR = CACHE_DIR / "state"
2425
2679
  _DATA_CACHE_TTL = 24 * 3600
2426
2680
 
2427
2681
 
@@ -2564,16 +2818,10 @@ def _sector_constituents(args):
2564
2818
  sector = args.sector.strip()
2565
2819
  if not sector:
2566
2820
  return {"error": "sector name required"}
2567
- board_type = args.board_type
2568
- # Sector names are user input — hash them instead of sanitizing, so names that
2569
- # differ only in whitespace/punctuation (创新药 vs 创新 药) can't collide.
2570
- cache_key = hashlib.sha256(f"{sector}|{board_type}".encode()).hexdigest()[:16]
2571
2821
  try:
2572
- result = sector_constituents_a(sector, board_type)
2822
+ return sector_constituents_a(sector, args.board_type)
2573
2823
  except Exception as e:
2574
- return {"error": str(e)}
2575
- _disk_cache_set(cache_key, result)
2576
- return result
2824
+ return {"error": error_message(e)}
2577
2825
 
2578
2826
 
2579
2827
  def _board_entry(name, source: str, board_type: str) -> dict:
@@ -2671,17 +2919,11 @@ def _stock_boards_cninfo(symbol: str) -> list:
2671
2919
  def _stock_boards_from_cache(symbol: str) -> list:
2672
2920
  """Reverse lookup against the get_sector_constituents disk cache — the honest
2673
2921
  fallback when eastmoney blocks the caller's IP and xueqiu has no token (the two
2674
- live A-share sources are both eastmoney-flavored). Reads week-lived user-directory entries plus legacy temporary payloads,
2675
- and returns one entry per cached sector
2676
- containing the symbol. Cold cache → []; malformed cache files are skipped
2677
- (_disk_cache_get returns None on expiry, bad JSON, or read errors)."""
2678
- from itertools import chain
2679
-
2680
- from _cache import cached_values
2681
-
2922
+ live A-share sources are both eastmoney-flavored). Reads the week-lived get_sector_constituents
2923
+ entries and returns one entry per cached sector containing the symbol. Cold cache → [];
2924
+ expired or malformed entries are skipped."""
2682
2925
  boards = []
2683
- legacy = (_disk_cache_get(path.stem) for path in _DATA_CACHE_DIR.glob("*.json"))
2684
- for data in chain(legacy, cached_values("sector-constituents", WEEK)):
2926
+ for data in cached_values("sector-constituents", WEEK):
2685
2927
  if not isinstance(data, dict):
2686
2928
  continue
2687
2929
  sector = data.get("sector")
@@ -2730,7 +2972,7 @@ _RESOLVE_DOWN_TTL = 3600
2730
2972
  def _resolve_leg_down(name: str) -> bool:
2731
2973
  """True while leg `name`'s failure marker is fresh. The marker stores a plain
2732
2974
  timestamp — the effective TTL above is shorter than the 24h file lifetime that
2733
- _disk_cache_get enforces on the shared cache dir."""
2975
+ _disk_cache_get enforces on the private state cache dir."""
2734
2976
  ts = _disk_cache_get(f"resolve-down-{name}")
2735
2977
  return isinstance(ts, (int, float)) and time.time() - ts < _RESOLVE_DOWN_TTL
2736
2978
 
@@ -2870,12 +3112,13 @@ def cmd_stock_info(args):
2870
3112
  if is_etf:
2871
3113
  try:
2872
3114
  # ETF 最新净值(天天基金-场内基金历史净值明细)。窄日期窗口 → 单页返回
2873
- end = datetime.now()
3115
+ # akshare 1.20.41 改名为 fund_exchange_nav_hist_em;py3.10 只能装到 <1.20.40,仍是旧名
3116
+ end = _cn_now()
2874
3117
  start = end - timedelta(days=30)
2875
3118
  nav_df = _cached_frame(
2876
3119
  f"etf-basic-nav:{args.symbol}",
2877
3120
  lambda: _akshare_retry(
2878
- ak.fund_etf_fund_info_em,
3121
+ getattr(ak, "fund_exchange_nav_hist_em", None) or ak.fund_etf_fund_info_em,
2879
3122
  fund=args.symbol,
2880
3123
  start_date=start.strftime("%Y%m%d"),
2881
3124
  end_date=end.strftime("%Y%m%d"),
@@ -2914,7 +3157,7 @@ def cmd_stock_info(args):
2914
3157
  }
2915
3158
  )
2916
3159
  except Exception as e:
2917
- return {"error": str(e)}
3160
+ return {"error": error_message(e)}
2918
3161
 
2919
3162
 
2920
3163
  # --------------- chip_distribution ---------------
@@ -2957,7 +3200,7 @@ def cmd_chip_distribution(args):
2957
3200
  result["concentration_70"] = round((h70 - l70) / ((h70 + l70) / 2) * 100, 2)
2958
3201
  return result
2959
3202
  except Exception as e:
2960
- return {"error": str(e)}
3203
+ return {"error": error_message(e)}
2961
3204
 
2962
3205
 
2963
3206
  # --------------- market_stats ---------------
@@ -3033,17 +3276,25 @@ def compute_market_stats(data: list) -> dict:
3033
3276
 
3034
3277
 
3035
3278
  def cmd_market_stats(args):
3279
+ market = getattr(args, "market", "A")
3036
3280
  try:
3037
- data = snapshot_a()
3281
+ data = {"A": snapshot_a, "HK": snapshot_hk, "US": snapshot_us}[market]()
3038
3282
  if isinstance(data, dict) and "error" in data:
3039
3283
  return data
3040
3284
  if isinstance(data, list) and len(data) == 1 and isinstance(data[0], dict) and "error" in data[0]:
3041
3285
  return data[0]
3042
3286
  if not data:
3043
3287
  return {"error": "No market data"}
3044
- return compute_market_stats(data)
3288
+ stats = compute_market_stats(data)
3289
+ if market != "A":
3290
+ # HK/US have no daily price limits; breadth covers the provider's listed-security universe.
3291
+ stats.update(
3292
+ dict.fromkeys(("limit_up_count", "limit_down_count", "limit_up_samples", "limit_down_samples"))
3293
+ )
3294
+ stats.update(market=market, source="eastmoney_spot", turnover_currency="HKD" if market == "HK" else "USD")
3295
+ return stats
3045
3296
  except Exception as e:
3046
- return {"error": str(e)}
3297
+ return {"error": error_message(e)}
3047
3298
 
3048
3299
 
3049
3300
  # --------------- fundamental_context ---------------
@@ -3110,7 +3361,7 @@ def cmd_fundamental_context(args):
3110
3361
 
3111
3362
  return result
3112
3363
  except Exception as e:
3113
- return {"error": str(e)}
3364
+ return {"error": error_message(e)}
3114
3365
 
3115
3366
 
3116
3367
  # --------------- short-term sentiment: limit_up_pool / dragon_tiger / hot_stocks (A-share only) ---------------
@@ -3128,7 +3379,7 @@ def _resolve_cn_data_date(raw: str) -> tuple[datetime, datetime]:
3128
3379
  from trading_calendar import cn_trade_dates # flat sibling import
3129
3380
 
3130
3381
  req = datetime.strptime(raw, "%Y%m%d")
3131
- d = min(req, datetime.now().replace(hour=0, minute=0, second=0, microsecond=0))
3382
+ d = min(req, _cn_now().replace(hour=0, minute=0, second=0, microsecond=0))
3132
3383
  trade_dates = cn_trade_dates(d.year)
3133
3384
  if d.month == 1: # the walk-back can cross into December of the previous year
3134
3385
  trade_dates |= cn_trade_dates(d.year - 1)
@@ -3150,7 +3401,7 @@ def cmd_limit_up_pool(args):
3150
3401
  request resolves to itself and no stale label is emitted (the zt-pool payload
3151
3402
  carries no date column to cross-check against)."""
3152
3403
  try:
3153
- req, data_day = _resolve_cn_data_date((args.date or datetime.now().strftime("%Y%m%d")).replace("-", ""))
3404
+ req, data_day = _resolve_cn_data_date((args.date or _cn_now().strftime("%Y%m%d")).replace("-", ""))
3154
3405
  except ValueError:
3155
3406
  return {"error": f"limit_up_pool: invalid --date {args.date!r} (want YYYYMMDD)"}
3156
3407
  date = data_day.strftime("%Y%m%d")
@@ -3202,7 +3453,7 @@ def cmd_limit_up_pool(args):
3202
3453
  result["pool"] = pool
3203
3454
  return result
3204
3455
  except Exception as e:
3205
- return {"error": f"limit_up_pool date={requested}: {e}"}
3456
+ return {"error": f"limit_up_pool date={requested}: {error_message(e)}"}
3206
3457
 
3207
3458
 
3208
3459
  def _dragon_tiger_em(raw: str) -> list:
@@ -3267,7 +3518,7 @@ def cmd_dragon_tiger(args):
3267
3518
  date is served the last trading day's list, labeled with requested_date and
3268
3519
  stale=True."""
3269
3520
  try:
3270
- req, data_day = _resolve_cn_data_date((args.date or datetime.now().strftime("%Y-%m-%d")).replace("-", ""))
3521
+ req, data_day = _resolve_cn_data_date((args.date or _cn_now().strftime("%Y-%m-%d")).replace("-", ""))
3271
3522
  except ValueError:
3272
3523
  return {"error": f"dragon_tiger: invalid --date {args.date!r} (want YYYY-MM-DD)"}
3273
3524
  raw = data_day.strftime("%Y%m%d")
@@ -3280,7 +3531,7 @@ def cmd_dragon_tiger(args):
3280
3531
  try:
3281
3532
  rows = _failover(sources, label=f"dragon_tiger:{raw}")
3282
3533
  except Exception as e:
3283
- return {"error": str(e)}
3534
+ return {"error": error_message(e)}
3284
3535
  stale = req != data_day
3285
3536
  if not rows:
3286
3537
  result = {"date": date, "count": 0, "items": []}
@@ -3351,7 +3602,7 @@ def _hot_stocks_baidu() -> list:
3351
3602
  df = _akshare_retry(
3352
3603
  ak.stock_hot_search_baidu,
3353
3604
  symbol="A股",
3354
- date=datetime.now().strftime("%Y%m%d"),
3605
+ date=_cn_now().strftime("%Y%m%d"),
3355
3606
  time="今日",
3356
3607
  )
3357
3608
  if df is None or df.empty:
@@ -3376,7 +3627,7 @@ def cmd_hot_stocks(args):
3376
3627
  try:
3377
3628
  rows = _failover(sources, label="hot_stocks")
3378
3629
  except Exception as e:
3379
- return {"error": str(e)}
3630
+ return {"error": error_message(e)}
3380
3631
  if not rows:
3381
3632
  return {"count": 0, "items": [], "note": "no hot-rank data available"}
3382
3633
  items = [{k: v for k, v in r.items() if k != "source"} for r in rows[: args.top]]
@@ -3477,7 +3728,7 @@ def cmd_margin_trading(args):
3477
3728
  return table
3478
3729
 
3479
3730
  try:
3480
- today = datetime.now(ZoneInfo("Asia/Shanghai")).date().isoformat()
3731
+ today = _cn_now().date().isoformat()
3481
3732
  table = (
3482
3733
  cached(f"margin-table:{exchange}:{date_iso}", DAY, fetch_table)
3483
3734
  if date_iso < today
@@ -3530,7 +3781,7 @@ def cmd_margin_trading(args):
3530
3781
  row["margin_buy_ratio_note"] = "matching-date CNY turnover unavailable"
3531
3782
  return rows
3532
3783
  except Exception as e:
3533
- return {"error": str(e)}
3784
+ return {"error": error_message(e)}
3534
3785
 
3535
3786
 
3536
3787
  def _northbound_row_is_shell(row: dict) -> bool:
@@ -3587,7 +3838,7 @@ def cmd_northbound_flow(args):
3587
3838
  rows.reverse()
3588
3839
  return rows
3589
3840
  except Exception as e:
3590
- return {"error": str(e)}
3841
+ return {"error": error_message(e)}
3591
3842
 
3592
3843
 
3593
3844
  # --------------- CLI ---------------
@@ -3624,6 +3875,7 @@ def main():
3624
3875
  p_fin.add_argument("symbol")
3625
3876
  p_fin.add_argument("--periods", type=int, default=1)
3626
3877
  p_fin.add_argument("--annual", action="store_true", help="Select annual reports; periods=10 requests ten years")
3878
+ p_fin.add_argument("--include-dcf-inputs", action="store_true", help="Add annual A/HK/US DCF input fields")
3627
3879
 
3628
3880
  p_snap = sub.add_parser("market_snapshot")
3629
3881
  p_snap.add_argument("--market", default="A", choices=["A", "HK", "US"])
@@ -3635,6 +3887,7 @@ def main():
3635
3887
  p_sec.add_argument("--top", type=int, default=10)
3636
3888
  p_sec.add_argument("--direction", default="top", choices=["top", "bottom", "both"])
3637
3889
  p_sec.add_argument("--board-type", default="industry", choices=["industry", "concept"])
3890
+ p_sec.add_argument("--market", default="A", choices=["A", "US"])
3638
3891
 
3639
3892
  p_cons = sub.add_parser("sector_constituents")
3640
3893
  p_cons.add_argument("sector")
@@ -3649,7 +3902,8 @@ def main():
3649
3902
  p_chip = sub.add_parser("chip_distribution")
3650
3903
  p_chip.add_argument("symbol")
3651
3904
 
3652
- sub.add_parser("market_stats")
3905
+ p_stats = sub.add_parser("market_stats")
3906
+ p_stats.add_argument("--market", default="A", choices=["A", "HK", "US"])
3653
3907
 
3654
3908
  p_fund = sub.add_parser("fundamental_context")
3655
3909
  p_fund.add_argument("symbol")