stock-analysis-plugin 0.2.11 → 0.2.12
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 +231 -381
- package/docs/mcp.md +60 -0
- package/hermes/__init__.py +35 -0
- package/hermes/plugin.yaml +131 -0
- package/hermes/schemas.py +6 -0
- package/hermes/tools.py +630 -0
- package/mcp_host/__init__.py +1 -0
- package/mcp_host/__main__.py +3 -0
- package/mcp_host/server.py +222 -0
- package/package.json +7 -1
- package/pi/index.ts +52 -2906
- package/scripts/cli-json.mjs +23 -0
- package/scripts/exec-process.mjs +89 -0
- package/scripts/setup-python.mjs +37 -4
- package/scripts/tool-calls.mjs +489 -0
- package/skills/event-driven/SKILL.md +2 -2
- package/skills/growth-quality/SKILL.md +1 -1
- package/skills/stock-analysis/SKILL.md +8 -6
- package/skills/stock-analysis/references/stateless-analysis.md +9 -1
- package/tools/_cache.py +13 -0
- package/tools/_subproc.py +46 -0
- package/tools/alert_rules.py +2 -2
- package/tools/backtest.py +3 -3
- package/tools/capabilities.py +32 -9
- package/tools/cli_budgets.json +2 -0
- package/tools/diagnostics.py +3 -4
- package/tools/gather.py +2 -6
- package/tools/import_parser.py +3 -4
- package/tools/lixinger.py +119 -27
- package/tools/market_regime.py +5 -2
- package/tools/market_review.py +5 -6
- package/tools/name_resolver.py +66 -7
- package/tools/report_renderer.py +3 -3
- package/tools/requirements.txt +5 -4
- package/tools/risk_screening.py +3 -2
- package/tools/screener.py +6 -4
- package/tools/search_intel.py +79 -10
- package/tools/sec_edgar.py +266 -0
- package/tools/sec_holders.py +6 -0
- package/tools/signal_tracker.py +5 -5
- package/tools/stateless_analysis.py +115 -0
- package/tools/stock_data.py +455 -201
- package/tools/tiaa_disclosures.py +4 -0
- package/tools/tool_schemas.json +2704 -0
- package/tools/trading_calendar.py +65 -30
- package/tools/value_data.py +366 -134
- package/tools/watchlist.py +43 -5
package/README.md
CHANGED
|
@@ -1,141 +1,101 @@
|
|
|
1
1
|
# stock-analysis-plugin
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/stock-analysis-plugin)
|
|
4
4
|
[](https://pypi.org/project/stock-analysis-plugin/)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
给 AI Agent 用的股票研究工具箱,覆盖 **A 股、港股、美股、日股、韩股、台股**。装进你常用的 Agent 后,直接用自然语言查行情、做个股分析、全市场选股、写策略回测、做盘后复盘。
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
同一套 Python 工具同时支持 [Pi Agent](https://github.com/earendil-works/pi)、[Hermes Agent](https://github.com/NousResearch/hermes-agent)、[OpenClaw](https://github.com/openclaw/openclaw)、[DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness),也能作为 MCP 服务器接入 Claude Desktop、Cursor、WorkBuddy。
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+

|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
- [安装](#安装)
|
|
16
|
-
- [Pi Agent Extension](#pi-agent-extension)
|
|
17
|
-
- [Hermes Agent Plugin](#hermes-agent-plugin)
|
|
18
|
-
- [OpenClaw Plugin](#openclaw-plugin)
|
|
19
|
-
- [dsh (DeepSeek Harness) Plugin](#dsh-deepseek-harness-plugin)
|
|
20
|
-
- [Python 依赖](#python-依赖)
|
|
21
|
-
- [快速开始](#快速开始)
|
|
22
|
-
- [Skills 一览](#skills-一览)
|
|
23
|
-
- [工具列表](#工具列表)
|
|
24
|
-
- [策略回测 DSL](#策略回测-dsl)
|
|
25
|
-
- [市场路由规则](#市场路由规则)
|
|
26
|
-
- [独立 CLI 使用](#独立-cli-使用)
|
|
27
|
-
- [CI 真实宿主测试](#ci-真实宿主测试)
|
|
28
|
-
- [项目结构](#项目结构)
|
|
29
|
-
- [致谢](#致谢)
|
|
30
|
-
- [常见问题](#常见问题)
|
|
31
|
-
- [License](#license)
|
|
14
|
+
<sub>dsh Web / Desktop 中的「股票仪表盘」,真实行情截图。</sub>
|
|
32
15
|
|
|
33
|
-
##
|
|
16
|
+
## 能做什么
|
|
34
17
|
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
18
|
+
- **个股分析**:「帮我分析贵州茅台」——行情、技术面、财务、资金流、新闻与舆情汇总成一份研报,并标注哪些数据缺失或过期。
|
|
19
|
+
- **全市场选股**:「A 股里找 PE < 30、市值 > 100 亿的成长股」——多因子硬筛,再由模型排序给出候选。
|
|
20
|
+
- **策略回测**:用 YAML 描述买卖条件,回测、诊断,按需调参。
|
|
21
|
+
- **盘后复盘**:指数、涨跌家数、板块轮动、涨停池、龙虎榜和市场情绪温度。
|
|
22
|
+
- **价值投资数据**:估值分位、股息、股东结构、ETF 折溢价、财报日历、公告,以及美股 SEC 13F / Form 4。
|
|
23
|
+
- **持仓与风控**:组合集中度、压力测试、调仓计划和仓位计算;只计算你本次传入的数据,不保存账户。
|
|
24
|
+
- **策略视角**:缠论、波浪理论、龙头战法、情绪周期等 18 套方法论,以 Skill 形式按需调用。
|
|
25
|
+
- **dsh 仪表盘**:在 dsh Web / Desktop 侧栏看自选股和六个市场的行情,后台预热,打开即显示。
|
|
41
26
|
|
|
42
|
-
|
|
27
|
+
一共 74 个工具、21 个 Skills,11 个数据源自动容灾。大部分功能不需要任何 API Key。
|
|
43
28
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
插件包地址:
|
|
29
|
+
## 快速开始
|
|
47
30
|
|
|
48
|
-
|
|
49
|
-
|------|------|------|----------|
|
|
50
|
-
| Pi Agent | `@weaxs/stock-analysis-plugin`(或 `stock-analysis-plugin`) | [npm](https://www.npmjs.com/package/@weaxs/stock-analysis-plugin) | `npm install @weaxs/stock-analysis-plugin` |
|
|
51
|
-
| Hermes Agent | `stock-analysis-plugin` | [PyPI](https://pypi.org/project/stock-analysis-plugin/) | `pip install stock-analysis-plugin` |
|
|
52
|
-
| OpenClaw | `@weaxs/openclaw-stock-analysis`(或 `openclaw-stock-analysis`) | [npm](https://www.npmjs.com/package/@weaxs/openclaw-stock-analysis) | `openclaw plugins install clawhub:@weaxs/openclaw-stock-analysis` |
|
|
53
|
-
| DeepSeek Harness (dsh) | `@weaxs/dsh-stock-analysis`(或 `dsh-stock-analysis`) | [npm](https://www.npmjs.com/package/@weaxs/dsh-stock-analysis) | `dsh plugin --profile <profile> add @weaxs/dsh-stock-analysis` |
|
|
31
|
+
需要本机有 **Python ≥ 3.10**。插件安装时会在包目录下创建 `.venv` 并装好依赖;dsh 和 OpenClaw 默认不执行安装脚本,处理方法见下方注意事项。
|
|
54
32
|
|
|
55
|
-
|
|
33
|
+
| 你在用 | 安装 | 详细说明 |
|
|
34
|
+
|--------|------|----------|
|
|
35
|
+
| Pi Agent | `pi install npm:stock-analysis-plugin` | [Pi 接入指南](docs/pi-integration.md) |
|
|
36
|
+
| Hermes Agent | `pip install stock-analysis-plugin` | [Hermes 接入指南](docs/hermes-integration.md) |
|
|
37
|
+
| OpenClaw | `openclaw plugins install npm:openclaw-stock-analysis` | [OpenClaw 接入指南](docs/openclaw-integration.md) |
|
|
38
|
+
| DeepSeek Harness (dsh) | `dsh plugin --profile <profile> add dsh-stock-analysis` | [dsh 插件说明](dsh/README.md) |
|
|
39
|
+
| Claude Desktop / Cursor / WorkBuddy(MCP) | `pip install stock-analysis-plugin`,运行 `stock-analysis-mcp` | [MCP 接入指南](docs/mcp.md) |
|
|
56
40
|
|
|
57
|
-
|
|
41
|
+
每个 npm 包也以 `@weaxs/` scoped 名发布(如 `@weaxs/dsh-stock-analysis`),内容一致。装的是 scoped 版时,配置里引用包名的地方也用 scoped 名。
|
|
58
42
|
|
|
59
|
-
|
|
60
|
-
# 全局安装
|
|
61
|
-
cd ~/.pi/agent/extensions
|
|
62
|
-
npm install @weaxs/stock-analysis-plugin
|
|
43
|
+
装好后试试:
|
|
63
44
|
|
|
64
|
-
# 或项目级安装
|
|
65
|
-
mkdir -p .pi/extensions && cd .pi/extensions
|
|
66
|
-
npm install @weaxs/stock-analysis-plugin
|
|
67
45
|
```
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
新版 Pi(已核验 1.5.2)提供原生 `tool_search` 时,插件自动启用按需工具发现,72 项能力保留注册,仅命中工具加载完整定义。缺少原生发现接口的旧版 Pi 或 SDK 宿主保持全量暴露。可直接用中文关键词或工具名检索,例如 `实时行情`、`get_quote`、`get_financials`;Pi 1.5 之前的版本只能匹配英文关键词。
|
|
74
|
-
|
|
75
|
-
### Hermes Agent Plugin
|
|
76
|
-
|
|
77
|
-
```bash
|
|
78
|
-
pip install stock-analysis-plugin
|
|
46
|
+
帮我分析贵州茅台(600519)
|
|
47
|
+
从 A 股中筛选低估值高成长的股票:PE < 30、PB < 5、市值 > 100 亿
|
|
48
|
+
用 RSI 超卖反弹策略回测茅台,时间段 2024 年全年
|
|
49
|
+
用缠论分析一下 600519 当前的走势结构
|
|
50
|
+
今天 A 股复盘
|
|
79
51
|
```
|
|
80
52
|
|
|
81
|
-
|
|
53
|
+
也可以显式调用 Skill,例如 `/skill:stock-analysis`、`/skill:wave-theory`。
|
|
82
54
|
|
|
83
|
-
|
|
55
|
+
### 各宿主的注意事项
|
|
84
56
|
|
|
85
|
-
|
|
86
|
-
from hermes import register
|
|
87
|
-
register(ctx)
|
|
88
|
-
```
|
|
57
|
+
**Pi**:加 `-l` 只装到当前项目,或直接 clone 源码使用。启动后输入 `/skills` 确认已加载。Pi 1.5.2 及以上提供原生 `tool_search` 时,插件只在命中时加载完整工具定义;可用中文关键词或工具名搜索,例如 `实时行情`、`get_quote`。
|
|
89
58
|
|
|
90
|
-
|
|
59
|
+
**Hermes**:通过 `hermes_agent.plugins` entry point 自动发现,无需复制目录;也可以在 Python 中 `from hermes import register; register(ctx)`。
|
|
91
60
|
|
|
92
|
-
|
|
61
|
+
**OpenClaw**:OpenClaw 安装 npm 插件时带 `--ignore-scripts`,不会自动建 `.venv`。装完后在插件目录(`openclaw plugins inspect stock-analysis --runtime --json` 的 `installPath`)运行一次 `node scripts/setup-python.mjs`。ClawHub 上只有 scoped 名:`clawhub:@weaxs/openclaw-stock-analysis`。
|
|
93
62
|
|
|
94
|
-
|
|
95
|
-
openclaw plugins install clawhub:@weaxs/openclaw-stock-analysis
|
|
96
|
-
```
|
|
63
|
+
**dsh**:dsh 用 pnpm 安装插件,默认不执行第三方安装脚本。若 `.venv` 没有建起来,在 profile 的 `pnpm-workspace.yaml` 中给 `dsh-stock-analysis` 配置 `allowBuilds`,否则会回退系统 `python3`。新版 dsh 默认通过 `stock_tool_search` 按需加载工具,可用 `toolDiscovery: false` 关闭。
|
|
97
64
|
|
|
98
|
-
|
|
65
|
+
**MCP**:源码方式运行 `.venv/bin/python mcp_host/server.py`,或 `python -m mcp_host`。客户端配置示例见 [MCP 接入指南](docs/mcp.md)。
|
|
99
66
|
|
|
100
|
-
|
|
67
|
+
## dsh 股票仪表盘
|
|
101
68
|
|
|
102
|
-
|
|
69
|
+
装了 dsh 插件的 Web / Desktop 会在侧栏出现「股票仪表盘」:
|
|
103
70
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
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,不新增模型工具。
|
|
112
|
-
|
|
113
|
-
新版 dsh 的原生函数调用模式默认通过 `stock_tool_search` 按 Agent 搜索、加载所需工具,支持中文关键词或工具名;旧接口、搜索入口不可用时保留全量暴露。可设置 `toolDiscovery: false` 关闭,配置与 PTC 模式边界见下方接入文档。
|
|
71
|
+
- **自选股行情表**:最新价、涨跌幅、今日区间、成交额和 30 日走势,可排序、按市场筛选;最多 30 只,支持六个市场。
|
|
72
|
+
- **市场概览**:顶部六市场指数带和 A 股涨跌分布;下方可切换市场查看指数,A 股另有涨跌统计和行业领涨、领跌榜。
|
|
73
|
+
- **打开即显示**:插件在后台常驻预热行情,页面只读内存快照;交易时段约 30 秒更新一次。
|
|
74
|
+
- **与 Agent 共享**:Agent 可以用 `get_watchlist` 读取同一份自选股。
|
|
114
75
|
|
|
115
|
-
|
|
76
|
+
刷新节奏、数据来源和存储位置见 [dsh 插件说明](dsh/README.md#股票仪表盘web--desktop)。
|
|
116
77
|
|
|
117
|
-
|
|
78
|
+
## 支持的市场
|
|
118
79
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
80
|
+
| 代码格式 | 示例 | 市场 | 行情报价 Failover 链(K 线差异见下方) |
|
|
81
|
+
|----------|------|------|---------------------|
|
|
82
|
+
| 6 位纯数字 | `600519`, `000001`, `300750` | A 股 | 腾讯 → akshare → tushare → efinance → 新浪 |
|
|
83
|
+
| 6 位纯数字(51/52/56/58/15/16/18 开头) | `510300`, `159915` | A 股 ETF | 腾讯 → akshare(ETF/全市场接口)→ tushare → efinance → 新浪 |
|
|
84
|
+
| 带交易所前缀(`sh`/`sz`/`bj` + 6 位数字) | `sh000001`(上证指数), `sz399006`(创业板指) | A 股(显式指定,含指数) | 腾讯 → 新浪 |
|
|
85
|
+
| `.HK` 结尾 | `00700.HK`, `09988.HK` | 港股 | yfinance → 腾讯 → finnhub → longbridge |
|
|
86
|
+
| 英文字母 | `AAPL`, `GOOGL`, `TSLA` | 美股 | yfinance → finnhub → longbridge → 腾讯 → alphavantage |
|
|
87
|
+
| `.T` 结尾 | `7203.T` | 日股 | yfinance |
|
|
88
|
+
| `.KS` / `.KQ` 结尾 | `005930.KS`, `036020.KQ` | 韩股 | yfinance |
|
|
89
|
+
| `.TW` / `.TWO` 结尾 | `2330.TW`, `6510.TWO` | 台股 | yfinance |
|
|
122
90
|
|
|
123
|
-
|
|
91
|
+
各数据源按优先级自动尝试,失败后切换到下一个;未配置 API Key 的数据源自动跳过。A 股单票报价优先使用腾讯和新浪,不依赖东财域名,境外网络通常也能用。港股备用源、指数前缀、K 线复权口径等细节见 [数据源与数据口径](docs/data-sources.md)。
|
|
124
92
|
|
|
125
|
-
|
|
126
|
-
|---|------|
|
|
127
|
-
| akshare | A 股数据源(行情、资金流、财务、新闻,含 A 股 ETF) |
|
|
128
|
-
| yfinance | 港股 / 美股 / 日股 / 韩股 / 台股数据源 |
|
|
129
|
-
| pandas / numpy | 数据处理和数值计算 |
|
|
130
|
-
| exchange-calendars | 交易日历(A/HK/US/JP/KR/TW) |
|
|
131
|
-
| newspaper4k | 新闻正文提取 |
|
|
132
|
-
| pypinyin | 股票名称拼音搜索 |
|
|
133
|
-
| pytdx | A 股 TDX 行情(免费兜底源) |
|
|
134
|
-
| longport | 港股 / 美股 Longbridge SDK |
|
|
93
|
+
## 可选配置
|
|
135
94
|
|
|
136
|
-
|
|
95
|
+
不配置任何环境变量也能使用。下面这些配置后会加入容灾链,或启用搜索、舆情和 SEC 数据:
|
|
137
96
|
|
|
138
|
-
|
|
97
|
+
<details>
|
|
98
|
+
<summary>环境变量列表</summary>
|
|
139
99
|
|
|
140
100
|
**数据源(可选,配置后自动加入 Failover 链):**
|
|
141
101
|
|
|
@@ -148,13 +108,13 @@ pip install -r tools/requirements.txt
|
|
|
148
108
|
| `ALPHAVANTAGE_API_KEY` | Alpha Vantage(美股 K 线 / 行情) |
|
|
149
109
|
| `FINNHUB_API_KEY` | Finnhub(港股 / 美股) |
|
|
150
110
|
| `XUEQIU_TOKEN` | 雪球(A 股个股所属板块反查,东财不可用时的兜底) |
|
|
111
|
+
| `LIXINGER_TOKEN` | 理杏仁:指数 PB、A 股/港股非金融公司每日估值与 DCF 财报输入、港股财务(需对应权限) |
|
|
112
|
+
| `SEC_USER_AGENT` | SEC EDGAR 身份声明:应用名称与真实联系邮箱,13F / Form 4 必需 |
|
|
151
113
|
|
|
152
114
|
**搜索引擎(可选,配置任一即可):**
|
|
153
115
|
|
|
154
116
|
| 环境变量 | 用途 |
|
|
155
117
|
|---------|------|
|
|
156
|
-
| `LIXINGER_TOKEN` | 理杏仁可选数据源:指数 PB 与港股非金融公司财务/每日估值(需对应权限) |
|
|
157
|
-
| `SEC_USER_AGENT` | SEC EDGAR 身份声明:应用名称与真实联系邮箱,13F/Form 4 必需 |
|
|
158
118
|
| `TAVILY_API_KEY` | Tavily 搜索 |
|
|
159
119
|
| `BRAVE_API_KEY` | Brave 搜索 |
|
|
160
120
|
| `SERPAPI_KEY` | SerpAPI |
|
|
@@ -168,43 +128,7 @@ pip install -r tools/requirements.txt
|
|
|
168
128
|
| `SENTIMENT_API_URL` | 舆情 API 地址(默认 `https://api.adanos.org`) |
|
|
169
129
|
| `SENTIMENT_API_KEY` | 舆情 API 密钥 |
|
|
170
130
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
### 综合分析
|
|
174
|
-
|
|
175
|
-
```
|
|
176
|
-
/skill:stock-analysis
|
|
177
|
-
|
|
178
|
-
帮我分析贵州茅台(600519)
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息面,输出多维度研报。
|
|
182
|
-
|
|
183
|
-
### 全市场选股
|
|
184
|
-
|
|
185
|
-
```
|
|
186
|
-
/skill:stock-screener
|
|
187
|
-
|
|
188
|
-
帮我从 A 股中筛选出低估值+高成长的股票,要求 PE < 30、PB < 5、市值 > 100 亿
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
### 策略回测
|
|
192
|
-
|
|
193
|
-
```
|
|
194
|
-
/skill:strategy-backtest
|
|
195
|
-
|
|
196
|
-
用 RSI 超卖反弹策略回测茅台,时间段 2024 年全年
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
### 特定策略视角
|
|
200
|
-
|
|
201
|
-
```
|
|
202
|
-
/skill:chan-theory
|
|
203
|
-
用缠论分析一下 600519 当前的走势结构
|
|
204
|
-
|
|
205
|
-
/skill:wave-theory
|
|
206
|
-
用波浪理论分析 AAPL 的浪形位置
|
|
207
|
-
```
|
|
131
|
+
</details>
|
|
208
132
|
|
|
209
133
|
## Skills 一览
|
|
210
134
|
|
|
@@ -241,32 +165,47 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
|
|
|
241
165
|
|
|
242
166
|
## 工具列表
|
|
243
167
|
|
|
244
|
-
|
|
168
|
+
74 个工具按用途分组:
|
|
169
|
+
|
|
170
|
+
| 类别 | 数量 | 主要内容 |
|
|
171
|
+
|------|------|----------|
|
|
172
|
+
| 数据获取 | 28 | K 线、报价、基金净值、资金流、财务、板块、涨停池、龙虎榜、两融、估值历史、股东、ETF、股息、公告、SEC |
|
|
173
|
+
| 分析计算 | 9 | 技术指标、K 线形态、量价、异动、信号胜率、趋势与行业轮动研究 |
|
|
174
|
+
| 筛选与回测 | 8 | 多因子选股、风险筛查、策略回测、市场状态、日度复盘、自选股批量分析 |
|
|
175
|
+
| 搜索与舆情 | 5 | 新闻搜索、综合情报、社交情绪、正文提取 |
|
|
176
|
+
| 辅助 | 7 | 名称/拼音解析、交易日历、交易时段、数据源诊断、股票列表解析 |
|
|
177
|
+
| 上下文与报告 | 8 | 自选股上下文、持仓分析、告警规则、信号记录与评估、研报渲染 |
|
|
178
|
+
| 无状态研究与风险计算 | 9 | 同行比较、公告变更、组合风险、调仓计划、仓位计算、DCF 估值、事件研究、回测稳健性 |
|
|
179
|
+
|
|
180
|
+
<details>
|
|
181
|
+
<summary>完整工具列表(74 个)</summary>
|
|
182
|
+
|
|
183
|
+
#### 数据获取
|
|
245
184
|
|
|
246
185
|
| 工具 | 说明 |
|
|
247
186
|
|------|------|
|
|
248
|
-
| `get_announcements` | A
|
|
187
|
+
| `get_announcements` | A 股巨潮公告 / 港股 HKEXnews / 美股 SEC 申报:类别/日期范围/标题与原文链接;美股需 SEC_USER_AGENT |
|
|
249
188
|
| `get_us_holdings` | SEC 机构组合 / 发行人 CIK 反查机构:精确 CUSIP 映射、季度数据与修订处理(需 SEC_USER_AGENT) |
|
|
250
189
|
| `get_insider_trades` | SEC 股票 ticker/发行人 CIK 的 Form 4 内部人交易、代码和脚注 |
|
|
251
|
-
| `get_valuation_history` | A/HK PE-TTM/PB 历史、正值分位与估值 Band
|
|
190
|
+
| `get_valuation_history` | A/HK/US PE-TTM/PB 历史、正值分位与估值 Band,实际采样窗口(美股由 SEC 申报与周收盘派生) |
|
|
252
191
|
| `get_index_valuation` | 中国指数 PE/PB 历史水位;中证官方多年滚动 PE;可选理杏仁补充 PB |
|
|
253
|
-
| `get_earnings_calendar` | A 股报告期披露与业绩预告;HK
|
|
192
|
+
| `get_earnings_calendar` | A 股报告期披露与业绩预告;HK 董事会排期;US/JP yfinance 预计日期(provider_only,非官方确认) |
|
|
254
193
|
| `get_shareholder_structure` | A 股股东户数/十大流通股东变化/报告期北向名义持股;HK 南向持股 |
|
|
255
194
|
| `get_etf_details` | A 股 ETF 净值折溢价、规模变动、披露持仓、可选基准成分与跟踪误差 |
|
|
256
|
-
| `get_dividends` | A/HK
|
|
195
|
+
| `get_dividends` | A/HK/US/JP/KR/TW 历史分红与除息日历、已实现 TTM 股息;排行仍仅 A/HK |
|
|
257
196
|
| `get_kline` | K 线数据(OHLCV),支持日/周/月线;A 股股票/ETF 前复权,每条记录 `adjusted=qfq`,指数 `adjusted=none` |
|
|
258
197
|
| `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
198
|
| `get_fund_quote` | 6 位场外公募基金净值;`nav` 是 `nav_date` 对应的已披露日终净值而非实时价,`accumulated_nav` 为累计净值、`change_pct` 为日涨跌幅;`estimated_nav` 可能为 `null`,QDII 净值可能滞后 1-2 交易日 |
|
|
260
199
|
| `get_capital_flow` | 资金流向(仅 A 股) |
|
|
261
200
|
| `get_news` | 个股相关新闻 |
|
|
262
|
-
| `get_financials` |
|
|
201
|
+
| `get_financials` | 财务指标;可选追加 A/港/美股年度 DCF 输入 |
|
|
263
202
|
| `get_stock_info` | 股票基本信息 |
|
|
264
203
|
| `get_chip_distribution` | 筹码分布 |
|
|
265
204
|
| `get_market_indices` | 主要指数行情 |
|
|
266
|
-
| `get_sector_rankings` |
|
|
205
|
+
| `get_sector_rankings` | 板块涨跌排行(A 股行业/概念;美股 SPDR 行业 ETF 代理) |
|
|
267
206
|
| `get_sector_constituents` | 板块成分股查询(仅 A 股,板块名模糊匹配) |
|
|
268
207
|
| `resolve_stock_sectors` | 个股所属板块查询(A 股行业+概念 / 港股 GICS) |
|
|
269
|
-
| `get_market_stats` |
|
|
208
|
+
| `get_market_stats` | 市场统计(A/HK/US 涨跌家数、成交额;涨停仅 A 股) |
|
|
270
209
|
| `get_limit_up_pool` | 涨停池/涨停板复盘(连板数、封板资金、炸板次数等,仅 A 股;非交易日自动回退到最近交易日并以 requested_date/stale 标注) |
|
|
271
210
|
| `get_dragon_tiger` | 龙虎榜(净买额/上榜原因/解读,仅 A 股;非交易日自动回退到最近交易日并以 requested_date/stale 标注) |
|
|
272
211
|
| `get_hot_stocks` | 全市场人气热搜榜(东财→百度,仅 A 股) |
|
|
@@ -274,7 +213,7 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
|
|
|
274
213
|
| `get_northbound_flow` | 北向资金市场级净买入序列(东财沪深港通历史数据;2024-08-16 起交易所停止披露日度净买额,仅 2024-08 之前历史数据可查,仅 A 股) |
|
|
275
214
|
| `get_fundamental_context` | 基本面综合上下文 |
|
|
276
215
|
|
|
277
|
-
|
|
216
|
+
#### 分析计算
|
|
278
217
|
|
|
279
218
|
| 工具 | 说明 |
|
|
280
219
|
|------|------|
|
|
@@ -288,27 +227,22 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
|
|
|
288
227
|
| `evaluate_signal` | 历史信号胜率回测 |
|
|
289
228
|
| `detect_anomaly` | 当日技术、量价与资金异动扫描 |
|
|
290
229
|
|
|
291
|
-
`trend_temperature`
|
|
292
|
-
|
|
293
|
-
月度右侧趋势策略,通过 `analyze_trend_strategy(symbols, ...)` 调用:月初200日线上行入场、真实旧仓优先、63日波动预算;[输入格式与完整规则](skills/bull-trend/references/monthly-trend-strategy.md)。扩展及历史样本尚未通过完整效果门槛;直接提供股票代码即可自动取日K,输出信号与预算计划;实际成交/股数和共享资金回测另行核实,不自动保存持仓或下单。
|
|
294
|
-
|
|
295
|
-
趋势研究另返回 `trend_horizons`(daily、建议count=360):21/63/252根日K过去对数收益,在月初首根有效日K收盘观察并保持;显示期限组成、方向及观察日期,不强凑七档。与回测 `monthly_momentum` 共用计算,仍为 `not_validated`;[方法、预热与验证局限](skills/bull-trend/references/trend-horizons.md)。
|
|
296
|
-
|
|
297
|
-
市场只约束新开仓的三期限实验可运行 [market_trend.py](skills/bull-trend/scripts/market_trend.py),输入带预热的个股/同市场宽基daily OHLCV JSON,复用同一Python核心。月度入场、次日开盘、已有持仓按个股趋势退出;不会自动保存持仓或下单。[使用与当前验证边界](skills/bull-trend/references/trend-horizons.md#市场环境入场实验)。
|
|
230
|
+
趋势温度 `trend_temperature`、多期限趋势 `trend_horizons`、月度右侧趋势策略和市场环境入场实验均为 `not_validated` 的研究工具,公式、边界与验证局限见 [工具行为与可靠性 · 趋势研究](docs/tool-behavior.md#趋势研究)。
|
|
298
231
|
|
|
299
|
-
|
|
232
|
+
#### 筛选与回测
|
|
300
233
|
|
|
301
234
|
| 工具 | 说明 |
|
|
302
235
|
|------|------|
|
|
303
|
-
| `screen_stocks` |
|
|
236
|
+
| `screen_stocks` | 全市场多因子筛选(流动性使用成交额 turnover;可选 L2;factor_coverage 展示缺失因子与实际权重) |
|
|
304
237
|
| `screen_risk` | 风险因子筛查 |
|
|
305
238
|
| `run_backtest` | YAML 策略回测,默认收盘信号于次日开盘成交,execution 返回模型与限制 |
|
|
306
|
-
| `detect_market_regime` |
|
|
239
|
+
| `detect_market_regime` | A/HK/US/JP/KR/TW 市场状态检测(返回实际 as_of 和警告;板块热点仅 A 股) |
|
|
307
240
|
| `get_market_review` | 市场日度复盘数据 |
|
|
308
241
|
| `get_review_history` | 复盘归档历史(最近 N 条,最新在前,用于纵向对比) |
|
|
242
|
+
| `get_watchlist` | 读取 dsh 仪表盘自选股,按首选写法返回代码;`600519` / `sh600519` 等价去重 |
|
|
309
243
|
| `run_watchlist_analysis` | 批量自选股分析 |
|
|
310
244
|
|
|
311
|
-
|
|
245
|
+
#### 搜索与舆情
|
|
312
246
|
|
|
313
247
|
| 工具 | 说明 |
|
|
314
248
|
|------|------|
|
|
@@ -316,21 +250,21 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
|
|
|
316
250
|
| `search_comprehensive_intel` | 综合情报搜索 |
|
|
317
251
|
| `get_social_sentiment` | 社交媒体情绪(A 股:东财股吧 + 雪球;美港股:Reddit / X / Polymarket) |
|
|
318
252
|
| `get_trending_sentiment` | 社交媒体热门趋势聚合(Reddit / X / Polymarket) |
|
|
319
|
-
| `extract_article` |
|
|
253
|
+
| `extract_article` | 网页 / 公告 PDF 正文提取;`max_chars` 默认 3000、上限 200000,返回 `truncated` |
|
|
320
254
|
|
|
321
|
-
|
|
255
|
+
#### 辅助
|
|
322
256
|
|
|
323
257
|
| 工具 | 说明 |
|
|
324
258
|
|------|------|
|
|
325
|
-
| `resolve_stock_name` |
|
|
259
|
+
| `resolve_stock_name` | A/HK/US 中文股票名、拼音与代码模糊匹配;港美名录单市场失败可降级 |
|
|
326
260
|
| `check_trading_day` | 查询是否交易日 |
|
|
327
|
-
| `get_trading_days` | 获取前后 N
|
|
261
|
+
| `get_trading_days` | 获取前后 N 个交易日;日历未覆盖的推测日期单列 `assumed_trading_days` |
|
|
328
262
|
| `get_trading_phase` | 查询市场当前交易时段(盘前/盘中/盘后/休市) |
|
|
329
263
|
| `diagnose_data_sources` | 诊断数据源、环境变量和市场链路 |
|
|
330
264
|
| `get_market_capabilities` | 查询各市场支持的工具边界 |
|
|
331
265
|
| `parse_stock_list` | 从自然语言、CSV 或 Markdown 解析股票列表 |
|
|
332
266
|
|
|
333
|
-
|
|
267
|
+
#### 上下文与报告
|
|
334
268
|
|
|
335
269
|
| 工具 | 说明 |
|
|
336
270
|
|------|------|
|
|
@@ -343,17 +277,9 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
|
|
|
343
277
|
| `render_stock_report` | 将结构化个股报告渲染为 Markdown,展示 evidence 与 data_quality 限制 |
|
|
344
278
|
| `render_market_report` | 将结构化市场复盘渲染为 Markdown(save=true 时归档到本地 JSONL) |
|
|
345
279
|
|
|
346
|
-
|
|
280
|
+
批量分析的成功判定、信号存储与结算、风险筛查缺失值、选股与回测字段语义见 [工具行为与可靠性](docs/tool-behavior.md#自选股批量分析信号与筛选)。
|
|
347
281
|
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
信号记录支持同一存储文件的多进程读写;评估期间新增的信号会保留。价格必须为正的有限数值,持有期限为正整数,日期格式为 YYYY-MM-DD。存储文件含损坏 JSON 行或无效信号时,记录、评估和汇总返回错误,原文件保持原样。
|
|
351
|
-
|
|
352
|
-
信号评估仅在历史 K 线覆盖记录日时结算,缺少历史窗口则返回 `skipped_no_data` 并保持未结算。风险筛查返回 `data_complete` 和 `warnings`;数据不足时评级可为 `unknown`,`risk_score`、`veto_buy` 可为 null。告警的 `evaluated` 条目含 `error` 时表示无法检查,不能将未触发理解为已通过检查。
|
|
353
|
-
|
|
354
|
-
选股的 `filters_applied` 只列实际执行的条件,显式条件缺少数据时报错。回测的 `period` 是实际数据期间,`requested_period` 保留请求期间,`warnings` 提示覆盖差异;买入预算包含佣金,年化收益和回撤按实际数据及初始资金计算。
|
|
355
|
-
|
|
356
|
-
### 无状态研究与风险计算
|
|
282
|
+
#### 无状态研究与风险计算
|
|
357
283
|
|
|
358
284
|
| 工具 | 说明 |
|
|
359
285
|
|------|------|
|
|
@@ -362,38 +288,20 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
|
|
|
362
288
|
| `analyze_portfolio_risk` | 一次性持仓的集中度、行业/币种敞口、价格盈亏、止损情景、可选相关性与市场/行业/个股/汇率压力测试 |
|
|
363
289
|
| `plan_portfolio_rebalance` | 按目标权重、整手、费用和现金约束生成先卖后买的调仓计划,返回未满足数量与调后敞口 |
|
|
364
290
|
| `calculate_position_size` | 按现金、风险预算、费用、滑点和交易单位计算本次可买数量 |
|
|
291
|
+
| `calculate_dcf_valuation` | 按显式假设计算达摩达兰式 FCFF DCF、股权价值、每股价值与敏感性 |
|
|
365
292
|
| `analyze_event_study` | 事件前一交易日收盘至各窗口的股票/基准收益差,标明缺失和重叠样本 |
|
|
366
293
|
| `validate_backtest` | 复用现有引擎,滚动训练选候选、样本外验证,比较参数及多个标的 |
|
|
367
294
|
| `compare_analysis_snapshots` | 比较调用方传入的快照,区分新增、删除、变化、数据失效和恢复 |
|
|
368
295
|
|
|
369
|
-
|
|
296
|
+
这些工具不保存自选股、账户或分析历史,也不提供调度/通知。输入格式、仓位预算示例与解读边界见 [工具行为与可靠性 · 无状态研究](docs/tool-behavior.md#无状态研究与风险计算)。
|
|
370
297
|
|
|
371
|
-
|
|
298
|
+
</details>
|
|
372
299
|
|
|
373
|
-
|
|
300
|
+
字段语义、部分失败和缺失数据的处理方式见 [工具行为与可靠性](docs/tool-behavior.md)。
|
|
374
301
|
|
|
375
|
-
|
|
376
|
-
{
|
|
377
|
-
"equity": 100000, "cash": 20000,
|
|
378
|
-
"entry_price": 100, "stop_price": 95,
|
|
379
|
-
"risk_fraction": 0.01, "lot_size": 100,
|
|
380
|
-
"fee_rate": 0.001, "slippage_rate": 0.001
|
|
381
|
-
}
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
将上述 JSON 保存为 `input.json` 后运行:
|
|
302
|
+
## 策略回测
|
|
385
303
|
|
|
386
|
-
|
|
387
|
-
python tools/stateless_analysis.py position_size --input input.json
|
|
388
|
-
```
|
|
389
|
-
|
|
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 模式仍支持离线计算,两种模式互斥。
|
|
391
|
-
|
|
392
|
-
跨币种组合必须提供显式汇率;价格盈亏不含历史汇兑损益。组合压力测试是用户指定市场/行业/个股/汇率冲击的确定性 what-if,个股冲击覆盖行业、行业覆盖市场,汇率独立乘算,不是预测或最大亏损保证。调仓工具按目标权重和整手生成计划,先卖后买;现金不足时同比例缩减买单并以 `cash_limited/unfilled` 标记,计划数量不代表成交。稳健性工具仅支持 next_open、每窗口重新从现金开始,样本内敏感性不等于样本外表现。
|
|
393
|
-
|
|
394
|
-
## 策略回测 DSL
|
|
395
|
-
|
|
396
|
-
策略以 YAML 格式定义,支持参数化和条件组合:
|
|
304
|
+
策略用 YAML 描述,支持参数化和条件组合:
|
|
397
305
|
|
|
398
306
|
```yaml
|
|
399
307
|
name: "RSI Oversold Bounce"
|
|
@@ -433,91 +341,23 @@ position:
|
|
|
433
341
|
max_positions: 1
|
|
434
342
|
```
|
|
435
343
|
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
其他可用键:
|
|
439
|
-
|
|
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 或混合口径明确报错。
|
|
443
|
-
- `simulation`(顶层):交易成本。`slippage`(滑点,买卖双边,默认 0.001)、`commission`(佣金,买卖双边,默认 0.0015)、`stamp_tax`(印花税,仅卖出收取,默认 0;A股为 0.0005,各市场税率不同且会调整,按当下实际费率填写)。费率均须在 [0, 1) 区间,越界报错。回测结果附带 `costs` 块(实际生效费率与实付费用合计 `commission_paid`/`stamp_tax_paid`)。
|
|
444
|
-
|
|
445
|
-
### 可用指标
|
|
446
|
-
|
|
447
|
-
| 指标 | 说明 | 需要 period |
|
|
448
|
-
|------|------|-------------|
|
|
449
|
-
| `rsi` | RSI 相对强弱指数;预热不足不可用,全涨窗口为 100,全平为 50 | 是(默认 14) |
|
|
450
|
-
| `ma` / `ema` | 简单 / 指数移动平均 | 是(默认 20) |
|
|
451
|
-
| `macd_dif` / `macd_dea` / `macd` | MACD 三线 | 否 |
|
|
452
|
-
| `volume_ratio` | 当根成交量 / 前 N 根平均成交量(不含当根) | 是(默认 5) |
|
|
453
|
-
| `price_change` | 涨跌幅(%) | 否 |
|
|
454
|
-
| `bollinger_position` | 布林带位置(0=下轨, 1=上轨) | 是(默认 20) |
|
|
455
|
-
| `trend_score` | 独立实验趋势强度,默认 (EMA20−EMA60)/ATR14;fast_period/slow_period 控制 EMA | period 为 ATR 根数(默认 14) |
|
|
456
|
-
| `monthly_momentum` | 月初首根有效日K收盘观察过去 period 根对数收益,保持到下一观察;零成交量不计根数 | 是(默认63,要求正整数) |
|
|
457
|
-
| `close` / `volume` | 收盘价 / 成交量 | 否 |
|
|
458
|
-
|
|
459
|
-
### 可用运算符
|
|
460
|
-
|
|
461
|
-
`>` `<` `>=` `<=` `==` `cross_above`(上穿) `cross_below`(下穿)
|
|
462
|
-
|
|
463
|
-
示例策略见 `strategies/examples/`。
|
|
464
|
-
|
|
465
|
-
## 市场路由规则
|
|
466
|
-
|
|
467
|
-
| 代码格式 | 示例 | 市场 | 行情报价 Failover 链(K 线差异见下方) |
|
|
468
|
-
|----------|------|------|---------------------|
|
|
469
|
-
| 6 位纯数字 | `600519`, `000001`, `300750` | A 股 | akshare → tushare → efinance → 腾讯 → 新浪 → pytdx → baostock |
|
|
470
|
-
| 6 位纯数字(51/52/56/58/15/16/18 开头) | `510300`, `159915` | A 股 ETF | akshare(基金接口)→ tushare → efinance → 腾讯 → 新浪 → pytdx → baostock |
|
|
471
|
-
| 带交易所前缀(`sh`/`sz`/`bj` + 6 位数字) | `sh000001`(上证指数), `sz399006`(创业板指) | A 股(显式指定,含指数) | 腾讯 → 新浪 |
|
|
472
|
-
| `.HK` 结尾 | `00700.HK`, `09988.HK` | 港股 | yfinance → 腾讯 → finnhub → longbridge |
|
|
473
|
-
| 英文字母 | `AAPL`, `GOOGL`, `TSLA` | 美股 | yfinance → finnhub → longbridge → alphavantage |
|
|
474
|
-
| `.T` 结尾 | `7203.T` | 日股 | yfinance |
|
|
475
|
-
| `.KS` / `.KQ` 结尾 | `005930.KS`, `036020.KQ` | 韩股 | yfinance |
|
|
476
|
-
| `.TW` / `.TWO` 结尾 | `2330.TW`, `6510.TWO` | 台股 | yfinance |
|
|
477
|
-
|
|
478
|
-
> 各数据源按优先级自动尝试,前一个失败后自动切换到下一个。未配置相关 env var 的数据源会被跳过。
|
|
479
|
-
> 港股腾讯备用源使用 `r_hk` 通道(`hk` 通道延迟约 15 分钟),仅用于实时报价,K 线仍走 yfinance → finnhub → longbridge。支持 `00700.HK` / `0700.HK` / `700.hk`,成交量单位为股,成交额及市值为港元;PB、换手率、量比在此备用源中返回 null,不套用 A 股字段。
|
|
480
|
-
> 裸 6 位代码一律按**个股**处理(`000001` 是平安银行);指数需带交易所前缀(`sh000001` = 上证指数),显式前缀代码直接走腾讯/新浪(东财源只认裸代码)。
|
|
481
|
-
> **A 股 K 线口径**:股票/ETF 仅接受前复权数据,链路为 akshare → tushare(仅股票)→ efinance → 腾讯(仅 qfq 数据)→ baostock;带前缀的股票/ETF 先去前缀再走同一链路。新浪和 pytdx 的未复权 K 线不参与股票/ETF 容灾。显式指数 `sh000xxx` / `sz399xxx` 保留原始点位,走腾讯 → 新浪 → baostock。上述路由表的完整链路仍适用于实时行情。
|
|
482
|
-
> 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)。
|
|
483
|
-
> **粘性优选**:A 股链路(K 线 / 行情 / 市场快照 / 板块成分)会记住最近一次成功的数据源(缓存在系统临时目录,24h 有效),下次调用优先从它开始;若它已失效则自动顺延并更新记录。港美股链路不做粘性——一次 yfinance 瞬时失败不应让后续全天的 quote 降质。
|
|
484
|
-
> 日/韩/台股仅 yfinance 一个数据源(免费数据延迟约 15 分钟);港股 / 美股 / 日股 / 韩股 / 台股的 ETF 与其所在市场股票走相同链路。
|
|
344
|
+
可用指标包括 RSI、MA/EMA、MACD、量比、布林带位置、趋势强度和月度动量,运算符支持比较和 `cross_above` / `cross_below`。止损、移动止损、基准对比、成交口径和交易成本见 [回测 DSL 参考](docs/backtest-dsl.md),示例策略在 `strategies/examples/`。
|
|
485
345
|
|
|
346
|
+
## 独立 CLI 使用
|
|
486
347
|
|
|
487
|
-
|
|
348
|
+
不接 Agent 也能直接用,所有命令输出 JSON:
|
|
488
349
|
|
|
489
350
|
```bash
|
|
490
|
-
python tools/
|
|
491
|
-
python tools/stock_data.py
|
|
492
|
-
python tools/
|
|
493
|
-
python tools/
|
|
494
|
-
python tools/
|
|
495
|
-
python tools/
|
|
496
|
-
python tools/value_data.py etf_details 510300 --benchmark sh000300 --days 60
|
|
497
|
-
python tools/value_data.py etf_details 510300 --include-full-holdings
|
|
498
|
-
python tools/stock_data.py margin_trading 600519 --days 10 --include-ratio
|
|
499
|
-
python tools/value_data.py dividends --symbol 600519
|
|
500
|
-
python tools/value_data.py dividends --symbol 0700.HK --mode calendar
|
|
501
|
-
python tools/value_data.py dividends --mode ranking --report-date 2025-12-31
|
|
502
|
-
python tools/value_data.py dividends --mode ranking --market HK --report-date 2025-12-31
|
|
503
|
-
python tools/value_data.py earnings_calendar --symbol 0700.HK
|
|
351
|
+
python tools/stock_data.py quote 600519
|
|
352
|
+
python tools/stock_data.py kline AAPL --period weekly --count 30
|
|
353
|
+
python tools/technical.py analyze 600519
|
|
354
|
+
python tools/screener.py screen --market A --top 20
|
|
355
|
+
python tools/backtest.py run strategies/examples/rsi_oversold.yaml 600519 --start 2024-01-01 --end 2025-01-01
|
|
356
|
+
python tools/market_regime.py detect A
|
|
504
357
|
```
|
|
505
358
|
|
|
506
|
-
|
|
507
|
-
|
|
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 按源实际可得年数返回,不补造缺失比率。
|
|
509
|
-
|
|
510
|
-
股东数据保留报告期、公告日或港交所披露日: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`。日期转为香港日期,公告表也不承诺覆盖所有港股。
|
|
511
|
-
|
|
512
|
-
ETF 使用披露资产规模历史(元)与披露持仓,保留持仓原始证券代码,不冒充实时完整申赎篮子;新增 `basket` 返回沪深交易所发布的完整当日 PCF(跨境代码原样保留),包含申赎单位、每篮子证券数量、现金替代规则与比例;校验基金代码、实际日期和全部组件数量,失败只提示不可用,不冒充完整。PCF 是申赎对价,不是实际持仓,证券数量也不是净值权重。`include_full_holdings=true` 时另取最近可得半年度/年度披露股票表,显式指定年份/月并请求较高行数上限,包含股票数量(股)、市值(人民币元)和实际报告期;返回全部收到的表格行,但不声称覆盖债券/现金等全资产或实时持仓,也不以 PCF 数量验证实际持仓。默认不取数百行明细。提供 `benchmark` 可另查基准指数成分。净值折溢价仅在行情/净值日期相同才计算,IOPV 折溢价另列。跟踪误差使用相同连续交易日区间的基金日净值增长与基准收盘收益差,取样本标准差乘 `sqrt(252)`,不填补缺失日期、不猜测基准。两融占比只匹配同一天的人民币元成交额,缺失则 null。
|
|
513
|
-
|
|
514
|
-
股息历史将预案与已实施分红分开,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填充。
|
|
515
|
-
|
|
516
|
-
数据源参考:[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)。
|
|
517
|
-
|
|
518
|
-
## 独立 CLI 使用
|
|
519
|
-
|
|
520
|
-
Python 工具可脱离 Agent 独立使用,所有输出为 JSON:
|
|
359
|
+
<details>
|
|
360
|
+
<summary>更多命令</summary>
|
|
521
361
|
|
|
522
362
|
```bash
|
|
523
363
|
# 行情数据
|
|
@@ -553,44 +393,105 @@ python tools/risk_screening.py screen 600519
|
|
|
553
393
|
|
|
554
394
|
# 市场状态
|
|
555
395
|
python tools/market_regime.py detect A
|
|
396
|
+
|
|
397
|
+
# 估值、财报、股东、ETF 与分红
|
|
398
|
+
python tools/value_data.py valuation_history 600519 --years 5
|
|
399
|
+
python tools/stock_data.py financials 600519 --annual --periods 10
|
|
400
|
+
python tools/value_data.py earnings_calendar --report-date 2026-09-30 --symbol 600519
|
|
401
|
+
python tools/value_data.py shareholder_structure 600519 --report-date 2026-06-30
|
|
402
|
+
python tools/value_data.py shareholder_structure 0700.HK
|
|
403
|
+
python tools/value_data.py index_valuation 000300 --years 5
|
|
404
|
+
python tools/value_data.py etf_details 510300 --benchmark sh000300 --days 60
|
|
405
|
+
python tools/value_data.py etf_details 510300 --include-full-holdings
|
|
406
|
+
python tools/stock_data.py margin_trading 600519 --days 10 --include-ratio
|
|
407
|
+
python tools/value_data.py dividends --symbol 600519
|
|
408
|
+
python tools/value_data.py dividends --symbol 0700.HK --mode calendar
|
|
409
|
+
python tools/value_data.py dividends --mode ranking --report-date 2025-12-31
|
|
410
|
+
python tools/value_data.py dividends --mode ranking --market HK --report-date 2025-12-31
|
|
411
|
+
python tools/value_data.py earnings_calendar --symbol 0700.HK
|
|
412
|
+
|
|
413
|
+
# 公告与港股长期财务
|
|
414
|
+
python tools/value_data.py announcements 600519 --category forecast --start-date 2026-01-01 --end-date 2026-10-13 --top 50
|
|
415
|
+
python tools/stock_data.py financials 0700.HK --annual --periods 10
|
|
416
|
+
python tools/value_data.py valuation_history 0700.HK --years 10
|
|
417
|
+
|
|
418
|
+
# SEC 13F / Form 4(SEC_USER_AGENT 必须配置为应用名称 + 你的真实联系邮箱)
|
|
419
|
+
python tools/sec_edgar.py holdings 0001067983
|
|
420
|
+
python tools/sec_edgar.py insider_trades AAPL --days 90 --top 10
|
|
421
|
+
python tools/sec_edgar.py holdings 0000320193 --mode issuer # 发行人 CIK 反查持仓机构
|
|
556
422
|
```
|
|
557
423
|
|
|
558
|
-
|
|
424
|
+
</details>
|
|
559
425
|
|
|
560
|
-
|
|
426
|
+
## 常见问题
|
|
561
427
|
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
| `OPENAI_BASE_URL` | Variable 或 Secret | OpenAI 兼容的 API base URL,包含服务商要求的路径(例如 `/v1`) |
|
|
565
|
-
| `OPENAI_API_KEY` | Secret | 对应的 API key |
|
|
566
|
-
| `OPENAI_MODEL` | Variable 或 Secret | 支持 tool calling 的模型 ID |
|
|
428
|
+
**Python 工具报错 `ModuleNotFoundError`?**
|
|
429
|
+
运行 `pip install -r tools/requirements.txt`。使用 virtualenv / conda 时,确保 Agent 启动时用的是同一个 Python 环境。
|
|
567
430
|
|
|
568
|
-
|
|
431
|
+
**A 股数据获取失败?**
|
|
432
|
+
报价会依次尝试腾讯、akshare、tushare、efinance 和新浪,K 线另有 baostock 兜底。都失败时,检查网络、升级 akshare(`pip install --upgrade akshare`),或配置 `TUSHARE_TOKEN` 增加一个可靠数据源。
|
|
433
|
+
|
|
434
|
+
**港股 / 美股数据有延迟?**
|
|
435
|
+
yfinance 免费数据通常延迟约 15 分钟。配置 Longbridge(`LONGBRIDGE_APP_KEY` 等)或 Finnhub(`FINNHUB_API_KEY`)可获得更实时的数据。
|
|
569
436
|
|
|
570
|
-
|
|
437
|
+
**如何自定义选股条件?**
|
|
438
|
+
写一个 YAML,再运行 `python tools/screener.py screen --config my_filter.yaml --top 30`:
|
|
439
|
+
|
|
440
|
+
```yaml
|
|
441
|
+
name: "我的选股策略"
|
|
442
|
+
filters:
|
|
443
|
+
pe_min: 5
|
|
444
|
+
pe_max: 25
|
|
445
|
+
pb_max: 3
|
|
446
|
+
market_cap_min: 20e9
|
|
447
|
+
sort_by: "composite_score"
|
|
448
|
+
sort_order: "desc"
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
**如何编写回测策略?**
|
|
452
|
+
参考 `strategies/examples/` 和 [回测 DSL 参考](docs/backtest-dsl.md),也可以直接让 Agent 帮你写。
|
|
453
|
+
|
|
454
|
+
## 参与开发
|
|
455
|
+
|
|
456
|
+
所有业务逻辑都在 `tools/*.py`,每个工具是一个输出 JSON 的 CLI。`pi/`、`hermes/`、`openclaw/`、`dsh/` 四个适配器只负责把宿主的工具调用转成子进程调用,`mcp_host/` 复用 Hermes 的工具定义。Skills 放在 `skills/*/SKILL.md`,四个宿主共用。
|
|
457
|
+
|
|
458
|
+
```bash
|
|
459
|
+
npm install # 同时构建仓库 .venv
|
|
460
|
+
.venv/bin/python -m pytest -q # Python 单元测试(离线)
|
|
461
|
+
npx tsc --noEmit # TypeScript 类型检查
|
|
462
|
+
npx tsx tests/test_adapter_parity.ts # 四个宿主的 74 个工具和参数映射一致
|
|
463
|
+
npm run build:openclaw && npm run build:dsh # 构建 OpenClaw / dsh bundle
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
开发约定、完整测试命令和跨平台注意事项见 [AGENTS.md](AGENTS.md)。
|
|
467
|
+
|
|
468
|
+
<details>
|
|
469
|
+
<summary>项目结构</summary>
|
|
571
470
|
|
|
572
471
|
```
|
|
573
472
|
stock-analysis/
|
|
574
473
|
├── pi/ # Pi Agent Extension
|
|
575
|
-
│ └── index.ts # 注册
|
|
474
|
+
│ └── index.ts # 注册 74 个工具 + 21 个 skill
|
|
576
475
|
├── hermes/ # Hermes Agent Plugin
|
|
577
476
|
│ ├── plugin.yaml # 插件清单
|
|
578
477
|
│ ├── __init__.py # register(ctx) 入口
|
|
579
|
-
│ ├── schemas.py #
|
|
580
|
-
│ └── tools.py #
|
|
478
|
+
│ ├── schemas.py # 读取 tools/tool_schemas.json
|
|
479
|
+
│ └── tools.py # 74 个 handler → subprocess 调 CLI
|
|
581
480
|
├── openclaw/ # OpenClaw Plugin
|
|
582
481
|
│ ├── openclaw.plugin.json # manifest(contracts.tools)
|
|
583
482
|
│ ├── package.json # 含 openclaw 块(pluginApi/SDK 版本)
|
|
584
|
-
│ └── index.ts # definePluginEntry +
|
|
483
|
+
│ └── index.ts # definePluginEntry + 按共享 schema 注册
|
|
585
484
|
├── dsh/ # DeepSeek Harness (dsh) Plugin
|
|
586
485
|
│ ├── cordis.patch.yml # bundle patch(insert 插件入口)
|
|
587
486
|
│ ├── package.json # dsh.bundle + dsh.client manifest
|
|
588
|
-
│ ├── index.ts # cordis apply(ctx) +
|
|
487
|
+
│ ├── index.ts # cordis apply(ctx) + 按共享 schema 注册
|
|
589
488
|
│ ├── dashboard.ts # 后台预热缓存 + 快照/自选股 HTTP API 与持久化
|
|
590
489
|
│ ├── client.ts # 侧栏入口 + 主面板 + 主题同步(编译为 dist/client.js)
|
|
591
490
|
│ └── web/ # 仪表盘页面(app.ts 编译为 dist/web/app.js)
|
|
592
491
|
│
|
|
492
|
+
├── mcp_host/ # MCP stdio 服务器(复用 Hermes schema/handler)
|
|
593
493
|
├── tools/ # 共享 Python CLI 工具
|
|
494
|
+
│ ├── tool_schemas.json # 74 个工具的名称/描述/参数(各宿主共用)
|
|
594
495
|
│ ├── stock_data.py # 行情 / 资金流 / 新闻 / 财务 / 短线情绪
|
|
595
496
|
│ ├── signal_tracker.py # AI 买卖建议回测闭环(本地 JSONL 存储)
|
|
596
497
|
│ ├── technical.py # 技术指标分析
|
|
@@ -620,17 +521,17 @@ stock-analysis/
|
|
|
620
521
|
└── tsconfig.json
|
|
621
522
|
```
|
|
622
523
|
|
|
623
|
-
|
|
524
|
+
数据流:
|
|
624
525
|
|
|
625
526
|
```
|
|
626
527
|
用户 (自然语言)
|
|
627
528
|
│
|
|
628
529
|
▼
|
|
629
|
-
Agent (Pi / Hermes / OpenClaw / dsh)
|
|
530
|
+
Agent (Pi / Hermes / OpenClaw / dsh / MCP)
|
|
630
531
|
│
|
|
631
532
|
├── 加载 SKILL.md → 分析框架 / 流程指引
|
|
632
533
|
│
|
|
633
|
-
├── 调用工具 → pi/index.ts
|
|
534
|
+
├── 调用工具 → pi/index.ts、hermes/tools.py、openclaw/index.ts、dsh/index.ts 或 mcp_host/server.py → python tools/xxx.py → JSON
|
|
634
535
|
│
|
|
635
536
|
▼
|
|
636
537
|
Agent (LLM 分析 + 生成报告)
|
|
@@ -639,96 +540,31 @@ Agent (LLM 分析 + 生成报告)
|
|
|
639
540
|
用户看到结构化分析结果
|
|
640
541
|
```
|
|
641
542
|
|
|
642
|
-
|
|
543
|
+
</details>
|
|
643
544
|
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
- [yfinance](https://github.com/ranaroussi/yfinance) — 港股 / 美股数据源
|
|
647
|
-
- [pytdx](https://github.com/rainx/pytdx) — 通达信 TDX 协议(A 股免费兜底)
|
|
648
|
-
- [longport](https://github.com/longportapp/openapi-sdk) — Longbridge OpenAPI(港股 / 美股)
|
|
649
|
-
- [exchange-calendars](https://github.com/gerrymanoim/exchange_calendars) — 全球交易日历
|
|
650
|
-
|
|
651
|
-
## 常见问题
|
|
652
|
-
|
|
653
|
-
### Q: Python 工具报错 `ModuleNotFoundError`?
|
|
545
|
+
<details>
|
|
546
|
+
<summary>Python 依赖</summary>
|
|
654
547
|
|
|
655
548
|
```bash
|
|
656
549
|
pip install -r tools/requirements.txt
|
|
657
550
|
```
|
|
658
551
|
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
### Q: A 股数据获取失败?
|
|
662
|
-
|
|
663
|
-
系统会自动按 akshare → tushare → efinance → 腾讯 → 新浪 → pytdx → baostock 顺序尝试(A 股链路含粘性优选:最近成功的源 24h 内优先)。腾讯 / 新浪源不依赖东财域名,在境外或受限网络下通常仍可用。如果所有源都失败,检查:网络问题、akshare 版本过低(`pip install --upgrade akshare`)、或非交易时间。配置 `TUSHARE_TOKEN` 可增加一个可靠数据源。
|
|
664
|
-
|
|
665
|
-
### Q: 港股 / 美股数据有延迟?
|
|
666
|
-
|
|
667
|
-
yfinance 免费数据通常有 15 分钟延迟。配置 Longbridge(`LONGBRIDGE_APP_KEY` 等)或 Finnhub(`FINNHUB_API_KEY`)可获取更实时的数据,且作为 failover 备用源。
|
|
668
|
-
|
|
669
|
-
### Q: 如何自定义筛选条件?
|
|
670
|
-
|
|
671
|
-
创建 YAML 配置:
|
|
672
|
-
|
|
673
|
-
```yaml
|
|
674
|
-
name: "我的选股策略"
|
|
675
|
-
filters:
|
|
676
|
-
pe_min: 5
|
|
677
|
-
pe_max: 25
|
|
678
|
-
pb_max: 3
|
|
679
|
-
market_cap_min: 20e9
|
|
680
|
-
sort_by: "composite_score"
|
|
681
|
-
sort_order: "desc"
|
|
682
|
-
```
|
|
683
|
-
|
|
684
|
-
CLI 使用:`python tools/screener.py screen --config my_filter.yaml --top 30`
|
|
685
|
-
|
|
686
|
-
### Q: 如何编写自定义回测策略?
|
|
687
|
-
|
|
688
|
-
参考 `strategies/examples/` 下的示例和 [策略回测 DSL](#策略回测-dsl) 章节。也可以直接让 Agent 帮你编写 YAML 策略。
|
|
689
|
-
|
|
690
|
-
## License
|
|
691
|
-
|
|
692
|
-
MIT
|
|
693
|
-
|
|
694
|
-
### 公告与港美股研究数据(#49–#51)
|
|
695
|
-
|
|
696
|
-
```bash
|
|
697
|
-
python3 tools/value_data.py announcements 600519 --category forecast --start-date 2026-01-01 --end-date 2026-10-13 --top 50
|
|
698
|
-
python3 tools/stock_data.py financials 0700.HK --annual --periods 10
|
|
699
|
-
python3 tools/value_data.py valuation_history 0700.HK --years 10
|
|
700
|
-
# SEC_USER_AGENT 必须配置为应用名称 + 你的真实联系邮箱
|
|
701
|
-
python3 tools/sec_edgar.py holdings 0001067983
|
|
702
|
-
python3 tools/sec_edgar.py insider_trades AAPL --days 90 --top 10
|
|
703
|
-
```
|
|
704
|
-
|
|
705
|
-
公告类别为 `all/forecast/express/annual/interim/quarterly/reduction/issuance/inquiry/dividend`。默认最近 90 天,最多 500 条;通过巨潮官方股票目录取得 orgId,沪深京统一使用官方 `szse` 查询栏目。业绩快报和问询使用标题关键词查询。第一版返回 PDF 原文链接,不引入 PDF 解析依赖;`total/truncated` 表示供应商匹配数量及截断,查询无结果与请求失败分开。
|
|
706
|
-
|
|
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 百分数当作小数倍数。
|
|
708
|
-
|
|
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`。
|
|
710
|
-
|
|
711
|
-
Form 4 的 `days` 是申报日期窗口,`top=1..20` 限制文件数,返回全部已解析交易。保留多人联报、衍生品、交易代码、脚注、直接/间接持有和修订信息;仅 P/S 标为买/卖,其余行为不推断方向,价格未披露为 null。读取 `truncated/warnings`,原件与修订不要重复计数。风险组合工具 `screen_risk` 仍为 A 股专用。
|
|
712
|
-
|
|
713
|
-
接口依据:[巨潮公告查询](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)。
|
|
714
|
-
|
|
715
|
-
股票 CIK 反查示例:
|
|
716
|
-
|
|
717
|
-
```bash
|
|
718
|
-
python3 tools/sec_edgar.py holdings 0000320193 --mode issuer
|
|
719
|
-
# 原机构查询保持可用
|
|
720
|
-
python3 tools/sec_edgar.py holdings 0001067983 --mode manager
|
|
721
|
-
```
|
|
722
|
-
|
|
723
|
-
首次下载当前 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 股票。不能将跨机构合计当作已去重的全市场持股。
|
|
724
|
-
|
|
725
|
-
13F CLI 预算为 300 秒,宿主另留 30 秒接收输出;其他命令按共享预算表执行。机构查询优先寻找最新已知报告期的原始 13F:较新修订对应的原始版未找到时明确报错,历史分片仍未完全检索时返回 `history_truncated` 与警告。发行人 CUSIP 查询会跳过不可访问/无效 XML,继续核对后续原文;没有任何可验证映射时才报缺失。
|
|
552
|
+
主要依赖:
|
|
726
553
|
|
|
727
|
-
|
|
554
|
+
| 包 | 用途 |
|
|
555
|
+
|---|------|
|
|
556
|
+
| akshare | A 股数据源(行情、资金流、财务、新闻,含 A 股 ETF) |
|
|
557
|
+
| yfinance | 港股 / 美股 / 日股 / 韩股 / 台股数据源 |
|
|
558
|
+
| pandas / numpy | 数据处理和数值计算 |
|
|
559
|
+
| exchange-calendars | 交易日历(A/HK/US/JP/KR/TW) |
|
|
560
|
+
| newspaper4k / pypdf | HTML 新闻与公告 PDF 正文提取 |
|
|
561
|
+
| pypinyin | 股票名称拼音搜索 |
|
|
562
|
+
| longport | 港股 / 美股 Longbridge SDK |
|
|
728
563
|
|
|
729
|
-
|
|
564
|
+
</details>
|
|
730
565
|
|
|
731
|
-
|
|
566
|
+
<details>
|
|
567
|
+
<summary>报告质量评测与 CI 真实宿主测试</summary>
|
|
732
568
|
|
|
733
569
|
```bash
|
|
734
570
|
.venv/bin/python -m pytest tests/test_analysis_quality.py -q
|
|
@@ -736,12 +572,26 @@ python3 tools/sec_edgar.py holdings 0001067983 --mode manager
|
|
|
736
572
|
.venv/bin/python -m pytest tests/e2e/test_analysis_quality.py -m integration_llm -v
|
|
737
573
|
```
|
|
738
574
|
|
|
739
|
-
|
|
575
|
+
GitHub Actions 的 `e2e-host` 使用 Pi、Hermes、OpenClaw、dsh 的真实运行时执行工具调用。在仓库 **Settings → Secrets and variables → Actions** 中配置以下三项,所有 E2E 共用:
|
|
576
|
+
|
|
577
|
+
| 名称 | 存放位置 | 内容 |
|
|
578
|
+
|---|---|---|
|
|
579
|
+
| `OPENAI_BASE_URL` | Variable 或 Secret | OpenAI 兼容的 API base URL,包含服务商要求的路径(例如 `/v1`) |
|
|
580
|
+
| `OPENAI_API_KEY` | Secret | 对应的 API key |
|
|
581
|
+
| `OPENAI_MODEL` | Variable 或 Secret | 支持 tool calling 的模型 ID |
|
|
740
582
|
|
|
741
|
-
|
|
583
|
+
`e2e-llm` 也使用这三项配置,Hermes(含报告质量评测)、Pi、OpenClaw 和 dsh 通过四个 matrix 作业并行运行,互不因失败而取消;同仓库 PR 和主分支推送会运行,fork PR 不读取 API key。`e2e-host` 缺少任一项时会失败。URL 和 model 同时存在于 Variable 与 Secret 时,优先使用 Secret。
|
|
742
584
|
|
|
743
|
-
|
|
585
|
+
</details>
|
|
744
586
|
|
|
745
|
-
|
|
587
|
+
## 致谢
|
|
746
588
|
|
|
747
|
-
|
|
589
|
+
- [daily_stock_analysis](https://github.com/ZhuLinsen/daily_stock_analysis) — A 股每日分析工具,本项目的综合分析流程参考了其设计思路
|
|
590
|
+
- [akshare](https://github.com/akfamily/akshare) — A 股数据源
|
|
591
|
+
- [yfinance](https://github.com/ranaroussi/yfinance) — 港股 / 美股数据源
|
|
592
|
+
- [longport](https://github.com/longbridge/openapi) — Longbridge OpenAPI(港股 / 美股)
|
|
593
|
+
- [exchange-calendars](https://github.com/gerrymanoim/exchange_calendars) — 全球交易日历
|
|
594
|
+
|
|
595
|
+
## License
|
|
596
|
+
|
|
597
|
+
MIT
|