stock-analysis-plugin 0.2.3 → 0.2.5
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 +53 -11
- package/package.json +1 -1
- package/pi/index.ts +185 -9
- package/skills/event-driven/SKILL.md +6 -0
- package/skills/growth-quality/SKILL.md +6 -0
- package/skills/stock-analysis/SKILL.md +22 -0
- package/skills/stock-screener/SKILL.md +18 -0
- package/skills/strategy-backtest/SKILL.md +2 -0
- package/tools/_cache.py +61 -0
- package/tools/capabilities.py +9 -0
- package/tools/diagnostics.py +6 -0
- package/tools/screener.py +54 -2
- package/tools/stock_data.py +241 -99
- package/tools/value_data.py +1368 -0
package/README.md
CHANGED
|
@@ -32,7 +32,7 @@ A 股 / 港股 / 美股 / 日股 / 韩股 / 台股综合分析、多因子选股
|
|
|
32
32
|
|
|
33
33
|
## 功能概览
|
|
34
34
|
|
|
35
|
-
- **
|
|
35
|
+
- **57 个工具** — 行情数据、技术分析、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 启动后自动加载并注册
|
|
96
|
+
OpenClaw Gateway 启动后自动加载并注册 57 个 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 组合,注册
|
|
107
|
+
作为 dsh bundle 安装:`dsh plugin add` 会把 `cordis.patch.yml` 叠加进 profile 组合,注册 57 个 tool + 20 个 skill。postinstall 自动建 `.venv`(pnpm 需在 profile 的 `pnpm-workspace.yaml` 里给本包配 `allowBuilds`,否则回退系统 `python3`)。
|
|
108
108
|
|
|
109
109
|
详见 [`dsh/README.md`](dsh/README.md)。
|
|
110
110
|
|
|
@@ -236,7 +236,13 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
|
|
|
236
236
|
|
|
237
237
|
| 工具 | 说明 |
|
|
238
238
|
|------|------|
|
|
239
|
-
| `
|
|
239
|
+
| `get_valuation_history` | A/HK PE-TTM/PB 历史、正值分位与估值 Band,实际采样窗口 |
|
|
240
|
+
| `get_index_valuation` | 中国指数 PE/PB 历史水位;中证官方多年滚动 PE;可选理杏仁补充 PB |
|
|
241
|
+
| `get_earnings_calendar` | A 股报告期披露与业绩预告;HK 已公告业绩审批董事会排期/供应商备选日期 |
|
|
242
|
+
| `get_shareholder_structure` | A 股股东户数/十大流通股东变化/报告期北向名义持股;HK 南向持股 |
|
|
243
|
+
| `get_etf_details` | A 股 ETF 净值折溢价、规模变动、披露持仓、可选基准成分与跟踪误差 |
|
|
244
|
+
| `get_dividends` | A/HK 历史分红/除息日历/已实现 TTM 股息与连续年数;A/HK 报告期/年度排行 |
|
|
245
|
+
| `get_kline` | K 线数据(OHLCV),支持日/周/月线;A 股股票/ETF 前复权,每条记录 `adjusted=qfq`,指数 `adjusted=none` |
|
|
240
246
|
| `get_quote` | 实时行情快照(非交易时段返回最近交易日收盘价并以 as_of/stale 标注;ETF 的 premium_discount_rate 为正=溢价、负=折价) |
|
|
241
247
|
| `get_capital_flow` | 资金流向(仅 A 股) |
|
|
242
248
|
| `get_news` | 个股相关新闻 |
|
|
@@ -381,11 +387,11 @@ position:
|
|
|
381
387
|
|
|
382
388
|
## 市场路由规则
|
|
383
389
|
|
|
384
|
-
| 代码格式 | 示例 | 市场 |
|
|
390
|
+
| 代码格式 | 示例 | 市场 | 行情报价 Failover 链(K 线差异见下方) |
|
|
385
391
|
|----------|------|------|---------------------|
|
|
386
392
|
| 6 位纯数字 | `600519`, `000001`, `300750` | A 股 | akshare → tushare → efinance → 腾讯 → 新浪 → pytdx → baostock |
|
|
387
393
|
| 6 位纯数字(51/52/56/58/15/16/18 开头) | `510300`, `159915` | A 股 ETF | akshare(基金接口)→ tushare → efinance → 腾讯 → 新浪 → pytdx → baostock |
|
|
388
|
-
| 带交易所前缀(`sh`/`sz`/`bj` + 6 位数字) | `sh000001`(上证指数), `sz399006`(创业板指) | A 股(显式指定,含指数) | 腾讯 →
|
|
394
|
+
| 带交易所前缀(`sh`/`sz`/`bj` + 6 位数字) | `sh000001`(上证指数), `sz399006`(创业板指) | A 股(显式指定,含指数) | 腾讯 → 新浪 |
|
|
389
395
|
| `.HK` 结尾 | `00700.HK`, `09988.HK` | 港股 | yfinance → finnhub → longbridge |
|
|
390
396
|
| 英文字母 | `AAPL`, `GOOGL`, `TSLA` | 美股 | yfinance → finnhub → longbridge → alphavantage |
|
|
391
397
|
| `.T` 结尾 | `7203.T` | 日股 | yfinance |
|
|
@@ -394,9 +400,43 @@ position:
|
|
|
394
400
|
|
|
395
401
|
> 各数据源按优先级自动尝试,前一个失败后自动切换到下一个。未配置相关 env var 的数据源会被跳过。
|
|
396
402
|
> 裸 6 位代码一律按**个股**处理(`000001` 是平安银行);指数需带交易所前缀(`sh000001` = 上证指数),显式前缀代码直接走腾讯/新浪(东财源只认裸代码)。
|
|
403
|
+
> **A 股 K 线口径**:股票/ETF 仅接受前复权数据,链路为 akshare → tushare(仅股票)→ efinance → 腾讯(仅 qfq 数据)→ baostock;带前缀的股票/ETF 先去前缀再走同一链路。新浪和 pytdx 的未复权 K 线不参与股票/ETF 容灾。显式指数 `sh000xxx` / `sz399xxx` 保留原始点位,走腾讯 → 新浪 → baostock。上述路由表的完整链路仍适用于实时行情。
|
|
404
|
+
> 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)。
|
|
397
405
|
> **粘性优选**:A 股链路(K 线 / 行情 / 市场快照 / 板块成分)会记住最近一次成功的数据源(缓存在系统临时目录,24h 有效),下次调用优先从它开始;若它已失效则自动顺延并更新记录。港美股链路不做粘性——一次 yfinance 瞬时失败不应让后续全天的 quote 降质。
|
|
398
406
|
> 日/韩/台股仅 yfinance 一个数据源(免费数据延迟约 15 分钟);港股 / 美股 / 日股 / 韩股 / 台股的 ETF 与其所在市场股票走相同链路。
|
|
399
407
|
|
|
408
|
+
|
|
409
|
+
## 低频价投与增量数据
|
|
410
|
+
|
|
411
|
+
```bash
|
|
412
|
+
python tools/value_data.py valuation_history 600519 --years 5
|
|
413
|
+
python tools/stock_data.py financials 600519 --annual --periods 10
|
|
414
|
+
python tools/value_data.py earnings_calendar --report-date 2026-09-30 --symbol 600519
|
|
415
|
+
python tools/value_data.py shareholder_structure 600519 --report-date 2026-06-30
|
|
416
|
+
python tools/value_data.py shareholder_structure 0700.HK
|
|
417
|
+
python tools/value_data.py index_valuation 000300 --years 5
|
|
418
|
+
python tools/value_data.py etf_details 510300 --benchmark sh000300 --days 60
|
|
419
|
+
python tools/value_data.py etf_details 510300 --include-full-holdings
|
|
420
|
+
python tools/stock_data.py margin_trading 600519 --days 10 --include-ratio
|
|
421
|
+
python tools/value_data.py dividends --symbol 600519
|
|
422
|
+
python tools/value_data.py dividends --symbol 0700.HK --mode calendar
|
|
423
|
+
python tools/value_data.py dividends --mode ranking --report-date 2025-12-31
|
|
424
|
+
python tools/value_data.py dividends --mode ranking --market HK --report-date 2025-12-31
|
|
425
|
+
python tools/value_data.py earnings_calendar --symbol 0700.HK
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
财报、基本信息及估值/股东/ETF/分红等慢变数据缓存到 `~/.stock-analysis/cache`,TTL 一天;板块成分/映射一周。行情报价不缓存。缓存文件原子替换,过期/损坏重拉,错误和显式部分失败不缓存;不以过期数据伪装最新数据。原有临时目录的粘性路由和反向成分缓存保留。
|
|
429
|
+
|
|
430
|
+
估值使用可得数据的正值样本分位(`<=当前值`),返回 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 按源实际可得年数返回,不补造缺失比率。
|
|
431
|
+
|
|
432
|
+
股东数据保留报告期、公告日或港交所披露日: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`。日期转为香港日期,公告表也不承诺覆盖所有港股。
|
|
433
|
+
|
|
434
|
+
ETF 使用披露资产规模历史(元)与披露持仓,保留持仓原始证券代码,不冒充实时完整申赎篮子;新增 `basket` 返回沪深交易所发布的完整当日 PCF(跨境代码原样保留),包含申赎单位、每篮子证券数量、现金替代规则与比例;校验基金代码、实际日期和全部组件数量,失败只提示不可用,不冒充完整。PCF 是申赎对价,不是实际持仓,证券数量也不是净值权重。`include_full_holdings=true` 时另取最近可得半年度/年度披露股票表,显式指定年份/月并请求较高行数上限,包含股票数量(股)、市值(人民币元)和实际报告期;返回全部收到的表格行,但不声称覆盖债券/现金等全资产或实时持仓,也不以 PCF 数量验证实际持仓。默认不取数百行明细。提供 `benchmark` 可另查基准指数成分。净值折溢价仅在行情/净值日期相同才计算,IOPV 折溢价另列。跟踪误差使用相同连续交易日区间的基金日净值增长与基准收盘收益差,取样本标准差乘 `sqrt(252)`,不填补缺失日期、不猜测基准。两融占比只匹配同一天的人民币元成交额,缺失则 null。
|
|
435
|
+
|
|
436
|
+
股息历史将预案与已实施分红分开,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填充。
|
|
437
|
+
|
|
438
|
+
数据源参考:[AKShare股票接口](https://akshare.akfamily.xyz/data/stock/stock.html)、[指数接口](https://github.com/akfamily/akshare/blob/main/docs/data/index/index.md)、[基金接口](https://github.com/akfamily/akshare/blob/main/docs/data/fund/fund_public.md)、[港交所南向持股](https://www.hkexnews.hk/sdw/search/mutualmarket.aspx?t=hk)、[HKEX 年度股息率](https://www.hkex.com.hk/Listing/Sustainability/Shareholder-Value-in-Focus/Dividend-Yield-Ratio?sc_lang=en)、[理杏仁指数基本面接口](https://www.lixinger.com/api/open-api/html-doc/cn/index/fundamental)。
|
|
439
|
+
|
|
400
440
|
## 独立 CLI 使用
|
|
401
441
|
|
|
402
442
|
Python 工具可脱离 Agent 独立使用,所有输出为 JSON:
|
|
@@ -454,26 +494,28 @@ GitHub Actions 的 `e2e-host` 使用 Pi、Hermes、OpenClaw、dsh 的真实运
|
|
|
454
494
|
```
|
|
455
495
|
stock-analysis/
|
|
456
496
|
├── pi/ # Pi Agent Extension
|
|
457
|
-
│ └── index.ts # 注册
|
|
497
|
+
│ └── index.ts # 注册 57 个工具 + 20 个 skill
|
|
458
498
|
├── hermes/ # Hermes Agent Plugin
|
|
459
499
|
│ ├── plugin.yaml # 插件清单
|
|
460
500
|
│ ├── __init__.py # register(ctx) 入口
|
|
461
501
|
│ ├── schemas.py # 工具 JSON Schema 定义
|
|
462
|
-
│ └── tools.py #
|
|
502
|
+
│ └── tools.py # 57 个 handler → subprocess 调 CLI
|
|
463
503
|
├── openclaw/ # OpenClaw Plugin
|
|
464
504
|
│ ├── openclaw.plugin.json # manifest(contracts.tools)
|
|
465
505
|
│ ├── package.json # 含 openclaw 块(pluginApi/SDK 版本)
|
|
466
|
-
│ └── index.ts # definePluginEntry + registerTool ×
|
|
506
|
+
│ └── index.ts # definePluginEntry + registerTool ×57
|
|
467
507
|
├── dsh/ # DeepSeek Harness (dsh) Plugin
|
|
468
508
|
│ ├── cordis.patch.yml # bundle patch(insert 插件入口)
|
|
469
509
|
│ ├── package.json # 含 dsh.bundle 块(bundle manifest)
|
|
470
|
-
│ └── index.ts # cordis apply(ctx) + defineTool ×
|
|
510
|
+
│ └── index.ts # cordis apply(ctx) + defineTool ×57
|
|
471
511
|
│
|
|
472
|
-
├── tools/ # 共享 Python CLI
|
|
512
|
+
├── tools/ # 共享 Python CLI 工具
|
|
473
513
|
│ ├── stock_data.py # 行情 / 资金流 / 新闻 / 财务 / 短线情绪
|
|
474
514
|
│ ├── signal_tracker.py # AI 买卖建议回测闭环(本地 JSONL 存储)
|
|
475
515
|
│ ├── technical.py # 技术指标分析
|
|
476
516
|
│ ├── pattern.py # K 线形态识别
|
|
517
|
+
│ ├── value_data.py # 估值/财报日历/股东/ETF/股息
|
|
518
|
+
│ ├── _cache.py # 用户目录 TTL 缓存
|
|
477
519
|
│ ├── screener.py # 全市场多因子筛选(含市场情绪调节,--l2 量化增强)
|
|
478
520
|
│ ├── backtest.py # 策略回测引擎
|
|
479
521
|
│ ├── volume_analysis.py # 量价分析
|
package/package.json
CHANGED
package/pi/index.ts
CHANGED
|
@@ -24,10 +24,183 @@ export default (pi: ExtensionAPI) => {
|
|
|
24
24
|
|
|
25
25
|
// --- Data Tools ---
|
|
26
26
|
|
|
27
|
+
pi.registerTool({
|
|
28
|
+
name: "get_valuation_history",
|
|
29
|
+
description: "查询A/HK股票历史 PE-TTM/PB、当前正值分位和10/25/50/75/90分位 Band,返回实际采样区间;亏损估值分位为null。years=1..10,数据按天缓存。",
|
|
30
|
+
parameters: {
|
|
31
|
+
"type": "object",
|
|
32
|
+
"properties": {
|
|
33
|
+
"symbol": {
|
|
34
|
+
"type": "string",
|
|
35
|
+
"description": "A股代码或港股.HK代码"
|
|
36
|
+
},
|
|
37
|
+
"years": {
|
|
38
|
+
"type": "number",
|
|
39
|
+
"description": "历史窗口年数1..10,默认5"
|
|
40
|
+
}
|
|
41
|
+
},
|
|
42
|
+
"required": [
|
|
43
|
+
"symbol"
|
|
44
|
+
]
|
|
45
|
+
},
|
|
46
|
+
async execute(_id, p) {
|
|
47
|
+
const result = await py("value_data.py", ["valuation_history", p.symbol, "--years", String(p.years ?? 5)]);
|
|
48
|
+
return asText(result.stdout);
|
|
49
|
+
},
|
|
50
|
+
});
|
|
51
|
+
|
|
52
|
+
pi.registerTool({
|
|
53
|
+
name: "get_index_valuation",
|
|
54
|
+
description: "查询中国指数估值历史分位与Band;乐咕乐股PE/PB优先,中证官方历史补充滚动PE并保留近期PE1口径。缺PB时可用LIXINGER_TOKEN补充理杏仁mcw历史,来源与算法分别标明,不混接同一指标。",
|
|
55
|
+
parameters: {
|
|
56
|
+
"type": "object",
|
|
57
|
+
"properties": {
|
|
58
|
+
"symbol": {
|
|
59
|
+
"type": "string",
|
|
60
|
+
"description": "指数代码或名称,如000300、沪深300、000985"
|
|
61
|
+
},
|
|
62
|
+
"years": {
|
|
63
|
+
"type": "number",
|
|
64
|
+
"description": "历史窗口年数1..10,默认5"
|
|
65
|
+
}
|
|
66
|
+
},
|
|
67
|
+
"required": [
|
|
68
|
+
"symbol"
|
|
69
|
+
]
|
|
70
|
+
},
|
|
71
|
+
async execute(_id, p) {
|
|
72
|
+
const result = await py("value_data.py", ["index_valuation", p.symbol, "--years", String(p.years ?? 5)]);
|
|
73
|
+
return asText(result.stdout);
|
|
74
|
+
},
|
|
75
|
+
});
|
|
76
|
+
|
|
77
|
+
pi.registerTool({
|
|
78
|
+
name: "get_earnings_calendar",
|
|
79
|
+
description: "查询财报日历:A股report_date必填季度期末,返回预约/修订/实际披露与业绩预告;HK需symbol,优先HKEX已公告业绩审批董事会排期(不是实际披露日),缺失时返回供应商日期。HK可按已知财政期末过滤,未知期次另列。",
|
|
80
|
+
parameters: {
|
|
81
|
+
"type": "object",
|
|
82
|
+
"properties": {
|
|
83
|
+
"report_date": {
|
|
84
|
+
"type": "string",
|
|
85
|
+
"description": "A股必填季度期末YYYY-MM-DD;HK可选已公告财政期末,未知期次另列"
|
|
86
|
+
},
|
|
87
|
+
"symbol": {
|
|
88
|
+
"type": "string",
|
|
89
|
+
"description": "A股代码可选(省略查全市场);HK必须提供港股.HK代码"
|
|
90
|
+
},
|
|
91
|
+
"top": {
|
|
92
|
+
"type": "number",
|
|
93
|
+
"description": "每类最多返回条数1..500,默认50"
|
|
94
|
+
}
|
|
95
|
+
},
|
|
96
|
+
"required": []
|
|
97
|
+
},
|
|
98
|
+
async execute(_id, p) {
|
|
99
|
+
const result = await py("value_data.py", ["earnings_calendar", "--report-date", p.report_date ?? "", "--symbol", p.symbol ?? "", "--top", String(p.top ?? 50)]);
|
|
100
|
+
return asText(result.stdout);
|
|
101
|
+
},
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
pi.registerTool({
|
|
105
|
+
name: "get_shareholder_structure",
|
|
106
|
+
description: "查询A股股东户数、十大流通股东变化及沪深交易所季度北向合计持股;官方总量优先,十大HKSCC名义持股仅兜底且标明口径。HK返回港交所南向记录。缺失不当零,期末不等于已公布。",
|
|
107
|
+
parameters: {
|
|
108
|
+
"type": "object",
|
|
109
|
+
"properties": {
|
|
110
|
+
"symbol": {
|
|
111
|
+
"type": "string",
|
|
112
|
+
"description": "A股代码或港股.HK代码"
|
|
113
|
+
},
|
|
114
|
+
"report_date": {
|
|
115
|
+
"type": "string",
|
|
116
|
+
"description": "A股报告期YYYY-MM-DD;省略时北向使用最新已公布季度,十大股东使用最新财报期;HK忽略"
|
|
117
|
+
}
|
|
118
|
+
},
|
|
119
|
+
"required": [
|
|
120
|
+
"symbol"
|
|
121
|
+
]
|
|
122
|
+
},
|
|
123
|
+
async execute(_id, p) {
|
|
124
|
+
const result = await py("value_data.py", ["shareholder_structure", p.symbol, "--report-date", p.report_date ?? ""]);
|
|
125
|
+
return asText(result.stdout);
|
|
126
|
+
},
|
|
127
|
+
});
|
|
128
|
+
|
|
129
|
+
pi.registerTool({
|
|
130
|
+
name: "get_etf_details",
|
|
131
|
+
description: "查询A股ETF净值折溢价、规模、披露持仓及沪深完整PCF申赎篮子;篮子不是实际持仓。include_full_holdings=true另取最近可得半年度/年度披露股票表,含数量/市值/报告期,非实时全资产组合;benchmark用于跟踪误差。",
|
|
132
|
+
parameters: {
|
|
133
|
+
"type": "object",
|
|
134
|
+
"properties": {
|
|
135
|
+
"include_full_holdings": {"type": "boolean", "description": "显式请求半年度/年度全部披露股票表,默认false;不是实时全资产组合"},
|
|
136
|
+
"symbol": {
|
|
137
|
+
"type": "string",
|
|
138
|
+
"description": "A股ETF代码,如510300"
|
|
139
|
+
},
|
|
140
|
+
"benchmark": {
|
|
141
|
+
"type": "string",
|
|
142
|
+
"description": "可选基准代码,如sh000300;不猜测基准"
|
|
143
|
+
},
|
|
144
|
+
"days": {
|
|
145
|
+
"type": "number",
|
|
146
|
+
"description": "净值窗口交易日数10..252,默认60"
|
|
147
|
+
}
|
|
148
|
+
},
|
|
149
|
+
"required": [
|
|
150
|
+
"symbol"
|
|
151
|
+
]
|
|
152
|
+
},
|
|
153
|
+
async execute(_id, p) {
|
|
154
|
+
const result = await py("value_data.py", ["etf_details", p.symbol, "--benchmark", p.benchmark ?? "", "--days", String(p.days ?? 60), ...(p.include_full_holdings ? ["--include-full-holdings"] : [])]);
|
|
155
|
+
return asText(result.stdout);
|
|
156
|
+
},
|
|
157
|
+
});
|
|
158
|
+
|
|
159
|
+
pi.registerTool({
|
|
160
|
+
name: "get_dividends",
|
|
161
|
+
description: "查询A/HK分红历史、除息日历、已实施TTM股息与连续年数。mode=ranking省略symbol,market=A查报告期排行,market=HK查HKEX/LSEG年度股息率排行(report_date须年末);排行均非当前TTM收益率。缺失不按零。",
|
|
162
|
+
parameters: {
|
|
163
|
+
"type": "object",
|
|
164
|
+
"properties": {
|
|
165
|
+
"market": {"type": "string", "enum": ["A", "HK"], "description": "仅ranking选择市场,默认A;历史/除息日历由symbol决定"},
|
|
166
|
+
"symbol": {
|
|
167
|
+
"type": "string",
|
|
168
|
+
"description": "history/calendar必填A股或港股.HK代码;ranking省略"
|
|
169
|
+
},
|
|
170
|
+
"mode": {
|
|
171
|
+
"type": "string",
|
|
172
|
+
"description": "history默认;calendar未来已公布除息事件;ranking按market查询A/HK排行",
|
|
173
|
+
"enum": [
|
|
174
|
+
"history",
|
|
175
|
+
"calendar",
|
|
176
|
+
"ranking"
|
|
177
|
+
]
|
|
178
|
+
},
|
|
179
|
+
"report_date": {
|
|
180
|
+
"type": "string",
|
|
181
|
+
"description": "ranking报告期YYYY-MM-DD,默认上一年年末;HK仅年度年末日期"
|
|
182
|
+
},
|
|
183
|
+
"years": {
|
|
184
|
+
"type": "number",
|
|
185
|
+
"description": "历史窗口年数1..20,默认10"
|
|
186
|
+
},
|
|
187
|
+
"top": {
|
|
188
|
+
"type": "number",
|
|
189
|
+
"description": "排名条数1..500,默认20"
|
|
190
|
+
}
|
|
191
|
+
},
|
|
192
|
+
"required": []
|
|
193
|
+
},
|
|
194
|
+
async execute(_id, p) {
|
|
195
|
+
const result = await py("value_data.py", ["dividends", "--market", p.market ?? "A", "--symbol", p.symbol ?? "", "--mode", p.mode ?? "history", "--report-date", p.report_date ?? "", "--years", String(p.years ?? 10), "--top", String(p.top ?? 20)]);
|
|
196
|
+
return asText(result.stdout);
|
|
197
|
+
},
|
|
198
|
+
});
|
|
199
|
+
|
|
27
200
|
pi.registerTool({
|
|
28
201
|
name: "get_kline",
|
|
29
202
|
description:
|
|
30
|
-
"获取股票K线数据(OHLCV)。支持A股(如600519)、港股(如00700.HK)、美股(如AAPL)、日股(如7203.T)、韩股(如005930.KS)、台股(如2330.TW)及A股ETF
|
|
203
|
+
"获取股票K线数据(OHLCV)。支持A股(如600519)、港股(如00700.HK)、美股(如AAPL)、日股(如7203.T)、韩股(如005930.KS)、台股(如2330.TW)及A股ETF。A股股票/ETF返回前复权价格,每条记录 adjusted=qfq;sh000xxx/sz399xxx 指数返回原始点位,adjusted=none。需要历史价格自行计算或画图时用;只问指标用 get_technical_analysis,只问现价用 get_quote",
|
|
31
204
|
parameters: {
|
|
32
205
|
type: "object",
|
|
33
206
|
properties: {
|
|
@@ -135,7 +308,7 @@ export default (pi: ExtensionAPI) => {
|
|
|
135
308
|
pi.registerTool({
|
|
136
309
|
name: "get_financials",
|
|
137
310
|
description:
|
|
138
|
-
"
|
|
311
|
+
"获取股票财务摘要及历史趋势,按天缓存。A股返回ROE/毛利率/净利率等;annual=true与periods=10取十年年报,港股年度历史按数据源实际可得期数返回。估值历史用get_valuation_history,披露排期用get_earnings_calendar",
|
|
139
312
|
parameters: {
|
|
140
313
|
type: "object",
|
|
141
314
|
properties: {
|
|
@@ -143,18 +316,20 @@ export default (pi: ExtensionAPI) => {
|
|
|
143
316
|
type: "string",
|
|
144
317
|
description: "股票代码(A股如600519,美股如AAPL,港股如00700.HK)",
|
|
145
318
|
},
|
|
319
|
+
annual: { type: "boolean", description: "只取年度报告,默认false" },
|
|
146
320
|
periods: {
|
|
147
321
|
type: "number",
|
|
148
|
-
description: "返回最近N
|
|
322
|
+
description: "返回最近N个报告期1..40,默认1;annual=true时periods=10请求10年年报",
|
|
149
323
|
},
|
|
150
324
|
},
|
|
151
325
|
required: ["symbol"],
|
|
152
326
|
},
|
|
153
|
-
async execute(_id, { symbol, periods = 1 }) {
|
|
327
|
+
async execute(_id, { symbol, periods = 1, annual = false }) {
|
|
154
328
|
const result = await py("stock_data.py", [
|
|
155
329
|
"financials",
|
|
156
330
|
symbol,
|
|
157
|
-
...(periods
|
|
331
|
+
...(periods !== 1 ? ["--periods", String(periods)] : []),
|
|
332
|
+
...(annual ? ["--annual"] : []),
|
|
158
333
|
]);
|
|
159
334
|
return asText(result.stdout);
|
|
160
335
|
},
|
|
@@ -304,7 +479,7 @@ export default (pi: ExtensionAPI) => {
|
|
|
304
479
|
pi.registerTool({
|
|
305
480
|
name: "get_sector_constituents",
|
|
306
481
|
description:
|
|
307
|
-
"查询A股板块成分股(正向映射:板块→股票列表)。板块名支持模糊匹配(如「创新药」自动解析到精确板块名),东财行业/概念 + 新浪多源 failover
|
|
482
|
+
"查询A股板块成分股(正向映射:板块→股票列表)。板块名支持模糊匹配(如「创新药」自动解析到精确板块名),东财行业/概念 + 新浪多源 failover,结果按用户目录缓存7天。仅支持A股;反向查个股所属板块用 resolve_stock_sectors",
|
|
308
483
|
parameters: {
|
|
309
484
|
type: "object",
|
|
310
485
|
properties: {
|
|
@@ -481,7 +656,7 @@ export default (pi: ExtensionAPI) => {
|
|
|
481
656
|
pi.registerTool({
|
|
482
657
|
name: "get_margin_trading",
|
|
483
658
|
description:
|
|
484
|
-
"获取A股个股融资融券明细(融资余额/融资买入额/融券余量等,上交所/深交所官方数据按交易所分流),返回最近N个交易日序列(最新在前)。金额单位为元,short_*_shares
|
|
659
|
+
"获取A股个股融资融券明细(融资余额/融资买入额/融券余量等,上交所/深交所官方数据按交易所分流),返回最近N个交易日序列(最新在前)。金额单位为元,short_*_shares 单位为股。include_ratio=true追加同日融资买入/成交额百分比(margin_buy_ratio_pct),缺少同日元口径成交额则为null。仅两融标的有数据,非两融标的返回错误",
|
|
485
660
|
parameters: {
|
|
486
661
|
type: "object",
|
|
487
662
|
properties: {
|
|
@@ -489,6 +664,7 @@ export default (pi: ExtensionAPI) => {
|
|
|
489
664
|
type: "string",
|
|
490
665
|
description: "A股股票代码,如 600519",
|
|
491
666
|
},
|
|
667
|
+
include_ratio: { type: "boolean", description: "追加同日融资买入占比,默认false" },
|
|
492
668
|
days: {
|
|
493
669
|
type: "number",
|
|
494
670
|
description: "返回最近N个交易日,默认 10",
|
|
@@ -496,8 +672,8 @@ export default (pi: ExtensionAPI) => {
|
|
|
496
672
|
},
|
|
497
673
|
required: ["symbol"],
|
|
498
674
|
},
|
|
499
|
-
async execute(_id, { symbol, days = 10 }) {
|
|
500
|
-
const result = await py("stock_data.py", ["margin_trading", symbol, "--days", String(days)]);
|
|
675
|
+
async execute(_id, { symbol, days = 10, include_ratio = false }) {
|
|
676
|
+
const result = await py("stock_data.py", ["margin_trading", symbol, "--days", String(days), ...(include_ratio ? ["--include-ratio"] : [])]);
|
|
501
677
|
return asText(result.stdout);
|
|
502
678
|
},
|
|
503
679
|
});
|
|
@@ -87,3 +87,9 @@ gather 工具返回:
|
|
|
87
87
|
5. 触发、失效、时间止损、潜在收益/R 与风险提示
|
|
88
88
|
|
|
89
89
|
完成标准:区分“已确认事实”“推断的影响路径”和“待验证项”,并为交易计划给出可观察的失效条件。
|
|
90
|
+
|
|
91
|
+
财报季排期使用 `get_earnings_calendar(report_date="YYYY-MM-DD", symbol=...)`:最新预约/修订日期是计划,实际披露日期是实绩时间,业绩预告是已公告预估。除息事件用 `get_dividends(mode="calendar", symbol=...)`;不补造未公告日期或把分红预案计入已支付现金。
|
|
92
|
+
|
|
93
|
+
### 补充数据覆盖
|
|
94
|
+
|
|
95
|
+
get_earnings_calendar 查询 A 股仍需 report_date;HK 提供 symbol,可选财政期末 report_date;优先 HKEX 已公告业绩审批董事会排期 confirmation=official_board_meeting_notice、date_kind=scheduled_board_meeting,不能称实际披露日。供应商备选日期为 provider_only,未知期次在请求特定报告期时另列 unverified_schedules,不能强行匹配。
|
|
@@ -77,3 +77,9 @@ gather 工具返回:
|
|
|
77
77
|
5. 投资建议与关注风险点
|
|
78
78
|
|
|
79
79
|
只有收入、利润、现金流和 ROE 均有可比多期数据时,才可给出“优质”结论;否则完成标准是给出已验证项、缺失项和最小补证建议。
|
|
80
|
+
|
|
81
|
+
用户要求长期质量、五到十年财报或 ROE/利润率趋势时,补充 `get_financials(symbol, periods=10, annual=true)`;逐年比较同口径年报,实际可得年份不足时明确标注,不以最近十个季度代替十年。结合 `get_valuation_history` 检查估值分位,分位窗口以实际返回数据为准。
|
|
82
|
+
|
|
83
|
+
### 补充数据覆盖
|
|
84
|
+
|
|
85
|
+
指数估值可用 get_index_valuation;中证补充多年滚动 PE,配置 LIXINGER_TOKEN 可补理杏仁 mcw 历史 PB。每个指标按其来源/口径使用,不把缺失 PB 或近期 PE1 当长期数据。
|
|
@@ -77,6 +77,7 @@ python3 scripts/gather.py <symbol>
|
|
|
77
77
|
- 信号持久化在本地 JSONL(`$STOCK_SIGNAL_STORE` 或 `~/.stock-analysis/signals.jsonl`);是否记录由宿主 Agent 决定,不阻塞报告输出。
|
|
78
78
|
|
|
79
79
|
## 注意事项
|
|
80
|
+
- `get_kline` 的 A 股股票/ETF 数据为前复权,每条记录 `adjusted="qfq"`;显式指数 `sh000xxx` / `sz399xxx` 为原始点位,`adjusted="none"`。复权数据源全部失败时说明数据缺失,不用未复权价格补算指标或信号。
|
|
80
81
|
- 始终提供风险提示
|
|
81
82
|
- 不做绝对化的涨跌预测
|
|
82
83
|
- 建议用户结合自身风险偏好做决策
|
|
@@ -84,3 +85,24 @@ python3 scripts/gather.py <symbol>
|
|
|
84
85
|
- 如果风险筛查返回 veto_buy=true,必须醒目标注并建议谨慎
|
|
85
86
|
|
|
86
87
|
完成标准:每个买卖建议都对应可观察的触发条件和失效条件,且所有缺失数据及其影响已说明。
|
|
88
|
+
|
|
89
|
+
## 低频价投数据
|
|
90
|
+
|
|
91
|
+
按用户问题选择数据,完整说明口径、采样覆盖和缺失项:
|
|
92
|
+
|
|
93
|
+
- 判断估值贵贱:`get_valuation_history(symbol, years=5)` 的 PE-TTM/PB 历史正值分位与 Band;亏损 PE 不计算分位,实际采样不足五年必须说明。
|
|
94
|
+
- 读多年财报:`get_financials(symbol, periods=10, annual=true)`;A 股按年报筛选,港股按源实际可得年度数返回。财报期不等于公告日,年报历史不能用于假定当时已知信息的回测。
|
|
95
|
+
- 财报季排期:`get_earnings_calendar(report_date="YYYY-MM-DD", symbol=...)`,区分最新预约日期、实际披露日期和已公告业绩预告,不把预告当业绩实绩。
|
|
96
|
+
- 股东变化:`get_shareholder_structure`。A 股北向值是财报十大流通股东中的 HKSCC 名义持股,缺席不等于零,不能当成日度北向买卖;港股南向值按港交所披露日期使用。
|
|
97
|
+
- 大盘估值:`get_index_valuation(symbol="000300", years=5)`;中证近期 PE1 不冒充 PE-TTM、PB 或多年分位。
|
|
98
|
+
- ETF:`get_etf_details(symbol="510300", benchmark="sh000300")`。折溢价须看净值/行情日期;披露持仓不是完整实时申赎篮子,指数成分与基金持仓分别呈现。跟踪误差必须给出用户认可的基准。
|
|
99
|
+
- 股息:`get_dividends` 区分历史、未来已公布除息日历和 A 股报告期排行;预案不计入已实现 TTM 股息。名义每股现金未重算送转股口径,遇送转股时不得据此精确比较持有收益。
|
|
100
|
+
- 两融:`get_margin_trading(include_ratio=true)` 的 `margin_buy_ratio_pct` 只使用同日成交额;null 表示不可计算。
|
|
101
|
+
|
|
102
|
+
慢变数据存于 `~/.stock-analysis/cache`:财报、基本信息及新历史数据按天,板块映射按周;行情仍实时查询。输出中的报告期/数据日期决定能否用于判断,缓存命中不代表数据已更新。
|
|
103
|
+
|
|
104
|
+
### 补充数据覆盖
|
|
105
|
+
|
|
106
|
+
get_shareholder_structure 的 northbound 优先使用沪深官方季度总量;northbound_nominee 只是十大股东推断,不能混同。get_etf_details 的 basket 是完整已发布 PCF,对价数量/现金替代规则不是基金实际持仓或NAV权重。HK 股息排行使用 get_dividends(mode=ranking, market=HK),年度口径不能称 TTM。
|
|
107
|
+
|
|
108
|
+
实际披露股票持仓可用 get_etf_details(include_full_holdings=true) 获取半年度/年度表;按 as_of 解释,数量为股、市值为人民币元。默认不取大量明细;不是实时全资产组合,不与 PCF 对价数量混同。
|
|
@@ -73,3 +73,21 @@ python3 tools/screener.py screen --market A --top 20
|
|
|
73
73
|
- **成长型**:中等PE + 高营收增长 + 高换手率
|
|
74
74
|
- **趋势型**:放量突破 + 均线多头 + 高量比
|
|
75
75
|
- **低估反转**:超跌 + 低PB + 资金净流入
|
|
76
|
+
|
|
77
|
+
## 股息因子(A股,可选)
|
|
78
|
+
|
|
79
|
+
配置 `filters.dividend_yield_min` / `dividend_yield_max` 或 `sort_by: dividend_score` / `dividend_yield` 时才拉取股息数据。`dividend_report_date` 可指定报告期,默认上一年年末。这里使用已实施方案的**报告期股息率**(百分数),不是滚动十二个月股息率;缺失为未知,使用股息阈值时排除。启用后 value 分项加入股息横截面评分,未启用时不增加股息请求。
|
|
80
|
+
|
|
81
|
+
```yaml
|
|
82
|
+
filters:
|
|
83
|
+
dividend_yield_min: 3
|
|
84
|
+
sort_by: dividend_score
|
|
85
|
+
sort_order: desc
|
|
86
|
+
dividend_report_date: "2025-12-31"
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
筛选结果仍需用 `get_dividends(mode="history", symbol=...)` 核查已实施现金分红、连续支付年数与除息时间,不能把高股息直接解释为低风险。
|
|
90
|
+
|
|
91
|
+
### 补充数据覆盖
|
|
92
|
+
|
|
93
|
+
股息筛选支持 A/HK:A 股为报告期已实施方案股息率,HK 为 HKEX/LSEG 年度股息率。两者都不是当前价 TTM;使用结果的 yield_basis 和 report_date,缺失不当零。
|
package/tools/_cache.py
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
"""TTL cache for slow public datasets; live quotes and errors are never stored."""
|
|
2
|
+
|
|
3
|
+
import contextlib
|
|
4
|
+
import hashlib
|
|
5
|
+
import json
|
|
6
|
+
import os
|
|
7
|
+
import tempfile
|
|
8
|
+
import time
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
|
|
11
|
+
CACHE_DIR = Path.home() / ".stock-analysis" / "cache"
|
|
12
|
+
DAY = 86400
|
|
13
|
+
WEEK = 7 * DAY
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def _namespace_prefix(namespace):
|
|
17
|
+
return hashlib.sha256(namespace.encode()).hexdigest()[:12]
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def _read(path, ttl):
|
|
21
|
+
try:
|
|
22
|
+
entry = json.loads(path.read_text(encoding="utf-8"))
|
|
23
|
+
if 0 <= time.time() - entry["fetched_at"] < ttl:
|
|
24
|
+
return entry
|
|
25
|
+
except (OSError, ValueError, KeyError, TypeError):
|
|
26
|
+
pass
|
|
27
|
+
return None
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def cached_values(namespace, ttl):
|
|
31
|
+
for path in CACHE_DIR.glob(f"{_namespace_prefix(namespace)}-*.json"):
|
|
32
|
+
entry = _read(path, ttl)
|
|
33
|
+
if entry and str(entry.get("key", "")).startswith(namespace + ":"):
|
|
34
|
+
yield entry.get("data")
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def cached(key: str, ttl: int, fetch):
|
|
38
|
+
path = CACHE_DIR / f"{_namespace_prefix(key.partition(':')[0])}-{hashlib.sha256(key.encode()).hexdigest()}.json"
|
|
39
|
+
entry = _read(path, ttl)
|
|
40
|
+
if entry and "data" in entry:
|
|
41
|
+
return entry["data"]
|
|
42
|
+
result = fetch()
|
|
43
|
+
rows = result if isinstance(result, list) else [result]
|
|
44
|
+
if not result or any(isinstance(row, dict) and (row.get("error") or row.get("warnings")) for row in rows):
|
|
45
|
+
return result
|
|
46
|
+
tmp = None
|
|
47
|
+
try:
|
|
48
|
+
CACHE_DIR.mkdir(parents=True, exist_ok=True)
|
|
49
|
+
with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=CACHE_DIR, delete=False) as stream:
|
|
50
|
+
tmp = stream.name
|
|
51
|
+
json.dump(
|
|
52
|
+
{"key": key, "fetched_at": time.time(), "data": result}, stream, ensure_ascii=False, allow_nan=False
|
|
53
|
+
)
|
|
54
|
+
os.replace(tmp, path)
|
|
55
|
+
except (OSError, ValueError, TypeError):
|
|
56
|
+
pass
|
|
57
|
+
finally:
|
|
58
|
+
if tmp:
|
|
59
|
+
with contextlib.suppress(OSError):
|
|
60
|
+
Path(tmp).unlink(missing_ok=True)
|
|
61
|
+
return result
|
package/tools/capabilities.py
CHANGED
|
@@ -18,6 +18,15 @@ ALL_MARKETS = ["A", "HK", "US", "JP", "KR", "TW"]
|
|
|
18
18
|
|
|
19
19
|
# tool_name -> {markets: [supported markets], reason: str for unsupported}
|
|
20
20
|
TOOL_MATRIX = {
|
|
21
|
+
"get_valuation_history": {"markets": ["A", "HK"], "reason": "A/HK historical valuation providers only"},
|
|
22
|
+
"get_index_valuation": {"markets": ["A"], "reason": "Chinese index valuation only"},
|
|
23
|
+
"get_earnings_calendar": {
|
|
24
|
+
"markets": ["A", "HK"],
|
|
25
|
+
"reason": "A-share disclosed calendar / HK single-symbol provider schedule",
|
|
26
|
+
},
|
|
27
|
+
"get_shareholder_structure": {"markets": ["A", "HK"], "reason": "A-share shareholder reports / HK southbound only"},
|
|
28
|
+
"get_etf_details": {"markets": ["A"], "reason": "A-share ETF portfolio/NAV/size only"},
|
|
29
|
+
"get_dividends": {"markets": ["A", "HK"], "reason": "A/HK dividend history and report-year ranking"},
|
|
21
30
|
"get_kline": {"markets": ALL_MARKETS, "reason": None},
|
|
22
31
|
"get_quote": {"markets": ALL_MARKETS, "reason": None},
|
|
23
32
|
"get_news": {"markets": ALL_MARKETS, "reason": None},
|
package/tools/diagnostics.py
CHANGED
|
@@ -27,6 +27,12 @@ PROVIDERS = {
|
|
|
27
27
|
# see stock_data._kline_tushare) — the tushare package is not in requirements,
|
|
28
28
|
# so availability is the token, not a package probe
|
|
29
29
|
"tushare": ("requests", ["TUSHARE_TOKEN"], ["A"], "pure-HTTP API (api.tushare.pro); no tushare package needed"),
|
|
30
|
+
"lixinger": (
|
|
31
|
+
"requests",
|
|
32
|
+
["LIXINGER_TOKEN"],
|
|
33
|
+
["A"],
|
|
34
|
+
"optional index PE/PB history; subscription permissions not probed",
|
|
35
|
+
),
|
|
30
36
|
"efinance": ("efinance", [], ["A"], None),
|
|
31
37
|
"tencent": ("requests", [], ["A"], "qt.gtimg.cn quote/kline, no auth (issue #25)"),
|
|
32
38
|
"sina": (
|