stock-analyzer-skill 1.1.0 → 1.2.0

package/methodology.md

@@ -200,25 +200,26 @@ p = 胜率, b = 赔率(期望收益/最大风险)
 |------|--------|------|------|
 | 质量 | quality | ROE、净利增速、营收增速、毛利率、负债率、经营现金流/EPS | 好公司与盈利质量 |
 | 估值 | valuation | PE、PB、PEG、PE/ROE | 安全边际和估值消化能力 |
-| 动量 | momentum | 20 日收益、MA10/MA20、量能比、换手率 | 市场是否开始认可 |
+| 动量 | momentum | 20日收益、MA10/MA20、量能比、换手率 | 市场是否开始认可 |
 | 流动性 | liquidity | 成交额、总市值、换手适中程度 | 能否交易、能否退出 |
+| 波动率 | volatility | 历史收益率标准差（低波动得高分） | A股低波动异象 |
 
-### 5. 策略权重
+### 5. 策略权重（五因子模型）
 
-| 策略 | 市场环境 | 质量 | 估值 | 动量 | 流动性 |
-|------|----------|------|------|------|--------|
-| balanced | 震荡/方向不明 | 32% | 25% | 23% | 20% |
-| quality_value | 价值修复/防守 | 42% | 32% | 10% | 16% |
-| growth_momentum | 进攻行情/主线题材 | 26% | 12% | 42% | 20% |
-| defensive | 缩量弱市/避险 | 38% | 34% | 8% | 20% |
-| turning_point | 超跌修复/拐点 | 24% | 24% | 36% | 16% |
+| 策略 | 市场环境 | 质量 | 估值 | 动量 | 流动性 | 波动率 |
+|------|----------|------|------|------|--------|--------|
+| balanced | 震荡/方向不明 | 25% | 20% | 20% | 15% | 20% |
+| quality_value | 价值修复/防守 | 35% | 30% | 5% | 12% | 18% |
+| growth_momentum | 进攻行情/主线题材 | 18% | 15% | 35% | 12% | 20% |
+| defensive | 缩量弱市/避险 | 25% | 22% | 8% | 12% | 33% |
+| turning_point | 超跌修复/拐点 | 18% | 18% | 32% | 14% | 18% |
 
 ### 6. 输出标准
 
 选股结果必须同时给出：
 
-- 候选排名：总分 + 四因子分。
-- 剔除原因：让“为什么没选”可审计。
+- 候选排名：总分 + 五因子分。
+- 剔除原因：让”为什么没选”可审计。
 - 市场适配：当前更适合进攻、均衡还是防守。
 - 交易计划：买入触发、失效条件、止损/降仓、仓位上限。
 - 后续跟踪：需要复核的财报、公告、板块 ETF、关键均线或支撑位。
@@ -232,9 +233,153 @@ python3 scripts/screener.py --codes sh600989,sz000807,300476 --strategy growth_m
 python3 scripts/screener.py --strategy defensive --exclude-loss --json
 ```
 
-## 七、数据获取工具详解
+## 七、数据获取工具详解（v1.1.0）
 
-### 1. 腾讯实时行情 — 批量查询
+### 1. 代码结构总览
+
+```
+scripts/
+├── __init__.py           # 入口
+├── common/               # 公共工具包（v1.1.0 新增）
+│   ├── __init__.py       # 主模块（缓存、HTTP、编码转换）
+│   ├── validators.py     # 输入验证器
+│   └── exceptions/       # 统一异常类
+│       └── __init__.py
+├── config/               # 配置加载器（v1.1.0 新增）
+│   ├── __init__.py
+│   ├── loader.py
+│   ├── data_source.yaml
+│   ├── industry_thresholds.yaml
+│   ├── limits.yaml
+│   └── scoring.yaml
+├── data/                 # 数据层
+├── strategies/           # 选股策略
+└── technical/            # 技术分析
+```
+
+### 2. Common 模块详解
+
+#### 2.1 缓存与 HTTP
+
+```python
+from common import (
+    cache_get, cache_set, cache_cleanup,
+    http_get, http_get_cached,
+    CACHE_DIR,
+)
+
+# 带缓存的 HTTP 请求（默认 6 小时 TTL）
+data = http_get_cached("https://qt.gtimg.cn/q=sh600989")
+
+# 直接 HTTP 请求
+data = http_get(url, timeout=10)
+```
+
+#### 2.2 股票代码标准化
+
+```python
+from common import normalize_quote_code, normalize_finance_code, plain_code
+
+# 标准化为 sh/sz 前缀格式
+quote_code = normalize_quote_code("600989")  # → "sh600989"
+finance_code = normalize_finance_code("600989")  # → "sh600989"
+plain = plain_code("sh600989")  # → "600989"
+```
+
+#### 2.3 输入验证器
+
+```python
+from common.validators import (
+    validate_code, normalize_code, validate_codes,
+    validate_date, validate_date_range,
+    validate_positive, validate_in_range,
+    ValidationError,
+)
+
+# 验证单个代码
+if validate_code("sh600989"):
+    code = normalize_code("600989")  # → "sh600989"
+
+# 批量验证
+codes = validate_codes(["600989", "000807", "300476"])
+
+# 日期验证
+validate_date_range("2024-01-01", "2024-12-31")
+
+# 数值验证
+validate_positive(10.5, "price", min_value=0)
+validate_in_range(15.0, "pe", 0, 1000)
+```
+
+#### 2.4 统一异常类
+
+```python
+from common.exceptions import (
+    StockAnalyzerError, DataError, NetworkError,
+    RateLimitError, ParseError, DataUnavailableError,
+    BusinessError, ValidationError, StrategyError,
+    InsufficientDataError, ConfigurationError,
+)
+
+try:
+    result = http_get(url)
+except RateLimitError as e:
+    print(f"触发速率限制: {e.retry_after}秒后重试")
+except NetworkError as e:
+    print(f"网络错误: {e.url}, {e.message}")
+except ValidationError as e:
+    print(f"校验失败: {e.field} = {e.value_str}, {e.message}")
+```
+
+### 3. Config 模块详解
+
+```python
+from config import get_limit_config, get_scoring_config, load_industry_thresholds
+
+# 获取限制配置
+st_prefixes = get_limit_config("st_prefixes", ["ST", "*ST"])
+min_amount = get_limit_config("min_amount.创业板", 3000)
+
+# 获取评分配置
+quality_weights = get_scoring_config("weights.quality")
+valuation_weights = get_scoring_config("weights.valuation")
+
+# 获取行业阈值
+thresholds = load_industry_thresholds()
+```
+
+**配置文件说明：**
+
+| 文件 | 用途 |
+|------|------|
+| `limits.yaml` | ST 前缀、最低成交额、最低市值、涨跌停限制 |
+| `scoring.yaml` | 多因子评分权重、因子阈值 |
+| `industry_thresholds.yaml` | 各行业 ROE/PE/增速阈值 |
+| `data_source.yaml` | API 端点配置、缓存 TTL |
+
+### 4. 数据层使用
+
+```python
+from data import get_quote, get_quotes, get_kline, get_finance
+
+# 单只行情
+quote = get_quote("sh600989")
+print(quote.price, quote.pe, quote.change_pct)
+
+# 批量行情
+quotes = get_quotes(["sh600989", "sz000807"])
+
+# K线数据
+bars = get_kline("sh600989", scale=240, datalen=30)  # 日K
+bars = get_kline("sh600989", scale=5, datalen=100)   # 5分钟
+
+# 财务数据
+records = get_finance("sh600989")
+fin = records[0]  # 最新一期
+print(fin.ROEJQ, fin.EPSJB, fin.PARENTNETPROFITTZ)
+```
+
+### 5. 腾讯实时行情 — 批量查询
 
 **单只查询：**
 ```bash
@@ -453,3 +598,158 @@ done
 6. 高赔率≠无风险：仍需止损纪律
 7. 防御仓位（黄金/低估值金融）是组合压舱石
 8. 科技仓位不能为零，至少5-8%
+
+## 十、近期案例复盘总结（2026年6月）
+
+> 完整案例汇总见 `data/reports/202506_Stock_Analysis_Summary.md`
+
+### 10.1 本次分析股票概览
+
+| 股票 | 代码 | 评级 | 置信度 | PE | Q1净利增速 | 今日涨跌 |
+|------|------|------|--------|-----|-----------|----------|
+| 云铝股份 | 000807 | Buy | 80% | 10.7 | +269% | -3.04% |
+| 宝丰能源 | 600989 | Buy | 78% | 13.8 | +50% | +0.73% |
+| 洛阳钼业 | 603993 | Buy | 75% | 15.0 | +97% | -7.15% |
+| 华友钴业 | 603799 | Hold | 65% | 12.1 | +99% | -6.49% |
+| 海尔智家 | 600690 | Hold | 65% | 10.1 | -15% | -0.69% |
+| 贵研铂业 | 600459 | Hold | 55% | 29.8 | +9% | -3.64% |
+| 中兴通讯 | 000063 | **Sell** | 55% | 39.4 | **-47%** | -5.93% |
+
+### 10.2 成功案例特征
+
+**Buy 评级的共同特征**：
+1. **高ROE**：ROE > 15%（云铝19.7%、宝丰24.8%、洛阳26.6%）
+2. **高增长**：Q1净利增速 > 50%（云铝269%、洛阳97%、华友99%）
+3. **低估值**：PE < 15x，PE/ROE < 3
+4. **技术面偏多**：技术评分 > 60，买入信号共振
+
+**案例1：云铝股份**
+- 核心逻辑：Q1净利暴增269%，PE仅10.7x，负债率17.7%极安全
+- 技术面：双针探底+老鸭头形态
+- 结论：Buy，置信度80%，目标价32元
+
+**案例2：宝丰能源**
+- 核心逻辑：ROE 25%顶级，PEG仅0.17严重低估
+- 技术面：三阴一阳+缠论底背驰
+- 结论：Buy，置信度78%，目标价26元
+
+**案例3：洛阳钼业**
+- 核心逻辑：铜金双极战略，Q1净利+97%
+- 技术面：MACD底背离+老鸭头
+- 结论：Buy，置信度75%，目标价20元
+
+### 10.3 失败案例警示
+
+**Sell/Hold 评级的共同特征**：
+1. **业绩下滑**：Q1净利负增长（中兴-47%、海尔-15%）
+2. **高估值陷阱**：PE > 30 且无高增长支撑（中兴PE 39x）
+3. **技术面极弱**：MACD死叉、均线空头排列
+4. **负债率过高**： > 60%（华友63.6%、贵研64.9%）
+
+**案例：中兴通讯**
+- 问题：PE 39x严重高估，Q1净利-47%下滑，ROE仅7.6%
+- 技术面：今日放量大跌-5.93%，MACD死叉
+- 结论：Sell，置信度55%，建议回避
+
+### 10.4 选股核心逻辑总结
+
+| 优先级 | 指标 | 阈值 | 权重 |
+|--------|------|------|------|
+| 1 | ROE | >15%优秀，>20%顶级 | 25% |
+| 2 | 净利增速 | >20%成长，>50%高速 | 25% |
+| 3 | PE/ROE | <3低估，<1极度低估 | 20% |
+| 4 | 技术面 | 评分>60，买入信号共振 | 15% |
+| 5 | 负债率 | <60%健康，<50%优秀 | 10% |
+| 6 | 毛利率 | >30%有壁垒 | 5% |
+
+### 10.5 风险识别模式库
+
+| 风险类型 | 识别信号 | 典型案例 | 应对策略 |
+|----------|----------|----------|----------|
+| 业绩暴降 | Q1/Q2增速转负 | 中兴(-47%) | 立即卖出 |
+| 估值泡沫 | PE>30 且 增速<20% | 中兴(PE 39x) | 回避 |
+| 技术破位 | MACD死叉+放量下跌 | 华友钴业 | 止损 |
+| 负债过高 | 负债率>60% | 华友(63.6%) | 降低仓位 |
+| 周期陷阱 | 低价但无成长 | 贵研铂业 | 观察 |
+| 趋势向下 | 均线空头排列 | 中兴通讯 | 观望 |
+
+### 10.6 今日市场特征（2026-06-08）
+
+- **大盘**：沪深300ETF -2.15%，偏弱震荡
+- **板块**：有色/能源/AI板块领跌
+- **情绪**：7只分析股6只下跌，仅宝丰能源微涨
+- **结论**：市场处于调整期，控制仓位，防守为主
+
+### 10.7 输出格式标准化
+
+深度分析报告必须包含以下核心章节（详见 `skills/stock/SKILL.md` Step 3.1）：
+
+1. **一句话结论**：核心判断 + 置信度
+2. **五层分析**：基本面/估值/技术面/板块/风险收益比
+3. **同业对比**：与行业竞争对手关键指标对比
+4. **8人专家圆桌**：8位专家评分 + 分组汇总 + 信心指数
+5. **投资建议**：评级 + 仓位 + 止损止盈 + 跟踪条件
+6. **核心矛盾**：主要风险点和转折信号
+
+## 十一、测试框架（v1.1.0）
+
+### 1. Pytest 配置
+
+```bash
+# 运行所有测试（跳过网络测试）
+pytest
+
+# 运行包含网络测试
+pytest --run-network
+
+# 运行特定标记的测试
+pytest -m unit
+pytest -m "not slow"
+```
+
+**可用标记：**
+
+| 标记 | 说明 |
+|------|------|
+| `unit` | 单元测试 |
+| `integration` | 集成测试 |
+| `e2e` | 端到端测试 |
+| `network` | 需要网络的测试（默认跳过） |
+| `slow` | 慢速测试 |
+
+### 2. 测试数据 fixtures
+
+```python
+import pytest
+from conftest import (
+    SAMPLE_KLINE,
+    SAMPLE_QUOTE,
+    sample_finance_data,
+    mock_http_get,
+)
+
+# 使用标准K线数据
+def test_ema_trend(SAMPLE_KLINE):
+    closes = [bar["close"] for bar in SAMPLE_KLINE]
+    ...
+
+# 使用标准行情数据
+def test_quota_fields(SAMPLE_QUOTE):
+    assert SAMPLE_QUOTE["pe"] > 0
+```
+
+### 3. Mock 网络请求
+
+```python
+from unittest.mock import patch
+
+@patch("common.http_get")
+def test_with_mock(mock_get):
+    mock_get.return_value = b'...'
+    result = get_quote("sh600989")
+    ...
+```
+
+---
+
+> **版本说明**：v1.1.0 新增 common 包、config 包、增强测试框架。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stock-analyzer-skill",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A 股分析 skill 包，包含 8 个专业分析工具：单股分析、大盘复盘、板块分析、持仓检查、选股策略、技术分析、财务分析、投资研究",
   "main": "index.js",
   "scripts": {

package/scripts/api/__init__.py

@@ -0,0 +1,22 @@
+"""
+API 层 - 面向用户/CLI 的统一入口。
+
+模块:
+- quote_cli: 行情查询 CLI
+- kline_cli: K线查询 CLI
+- screener_cli: 选股 CLI
+- backtest_cli: 回测 CLI
+
+使用方法:
+    from api import quote_cli, screener_cli
+    
+    # 命令行调用
+    python -m api.quote_cli sh600989
+"""
+from .quote_cli import main as quote_main
+from .screener_cli import main as screener_main
+
+__all__ = [
+    "quote_main",
+    "screener_main",
+]

package/scripts/api/quote_cli.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""
+行情查询 CLI (API 层)。
+
+重构自 scripts/quote.py，将用户交互逻辑与业务逻辑分离。
+"""
+import sys
+import json
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from common import (
+    split_codes, 
+    batchify, 
+    normalize_quote_code, 
+    parallel_map, 
+    err,
+    DataError,
+    format_error,
+)
+from common.validators import validate_code
+from data import get_quote, get_quotes
+from common.exceptions import ValidationError
+
+
+def fetch_batch(codes: list, use_cache: bool = True) -> list:
+    """批量获取行情，返回 dict 列表。"""
+    quotes = get_quotes(codes, use_cache=use_cache)
+    return [q.to_dict() for q in quotes]
+
+
+def render_table(records: list):
+    """渲染表格输出。"""
+    if not records:
+        print("(无数据)")
+        return
+    print(f"{'代码':<10} {'名称':<10} {'现价':>8} {'涨跌%':>7} {'PE':>7} {'换手%':>6} {'市值亿':>8}")
+    print("-" * 60)
+    for r in records:
+        print(f"{r['code']:<10} {r['name']:<10} {r['price']:>8} {r['change_pct']:>7} {r['pe']:>7} {r['turnover']:>6} {r['total_cap']:>8}")
+
+
+def main():
+    """主入口。"""
+    if len(sys.argv) < 2:
+        err("用法: python -m api.quote_cli <代码|@文件> [-j] [--sources]")
+    
+    args = sys.argv[1:]
+    
+    if "--sources" in args:
+        from fetchers import get_quote_fetchers
+        fetchers = get_quote_fetchers()
+        print("可用行情数据源:")
+        for f in fetchers:
+            print(f"  - {f.name} (优先级 {f.priority})")
+        return
+    
+    json_mode = "-j" in args
+    args = [a for a in args if a not in ("-j", "--sources")]
+    
+    try:
+        # 验证输入
+        raw_codes = split_codes(args[0])
+        codes = []
+        for c in raw_codes:
+            if not validate_code(c):
+                raise ValidationError("code", c, "格式无效")
+            codes.append(normalize_quote_code(c))
+        
+        if not codes:
+            err("未提供代码")
+        
+        # 分批查询 (腾讯单次 ≤15)
+        batches = list(batchify(codes, 15))
+        if len(batches) > 1:
+            results = parallel_map(
+                lambda b: fetch_batch(b, use_cache=True), 
+                batches, 
+                max_workers=4, 
+                timeout=30
+            )
+            all_records = []
+            for batch in batches:
+                all_records.extend(results.get(batch, []))
+        else:
+            all_records = fetch_batch(batches[0])
+        
+        if json_mode:
+            print(json.dumps(all_records, ensure_ascii=False, indent=2))
+        else:
+            render_table(all_records)
+            
+    except ValidationError as e:
+        print(f"❌ 输入错误: {e.message}", file=sys.stderr)
+        sys.exit(1)
+    except DataError as e:
+        print(f"❌ 数据错误: {format_error(e)}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"❌ 系统错误: {format_error(e)}", file=sys.stderr)
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/api/screener_cli.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""
+选股 CLI (API 层)。
+
+重构自 scripts/screener.py，将用户交互逻辑与业务逻辑分离。
+"""
+import sys
+import json
+import argparse
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from common import DATA_DIR, to_float
+from data import get_quote, get_quotes
+from common.exceptions import ValidationError, format_error
+
+
+def load_universe(sector=None, codes=None):
+    """加载股票池。"""
+    import json
+    
+    if codes:
+        return sorted({normalize_quote_code(c) for c in codes})
+    
+    path = DATA_DIR / "sector_stocks.json"
+    sectors = json.loads(path.read_text(encoding="utf-8"))
+    
+    if sector:
+        matched = []
+        for name, items in sectors.items():
+            if sector.lower() in name.lower():
+                matched.extend(items)
+        if not matched:
+            raise SystemExit(f"未在内置标的库找到板块: {sector}")
+        return sorted({normalize_quote_code(c) for c in matched})
+    
+    all_codes = []
+    for items in sectors.values():
+        all_codes.extend(items)
+    return sorted({normalize_quote_code(c) for c in all_codes})
+
+
+def normalize_quote_code(code: str) -> str:
+    """标准化股票代码。"""
+    c = code.strip().lower()
+    if c.startswith(("sh", "sz", "bj")):
+        return c
+    
+    # 纯数字
+    digits = "".join(filter(str.isdigit, c))
+    if len(digits) != 6:
+        raise ValidationError("code", code, "必须是6位数字")
+    
+    if digits.startswith(("60", "68", "51", "56", "58")):
+        return f"sh{digits}"
+    return f"sz{digits}"
+
+
+def normalize_finance_code(code: str) -> str:
+    """标准化财务代码。"""
+    q = normalize_quote_code(code)
+    return q[:2].upper() + q[2:] if len(q) >= 8 else q.upper()
+
+
+def render(rows, strategy, top):
+    """渲染结果。"""
+    from strategies import STRATEGIES
+    
+    accepted = [r for r in rows if not r.get("rejected")]
+    accepted.sort(key=lambda r: r.get("score", 0), reverse=True)
+    
+    print(f"策略: {STRATEGIES[strategy]['label']} ({strategy})")
+    print(f"入选: {len(accepted)} | 剔除: {len(rows) - len(accepted)}")
+    print()
+    
+    header = "排名 | 代码 | 名称 | 行业 | 板块 | 总分 | 质量 | 估值 | 动量 | 流动性 | PE | ROE | RSI | 20日% | 趋势"
+    print(header)
+    print("-" * len(header))
+    
+    for idx, r in enumerate(accepted[:top], 1):
+        print(
+            f"{idx:>2} | {r['code']:<8} | {r['name']:<8} | {r.get('industry', '默认'):<4} | "
+            f"{r.get('board', '主板'):<4} | {r.get('score', 0):>5} | {r.get('quality', 0):>5} | "
+            f"{r.get('valuation', 0):>5} | {r.get('momentum', 0):>5} | {r.get('liquidity', 0):>6} | "
+            f"{r.get('pe', '-'):>6} | {r.get('roe', '-'):>6} | {r.get('rsi', 50):>4} | "
+            f"{r.get('ret20', 0):>5} | {r.get('trend', '震荡')}"
+        )
+
+
+def main():
+    """主入口。"""
+    parser = argparse.ArgumentParser(description="A 股多因子选股器")
+    parser.add_argument("--strategy", default="balanced")
+    parser.add_argument("--sector", help="板块名称")
+    parser.add_argument("--codes", help="逗号分隔代码列表")
+    parser.add_argument("--top", type=int, default=10)
+    parser.add_argument("--min-amount", type=float, default=5000)
+    parser.add_argument("--min-cap", type=float, default=40)
+    parser.add_argument("--exclude-loss", action="store_true")
+    parser.add_argument("-j", "--json", action="store_true")
+    args = parser.parse_args()
+    
+    try:
+        # 加载股票池
+        codes = load_universe(args.sector, args.codes.split(",") if args.codes else None)
+        
+        # 获取行情
+        quotes = get_quotes(codes)
+        quote_dict = {q.code: q.to_dict() for q in quotes}
+        
+        # TODO: 调用业务层筛选
+        # 暂时简单返回行情数据
+        rows = []
+        for code in codes[:args.top]:
+            if code in quote_dict:
+                q = quote_dict[code]
+                rows.append({
+                    "code": code,
+                    "name": q.get("name", ""),
+                    "score": 0,
+                    "quality": 0,
+                    "valuation": 0,
+                    "momentum": 0,
+                    "liquidity": 0,
+                    "pe": q.get("pe", "-"),
+                    "roe": "-",
+                    "rsi": 50,
+                    "ret20": 0,
+                    "trend": "震荡",
+                    "industry": "默认",
+                    "board": "主板",
+                })
+        
+        if args.json:
+            print(json.dumps(rows, ensure_ascii=False, indent=2))
+        else:
+            render(rows, args.strategy, args.top)
+            
+    except ValidationError as e:
+        print(f"❌ 输入错误: {e.message}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"❌ 系统错误: {format_error(e)}", file=sys.stderr)
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/business/__init__.py

@@ -0,0 +1,15 @@
+"""
+Business 层 - 业务逻辑聚合。
+
+模块:
+- stock_analysis: 个股分析业务流程
+- screening_service: 选股服务
+- backtest_service: 回测服务
+"""
+from .stock_analysis import StockAnalysisService
+from .screening_service import ScreeningService
+
+__all__ = [
+    "StockAnalysisService",
+    "ScreeningService",
+]