shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析无需 API Key

量化小精灵

A股, 量化, 行情, 选股, 回测, 自选股, 预警, 推送, 技术分析, 策略回测, SQLite, Flask, Plotly

person作者: user_7f2d3808hubcommunity
download下载资源包

量化小精灵 (Quant Elf)

Overview

个人 A 股量化分析工具「量化小精灵」，基于 AkShare 开源数据库 + 新浪财经API（多数据源自动回退），数据持久化使用内置 SQLite 数据库。七大模块：

  • stock_cli.py — 实时行情/历史K线/技术指标/K线图/资金流向/财务/板块/选股
  • strategy.py — 15种量化策略回测（均线/MACD/RSI/布林/KDJ/量价/多因子/海龟/DualThrust/RSI背离/网格/布林+ATR/MACD量能/DMA）+ 策略对比 + 实时信号
  • watchlist.py — 自选股管理 + 价格预警 + 新闻监控 + 多平台推送（飞书/钉钉/企业微信/Telegram/邮件）
  • stock_monitor.py — 技术指标监控（7大规则：涨跌幅/均线交叉/RSI/量异动/跳空/涨跌停）
  • db.py — SQLite 数据库模块（12张表，含投资组合 + 全市场产品目录）
  • market_init.py — 全市场产品目录初始化与每日增量更新（A股/ETF/可转债，新股上市/退市检测）
  • market_scan.py — 市场全景扫描（涨跌停板池/北向资金/大盘资金流/大宗交易/解禁/回购/业绩预告/分红送配/热度排行/指数行情）
  • web_server.py — Flask + Plotly Web 可视化仪表盘（K线/回测/预测/投资组合，浅蓝清爽主题 v4）
  • static/predict.js — 预测页面独立JS（场景切换 + 蒙特卡洛渲染，绕开f-string转义灾难）
  • K线图 — mplfinance 红涨绿跌（中国习惯）+ 技术指标叠加

数据源策略：新浪API优先（本机网络环境最稳定），东财API备选。详见 references/network_proxy_workaround.md。

When to Use

  • "查看XX股票实时行情"
  • "XX股票最近30天K线"
  • "XX的技术指标怎么样"（RSI/MACD/均线）
  • "XX的资金流向/主力资金"
  • "筛选涨跌幅>5%且换手率>3%的股票"
  • "监控XX股票，涨跌超过3%提醒我"
  • "XX股票的财务报表"
  • "今天的龙虎榜"
  • "半导体板块有哪些股票"
  • "搜索茅台" / "帮我查一下芯片ETF"（模糊搜索A股/ETF/可转债）
  • "最近有什么新股上市" / "有哪些退市股票"（新股/退市检测）
  • "初始化股票数据库" / "更新股票列表"（全市场产品目录维护）
  • "今天涨停了哪些股票" / "强势股有哪些"（涨跌停板池分析）
  • "北向资金今天流入了多少" / "大盘资金流向"（资金面分析）
  • "今天有哪些大宗交易" / "近期解禁的股票"（大宗交易/解禁监控）
  • "哪些公司在回购股票" / "业绩预告" / "分红送配"（回购/业绩/分红）
  • "一键看盘" / "市场全景扫描"（涨跌停+资金+热度+大宗+解禁 汇总）
  • "上证指数最近走势" / "创业板指数K线"（指数行情）
  • "帮我选股"（需要给出筛选条件）
  • "回测均线策略"（量化策略回测）
  • "添加自选股" / "监控XX股票到XX价格"（自选股管理）
  • "有新闻了提醒我" / "推送到飞书/钉钉"（新闻监控+消息推送）
  • "启动Web服务器" / "可视化展示"（Flask仪表盘）
  • "帮我设计图表界面"（Plotly交互式图表）
  • "股价预测" / "未来走势"（蒙特卡洛预测）
  • "我的持仓" / "投资组合"（实际资产管理）

Don't use for: 港股/美股/加密货币（本技能专注A股，含北证A股）。高频交易/tick级数据（AkShare是分钟级延迟，非实时tick）。

Quick Start

安装依赖

pip install akshare pandas mplfinance matplotlib flask plotly

核心命令

# 实时行情（全市场快照或单只）
python scripts/stock_cli.py spot 000001
python scripts/stock_cli.py spot --market full

# 历史K线 + 技术指标
python scripts/stock_cli.py hist 000001 --days 60 --period daily --indicators ma,macd,rsi,boll

# K线图（输出PNG）
python scripts/stock_cli.py chart 000001 --days 60 --type candle --indicators ma,boll,volume
python scripts/stock_cli.py chart 000001 --days 90 --type line

# 资金流向
python scripts/stock_cli.py fund 000001 --days 10

# 财务数据
python scripts/stock_cli.py finance 000001 --report income
python scripts/stock_cli.py finance 600519 --report indicator

# 板块分析
python scripts/stock_cli.py board --type industry
python scripts/stock_cli.py board --type concept
python scripts/stock_cli.py board-cons 半导体

# 选股
python scripts/stock_cli.py screen --change 5 --turnover 3 --volume_ratio 2
python scripts/stock_cli.py screen --pe 0,30 --pb 0,5

# 龙虎榜
python scripts/stock_cli.py lhb --date 20240930

# 融资融券
python scripts/stock_cli.py margin 600000 --days 10

# 一键报告（输出完整分析报告）
python scripts/stock_cli.py report 000001

# 搜索股票/ETF/可转债（优先本地数据库，fallback新浪API）
python scripts/stock_cli.py search 茅台
python scripts/stock_cli.py search 芯片 --limit 5

全市场产品目录初始化与每日更新

将全市场 A股（沪/深/北）+ ETF基金 + 可转债 产品目录初始化到 SQLite，后续查询直接从数据库读取，无需每次调用网络API。每日增量更新自动检测新股上市和退市。

# 全量初始化（首次运行，约30秒，采集约7800+产品）
python scripts/market_init.py init

# 增量更新（每日运行，检测新股上市/退市，记录到update_log）
python scripts/market_init.py update

# 模糊搜索产品（代码或名称）
python scripts/market_init.py search 茅台
python scripts/market_init.py search 半导体 --limit 10

# 产品目录统计
python scripts/market_init.py stats

# 查看最近上市新股（默认30天）
python scripts/market_init.py new
python scripts/market_init.py new --days 60

# 查看退市股票
python scripts/market_init.py delisted

数据源（全部避开被Clash阻断的东财push2域名）：

| 产品类型 | 数据源 | 接口 | |----------|--------|------| | 沪市A股（主板+科创板）| 上交所官网 | stock_info_sh_name_code | | 深市A股（主板+创业板）| 深交所官网 | stock_info_sz_name_code | | 北证A股 | 北交所官网 | stock_info_bj_name_code | | ETF基金 | 新浪财经 | fund_etf_category_sina | | 可转债 | 新浪财经 | bond_zh_hs_cov_spot | | 退市股票（沪市）| 上交所官网 | stock_info_sh_delist | | 退市股票（深市）| 深交所官网 | stock_info_sz_delist |

SQLite表结构：

  • stock_basic — 产品目录（code/name/type/market/industry/list_date/status）
  • update_log — 每日更新日志（new_listing/delisting/re_listing）

配合 Hermes Cron 每日自动更新：

# 每天收盘后17:00自动增量更新
hermes cron add --name "产品目录更新" --cron "0 17 * * 1-5" \
  --message "运行 python scripts/market_init.py update" --deliver telegram

市场全景扫描

多维度市场情绪分析工具，一键看盘 + 10个子命令覆盖涨跌停/资金面/大宗交易/解禁/回购/业绩/分红/热度/指数。

# 一键全景看盘（涨跌停+资金+热度+大宗+解禁 汇总）
python scripts/market_scan.py scan

# 涨跌停板池
python scripts/market_scan.py zt                      # 今日涨停板
python scripts/market_scan.py zt --type previous      # 昨日涨停
python scripts/market_scan.py zt --type strong        # 强势股池
python scripts/market_scan.py zt --type dtgc          # 跌停股池

# 北向资金（沪深港通）
python scripts/market_scan.py north                   # 北向资金流向
python scripts/market_scan.py north --stock 600519    # 个股北向持股

# 大盘资金流
python scripts/market_scan.py flow                    # 主力资金进出

# 限售股解禁时间表
python scripts/market_scan.py unlock

# 大宗交易明细
python scripts/market_scan.py block                   # 今日大宗交易
python scripts/market_scan.py block --date 20260709   # 指定日期

# 股票回购一览
python scripts/market_scan.py buyback --limit 30

# 业绩预告
python scripts/market_scan.py forecast                # 自动选最近报告期

# 个股分红送配明细
python scripts/market_scan.py dividend 000001

# 热度排行（东财人气榜）
python scripts/market_scan.py hot --limit 50

# 指数行情（上证/深证/创业板）
python scripts/market_scan.py index sh000001 --days 30
python scripts/market_scan.py index sz399006 --days 60

数据源：东财数据中心（涨停板/大宗交易/回购/业绩/北向资金）+ 新浪财经（解禁/指数/可转债）+ 腾讯（指数备用）。

⚠️ stock_hot_rank_em（热度排行）和 stock_market_fund_flow（大盘资金流）依赖东财push2域名，本机Clash环境下可能间歇性失败，scan命令会自动跳过失败项。

预警监控

# 添加监控
python scripts/stock_monitor.py add 000001 --rule change_percent --threshold 3
python scripts/stock_monitor.py add 600519 --rule ma_cross --period 5,20
python scripts/stock_monitor.py add 300750 --rule rsi --oversold 30 --overbought 70
python scripts/stock_monitor.py add 002594 --rule volume_spike --threshold 2

# 查看监控列表
python scripts/stock_monitor.py list

# 执行监控检查（配合定时任务）
python scripts/stock_monitor.py check

# 删除监控
python scripts/stock_monitor.py remove 000001

技术指标说明

| 指标 | 参数 | 用途 | |------|------|------| | MA | 5/10/20/60日 | 均线系统，判断趋势方向 | | EMA | 12/26日 | 指数均线，权重偏近期 | | RSI | 14日 | 超买(>70)/超卖(<30)，判断强弱 | | MACD | 12,26,9 | 趋势动量，金叉/死叉信号 | | BOLL | 20日,2σ | 布林带，判断波动率和支撑/压力 | | KDJ | 9,3,3 | 随机指标，短线买卖信号 | | VWAP | 当日 | 成交量加权均价，机构参考线 | | ATR | 14日 | 真实波幅，止损/仓位管理 |

选股策略条件

| 条件 | 参数格式 | 说明 | |------|----------|------| | 涨跌幅 | --change 5 (涨>5%) 或 --change -5 (跌>5%) | 当日涨跌幅筛选 | | 换手率 | --turnover 3 | 换手率>3% | | 量比 | --volume_ratio 2 | 量比>2 | | 市盈率 | --pe 0,30 | PE在0-30之间 | | 市净率 | --pb 0,5 | PB在0-5之间 | | 涨速 | --speed 2 | 5分钟涨速>2% |

多个条件可组合使用，取交集。

预警规则

| 规则 | 说明 | 配置 | |------|------|------| | change_percent | 涨跌幅超阈值 | --threshold 3 (±3%) | | ma_cross | 均线金叉/死叉 | --period 5,20 (5日/20日均线) | | rsi | RSI超买/超卖 | --oversold 30 --overbought 70 | | volume_spike | 成交量异常放大 | --threshold 2 (2倍均量) | | gap | 跳空缺口 | --threshold 1 (±1%缺口) | | limit_up | 涨停板预警 | (无需阈值) | | limit_down | 跌停板预警 | (无需阈值) |

监控规则持久化在 SQLite 数据库 ~/.hermes/a-stock/a-stock.db（表 monitor_rules）。

量化策略回测

15种内置策略，支持单策略回测和多策略对比。策略来源：经典技术形态（均线/MACD/RSI/布林/KDJ/量价/多因子）+ 社区调研工业级策略（海龟/Dual Thrust/RSI背离/网格/布林+ATR/MACD量能/DMA）。

策略列表

| 策略代号 | 说明 | 信号逻辑 | 来源 | |----------|------|----------|------| | ma | 均线交叉 | MA5上穿MA20买入/下穿卖出 | 经典 | | macd | MACD金叉死叉 | DIF上穿DEA买入/下穿卖出 | 经典 | | rsi | RSI超买超卖反转 | RSI<30回升买入/>70回落卖出 | 经典 | | boll | 布林带突破 | 触及下轨买入/触及上轨卖出 | 经典 | | vol | 量价突破 | 放量+站上均线买入 | 经典 | | kdj | KDJ金叉死叉 | K上穿D买入/下穿卖出 | 经典 | | multi | 多因子组合 | MACD金叉+RSI<50+放量 三重确认 | 经典 | | turtle | 海龟交易法 | 唐奇安通道(20日)突破+ATR(2×)止损 | VectorFactory | | turtle2 | 海龟2.0 | 短周期灵敏版(10/5日通道) | VectorFactory改编 | | dual_thrust | Dual Thrust | N日区间突破(K1/K2比例上下轨) | VectorFactory | | rsi_div | RSI底背离 | 价格新低+RSI不新低→动能衰竭买入 | VectorFactory | | grid | 网格交易 | 价格区间等分N格，震荡买卖 | EasyQuant | | boll_atr | 布林带+ATR止损 | 下轨买入+上轨卖出+ATR动态止损 | EasyQuant | | macd_vol | MACD+量能确认 | 金叉且成交量>1.5倍均量才买入 | EasyQuant | | dma | DMA+BIAS | 平行线差趋势+乖离率过滤 | 社区通用 |

回测命令

# 单策略回测
python scripts/strategy.py backtest 000001 --strategy ma --days 120 --verbose

# 海龟交易法回测
python scripts/strategy.py backtest 000001 --strategy turtle --days 250

# 对比所有策略（找出最优策略）
python scripts/strategy.py compare 000001 --days 180

# 查看当前交易信号
python scripts/strategy.py signal 000001 --strategy multi
python scripts/strategy.py signal 000001 --all   # 所有策略综合信号

回测输出：策略收益 vs 基准收益（买入持有）、超额收益、最大回撤、胜率、年化收益、夏普比率。

未来股价预测（蒙特卡洛模拟引擎）

预测页面 /predict 调用 predict_future_prices() 函数（位于 web_server.py）：蒙特卡洛模拟 + 多因子趋势驱动。

三步流程：

  1. 提取历史收益率分布：最近60日日收益率(log returns)的标准差 → 波动率
  2. 合成多因子漂移率(drift)：5个因子合成日预期收益率
  3. 几何布朗运动(GBM)模拟：1000次随机游走 × 30交易日，从模拟分布提取 P25(悲观)/P50(中性)/P75(乐观)

5个漂移因子：

| 因子 | 计算 | 权重 | |------|------|------| | MA5/MA20多空趋势 | MA5偏离MA20百分比 | × 0.15 | | MACD动量加速度 | sign(DIF-DEA) × min(|ΔMACD|×3, 0.2%) | 线性 | | RSI均值回归 | RSI>70→回调, RSI<30→反弹 | ×0.02% per unit | | 布林带位置 | boll_pos>0.85→回调, <0.15→反弹 | ±0.05% | | 策略信号 | 买入/卖出/观望 | ±0.03% |

资产预测逻辑：

  • 持仓中：资产 = 持仓股数 × 预测股价
  • 空仓时：假设以当前价满仓买入，资产 = 等效股数 × 预测股价（而不是资产不变）

⚠️ 预测基于蒙特卡洛模拟，仅供参考，不构成投资建议。

自选股 + 消息推送

自选股管理系统：添加股票 → 设定价格/涨跌幅提醒 → 开启新闻监控 → 自动推送到飞书/钉钉/企业微信/Telegram/邮件。

添加自选股

# 添加股价提醒（突破/跌破目标价）
python scripts/watchlist.py add 000001 --price 11.0 --direction above
python scripts/watchlist.py add 600519 --price 1100 --direction below

# 添加涨跌幅提醒
python scripts/watchlist.py add 300750 --change 5    # 涨跌超5%提醒

# 开启新闻监控
python scripts/watchlist.py add 000001 --news

# 组合：价格+涨跌幅+新闻
python scripts/watchlist.py add 000001 --price 10.5 --direction below --change 3 --news

# 查看自选股列表（实时行情+提醒状态）
python scripts/watchlist.py list

# 移除自选股
python scripts/watchlist.py remove 000001

配置消息推送

详细配置步骤见 templates/webhook_setup.md。快速开始：

# 飞书机器人
python scripts/watchlist.py webhook add my-feishu --platform feishu --url "https://open.feishu.cn/open-apis/bot/v2/hook/xxx"

# 钉钉机器人
python scripts/watchlist.py webhook add my-ding --platform dingtalk --url "https://oapi.dingtalk.com/robot/send?access_token=xxx"

# 企业微信机器人
python scripts/watchlist.py webhook add my-wx --platform wechat_work --url "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"

# Telegram Bot
python scripts/watchlist.py webhook add my-tg --platform telegram --token "123456:ABC" --chat_id "789012"

# 邮件推送（QQ邮箱）
python scripts/watchlist.py webhook add my-email --platform email --host smtp.qq.com --user "xxx@qq.com" --password "SMTP授权码" --to_email "xxx@qq.com"

# 测试推送
python scripts/watchlist.py webhook test

执行检查 + 自动推送

# 手动检查（价格+新闻），触发提醒自动推送到所有配置的平台
python scripts/watchlist.py check

# 重置今日提醒（允许明天重新触发）
python scripts/watchlist.py clear --what alerts

配合 Hermes Cron 定时推送

# 交易时间每10分钟检查，推送到 Telegram
hermes cron add --name "自选股监控" --cron "*/10 9-14 * * 1-5" \
  --message "运行 python scripts/watchlist.py check" --deliver telegram

所有数据持久化在 SQLite 数据库 ~/.hermes/a-stock/a-stock.db（10张表，含自选股/提醒/监控规则/推送平台/预警历史/新闻缓存/K线缓存/回测结果/投资组合/预测日志）。

# 从旧JSON迁移数据到SQLite
python scripts/db.py migrate

# 查看数据库统计
python scripts/db.py stats

# 查看表结构
python scripts/db.py tables

# 清空数据库（危险）
python scripts/db.py reset --confirm

Web 可视化服务器

Flask + Plotly 交互式仪表盘，浅蓝清爽主题 v4（白底卡片 + 蓝色点缀 + JetBrains Mono等宽数据字体）。

⚠️ 用户偏好（2026-07-08 纠正）：用户明确不喜欢全黑深色主题，说"怎么都是黑色的主题 默认浅蓝色的主题比较好看吧"。默认使用浅蓝清爽主题，不要做深色/黑色主题。

启动

pip install flask plotly
python scripts/web_server.py 5555
# 浏览器访问 http://localhost:5555

六个页面（2026-07-09）

| 路由 | 功能 | |------|------| | / | 仪表盘 — 自选股实时行情表 + 统计卡片 | | /chart | K线分析 — 报价 + K线图(MA5/MA20) + MACD/RSI 指标图（Plotly 交互式） | | /backtest | 策略回测 — 15种策略选择 + 收益曲线 + 买卖点 + 统计 + 交易明细（纯回测，不含预测） | | /predict | 策略预测 — 蒙特卡洛预测：方法论 + 场景切换器（乐观/中性/悲观 三选一，默认中性）+ 6周股价/资产预测卡片 + 高亮走势图 | | /portfolio | 投资组合 — 实际持仓管理：添加表单(支持名称搜索) + 汇总卡片(总成本/总市值/盈亏/收益率) + 持仓明细表(实时估值) | | /watchlist | 自选股管理 — 添加表单 + 列表 + 推送平台 |

股票名称模糊搜索（2026-07-08）

所有页面的股票输入框都支持名称/代码模糊搜索（不需要知道代码就能搜）。输入"茅台"→下拉显示"贵州茅台 600519 沪"，点击即自动跳转。

  • API：/api/search?q=<关键词> — 调用新浪 suggest3.sinajs.cn 接口，过滤只返回沪深A股（排除基金/港股/美股/牛熊证/指数）
  • 前端：输入框 class=stock-search + 300ms防抖 + 下拉列表(代码+名称+沪/深标签) + 点击自动提交表单
  • 缓存：搜索结果5分钟TTL（_search_cache）
  • 指数过滤：sh00*/sz39*开头的是指数，排除；代码去重保留A股

⚠️ 回测和预测分离（2026-07-08 用户要求）：/backtest 只做纯回测，/predict 独立做蒙特卡洛预测。两个页面共享策略选择器，通过"查看回测"/"查看预测"按钮互相跳转。

设计模式：Plotly plotly_white template + 浅蓝底 #f0f4fa + 白色卡片 + 蓝色点缀 #3b82f6 + Inter/JetBrains Mono 字体 + 柔和阴影。红涨绿跌（#ef4444 / #10b981）。详细设计规范见 references/frontend-design.md。

参考文件

  • README.md — 完整使用说明书（中文，含策略列表、快速开始、路线图）
  • references/api_reference.md — AkShare 常用API速查表（行情/财务/板块/资金/龙虎榜/融资融券）
  • references/network_proxy_workaround.md — 本机网络环境代理绕过方案 + Sina API 格式详解 + 数据源可靠性排序
  • references/frontend-design.md — Web 前端设计规范（浅蓝清爽主题 v4 + Plotly 配色 + v3→v4降级经验）
  • references/monte-carlo-prediction.md — 蒙特卡洛股价预测引擎设计文档（多因子漂移模型 + GBM模拟 + 资产预测逻辑 + 场景切换架构）
  • references/sina-search-api.md — 新浪股票搜索API文档（suggest接口 + 字段解析 + 过滤规则 + 前端搜索组件）
  • references/static-js-pattern.md — Flask静态JS模式（f-string模板中嵌入JS的转义灾难 + 静态JS + URL参数自启动解法）
  • references/directory-convention.md — 目录约定 + 删除安全铁律
  • templates/webhook_setup.md — 飞书/钉钉/企业微信/Telegram/邮件 推送平台配置指南

Common Pitfalls

  1. ⚠️ DELETION SAFETY：用户的技能位置 D:\GitHub\hermescn\skills/。任何 Remove-Item 目录前必须明确询问。先复制再确认。绝不用 -Recurse -Force。

  2. Hermes auto-discovers skills from AppData：技能文件的 GitHub copy 仅用于版本控制，真正的副本在 AppData。不要删 AppData 里的。

  3. Clash/代理阻断东财API：本机 Clash 代理会阻断 push2.eastmoney.com 系域名。所有脚本已内置 _check_and_fix_proxy() 多层 monkey-patch 自动绕过。详见 references/network_proxy_workaround.md。

  4. 新浪API需要 Referer：hq.sinajs.cn 必须设置 Referer: https://finance.sina.com.cn 否则返回 403。

  5. AkShare接口频率限制：连续高频调用同一接口可能被限流。建议间隔≥1秒。

  6. 股票代码格式：6位纯数字代码（如 000001）。60xxxx=沪市主板、00xxxx=深市主板、30xxxx=创业板、68xxxx=科创板、8xxxxx/4xxxxx=北交所。

  7. 复权方式：adjust 参数 — qfq(前复权,默认)、hfq(后复权)、""(不复权)。

  8. 数据持久化已迁移到SQLite：新数据全部存入 ~/.hermes/a-stock/a-stock.db。

  9. mplfinance中文显示：图表中文字体需设置 matplotlib.rcParams['font.sans-serif'] = ['SimHei']。

  10. Web服务器启动：python scripts/web_server.py 5555。验证 Invoke-WebRequest -Uri 'http://localhost:5555/'。

  11. 数据字段名称变更：AkShare版本更新后字段名可能变化，如遇 KeyError 检查版本。

  12. Python 3.11 f-string 反斜杠限制：在 f-string {...} 内不能包含反斜杠。需嵌入含引号的 HTML 时先赋变量再引用。

  13. ⚠️ f-string中嵌入JS = 灾难（2026-07-09 血的教训）：当 content = f"""<script>...</script>""" 模板里需要写大量 JS（特别是包含 fetch、onclick、DOM 操作、事件委托的代码）时，Python f-string 的 {{ }} 转义和 JS 的 {} 花括号、引号嵌套会反复冲突，导致浏览器报 Unexpected token 或函数调用 undefined。正确做法：把所有 JS 逻辑写成独立的 static/xxx.js 文件，Python 模板只输出 <script src="/static/xxx.js"></script> 和必要的 HTML 骨架。JS 文件通过 URLSearchParams 从 URL 读取参数自启动。Flask 配置：static_folder='static'，静态文件放在 scripts/static/ 目录下。详见 references/static-js-pattern.md。

  14. ⚠️ f-string 中嵌套 jsonify 双花括号问题：注入的路由函数体中 jsonify() 的花括号必须是单层 { }。f-string 模板内的 <select> options 必须在 f-string 之前预计算成变量。

  15. ⚠️ regex脚本替换产生重复函数定义（严重bug）：多次运行注入脚本会导致同名 def 出现两次——后者静默覆盖前者，新功能看似写入但运行时不生效。排查：code.count('def name') > 1。预防：每次注入前先检查函数名是否已存在。

  16. SKILL.md BOM字符问题：skill_manage(action='patch') 报错可能是文件开头有BOM字符。用 skill_manage(action='edit') 全量重写可解决。

  17. ⚠️ Over-patch灾难（2026-07-09）：用多个临时Python脚本连续 over-patch 同一个代码文件时，每次脚本缺陷会累积污染文件，最终导致不可逆损坏（如 web_server.py 从85KB截断到32KB）。规则：(1) 每个补丁前先确认文件在git中，git checkout -- <file> 可以干净恢复；(2) 单次会话只保留一个活动补丁脚本；(3) 如果 patch 后验证失败（py_compile 不过），git reset --hard HEAD 而不是继续堆补丁；(4) CRLF安全写入：用 open(path, 'r', encoding='utf-8', newline='') 读 + open(path, 'w', encoding='utf-8', newline='') 写，这样 Python 不会自动转换 \r\n↔\n，补丁字符串中显式用 \r\n 匹配即可。比 binary mode 更简单（不需要手动 decode/encode）；(5) 临时 _*.py 脚本用完后必须 Remove-Item 清理。详见 hermes-windows-tooling skill pitfall #7-#8。⚠️ patch工具的 CRLF 陷阱：patch(mode='replace') 对含中文的 Windows 文件（纯 \r\n）经常匹配失败，因为 old_string 用 \n 而文件用 \r\n。解法：写独立 Python 脚本用 newline='' 读写。

  18. ⚠️ f-string变量引用的JS必须包裹<script>标签（2026-07-09）：在 render_page() 的 f-string 中用 {SEARCH_JS} 引用一个纯JS字符串变量时，输出到HTML的是裸JS文本（没有 <script></script> 包裹），浏览器将其当作纯文本渲染——每个页面底部都会显示一大段JS代码。正确做法：变量定义时首尾加 <script> 和 </script>：SEARCH_JS = '''<script>\nfunction ...()\n</script>'''。

  19. ⚠️ SQLite表结构变更需DROP+CREATE（2026-07-09）：通过补丁脚本给 _init_tables() 添加新表定义（如 portfolio）后，如果数据库文件已存在且旧表已创建，CREATE TABLE IF NOT EXISTS 不会更新旧表结构——新加的列（如 type）不存在，导致 OperationalError: table portfolio has no column named type。修复：用 conn.execute('DROP TABLE IF EXISTS portfolio') + 重新 CREATE TABLE 强制重建。注意：这会清空该表数据，仅在表为空或可重建时使用。

  20. ⚠️ str.find('")') 在三引号字符串中误匹配（2026-07-09）：当代码文件包含 conn.executescript("""...SQL DDL...""") 时，用 code.find('")') 定位闭合位置会匹配到 SQL 内容内部的 ") 而非三引号闭合的 """)，导致插入位置错误、SQL DDL 被截断、后续中文 docstring 暴露到代码区。正确做法：搜索 code.find('""")') （三引号+括号），而非 code.find('")')。

  21. ⚠️ 资产预测空仓默认假设满仓1万（2026-07-09）：predict_future_prices() 中，当回测引擎返回 last_equity=0（策略空仓）时，所有资产预测显示 ¥0。修复：last_eq 默认值设为 10000.0（假设满仓1万元），hold_shares = 10000 / last_price；仅当引擎实际持仓 engine_eq > 0 时才用引擎的 equity 值。position_basis 字段标注 "假设满仓1万" 或 "策略持仓"。

  22. CSS大块替换用 repr() 避免三引号嵌套（2026-07-09）：用Python脚本替换 web_server.py 中的整个 CSS 块时，CSS = """...""" 内部不能再用 """ 嵌套。技巧：把CSS行存为 list，new_css = 'CSS = ' + repr('\n'.join(css_lines))。repr() 会自动处理引号转义，生成的赋值语句语法正确。

Verification Checklist

  • [ ] pip install akshare pandas mplfinance matplotlib flask plotly 成功
  • [ ] python scripts/stock_cli.py spot 000001 返回平安银行实时行情
  • [ ] python scripts/stock_cli.py chart 000001 --days 30 生成K线图PNG
  • [ ] python scripts/stock_cli.py screen --change 3 返回筛选结果
  • [ ] python scripts/stock_monitor.py add 000001 --rule change_percent --threshold 3 添加成功
  • [ ] python scripts/stock_monitor.py check 执行无报错
  • [ ] K线图红涨绿跌（中国习惯）
  • [ ] python scripts/strategy.py backtest 000001 --strategy ma --days 60 输出回测统计
  • [ ] python scripts/strategy.py compare 000001 --days 180 输出15种策略对比
  • [ ] python scripts/watchlist.py add 000001 --price 10.5 --direction below 添加自选股成功
  • [ ] python scripts/db.py stats 显示数据库统计
  • [ ] python scripts/web_server.py 5555 启动后 http://localhost:5555/ 返回仪表盘（浅蓝清爽主题 + 白色卡片）
  • [ ] 仪表盘/K线/回测/预测/投资组合页面的输入框输入"茅台"能下拉显示"贵州茅台 600519"
  • [ ] /predict 页面显示三场景切换器（乐观/中性/悲观），默认中性，点击切换图表高亮
  • [ ] /backtest 页面只显示纯回测（统计+图表+交易明细），不含预测内容
  • [ ] /portfolio 页面可添加/删除持仓，自动实时估值
  • [ ] static/predict.js 正常加载（非 inline JS）
  • [ ] 页面底部不显示裸JS代码（SEARCH_JS被<script>标签正确包裹）
  • [ ] /portfolio 页面持仓表有正确的type列（SQLite表结构匹配）
  • [ ] 资产预测不为¥0（空仓时默认假设满仓1万）
  • [ ] python scripts/market_init.py stats 显示产品目录统计（A股5529+退市357+ETF1594+可转债320≈7800条）
  • [ ] python scripts/market_init.py search 茅台 从本地SQLite返回"贵州茅台 600519"
  • [ ] python scripts/market_init.py new --days 30 显示最近上市新股
  • [ ] python scripts/stock_cli.py search 芯片 --limit 3 从本地SQLite返回ETF结果
  • [ ] python scripts/market_init.py update 增量更新执行无报错（首次更新0变更）