stock-analysis-plugin 0.2.5 → 0.2.6

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
- - **57 个工具** — 行情数据、技术分析、K 线形态、资金流向、估值历史、财报日历、股东/ETF/股息、新闻舆情、风险筛查、市场状态等
35
+ - **60 个工具** — 行情数据、技术分析、K 线形态、资金流向、估值历史、财报日历、股东/ETF/股息、新闻舆情、风险筛查、市场状态等
36
36
  - **20 个 Skills** — 综合分析、全市场选股、策略回测 + 17 个策略方法论(缠论、波浪、龙头、情绪周期等)
37
37
  - **策略回测引擎** — YAML DSL 定义策略,参数化条件组合,自动诊断,按需进行有限轮参数优化
38
38
  - **多数据源 Failover** — 11 个数据源自动容灾切换(akshare / tushare / efinance / 腾讯行情 / 新浪行情 / pytdx / baostock / yfinance / finnhub / longbridge / alphavantage),A 股链路带粘性优选(最近成功的数据源下次优先尝试)
@@ -93,7 +93,7 @@ register(ctx)
93
93
  openclaw plugins install clawhub:@weaxs/openclaw-stock-analysis
94
94
  ```
95
95
 
96
- OpenClaw Gateway 启动后自动加载并注册 57 个 tool。安装时 postinstall 会自动建 `.venv` 并装好 Python 依赖(前提:本机有 `python3 >= 3.10`)。
96
+ OpenClaw Gateway 启动后自动加载并注册 60 个 tool。安装时 postinstall 会自动建 `.venv` 并装好 Python 依赖(前提:本机有 `python3 >= 3.10`)。
97
97
 
98
98
  详见 [OpenClaw 接入指南](docs/openclaw-integration.md),或 plugin 自身说明 [`openclaw/README.md`](openclaw/README.md)。
99
99
 
@@ -104,7 +104,7 @@ dsh plugin --profile <你的profile> add @weaxs/dsh-stock-analysis
104
104
  dsh --profile <你的profile>
105
105
  ```
106
106
 
107
- 作为 dsh bundle 安装:`dsh plugin add` 会把 `cordis.patch.yml` 叠加进 profile 组合,注册 57 个 tool + 20 个 skill。postinstall 自动建 `.venv`(pnpm 需在 profile 的 `pnpm-workspace.yaml` 里给本包配 `allowBuilds`,否则回退系统 `python3`)。
107
+ 作为 dsh bundle 安装:`dsh plugin add` 会把 `cordis.patch.yml` 叠加进 profile 组合,注册 60 个 tool + 20 个 skill。postinstall 自动建 `.venv`(pnpm 需在 profile 的 `pnpm-workspace.yaml` 里给本包配 `allowBuilds`,否则回退系统 `python3`)。
108
108
 
109
109
  详见 [`dsh/README.md`](dsh/README.md)。
110
110
 
@@ -127,7 +127,7 @@ pip install -r tools/requirements.txt
127
127
  | pytdx | A 股 TDX 行情(免费兜底源) |
128
128
  | longport | 港股 / 美股 Longbridge SDK |
129
129
 
130
- > A 股行情另有**腾讯(qt.gtimg.cn)/ 新浪(hq.sinajs.cn)**两个免鉴权兜底源,不依赖任何 Python 包(直接 HTTP 调用),用于东财域名不可达的网络环境(境外主机、企业出网限制等)。
130
+ > A 股行情另有**腾讯(qt.gtimg.cn)/ 新浪(hq.sinajs.cn)**两个免鉴权兜底源,直接 HTTP 调用,用于东财域名不可达的网络环境(境外主机、企业出网限制等)。港股实时行情也使用腾讯作为 yfinance 之后的免 key 备用源。
131
131
 
132
132
  ### 环境变量
133
133
 
@@ -147,6 +147,8 @@ pip install -r tools/requirements.txt
147
147
 
148
148
  | 环境变量 | 用途 |
149
149
  |---------|------|
150
+ | `LIXINGER_TOKEN` | 理杏仁可选数据源:指数 PB 与港股非金融公司财务/每日估值(需对应权限) |
151
+ | `SEC_USER_AGENT` | SEC EDGAR 身份声明:应用名称与真实联系邮箱,13F/Form 4 必需 |
150
152
  | `TAVILY_API_KEY` | Tavily 搜索 |
151
153
  | `BRAVE_API_KEY` | Brave 搜索 |
152
154
  | `SERPAPI_KEY` | SerpAPI |
@@ -236,6 +238,9 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
236
238
 
237
239
  | 工具 | 说明 |
238
240
  |------|------|
241
+ | `get_announcements` | A 股巨潮公告查询:类别/日期范围/标题/原文 PDF 链接 |
242
+ | `get_us_holdings` | SEC 机构组合 / 发行人 CIK 反查机构:精确 CUSIP 映射、季度数据与修订处理(需 SEC_USER_AGENT) |
243
+ | `get_insider_trades` | SEC 股票 ticker/发行人 CIK 的 Form 4 内部人交易、代码和脚注 |
239
244
  | `get_valuation_history` | A/HK PE-TTM/PB 历史、正值分位与估值 Band,实际采样窗口 |
240
245
  | `get_index_valuation` | 中国指数 PE/PB 历史水位;中证官方多年滚动 PE;可选理杏仁补充 PB |
241
246
  | `get_earnings_calendar` | A 股报告期披露与业绩预告;HK 已公告业绩审批董事会排期/供应商备选日期 |
@@ -319,6 +324,14 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
319
324
  | `render_stock_report` | 将结构化个股报告渲染为 Markdown |
320
325
  | `render_market_report` | 将结构化市场复盘渲染为 Markdown(save=true 时归档到本地 JSONL) |
321
326
 
327
+ 批量自选股分析和摘要的 `success` 表示至少获取了有效行情价格、K 线收盘价或技术评分;全部关键数据失败时计入 `failed`,部分结果仍保留。采集脚本复用返回的 K 线计算技术指标,并按股票所属市场查询大盘状态;日/韩/台市场状态暂不可用,非 A 股板块榜单也暂不可用,均会明确返回错误。
328
+
329
+ 信号记录支持同一存储文件的多进程读写;评估期间新增的信号会保留。价格必须为正的有限数值,持有期限为正整数,日期格式为 YYYY-MM-DD。存储文件含损坏 JSON 行或无效信号时,记录、评估和汇总返回错误,原文件保持原样。
330
+
331
+ 信号评估仅在历史 K 线覆盖记录日时结算,缺少历史窗口则返回 `skipped_no_data` 并保持未结算。风险筛查返回 `data_complete` 和 `warnings`;数据不足时评级可为 `unknown`,`risk_score`、`veto_buy` 可为 null。告警的 `evaluated` 条目含 `error` 时表示无法检查,不能将未触发理解为已通过检查。
332
+
333
+ 选股的 `filters_applied` 只列实际执行的条件,显式条件缺少数据时报错。回测的 `period` 是实际数据期间,`requested_period` 保留请求期间,`warnings` 提示覆盖差异;买入预算包含佣金,年化收益和回撤按实际数据及初始资金计算。
334
+
322
335
  ## 策略回测 DSL
323
336
 
324
337
  策略以 YAML 格式定义,支持参数化和条件组合:
@@ -392,13 +405,14 @@ position:
392
405
  | 6 位纯数字 | `600519`, `000001`, `300750` | A 股 | akshare → tushare → efinance → 腾讯 → 新浪 → pytdx → baostock |
393
406
  | 6 位纯数字(51/52/56/58/15/16/18 开头) | `510300`, `159915` | A 股 ETF | akshare(基金接口)→ tushare → efinance → 腾讯 → 新浪 → pytdx → baostock |
394
407
  | 带交易所前缀(`sh`/`sz`/`bj` + 6 位数字) | `sh000001`(上证指数), `sz399006`(创业板指) | A 股(显式指定,含指数) | 腾讯 → 新浪 |
395
- | `.HK` 结尾 | `00700.HK`, `09988.HK` | 港股 | yfinance → finnhub → longbridge |
408
+ | `.HK` 结尾 | `00700.HK`, `09988.HK` | 港股 | yfinance → 腾讯 → finnhub → longbridge |
396
409
  | 英文字母 | `AAPL`, `GOOGL`, `TSLA` | 美股 | yfinance → finnhub → longbridge → alphavantage |
397
410
  | `.T` 结尾 | `7203.T` | 日股 | yfinance |
398
- | `.KS` / `.KQ` 结尾 | `005930.KS`, `035720.KQ` | 韩股 | yfinance |
411
+ | `.KS` / `.KQ` 结尾 | `005930.KS`, `036020.KQ` | 韩股 | yfinance |
399
412
  | `.TW` / `.TWO` 结尾 | `2330.TW`, `6510.TWO` | 台股 | yfinance |
400
413
 
401
414
  > 各数据源按优先级自动尝试,前一个失败后自动切换到下一个。未配置相关 env var 的数据源会被跳过。
415
+ > 港股腾讯备用源使用 `r_hk` 通道(`hk` 通道延迟约 15 分钟),仅用于实时报价,K 线仍走 yfinance → finnhub → longbridge。支持 `00700.HK` / `0700.HK` / `700.hk`,成交量单位为股,成交额及市值为港元;PB、换手率、量比在此备用源中返回 null,不套用 A 股字段。
402
416
  > 裸 6 位代码一律按**个股**处理(`000001` 是平安银行);指数需带交易所前缀(`sh000001` = 上证指数),显式前缀代码直接走腾讯/新浪(东财源只认裸代码)。
403
417
  > **A 股 K 线口径**:股票/ETF 仅接受前复权数据,链路为 akshare → tushare(仅股票)→ efinance → 腾讯(仅 qfq 数据)→ baostock;带前缀的股票/ETF 先去前缀再走同一链路。新浪和 pytdx 的未复权 K 线不参与股票/ETF 容灾。显式指数 `sh000xxx` / `sz399xxx` 保留原始点位,走腾讯 → 新浪 → baostock。上述路由表的完整链路仍适用于实时行情。
404
418
  > K 线响应保留原有 JSON 数组,每条 A 股记录新增 `adjusted`:股票/ETF 为 `"qfq"`,指数为 `"none"`。Tushare 日线通过 `adj_factor` 前复权,周/月线使用 `stk_week_month_adj` 的 qfq 字段;复权权限不足、因子缺失或源只返回原始价格时继续切换,所有可用复权源都失败时返回 JSON `error`,不降级到未复权股票价格。Tushare 复权接口需至少 2000 积分,见[复权因子](https://tushare.pro/document/2?doc_id=28)与[复权周/月线](https://tushare.pro/document/2?doc_id=365)。
@@ -494,20 +508,20 @@ GitHub Actions 的 `e2e-host` 使用 Pi、Hermes、OpenClaw、dsh 的真实运
494
508
  ```
495
509
  stock-analysis/
496
510
  ├── pi/ # Pi Agent Extension
497
- │ └── index.ts # 注册 57 个工具 + 20 个 skill
511
+ │ └── index.ts # 注册 60 个工具 + 20 个 skill
498
512
  ├── hermes/ # Hermes Agent Plugin
499
513
  │ ├── plugin.yaml # 插件清单
500
514
  │ ├── __init__.py # register(ctx) 入口
501
515
  │ ├── schemas.py # 工具 JSON Schema 定义
502
- │ └── tools.py # 57 个 handler → subprocess 调 CLI
516
+ │ └── tools.py # 60 个 handler → subprocess 调 CLI
503
517
  ├── openclaw/ # OpenClaw Plugin
504
518
  │ ├── openclaw.plugin.json # manifest(contracts.tools)
505
519
  │ ├── package.json # 含 openclaw 块(pluginApi/SDK 版本)
506
- │ └── index.ts # definePluginEntry + registerTool ×57
520
+ │ └── index.ts # definePluginEntry + registerTool ×60
507
521
  ├── dsh/ # DeepSeek Harness (dsh) Plugin
508
522
  │ ├── cordis.patch.yml # bundle patch(insert 插件入口)
509
523
  │ ├── package.json # 含 dsh.bundle 块(bundle manifest)
510
- │ └── index.ts # cordis apply(ctx) + defineTool ×57
524
+ │ └── index.ts # cordis apply(ctx) + defineTool ×60
511
525
  │
512
526
  ├── tools/ # 共享 Python CLI 工具
513
527
  │ ├── stock_data.py # 行情 / 资金流 / 新闻 / 财务 / 短线情绪
@@ -609,3 +623,38 @@ CLI 使用:`python tools/screener.py screen --config my_filter.yaml --top 30`
609
623
  ## License
610
624
 
611
625
  MIT
626
+
627
+ ### 公告与港美股研究数据(#49–#51)
628
+
629
+ ```bash
630
+ python3 tools/value_data.py announcements 600519 --category forecast --start-date 2026-01-01 --end-date 2026-10-13 --top 50
631
+ python3 tools/stock_data.py financials 0700.HK --annual --periods 10
632
+ python3 tools/value_data.py valuation_history 0700.HK --years 10
633
+ # SEC_USER_AGENT 必须配置为应用名称 + 你的真实联系邮箱
634
+ python3 tools/sec_edgar.py holdings 0001067983
635
+ python3 tools/sec_edgar.py insider_trades AAPL --days 90 --top 10
636
+ ```
637
+
638
+ 公告类别为 `all/forecast/express/annual/interim/quarterly/reduction/issuance/inquiry/dividend`。默认最近 90 天,最多 500 条;通过巨潮官方股票目录取得 orgId,沪深京统一使用官方 `szse` 查询栏目。业绩快报和问询使用标题关键词查询。第一版返回 PDF 原文链接,不引入 PDF 解析依赖;`total/truncated` 表示供应商匹配数量及截断,查询无结果与请求失败分开。
639
+
640
+ 港股使用既有 `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 股,估值分位沿用正值样本算法,不拼接不同来源。
641
+
642
+ 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`。
643
+
644
+ Form 4 的 `days` 是申报日期窗口,`top=1..20` 限制文件数,返回全部已解析交易。保留多人联报、衍生品、交易代码、脚注、直接/间接持有和修订信息;仅 P/S 标为买/卖,其余行为不推断方向,价格未披露为 null。读取 `truncated/warnings`,原件与修订不要重复计数。风险组合工具 `screen_risk` 仍为 A 股专用。
645
+
646
+ 接口依据:[巨潮公告查询](https://www.cninfo.com.cn/new/commonUrl/pageOfSearch?url=disclosure/list/search)、[理杏仁港股财报](https://www.lixinger.com/api/open-api/html-doc/hk/company/fs/non_financial)、[理杏仁港股估值](https://www.lixinger.com/api/open-api/html-doc/hk/company/fundamental/non_financial)、[SEC API](https://www.sec.gov/search-filings/edgar-application-programming-interfaces)。
647
+
648
+ 股票 CIK 反查示例:
649
+
650
+ ```bash
651
+ python3 tools/sec_edgar.py holdings 0000320193 --mode issuer
652
+ # 原机构查询保持可用
653
+ python3 tools/sec_edgar.py holdings 0001067983 --mode manager
654
+ ```
655
+
656
+ 首次下载当前 SEC 包约 100 MB;ZIP 按周缓存,CUSIP 反查结果按天缓存,流式扫描不解压整个持仓表、不增加数据库依赖。返回 `report_date`(持仓日期)、`filing_window_end`(公开申报窗口截止)、`cusip_evidence`(原文映射依据),不把文件披露窗口当作持仓日期。`mapping_complete=false` 表示最近十份结构化 13D/G 可能未覆盖所有证券类别或 CUSIP 变更;缺映射直接报错,不做名称模糊匹配。`complete_for_mapped_cusips` 仅在该报告期没有未解决申报链时为 true,不代表实时全部股东。期权与本金持仓在 `positions` 保留,`shares` 合计只计无 PUT/CALL 的 SH 股票。不能将跨机构合计当作已去重的全市场持股。
657
+
658
+ 来源格式与实測依据见 [#51 数据研究](docs/research/issue-51-reverse-holdings.md)。
659
+
660
+ Hermes 的 `get_us_holdings` 子进程预算为 300 秒,允许首次下载批量包;其他 CLI 仍为 120 秒。机构查询优先寻找最新已知报告期的原始 13F:较新修订对应的原始版未找到时明确报错,历史分片仍未完全检索时返回 `history_truncated` 与警告。发行人 CUSIP 查询会跳过不可访问/无效 XML,继续核对后续原文;没有任何可验证映射时才报缺失。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "stock-analysis-plugin",
3
- "version": "0.2.5",
3
+ "version": "0.2.6",
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",
package/pi/index.ts CHANGED
@@ -22,11 +22,111 @@ export default (pi: ExtensionAPI) => {
22
22
  details: {},
23
23
  });
24
24
 
25
+ pi.registerTool({
26
+ name: "get_announcements",
27
+ description: "查询A股巨潮公告标题、日期、类型和原文PDF链接;按日期范围/类别筛选,默认近90天,top=1..500。第一版不提取正文,truncated提示截断。",
28
+ parameters: {
29
+ "type": "object",
30
+ "properties": {
31
+ "symbol": {
32
+ "type": "string",
33
+ "description": "A股代码"
34
+ },
35
+ "category": {
36
+ "type": "string",
37
+ "enum": [
38
+ "all",
39
+ "forecast",
40
+ "express",
41
+ "annual",
42
+ "interim",
43
+ "quarterly",
44
+ "reduction",
45
+ "issuance",
46
+ "inquiry",
47
+ "dividend"
48
+ ],
49
+ "description": "公告类别,默认all"
50
+ },
51
+ "start_date": {
52
+ "type": "string",
53
+ "description": "开始日期YYYY-MM-DD,默认结束日期前90天"
54
+ },
55
+ "end_date": {
56
+ "type": "string",
57
+ "description": "结束日期YYYY-MM-DD,默认今天"
58
+ },
59
+ "top": {
60
+ "type": "number",
61
+ "description": "最多条数1..500,默认50"
62
+ }
63
+ },
64
+ "required": [
65
+ "symbol"
66
+ ]
67
+ },
68
+ async execute(_id, p) {
69
+ const result = await py("value_data.py", ["announcements", p.symbol, "--category", p.category ?? "all", "--start-date", p.start_date ?? "", "--end-date", p.end_date ?? "", "--top", String(p.top ?? 50)]);
70
+ return asText(result.stdout);
71
+ },
72
+ });
73
+
74
+ pi.registerTool({
75
+ name: "get_us_holdings",
76
+ description: "查询SEC 13F:mode=auto默认有13F申报时查机构,否则按发行人CIK反查持仓机构;manager/issuer可显式指定。发行人通过官方13D/G精确映射CUSIP,扫描最新已发布13F窗口,处理重述/补充修订,返回实际报告期、截止日及映射覆盖。首次约100MB下载,后续缓存;无映射明确报错,不做名称猜测。需SEC_USER_AGENT含真实联系邮箱,不是实时或全部证券持仓。",
77
+ parameters: {
78
+ "type": "object",
79
+ "properties": {
80
+ "cik": {
81
+ "type": "string",
82
+ "description": "机构或发行人CIK,1..10位数字,如0001067983/0000320193"
83
+ },
84
+ "mode": {"type": "string", "enum": ["auto", "manager", "issuer"], "description": "默认auto;manager查机构组合,issuer反查发行人持仓机构"}
85
+ },
86
+ "required": [
87
+ "cik"
88
+ ]
89
+ },
90
+ async execute(_id, p) {
91
+ const result = await py("sec_edgar.py", ["holdings", p.cik, ...(p.mode ? ["--mode", p.mode] : [])]);
92
+ return asText(result.stdout);
93
+ },
94
+ });
95
+
96
+ pi.registerTool({
97
+ name: "get_insider_trades",
98
+ description: "查询美股发行人近期Form 4/4-A内部人交易(SEC官方XML),保留人员职务、交易代码、买卖方向、数量、价格、脚注和衍生品标志。需SEC_USER_AGENT含真实联系邮箱;days按申报日期筛选,top限制文件数,修订勿重复计数。",
99
+ parameters: {
100
+ "type": "object",
101
+ "properties": {
102
+ "symbol": {
103
+ "type": "string",
104
+ "description": "美股ticker或发行人CIK"
105
+ },
106
+ "days": {
107
+ "type": "number",
108
+ "description": "申报日期窗口1..365天,默认90"
109
+ },
110
+ "top": {
111
+ "type": "number",
112
+ "description": "最多解析Form 4文件数1..20,默认10"
113
+ }
114
+ },
115
+ "required": [
116
+ "symbol"
117
+ ]
118
+ },
119
+ async execute(_id, p) {
120
+ const result = await py("sec_edgar.py", ["insider_trades", p.symbol, "--days", String(p.days ?? 90), "--top", String(p.top ?? 10)]);
121
+ return asText(result.stdout);
122
+ },
123
+ });
124
+
25
125
  // --- Data Tools ---
26
126
 
27
127
  pi.registerTool({
28
128
  name: "get_valuation_history",
29
- description: "查询A/HK股票历史 PE-TTM/PB、当前正值分位和10/25/50/75/90分位 Band,返回实际采样区间;亏损估值分位为null。years=1..10,数据按天缓存。",
129
+ description: "查询A/HK股票历史PE-TTM/PB、当前正值分位和10/25/50/75/90分位Band,返回实际采样区间;亏损估值分位为null。years=1..10,按天缓存。HK配置LIXINGER_TOKEN时优先理杏仁非金融公司日历史,失败降级百度,不混接来源。",
30
130
  parameters: {
31
131
  "type": "object",
32
132
  "properties": {
@@ -308,7 +408,7 @@ export default (pi: ExtensionAPI) => {
308
408
  pi.registerTool({
309
409
  name: "get_financials",
310
410
  description:
311
- "获取股票财务摘要及历史趋势,按天缓存。A股返回ROE/毛利率/净利率等;annual=true与periods=10取十年年报,港股年度历史按数据源实际可得期数返回。估值历史用get_valuation_history,披露排期用get_earnings_calendar",
411
+ "获取股票财务摘要及历史趋势,按天缓存。A股annual=true与periods=10取十年年报;港股可配置LIXINGER_TOKEN取非金融公司财务序列,保留币种/披露日/实际财年,历史比率单位percent。有效Yahoo顶层快照按整组保留,currency为财报币种、market_cap_currency为市值币种、snapshot_source标明来源;缺失值及report_date不混入历史数值/日期。缺token或无权限降级原有来源并标注不足,不补造缺失。估值历史用get_valuation_history,披露排期用get_earnings_calendar",
312
412
  parameters: {
313
413
  type: "object",
314
414
  properties: {
@@ -722,7 +822,7 @@ export default (pi: ExtensionAPI) => {
722
822
  pi.registerTool({
723
823
  name: "screen_stocks",
724
824
  description:
725
- "全市场股票筛选(AlphaSift L1 多因子硬筛 + 市场情绪调节)。按PE/PB/市值/换手率/涨跌幅/量比等因子过滤和评分,可用 l2 开启质量/成长/动量/波动率/资金流增强",
825
+ "全市场股票筛选(AlphaSift L1 多因子硬筛 + 市场情绪调节)。按PE/PB/市值/换手率/涨跌幅/量比等因子过滤和评分,可用 l2 开启质量/成长/动量/波动率/资金流增强。显式筛选条件缺少数据时报error,filters_applied只列实际执行的条件",
726
826
  parameters: {
727
827
  type: "object",
728
828
  properties: {
@@ -762,7 +862,7 @@ export default (pi: ExtensionAPI) => {
762
862
  pi.registerTool({
763
863
  name: "run_backtest",
764
864
  description:
765
- "策略回测(AlphaEvo)。读取YAML策略定义,在历史数据上模拟交易,输出收益率/回撤/胜率等指标。只想知道单个技术信号的历史胜率用更轻量的 evaluate_signal",
865
+ "策略回测(AlphaEvo)。读取YAML策略定义,在历史数据上模拟交易,输出收益率/回撤/胜率等指标。只想知道单个技术信号的历史胜率用更轻量的 evaluate_signal。period为实际数据期间,requested_period保留请求期间,warnings提示覆盖差异;年化按实际期间计算",
766
866
  parameters: {
767
867
  type: "object",
768
868
  properties: {
@@ -1171,7 +1271,7 @@ export default (pi: ExtensionAPI) => {
1171
1271
  pi.registerTool({
1172
1272
  name: "screen_risk",
1173
1273
  description:
1174
- "A股风险专项筛查 — 检查估值、技术预警、解禁、减持、业绩预警、监管和行业政策,返回风险评级和 veto_buy。新闻搜索命中是待核实线索,不是已证实风险",
1274
+ "A股风险专项筛查 — 检查估值、技术预警、解禁、减持、业绩预警、监管和行业政策,返回风险评级和 veto_buy。新闻搜索命中是待核实线索,不是已证实风险。data_complete和warnings标明覆盖;数据不足时risk_level=unknown,risk_score或veto_buy可为null,不能视为低风险",
1175
1275
  parameters: {
1176
1276
  type: "object",
1177
1277
  properties: {
@@ -1466,7 +1566,7 @@ export default (pi: ExtensionAPI) => {
1466
1566
  pi.registerTool({
1467
1567
  name: "check_alert_rules",
1468
1568
  description:
1469
- "无状态告警规则检查 — 传入规则数组,返回当前是否触发。规则类型:price_below/price_above/change_pct_above/change_pct_below/volume_ratio_above/anomaly/risk_veto/risk_level_at_least。不做调度不存历史",
1569
+ "无状态告警规则检查 — 传入规则数组,返回当前是否触发。规则类型:price_below/price_above/change_pct_above/change_pct_below/volume_ratio_above/anomaly/risk_veto/risk_level_at_least。不做调度不存历史。依赖数据不可用时evaluated条目含error,meta.warnings提示缺失,triggered=false不代表检查成功",
1470
1570
  parameters: {
1471
1571
  type: "object",
1472
1572
  properties: {
@@ -1535,7 +1635,7 @@ export default (pi: ExtensionAPI) => {
1535
1635
  pi.registerTool({
1536
1636
  name: "evaluate_signals",
1537
1637
  description:
1538
- "评估到期信号:拉取记录日之后的日K,判定 target_hit/stop_hit/timeout 并计算收益,回写存储。记录建议用 record_signal,胜率复盘用 get_signal_summary",
1638
+ "评估到期信号:拉取记录日之后的日K,判定 target_hit/stop_hit/timeout 并计算收益,回写存储。记录建议用 record_signal,胜率复盘用 get_signal_summary。历史K线未覆盖记录日时skipped_no_data并保持未结算,不能用较新行情代替",
1539
1639
  parameters: {
1540
1640
  type: "object",
1541
1641
  properties: {
@@ -48,9 +48,9 @@
48
48
  "type": "object",
49
49
  "description": "风险筛查结果(来自 screen_risk)",
50
50
  "properties": {
51
- "risk_level": { "type": "string", "enum": ["low", "medium", "high"] },
52
- "risk_score": { "type": "integer", "minimum": 0, "maximum": 100 },
53
- "veto_buy": { "type": "boolean" },
51
+ "risk_level": { "type": "string", "enum": ["low", "medium", "high", "unknown"] },
52
+ "risk_score": { "type": ["integer", "null"], "minimum": 0, "maximum": 100 },
53
+ "veto_buy": { "type": ["boolean", "null"] },
54
54
  "flags": {
55
55
  "type": "array",
56
56
  "items": {
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- import { execSync } from "node:child_process";
2
+ import { execFileSync } from "node:child_process";
3
3
  import { existsSync } from "node:fs";
4
4
  import { join } from "node:path";
5
5
  import { fileURLToPath } from "node:url";
@@ -14,14 +14,14 @@ const venvDir = join(pkgDir, ".venv");
14
14
  const venvPython = venvPythonPath(pkgDir);
15
15
  const requirements = join(pkgDir, "tools", "requirements.txt");
16
16
 
17
- function run(cmd) {
18
- execSync(cmd, { stdio: "inherit", timeout: 1_800_000 });
17
+ function run(bin, args) {
18
+ execFileSync(bin, args, { stdio: "inherit", timeout: 1_800_000 });
19
19
  }
20
20
 
21
21
  function findPython() {
22
22
  for (const name of ["python3", "python"]) {
23
23
  try {
24
- const ver = execSync(`${name} --version`, { stdio: "pipe" }).toString().trim();
24
+ const ver = execFileSync(name, ["--version"], { stdio: "pipe" }).toString().trim();
25
25
  const match = ver.match(/(\d+)\.(\d+)/);
26
26
  if (match && (parseInt(match[1]) > 3 || (parseInt(match[1]) === 3 && parseInt(match[2]) >= 10))) {
27
27
  return name;
@@ -42,10 +42,10 @@ try {
42
42
  }
43
43
 
44
44
  if (!existsSync(venvDir)) {
45
- run(`${python} -m venv "${venvDir}"`);
45
+ run(python, ["-m", "venv", venvDir]);
46
46
  }
47
47
 
48
- run(`"${venvPython}" -m pip install -q -r "${requirements}"`);
48
+ run(venvPython, ["-m", "pip", "install", "-q", "-r", requirements]);
49
49
  } catch (err) {
50
50
  console.warn(
51
51
  `\n[pi-stock-analysis] Python setup failed: ${err.message}\n` +
@@ -1,24 +1,30 @@
1
1
  ---
2
2
  name: bull-trend
3
- description: 趋势追踪分析:识别中长期趋势、所处阶段和离场条件。用于多头排列、上升通道或持有趋势股。
3
+ description: 趋势交易:识别中长期趋势,制定入场、持仓和退出规则。用于趋势股持有、规则化趋势策略或肥尾收益分析。
4
4
  ---
5
5
 
6
6
  # 趋势追踪分析
7
7
 
8
8
  ## 核心理念
9
9
 
10
- 趋势追踪的核心是"顺势而为"——在确认趋势形成后入场,在趋势转弱时离场。不预测顶底,只跟随趋势。
10
+ 趋势追踪用可执行的规则参与趋势,通过控制试错损失、保留盈利空间捕获少数大行情。肥尾描述收益分布,趋势描述价格路径;肥尾指标不是趋势启动或延续信号。
11
+
12
+ 用户询问塔勒布、肥尾计算、极端行情或策略是否依赖少数大盈利时,先读取 [肥尾度量与趋势收益诊断](references/fat-tails.md)。概念问题直接解释方法;需要具体统计结果时,按参考中的数据口径准备输入并调用 `scripts/tail_analysis.py`。普通趋势判断无需加载这份参考。
13
+
14
+ 仅解释肥尾概念时,到此完成;下述流程用于具体标的的趋势分析。
11
15
 
12
16
  ## 执行流程
13
17
 
14
18
  ### 1. 采集数据
15
19
 
16
- 运行数据采集脚本获取 120 根日K线及技术指标:
20
+ 运行数据采集脚本获取 120 根日K线及技术指标(相对本 skill 目录执行):
17
21
 
18
22
  ```bash
19
23
  python3 scripts/gather.py <symbol>
20
24
  ```
21
25
 
26
+ 确认数据日期、周期和复权口径;120 根日K线用于近期趋势判断。肥尾分支按参考文件另取历史收益,报告实际取得的区间和样本量。
27
+
22
28
  ### 2. 趋势确认
23
29
 
24
30
  **多头趋势确认条件**:
@@ -32,26 +38,44 @@ python3 scripts/gather.py <symbol>
32
38
  - MACD 在零轴之下运行
33
39
  - 价格沿下降通道运行
34
40
 
41
+ 报告哪些条件已满足、哪些尚未满足,并给出对应数值或价格位置。空头趋势对仅能做多的股票账户意味着退出或观望;做空建议须有对应市场和账户能力。
42
+
35
43
  ### 3. 趋势阶段判断
36
44
 
37
45
  | 阶段 | 特征 | 操作 |
38
46
  |------|------|------|
39
- | 启动期 | 均线粘合后向上发散,放量突破 | 建仓 |
40
- | 加速期 | 价格加速上涨,远离均线 | 持有,注意高位风险 |
41
- | 成熟期 | 涨幅放缓,量能递减 | 逐步减仓 |
42
- | 衰退期 | 跌破 MA20 或趋势线 | 清仓 |
47
+ | 启动期 | 均线粘合后向上发散,放量突破 | 检查入场触发和初始风险 |
48
+ | 加速期 | 价格加速上涨,远离均线 | 按持仓规则跟踪,更新保护位 |
49
+ | 成熟期 | 涨幅放缓,量能递减 | 检查退出条件,阶段标签本身不触发减仓 |
50
+ | 衰退期 | 跌破预先选定的均线或趋势支撑 | 按退出规则执行 |
43
51
 
44
52
  ### 4. 关键指标
45
53
 
46
54
  - **ADX 替代**:用 MA 斜率和排列程度衡量趋势强度
47
55
  - **趋势线**:连接近期低点作为上升趋势线
48
- - **回调幅度**:健康回调通常不超过前一波涨幅的 38.2%-50%
56
+ - **回调幅度**:描述相对前一波涨幅的回撤及是否破坏支撑;斐波那契比例只作为观察位置,不能单独证明回调健康。
57
+
58
+ ### 5. 形成交易规则
59
+
60
+ 先读取 [短线交易决策框架](../stock-analysis/references/short-term-trading.md)的风险单位和市场成交约束,再形成同一套入场、持仓和退出规则:
61
+
62
+ - **入场**:指定周期、触发条件、判断时点和成交假设。例如收盘突破此前 20 根K线最高价,阈值排除当前K线;历史检验使用信号产生后可成交的价格。
63
+ - **初始风险**:给出初始止损、单笔风险预算和仓位。按预算 / 入场到止损的每股损失估算数量,并受资金、交易单位和组合风险限制;跳空和无法成交可能使实际亏损超过预算。
64
+ - **持仓**:趋势条件持续满足时保留盈利空间。保护位随有利走势更新,做多止损只上移;涨幅大或收益处于高分位本身不构成退出条件。
65
+ - **退出**:明确采用均线失效、通道破位或移动止损中的哪一种、如何触发。固定止盈属于可选策略约束,要说明它可能截断大盈利;参数是待检验假设,不归为塔勒布公式。
66
+
67
+ 规则完成标准:每项都有可核验的触发条件,说明下一次观察时点,以及触发后动作。用户已有规则时按其规则评价,调整另列为建议。
68
+
69
+ ### 6. 按需检验
70
+
71
+ 用户要求历史验证时使用 [策略回测](../strategy-backtest/SKILL.md)。先核对现有 DSL 能否表达规则,无法表达的条件标为未验证;不以近似规则冒充原策略。趋势收益的利润集中度诊断按肥尾参考文件执行。
49
72
 
50
73
  ## 输出要求
51
74
 
52
75
  分析完成后输出:
53
76
  1. 当前趋势方向和阶段
54
- 2. 趋势强度评分(1-10)
77
+ 2. 趋势证据和未满足条件
55
78
  3. 关键趋势支撑/压力位
56
79
  4. 入场/持有/离场建议
57
- 5. 止损位建议
80
+ 5. 初始风险、保护位和退出触发条件
81
+ 6. 数据或成交限制;肥尾分支附计算口径和不确定性
@@ -0,0 +1,91 @@
1
+ # 肥尾度量与趋势收益诊断
2
+
3
+ 本参考供趋势 skill 和趋势策略回测按需读取。数值由本 skill 的 [计算脚本](../scripts/tail_analysis.py) 执行,无需独立工具注册。保留输入、运行参数和输出;没有执行环境或数据时只解释方法,数值标为未计算。
4
+
5
+ ## 调用脚本
6
+
7
+ 从插件根目录使用安装了现有 numpy 依赖的 Python 运行(POSIX 通常为 `.venv/bin/python3`,Windows 为 `.venv/Scripts/python.exe`):
8
+
9
+ ```bash
10
+ python skills/bull-trend/scripts/tail_analysis.py returns historical-returns.json --n 2 10 30 --draws 20000 --seed 42
11
+ python skills/bull-trend/scripts/tail_analysis.py returns historical-returns.json --current 0.05
12
+ python skills/bull-trend/scripts/tail_analysis.py trades backtest-result.json
13
+ ```
14
+
15
+ `returns` 输入是同周期历史对数收益的 JSON 数组,如 `[0.01, -0.02, 0.005]`,以小数表示;`--current` 的当前收益另传,必须从历史输入中排除。脚本不转换价格、不抓行情、不识别日期,因此先按下文校验并记录数据口径。`trades` 输入是含完整 `trades` 数组的回测 JSON。脚本 stdout 输出 JSON,失败返回 `error` 并以非零状态退出。
16
+
17
+ κ 默认 n0 = 1,以固定种子做 iid 经验重抽样,输出每个 n 的 κ 和平均绝对偏差;换种子重复运行检查 Monte Carlo 波动,换历史窗口检查数据敏感性。输出没有总体置信区间。`sample_count` 是历史收益数量,`draws` 是模拟轮数,两者不能混称样本量。`current_event.percentile` 为 0..1,`upper_exceedances` / `lower_exceedances` 是历史严格超过 / 低于当前收益的次数。
18
+
19
+ ## 先确定分析对象
20
+
21
+ | 用户问题 | 分析对象 | 可交付结论 |
22
+ |---|---|---|
23
+ | 收益分布有多肥尾 | 固定周期的历史收益 | 样本尾部特征、κ 的条件性估计 |
24
+ | 当前涨跌是否极端 | 当前收益与此前同周期收益 | 历史分位或阈值超越,不能推导后续方向 |
25
+ | 趋势系统是否靠大赢家 | 策略平仓盈亏 | 盈利集中度及移除大赢家后的敏感性 |
26
+
27
+ 市场收益的厚尾、策略收益的正偏和趋势延续是不同性质。塔勒布的度量回答统计稳定性问题;下文的分位和盈利贡献是本项目的诊断方法,不称为塔勒布交易信号。
28
+
29
+ ## 数据口径
30
+
31
+ 使用 `get_kline` 或现有 `stock_data.py kline`,核对实际返回的日期范围、周期、数量和复权标记。股票历史价格保持一致复权口径,指数保持原始点位;先处理乱序、重复日期和无效价格,说明停牌或缺失导致的时间间隔,保留真实极端收益。
32
+
33
+ 默认分析对数收益 `r_t = log(P_t / P_{t-1})`,仅使用正价格。日、周收益分别计算;周收益从周末价格或同一周日对数收益之和取得,避免把重叠多日收益当作独立样本。策略盈利贡献使用货币盈亏,不混用价格收益。
34
+
35
+ 申请多年的同口径历史,报告实际样本量;120 根日K线只能给出短窗口描述。不存在通用的“够用样本数”;长历史也可能混合不同制度或波动阶段,按分段结果检查稳定性。
36
+
37
+ ## 当前事件的历史分位
38
+
39
+ 以当前事件之前的同周期收益 `r_1,...,r_N` 为参考,对当前收益 `r_*` 计算经验分位:
40
+
41
+ ```text
42
+ F_hat(r_*) = count(r_i <= r_*) / N
43
+ ```
44
+
45
+ 报告单侧方向、参考区间、N 和超越次数。例如当前上涨高于历史样本的 99% 分位,仅说明它相对该样本少见。样本之外的事件频率不可由零超越次数认定为零;回测每个时点只使用此前数据计算阈值。
46
+
47
+ ## 塔勒布的 κ:有限样本聚合速度
48
+
49
+ 来源:[Taleb, How Much Data Do You Need? A Pre-asymptotic Metric for Fat-tailedness](https://arxiv.org/html/1802.05495),Definition 1、Equation (1) 和 III-B。
50
+
51
+ 设 `X_i` 独立同分布且具有有限绝对一阶矩:
52
+
53
+ ```text
54
+ S_n = sum(X_i, i=1..n)
55
+ M(n) = E[abs(S_n - E[S_n])]
56
+ kappa(n0, n) = 2 - log(n/n0) / log(M(n)/M(n0)), n > n0 >= 1
57
+ ```
58
+
59
+ `M(n)` 是 n 项之和相对其均值的平均绝对偏差,不是中位数绝对偏差,也不是 n 项均值的偏差。高斯分布满足 `M(n)/M(n0) = sqrt(n/n0)`,因此 κ = 0。在论文适用的分布中,较高 κ 表示增加样本带来的均值稳定性改善较慢;κ 与 n0、n 有关。
60
+
61
+ 脚本计算的是**基于历史经验分布的条件性估计**:用历史均值中心化后计算 `M_hat(1)`,有放回独立抽样 n 项相加,以绝对和值的模拟均值估计 `M_hat(n)`,代入 n0 = 1 的公式。
62
+
63
+ 零离散度或零对数分母时,脚本返回 `kappa: null` 和 `unavailable_reason`。估计超出预期范围时报告原值并检查假设和数值稳定性,不强行裁剪到 [0,1]。
64
+
65
+ 股价收益可能具有自相关、波动聚集和制度变化,独立抽样会抹去时间结构。按真实连续时间聚合或使用块抽样时,应将结果标为包含时间依赖的描述性统计,与原论文的 iid κ 区分。仅重抽历史不能创造尚未出现的极端事件,也不能证明总体尾部已被充分观测。
66
+
67
+ κ 不能区分获利方向,不能预测趋势启动。论文中 κ > 0.15 是对正态近似可靠性的启发式提醒,不是入场、止盈或“已到肥尾”的通用阈值。
68
+
69
+ ## 趋势策略的盈利集中度
70
+
71
+ 来源:[CFM, Making fat right tails fatter with trend following… most of the time](https://www.cfm.com/making-fat-right-tails-fatter-with-trend-following-most-of-the-time/)。趋势追踪的凸性和正偏依赖策略与时间尺度;单次跳空或快速反转未必能被系统捕获。
72
+
73
+ 使用 `run_backtest` 返回的 `trades`,仅取 `type == "sell"` 的平仓记录,以 `pnl` 的货币金额计算;`pnl_pct` 是小数比例,不能当百分数或与货币盈亏相加。先确认返回结果是否完整、是否存在未平仓头寸以及费用覆盖口径。
74
+
75
+ ```text
76
+ G = sum(max(pnl_i, 0))
77
+ L = sum(min(pnl_i, 0))
78
+ T = G + L
79
+ C_k = 最大 k 笔正盈利之和 / G
80
+ T_without_k = T - 最大 k 笔正盈利之和
81
+ ```
82
+
83
+ 默认报告最大 1 笔和最大 3 笔,正盈利笔数不足时使用实际数量并注明。G = 0 时集中度不可计算;同时报告交易笔数、G、L、最差单笔及回测已有的最大回撤。使用 G 作分母,避免总净利润接近零时比率失真。
84
+
85
+ `T_without_k` 是已实现盈亏的删除敏感性分析,保留其余交易金额不变;它不是删除交易后重新模拟的资金曲线或收益率。未平仓盈亏另列,不能把 T 当作账户总收益。少数赢家贡献高符合某些趋势系统的结构,但不能单凭这一点证明策略有效或失效;结合成本、回撤、不同区间和样本外表现评价。
86
+
87
+ 现有回测有固定止盈默认值;省略 `take_profit` 不会关闭止盈。验证保留右尾的退出规则前,检查实际引擎和 DSL 的支持情况,将无法表达的规则明确列为未验证。
88
+
89
+ ## 完成标准
90
+
91
+ 报告指出分析对象、数据来源及区间、周期、复权口径、样本量、公式与估计方法、实际数值或未计算原因。κ 结果还需注明 n0、n、抽样假设和敏感性;盈利集中度需注明平仓与未平仓口径。交易建议依据趋势和风险规则,统计结果仅提供其能支持的证据。