Skill: pandaai-tech/panda-data-skill (version 4.0.0)

--- name: panda-data-skill version: 3.0.0 description: PandaAI 金融数据 API 的 LLM Tool 封装多个数据查询方法，支持A股行情、A股基本面，期货，指数等 author: PandaAI homepage: https://pypi.org/project/panda-data-tools/ user-invocable: true metadata: categories: - financial - market-data - llm-tools --- # Panda Data Skill PandaAI 金融数据 API 的 OpenClaw 技能封装，将 35 个数据查询方法封装为符合 LLM function calling 规范的 tools，支持行情数据、市场参考、财务因子、交易工具、期货等全品类查询。 ## Quick Start ```python from panda_tools.credential import CredentialManager from panda_tools.registry import ToolRegistry CredentialManager.init_from_env() registry = ToolRegistry() tools = registry.get_all_tools() result = registry.call_tool("get_market_data", start_date="20250101", end_date="20250110", symbol="000001.SZ") ``` ## Key Notes - 需配置环境变量 `PANDA_DATA_USERNAME` 和 `PANDA_DATA_PASSWORD` 作为 API 凭证 - 需安装 PandaData SDK：`pip install panda_data` - 需安装 PandaDataSkill SDK：`pip install panda-data-tools` - 完整安装步骤（ClawHub、pip、凭证）见同目录 **[INSTALL_GUIDE.md](INSTALL_GUIDE.md)** - 日期格式统一为 YYYYMMDD（如 20250101） - 股票代码格式：A股 `000001.SZ`、指数 `000300.SH`、期货 `A2501.DCE` ## Rules 1. 调用任何数据接口前必须先执行 `CredentialManager.init_from_env()` 初始化凭证 2. 日期参数使用 YYYYMMDD 格式，不要使用 YYYY-MM-DD 3. 股票/指数/期货代码需带交易所后缀（.SZ/.SH/.DCE 等） 4. 查询日期范围注意 API 限制（如日线不超过 5 年） ## 代码示例 ```python # 获取日线行情 registry.call_tool("get_market_data", start_date="20250101", end_date="20250110", symbol="000001.SZ") # 获取交易日历 registry.call_tool("get_trade_cal", start_date="20250101", end_date="20250131") # 获取最新交易日 registry.call_tool("get_last_trade_date") ``` ## API 方法列表 完整参数说明见 [api_reference.md](api_reference.md)。 #### 1. `get_market_data(start_date, end_date, symbol, ...)` — 获取日线行情数据 获取股票、指数、期货的日线行情，返回开高低收、成交量等字段。 #### 2. `get_market_min_data(start_date, end_date, symbol, ...)` — 获取分钟级行情数据 获取分钟级行情，支持 1m/5m/15m/60m 频率。 #### 3. `get_stock_detail(symbol, fields, ...)` — 获取股票基本信息 获取 A 股、港股、美股的股票基本信息。 #### 4. `get_index_detail(symbol, fields, ...)` — 获取指数基本信息 获取指数代码、名称、上市日期等。 #### 5. `get_concept_list(concept, start_date, end_date)` — 获取概念列表 获取概念板块列表及纳入日期。 #### 6. `get_concept_constituents(concept, concept_stock, ...)` — 获取概念成分股 获取指定概念的成分股列表。 #### 7. `get_industry_detail(fields, level)` — 获取行业基本信息 获取申万行业分类的行业列表。 #### 8. `get_industry_constituents(industry_code, stock_symbol, ...)` — 获取行业成分股 获取指定行业的成分股数据。 #### 9. `get_stock_industry(stock_symbol, level)` — 获取股票所属行业 查询指定股票所属的行业信息。 #### 10. `get_index_indicator(symbol, start_date, end_date, ...)` — 获取指数估值指标 获取指数市净率、市盈率等估值指标。 #### 11. `get_index_weights(index_symbol, stock_symbol, start_date, end_date, ...)` — 获取指数权重 获取指数成分股权重信息。 #### 12. `get_lhb_list(symbol, type, start_date, end_date, ...)` — 获取龙虎榜数据 获取股票龙虎榜上榜数据。 #### 13. `get_lhb_detail(symbol, type, start_date, end_date, ...)` — 获取龙虎榜明细 获取龙虎榜买卖明细及营业部信息。 #### 14. `get_repurchase(symbol, start_date, end_date, ...)` — 获取回购数据 获取上市公司回购数据。 #### 15. `get_margin(symbol, start_date, end_date, ...)` — 获取融资融券信息 获取融资买入、融券卖出等两融数据。 #### 16. `get_hsgt_hold(symbol, start_date, end_date, ...)` — 获取沪深股通持股 获取北向资金持股信息。 #### 17. `get_investor_activity(symbol, start_date, end_date, ...)` — 获取投资者关系活动 获取 A 股投资者关系活动记录。 #### 18. `get_restricted_list(symbol, start_date, end_date, ...)` — 获取限售解禁明细 获取股票限售解禁数据。 #### 19. `get_holder_count(symbol, start_date, end_date, ...)` — 获取股东数量 获取股东户数及户均持股等。 #### 20. `get_top_holders(symbol, start_date, end_date, ...)` — 获取股东信息 获取十大股东、十大流通股东等。 #### 21. `get_block_trade(symbol, start_date, end_date, ...)` — 获取大宗交易 获取 A 股大宗交易信息。 #### 22. `get_share_float(symbol, start_date, end_date, ...)` — 获取股本数据 获取流通股本、总股本等。 #### 23. `get_fina_forecast(symbol, fields, info_date, end_quarter)` — 获取业绩预告 获取业绩预告数据。 #### 24. `get_fina_performance(symbol, fields, info_date, end_quarter)` — 获取财务快报 获取财务快报数据。 #### 25. `get_fina_reports(symbol, start_date, end_date, start_quarter, end_quarter, ...)` — 获取财务报告 获取财务季度报告，含四大报表字段。 #### 26. `get_factor(start_date, end_date, factors, symbol, ...)` — 获取回测因子 获取股票或期货的回测因子数据。 #### 27. `get_adj_factor(symbol, start_date, end_date, ...)` — 获取复权因子 获取前复权、后复权因子。 #### 28. `get_trade_cal(start_date, end_date, exchange, ...)` — 获取交易日历 获取交易日历，支持 SH/HK/US。 #### 29. `get_prev_trade_date(date, exchange, n)` — 获取前第 n 个交易日 返回指定日期前第 n 个交易日的日期字符串。 #### 30. `get_last_trade_date(exchange)` — 获取最新交易日 返回最新交易日日期字符串。 #### 31. `get_stock_status_change(symbol, start_date, end_date, ...)` — 获取特殊处理数据 获取 ST、退市等状态变更数据。 #### 32. `get_trade_list(date)` — 获取在售股票列表 获取指定日期的可交易股票列表。 #### 33. `get_future_detail(symbol, fields, is_trading)` — 获取期货基本信息 获取期货合约基本信息。 #### 34. `get_future_market_post(start_date, end_date, symbol, ...)` — 获取期货后复权数据 获取期货后复权行情。 #### 35. `get_future_dominant(start_date, end_date, underlying_symbol)` — 获取期货主力合约 获取每日主力合约代码。 #### 38. `get_hk_daily(symbol, start_date, end_date, fields)` — 获取港股日线 获取港股日线行情数据。 #### 39. `get_us_daily(symbol, start_date, end_date, fields)` — 获取美股日线 获取美股日线行情数据。 #### 40. `get_stock_cash_dividend(symbol, start_date, end_date, market, fields)` — 获取现金分红 获取股票现金分红公告与金额信息。 #### 41. `get_stock_dividend_info(symbol, start_date, end_date, market, fields)` — 获取分红信息 获取股票分红方案及实施信息。 #### 42. `get_stock_split_info(symbol, start_date, end_date, market, fields)` — 获取拆合股信息 获取送股、转增、拆合股相关信息。 #### 43. `get_stock_dividend_amount(symbol, start_date, end_date, market, fields)` — 获取分红金额 获取股票累计分红金额与分红比例信息。 #### 44. `get_stock_private_placement(symbol, start_date, end_date, market, fields)` — 获取定向增发 获取股票定向增发相关信息。 #### 45. `get_stock_allotment(symbol, start_date, end_date, market, fields)` — 获取配股信息 获取股票配股方案与执行信息。 #### 46. `get_audit_opinion(symbol, start_quarter, end_quarter, market, fields)` — 获取审计意见 获取审计意见与审计机构信息。 #### 47. `get_future_netposi_rank(underlying_symbol, start_date, end_date, max_rank, fields, type)` — 获取净持仓排名 获取期货净持仓排名统计。 #### 48. `get_future_symbol_posi_rank(start_date, end_date, symbol, position_type, broker_name, rank_max, fields)` — 获取合约持仓排名 获取合约维度席位持仓排名。 #### 49. `get_future_variety_posi_rank(start_date, end_date, symbol, position_type, broker_name, rank_max, fields)` — 获取品种持仓排名 获取品种维度席位持仓排名。 #### 50. `get_future_contract_daily_indicators(start_date, end_date, symbol, fields)` — 获取合约日度指标 获取期货合约日度指标数据。 #### 51. `get_broker_variety_profit(start_date, end_date, symbol, fields, broker)` — 获取席位品种盈利 获取席位在品种维度的盈利统计。 #### 52. `get_broker_grade(grade)` — 获取席位评级 获取期货席位评级信息。 #### 53. `get_broker_net_margin(underlying_symbol, start_date, end_date, fields, broker)` — 获取净保证金 获取席位净保证金数据。 #### 54. `get_broker_net_margin_change(underlying_symbol, start_date, end_date, fields, broker)` — 获取净保证金变化 获取席位净保证金变动数据。 #### 55. `get_broker_total_margin(underlying_symbol, start_date, end_date, fields, broker)` — 获取总保证金 获取席位总保证金数据。 #### 56. `get_future_net_flow(start_date, end_date, symbol, fields, broker_name, position_type)` — 获取净资金流 获取期货净资金流向数据。 #### 57. `get_future_basis(underlying_symbol, start_date, end_date, fields)` — 获取期货基差 获取期货基差统计数据。 #### 58. `get_future_wr(underlying_symbol, start_date, end_date, fields)` — 获取仓单比率 获取期货仓单比率数据。 #### 59. `get_future_ls_ratio(symbol, start_date, end_date)` — 获取多空比 获取期货多空比数据。 #### 60. `get_future_net_cap_change(symbol, start_date, end_date, broker)` — 获取净资金变化 获取期货净资金变化数据。 #### 61. `get_future_contract_rank(symbol, underlying_symbol, start_date, end_date, type, max_rank, rank_type)` — 获取合约排名 获取期货合约席位排名数据。

path: CHANGELOG.md
content: # Changelog

本文件记录 Panda Data Skill 的所有版本变更。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

## [2.0.0] - 2025-07-18

### Added

- 与 panda-data-tools v2.0.0 对齐
- 支持 DuckDB 本地数据缓存
- 支持数据导出（CSV、Excel、DuckDB）
- 完善 SKILL.md 结构，包含全部 35 个 API 方法说明

## [1.0.0] - 2025-07-01

### Added

- 初始发布
- 35 个金融数据 API 的 LLM Tool 封装
- 支持行情、市场参考、财务、交易、期货五大分类


path: INSTALL_GUIDE.md
content: # Panda Data Skill（panda_data）安装指南

本文面向 **OpenClaw** 及需要在编程环境中使用 **PandaAI 金融数据** 的用户，结构与常见 Skills 安装说明（可参考 [Tushare Skills 安装指南](https://tushare.pro/document/1)）一致，便于对照操作。

---

## Skills 是什么

在 OpenClaw 生态中，**Skills** 是一种能力扩展方式，可以理解为给 AI 助手增加的「领域扩展包」：

- **专注领域**：例如本 Skill 面向股票、指数、期货、财务与因子等金融数据查询。
- **内置约定**：`SKILL.md` 中说明了调用规则、日期与代码格式、必须先完成认证等。
- **与运行时代码分离**：Skill 压缩包主要包含说明文档与辅助脚本；**Python 可执行库需单独通过 pip 安装**（见下文步骤 2）。

为便于大模型稳定调用 PandaAI 接口，**请同时完成：安装 Skill → 安装 SDK 与工具包 → 配置账号凭证**。

---

## 安装与准备

### 步骤 1：安装 Panda Data Skill

#### 在 OpenClaw 里通过 ClawHub 安装

若已在 [ClawHub](https://clawhub.com)（或你环境提供的等价命令）发布/收录本技能，一般形式为：

```bash
# 使用 clawhub 安装（技能在 ClawHub 上的名称为 panda-data-skill）
clawhub install panda-data-skill

# 升级
clawhub update panda-data-skill
```

也可在 OpenClaw 对话中让助手安装，例如提示：**请安装最新版 Panda Data skill，名称为 panda-data-skill**（若平台展示名称略有差异，以 ClawHub 为准）。

若线上安装失败（如限流、网络问题），可使用 **离线 zip**：将技能包 zip 下载到本地后，在 OpenClaw 中按平台说明导入该 zip，或通过对话提示「安装某目录下的 xxx.zip Skills」。

> **说明**：ClawHub 下载的 skill **通常只含** `SKILL.md`、`README.md`、`api_reference.md`、`scripts/` 等，**不包含** `panda_tools` 源码，步骤 2 必须执行。

---

### 步骤 2：安装 Python 依赖（panda_data + panda-data-tools）

大模型或脚本实际调数据时，需要：

| 组件 | 作用                                                                                                           |
|------|--------------------------------------------------------------------------------------------------------------|
| **panda_data** | PandaAI 官方 Python SDK（一般 `pip install panda_data`                                                            |
| **panda-data-tools** | 本项目的 PyPI 包名，`pip install panda-data-tools`提供 `panda_tools` 模块（`ToolRegistry`、`CredentialManager`、各 tool 封装） |

**2.1 安装 PandaAI SDK（panda_data）**

```bash
pip install panda_data
```

**2.2 安装 panda-data-tools**

若已在 [PyPI](https://pypi.org/) 发布：

```bash
pip install panda-data-tools
```

建议使用 **Python 3.12+**，并在虚拟环境中操作。

---

### 步骤 3：获取 PandaAI 账号凭证
官网账号注册：https://www.pandaai.online

PandaAI 数据接口使用 **86手机号+ 密码** 登录（该账号密码与PandaAI官网账号密码相同）

- 可用的 **用户名**
- 对应的 **密码**

请妥善保管，不要提交到公开仓库或聊天记录的公开频道。

---

### 步骤 4：配置凭证

**方式 A：环境变量（推荐脚本/服务）**

```bash
export PANDA_DATA_USERNAME="86+你的手机号"
export PANDA_DATA_PASSWORD="你的密码"
```

**方式 B：`.env` 文件（与 python-dotenv 配合）**

在运行时的**当前工作目录**或其**上级目录**放置 `.env`（`panda-data-tools` 会向上查找并加载，且默认**不覆盖**已在 shell 中设置的变量）：

```env
PANDA_DATA_USERNAME=86+你的手机号
PANDA_DATA_PASSWORD=你的密码
```

**方式 C：在 OpenClaw 里**

将用户名与密码（或说明已写入环境变量 / `.env`）告知助手，请其在**安全前提下**协助写入环境或配置文件，并提醒勿泄露。

**方式 D：代码中显式传入**

```python
from panda_tools.credential import CredentialManager

CredentialManager.init_with_credentials("86+手机号", "密码")
```

---

### 步骤 5：验证是否可用

```python
from panda_tools.credential import CredentialManager
from panda_tools.registry import ToolRegistry

CredentialManager.init_from_env()
registry = ToolRegistry()
result = registry.call_tool(
    "get_market_data",
    start_date="20250101",
    end_date="20250110",
    symbol="000001.SZ",
)
print(result)
```

或使用 skill 包内脚本（需已安装 `panda-data-tools` 且路径正确）：

```bash
python scripts/call_tool.py get_market_data start_date=20250101 end_date=20250110 symbol=000001.SZ
```

---

## 常见问题

| 现象 | 处理思路 |
|------|----------|
| `panda_tools 未安装` | 执行 `pip install panda-data-tools`|
| `panda_data` 相关导入失败 | 先执行 `pip install panda_data`|
| 认证失败 / 客户端未初始化 | 检查环境变量或 `.env`，并先调用 `CredentialManager.init_from_env()` |
| ClawHub 里只有几个 md/py 文件 | 正常；可执行代码在 pip 包中，不是 skill zip 缺文件 |

---

## 更多文档

- 技能规则与 API 摘要：`SKILL.md`
- 参数与接口说明：`api_reference.md`
- 变更记录：`CHANGELOG.md`
- 开源仓库：`SKILL.md` 中 `homepage` 字段

---

*文档版本与 skill 版本同步维护；若与 PandaAI 官方说明冲突，以官方为准。*


path: README.md
content: # Panda Data Skill

本目录为 **ClawHub 技能包**。

- **安装全流程（OpenClaw / pip / 凭证）**：请优先阅读 **[INSTALL_GUIDE.md](INSTALL_GUIDE.md)**（结构与 [Tushare Skills 安装指南](https://tushare.pro/document/1) 类似，便于对照）。
- 仓库根目录说明见 [项目 README](../README.md)。

## 目录结构

```
panda-data-skill/
├── SKILL.md            # 技能元信息（ClawHub 必须）
├── README.md           # 本文档
├── INSTALL_GUIDE.md    # 安装指南（panda_data + panda-data-tools + 凭证）
├── CHANGELOG.md        # 版本变更记录
├── api_reference.md    # API 详细参考
└── scripts/call_tool.py
```

## 安装

见 [项目 README - 安装](../README.md#安装)

## 凭证配置

见 [项目 README](../README.md#使用方式)

## 快速开始

见 [项目 README - 使用方式](../README.md#使用方式)

## API 分类概览

| 分类 | 方法数 | 说明 |
|------|--------|------|
| market_data | 2 | 日线、分钟级行情 |
| market_ref | 20 | 股票/指数/概念/行业/龙虎榜等 |
| financial | 5 | 业绩预告、财务报告、因子、复权 |
| trade | 5 | 交易日历、在售股票等 |
| futures | 3 | 期货基本信息、后复权、主力合约 |

## 示例脚本

```bash
python scripts/call_tool.py get_market_data start_date=20250101 end_date=20250110 symbol=000001.SZ
```

## 功能对比

| 功能 | v1.0.0 | v2.0.0 |
|------|--------|--------|
| 35 个 API 封装 | ✓ | ✓ |
| 凭证管理 | ✓ | ✓ |
| DuckDB 缓存 | — | ✓ |
| 数据导出 | — | ✓ |

## 版本信息

- 当前版本：2.0.0
- 变更记录：[CHANGELOG.md](CHANGELOG.md)


path: api_reference.md
content: # API 参考

本文档与 `panda_tools` 中各 tool 的 JSON Schema 定义一致，供调用 `ToolRegistry.call_tool(name, **kwargs)` 或 LLM function calling 时查阅。

## 通用约定

| 约定 | 说明 |
|------|------|
| **日期** | 均为字符串 `YYYYMMDD`，如 `20250101` |
| **symbol / 代码类** | 多数支持 `string` 或 `string[]`；未传或空串在部分接口表示「全市场」。经 `ToolRegistry.call_tool` 时会对常见误写做规范化：A 股 `xxxxxx.SH`/`SZ` 按 `get_exchange_suffix` 规则推断；期货先将 `CFFEX`/`SHFE` 等长名映射为 CTP 三位码，再按 `panda_tools/future_ctp_reference.py` 中的**品种—CTP 后缀**对照表（中金所 CFE、郑商所 CZC、大商所 DCE、上期所 SHF、能源中心 INE、广期所 GFE）把与品种不符的后缀改对。`get_market_data` 在 `type=index` 下不改动 `symbol`；港股/美股代码不参与 A 股推断。 |
| **fields** | 返回列筛选；不传通常表示全部字段 |
| **返回值** | 成功时为格式化后的表格字符串（源自 DataFrame）；失败时为统一错误文案 |

---

## 行情数据 `market_data`

### get_market_data

**说明：** 获取日线行情（股票 / 指数 / 期货）。开始、结束日期间隔不超过 5 年。

**返回：** 含日期、代码、开高低收、成交量等。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | 是 | string | 开始日期 YYYYMMDD |
| end_date | 是 | string | 结束日期 YYYYMMDD |
| symbol | 否 | string \| string[] | 代码；A股如 `000001.SZ`，期货如 `A2501.DCE`，指数如 `000001.SH` |
| fields | 否 | string \| string[] | 返回列 |
| type | 否 | enum | `stock`（默认）\|`future`\|`index` |
| indicator | 否 | string | 指数成分筛选，默认 `000985`；可选 `000300`、`000905`、`000985`、`000852`；仅 `type=stock` |
| st | 否 | boolean | 是否含 ST，默认 `true`；仅 `type=stock` |

**期货交易所映射：** CFFEX→CFE, CZCE→CZC, DCE→DCE, SHFE→SHF, INE→INE, GFEX→GFE。

---

### get_market_min_data

**说明：** 获取分钟线。频率与区间限制：`1m`≈1 个月，`5m`≈6 个月，`15m`≈1 年，`60m`≈5 年；指数仅支持 `1m`。

**注意：** 产品类型参数名为 **`symbol_type`**，不是 `type`。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | 是 | string | 开始日期 YYYYMMDD |
| end_date | 是 | string | 结束日期 YYYYMMDD |
| symbol | 否 | string \| string[] | 代码 |
| fields | 否 | string \| string[] | 返回列 |
| symbol_type | 否 | enum | `stock`\|`future`\|`index` |
| time_zone | 否 | [string, string] | 两段交易时段，如 `["10:00","11:00"]` |
| frequency | 否 | enum | `1m`（默认）\|`5m`\|`15m`\|`60m` |

---

## 市场参考数据 `market_ref`

### get_stock_detail

**说明：** A 股 / 港股 / 美股基本信息。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 代码；空串可表示全市场 |
| fields | 否 | string \| string[] | 返回列 |
| market | 否 | enum | `cn`（默认）\|`hk`\|`us` |
| status | 否 | int | `1` 在市，`0` 退市，`-1` 未知 |

---

### get_index_detail

**说明：** 指数基本信息。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 指数代码；空串可全市场 |
| fields | 否 | string \| string[] | 返回列 |
| status | 否 | enum string | `1`\|`0`\|`-1` |

---

### get_concept_list

**说明：** 概念列表及纳入日期。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| concept | 否 | string \| string[] | 概念名，如「英伟达概念」 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |

---

### get_concept_constituents

**说明：** 概念成分股。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| concept | 否 | string \| string[] | 概念名 |
| concept_stock | 否 | string \| string[] | 股票代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |

---

### get_industry_detail

**说明：** 申万行业层级信息。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| fields | 否 | string \| string[] | 返回列 |
| level | 否 | string \| string[] | `L1` / `L2` / `L3` |

---

### get_industry_constituents

**说明：** 行业成分股。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| industry_code | 否 | string \| string[] | 行业代码，如 `801780` |
| stock_symbol | 否 | string \| string[] | 股票代码 |
| level | 否 | enum | `L1`\|`L2`\|`L3` |
| fields | 否 | string \| string[] | 返回列 |

---

### get_stock_industry

**说明：** 单只股票所属行业。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| stock_symbol | **是** | string | 如 `000001.SZ` |
| level | 否 | enum | `L1`\|`L2`\|`L3` |

---

### get_index_indicator

**说明：** 指数估值（PB、PE 等）。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 指数代码；空串可全指数 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |

---

### get_index_weights

**说明：** 指数成分股权重。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| index_symbol | 否 | string \| string[] | 指数代码 |
| stock_symbol | 否 | string \| string[] | 成分股代码 |
| fields | 否 | string \| string[] | 返回列 |

---

### get_lhb_list

**说明：** 龙虎榜上榜记录。类型示例：`G0007`、`T0020`、`C0000`、`D0000` 等。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| type | 否 | string \| string[] | 龙虎榜类型代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |

---

### get_lhb_detail

**说明：** 龙虎榜营业部明细。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| symbol | 否 | string \| string[] | 股票代码 |
| type | 否 | string \| string[] | 龙虎榜类型 |
| side | 否 | enum | `buy`\|`sell`\|`cum` |
| fields | 否 | string \| string[] | 返回列 |

---

### get_repurchase

**说明：** 回购公告与进程。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |

---

### get_margin

**说明：** 融资融券余额与成交。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| symbol | 否 | string \| string[] | 股票代码 |
| fields | 否 | string \| string[] | 返回列 |
| margin_type | 否 | enum | `stock`（融券）\|`cash`（融资） |

---

### get_hsgt_hold

**说明：** 沪深港通持股。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| symbol | 否 | string \| string[] | 股票代码；空串可全市场 |
| fields | 否 | string \| string[] | 返回列 |

---

### get_investor_activity

**说明：** 投资者关系活动记录。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| symbol | 否 | string \| string[] | 股票代码 |
| fields | 否 | string \| string[] | 返回列 |

---

### get_restricted_list

**说明：** 限售解禁明细。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| symbol | 否 | string \| string[] | 股票代码 |
| fields | 否 | string \| string[] | 返回列 |
| market | 否 | string | 默认 `cn` |

---

### get_holder_count

**说明：** 股东户数等。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码；空串可全市场 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |

---

### get_top_holders

**说明：** 十大股东 / 流通股东等。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| symbol | 否 | string \| string[] | 股票代码 |
| fields | 否 | string \| string[] | 返回列 |
| market | 否 | string | 默认 `cn` |
| start_rank | 否 | int | 排名起 |
| end_rank | 否 | int | 排名止 |
| stock_type | 否 | enum | `flow`（流通）\|`total`（总股本口径） |

---

### get_block_trade

**说明：** A 股大宗交易。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |

---

### get_share_float

**说明：** 股本结构（流通、总股本等）。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| symbol | 否 | string \| string[] | 股票代码 |
| fields | 否 | string \| string[] | 返回列 |

---

## 财务与因子 `financial`

### get_fina_forecast

**说明：** 业绩预告。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| fields | 否 | string \| string[] | 返回列 |
| info_date | 否 | string | 公告日 YYYYMMDD |
| end_quarter | 否 | string | 报告季，如 `2025q4` |

---

### get_fina_performance

**说明：** 财务快报。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| fields | 否 | string \| string[] | 返回列 |
| info_date | 否 | string | 公告日 YYYYMMDD |
| end_quarter | 否 | string | 报告季，如 `2025q4` |

---

### get_fina_reports

**说明：** 财报季报（SDK：`get_fina_reports`）；字段前缀 `cfs_*`、`bs_*`、`is_*`、`ratio_*`。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| start_quarter | 否 | string | 如 `2024q1` |
| end_quarter | 否 | string | 如 `2024q4` |
| start_date | 否 | string | YYYYMMDD；未传季度时用于换算 `start_quarter` |
| end_date | 否 | string | YYYYMMDD；未传季度时用于换算 `end_quarter`，并作为 `date` |
| fields | 否 | string \| string[] | 返回列 |
| is_latest | 否 | bool | 是否每组只保留最新一条 |

---

### get_factor

**说明：** 回测因子（价量 + 可选财务因子）。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| factors | **是** | string \| string[] | 如 `open`、`close`、`volume`、`ratio_pe_ttm` 等 |
| symbol | 否 | string \| string[] | 股票或期货代码 |
| index_component | 否 | string | `100`（沪深300）、`010`（中证500）、`001`（中证1000）、`000`（其他） |
| type | 否 | enum | `stock`（默认）\|`future` |

---

### get_adj_factor

**说明：** 复权因子。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |

---

## 交易工具 `trade`

### get_trade_cal

**说明：** 交易日历（SH / HK / US）。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| exchange | 否 | enum | `SH`（默认）\|`HK`\|`US` |
| is_trading_day | 否 | int | `1` 仅交易日，`0` 仅非交易日 |
| fields | 否 | string \| string[] | 返回列 |

---

### get_prev_trade_date

**说明：** 返回**字符串** `YYYYMMDD`，为基准日前第 `n` 个交易日。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| date | **是** | string | 基准日 YYYYMMDD |
| exchange | 否 | enum | `SH`（默认）\|`HK`\|`US` |
| n | 否 | int | 前推交易日个数，默认 `1` |

---

### get_last_trade_date

**说明：** 返回**字符串**最新交易日，无则可能为 `None`。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| exchange | 否 | enum | `SH`（默认）\|`HK`\|`US` |

---

### get_stock_status_change

**说明：** ST、*ST、退市整理等状态变更。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |

---

### get_trade_list

**说明：** 指定日期的可交易股票列表。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| date | **是** | string \| string[] | YYYYMMDD，可多日期 |

---

## 期货 `futures`

### get_future_detail

**说明：** 期货合约元数据。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 合约代码 |
| fields | 否 | string \| string[] | 返回列 |
| is_trading | 否 | int | `1` 交易中，`0` 已退市 |

---

### get_future_market_post

**说明：** 期货后复权行情。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| symbol | 否 | string \| string[] | 合约代码 |
| fields | 否 | string \| string[] | 返回列 |

---

### get_future_dominant

**说明：** 品种主力合约序列（参数为**品种**代码，如 `A`、`ZN`，非具体合约）。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| underlying_symbol | 否 | string \| string[] | 品种代码 |

---

## 维护说明

若业务侧 Schema 有变更，请以 `panda_tools/tools/*.py` 中 `TOOLS` 的 `parameters` 为准，并同步更新本文档。

---

## readers 扩展补充（按 TOOLS.parameters）

以下为本次 readers 接入新增方法，按所属章节归类。

### 行情数据 `market_data`（新增）

#### get_hk_daily

**说明：** 港股日线行情。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 港股代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |

#### get_us_daily

**说明：** 美股日线行情。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 美股代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |

### 市场参考数据 `market_ref`（新增）

#### get_stock_cash_dividend

**说明：** 股票现金分红信息。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| market | 否 | string | 市场，默认 cn |
| fields | 否 | string \| string[] | 返回列 |

#### get_stock_dividend_info

**说明：** 股票分红方案与实施信息。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| market | 否 | string | 市场，默认 cn |
| fields | 否 | string \| string[] | 返回列 |

#### get_stock_split_info

**说明：** 股票送转拆合信息。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| market | 否 | string | 市场，默认 cn |
| fields | 否 | string \| string[] | 返回列 |

#### get_stock_dividend_amount

**说明：** 股票分红金额与分红比例。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| market | 否 | string | 市场，默认 cn |
| fields | 否 | string \| string[] | 返回列 |

#### get_stock_private_placement

**说明：** 股票定向增发信息。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| market | 否 | string | 市场，默认 cn |
| fields | 否 | string \| string[] | 返回列 |

#### get_stock_allotment

**说明：** 股票配股信息。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| market | 否 | string | 市场，默认 cn |
| fields | 否 | string \| string[] | 返回列 |

### 财务与因子 `financial`（新增）

#### get_audit_opinion

**说明：** 审计意见数据。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 股票代码 |
| start_quarter | 否 | string | 起始季度 yyyyqN |
| end_quarter | 否 | string | 结束季度 yyyyqN |
| market | 否 | string | 市场，默认 cn |
| fields | 否 | string \| string[] | 返回列 |

### 期货 `futures`（新增）

#### get_future_netposi_rank

**说明：** 净持仓排名。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| underlying_symbol | 否 | string \| string[] | 品种代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| max_rank | 否 | int | 最大排名 |
| fields | 否 | string \| string[] | 返回列 |
| type | 否 | string | 持仓类型 |

#### get_future_symbol_posi_rank

**说明：** 合约席位持仓排名。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| symbol | 否 | string \| string[] | 合约代码 |
| position_type | 否 | string | 持仓方向 |
| broker_name | 否 | string \| string[] | 席位名称 |
| rank_max | 否 | int | 最大排名 |
| fields | 否 | string \| string[] | 返回列 |

#### get_future_variety_posi_rank

**说明：** 品种席位持仓排名。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| symbol | 否 | string \| string[] | 品种代码 |
| position_type | 否 | string | 持仓方向 |
| broker_name | 否 | string \| string[] | 席位名称 |
| rank_max | 否 | int | 最大排名 |
| fields | 否 | string \| string[] | 返回列 |

#### get_future_contract_daily_indicators

**说明：** 合约日度指标。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| symbol | 否 | string \| string[] | 合约代码 |
| fields | 否 | string \| string[] | 返回列 |

#### get_broker_variety_profit

**说明：** 席位品种盈利。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| symbol | 否 | string \| string[] | 品种代码 |
| fields | 否 | string \| string[] | 返回列 |
| broker | 否 | string \| string[] | 席位名称 |

#### get_broker_grade

**说明：** 席位评级。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| grade | 否 | string | 评级 |

#### get_broker_net_margin

**说明：** 席位净保证金。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| underlying_symbol | 否 | string \| string[] | 品种代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |
| broker | 否 | string \| string[] | 席位名称 |

#### get_broker_net_margin_change

**说明：** 席位净保证金变化。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| underlying_symbol | 否 | string \| string[] | 品种代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |
| broker | 否 | string \| string[] | 席位名称 |

#### get_broker_total_margin

**说明：** 席位总保证金。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| underlying_symbol | 否 | string \| string[] | 品种代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |
| broker | 否 | string \| string[] | 席位名称 |

#### get_future_net_flow

**说明：** 期货净资金流向。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| start_date | **是** | string | YYYYMMDD |
| end_date | **是** | string | YYYYMMDD |
| symbol | 否 | string \| string[] | 合约代码 |
| fields | 否 | string \| string[] | 返回列 |
| broker_name | 否 | string \| string[] | 席位名称 |
| position_type | 否 | string | 持仓方向 |

#### get_future_basis

**说明：** 期货基差。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| underlying_symbol | 否 | string \| string[] | 品种代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |

#### get_future_wr

**说明：** 期货仓单比率。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| underlying_symbol | 否 | string \| string[] | 品种代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| fields | 否 | string \| string[] | 返回列 |

#### get_future_ls_ratio

**说明：** 期货多空比。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 合约代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |

#### get_future_net_cap_change

**说明：** 期货净资金变化。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 合约代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| broker | 否 | string \| string[] | 席位名称 |

#### get_future_contract_rank

**说明：** 期货合约席位排名。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| symbol | 否 | string \| string[] | 合约代码 |
| underlying_symbol | 否 | string \| string[] | 品种代码 |
| start_date | 否 | string | YYYYMMDD |
| end_date | 否 | string | YYYYMMDD |
| type | 否 | string | 统计类型 |
| max_rank | 否 | int | 最大排名 |
| rank_type | 否 | string | 排名类型 |


path: scripts/call_tool.py
content: #!/usr/bin/env python
"""
Panda Data Skill - 命令行调用 tool。

Agent 可通过 exec 调用此脚本，传入 tool 名称和参数。
用法: python scripts/call_tool.py <tool_name> <key>=<value> ...
"""
import json
import sys
from pathlib import Path

# 确保能导入 panda_tools（需已安装 panda-data-tools）
try:
    from panda_tools.credential import CredentialManager
    from panda_tools.registry import ToolRegistry
except ImportError as e:
    print(json.dumps({"error": f"panda_tools 未安装: {e}"}, ensure_ascii=False))
    sys.exit(1)


def parse_args(args: list[str]) -> dict:
    """解析 key=value 形式的参数为字典。"""
    kwargs = {}
    for arg in args:
        if "=" in arg:
            k, v = arg.split("=", 1)
            # 尝试转换为数字
            try:
                v = int(v)
            except ValueError:
                try:
                    v = float(v)
                except ValueError:
                    pass
            kwargs[k.strip()] = v
    return kwargs


def main() -> None:
    if len(sys.argv) < 2:
        print(json.dumps({"error": "用法: python call_tool.py <tool_name> [key=value ...]"}, ensure_ascii=False))
        sys.exit(1)

    tool_name = sys.argv[1]
    kwargs = parse_args(sys.argv[2:])

    CredentialManager.init_from_env()
    registry = ToolRegistry()

    if tool_name not in registry.get_tool_names():
        print(json.dumps({"error": f"未知的 tool: {tool_name}"}, ensure_ascii=False))
        sys.exit(1)

    try:
        result = registry.call_tool(tool_name, **kwargs)
        print(result)
    except Exception as e:
        print(json.dumps({"error": str(e)}, ensure_ascii=False))
        sys.exit(1)


if __name__ == "__main__":
    main()


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)