stock-analysis-plugin

stock-analysis-plugin

A 股 / 港股 / 美股 / 日股 / 韩股 / 台股综合分析、多因子选股和策略回测工具集，可作为 Pi Agent Extension、Hermes Agent Plugin、OpenClaw Plugin，或 DeepSeek Harness (dsh) Plugin 使用。

底层共享同一套 Python CLI 工具和 SKILL.md 工作流，上层分别适配四个平台的注册机制。

目录

• 功能概览
• 安装
• Pi Agent Extension
• Hermes Agent Plugin
• OpenClaw Plugin
• dsh (DeepSeek Harness) Plugin
• Python 依赖
• 快速开始
• Skills 一览
• 工具列表
• 策略回测 DSL
• 市场路由规则
• 独立 CLI 使用
• CI 真实宿主测试
• 项目结构
• 致谢
• 常见问题
• License

功能概览

• 70 个工具 — 行情数据、技术分析、K 线形态、资金流向、估值历史、财报日历、股东/ETF/股息、新闻舆情、风险筛查、市场状态等
• 21 个 Skills — 综合分析、全市场选股、策略回测 + 18 个策略、复盘与研究方法论（缠论、波浪、龙头、情绪周期等）
• 策略回测引擎 — YAML DSL 定义策略，参数化条件组合，自动诊断，按需进行有限轮参数优化
• 多数据源 Failover — 11 个数据源自动容灾切换（akshare / tushare / efinance / 腾讯行情 / 新浪行情 / pytdx / baostock / yfinance / finnhub / longbridge / alphavantage），A 股链路带粘性优选（最近成功的数据源下次优先尝试）
• 社交舆情增强 — A 股（东财股吧 + 雪球）/ 美港股（Reddit / X / Polymarket），市场自动路由
• 四平台适配 — 同一套工具同时支持 Pi Agent、Hermes Agent、OpenClaw 和 dsh

安装

所有 npm 包同时以 scoped（@weaxs/*）和非 scoped 同名两种名字发布，内容一致，任选其一即可。

插件包地址：

平台 · 包名 · 地址 · 安装命令 Pi Agent · @weaxs/stock-analysis-plugin（或 stock-analysis-plugin） · npm · npm install @weaxs/stock-analysis-plugin Hermes Agent · stock-analysis-plugin · PyPI · pip install stock-analysis-plugin OpenClaw · @weaxs/openclaw-stock-analysis（或 openclaw-stock-analysis） · npm · openclaw plugins install clawhub:@weaxs/openclaw-stock-analysis DeepSeek Harness (dsh) · @weaxs/dsh-stock-analysis（或 dsh-stock-analysis） · npm · dsh plugin --profile add @weaxs/dsh-stock-analysis

各平台的详细安装步骤见下方对应小节。

Pi Agent Extension

# 全局安装
cd ~/.pi/agent/extensions
npm install @weaxs/stock-analysis-plugin

# 或项目级安装
mkdir -p .pi/extensions && cd .pi/extensions
npm install @weaxs/stock-analysis-plugin

也可以直接 git clone git@github.com:Weaxs/stock-analysis-plugin.git 使用源码版本。

Pi 启动后自动加载，输入 /skills 确认。详见 Pi Agent 接入指南（English）。

新版 Pi（已核验 1.2.0）提供原生 tool_search 时，插件自动启用按需工具发现，70 项能力保留注册，仅命中工具加载完整定义。缺少原生发现接口的旧版 Pi 或 SDK 宿主保持全量暴露。检索使用英文关键词或工具名，例如 get_quote、get_financials。

Hermes Agent Plugin

pip install stock-analysis-plugin

安装后 Hermes 通过 hermes_agent.plugins entry point 自动发现并注册，无需手动复制目录。

或在 Python 中直接注册：

from hermes import register
register(ctx)

详见 Hermes Agent 接入指南（English）。

OpenClaw Plugin

openclaw plugins install clawhub:@weaxs/openclaw-stock-analysis

OpenClaw Gateway 启动后自动加载并注册 70 个 tool。安装时 postinstall 会自动建 .venv 并装好 Python 依赖（前提：本机有 python3 >= 3.10）。

详见 OpenClaw 接入指南，或 plugin 自身说明 openclaw/README.md。

dsh (DeepSeek Harness) Plugin

dsh plugin --profile <你的profile> add @weaxs/dsh-stock-analysis
dsh --profile <你的profile>

作为 dsh bundle 安装：dsh plugin add 会把 cordis.patch.yml 叠加进 profile 组合，注册 70 个 tool + 21 个 skill。postinstall 自动建 .venv（pnpm 需在 profile 的 pnpm-workspace.yaml 里给本包配 allowBuilds，否则回退系统 python3）。

新版 dsh 的原生函数调用模式默认通过 stock_tool_search 按 Agent 搜索、加载所需工具，支持中文关键词或工具名；旧接口、搜索入口不可用时保留全量暴露。可设置 toolDiscovery: false 关闭，配置与 PTC 模式边界见下方接入文档。

详见 dsh/README.md。

Python 依赖

pip install -r tools/requirements.txt

主要依赖：

包 · 用途 akshare · A 股数据源（行情、资金流、财务、新闻，含 A 股 ETF） yfinance · 港股 / 美股 / 日股 / 韩股 / 台股数据源 pandas / numpy · 数据处理和数值计算 exchange-calendars · 交易日历（A/HK/US/JP/KR/TW） newspaper4k · 新闻正文提取 pypinyin · 股票名称拼音搜索 pytdx · A 股 TDX 行情（免费兜底源） longport · 港股 / 美股 Longbridge SDK

A 股行情另有腾讯（qt.gtimg.cn）/ 新浪（hq.sinajs.cn）两个免鉴权兜底源，直接 HTTP 调用，用于东财域名不可达的网络环境（境外主机、企业出网限制等）。港股实时行情也使用腾讯作为 yfinance 之后的免 key 备用源。

环境变量

数据源（可选，配置后自动加入 Failover 链）：

环境变量 · 用途 TUSHARE_TOKEN · Tushare 数据源（A 股 K 线 / 行情） LONGBRIDGE_APP_KEY · Longbridge SDK（港股 / 美股） LONGBRIDGE_APP_SECRET · Longbridge SDK LONGBRIDGE_ACCESS_TOKEN · Longbridge SDK ALPHAVANTAGE_API_KEY · Alpha Vantage（美股 K 线 / 行情） FINNHUB_API_KEY · Finnhub（港股 / 美股） XUEQIU_TOKEN · 雪球（A 股个股所属板块反查，东财不可用时的兜底）

搜索引擎（可选，配置任一即可）：

环境变量 · 用途 LIXINGER_TOKEN · 理杏仁可选数据源：指数 PB 与港股非金融公司财务/每日估值（需对应权限） SEC_USER_AGENT · SEC EDGAR 身份声明：应用名称与真实联系邮箱，13F/Form 4 必需 TAVILY_API_KEY · Tavily 搜索 BRAVE_API_KEY · Brave 搜索 SERPAPI_KEY · SerpAPI BOCHA_API_KEY · Bocha AI 搜索 SEARXNG_BASE_URLS · SearXNG 自建实例地址（逗号分隔多个，无需 Key，兜底用）

社交舆情（可选）：

环境变量 · 用途 SENTIMENT_API_URL · 舆情 API 地址（默认 https://api.adanos.org） SENTIMENT_API_KEY · 舆情 API 密钥

快速开始

综合分析

/skill:stock-analysis

帮我分析贵州茅台（600519）

Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息面，输出多维度研报。

全市场选股

/skill:stock-screener

帮我从 A 股中筛选出低估值+高成长的股票，要求 PE < 30、PB < 5、市值 > 100 亿

策略回测

/skill:strategy-backtest

用 RSI 超卖反弹策略回测茅台，时间段 2024 年全年

特定策略视角

/skill:chan-theory
用缠论分析一下 600519 当前的走势结构

/skill:wave-theory
用波浪理论分析 AAPL 的浪形位置

Skills 一览

核心 Workflow（3 个）

Skill · 调用方式 · 功能 综合分析 · /skill:stock-analysis · 技术面 + 基本面 + 资金面 + 消息面多维研判，输出结构化研报 全市场选股 · /skill:stock-screener · L1 多因子硬筛（市场情绪调节，可选 --l2 量化增强）→ L2 LLM 智能排序 → 输出推荐列表 策略回测 · /skill:strategy-backtest · YAML 策略定义 → 回测 → 诊断；按需进行最多 3 轮参数优化

策略、复盘与研究（18 个）

Skill · 调用方式 · 方法论 趋势追踪 · /skill:bull-trend · 均线排列 + MACD 方向 + 趋势阶段判断 缩量回调 · /skill:shrink-pullback · 上升趋势中的缩量洗盘识别 均线金叉 · /skill:ma-crossover · MA5/10/20/60 交叉信号 + 金叉质量评估 放量突破 · /skill:volume-breakout · 关键阻力位的放量突破确认 底部放量 · /skill:bottom-volume · 底部区域异动放量 → 主力建仓信号 龙头战法 · /skill:dragon-head · 板块龙头识别 + 龙头 vs 跟风判断 缠论 · /skill:chan-theory · 笔 → 段 → 中枢 → 背驰 → 买卖点 波浪理论 · /skill:wave-theory · Elliott 5 浪推动 + 3 浪调整 + 斐波那契 箱体震荡 · /skill:box-oscillation · 箱体区间识别 + 支撑压力间波段操作 情绪周期 · /skill:emotion-cycle · 市场情绪冰点 → 回暖 → 狂热 → 退潮周期判断 一阳穿三阴 · /skill:one-yang-three-yin · K 线形态识别 + 反转信号质量评级 事件驱动 · /skill:event-driven · 公告/政策/业绩事件的影响路径与失效条件 预期重估 · /skill:expectation-repricing · 市场预期与实际数据的偏差 成长质量 · /skill:growth-quality · 收入、利润、现金流与盈利能力的多期验证 行业 ETF 轮动研究 · /skill:sector-rotation · 确定性集中度/配权计算、跨市场分组的配权分项回测；完整深度模型尚未实现 热点题材 · /skill:hot-theme · 板块强度、扩散度、关联度与节奏 市场复盘 · /skill:market-review · 指数、宽度、板块、温度与次日策略 Wisburg 投研 · /skill:wisburg-research · 检索机构研报、公告、电话会纪要和市场日报

工具列表

数据获取

工具 · 说明 get_announcements · A 股巨潮公告查询：类别/日期范围/标题/原文 PDF 链接 get_us_holdings · SEC 机构组合 / 发行人 CIK 反查机构：精确 CUSIP 映射、季度数据与修订处理（需 SEC_USER_AGENT） get_insider_trades · SEC 股票 ticker/发行人 CIK 的 Form 4 内部人交易、代码和脚注 get_valuation_history · A/HK PE-TTM/PB 历史、正值分位与估值 Band，实际采样窗口 get_index_valuation · 中国指数 PE/PB 历史水位；中证官方多年滚动 PE；可选理杏仁补充 PB get_earnings_calendar · A 股报告期披露与业绩预告；HK 已公告业绩审批董事会排期／供应商备选日期 get_shareholder_structure · A 股股东户数/十大流通股东变化/报告期北向名义持股；HK 南向持股 get_etf_details · A 股 ETF 净值折溢价、规模变动、披露持仓、可选基准成分与跟踪误差 get_dividends · A/HK 历史分红/除息日历/已实现 TTM 股息与连续年数；A/HK 报告期/年度排行 get_kline · K 线数据（OHLCV），支持日/周/月线；A 股股票/ETF 前复权，每条记录 adjusted=qfq，指数 adjusted=none get_quote · 实时行情快照（非交易时段返回最近交易日收盘价并以 as_of/stale 标注；pe_basis 区分 dynamic/trailing/unknown；ETF 的 premium_discount_rate 为正=溢价、负=折价） get_capital_flow · 资金流向（仅 A 股） get_news · 个股相关新闻 get_financials · 财务指标 get_stock_info · 股票基本信息 get_chip_distribution · 筹码分布 get_market_indices · 主要指数行情 get_sector_rankings · 板块涨跌排行（行业/概念） get_sector_constituents · 板块成分股查询（仅 A 股，板块名模糊匹配） resolve_stock_sectors · 个股所属板块查询（A 股行业+概念 / 港股 GICS） get_market_stats · 市场统计（涨跌家数、涨停等） get_limit_up_pool · 涨停池/涨停板复盘（连板数、封板资金、炸板次数等，仅 A 股；非交易日自动回退到最近交易日并以 requested_date/stale 标注） get_dragon_tiger · 龙虎榜（净买额/上榜原因/解读，仅 A 股；非交易日自动回退到最近交易日并以 requested_date/stale 标注） get_hot_stocks · 全市场人气热搜榜（东财→百度，仅 A 股） get_margin_trading · 个股融资融券明细（融资余额/融资买入额/融券余量等，沪深交易所官方数据，仅 A 股两融标的；金额单位为元，short_*_shares 单位为股） get_northbound_flow · 北向资金市场级净买入序列（东财沪深港通历史数据；2024-08-16 起交易所停止披露日度净买额，仅 2024-08 之前历史数据可查，仅 A 股） get_fundamental_context · 基本面综合上下文

分析计算

工具 · 说明 calculate_rotation_metrics · 真实MC-dropout分布集中度与历史原始配权计算；不生成预测或买入信号 backtest_rotation_allocation · 股票/ETF代码自动取数，按市场与报价币种独立比较等权和历史配权；分项回测，非完整论文模型 analyze_trend_strategy · 月度右侧趋势策略：单市场股票池筛选、真实旧仓保持/退出与逆波动新仓预算；直接传股票代码、自动取行情，无持仓存储，仍为not_validated get_technical_analysis · 全面技术指标分析（MA/MACD/RSI/BOLL/KDJ；附实验性 trend_horizons 多期限月度趋势及独立趋势温度 trend_temperature；多周期共振时 resonance.direction ∈ aligned_bullish/aligned_bearish/divergent） analyze_pattern · K 线形态识别 calculate_ma · 多周期均线计算 get_volume_analysis · 量价分析 evaluate_signal · 历史信号胜率回测 detect_anomaly · 当日技术、量价与资金异动扫描

trend_temperature 是独立趋势温度指标：(EMA20-EMA60)/ATR14，ATR 使用包含跳空的真实波幅简单均值。附分数、EMA差方向 direction、七档研究标签、前一期信息、数据日期和价格口径；validation_status=not_validated，真实股票试验未支持默认温度交易映射。方向按零轴计算，“平”标签不代表零方向；默认需 60 根预热，零 ATR 或坏行情返回不可用。±0.5/±1.5/±3 的分档尚未校准，不是趋势动物公式、肥尾指标、上涨概率或自动买卖信号，也不修改原综合评分。无需个人持仓存储；公式、边界及回测说明。

月度右侧趋势策略，通过 analyze_trend_strategy(symbols, ...) 调用：月初200日线上行入场、真实旧仓优先、63日波动预算；输入格式与完整规则。扩展及历史样本尚未通过完整效果门槛；直接提供股票代码即可自动取日K，输出信号与预算计划；实际成交/股数和共享资金回测另行核实，不自动保存持仓或下单。

趋势研究另返回 trend_horizons（daily、建议count=360）：21/63/252根日K过去对数收益，在月初首根有效日K收盘观察并保持；显示期限组成、方向及观察日期，不强凑七档。与回测 monthly_momentum 共用计算，仍为 not_validated；方法、预热与验证局限。

市场只约束新开仓的三期限实验可运行 market_trend.py，输入带预热的个股/同市场宽基daily OHLCV JSON，复用同一Python核心。月度入场、次日开盘、已有持仓按个股趋势退出；不会自动保存持仓或下单。使用与当前验证边界。

筛选与回测

工具 · 说明 screen_stocks · 全市场多因子筛选（可选 L2；factor_coverage 展示缺失因子、覆盖度、实际权重及 L2 effective_scores） screen_risk · 风险因子筛查 run_backtest · YAML 策略回测，默认收盘信号于次日开盘成交，execution 返回模型与限制 detect_market_regime · 市场状态检测（牛/熊/震荡；返回实际 as_of 和坏行警告，历史不足 60 根时 above_ma60=null） get_market_review · 市场日度复盘数据 get_review_history · 复盘归档历史（最近 N 条，最新在前，用于纵向对比） run_watchlist_analysis · 批量自选股分析

搜索与舆情

工具 · 说明 search_stock_news · 关键词搜索新闻 search_comprehensive_intel · 综合情报搜索 get_social_sentiment · 社交媒体情绪（A 股：东财股吧 + 雪球；美港股：Reddit / X / Polymarket） get_trending_sentiment · 社交媒体热门趋势聚合（Reddit / X / Polymarket） extract_article · 网页正文提取

辅助

工具 · 说明 resolve_stock_name · 股票名称 / 拼音模糊匹配 check_trading_day · 查询是否交易日 get_trading_days · 获取前后 N 个交易日 get_trading_phase · 查询市场当前交易时段（盘前/盘中/盘后/休市） diagnose_data_sources · 诊断数据源、环境变量和市场链路 get_market_capabilities · 查询各市场支持的工具边界 parse_stock_list · 从自然语言、CSV 或 Markdown 解析股票列表

上下文与报告

工具 · 说明 build_watchlist_context · 构建自选股摘要与后续工具建议 analyze_position_context · 结合成本、仓位与止损止盈分析持仓 check_alert_rules · 无状态检查价格、涨跌幅、异动和风险规则 record_signal · 记录 AI 分析建议信号（本地 JSONL 持久化） evaluate_signals · 评估到期信号（target_hit/stop_hit/timeout 结算） get_signal_summary · 信号胜率及分来源平均收益、有效收益样本数与小样本提示（按 source/symbol/status 过滤） render_stock_report · 将结构化个股报告渲染为 Markdown，展示 evidence 与 data_quality 限制 render_market_report · 将结构化市场复盘渲染为 Markdown（save=true 时归档到本地 JSONL）

批量自选股分析和摘要的 success 表示至少获取了有效行情价格、K 线收盘价或技术评分；全部关键数据失败时计入 failed，部分结果仍保留。采集脚本复用返回的 K 线计算技术指标，并按股票所属市场查询大盘状态；日/韩/台市场状态暂不可用，非 A 股板块榜单也暂不可用，均会明确返回错误。

信号记录支持同一存储文件的多进程读写；评估期间新增的信号会保留。价格必须为正的有限数值，持有期限为正整数，日期格式为 YYYY-MM-DD。存储文件含损坏 JSON 行或无效信号时，记录、评估和汇总返回错误，原文件保持原样。

信号评估仅在历史 K 线覆盖记录日时结算，缺少历史窗口则返回 skipped_no_data 并保持未结算。风险筛查返回 data_complete 和 warnings；数据不足时评级可为 unknown，risk_score、veto_buy 可为 null。告警的 evaluated 条目含 error 时表示无法检查，不能将未触发理解为已通过检查。

选股的 filters_applied 只列实际执行的条件，显式条件缺少数据时报错。回测的 period 是实际数据期间，requested_period 保留请求期间，warnings 提示覆盖差异；买入预算包含佣金，年化收益和回撤按实际数据及初始资金计算。