stock-analysis-plugin 0.2.9 → 0.2.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -32,7 +32,7 @@ A 股 / 港股 / 美股 / 日股 / 韩股 / 台股综合分析、多因子选股
32
32
 
33
33
  ## 功能概览
34
34
 
35
- - **70 个工具** — 行情数据、技术分析、K 线形态、资金流向、估值历史、财报日历、股东/ETF/股息、新闻舆情、风险筛查、市场状态等
35
+ - **72 个工具** — 行情数据、技术分析、K 线形态、资金流向、估值历史、财报日历、股东/ETF/股息、新闻舆情、风险筛查、市场状态等
36
36
  - **21 个 Skills** — 综合分析、全市场选股、策略回测 + 18 个策略、复盘与研究方法论(缠论、波浪、龙头、情绪周期等)
37
37
  - **策略回测引擎** — YAML DSL 定义策略,参数化条件组合,自动诊断,按需进行有限轮参数优化
38
38
  - **多数据源 Failover** — 11 个数据源自动容灾切换(akshare / tushare / efinance / 腾讯行情 / 新浪行情 / pytdx / baostock / yfinance / finnhub / longbridge / alphavantage),A 股链路带粘性优选(最近成功的数据源下次优先尝试)
@@ -70,7 +70,7 @@ npm install @weaxs/stock-analysis-plugin
70
70
 
71
71
  Pi 启动后自动加载,输入 `/skills` 确认。详见 [Pi Agent 接入指南](docs/pi-integration.md)([English](docs/pi-integration.en.md))。
72
72
 
73
- 新版 Pi(已核验 1.2.0)提供原生 `tool_search` 时,插件自动启用按需工具发现,70 项能力保留注册,仅命中工具加载完整定义。缺少原生发现接口的旧版 Pi 或 SDK 宿主保持全量暴露。检索使用英文关键词或工具名,例如 `get_quote`、`get_financials`。
73
+ 新版 Pi(已核验 1.5.2)提供原生 `tool_search` 时,插件自动启用按需工具发现,72 项能力保留注册,仅命中工具加载完整定义。缺少原生发现接口的旧版 Pi 或 SDK 宿主保持全量暴露。可直接用中文关键词或工具名检索,例如 `实时行情`、`get_quote`、`get_financials`;Pi 1.5 之前的版本只能匹配英文关键词。
74
74
 
75
75
  ### Hermes Agent Plugin
76
76
 
@@ -95,7 +95,7 @@ register(ctx)
95
95
  openclaw plugins install clawhub:@weaxs/openclaw-stock-analysis
96
96
  ```
97
97
 
98
- OpenClaw Gateway 启动后自动加载并注册 70 个 tool。安装时 postinstall 会自动建 `.venv` 并装好 Python 依赖(前提:本机有 `python3 >= 3.10`)。
98
+ OpenClaw Gateway 启动后自动加载并注册 72 个 tool。安装时 postinstall 会自动建 `.venv` 并装好 Python 依赖(前提:本机有 `python3 >= 3.10`)。
99
99
 
100
100
  详见 [OpenClaw 接入指南](docs/openclaw-integration.md),或 plugin 自身说明 [`openclaw/README.md`](openclaw/README.md)。
101
101
 
@@ -106,7 +106,9 @@ dsh plugin --profile <你的profile> add @weaxs/dsh-stock-analysis
106
106
  dsh --profile <你的profile>
107
107
  ```
108
108
 
109
- 作为 dsh bundle 安装:`dsh plugin add` 会把 `cordis.patch.yml` 叠加进 profile 组合,注册 70 个 tool + 21 个 skill。postinstall 自动建 `.venv`(pnpm 需在 profile 的 `pnpm-workspace.yaml` 里给本包配 `allowBuilds`,否则回退系统 `python3`)。
109
+ 作为 dsh bundle 安装:`dsh plugin add` 会把 `cordis.patch.yml` 叠加进 profile 组合,注册 72 个 tool + 21 个 skill。postinstall 自动建 `.venv`(pnpm 需在 profile 的 `pnpm-workspace.yaml` 里给本包配 `allowBuilds`,否则回退系统 `python3`)。
110
+
111
+ 支持 dsh 前端的宿主还会在侧栏提供「股票仪表盘」:可排序、按市场筛选的自选股行情表(今日区间、成交额、30 日走势),顶部六市场指数带与 A 股涨跌分布,下方各市场指数、A 股涨跌统计和行业涨跌榜。插件在后台常驻预热并缓存行情,页面只读内存快照,打开即显示;交易时段有页面打开时约 30 秒更新一次。数据仍复用共享 Python CLI,不新增模型工具。
110
112
 
111
113
  新版 dsh 的原生函数调用模式默认通过 `stock_tool_search` 按 Agent 搜索、加载所需工具,支持中文关键词或工具名;旧接口、搜索入口不可用时保留全量暴露。可设置 `toolDiscovery: false` 关闭,配置与 PTC 模式边界见下方接入文档。
112
114
 
@@ -253,7 +255,8 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
253
255
  | `get_etf_details` | A 股 ETF 净值折溢价、规模变动、披露持仓、可选基准成分与跟踪误差 |
254
256
  | `get_dividends` | A/HK 历史分红/除息日历/已实现 TTM 股息与连续年数;A/HK 报告期/年度排行 |
255
257
  | `get_kline` | K 线数据(OHLCV),支持日/周/月线;A 股股票/ETF 前复权,每条记录 `adjusted=qfq`,指数 `adjusted=none` |
256
- | `get_quote` | 实时行情快照(非交易时段返回最近交易日收盘价并以 as_of/stale 标注;ETF 的 premium_discount_rate 为正=溢价、负=折价) |
258
+ | `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` |
259
+ | `get_fund_quote` | 6 位场外公募基金净值;`nav` 是 `nav_date` 对应的已披露日终净值而非实时价,`accumulated_nav` 为累计净值、`change_pct` 为日涨跌幅;`estimated_nav` 可能为 `null`,QDII 净值可能滞后 1-2 交易日 |
257
260
  | `get_capital_flow` | 资金流向(仅 A 股) |
258
261
  | `get_news` | 个股相关新闻 |
259
262
  | `get_financials` | 财务指标 |
@@ -300,7 +303,7 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
300
303
  | `screen_stocks` | 全市场多因子筛选(可选 L2;factor_coverage 展示缺失因子、覆盖度、实际权重及 L2 effective_scores) |
301
304
  | `screen_risk` | 风险因子筛查 |
302
305
  | `run_backtest` | YAML 策略回测,默认收盘信号于次日开盘成交,execution 返回模型与限制 |
303
- | `detect_market_regime` | 市场状态检测(牛/熊/震荡) |
306
+ | `detect_market_regime` | 市场状态检测(牛/熊/震荡;返回实际 as_of 和坏行警告,历史不足 60 根时 above_ma60=null) |
304
307
  | `get_market_review` | 市场日度复盘数据 |
305
308
  | `get_review_history` | 复盘归档历史(最近 N 条,最新在前,用于纵向对比) |
306
309
  | `run_watchlist_analysis` | 批量自选股分析 |
@@ -342,6 +345,8 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
342
345
 
343
346
  批量自选股分析和摘要的 `success` 表示至少获取了有效行情价格、K 线收盘价或技术评分;全部关键数据失败时计入 `failed`,部分结果仍保留。采集脚本复用返回的 K 线计算技术指标,并按股票所属市场查询大盘状态;日/韩/台市场状态暂不可用,非 A 股板块榜单也暂不可用,均会明确返回错误。
344
347
 
348
+ 同一次自选股分析会共享报价、日 K 线和按市场获取的大盘状态(包含可选市场复盘);风险与异动分析复用本次快照,资金流汇总和明细仍分开采集。采集任务使用共享的 6 线程 CLI 池,每支股票完成后即可接续异动分析,最终顺序保持调用方顺序。报价不跨调用保存。独立仓位/风控/筛选采集步骤并行执行。 两融历史明细按交易所/日期复用完整表,当日表和空表不缓存;CN 交易日历完整快照缓存一天。搜索按原优先级降级,单次查询的切换预算为 45 秒,综合搜索共用 90 秒预算;各请求使用剩余预算内的超时,严格总时限仍由宿主控制。同次综合搜索会跳过已确认不可用的引擎,下次独立调用重试。
349
+
345
350
  信号记录支持同一存储文件的多进程读写;评估期间新增的信号会保留。价格必须为正的有限数值,持有期限为正整数,日期格式为 YYYY-MM-DD。存储文件含损坏 JSON 行或无效信号时,记录、评估和汇总返回错误,原文件保持原样。
346
351
 
347
352
  信号评估仅在历史 K 线覆盖记录日时结算,缺少历史窗口则返回 `skipped_no_data` 并保持未结算。风险筛查返回 `data_complete` 和 `warnings`;数据不足时评级可为 `unknown`,`risk_score`、`veto_buy` 可为 null。告警的 `evaluated` 条目含 `error` 时表示无法检查,不能将未触发理解为已通过检查。
@@ -354,7 +359,8 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
354
359
  |------|------|
355
360
  | `compare_stocks` | 比较显式输入的同行指标;检查单位、期间和口径,仅对可比数值排序 |
356
361
  | `analyze_disclosure_changes` | 比较新旧公告正文与财务指标,返回来源、变更行号和增长率限制 |
357
- | `analyze_portfolio_risk` | 一次性持仓的集中度、行业/币种敞口、价格盈亏、止损情景与可选相关性 |
362
+ | `analyze_portfolio_risk` | 一次性持仓的集中度、行业/币种敞口、价格盈亏、止损情景、可选相关性与市场/行业/个股/汇率压力测试 |
363
+ | `plan_portfolio_rebalance` | 按目标权重、整手、费用和现金约束生成先卖后买的调仓计划,返回未满足数量与调后敞口 |
358
364
  | `calculate_position_size` | 按现金、风险预算、费用、滑点和交易单位计算本次可买数量 |
359
365
  | `analyze_event_study` | 事件前一交易日收盘至各窗口的股票/基准收益差,标明缺失和重叠样本 |
360
366
  | `validate_backtest` | 复用现有引擎,滚动训练选候选、样本外验证,比较参数及多个标的 |
@@ -381,9 +387,9 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
381
387
  python tools/stateless_analysis.py position_size --input input.json
382
388
  ```
383
389
 
384
- 对应宿主工具是 `calculate_position_size`。其余 CLI 子命令依次为 `peers/disclosure/portfolio/event_study/robustness/snapshot`。事件研究可直接传 `symbol/benchmark/start_date/end_date/event_dates`;回测验证可传 `symbols/start_date/end_date/strategies`,由 Python 复用行情接口,避免模型重新抄写历史 K 线。显式价格/datasets 模式仍支持离线计算,两种模式互斥。
390
+ 对应宿主工具是 `calculate_position_size`。其余 CLI 子命令依次为 `peers/disclosure/portfolio/rebalance/event_study/robustness/snapshot`。事件研究可直接传 `symbol/benchmark/start_date/end_date/event_dates`;回测验证可传 `symbols/start_date/end_date/strategies`,由 Python 复用行情接口,避免模型重新抄写历史 K 线。显式价格/datasets 模式仍支持离线计算,两种模式互斥。
385
391
 
386
- 跨币种组合必须提供显式汇率;价格盈亏不含历史汇兑损益。稳健性工具仅支持 next_open、每窗口重新从现金开始,样本内敏感性不等于样本外表现。
392
+ 跨币种组合必须提供显式汇率;价格盈亏不含历史汇兑损益。组合压力测试是用户指定市场/行业/个股/汇率冲击的确定性 what-if,个股冲击覆盖行业、行业覆盖市场,汇率独立乘算,不是预测或最大亏损保证。调仓工具按目标权重和整手生成计划,先卖后买;现金不足时同比例缩减买单并以 `cash_limited/unfilled` 标记,计划数量不代表成交。稳健性工具仅支持 next_open、每窗口重新从现金开始,样本内敏感性不等于样本外表现。
387
393
 
388
394
  ## 策略回测 DSL
389
395
 
@@ -431,19 +437,19 @@ position:
431
437
 
432
438
  其他可用键:
433
439
 
434
- - `exit.trailing_stop`:移动止损,价格自持仓期间最高收盘价回撤达到该比例即卖出(如 `0.08` = 峰值回撤 8% 触发);与 `stop_loss` 同时设置时先判固定止损。
435
- - `benchmark`(顶层):基准对比标的代码(如 `"sh000300"` 沪深300;指数代码必须带 sh/sz 交易所前缀,裸 6 位数字会被当作个股),设置后回测结果附带 `benchmark` 块(基准买入持有收益与 `excess_return` 超额收益)。
436
- - `simulation.execution`:默认 `next_open`,前日收盘信号、次日开盘加滑点成交;显式 `same_close` 复现旧收盘成交假设。交易同时返回 signal_date/date。零成交量阻止成交;一字板限制只在输入提供同口径历史 limit_up/limit_down 时执行。`execution` 列出阻止成交次数、未成交订单及限制;止损是收盘信号,未模拟盘口排队、部分成交、结算和市场冲击。
440
+ - `exit.trailing_stop`:移动止损,价格自持仓期间最高收盘价回撤达到该比例即卖出(如 `0.08` = 峰值回撤 8% 触发);与 `stop_loss` 同时设置时先判固定止损。`stop_loss` 必须为负数、`take_profit` 必须为正数、`trailing_stop` 须在 (0, 1) 内;`position.max_positions` 当前仅支持 1,其他配置明确报错。
441
+ - `benchmark`(顶层):基准对比标的代码(如 `"sh000300"` 沪深300;指数代码必须带 sh/sz 交易所前缀,裸 6 位数字会被当作个股),设置后回测结果附带 `benchmark` 块(基准买入持有收益与 `excess_return` 超额收益)。基准与策略采用同一首日执行口径(next_open 用 open、same_close 用 close),无预热时以策略首条权益日期为起点;实际覆盖不符或首末价格非法时返回 error,不输出超额。
442
+ - `simulation.execution`:默认 `next_open`,前日收盘信号、次日开盘加滑点成交;显式 `same_close` 复现旧收盘成交假设。交易同时返回 signal_date/date。延迟的入场信号在新收盘失效时撤单,风险退出 pending 保留至成交。`start` 前可得历史仅用于指标预热,取数长度随策略最大 lookback 增加,交易与权益仍按请求区间统计;`warnings` 出现 `Entry indicator is unavailable` 时必须披露指标不可用及数据质量,不能声称完成预热。零成交量阻止成交;一字板限制只在输入提供同口径历史 limit_up/limit_down 时执行。`execution` 列出阻止成交次数、未成交订单及限制;止损是收盘信号,未模拟盘口排队、部分成交、结算和市场冲击。回测仅接受单一 `qfq`/`total_return`/`none` 复权口径,unknown 或混合口径明确报错。
437
443
  - `simulation`(顶层):交易成本。`slippage`(滑点,买卖双边,默认 0.001)、`commission`(佣金,买卖双边,默认 0.0015)、`stamp_tax`(印花税,仅卖出收取,默认 0;A股为 0.0005,各市场税率不同且会调整,按当下实际费率填写)。费率均须在 [0, 1) 区间,越界报错。回测结果附带 `costs` 块(实际生效费率与实付费用合计 `commission_paid`/`stamp_tax_paid`)。
438
444
 
439
445
  ### 可用指标
440
446
 
441
447
  | 指标 | 说明 | 需要 period |
442
448
  |------|------|-------------|
443
- | `rsi` | RSI 相对强弱指数 | 是(默认 14) |
449
+ | `rsi` | RSI 相对强弱指数;预热不足不可用,全涨窗口为 100,全平为 50 | 是(默认 14) |
444
450
  | `ma` / `ema` | 简单 / 指数移动平均 | 是(默认 20) |
445
451
  | `macd_dif` / `macd_dea` / `macd` | MACD 三线 | 否 |
446
- | `volume_ratio` | 量比 | 是(默认 5) |
452
+ | `volume_ratio` | 当根成交量 / 前 N 根平均成交量(不含当根) | 是(默认 5) |
447
453
  | `price_change` | 涨跌幅(%) | 否 |
448
454
  | `bollinger_position` | 布林带位置(0=下轨, 1=上轨) | 是(默认 20) |
449
455
  | `trend_score` | 独立实验趋势强度,默认 (EMA20−EMA60)/ATR14;fast_period/slow_period 控制 EMA | period 为 ATR 根数(默认 14) |
@@ -497,7 +503,7 @@ python tools/value_data.py dividends --mode ranking --market HK --report-date 20
497
503
  python tools/value_data.py earnings_calendar --symbol 0700.HK
498
504
  ```
499
505
 
500
- 财报、基本信息及估值/股东/ETF/分红等慢变数据缓存到 `~/.stock-analysis/cache`,TTL 一天;板块成分/映射一周。行情报价不缓存。缓存文件原子替换,过期/损坏重拉,错误和显式部分失败不缓存;不以过期数据伪装最新数据。原有临时目录的粘性路由和反向成分缓存保留。
506
+ 财报、基本信息、股票代码/名称映射及估值/股东/ETF/分红等慢变数据缓存到 `~/.stock-analysis/cache`(可通过 `STOCK_CACHE_DIR` 指定可写目录,适用于沙箱/只读用户目录),TTL 一天;板块成分/映射一周。行情报价不缓存。缓存写入失败时直接返回已获取数据;缓存文件原子替换,过期/损坏重拉,错误和显式部分失败不缓存;不以过期数据伪装最新数据。原有临时目录的粘性路由和反向成分缓存保留。 同键缓存缺失与 SEC ZIP 下载通过跨进程文件锁协调,等待最多 5 秒;普通缓存锁不可用或超时后仍可直接抓取,持久写入/ZIP 下载则返回错误,避免无界等待。有效缓存命中不要求目录可写。
501
507
 
502
508
  估值使用可得数据的正值样本分位(`<=当前值`),返回 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 按源实际可得年数返回,不补造缺失比率。
503
509
 
@@ -566,20 +572,23 @@ GitHub Actions 的 `e2e-host` 使用 Pi、Hermes、OpenClaw、dsh 的真实运
566
572
  ```
567
573
  stock-analysis/
568
574
  ├── pi/ # Pi Agent Extension
569
- │ └── index.ts # 注册 70 个工具 + 21 个 skill
575
+ │ └── index.ts # 注册 72 个工具 + 21 个 skill
570
576
  ├── hermes/ # Hermes Agent Plugin
571
577
  │ ├── plugin.yaml # 插件清单
572
578
  │ ├── __init__.py # register(ctx) 入口
573
579
  │ ├── schemas.py # 工具 JSON Schema 定义
574
- │ └── tools.py # 70 个 handler → subprocess 调 CLI
580
+ │ └── tools.py # 72 个 handler → subprocess 调 CLI
575
581
  ├── openclaw/ # OpenClaw Plugin
576
582
  │ ├── openclaw.plugin.json # manifest(contracts.tools)
577
583
  │ ├── package.json # 含 openclaw 块(pluginApi/SDK 版本)
578
- │ └── index.ts # definePluginEntry + registerTool ×70
584
+ │ └── index.ts # definePluginEntry + registerTool ×72
579
585
  ├── dsh/ # DeepSeek Harness (dsh) Plugin
580
586
  │ ├── cordis.patch.yml # bundle patch(insert 插件入口)
581
- │ ├── package.json # 含 dsh.bundle 块(bundle manifest)
582
- │ └── index.ts # cordis apply(ctx) + defineTool ×70
587
+ │ ├── package.json # dsh.bundle + dsh.client manifest
588
+ │ ├── index.ts # cordis apply(ctx) + defineTool ×72
589
+ │ ├── dashboard.ts # 后台预热缓存 + 快照/自选股 HTTP API 与持久化
590
+ │ ├── client.ts # 侧栏入口 + 主面板 + 主题同步(编译为 dist/client.js)
591
+ │ └── web/ # 仪表盘页面(app.ts 编译为 dist/web/app.js)
583
592
  │
584
593
  ├── tools/ # 共享 Python CLI 工具
585
594
  │ ├── stock_data.py # 行情 / 资金流 / 新闻 / 财务 / 短线情绪
@@ -598,11 +607,11 @@ stock-analysis/
598
607
  │ ├── trading_calendar.py # 交易日历
599
608
  │ └── requirements.txt
600
609
  │
601
- ├── skills/ # 共享 SKILL.md(20 个)
610
+ ├── skills/ # 共享 SKILL.md(21 个)
602
611
  │ ├── stock-analysis/ # 综合分析 workflow
603
612
  │ ├── stock-screener/ # 选股 workflow
604
613
  │ ├── strategy-backtest/ # 回测 + 进化 workflow
605
- │ └── ... # 12 个策略方法论
614
+ │ └── ... # 18 个策略方法论
606
615
  │
607
616
  ├── strategies/examples/ # 回测策略 YAML 示例
608
617
  ├── schemas/ # JSON Schema(研报结构等)
@@ -695,7 +704,7 @@ python3 tools/sec_edgar.py insider_trades AAPL --days 90 --top 10
695
704
 
696
705
  公告类别为 `all/forecast/express/annual/interim/quarterly/reduction/issuance/inquiry/dividend`。默认最近 90 天,最多 500 条;通过巨潮官方股票目录取得 orgId,沪深京统一使用官方 `szse` 查询栏目。业绩快报和问询使用标题关键词查询。第一版返回 PDF 原文链接,不引入 PDF 解析依赖;`total/truncated` 表示供应商匹配数量及截断,查询无结果与请求失败分开。
697
706
 
698
- 港股使用既有 `LIXINGER_TOKEN`,需具备港股接口权限。新增来源覆盖理杏仁非金融公司财务和每日估值,最多十年;金融公司或无权限时回退现有 Yahoo/东财财务和百度估值,返回实际期数和不足提示。财务按 `annual_report` 识别年报,保留财年末、披露日和币种,金额为报告币种,历史比率为百分数;顶层 `roe/profit_margin` 延续 Yahoo 小数比例。理杏仁财报用于增强历史,同时按整组保留可用的 Yahoo 顶层快照,`currency` 是 Yahoo 的财报币种,`market_cap_currency` 是市值币种,`snapshot_source` 标明来源,缺失值不混入其他报告期或币种的历史数字;历史币种和报告日期在 `periods` 每行保留,Yahoo 未提供明确报告日期时顶层 `report_date=null`。快照失败时 `snapshot_available=false`,财报与历史仍返回。会计口径不强行转换为 A 股,估值分位沿用正值样本算法,不拼接不同来源。
707
+ 港股使用既有 `LIXINGER_TOKEN`,需具备港股接口权限。新增来源覆盖理杏仁非金融公司财务和每日估值,最多十年;金融公司或无权限时回退现有 Yahoo/东财财务和百度估值,返回实际期数和不足提示。财务按 `annual_report` 识别年报,保留财年末、披露日和币种,金额为报告币种,历史比率为百分数;顶层 `roe/profit_margin` 延续 Yahoo 小数比例。理杏仁财报用于增强历史,同时按整组保留可用的 Yahoo 顶层快照,`currency` 是 Yahoo 的财报币种,`market_cap_currency` 是市值币种,`snapshot_source` 标明来源,缺失值不混入其他报告期或币种的历史数字;历史币种和报告日期在 `periods` 每行保留,Yahoo 未提供明确报告日期时顶层 `report_date=null`。快照失败时 `snapshot_available=false`,财报与历史仍返回。会计口径不强行转换为 A 股,估值分位沿用正值样本算法,不拼接不同来源。Yahoo 顶层快照的 `snapshot_units` 明确:`pe=trailing`,`roe/profit_margin/dividend_yield=ratio`(小数),`debt_to_equity=percent`(百分数);不得把 D/E 百分数当作小数倍数。
699
708
 
700
709
  SEC 配置 `SEC_USER_AGENT`,包含应用名称与真实联系邮箱,仅通过环境变量提供。单进程最多每秒 2 次请求(多个并行进程需控制账户/IP 总量不超过 SEC 的每秒 10 次),并缓存 ticker/CIK、申报元数据和 XML 解析结果。13F 返回机构最近季度的原始申报,不是实时完整组合;通常在季度后 45 天内披露(节假日顺延),实际数据年龄以季度末为准,2023-01-03 起金额单位为美元,更早申报为千美元。修订文件另列原文链接,避免错误合并补充与重述;发行人 CIK 反查现已通过 `mode=issuer` 支持:从结构化 Schedule 13D/G 校验发行人 CIK、提取 CUSIP,再扫描官方最新已发布 13F 批量窗口。`auto` 默认有当前或已检索历史 13F 时查机构,否则查发行人;Berkshire 等兼具两种身份时显式选择 `issuer`。修订按 `RESTATEMENT` 替换与 `NEW HOLDINGS` 补充重建;无法判断的修订或缺少基础版时总量为 null,并给出 `unresolved_manager_count`。
701
710
 
@@ -729,8 +738,10 @@ python3 tools/sec_edgar.py holdings 0001067983 --mode manager
729
738
 
730
739
  真实模型评测同时要求结构化证据检查与独立上下文的结论审稿通过:审稿检查正文事实、限制说明是否诚实,以及是否过度外推。未运行审稿、结果缺失或模糊都不能算通过;报告自行声明通过不被采信。另有人工核对的正确报告及两类反例用于验证审稿器(正确引用但正文捏造现价、3笔交易却保证长期胜率)。空回答也失败。离线渲染和规则检查不代表真实模型通过,也不证明策略未来有效。信号建议可沿用 source 标识策略版本,按来源复盘胜率、平均收益和样本量;未扣成本、未匹配基准的观察记录不能当作策略回测。
731
740
 
732
- 信号结算仅在价格口径可核实时进行:原始价格可直接比较;复权日线需记录日 adjustment_factor(复权价/原始价),当前日线 Tushare、Alpha Vantage 可提供。缺失系数或口径未知时返回 skipped_price_basis,保持未结算,不猜测除权比例。换算后的 exit_price 是记录时价格单位的等价值,实际市场价可不同,evaluation_price_basis 保留依据。evaluate_signals 的 CLI 预算为 300 秒,内部提前结束采集并保存已完成结果,complete/deferred/warnings 指示需要重试的记录;预算耗尽后调整未结算记录的处理顺序,下轮优先处理尚未尝试的记录,避免慢请求长期阻塞后续信号。
741
+ 信号结算仅在价格口径可核实时进行:原始价格可直接比较;自动记录的默认 `record_date` 与 `price_date` 均按标的市场时区确定(显式 `date` 不变),并保存原始 `price_as_of`;`price_date` 晚于 `record_date` 时拒绝记录与结算;多头 target 必须高于 entry、stop 必须低于 entry,空头相反,否则拒绝记录。开盘先触 stop 按 open 结算,先触 target 按 target 保守结算,日内顺序未知的双触发仍 stop 优先;无止损的旧 HLC 记录可继续用 high/low/close 判定目标和到期,但若提供 open 也必须是正有限数值,有止损但缺 open 则拒绝结算。重复日期返回 skipped_no_data,复权乘除使用 Decimal。复权日线需该报价日的 adjustment_factor(复权价/原始价),当前日线 Tushare、Alpha Vantage 可提供。缺失系数或口径未知时返回 skipped_price_basis,保持未结算,不猜测除权比例;记录日无 K 线时仅在前后因子一致(或已有明确报价日)时使用最近锚点,旧信号缺少报价时点且记录日因子变化时也保持未结算。换算后的 exit_price 是记录时价格单位的等价值,实际市场价可不同,evaluation_price_basis 保留依据。evaluate_signals 的 CLI 预算为 300 秒,内部提前结束采集并保存已完成结果,complete/deferred/warnings 指示需要重试的记录;预算耗尽后调整未结算记录的处理顺序,下轮优先处理尚未尝试的记录,避免慢请求长期阻塞后续信号。
733
742
 
734
743
  市场复盘数据不足时温度/姿态为 null,信号 unknown,data_quality.limitations 说明限制。自选股异动采集失败时 anomaly_status=unavailable、anomaly_count=null,保留警告并计入 summary.partial,不能当成无异常。
735
744
 
736
- L1 与 L2 综合分均在排序前按可用因子重新归一化;缺失或非有限因子不作零分处理,因子组内部也仅平均有效输入。factor_coverage.ratio 保留原始权重覆盖率,effective_weights 是实际归一化后的权重,高分仍需结合覆盖率判断。
745
+ L1 与 L2 综合分均在排序前按可用因子重新归一化;缺失或非有限因子不作零分处理,因子组内部也仅平均有效输入。factor_coverage.ratio 保留原始权重覆盖率,effective_weights 是实际归一化后的权重,高分仍需结合覆盖率判断。估值比较需同时读取 `pe_basis`;有限非正 PE/PB 的价值子分为 0,不能因数值更低而获得最高价值分。
746
+
747
+ L2 的 `vol20` 只使用恰好 20 个有效日收益,`factor_coverage.vol20_samples` 记录实际样本数,非正/非有限收盘价先剔除,空输入为 0;质量因子按 `report_date` 分组归一,避免年度累计与单季累计直接比较。资金流 5/10/20 日窗口不足返回 null,不按 0 或完整窗口处理。HK 快照统一带 `.HK`,US 快照移除东财交易所后缀并把类别股点号转为 Yahoo 连字符。主板 ST/*ST 按 5% 识别涨跌停,其他板块比例不变。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "stock-analysis-plugin",
3
- "version": "0.2.9",
3
+ "version": "0.2.11",
4
4
  "description": "Pi Agent extension for stock analysis, screening, and strategy backtesting across A/HK/US/JP/KR/TW markets",
5
5
  "type": "module",
6
6
  "main": "./pi/index.ts",
@@ -48,7 +48,7 @@
48
48
  "scripts": {
49
49
  "postinstall": "node scripts/setup-python.mjs",
50
50
  "build:openclaw": "esbuild openclaw/index.ts --bundle --format=esm --platform=node --external:openclaw/* --outfile=openclaw/dist/index.js",
51
- "build:dsh": "esbuild dsh/index.ts dsh/research-role.ts --bundle --format=esm --platform=node --external:@deepseek-ai/* --outdir=dsh/dist"
51
+ "build:dsh": "esbuild dsh/index.ts dsh/research-role.ts --bundle --format=esm --platform=node --external:@deepseek-ai/* --outdir=dsh/dist && esbuild dsh/client.ts dsh/web/app.ts dsh/web/index.html dsh/web/style.css --bundle --format=iife --platform=browser --target=es2020 --outbase=dsh --outdir=dsh/dist --loader:.html=copy --loader:.css=copy"
52
52
  },
53
53
  "keywords": [
54
54
  "pi-agent",
@@ -78,17 +78,21 @@
78
78
  },
79
79
  "license": "MIT",
80
80
  "devDependencies": {
81
- "@deepseek-ai/cordis": "4.0.5",
82
- "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
83
- "@deepseek-ai/dsh-skill": "0.2.1-rc.2",
84
- "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.2",
85
- "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
86
- "@types/node": "^22.0.0",
87
- "esbuild": "^0.28.0",
81
+ "@deepseek-ai/cordis": "4.1.0",
82
+ "@deepseek-ai/dsh-llm": "0.2.2-rc.1",
83
+ "@deepseek-ai/dsh-skill": "0.2.2-rc.1",
84
+ "@deepseek-ai/dsh-system-prompt": "0.2.2-rc.1",
85
+ "@deepseek-ai/dsh-tool-executor-native": "0.2.2-rc.1",
86
+ "@deepseek-ai/dsh-tools": "0.2.2-rc.1",
87
+ "@types/node": "^24.19.2",
88
+ "esbuild": "^0.28.2",
88
89
  "jiti": "^2.7.0",
89
- "openai": "^4.104.0",
90
- "tsx": "^4.22.1",
91
- "typebox": "^1.3.10",
90
+ "openai": "^7.47.0",
91
+ "tsx": "^4.23.15",
92
+ "typebox": "^1.4.3",
92
93
  "typescript": "^5.5.0"
94
+ },
95
+ "overrides": {
96
+ "zod": "4.6.7"
93
97
  }
94
98
  }
package/pi/index.ts CHANGED
@@ -1,9 +1,9 @@
1
1
  import { withJsonInput } from "../scripts/json-input.mjs";
2
2
  import type { ExtensionAPI } from "pi-agent";
3
- import { existsSync } from "fs";
4
3
  import { fileURLToPath } from "url";
5
4
 
6
5
  import { commandTimeout } from "../scripts/cli-timeout.mjs";
6
+ import { resolvePython } from "../scripts/venv-python.mjs";
7
7
 
8
8
  export default (pi: ExtensionAPI) => {
9
9
  const tools: Parameters<ExtensionAPI["registerTool"]>[0][] = [];
@@ -41,7 +41,7 @@ export default (pi: ExtensionAPI) => {
41
41
  return discoveryEnabled ? {
42
42
  message: {
43
43
  customType: "stock-analysis-discovery",
44
- content: "Stock analysis tools are available through tool_search. Search using English keywords or exact tool names (e.g. get_quote, get_financials, screen_stocks, run_backtest); its search does not tokenize Chinese. Load the tools needed for the task, then call them normally.",
44
+ content: "Stock analysis tools are available through tool_search. Search with exact tool names (e.g. get_quote, get_financials, screen_stocks, run_backtest) or keywords; their descriptions are Chinese, so Chinese keywords match on Pi 1.5+, while older Pi matches only English/ASCII terms. Load the tools needed for the task, then call them normally.",
45
45
  display: false,
46
46
  },
47
47
  } : undefined;
@@ -53,11 +53,7 @@ export default (pi: ExtensionAPI) => {
53
53
  ? `${__dirname}/..`
54
54
  : fileURLToPath(new URL("..", import.meta.url));
55
55
  const toolsDir = `${baseDir}/tools`;
56
- const isWin = process.platform === "win32";
57
- // Windows venvs ship Scripts/python.exe (there is no python3); POSIX venvs ship bin/python3.
58
- const venvPython = `${baseDir}/.venv/${isWin ? "Scripts/python.exe" : "bin/python3"}`;
59
- // Fallback: on Windows "python3" is usually the Microsoft Store stub — prefer "python".
60
- const python = existsSync(venvPython) ? venvPython : isWin ? "python" : "python3";
56
+ const python = resolvePython(baseDir);
61
57
  const py = async (script: string, args: string[]) => {
62
58
  const result = await pi.exec(python, [`${toolsDir}/${script}`, ...args], { timeout: commandTimeout(script, args) });
63
59
  if (result.killed || !result.stdout.trim()) {
@@ -313,7 +309,7 @@ export default (pi: ExtensionAPI) => {
313
309
 
314
310
  registerTool({
315
311
  name: "analyze_portfolio_risk",
316
- description: "无状态现货多头组合风险:输入持仓、基准币种现金与汇率,返回集中度、币种/行业敞口、价格盈亏和止损情景。缺汇率报错;不保存账户。",
312
+ description: "无状态现货多头组合风险与压力测试:输入持仓、基准币种现金与汇率,返回集中度、币种/行业敞口、价格盈亏、止损情景及可选市场/行业/个股/汇率冲击损益。缺汇率报错;不保存账户。",
317
313
  parameters: {
318
314
  "type": "object",
319
315
  "properties": {
@@ -434,6 +430,82 @@ export default (pi: ExtensionAPI) => {
434
430
  "additionalProperties": false
435
431
  },
436
432
  "description": "可选历史,共同日期本币价格收益相关性,不计汇率"
433
+ },
434
+ "stress_scenarios": {
435
+ "type": "array",
436
+ "items": {
437
+ "type": "object",
438
+ "properties": {
439
+ "name": {
440
+ "type": "string",
441
+ "description": "情景名称"
442
+ },
443
+ "market_shock": {
444
+ "type": "number",
445
+ "description": "全市场资产价格冲击比例,如-0.1"
446
+ },
447
+ "sector_shocks": {
448
+ "type": "array",
449
+ "items": {
450
+ "type": "object",
451
+ "properties": {
452
+ "sector": {
453
+ "type": "string",
454
+ "description": "与持仓一致的行业名称"
455
+ },
456
+ "shock": {
457
+ "type": "number",
458
+ "description": "行业价格冲击比例"
459
+ }
460
+ },
461
+ "required": ["sector", "shock"],
462
+ "additionalProperties": false
463
+ },
464
+ "description": "可选行业冲击"
465
+ },
466
+ "symbol_shocks": {
467
+ "type": "array",
468
+ "items": {
469
+ "type": "object",
470
+ "properties": {
471
+ "symbol": {
472
+ "type": "string",
473
+ "description": "持仓标的代码"
474
+ },
475
+ "shock": {
476
+ "type": "number",
477
+ "description": "标的价格冲击比例"
478
+ }
479
+ },
480
+ "required": ["symbol", "shock"],
481
+ "additionalProperties": false
482
+ },
483
+ "description": "可选个股冲击"
484
+ },
485
+ "currency_shocks": {
486
+ "type": "array",
487
+ "items": {
488
+ "type": "object",
489
+ "properties": {
490
+ "currency": {
491
+ "type": "string",
492
+ "description": "持仓中的非基准币种;基准币种不可相对自身冲击"
493
+ },
494
+ "shock": {
495
+ "type": "number",
496
+ "description": "相对基准币种的汇率冲击比例"
497
+ }
498
+ },
499
+ "required": ["currency", "shock"],
500
+ "additionalProperties": false
501
+ },
502
+ "description": "可选汇率冲击"
503
+ }
504
+ },
505
+ "required": ["name"],
506
+ "additionalProperties": false
507
+ },
508
+ "description": "可选压力情景;所有冲击均为比例,由共享核心计算"
437
509
  }
438
510
  },
439
511
  "required": [
@@ -449,6 +521,156 @@ export default (pi: ExtensionAPI) => {
449
521
  },
450
522
  });
451
523
 
524
+ registerTool({
525
+ name: "plan_portfolio_rebalance",
526
+ description: "无状态组合调仓计划:按当前持仓、目标权重、现金、汇率、整手、费用和换手约束生成先卖后买清单;不保存账户或提交订单。",
527
+ parameters: {
528
+ "type": "object",
529
+ "properties": {
530
+ "base_currency": {
531
+ "type": "string",
532
+ "description": "基准币种"
533
+ },
534
+ "cash": {
535
+ "type": "number",
536
+ "description": "基准币种现金,非负"
537
+ },
538
+ "positions": {
539
+ "type": "array",
540
+ "items": {
541
+ "type": "object",
542
+ "properties": {
543
+ "symbol": {
544
+ "type": "string",
545
+ "description": "唯一代码,重复持仓先汇总"
546
+ },
547
+ "quantity": {
548
+ "type": "number",
549
+ "description": "正持仓数量"
550
+ },
551
+ "price": {
552
+ "type": "number",
553
+ "description": "正现价"
554
+ },
555
+ "currency": {
556
+ "type": "string",
557
+ "description": "持仓币种,如CNY/USD/HKD"
558
+ },
559
+ "cost": {
560
+ "type": "number",
561
+ "description": "同币种正成本价,可选;调仓计算不使用"
562
+ },
563
+ "stop_price": {
564
+ "type": "number",
565
+ "description": "同币种正止损价,可选;调仓计算不使用"
566
+ },
567
+ "sector": {
568
+ "type": "string",
569
+ "description": "统一行业分类,可选"
570
+ },
571
+ "as_of": {
572
+ "type": "string",
573
+ "description": "实际估值时点,建议ISO8601"
574
+ }
575
+ },
576
+ "required": [
577
+ "symbol",
578
+ "quantity",
579
+ "price",
580
+ "currency"
581
+ ],
582
+ "additionalProperties": false
583
+ },
584
+ "description": "0..100个现货多头持仓,空数组表示纯现金建仓"
585
+ },
586
+ "targets": {
587
+ "type": "array",
588
+ "items": {
589
+ "type": "object",
590
+ "properties": {
591
+ "symbol": {
592
+ "type": "string",
593
+ "description": "目标标的代码"
594
+ },
595
+ "weight": {
596
+ "type": "number",
597
+ "description": "目标权重;大于0时lot_size必填"
598
+ },
599
+ "price": {
600
+ "type": "number",
601
+ "description": "正目标价格;当前未持有的新标的必填"
602
+ },
603
+ "currency": {
604
+ "type": "string",
605
+ "description": "目标币种;当前未持有的新标的必填"
606
+ },
607
+ "sector": {
608
+ "type": "string",
609
+ "description": "统一行业分类,可选"
610
+ },
611
+ "as_of": {
612
+ "type": "string",
613
+ "description": "实际估值时点,建议ISO8601"
614
+ },
615
+ "lot_size": {
616
+ "type": "number",
617
+ "description": "正整数交易单位;weight>0时必填"
618
+ }
619
+ },
620
+ "required": ["symbol", "weight"],
621
+ "additionalProperties": false
622
+ },
623
+ "description": "1..100个目标;新标的price/currency必填"
624
+ },
625
+ "fx_rates": {
626
+ "type": "array",
627
+ "items": {
628
+ "type": "object",
629
+ "properties": {
630
+ "currency": {
631
+ "type": "string",
632
+ "description": "唯一非基准币种"
633
+ },
634
+ "rate": {
635
+ "type": "number",
636
+ "description": "一单位该币种对应多少基准币种,正数"
637
+ }
638
+ },
639
+ "required": [
640
+ "currency",
641
+ "rate"
642
+ ],
643
+ "additionalProperties": false
644
+ },
645
+ "description": "显式现价汇率;基准币种隐含1,不得重复"
646
+ },
647
+ "fee_rate": {
648
+ "type": "number",
649
+ "description": "每边比例费用0..0.1,默认0;不含未提供税费/最低收费"
650
+ },
651
+ "slippage_rate": {
652
+ "type": "number",
653
+ "description": "每边滑点0..0.1,默认0"
654
+ },
655
+ "max_turnover_fraction": {
656
+ "type": "number",
657
+ "description": "非负最大总换手,按买卖参考金额合计/初始权益;默认不限制,可大于1"
658
+ }
659
+ },
660
+ "required": [
661
+ "base_currency",
662
+ "cash",
663
+ "positions",
664
+ "targets"
665
+ ],
666
+ "additionalProperties": false
667
+ },
668
+ async execute(_id, params) {
669
+ return asText(await withJsonInput(params, async (path: string) =>
670
+ (await py("stateless_analysis.py", ["rebalance", "--input", path])).stdout));
671
+ },
672
+ });
673
+
452
674
  registerTool({
453
675
  name: "calculate_position_size",
454
676
  description: "无状态多头仓位预算:同币种金额,按现金/风险预算/最大仓位/交易单位取最小数量,双边费用和滑点参与止损情景;不执行交易。",
@@ -1082,7 +1304,7 @@ export default (pi: ExtensionAPI) => {
1082
1304
  registerTool({
1083
1305
  name: "get_quote",
1084
1306
  description:
1085
- "获取股票实时行情报价(现价、涨跌幅、量比等)。支持A股、港股、美股、日股、韩股、台股;非交易时段返回最近交易日收盘价并以 as_of/stale 标注;ETF 的 premium_discount_rate 为正=溢价、负=折价。返回 source、UTC fetched_at 和提供方 data_as_of(未知为null);as_of_basis区分提供方时间与交易日历推断,采集时间不等于行情时间。",
1307
+ "获取股票实时行情报价(现价、涨跌幅、量比等)。支持A股、港股、美股、日股、韩股、台股;非交易时段返回最近交易日收盘价并以 as_of/stale 标注;ETF 的 premium_discount_rate 为正=溢价、负=折价。返回 source、UTC fetched_at 和提供方 data_as_of(未知为null);as_of_basis区分提供方时间与交易日历推断,采集时间不等于行情时间。场外基金用 get_fund_quote;TIAAxxxxxx 返回投顾组合识别、advisor_org 与无统一净值提示;长钱/海外长钱/稳钱另有有知有行 official_disclosures(partial=true,非实时完整持仓);其他组合搜索可用时为 search_partial,否则 unsupported_provider。",
1086
1308
  parameters: {
1087
1309
  type: "object",
1088
1310
  properties: {
@@ -1099,6 +1321,26 @@ export default (pi: ExtensionAPI) => {
1099
1321
  },
1100
1322
  });
1101
1323
 
1324
+ registerTool({
1325
+ name: "get_fund_quote",
1326
+ description:
1327
+ "获取场外公募基金净值(6位基金代码,如018147)。nav 是已披露日终净值,非实时价;返回 accumulated_nav(累计净值)、change_pct(日涨跌幅)、nav_date(净值日期)。estimated_nav 为估算净值,可能为 null,不能当作实时价;QDII 净值可能滞后 1-2 交易日。",
1328
+ parameters: {
1329
+ type: "object",
1330
+ properties: {
1331
+ symbol: {
1332
+ type: "string",
1333
+ description: "6位场外公募基金代码,如 018147",
1334
+ },
1335
+ },
1336
+ required: ["symbol"],
1337
+ },
1338
+ async execute(_id, { symbol }) {
1339
+ const result = await py("stock_data.py", ["fund_quote", symbol]);
1340
+ return asText(result.stdout);
1341
+ },
1342
+ });
1343
+
1102
1344
  registerTool({
1103
1345
  name: "get_capital_flow",
1104
1346
  description:
@@ -1824,8 +2066,6 @@ export default (pi: ExtensionAPI) => {
1824
2066
  "items": {
1825
2067
  "type": "string"
1826
2068
  },
1827
- "minItems": 1,
1828
- "maxItems": 100,
1829
2069
  "description": "同一市场的完整股票池,1..100只;A如600036,HK如0700.HK,US如AAPL"
1830
2070
  },
1831
2071
  "as_of": {