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

功能概览

• 57 个工具 — 行情数据、技术分析、K 线形态、资金流向、估值历史、财报日历、股东/ETF/股息、新闻舆情、风险筛查、市场状态等
• 20 个 Skills — 综合分析、全市场选股、策略回测 + 17 个策略方法论（缠论、波浪、龙头、情绪周期等）
• 策略回测引擎 — 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 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）。

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 启动后自动加载并注册 57 个 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 组合，注册 57 个 tool + 20 个 skill。postinstall 自动建 .venv（pnpm 需在 profile 的 pnpm-workspace.yaml 里给本包配 allowBuilds，否则回退系统 python3）。

详见 dsh/README.md。

Python 依赖

pip install -r tools/requirements.txt

主要依赖：

A 股行情另有**腾讯（qt.gtimg.cn）/ 新浪（hq.sinajs.cn）**两个免鉴权兜底源，不依赖任何 Python 包（直接 HTTP 调用），用于东财域名不可达的网络环境（境外主机、企业出网限制等）。

环境变量

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

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

社交舆情（可选）：

快速开始

综合分析

/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 个）

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

工具列表

数据获取

分析计算

筛选与回测

搜索与舆情

辅助

上下文与报告

策略回测 DSL

策略以 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

其他可用键：

• exit.trailing_stop：移动止损，价格自持仓期间最高收盘价回撤达到该比例即卖出（如 0.08 = 峰值回撤 8% 触发）；与 stop_loss 同时设置时先判固定止损。
• benchmark（顶层）：基准对比标的代码（如 "sh000300" 沪深300；指数代码必须带 sh/sz 交易所前缀，裸 6 位数字会被当作个股），设置后回测结果附带 benchmark 块（基准买入持有收益与 excess_return 超额收益）。
• simulation（顶层）：交易成本。slippage（滑点，买卖双边，默认 0.001）、commission（佣金，买卖双边，默认 0.0015）、stamp_tax（印花税，仅卖出收取，默认 0；A股为 0.0005，各市场税率不同且会调整，按当下实际费率填写）。费率均须在 [0, 1) 区间，越界报错。回测结果附带 costs 块（实际生效费率与实付费用合计 commission_paid/stamp_tax_paid）。

可用指标

可用运算符

> < >= <= == cross_above（上穿） cross_below（下穿）

示例策略见 strategies/examples/。

市场路由规则

各数据源按优先级自动尝试，前一个失败后自动切换到下一个。未配置相关 env var 的数据源会被跳过。 裸 6 位代码一律按个股处理（000001 是平安银行）；指数需带交易所前缀（sh000001 = 上证指数），显式前缀代码直接走腾讯/新浪（东财源只认裸代码）。 A 股 K 线口径：股票/ETF 仅接受前复权数据，链路为 akshare → tushare（仅股票）→ efinance → 腾讯（仅 qfq 数据）→ baostock；带前缀的股票/ETF 先去前缀再走同一链路。新浪和 pytdx 的未复权 K 线不参与股票/ETF 容灾。显式指数 sh000xxx / sz399xxx 保留原始点位，走腾讯 → 新浪 → baostock。上述路由表的完整链路仍适用于实时行情。 K 线响应保留原有 JSON 数组，每条 A 股记录新增 adjusted：股票/ETF 为 "qfq"，指数为 "none"。Tushare 日线通过 adj_factor 前复权，周/月线使用 stk_week_month_adj 的 qfq 字段；复权权限不足、因子缺失或源只返回原始价格时继续切换，所有可用复权源都失败时返回 JSON error，不降级到未复权股票价格。Tushare 复权接口需至少 2000 积分，见复权因子与复权周/月线。 粘性优选：A 股链路（K 线 / 行情 / 市场快照 / 板块成分）会记住最近一次成功的数据源（缓存在系统临时目录，24h 有效），下次调用优先从它开始；若它已失效则自动顺延并更新记录。港美股链路不做粘性——一次 yfinance 瞬时失败不应让后续全天的 quote 降质。 日/韩/台股仅 yfinance 一个数据源（免费数据延迟约 15 分钟）；港股 / 美股 / 日股 / 韩股 / 台股的 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/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

财报、基本信息及估值/股东/ETF/分红等慢变数据缓存到 ~/.stock-analysis/cache，TTL 一天；板块成分/映射一周。行情报价不缓存。缓存文件原子替换，过期/损坏重拉，错误和显式部分失败不缓存；不以过期数据伪装最新数据。原有临时目录的粘性路由和反向成分缓存保留。

估值使用可得数据的正值样本分位（<=当前值），返回 10/25/50/75/90 分位 Band 与实际起止日期；亏损 PE 分位为 null。当前 AKShare 已无 issue 中提到的 stock_a_indicator_lg，个股采用百度 PE-TTM/PB 历史，指数采用乐咕乐股；中证全指等通过中证官方历史接口取得多年滚动 PE，近期总股本 PE1 仍单独保留；PB 缺失时可配置 LIXINGER_TOKEN 补充理杏仁总市值加权（mcw）历史，返回每个指标的来源与口径，不拼接不同方法的同一指标。未配置或无权限时 PB 保持未知。A 股 annual=true, periods=10 请求十年年报；HK 按源实际可得年数返回，不补造缺失比率。

股东数据保留报告期、公告日或港交所披露日：A 股北向优先返回沪深交易所披露的季度合计数量，省略报告期时查最新已公布季度；十大流通股东中的 HKSCC 推断保留在 northbound_nominee，仅作明确标注的兜底，缺席不是零；HK 南向取自港交所 Stock Connect CCASS 记录，不等同完整实益股东名册。A 股财报预约/修订是计划，业绩预告是已公告预估，不是实际业绩。HK 单股优先使用 HKEX 主板/GEM 已公告业绩审批董事会排期，标记 confirmation=official_board_meeting_notice、date_kind=scheduled_board_meeting；这是计划会议日，不是实际披露日。可按已知财政期末过滤；找不到匹配公告时保留 Yahoo 供应商未来排期，confirmation=provider_only，未知报告期不归入指定期次，而另列 unverified_schedules。日期转为香港日期，公告表也不承诺覆盖所有港股。

ETF 使用披露资产规模历史（元）与披露持仓，保留持仓原始证券代码，不冒充实时完整申赎篮子；新增 basket 返回沪深交易所发布的完整当日 PCF（跨境代码原样保留），包含申赎单位、每篮子证券数量、现金替代规则与比例；校验基金代码、实际日期和全部组件数量，失败只提示不可用，不冒充完整。PCF 是申赎对价，不是实际持仓，证券数量也不是净值权重。include_full_holdings=true 时另取最近可得半年度/年度披露股票表，显式指定年份/月并请求较高行数上限，包含股票数量（股）、市值（人民币元）和实际报告期；返回全部收到的表格行，但不声称覆盖债券/现金等全资产或实时持仓，也不以 PCF 数量验证实际持仓。默认不取数百行明细。提供 benchmark 可另查基准指数成分。净值折溢价仅在行情/净值日期相同才计算，IOPV 折溢价另列。跟踪误差使用相同连续交易日区间的基金日净值增长与基准收盘收益差，取样本标准差乘 sqrt(252)，不填补缺失日期、不猜测基准。两融占比只匹配同一天的人民币元成交额，缺失则 null。

股息历史将预案与已实施分红分开，TTM 股息率以过去365天已实施名义每股现金/最新价计算（税前，未重算送转股）；空历史、已实施记录缺失日期/金额或分红币种与报价币种不一致时，受影响的总额/股息率返回未知，不猜测汇率；历史不完整时不推断连续分红年数。港股日历、现金历史与报价独立降级，保留可用部分并提示失败来源。日历独立返回已公告未来除息日期。A 股排行/选股使用指定报告期已实施方案股息率；HK 指定 market=HK 时使用 HKEX/LSEG 公布的年度股息率（百分数），不是当前价 TTM；HK report_date 仅支持数据源可得年度的年末。港股股息选股因子也使用同一年度口径。筛选 YAML 可增加 filters.dividend_yield_min: 3、sort_by: dividend_score 与可选 dividend_report_date；缺失为未知，不按0填充。

数据源参考：AKShare股票接口、指数接口、基金接口、港交所南向持股、HKEX 年度股息率、理杏仁指数基本面接口。

独立 CLI 使用

Python 工具可脱离 Agent 独立使用，所有输出为 JSON：

# 行情数据
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

CI 真实宿主测试

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

e2e-llm 也使用这三项配置；同仓库 PR 和主分支推送会运行，fork PR 不读取 API key。e2e-host 缺少任一项时会失败。URL 和 model 同时存在于 Variable 与 Secret 时，优先使用 Secret。

项目结构

stock-analysis/
├── pi/                              # Pi Agent Extension
│   └── index.ts                     #   注册 57 个工具 + 20 个 skill
├── hermes/                          # Hermes Agent Plugin
│   ├── plugin.yaml                  #   插件清单
│   ├── __init__.py                  #   register(ctx) 入口
│   ├── schemas.py                   #   工具 JSON Schema 定义
│   └── tools.py                     #   57 个 handler → subprocess 调 CLI
├── openclaw/                        # OpenClaw Plugin
│   ├── openclaw.plugin.json         #   manifest（contracts.tools）
│   ├── package.json                 #   含 openclaw 块（pluginApi/SDK 版本）
│   └── index.ts                     #   definePluginEntry + registerTool ×57
├── dsh/                             # DeepSeek Harness (dsh) Plugin
│   ├── cordis.patch.yml             #   bundle patch（insert 插件入口）
│   ├── package.json                 #   含 dsh.bundle 块（bundle manifest）
│   └── index.ts                     #   cordis apply(ctx) + defineTool ×57
│
├── tools/                           # 共享 Python CLI 工具
│   ├── 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（20 个）
│   ├── stock-analysis/              #   综合分析 workflow
│   ├── stock-screener/              #   选股 workflow
│   ├── strategy-backtest/           #   回测 + 进化 workflow
│   └── ...                          #   12 个策略方法论
│
├── strategies/examples/             # 回测策略 YAML 示例
├── schemas/                         # JSON Schema（研报结构等）
├── tests/                           # pytest 测试
├── package.json                     # npm / Pi 配置
└── tsconfig.json

数据流

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

致谢

• daily_stock_analysis — A 股每日分析工具，本项目的综合分析流程参考了其设计思路
• akshare — A 股数据源
• yfinance — 港股 / 美股数据源
• pytdx — 通达信 TDX 协议（A 股免费兜底）
• longport — Longbridge OpenAPI（港股 / 美股）
• exchange-calendars — 全球交易日历

常见问题

Q: Python 工具报错 ModuleNotFoundError？

pip install -r tools/requirements.txt

如果使用 virtualenv / conda，确保 Agent 启动时能访问到对应的 Python 环境。

Q: A 股数据获取失败？

系统会自动按 akshare → tushare → efinance → 腾讯 → 新浪 → pytdx → baostock 顺序尝试（A 股链路含粘性优选：最近成功的源 24h 内优先）。腾讯 / 新浪源不依赖东财域名，在境外或受限网络下通常仍可用。如果所有源都失败，检查：网络问题、akshare 版本过低（pip install --upgrade akshare）、或非交易时间。配置 TUSHARE_TOKEN 可增加一个可靠数据源。

Q: 港股 / 美股数据有延迟？

yfinance 免费数据通常有 15 分钟延迟。配置 Longbridge（LONGBRIDGE_APP_KEY 等）或 Finnhub（FINNHUB_API_KEY）可获取更实时的数据，且作为 failover 备用源。

Q: 如何自定义筛选条件？

创建 YAML 配置：

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

CLI 使用：python tools/screener.py screen --config my_filter.yaml --top 30

Q: 如何编写自定义回测策略？

参考 strategies/examples/ 下的示例和 策略回测 DSL 章节。也可以直接让 Agent 帮你编写 YAML 策略。

License

MIT