Skip to content

Commit 7f09375

Browse files
WeaxsWeaxs
committed
docs: update env vars, add Wisburg MCP setup, fix tool counts
- Expand environment variable docs from 5 to 12 (grouped by function) - Add Wisburg MCP Server integration instructions - Fix tool count: 31 tools, 20 skills - Add missing get_trending_sentiment to pi/index.ts and plugin.yaml - Remove duplicate get_market_review in pi/index.ts
1 parent 5c34f45 commit 7f09375

6 files changed

Lines changed: 300 additions & 76 deletions

File tree

‎docs/hermes-integration.en.md‎

Lines changed: 67 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ class MockCtx:
6464

6565
ctx = MockCtx()
6666
register(ctx)
67-
print(f"Tools: {len(ctx.tools)}") # Should print 30
67+
print(f"Tools: {len(ctx.tools)}") # Should print 31
6868
print(f"Skills: {len(ctx.skills)}") # Should print 20
6969
```
7070

@@ -82,7 +82,7 @@ PROJECT_ROOT = Path(__file__).resolve().parent.parent
8282
SKILLS_DIR = PROJECT_ROOT / "skills"
8383

8484
def register(ctx):
85-
# Register 30 tools
85+
# Register 31 tools
8686
for schema in schemas.TOOL_SCHEMAS:
8787
name = schema["name"]
8888
handler = _HANDLER_MAP[name]
@@ -102,7 +102,7 @@ def register(ctx):
102102

103103
### Tool Definitions (Schema)
104104

105-
`hermes/schemas.py` defines the JSON Schema for all 30 tools, each containing `name`, `description`, and `parameters`:
105+
`hermes/schemas.py` defines the JSON Schema for all 31 tools, each containing `name`, `description`, and `parameters`:
106106

107107
```python
108108
TOOL_SCHEMAS = [
@@ -119,13 +119,13 @@ TOOL_SCHEMAS = [
119119
"required": ["symbol"],
120120
},
121121
},
122-
# ... 29 more
122+
# ... 30 more
123123
]
124124
```
125125

126126
### Tool Handlers
127127

128-
`hermes/tools.py` implements 30 handler functions, each calling the corresponding Python CLI script via `subprocess`:
128+
`hermes/tools.py` implements 31 handler functions, each calling the corresponding Python CLI script via `subprocess`:
129129

130130
```python
131131
import subprocess
@@ -158,7 +158,7 @@ def get_kline(args, **kwargs):
158158
cmd += ["--count", str(args["count"])]
159159
return _run("stock_data.py", cmd)
160160

161-
# ... 29 more handlers
161+
# ... 30 more handlers
162162
```
163163

164164
### Plugin Manifest
@@ -172,7 +172,7 @@ description: "Stock analysis, screening, and strategy backtesting across A/HK/US
172172
provides_tools:
173173
- get_kline
174174
- get_quote
175-
# ... 30 tools total
175+
# ... 31 tools total
176176
requires_env:
177177
- name: TAVILY_API_KEY
178178
description: "Tavily search API key (optional)"
@@ -188,15 +188,65 @@ The plugin locates the project root via `Path(__file__).resolve().parent.parent`
188188

189189
## Environment Variables
190190

191-
The following environment variables are optional (configure at least one search engine to enable news search):
191+
Environment variables are grouped by function — configure as needed:
192192

193-
| Variable | Purpose |
194-
|----------|---------|
195-
| `TAVILY_API_KEY` | Tavily search |
196-
| `BRAVE_API_KEY` | Brave search |
197-
| `SERPAPI_KEY` | SerpAPI |
198-
| `BOCHA_API_KEY` | Bocha AI search |
199-
| `SENTIMENT_API_KEY` | Social media sentiment analysis |
193+
### News & Search (configure at least one)
194+
195+
| Variable | Purpose | URL |
196+
|----------|---------|-----|
197+
| `TAVILY_API_KEY` | Tavily search | https://tavily.com |
198+
| `BRAVE_API_KEY` | Brave search | https://brave.com/search/api/ |
199+
| `SERPAPI_KEY` | SerpAPI | https://serpapi.com |
200+
| `BOCHA_API_KEY` | Bocha AI search | — |
201+
202+
### Social Sentiment
203+
204+
| Variable | Purpose | Notes |
205+
|----------|---------|-------|
206+
| `SENTIMENT_API_KEY` | Social sentiment API auth | Eastmoney + Xueqiu sentiment |
207+
| `SENTIMENT_API_URL` | Sentiment API endpoint | Default: `https://api.adanos.org` |
208+
209+
### US / HK Market Data Sources
210+
211+
| Variable | Purpose | Notes |
212+
|----------|---------|-------|
213+
| `FINNHUB_API_KEY` | Finnhub (US quotes, financials) | https://finnhub.io |
214+
| `ALPHAVANTAGE_API_KEY` | Alpha Vantage (US klines) | https://www.alphavantage.co |
215+
| `LONGBRIDGE_APP_KEY` | Longbridge (HK quotes) | https://open.longportapp.com |
216+
| `LONGBRIDGE_APP_SECRET` | Longbridge App Secret | Same as above |
217+
| `LONGBRIDGE_ACCESS_TOKEN` | Longbridge Access Token | Same as above |
218+
219+
### A-share Enhanced Data Source (Optional)
220+
221+
| Variable | Purpose | Notes |
222+
|----------|---------|-------|
223+
| `TUSHARE_TOKEN` | Tushare (A-share fallback source) | https://tushare.pro |
224+
225+
> Note: A-share basic data is fetched via akshare (free, no key required). Tushare is only used as a fallback/enhanced source.
226+
227+
### Wisburg Research Data
228+
229+
Wisburg is integrated via **MCP Server**, not environment variables. Add the Wisburg MCP service to your Hermes Agent MCP configuration:
230+
231+
```json
232+
{
233+
"mcpServers": {
234+
"wisburg-mcp-server": {
235+
"command": "npx",
236+
"args": ["-y", "@anthropic/wisburg-mcp-server"],
237+
"env": {
238+
"WISBURG_API_KEY": "your-wisburg-key"
239+
}
240+
}
241+
}
242+
}
243+
```
244+
245+
Once configured, the `wisburg-research` Skill automatically calls Wisburg MCP tools (prefixed with `mcp__wisburg-mcp-server__`), providing:
246+
- Institutional research reports (Goldman Sachs, Morgan Stanley, CICC, etc.)
247+
- Earnings call transcripts, financial filings (A/HK/US markets)
248+
- Research feed, market daily digest
249+
- A-share investor Q&A (semantic search)
200250

201251
Configure in Hermes Agent:
202252

@@ -269,8 +319,8 @@ stock-analysis-plugin/
269319
├── hermes/
270320
│ ├── __init__.py # register(ctx) entry point
271321
│ ├── plugin.yaml # Plugin manifest
272-
│ ├── schemas.py # JSON Schema definitions for 30 tools
273-
│ └── tools.py # 30 handlers calling CLI via subprocess
322+
│ ├── schemas.py # JSON Schema definitions for 31 tools
323+
│ └── tools.py # 31 handlers calling CLI via subprocess
274324
├── tools/ # Shared Python CLI tools
275325
├── skills/ # Shared SKILL.md files
276326
└── .venv/ # Python virtual environment (optional)

‎docs/hermes-integration.md‎

Lines changed: 67 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ class MockCtx:
6464

6565
ctx = MockCtx()
6666
register(ctx)
67-
print(f"Tools: {len(ctx.tools)}") # 应输出 30
67+
print(f"Tools: {len(ctx.tools)}") # 应输出 31
6868
print(f"Skills: {len(ctx.skills)}") # 应输出 20
6969
```
7070

@@ -82,7 +82,7 @@ PROJECT_ROOT = Path(__file__).resolve().parent.parent
8282
SKILLS_DIR = PROJECT_ROOT / "skills"
8383

8484
def register(ctx):
85-
# 注册 30 个工具
85+
# 注册 31 个工具
8686
for schema in schemas.TOOL_SCHEMAS:
8787
name = schema["name"]
8888
handler = _HANDLER_MAP[name]
@@ -102,7 +102,7 @@ def register(ctx):
102102

103103
### 工具定义（Schema）
104104

105-
`hermes/schemas.py` 定义了 30 个工具的 JSON Schema，每个工具包含 `name`、`description` 和 `parameters`：
105+
`hermes/schemas.py` 定义了 31 个工具的 JSON Schema，每个工具包含 `name`、`description` 和 `parameters`：
106106

107107
```python
108108
TOOL_SCHEMAS = [
@@ -119,13 +119,13 @@ TOOL_SCHEMAS = [
119119
"required": ["symbol"],
120120
},
121121
},
122-
# ... 其余 29 个
122+
# ... 其余 30 个
123123
]
124124
```
125125

126126
### 工具实现（Handler）
127127

128-
`hermes/tools.py` 实现了 30 个 handler 函数，每个函数通过 `subprocess` 调用对应的 Python CLI 脚本：
128+
`hermes/tools.py` 实现了 31 个 handler 函数，每个函数通过 `subprocess` 调用对应的 Python CLI 脚本：
129129

130130
```python
131131
import subprocess
@@ -158,7 +158,7 @@ def get_kline(args, **kwargs):
158158
cmd += ["--count", str(args["count"])]
159159
return _run("stock_data.py", cmd)
160160

161-
# ... 其余 29 个 handler
161+
# ... 其余 30 个 handler
162162
```
163163

164164
### Plugin Manifest
@@ -172,7 +172,7 @@ description: "Stock analysis, screening, and strategy backtesting across A/HK/US
172172
provides_tools:
173173
- get_kline
174174
- get_quote
175-
# ... 30 个工具
175+
# ... 31 个工具
176176
requires_env:
177177
- name: TAVILY_API_KEY
178178
description: "Tavily search API key (optional)"
@@ -188,15 +188,65 @@ requires_env:
188188

189189
## 环境变量配置
190190

191-
以下环境变量可选配置（配置任一搜索引擎即可启用新闻搜索功能）：
191+
以下环境变量按功能分组，根据需要配置：
192192

193-
| 环境变量 | 用途 |
194-
|---------|------|
195-
| `TAVILY_API_KEY` | Tavily 搜索 |
196-
| `BRAVE_API_KEY` | Brave 搜索 |
197-
| `SERPAPI_KEY` | SerpAPI |
198-
| `BOCHA_API_KEY` | Bocha AI 搜索 |
199-
| `SENTIMENT_API_KEY` | 社交媒体情绪分析 |
193+
### 新闻 & 搜索（配置任一即可）
194+
195+
| 环境变量 | 用途 | 获取地址 |
196+
|---------|------|---------|
197+
| `TAVILY_API_KEY` | Tavily 搜索 | https://tavily.com |
198+
| `BRAVE_API_KEY` | Brave 搜索 | https://brave.com/search/api/ |
199+
| `SERPAPI_KEY` | SerpAPI | https://serpapi.com |
200+
| `BOCHA_API_KEY` | Bocha AI 搜索 | — |
201+
202+
### 社交情绪
203+
204+
| 环境变量 | 用途 | 说明 |
205+
|---------|------|------|
206+
| `SENTIMENT_API_KEY` | 社交情绪分析 API 认证 | 东财股吧 + 雪球情绪 |
207+
| `SENTIMENT_API_URL` | 情绪 API 地址 | 默认 `https://api.adanos.org` |
208+
209+
### 美股 / 港股数据源
210+
211+
| 环境变量 | 用途 | 说明 |
212+
|---------|------|------|
213+
| `FINNHUB_API_KEY` | Finnhub（美股行情、财报） | https://finnhub.io |
214+
| `ALPHAVANTAGE_API_KEY` | Alpha Vantage（美股K线） | https://www.alphavantage.co |
215+
| `LONGBRIDGE_APP_KEY` | 长桥（港股行情） | https://open.longportapp.com |
216+
| `LONGBRIDGE_APP_SECRET` | 长桥 App Secret | 同上 |
217+
| `LONGBRIDGE_ACCESS_TOKEN` | 长桥 Access Token | 同上 |
218+
219+
### A 股增强数据源（可选）
220+
221+
| 环境变量 | 用途 | 说明 |
222+
|---------|------|------|
223+
| `TUSHARE_TOKEN` | Tushare（A股历史数据备用源） | https://tushare.pro |
224+
225+
> 注意：A 股基础数据通过 akshare 免费获取，无需配置。Tushare 仅作为备用/增强数据源。
226+
227+
### 智堡（Wisburg）投研数据
228+
229+
智堡通过 **MCP Server** 接入，不是环境变量。需要在 Hermes Agent 的 MCP 配置中添加智堡服务：
230+
231+
```json
232+
{
233+
"mcpServers": {
234+
"wisburg-mcp-server": {
235+
"command": "npx",
236+
"args": ["-y", "@anthropic/wisburg-mcp-server"],
237+
"env": {
238+
"WISBURG_API_KEY": "your-wisburg-key"
239+
}
240+
}
241+
}
242+
}
243+
```
244+
245+
配置完成后，插件的 `wisburg-research` Skill 会自动调用智堡 MCP 工具（以 `mcp__wisburg-mcp-server__` 前缀），提供：
246+
- 投行/券商研报、个股研究报告
247+
- 电话会纪要、财报公告（A/港/美三市场）
248+
- 投研资讯流、市场日报
249+
- A股投资者问答（语义搜索）
200250

201251
在 Hermes Agent 中配置环境变量：
202252

@@ -269,8 +319,8 @@ stock-analysis-plugin/
269319
├── hermes/
270320
│ ├── __init__.py # register(ctx) 入口
271321
│ ├── plugin.yaml # 插件元数据清单
272-
│ ├── schemas.py # 30 个工具的 JSON Schema 定义
273-
│ └── tools.py # 30 个 handler，subprocess 调 CLI
322+
│ ├── schemas.py # 31 个工具的 JSON Schema 定义
323+
│ └── tools.py # 31 个 handler，subprocess 调 CLI
274324
├── tools/ # 共享 Python CLI 工具
275325
├── skills/ # 共享 SKILL.md
276326
└── .venv/ # Python 虚拟环境（可选）

‎docs/pi-integration.en.md‎

Lines changed: 60 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ Pi Agent loads TypeScript extensions using [jiti](https://github.com/nicolo-riba
7272

7373
### Tool Registration
7474

75-
`pi/index.ts` exports a function that receives the `ExtensionAPI` object and registers 30 tools via `pi.registerTool()`:
75+
`pi/index.ts` exports a function that receives the `ExtensionAPI` object and registers 31 tools via `pi.registerTool()`:
7676

7777
```typescript
7878
import type { ExtensionAPI } from "pi-agent";
@@ -91,7 +91,7 @@ export default (pi: ExtensionAPI) => {
9191
return result.stdout;
9292
},
9393
});
94-
// ... 29 more tools
94+
// ... 30 more tools
9595
};
9696
```
9797

@@ -135,15 +135,65 @@ const python = existsSync(venvPython) ? venvPython : "python3";
135135

136136
## Environment Variables
137137

138-
The following environment variables are optional (configure at least one search engine to enable news search):
138+
Environment variables are grouped by function — configure as needed:
139139

140-
| Variable | Purpose |
141-
|----------|---------|
142-
| `TAVILY_API_KEY` | Tavily search |
143-
| `BRAVE_API_KEY` | Brave search |
144-
| `SERPAPI_KEY` | SerpAPI |
145-
| `BOCHA_API_KEY` | Bocha AI search |
146-
| `SENTIMENT_API_KEY` | Social media sentiment analysis |
140+
### News & Search (configure at least one)
141+
142+
| Variable | Purpose | URL |
143+
|----------|---------|-----|
144+
| `TAVILY_API_KEY` | Tavily search | https://tavily.com |
145+
| `BRAVE_API_KEY` | Brave search | https://brave.com/search/api/ |
146+
| `SERPAPI_KEY` | SerpAPI | https://serpapi.com |
147+
| `BOCHA_API_KEY` | Bocha AI search | — |
148+
149+
### Social Sentiment
150+
151+
| Variable | Purpose | Notes |
152+
|----------|---------|-------|
153+
| `SENTIMENT_API_KEY` | Social sentiment API auth | Eastmoney + Xueqiu sentiment |
154+
| `SENTIMENT_API_URL` | Sentiment API endpoint | Default: `https://api.adanos.org` |
155+
156+
### US / HK Market Data Sources
157+
158+
| Variable | Purpose | Notes |
159+
|----------|---------|-------|
160+
| `FINNHUB_API_KEY` | Finnhub (US quotes, financials) | https://finnhub.io |
161+
| `ALPHAVANTAGE_API_KEY` | Alpha Vantage (US klines) | https://www.alphavantage.co |
162+
| `LONGBRIDGE_APP_KEY` | Longbridge (HK quotes) | https://open.longportapp.com |
163+
| `LONGBRIDGE_APP_SECRET` | Longbridge App Secret | Same as above |
164+
| `LONGBRIDGE_ACCESS_TOKEN` | Longbridge Access Token | Same as above |
165+
166+
### A-share Enhanced Data Source (Optional)
167+
168+
| Variable | Purpose | Notes |
169+
|----------|---------|-------|
170+
| `TUSHARE_TOKEN` | Tushare (A-share fallback source) | https://tushare.pro |
171+
172+
> Note: A-share basic data is fetched via akshare (free, no key required). Tushare is only used as a fallback/enhanced source.
173+
174+
### Wisburg Research Data
175+
176+
Wisburg is integrated via **MCP Server**, not environment variables. Add the Wisburg MCP service to your Pi Agent MCP configuration:
177+
178+
```json
179+
{
180+
"mcpServers": {
181+
"wisburg-mcp-server": {
182+
"command": "npx",
183+
"args": ["-y", "@anthropic/wisburg-mcp-server"],
184+
"env": {
185+
"WISBURG_API_KEY": "your-wisburg-key"
186+
}
187+
}
188+
}
189+
}
190+
```
191+
192+
Once configured, the `wisburg-research` Skill automatically calls Wisburg MCP tools (prefixed with `mcp__wisburg-mcp-server__`), providing:
193+
- Institutional research reports (Goldman Sachs, Morgan Stanley, CICC, etc.)
194+
- Earnings call transcripts, financial filings (A/HK/US markets)
195+
- Research feed, market daily digest
196+
- A-share investor Q&A (semantic search)
147197

148198
Set them before starting Pi Agent:
149199

0 commit comments

Comments
 (0)