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.
Files changed (47) hide show
  1. package/README.md +231 -381
  2. package/docs/mcp.md +60 -0
  3. package/hermes/__init__.py +35 -0
  4. package/hermes/plugin.yaml +131 -0
  5. package/hermes/schemas.py +6 -0
  6. package/hermes/tools.py +630 -0
  7. package/mcp_host/__init__.py +1 -0
  8. package/mcp_host/__main__.py +3 -0
  9. package/mcp_host/server.py +222 -0
  10. package/package.json +7 -1
  11. package/pi/index.ts +52 -2906
  12. package/scripts/cli-json.mjs +23 -0
  13. package/scripts/exec-process.mjs +89 -0
  14. package/scripts/setup-python.mjs +37 -4
  15. package/scripts/tool-calls.mjs +489 -0
  16. package/skills/event-driven/SKILL.md +2 -2
  17. package/skills/growth-quality/SKILL.md +1 -1
  18. package/skills/stock-analysis/SKILL.md +8 -6
  19. package/skills/stock-analysis/references/stateless-analysis.md +9 -1
  20. package/tools/_cache.py +13 -0
  21. package/tools/_subproc.py +46 -0
  22. package/tools/alert_rules.py +2 -2
  23. package/tools/backtest.py +3 -3
  24. package/tools/capabilities.py +32 -9
  25. package/tools/cli_budgets.json +2 -0
  26. package/tools/diagnostics.py +3 -4
  27. package/tools/gather.py +2 -6
  28. package/tools/import_parser.py +3 -4
  29. package/tools/lixinger.py +119 -27
  30. package/tools/market_regime.py +5 -2
  31. package/tools/market_review.py +5 -6
  32. package/tools/name_resolver.py +66 -7
  33. package/tools/report_renderer.py +3 -3
  34. package/tools/requirements.txt +5 -4
  35. package/tools/risk_screening.py +3 -2
  36. package/tools/screener.py +6 -4
  37. package/tools/search_intel.py +79 -10
  38. package/tools/sec_edgar.py +266 -0
  39. package/tools/sec_holders.py +6 -0
  40. package/tools/signal_tracker.py +5 -5
  41. package/tools/stateless_analysis.py +115 -0
  42. package/tools/stock_data.py +455 -201
  43. package/tools/tiaa_disclosures.py +4 -0
  44. package/tools/tool_schemas.json +2704 -0
  45. package/tools/trading_calendar.py +65 -30
  46. package/tools/value_data.py +366 -134
  47. package/tools/watchlist.py +43 -5
package/README.md CHANGED
@@ -1,141 +1,101 @@
1
1
  # stock-analysis-plugin
2
2
 
3
- [![npm](https://img.shields.io/npm/v/@weaxs/stock-analysis-plugin?label=npm&logo=npm)](https://www.npmjs.com/package/@weaxs/stock-analysis-plugin)
3
+ [![npm](https://img.shields.io/npm/v/stock-analysis-plugin?label=npm&logo=npm)](https://www.npmjs.com/package/stock-analysis-plugin)
4
4
  [![PyPI](https://img.shields.io/pypi/v/stock-analysis-plugin?label=pypi&logo=pypi&logoColor=white)](https://pypi.org/project/stock-analysis-plugin/)
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
6
6
  [![Python](https://img.shields.io/badge/python-%3E=3.10-blue?logo=python&logoColor=white)](https://www.python.org/)
7
7
 
8
- A 股 / 港股 / 美股 / 日股 / 韩股 / 台股综合分析、多因子选股和策略回测工具集,可作为 [Pi Agent](https://github.com/anthropics/pi-agent) Extension、[Hermes Agent](https://github.com/NousResearch/hermes-agent) Plugin、[OpenClaw](https://docs.openclaw.ai/) Plugin,或 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) Plugin 使用。
8
+ 给 AI Agent 用的股票研究工具箱,覆盖 **A 股、港股、美股、日股、韩股、台股**。装进你常用的 Agent 后,直接用自然语言查行情、做个股分析、全市场选股、写策略回测、做盘后复盘。
9
9
 
10
- 底层共享同一套 Python CLI 工具和 SKILL.md 工作流,上层分别适配四个平台的注册机制。
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
+ ![dsh 股票仪表盘:六市场自选股行情、指数带、A 股涨跌分布与行业涨跌榜](https://raw.githubusercontent.com/Weaxs/stock-analysis-plugin/main/docs/images/dsh-dashboard-light.png)
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
- - **72 个工具** — 行情数据、技术分析、K 线形态、资金流向、估值历史、财报日历、股东/ETF/股息、新闻舆情、风险筛查、市场状态等
36
- - **21 个 Skills** — 综合分析、全市场选股、策略回测 + 18 个策略、复盘与研究方法论(缠论、波浪、龙头、情绪周期等)
37
- - **策略回测引擎** — YAML DSL 定义策略,参数化条件组合,自动诊断,按需进行有限轮参数优化
38
- - **多数据源 Failover** — 11 个数据源自动容灾切换(akshare / tushare / efinance / 腾讯行情 / 新浪行情 / pytdx / baostock / yfinance / finnhub / longbridge / alphavantage),A 股链路带粘性优选(最近成功的数据源下次优先尝试)
39
- - **社交舆情增强** — A 股(东财股吧 + 雪球)/ 美港股(Reddit / X / Polymarket),市场自动路由
40
- - **四平台适配** — 同一套工具同时支持 Pi Agent、Hermes Agent、OpenClaw 和 dsh
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
- > 所有 npm 包同时以 scoped(`@weaxs/*`)和非 scoped 同名两种名字发布,内容一致,任选其一即可。
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
- ### Pi Agent Extension
41
+ 每个 npm 包也以 `@weaxs/` scoped 名发布(如 `@weaxs/dsh-stock-analysis`),内容一致。装的是 scoped 版时,配置里引用包名的地方也用 scoped 名。
58
42
 
59
- ```bash
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
- > 也可以直接 `git clone git@github.com:Weaxs/stock-analysis-plugin.git` 使用源码版本。
70
-
71
- Pi 启动后自动加载,输入 `/skills` 确认。详见 [Pi Agent 接入指南](docs/pi-integration.md)([English](docs/pi-integration.en.md))。
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
- 安装后 Hermes 通过 `hermes_agent.plugins` entry point 自动发现并注册,无需手动复制目录。
53
+ 也可以显式调用 Skill,例如 `/skill:stock-analysis`、`/skill:wave-theory`。
82
54
 
83
- 或在 Python 中直接注册:
55
+ ### 各宿主的注意事项
84
56
 
85
- ```python
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
- 详见 [Hermes Agent 接入指南](docs/hermes-integration.md)([English](docs/hermes-integration.en.md))。
59
+ **Hermes**:通过 `hermes_agent.plugins` entry point 自动发现,无需复制目录;也可以在 Python 中 `from hermes import register; register(ctx)`。
91
60
 
92
- ### OpenClaw Plugin
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
- ```bash
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
- OpenClaw Gateway 启动后自动加载并注册 72 个 tool。安装时 postinstall 会自动建 `.venv` 并装好 Python 依赖(前提:本机有 `python3 >= 3.10`)。
65
+ **MCP**:源码方式运行 `.venv/bin/python mcp_host/server.py`,或 `python -m mcp_host`。客户端配置示例见 [MCP 接入指南](docs/mcp.md)。
99
66
 
100
- 详见 [OpenClaw 接入指南](docs/openclaw-integration.md),或 plugin 自身说明 [`openclaw/README.md`](openclaw/README.md)。
67
+ ## dsh 股票仪表盘
101
68
 
102
- ### dsh (DeepSeek Harness) Plugin
69
+ 装了 dsh 插件的 Web / Desktop 会在侧栏出现「股票仪表盘」:
103
70
 
104
- ```bash
105
- dsh plugin --profile <你的profile> add @weaxs/dsh-stock-analysis
106
- dsh --profile <你的profile>
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
- 详见 [`dsh/README.md`](dsh/README.md)。
76
+ 刷新节奏、数据来源和存储位置见 [dsh 插件说明](dsh/README.md#股票仪表盘web--desktop)。
116
77
 
117
- ### Python 依赖
78
+ ## 支持的市场
118
79
 
119
- ```bash
120
- pip install -r tools/requirements.txt
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
- > A 股行情另有**腾讯(qt.gtimg.cn)/ 新浪(hq.sinajs.cn)**两个免鉴权兜底源,直接 HTTP 调用,用于东财域名不可达的网络环境(境外主机、企业出网限制等)。港股实时行情也使用腾讯作为 yfinance 之后的免 key 备用源。
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 股巨潮公告查询:类别/日期范围/标题/原文 PDF 链接 |
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 历史分红/除息日历/已实现 TTM 股息与连续年数;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` 是独立趋势温度指标:`(EMA20-EMA60)/ATR14`,ATR 使用包含跳空的真实波幅简单均值。附分数、EMA差方向 `direction`、七档研究标签、前一期信息、数据日期和价格口径;`validation_status=not_validated`,真实股票试验未支持默认温度交易映射。方向按零轴计算,“平”标签不代表零方向;默认需 60 根预热,零 ATR 或坏行情返回不可用。±0.5/±1.5/±3 的分档尚未校准,不是趋势动物公式、肥尾指标、上涨概率或自动买卖信号,也不修改原综合评分。无需个人持仓存储;[公式、边界及回测说明](skills/bull-trend/references/trend-temperature.md)。
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` | 全市场多因子筛选(可选 L2;factor_coverage 展示缺失因子、覆盖度、实际权重及 L2 effective_scores) |
236
+ | `screen_stocks` | 全市场多因子筛选(流动性使用成交额 turnover;可选 L2;factor_coverage 展示缺失因子与实际权重) |
304
237
  | `screen_risk` | 风险因子筛查 |
305
238
  | `run_backtest` | YAML 策略回测,默认收盘信号于次日开盘成交,execution 返回模型与限制 |
306
- | `detect_market_regime` | 市场状态检测(牛/熊/震荡;返回实际 as_of 和坏行警告,历史不足 60 根时 above_ma60=null) |
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
- 批量自选股分析和摘要的 `success` 表示至少获取了有效行情价格、K 线收盘价或技术评分;全部关键数据失败时计入 `failed`,部分结果仍保留。采集脚本复用返回的 K 线计算技术指标,并按股票所属市场查询大盘状态;日/韩/台市场状态暂不可用,非 A 股板块榜单也暂不可用,均会明确返回错误。
280
+ 批量分析的成功判定、信号存储与结算、风险筛查缺失值、选股与回测字段语义见 [工具行为与可靠性](docs/tool-behavior.md#自选股批量分析信号与筛选)。
347
281
 
348
- 同一次自选股分析会共享报价、日 K 线和按市场获取的大盘状态(包含可选市场复盘);风险与异动分析复用本次快照,资金流汇总和明细仍分开采集。采集任务使用共享的 6 线程 CLI 池,每支股票完成后即可接续异动分析,最终顺序保持调用方顺序。报价不跨调用保存。独立仓位/风控/筛选采集步骤并行执行。 两融历史明细按交易所/日期复用完整表,当日表和空表不缓存;CN 交易日历完整快照缓存一天。搜索按原优先级降级,单次查询的切换预算为 45 秒,综合搜索共用 90 秒预算;各请求使用剩余预算内的超时,严格总时限仍由宿主控制。同次综合搜索会跳过已确认不可用的引擎,下次独立调用重试。
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
- 这些工具不保存自选股、账户或分析历史,也不提供调度/通知。现有数据工具采集行情和财务,宿主传入本次持仓、正文或快照;[完整输入约定与解读工作流](skills/stock-analysis/references/stateless-analysis.md)供四个宿主共用。
296
+ 这些工具不保存自选股、账户或分析历史,也不提供调度/通知。输入格式、仓位预算示例与解读边界见 [工具行为与可靠性 · 无状态研究](docs/tool-behavior.md#无状态研究与风险计算)。
370
297
 
371
- 大输入经权限受限的临时 JSON 文件传给 Python,调用结束后清理,避免 Windows 命令行长度限制;CLI 也支持 stdin 和 `--input` 文件。公告正文由宿主读取:PDF/OCR 不包含在本次扩展中,只有标题或链接不能声称已读全文。
298
+ </details>
372
299
 
373
- 例如仓位预算(所有金额同币种,lot_size 由用户或交易规则确认):
300
+ 字段语义、部分失败和缺失数据的处理方式见 [工具行为与可靠性](docs/tool-behavior.md)。
374
301
 
375
- ```json
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
- ```bash
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
- 行情 JSON 保留原有数组/字典形状,添加 `source`、UTC `fetched_at` 和 `data_as_of`。采集时间不是报价时间,提供方未给时间时为 null;仅提供交易日时保留 YYYY-MM-DD,不补造具体时刻;K 线 data_as_of 是该条的日期标签,周/月线标签不是实际末次成交时间;`as_of_basis=trading_calendar` 表示交易日历推断。A 股复权口径延续 qfq/none;其他市场按来源标为 total_return/qfq/unknown,不把 unknown 当已验证复权。
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/value_data.py valuation_history 600519 --years 5
491
- python tools/stock_data.py financials 600519 --annual --periods 10
492
- python tools/value_data.py earnings_calendar --report-date 2026-09-30 --symbol 600519
493
- python tools/value_data.py shareholder_structure 600519 --report-date 2026-06-30
494
- python tools/value_data.py shareholder_structure 0700.HK
495
- python tools/value_data.py index_valuation 000300 --years 5
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
- 财报、基本信息、股票代码/名称映射及估值/股东/ETF/分红等慢变数据缓存到 `~/.stock-analysis/cache`(可通过 `STOCK_CACHE_DIR` 指定可写目录,适用于沙箱/只读用户目录),TTL 一天;板块成分/映射一周。行情报价不缓存。缓存写入失败时直接返回已获取数据;缓存文件原子替换,过期/损坏重拉,错误和显式部分失败不缓存;不以过期数据伪装最新数据。原有临时目录的粘性路由和反向成分缓存保留。 同键缓存缺失与 SEC ZIP 下载通过跨进程文件锁协调,等待最多 5 秒;普通缓存锁不可用或超时后仍可直接抓取,持久写入/ZIP 下载则返回错误,避免无界等待。有效缓存命中不要求目录可写。
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
- ## CI 真实宿主测试
424
+ </details>
559
425
 
560
- GitHub Actions 的 `e2e-host` 使用 Pi、Hermes、OpenClaw、dsh 的真实运行时执行工具调用。在仓库 **Settings → Secrets and variables → Actions** 中配置以下三项,所有 E2E 共用:
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
- `e2e-llm` 也使用这三项配置,Hermes(含报告质量评测)、Pi、OpenClaw 和 dsh 通过四个 matrix 作业并行运行,互不因失败而取消;同仓库 PR 和主分支推送会运行,fork PR 不读取 API key。`e2e-host` 缺少任一项时会失败。URL 和 model 同时存在于 Variable 与 Secret 时,优先使用 Secret。
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 # 注册 72 个工具 + 21 个 skill
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 # 工具 JSON Schema 定义
580
- │ └── tools.py # 72 个 handler → subprocess 调 CLI
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 + registerTool ×72
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) + defineTool ×72
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 或 hermes/tools.py 或 openclaw/index.ts 或 dsh/index.ts → python3 tools/xxx.py → JSON
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
- - [daily_stock_analysis](https://github.com/ZhuLinsen/daily_stock_analysis) — A 股每日分析工具,本项目的综合分析流程参考了其设计思路
645
- - [akshare](https://github.com/akfamily/akshare) — A 股数据源
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
- 如果使用 virtualenv / conda,确保 Agent 启动时能访问到对应的 Python 环境。
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
- 命令预算集中于 `tools/cli_budgets.json`:通用采集默认 120 秒、市场快照 240 秒、选股 top 须为正整数,预算按候选数及 6 个 worker 的批次计算(默认 20 个候选为 1830 秒)、13F 300 秒;技术分析、市场状态、回测和风险筛查按实际嵌套调用另留预算;四个宿主额外留 30 秒接收 CLI 输出。综合采集保留安全 JSON 错误及 error_code(timeout/empty_output/invalid_json/process_failed/tool_error),不会把失败当成有效空数据。
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
- 真实模型评测同时要求结构化证据检查与独立上下文的结论审稿通过:审稿检查正文事实、限制说明是否诚实,以及是否过度外推。未运行审稿、结果缺失或模糊都不能算通过;报告自行声明通过不被采信。另有人工核对的正确报告及两类反例用于验证审稿器(正确引用但正文捏造现价、3笔交易却保证长期胜率)。空回答也失败。离线渲染和规则检查不代表真实模型通过,也不证明策略未来有效。信号建议可沿用 source 标识策略版本,按来源复盘胜率、平均收益和样本量;未扣成本、未匹配基准的观察记录不能当作策略回测。
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
- 信号结算仅在价格口径可核实时进行:原始价格可直接比较;自动记录的默认 `record_date` 与 `price_date` 均按标的市场时区确定(显式 `date` 不变),并保存原始 `price_as_of`;`price_date` 晚于 `record_date` 时拒绝记录与结算;多头 target 必须高于 entry、stop 必须低于 entry,空头相反,否则拒绝记录。开盘先触 stop 按 open 结算,先触 target 按 target 保守结算,日内顺序未知的双触发仍 stop 优先;无止损的旧 HLC 记录可继续用 high/low/close 判定目标和到期,但若提供 open 也必须是正有限数值,有止损但缺 open 则拒绝结算。重复日期返回 skipped_no_data,复权乘除使用 Decimal。复权日线需该报价日的 adjustment_factor(复权价/原始价),当前日线 Tushare、Alpha Vantage 可提供。缺失系数或口径未知时返回 skipped_price_basis,保持未结算,不猜测除权比例;记录日无 K 线时仅在前后因子一致(或已有明确报价日)时使用最近锚点,旧信号缺少报价时点且记录日因子变化时也保持未结算。换算后的 exit_price 是记录时价格单位的等价值,实际市场价可不同,evaluation_price_basis 保留依据。evaluate_signals 的 CLI 预算为 300 秒,内部提前结束采集并保存已完成结果,complete/deferred/warnings 指示需要重试的记录;预算耗尽后调整未结算记录的处理顺序,下轮优先处理尚未尝试的记录,避免慢请求长期阻塞后续信号。
583
+ `e2e-llm` 也使用这三项配置,Hermes(含报告质量评测)、Pi、OpenClaw 和 dsh 通过四个 matrix 作业并行运行,互不因失败而取消;同仓库 PR 和主分支推送会运行,fork PR 不读取 API key。`e2e-host` 缺少任一项时会失败。URL 和 model 同时存在于 Variable 与 Secret 时,优先使用 Secret。
742
584
 
743
- 市场复盘数据不足时温度/姿态为 null,信号 unknown,data_quality.limitations 说明限制。自选股异动采集失败时 anomaly_status=unavailable、anomaly_count=null,保留警告并计入 summary.partial,不能当成无异常。
585
+ </details>
744
586
 
745
- L1 与 L2 综合分均在排序前按可用因子重新归一化;缺失或非有限因子不作零分处理,因子组内部也仅平均有效输入。factor_coverage.ratio 保留原始权重覆盖率,effective_weights 是实际归一化后的权重,高分仍需结合覆盖率判断。估值比较需同时读取 `pe_basis`;有限非正 PE/PB 的价值子分为 0,不能因数值更低而获得最高价值分。
587
+ ## 致谢
746
588
 
747
- L2 的 `vol20` 只使用恰好 20 个有效日收益,`factor_coverage.vol20_samples` 记录实际样本数,非正/非有限收盘价先剔除,空输入为 0;质量因子按 `report_date` 分组归一,避免年度累计与单季累计直接比较。资金流 5/10/20 日窗口不足返回 null,不按 0 或完整窗口处理。HK 快照统一带 `.HK`,US 快照移除东财交易所后缀并把类别股点号转为 Yahoo 连字符。主板 ST/*ST 按 5% 识别涨跌停,其他板块比例不变。
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