@kamuira/stock-analyzer 1.0.5 → 1.2.1

package/README.md

@@ -1,273 +1,263 @@
 # @kamuira/stock-analyzer
 
-A股/台股综合技术分析工具 — 支持实时分析、历史回测、智能买卖建议
+A股/台股综合技术分析工具 — 实时分析、事件驱动回测、可解释的买卖建议
 
-## 功能特性
-
-- 15+ 技术指标综合评分（MA、MACD、RSI、KDJ、布林带、ADX、ATR...）
-- 动态加权评分：根据趋势/震荡市自动调整指标权重
-- 多重信号确认：金叉/死叉需要量能+趋势方向确认，减少假信号
-- 信号连续性判断：区分新信号和已持续信号，避免追高杀低
-- MACD/RSI 顶底背离检测
-- 缺口分析、斐波那契回撤位、动量衰竭检测
-- 形态识别（缩量回踩、放量突破、假突破、锤子线等）
-- 大盘环境过滤（获取上证指数趋势，弱势时降低做多权重）
-- 基于实际支撑/压力位的风险收益比计算
-- 可操作的买入/卖出建议（具体价位、仓位比例、持仓周期）
-- 历史回测验证（500个交易日，统计胜率和平均收益）
-- 支持 A股 + 台股
-- 端口自动重试 + 自动打开浏览器
+## 快速开始
 
-## 安装
+这是一个 CLI 工具,**需要全局安装**或用 `npx`:
 
 ```bash
-# 全局安装
+# 推荐:全局安装
 npm install -g @kamuira/stock-analyzer
 
-# 或直接使用 npx
+# 或者用 npx 直接跑(不安装)
 npx @kamuira/stock-analyzer
 ```
 
+> ⚠️ 本地安装(`npm install @kamuira/stock-analyzer`,不加 `-g`)会出现 `command not found: stock-server`,这是 npm 设计如此 — `node_modules/.bin` 不在 PATH。包内已加 `preferGlobal: true`,本地装会给警告。
+
+## 三个命令
+
+| 命令 | 作用 |
+|---|---|
+| `stock-server` | 启动 Web 界面(自动打开浏览器,默认端口 3000) |
+| `stock-analyze <code>` | CLI 单股分析,输出综合评分和买卖条件 |
+| `stock-backtest <code>` | 历史回测,验证策略在该股票上的真实表现 |
+
+## v1.2 关键改进 ⭐
+
+### 1. 回测验证的就是用户实际用的策略
+
+之前回测内部用的是简化版评分(`quickScore` ≈ 80 行),实盘分析用的是真正的综合评分(`analyzeStock` ≈ 600 行)。**回测给出的"胜率 X%"对实盘没有参考意义**。
+
+v1.1 起,所有评分逻辑统一在 `scoring.js`,**回测和实盘共享同一份代码**。这是这次升级最大的卖点。
+
+### 2. 事件驱动回测,不再是"信号 → N 天后"
+
+旧版回测:每日独立判断 → 信号会重复计数(连涨 10 天每天都触发 buy,统计为 10 次胜利)
+新版回测:
+- ✅ **信号去重**(已持仓不重复入场)
+- ✅ **止损/止盈/反向信号/超时** 四种退出方式
+- ✅ **大盘环境过滤**(每个回测日重算上证趋势,与实盘一致)
+- ✅ 返回每笔完整交易流水
+
+### 3. 指标计算与同花顺/通达信对齐
+
+- RSI 改为 **Wilder 平滑**(标准实现,与 TradingView 一致)
+- ADX 改为 **Wilder smoothing**
+- EMA 用 **SMA 种子**(替代 `data[0]` 单点种子)
+
+### 4. 跟踪止损(可选)
+
+`stock-backtest --trailing` 启用 Chandelier Exit。**注意:不是免费午餐**(详见下方回测章节)。
+
+## 功能特性
+
+- **15+ 技术指标**综合评分(MA、MACD、RSI、KDJ、布林带、ADX、ATR、VWAP)
+- **动态加权评分**:趋势市加大 MA/MACD/ADX 权重,震荡市加大 RSI/KDJ/布林权重
+- **多重信号确认**:金叉/死叉需要量能 + 趋势方向确认,减少假信号
+- **信号连续性判断**:新鲜度衰减,区分新信号和已持续信号,避免追高杀低
+- **MACD/RSI 顶底背离检测**(基于 ZigZag swing,而不是单日峰谷)
+- **有效缺口分析**(size > 0.5% 且当日量 > 1.5× 20日均 才计入)
+- **斐波那契回撤位、动量衰竭检测**
+- **形态识别**(缩量回踩、放量突破、假突破、锤子线、布林收窄突破等)
+- **大盘环境过滤**(获取上证趋势,弱势时降低做多权重)
+- **基于实际支撑/压力位的风险收益比**计算
+- **可操作的买卖建议**(具体价位、仓位比例、持仓周期)
+- **事件驱动历史回测**(信号去重、止损止盈退出、可选跟踪止损)
+- 支持 A股 + 台股
+- 端口自动重试 + 自动打开浏览器
+
 ## 使用方式
 
-### Web 界面（推荐）
+### Web 界面
 
 ```bash
-# 启动服务（自动打开浏览器）
-stock-server
-
-# 开发模式（文件变化自动重启）
-node dev.js
+stock-server                 # 自动打开浏览器
+node dev.js                  # 开发模式:文件变化自动重启
 ```
 
-启动后自动打开浏览器访问 `http://127.0.0.1:3000`，端口被占用会自动 +1 重试。
+启动后访问 `http://127.0.0.1:3000`,端口被占用会自动 +1 重试。
 
-### 命令行分析
+### CLI 分析
 
 ```bash
-# 分析单只股票
-stock-analyze sz002049
-stock-analyze 2330        # 台股（4位数字自动识别）
-stock-analyze 紫光国微     # 支持中文名搜索
-
-# 分析所有关注列表
-stock-analyze all
+stock-analyze sz002049       # A股(带前缀)
+stock-analyze 002049         # A股(纯数字,自动识别)
+stock-analyze 2330           # 台股(4位数字)
+stock-analyze 紫光国微        # 中文名搜索
+stock-analyze zggw           # 拼音缩写
+stock-analyze all            # 分析内置关注列表
 ```
 
-### 回测验证
+### CLI 回测
 
 ```bash
-# 回测单只股票
-stock-backtest sh601138
-
-# 回测所有
-stock-backtest all
+stock-backtest sh603986                       # 默认:TP1 止盈 + 反向信号退出
+stock-backtest sh603986 --trailing            # 启用跟踪止损(2.5×ATR)
+stock-backtest sh603986 --trailing --trailing-atr=1.5
+stock-backtest sh603986 --trailing --no-tp1   # 纯趋势跟随(只靠跟踪止损)
+stock-backtest all                            # 回测全部关注列表
 ```
 
-## 支持的输入格式
+## 输入格式
 
 | 格式 | 示例 | 说明 |
 |------|------|------|
-| 6位数字 | `002049` | 自动识别A股（6开头=上海，其他=深圳） |
-| sh/sz前缀 | `sz002049` | 明确指定A股 |
+| 6位数字 | `002049` | 自动识别A股(6开头=上海,其他=深圳) |
+| sh/sz 前缀 | `sz002049` | 明确指定A股 |
 | 4位数字 | `2330` | 自动识别台股 |
-| tw前缀 | `tw2330` | 明确指定台股 |
-| 中文名称 | `紫光国微` | 搜索A股 |
-| 拼音缩写 | `zggw` | 搜索A股 |
+| tw 前缀 | `tw2330` | 明确指定台股 |
+| 中文名 | `紫光国微` | 走腾讯智能搜索 |
+| 拼音缩写 | `zggw` | 走腾讯智能搜索 |
 
-## 技术指标一览
+## 技术指标
 
 | 指标 | 用途 | 参数 |
 |------|------|------|
 | MA (5/10/20/60) | 趋势方向、支撑压力 | 多头/空头排列、金叉死叉 |
 | MACD (12,26,9) | 趋势动能、买卖时机 | 金叉死叉、零轴位置、柱状线 |
-| RSI (14) | 超买超卖 | <30超卖、>70超买 |
+| RSI (14) Wilder | 超买超卖 | <30超卖、>70超买 |
 | KDJ (9,3,3) | 短期超买超卖 | J值极端、金叉死叉 |
 | 布林带 (20,2) | 波动区间、变盘信号 | 触轨、带宽收窄 |
-| ADX (14) | 趋势强度 | >25趋势市、<20震荡市 |
+| ADX (14) Wilder | 趋势强度 | >25趋势市、<20震荡市 |
 | ATR (14) | 波动率、仓位管理 | 止损距离、仓位建议 |
 | VWAP (20) | 量价均衡位 | 支撑/压力参考 |
 
-## 高级分析功能
-
-### 信号确认机制
-
-每个金叉/死叉信号需要多重确认才给满分：
-
-```
-确认因素：量能放大 + 趋势方向一致 + 价格位置合理
-- 3项确认 → 满分（强信号）
-- 2项确认 → 7折
-- 1项确认 → 5折
-- 0项确认 → 仅给基础分（可能是假信号）
-```
-
-### 动态加权评分
-
-根据 ADX 判断市场状态，自动切换权重：
-
-- **趋势市 (ADX>=25)**：加大 MA、MACD、ADX 权重，降低 RSI、KDJ 权重
-- **震荡市 (ADX<20)**：加大 RSI、KDJ、布林带权重，降低趋势指标权重
-- **ADX<15 极度震荡**：所有信号打 4 折（几乎无效）
-
-### 趋势一致性检查
-
-```
-短期(5日) + 中期(20日) + 长期(60日) 方向一致 → +3分
-短期和中期方向矛盾 → 信号打8折
-```
-
-### 大盘环境过滤
-
-自动获取上证指数趋势：
-- 大盘偏强 → 整体 +1.5 分
-- 大盘偏弱 → 整体 -1.5 分，且正分打 7 折
-
----
-
 ## 评分体系
 
 ### 信号分级
 
 | 评分 | 信号 | 建议操作 |
 |------|------|----------|
-| >= 10 | 强烈买入 | 积极建仓，持仓5-10天 |
-| >= 5 | 建议买入 | 适量买入，持仓3-5天 |
-| >= 1 | 谨慎买入 | 小仓位试探，持仓1-3天 |
-| >= -4 | 观望 | 不操作，等待方向 |
-| >= -9 | 建议卖出 | 减仓或观望 |
+| ≥ 10 | 强烈买入 | 积极建仓,持仓 5-10 天 |
+| ≥ 5 | 建议买入 | 适量买入,持仓 3-5 天 |
+| ≥ 1 | 谨慎买入 | 小仓位试探,持仓 1-3 天 |
+| ≥ -4 | 观望 | 不操作,等待方向 |
+| ≥ -9 | 建议卖出 | 减仓或观望 |
 | < -9 | 强烈卖出 | 清仓回避 |
 
-### 买入条件逻辑
+### 动态加权
 
-根据评分高低给出不同激进程度的入场建议：
+根据 ADX 判断市场状态,自动切换权重:
+- **趋势市 (ADX ≥ 25)**:加大 MA、MACD、ADX 权重,降低 RSI、KDJ
+- **震荡市 (ADX < 20)**:加大 RSI、KDJ、布林权重,降低趋势指标
+- **极度震荡 (ADX < 15)**:整体打 4 折(信号基本无效)
 
-| 评分区间 | 入场策略 |
-|----------|----------|
-| >= 5（强势） | 当前价附近或日内回调半个ATR入场 + 分批建仓方案 |
-| 1-4（偏多） | 等回调2-3%后出现止跌信号再买 |
-| < 1（中性/偏空） | 等布林下轨抄底或站回MA20 |
+### 趋势一致性
 
-### 风险收益比
+短期(5日) + 中期(20日) + 长期(60日) 三方向一致 → +3 分;短中期矛盾 → 信号打 8 折。
 
-基于实际支撑/压力位计算（非机械ATR倍数）：
+### 大盘环境
 
-**止损位选取（最近的下方支撑）：**
-- MA20（如果在下方）
-- 布林下轨
-- 近20日最低价
-- ATR止损（兜底）
+自动获取上证指数 20 日趋势,弱势时降权 + 减分。
 
-**止盈位选取（上方有意义的压力位，排除距离<2%的）：**
-- 近20日最高价
-- 布林上轨
-- 斐波那契回撤位
-- ATR目标（补充）
+### 风险收益比
 
-```
-风险收益比 = (止盈位 - 当前价) / (当前价 - 止损位)
+基于**实际支撑/压力位**计算(非机械 ATR 倍数):
 
->= 2.0 → "入场性价比高"
-< 1.0  → "建议等回调再入场"
+```
+止损位 = 最近的下方支撑(MA20 / 布林下轨 / 近20日低 / ATR兜底)
+止盈位 = 上方有意义的压力(近20日高 / 布林上轨 / 斐波那契位)
+风险收益比 = (止盈 - 当前) / (当前 - 止损)
 ```
 
----
+`≥ 2.0` 标记"性价比高",`< 1.0` 标记"建议等回调"。
 
-## 回测验证
+## 事件驱动回测
 
-### 胜率计算方法
+### 退出逻辑(优先级)
 
-**触发条件：**
-- 当日综合评分 >= 5 → 记为"买入信号"
-- 当日综合评分 <= -5 → 记为"卖出信号"
-- 中间区域 → "观望"，不计入统计
+1. **止损**:当日 low ≤ 入场时计算的 stopLoss
+2. **止盈**:当日 high ≥ 入场时计算的 takeProfit1(默认开启,可用 `--no-tp1` 关闭)
+3. **反向信号**:持仓中再次评分,score ≤ -5(多头退出)
+4. **超时**:超过 maxHoldDays(默认 30 天)
+5. **数据末尾**:回测期结束强制平仓
 
-**计算公式：**
-```
-买入胜率 = 信号发出后N天价格上涨的次数 / 买入信号总次数 × 100%
-平均收益 = 所有买入信号N天后涨跌幅之和 / 买入信号总次数
-```
-
-**流程：**
-1. 取500个交易日（约2年）历史数据
-2. 从第60天开始逐日计算综合评分
-3. 评分>=5时记录收盘价为入场价
-4. 分别统计 3天、5天、10天 后的涨跌
+### `--trailing` 跟踪止损
 
-**评级标准（取3/5/10日最佳表现）：**
-| 评级 | 条件 |
-|------|------|
-| 优秀 | 最佳胜率 >= 65% 且均收益 > 2% |
-| 良好 | 最佳胜率 >= 58% 且均收益 > 1% |
-| 一般 | 最佳胜率 >= 55%，或胜率>=50%且均收益>0.5% |
-| 较差 | 以上都不满足 |
+启用 Chandelier Exit:`stopLoss = max(原止损, peak − 2.5 × ATR)`,只上调不下调。
 
-### 回测结果（26只股票验证）
+**重要洞察:不是免费午餐**。同一份策略,不同股票表现完全不同:
 
-**适合本系统（胜率55%+）：**
-| 股票 | 5日胜率 | 5日均收益 | 类型 |
-|------|---------|-----------|------|
-| 兆易创新 | 68.5% | +5.50% | 半导体 |
-| 台积电 | 66.1% | +1.93% | 半导体 |
-| 阳光电源 | 64.5% | +4.82% | 新能源 |
-| 立讯精密 | 64.1% | +4.03% | 消费电子 |
-| 湖南白银 | 64.1% | +6.82% | 有色金属 |
-| 宏和科技 | 63.1% | +7.61% | 新材料 |
-| 工业富联 | 60.0% | +3.83% | AI/科技 |
-| 中芯国际 | 59.7% | +3.27% | 半导体 |
-| 紫金矿业 | 59.6% | +2.14% | 资源 |
+| 股票 | 默认 TP1 累计 | 纯跟踪止损累计 | 适合谁 |
+|---|---|---|---|
+| 兆易创新(ATR 6.5%) | **+68.56%** | +18.97% | ❌ 高波动股不要开 |
+| 工业富联(中波动) | **+84.95%** | +56.61% | ❌ 中波动股也不建议 |
+| 华能国际(低波动) | -0.31% | **+5.43%** | ✅ 低波动股开了救回 |
+| 中国平安(蓝筹) | +17.53% | **+29.65%** | ✅ 蓝筹股开了加分 |
 
-**不适合本系统（胜率<45%）：**
-- 银行股（招商银行、平安银行）— 低波动，政策驱动
-- 白酒消费（茅台、五粮液）— 基本面下行时技术面失效
-- 公用事业（核电、长江电力）— 波动太小
-- 券商（中信建投）— 脉冲式行情，趋势不持续
+原因:跟踪距离 = `2.5 × ATR`。ATR 大 → 回撤容忍 15%+ → 利润吐回;ATR 小 → 紧密跟踪 → 锁住利润。**自己用 `--trailing` 跑一遍,看哪些股票适合**。
 
-**结论：** 本系统最适合波动率适中(ATR 2-6%)、趋势性强(ADX经常>25)、成交活跃的科技/成长/有色金属类股票。
+### 评级标准
 
-### 当前局限性
+| 评级 | 条件 |
+|------|------|
+| 优秀 | 胜率 ≥ 60% 且均收益 > 3% |
+| 良好 | 胜率 ≥ 55% 且均收益 > 1.5% |
+| 一般 | 胜率 ≥ 50% 或 均收益 > 0 |
+| 较差 | 以上都不满足 |
 
-- 每天独立判断，连续信号不去重
-- 未模拟实际仓位管理和交易手续费
-- 未考虑止损提前退出
-- 固定持有N天后退出，不考虑中途信号变化
+### 当前局限
 
----
+- ❌ 未计手续费和滑点(按用户场景需求暂未实现)
+- ❌ 单股回测,无多周期共振(日+周+月)
+- ❌ 无信号日志/复盘(每次回测都重新算)
 
 ## 数据来源
 
-| 数据 | A股来源 | 台股来源 |
+| 数据 | A股 | 台股 |
 |------|---------|---------|
 | 实时行情 | 新浪财经 (hq.sinajs.cn) | TWSE MIS API |
 | 历史K线 | 腾讯财经 (web.ifzq.gtimg.cn) | Yahoo Finance |
 | 股票搜索 | 腾讯智能搜索 (smartbox.gtimg.cn) | — |
-| 大盘指数 | 腾讯财经 (上证000001) | — |
+| 大盘指数 | 腾讯财经(上证 000001) | — |
 
 ## 项目结构
 
 ```
-├── server.js        # Web 服务主程序（含所有分析逻辑）
-├── analyze.js       # CLI 分析工具
-├── backtest.js      # 回测验证工具
-├── dev.js           # 开发模式（文件变化自动重启）
-├── stock.js         # 数据获取工具
-├── index.html       # 前端页面
-├── package.json     # npm 包配置
-├── README.md        # 本文件
-└── bin/
-    ├── analyze.js   # CLI 入口: stock-analyze
-    ├── server.js    # 服务入口: stock-server
-    └── backtest.js  # 回测入口: stock-backtest
+├── indicators.js   # 技术指标:SMA/EMA/MACD/RSI/KDJ/BOLL/ATR/ADX/ZigZag 等
+├── scoring.js      # 评分逻辑(唯一来源,被 analyze/backtest/server 共享)
+├── analyze.js      # CLI 单股分析 + 数据获取(A股+台股)
+├── backtest.js     # 事件驱动回测引擎
+├── server.js       # Web 服务(API + 静态文件)
+├── dev.js          # 开发模式(文件变化自动重启)
+├── index.html      # 前端页面
+└── bin/            # CLI 入口
+    ├── analyze.js
+    ├── server.js
+    └── backtest.js
 ```
 
 ## 环境要求
 
-- Node.js >= 14.0.0
-- 无需安装任何第三方依赖（纯原生 Node.js 实现）
-- 需要网络连接（获取实时/历史数据）
+- Node.js ≥ 14
+- 无需任何第三方依赖(纯原生 Node.js)
+- 需要网络(获取实时/历史数据)
 
 ## 更新日志
 
+### v1.2.1
+- 加 `--trailing` / `--trailing-atr` / `--no-tp1` 三个回测参数
+- Chandelier Exit 实现(跟踪止损 = peak − N × ATR)
+- README 提供跨股票对比数据,说明跟踪止损在低 ATR 股上才发挥作用
+
+### v1.2.0
+- 事件驱动回测:信号去重、止损止盈退出、反向信号退出、超时退出
+- 回测加入历史大盘环境过滤(`getMarketEnvAtDate`),与实盘一致
+- 背离检测改用 ZigZag swing(替代单日峰谷,大幅减少假背离)
+- 缺口检测加 size > 0.5% + 量 > 1.5× 20日均 过滤
+- 回测 API 改成事件驱动版,返回完整交易流水
+
+### v1.1.0
+- **抽取 `indicators.js` + `scoring.js` 共享模块**,消除三处重复评分代码
+- 回测和实盘统一使用 `scoring.js`,**回测验证的就是用户实际用的策略**
+- RSI 改 Wilder 平滑(与同花顺/TradingView 对齐)
+- ADX 改 Wilder smoothing(标准 Welles Wilder 算法)
+- EMA 用 SMA 种子(替代单点种子)
+- 加 `preferGlobal: true`,本地装会给警告
+- 总代码量减少 46%(3367 → 1825 行)
+
 ### v1.0.3
 - 修复 README 在 npm 页面不显示的问题
 
@@ -282,17 +272,10 @@ stock-backtest all
 
 ### v1.0.0
 - 初始发布
-- 15+ 技术指标综合分析
-- 动态加权评分 + 多重信号确认
-- 历史回测验证
-- A股 + 台股支持
-- Web 界面 + CLI 工具
-
----
 
 ## 免责声明
 
-本工具仅基于技术面指标进行分析，不构成任何投资建议。技术分析有其固有局限性，无法预测突发事件、政策变化、基本面恶化等因素。投资有风险，入市需谨慎。使用本工具产生的任何投资损失，作者不承担任何责任。
+本工具仅基于技术面指标进行分析,不构成任何投资建议。技术分析有其固有局限性,无法预测突发事件、政策变化、基本面恶化等因素。投资有风险,入市需谨慎。使用本工具产生的任何投资损失,作者不承担任何责任。
 
 ## License