npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

stock-analysis-plugin

v0.2.15

Published

Pi Agent extension for stock analysis, screening, and strategy backtesting across A/HK/US/JP/KR/TW markets

Readme

stock-analysis-plugin

npm PyPI License: MIT Python

给 AI Agent 用的股票研究工具箱,覆盖 A 股、港股、美股、日股、韩股、台股。装进你常用的 Agent 后,直接用自然语言查行情、做个股分析、全市场选股、写策略回测、做盘后复盘。

同一套 Python 工具同时支持 Pi Agent、Hermes Agent、OpenClaw、DeepSeek Harness (dsh),也能作为 MCP 服务器接入 Claude Desktop、Cursor、WorkBuddy。

dsh 股票仪表盘:六市场自选股行情、指数带、A 股涨跌分布与行业涨跌榜

dsh Web / Desktop 中的「股票仪表盘」,真实行情截图。

能做什么

  • 个股分析:「帮我分析贵州茅台」——行情、技术面、财务、资金流、新闻与舆情汇总成一份研报,并标注哪些数据缺失或过期。
  • 全市场选股:「A 股里找 PE < 30、市值 > 100 亿的成长股」——多因子硬筛,再由模型排序给出候选。
  • 策略回测:用 YAML 描述买卖条件,回测、诊断,按需调参。
  • 盘后复盘:指数、涨跌家数、板块轮动、涨停池、龙虎榜和市场情绪温度。
  • 价值投资数据:估值分位、股息、股东结构、ETF 折溢价、财报日历、公告,以及美股 SEC 13F / Form 4。
  • 持仓与风控:组合集中度、压力测试、调仓计划和仓位计算;只计算你本次传入的数据,不保存账户。
  • 策略视角:缠论、波浪理论、龙头战法、情绪周期等 18 套方法论,以 Skill 形式按需调用。
  • dsh 仪表盘:在 dsh Web / Desktop 侧栏看自选股和六个市场的行情,后台预热,打开即显示。

一共 75 个工具、21 个 Skills,11 个数据源自动容灾。大部分功能不需要任何 API Key。

快速开始

需要本机有 Python ≥ 3.10。插件安装时会在包目录下创建 .venv 并装好依赖;dsh 和 OpenClaw 默认不执行安装脚本,处理方法见下方注意事项。

| 你在用 | 安装 | 详细说明 | |--------|------|----------| | Pi Agent | pi install npm:stock-analysis-plugin | Pi 接入指南 | | Hermes Agent | pip install stock-analysis-plugin | Hermes 接入指南 | | OpenClaw | openclaw plugins install npm:openclaw-stock-analysis | OpenClaw 接入指南 | | DeepSeek Harness (dsh) | dsh plugin --profile <profile> add dsh-stock-analysis | dsh 插件说明 | | Claude Desktop / Cursor / WorkBuddy(MCP) | pip install stock-analysis-plugin,运行 stock-analysis-mcp | MCP 接入指南 |

每个 npm 包也以 @weaxs/ scoped 名发布(如 @weaxs/dsh-stock-analysis),内容一致。装的是 scoped 版时,配置里引用包名的地方也用 scoped 名。

装好后试试:

帮我分析贵州茅台(600519)
从 A 股中筛选低估值高成长的股票:PE < 30、PB < 5、市值 > 100 亿
用 RSI 超卖反弹策略回测茅台,时间段 2024 年全年
用缠论分析一下 600519 当前的走势结构
今天 A 股复盘

也可以显式调用 Skill,例如 /skill:stock-analysis、/skill:wave-theory。

各宿主的注意事项

Pi:加 -l 只装到当前项目,或直接 clone 源码使用。启动后输入 /skills 确认已加载。Pi 1.5.2 及以上提供原生 tool_search 时,插件只在命中时加载完整工具定义;可用中文关键词或工具名搜索,例如 实时行情、get_quote。

Hermes:通过 hermes_agent.plugins entry point 自动发现,无需复制目录;也可以在 Python 中 from hermes import register; register(ctx)。

OpenClaw:OpenClaw 安装 npm 插件时带 --ignore-scripts,不会自动建 .venv。装完后在插件目录(openclaw plugins inspect stock-analysis --runtime --json 的 installPath)运行一次 node scripts/setup-python.mjs。ClawHub 上只有 scoped 名:clawhub:@weaxs/openclaw-stock-analysis。

dsh:dsh 用 pnpm 安装插件,默认不执行第三方安装脚本。若 .venv 没有建起来,在 profile 的 pnpm-workspace.yaml 中给 dsh-stock-analysis 配置 allowBuilds,否则会回退系统 python3。新版 dsh 默认通过 stock_tool_search 按需加载工具,可用 toolDiscovery: false 关闭。

MCP:源码方式运行 .venv/bin/python mcp_host/server.py,或 python -m mcp_host。客户端配置示例见 MCP 接入指南。

dsh 股票仪表盘

装了 dsh 插件的 Web / Desktop 会在侧栏出现「股票仪表盘」:

  • 自选股行情表:最新价、涨跌幅、今日区间、成交额和 30 日走势,可排序、按市场筛选;最多 30 只,支持六个市场。
  • 市场概览:顶部六市场指数带和 A 股涨跌分布;下方可切换市场查看指数,A 股另有涨跌统计和行业领涨、领跌榜。
  • 打开即显示:插件在后台常驻预热行情,页面只读内存快照;交易时段约 30 秒更新一次。
  • 与 Agent 共享:Agent 可以用 get_watchlist 读取同一份自选股。

刷新节奏、数据来源和存储位置见 dsh 插件说明。

支持的市场

| 代码格式 | 示例 | 市场 | 行情报价 Failover 链(K 线差异见下方) | |----------|------|------|---------------------| | 6 位纯数字 | 600519, 000001, 300750 | A 股 | 腾讯 → 东方财富 → tushare → 新浪 | | 6 位纯数字(51/52/56/58/15/16/18 开头) | 510300, 159915 | A 股 ETF | 腾讯 → 东方财富 → tushare → 新浪 | | 带交易所前缀(sh/sz/bj + 6 位数字) | sh000001(上证指数), sz399006(创业板指) | A 股(显式指定,含指数) | 腾讯 → 新浪 | | .HK 结尾 | 00700.HK, 09988.HK | 港股 | yfinance → 腾讯 → finnhub → longbridge | | 英文字母 | AAPL, GOOGL, TSLA | 美股 | yfinance → finnhub → longbridge → 腾讯 → alphavantage | | .T 结尾 | 7203.T | 日股 | yfinance | | .KS / .KQ 结尾 | 005930.KS, 036020.KQ | 韩股 | yfinance | | .TW / .TWO 结尾 | 2330.TW, 6510.TWO | 台股 | yfinance |

各数据源按优先级自动尝试,失败后切换到下一个;未配置 API Key 的数据源自动跳过。A 股单票报价优先使用腾讯和新浪,不依赖东财域名,境外网络通常也能用。港股备用源、指数前缀、K 线复权口径等细节见 数据源与数据口径。

可选配置

不配置任何环境变量也能使用。下面这些配置后会加入容灾链,或启用搜索、舆情和 SEC 数据:

数据源(可选,配置后自动加入 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、A 股/港股非金融公司每日估值与 DCF 财报输入、港股财务(需对应权限) | | 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 密钥 |

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 | 检索机构研报、公告、电话会纪要和市场日报 |

工具列表

75 个工具按用途分组:

| 类别 | 数量 | 主要内容 | |------|------|----------| | 数据获取 | 29 | K 线、报价、基金净值、资金流、财务、板块、涨停池、龙虎榜、两融、估值历史、股东、ETF、股息、公告、SEC、CDS 指数 | | 分析计算 | 9 | 技术指标、K 线形态、量价、异动、信号胜率、趋势与行业轮动研究 | | 筛选与回测 | 8 | 多因子选股、风险筛查、策略回测、市场状态、日度复盘、自选股批量分析 | | 搜索与舆情 | 5 | 新闻搜索、综合情报、社交情绪、正文提取 | | 辅助 | 7 | 名称/拼音解析、交易日历、交易时段、数据源诊断、股票列表解析 | | 上下文与报告 | 8 | 自选股上下文、持仓分析、告警规则、信号记录与评估、研报渲染 | | 无状态研究与风险计算 | 9 | 同行比较、公告变更、组合风险、调仓计划、仓位计算、DCF 估值、事件研究、回测稳健性 |

数据获取

| 工具 | 说明 | |------|------| | get_announcements | A 股巨潮公告 / 港股 HKEXnews / 美股 SEC 申报:类别/日期范围/标题与原文链接;美股需 SEC_USER_AGENT | | get_us_holdings | SEC 机构组合 / 发行人 CIK 反查机构:精确 CUSIP 映射、季度数据与修订处理(需 SEC_USER_AGENT) | | get_insider_trades | SEC 股票 ticker/发行人 CIK 的 Form 4 内部人交易、代码和脚注 | | get_valuation_history | A/HK/US PE-TTM/PB 历史、正值分位与估值 Band,实际采样窗口(美股由 SEC 申报与周收盘派生) | | get_index_valuation | 中国指数 PE/PB 历史水位;中证官方多年滚动 PE;可选理杏仁补充 PB | | get_cds_index | 市场级 CDS 指数:中国在岸 CFETS-SHCH 指数期限曲线,或 DTCC 公开成交的 CDX/iTraxx 当前系列日中位数;窗口变化与分位,可按 index/tenor 只取单个指数和期限;非个股 CDS | | get_earnings_calendar | A 股报告期披露与业绩预告;HK 董事会排期;US/JP yfinance 预计日期(provider_only,非官方确认) | | get_shareholder_structure | A 股股东户数/十大流通股东变化/报告期北向名义持股;HK 南向持股 | | get_etf_details | A 股 ETF 净值折溢价、规模变动、披露持仓、可选基准成分与跟踪误差 | | get_dividends | A/HK/US/JP/KR/TW 历史分红与除息日历、已实现 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_fund_quote,TIAAxxxxxx 返回投顾组合识别、advisor_org 与无统一净值提示;长钱/海外长钱/稳钱另有有知有行 official_disclosures(partial=true,非实时完整持仓);其他组合搜索可用时为 search_partial,否则 unsupported_provider | | get_fund_quote | 6 位场外公募基金净值;nav 是 nav_date 对应的已披露日终净值而非实时价,accumulated_nav 为累计净值、change_pct 为日涨跌幅;estimated_nav 目前恒为 null(东方财富单只基金估值接口已下线),QDII 净值可能滞后 1-2 交易日 | | get_capital_flow | 资金流向(仅 A 股) | | get_news | 个股相关新闻 | | get_financials | 财务指标;可选追加 A/港/美股年度 DCF 输入 | | get_stock_info | 股票基本信息 | | get_chip_distribution | 筹码分布 | | get_market_indices | 主要指数行情 | | get_sector_rankings | 板块涨跌排行(A 股行业/概念;美股 SPDR 行业 ETF 代理) | | get_sector_constituents | 板块成分股查询(仅 A 股,板块名模糊匹配) | | resolve_stock_sectors | 个股所属板块查询(A 股行业+概念 / 港股 GICS) | | get_market_stats | 市场统计(A/HK/US 涨跌家数;成交额、涨停仅 A 股) | | 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、多期限趋势 trend_horizons、月度右侧趋势策略和市场环境入场实验均为 not_validated 的研究工具,公式、边界与验证局限见 工具行为与可靠性 · 趋势研究。

筛选与回测

| 工具 | 说明 | |------|------| | screen_stocks | 全市场多因子筛选(流动性使用成交额 turnover;可选 L2;factor_coverage 展示缺失因子与实际权重) | | screen_risk | 风险因子筛查 | | run_backtest | YAML 策略回测,默认收盘信号于次日开盘成交,execution 返回模型与限制 | | detect_market_regime | A/HK/US/JP/KR/TW 市场状态检测(返回实际 as_of 和警告;板块热点仅 A 股) | | get_market_review | 市场日度复盘数据 | | get_review_history | 复盘归档历史(最近 N 条,最新在前,用于纵向对比) | | get_watchlist | 读取 dsh 仪表盘自选股,按首选写法返回代码;600519 / sh600519 等价去重 | | run_watchlist_analysis | 批量自选股分析 |

搜索与舆情

| 工具 | 说明 | |------|------| | search_stock_news | 关键词搜索新闻 | | search_comprehensive_intel | 综合情报搜索 | | get_social_sentiment | 社交媒体情绪(A 股:东财股吧 + 雪球;美港股:Reddit / X / Polymarket) | | get_trending_sentiment | 社交媒体热门趋势聚合(Reddit / X / Polymarket) | | extract_article | 网页 / 公告 PDF 正文提取;max_chars 默认 3000、上限 200000,返回 truncated |

辅助

| 工具 | 说明 | |------|------| | resolve_stock_name | A/HK/US 中文股票名、拼音与代码模糊匹配;港美名录单市场失败可降级 | | check_trading_day | 查询是否交易日 | | get_trading_days | 获取前后 N 个交易日;日历未覆盖的推测日期单列 assumed_trading_days | | 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) |

批量分析的成功判定、信号存储与结算、风险筛查缺失值、选股与回测字段语义见 工具行为与可靠性。

无状态研究与风险计算

| 工具 | 说明 | |------|------| | compare_stocks | 比较显式输入的同行指标;检查单位、期间和口径,仅对可比数值排序 | | analyze_disclosure_changes | 比较新旧公告正文与财务指标,返回来源、变更行号和增长率限制 | | analyze_portfolio_risk | 一次性持仓的集中度、行业/币种敞口、价格盈亏、止损情景、可选相关性与市场/行业/个股/汇率压力测试 | | plan_portfolio_rebalance | 按目标权重、整手、费用和现金约束生成先卖后买的调仓计划,返回未满足数量与调后敞口 | | calculate_position_size | 按现金、风险预算、费用、滑点和交易单位计算本次可买数量 | | calculate_dcf_valuation | 按显式假设计算达摩达兰式 FCFF DCF、股权价值、每股价值与敏感性 | | analyze_event_study | 事件前一交易日收盘至各窗口的股票/基准收益差,标明缺失和重叠样本 | | validate_backtest | 复用现有引擎,滚动训练选候选、样本外验证,比较参数及多个标的 | | compare_analysis_snapshots | 比较调用方传入的快照,区分新增、删除、变化、数据失效和恢复 |

这些工具不保存自选股、账户或分析历史,也不提供调度/通知。输入格式、仓位预算示例与解读边界见 工具行为与可靠性 · 无状态研究。

字段语义、部分失败和缺失数据的处理方式见 工具行为与可靠性。

策略回测

策略用 YAML 描述,支持参数化和条件组合:

name: "RSI Oversold Bounce"
version: "1.0"
description: "RSI超卖反弹策略"

parameters:
  rsi_period: 14
  rsi_oversold: 30
  rsi_overbought: 70
  stop_loss: -0.05
  take_profit: 0.15

entry:
  conditions:
    - indicator: "rsi"
      period: "{rsi_period}"
      operator: "<"
      value: "{rsi_oversold}"
    - indicator: "volume_ratio"
      operator: ">"
      value: 1.0
  logic: "all"

exit:
  conditions:
    - indicator: "rsi"
      period: "{rsi_period}"
      operator: ">"
      value: "{rsi_overbought}"
  logic: "any"
  stop_loss: "{stop_loss}"
  take_profit: "{take_profit}"

position:
  size: 1.0
  max_positions: 1

可用指标包括 RSI、MA/EMA、MACD、量比、布林带位置、趋势强度和月度动量,运算符支持比较和 cross_above / cross_below。止损、移动止损、基准对比、成交口径和交易成本见 回测 DSL 参考,示例策略在 strategies/examples/。

独立 CLI 使用

不接 Agent 也能直接用,所有命令输出 JSON:

python tools/stock_data.py quote 600519
python tools/stock_data.py kline AAPL --period weekly --count 30
python tools/technical.py analyze 600519
python tools/screener.py screen --market A --top 20
python tools/backtest.py run strategies/examples/rsi_oversold.yaml 600519 --start 2024-01-01 --end 2025-01-01
python tools/market_regime.py detect A
# 行情数据
python tools/stock_data.py kline 600519
python tools/stock_data.py kline AAPL --period weekly --count 30
python tools/stock_data.py quote 600519
python tools/stock_data.py capital_flow 600519
python tools/stock_data.py news 600519 --days 5
python tools/stock_data.py financials AAPL

# 技术分析
python tools/technical.py analyze 600519
python tools/technical.py analyze AAPL --period weekly

# 全市场筛选
python tools/screener.py screen --market A --top 20
python tools/screener.py screen --market A --top 20 --l2
python tools/screener.py screen --market A --config my_filter.yaml

# 策略回测
python tools/backtest.py run strategies/examples/rsi_oversold.yaml 600519
python tools/backtest.py run strategies/examples/rsi_oversold.yaml 600519 --start 2024-01-01 --end 2025-01-01

# 搜索与舆情
python tools/search_intel.py search "茅台 业绩"
python tools/search_intel.py comprehensive 600519
python tools/search_intel.py sentiment 600519
python tools/search_intel.py sentiment AAPL
python tools/search_intel.py trending

# 风险筛查
python tools/risk_screening.py screen 600519

# 市场状态
python tools/market_regime.py detect A

# 估值、财报、股东、ETF 与分红
python tools/value_data.py valuation_history 600519 --years 5
python tools/stock_data.py financials 600519 --annual --periods 10
python tools/value_data.py earnings_calendar --report-date 2026-09-30 --symbol 600519
python tools/value_data.py shareholder_structure 600519 --report-date 2026-06-30
python tools/value_data.py shareholder_structure 0700.HK
python tools/value_data.py index_valuation 000300 --years 5
python tools/credit_data.py cds_index --source cn --days 30
python tools/value_data.py etf_details 510300 --benchmark sh000300 --days 60
python tools/value_data.py etf_details 510300 --include-full-holdings
python tools/stock_data.py margin_trading 600519 --days 10 --include-ratio
python tools/value_data.py dividends --symbol 600519
python tools/value_data.py dividends --symbol 0700.HK --mode calendar
python tools/value_data.py dividends --mode ranking --report-date 2025-12-31
python tools/value_data.py dividends --mode ranking --market HK --report-date 2025-12-31
python tools/value_data.py earnings_calendar --symbol 0700.HK

# 公告与港股长期财务
python tools/value_data.py announcements 600519 --category forecast --start-date 2026-01-01 --end-date 2026-10-13 --top 50
python tools/stock_data.py financials 0700.HK --annual --periods 10
python tools/value_data.py valuation_history 0700.HK --years 10

# SEC 13F / Form 4(SEC_USER_AGENT 必须配置为应用名称 + 你的真实联系邮箱)
python tools/sec_edgar.py holdings 0001067983
python tools/sec_edgar.py insider_trades AAPL --days 90 --top 10
python tools/sec_edgar.py holdings 0000320193 --mode issuer   # 发行人 CIK 反查持仓机构

常见问题

Python 工具报错 ModuleNotFoundError? 运行 pip install -r tools/requirements.txt。使用 virtualenv / conda 时,确保 Agent 启动时用的是同一个 Python 环境。

A 股数据获取失败? 报价会依次尝试腾讯、akshare、tushare、efinance 和新浪,K 线另有 baostock 兜底。都失败时,检查网络、升级 akshare(pip install --upgrade akshare),或配置 TUSHARE_TOKEN 增加一个可靠数据源。

港股 / 美股数据有延迟? yfinance 免费数据通常延迟约 15 分钟。配置 Longbridge(LONGBRIDGE_APP_KEY 等)或 Finnhub(FINNHUB_API_KEY)可获得更实时的数据。

如何自定义选股条件? 写一个 YAML,再运行 python tools/screener.py screen --config my_filter.yaml --top 30:

name: "我的选股策略"
filters:
  pe_min: 5
  pe_max: 25
  pb_max: 3
  market_cap_min: 20e9
sort_by: "composite_score"
sort_order: "desc"

如何编写回测策略? 参考 strategies/examples/ 和 回测 DSL 参考,也可以直接让 Agent 帮你写。

参与开发

所有业务逻辑都在 tools/*.py,每个工具是一个输出 JSON 的 CLI。pi/、hermes/、openclaw/、dsh/ 四个适配器只负责把宿主的工具调用转成子进程调用,mcp_host/ 复用 Hermes 的工具定义。Skills 放在 skills/*/SKILL.md,四个宿主共用。

npm install                                   # 同时构建仓库 .venv
.venv/bin/python -m pytest -q                 # Python 单元测试(离线)
npx tsc --noEmit                              # TypeScript 类型检查
npx tsx tests/test_adapter_parity.ts          # 四个宿主的 75 个工具和参数映射一致
npm run build:openclaw && npm run build:dsh   # 构建 OpenClaw / dsh bundle

开发约定、完整测试命令和跨平台注意事项见 AGENTS.md。

stock-analysis/
├── pi/                              # Pi Agent Extension
│   └── index.ts                     #   注册 75 个工具 + 21 个 skill
├── hermes/                          # Hermes Agent Plugin
│   ├── plugin.yaml                  #   插件清单
│   ├── __init__.py                  #   register(ctx) 入口
│   ├── schemas.py                   #   读取 tools/tool_schemas.json
│   └── tools.py                     #   75 个 handler → subprocess 调 CLI
├── openclaw/                        # OpenClaw Plugin
│   ├── openclaw.plugin.json         #   manifest(contracts.tools)
│   ├── package.json                 #   含 openclaw 块(pluginApi/SDK 版本)
│   └── index.ts                     #   definePluginEntry + 按共享 schema 注册
├── dsh/                             # DeepSeek Harness (dsh) Plugin
│   ├── cordis.patch.yml             #   bundle patch(insert 插件入口)
│   ├── package.json                 #   dsh.bundle + dsh.client manifest
│   ├── index.ts                     #   cordis apply(ctx) + 按共享 schema 注册
│   ├── dashboard.ts                 #   后台预热缓存 + 快照/自选股 HTTP API 与持久化
│   ├── client.ts                    #   侧栏入口 + 主面板 + 主题同步(编译为 dist/client.js)
│   └── web/                         #   仪表盘页面(app.ts 编译为 dist/web/app.js)
│
├── mcp_host/                        # MCP stdio 服务器(复用 Hermes schema/handler)
├── tools/                           # 共享 Python CLI 工具
│   ├── tool_schemas.json            #   75 个工具的名称/描述/参数(各宿主共用)
│   ├── stock_data.py                #   行情 / 资金流 / 新闻 / 财务 / 短线情绪
│   ├── signal_tracker.py            #   AI 买卖建议回测闭环(本地 JSONL 存储)
│   ├── technical.py                 #   技术指标分析
│   ├── pattern.py                   #   K 线形态识别
│   ├── value_data.py                #   估值/财报日历/股东/ETF/股息
│   ├── _cache.py                    #   用户目录 TTL 缓存
│   ├── screener.py                  #   全市场多因子筛选(含市场情绪调节,--l2 量化增强)
│   ├── backtest.py                  #   策略回测引擎
│   ├── volume_analysis.py           #   量价分析
│   ├── search_intel.py              #   搜索 / 舆情 / 正文提取
│   ├── risk_screening.py            #   风险因子筛查
│   ├── market_regime.py             #   市场状态检测
│   ├── name_resolver.py             #   股票名称模糊匹配
│   ├── trading_calendar.py          #   交易日历
│   └── requirements.txt
│
├── skills/                          # 共享 SKILL.md(21 个)
│   ├── stock-analysis/              #   综合分析 workflow
│   ├── stock-screener/              #   选股 workflow
│   ├── strategy-backtest/           #   回测 + 进化 workflow
│   └── ...                          #   18 个策略方法论
│
├── strategies/examples/             # 回测策略 YAML 示例
├── schemas/                         # JSON Schema(研报结构等)
├── tests/                           # pytest 测试
├── package.json                     # npm / Pi 配置
└── tsconfig.json

数据流:

用户 (自然语言)
    │
    ▼
Agent (Pi / Hermes / OpenClaw / dsh / MCP)
    │
    ├── 加载 SKILL.md → 分析框架 / 流程指引
    │
    ├── 调用工具 → pi/index.ts、hermes/tools.py、openclaw/index.ts、dsh/index.ts 或 mcp_host/server.py → python tools/xxx.py → JSON
    │
    ▼
Agent (LLM 分析 + 生成报告)
    │
    ▼
用户看到结构化分析结果
pip install -r tools/requirements.txt

主要依赖:

| 包 | 用途 | |---|------| | akshare | A 股数据源(行情、资金流、财务、新闻,含 A 股 ETF) | | yfinance | 港股 / 美股 / 日股 / 韩股 / 台股数据源 | | pandas / numpy | 数据处理和数值计算 | | exchange-calendars | 交易日历(A/HK/US/JP/KR/TW) | | newspaper4k / pypdf | HTML 新闻与公告 PDF 正文提取 | | pypinyin | 股票名称拼音搜索 | | longport | 港股 / 美股 Longbridge SDK |

.venv/bin/python -m pytest tests/test_analysis_quality.py -q
# 需要 OPENAI_BASE_URL / OPENAI_API_KEY / OPENAI_MODEL;只调用模型,数据源使用固定夹具
.venv/bin/python -m pytest tests/e2e/test_analysis_quality.py -m integration_llm -v

GitHub Actions 的 e2e-host 使用 Pi、Hermes、OpenClaw、dsh 的真实运行时执行工具调用。在仓库 Settings → Secrets and variables → Actions 中配置以下三项,所有 E2E 共用:

| 名称 | 存放位置 | 内容 | |---|---|---| | OPENAI_BASE_URL | Variable 或 Secret | OpenAI 兼容的 API base URL,包含服务商要求的路径(例如 /v1) | | OPENAI_API_KEY | Secret | 对应的 API key | | OPENAI_MODEL | Variable 或 Secret | 支持 tool calling 的模型 ID |

e2e-llm 也使用这三项配置,Hermes(含报告质量评测)、Pi、OpenClaw 和 dsh 通过四个 matrix 作业并行运行,互不因失败而取消;同仓库 PR 和主分支推送会运行,fork PR 不读取 API key。e2e-host 缺少任一项时会失败。URL 和 model 同时存在于 Variable 与 Secret 时,优先使用 Secret。

致谢

License

MIT