Openclaw Stock Skill

## � 核心能力

本技能提供强大的股票数据查询与分析能力，主要包含：

1. **实时数据**：提供实时股票快照、实时分时行情。
2. **历史数据**：支持查询股票、可转债、ETF、指数等品种的历史数据（日线、分钟线、财务指标等）。
3. **自定义通知**（开发中）：支持涨停、炸板、放量大涨、涨停大额成交等异动信号的自定义消息通知。

## �📥 安装方法

```bash
npx skills add https://github.com/1018466411/openclaw-stock-data-skill
```

安装时按提示选择：

1. 选择 **openclaw**
2. 选择 **global** 应用于所有 Agent
3. Copy to all agents: **yes**

本技能教会代理如何使用你自建的股票数据服务（注册账号 `https://data.diemeng.chat`），通过 **API Key** 进行鉴权，查询股票的日线、分钟线、财务指标等数据。

> ⚙️ **API Key 配置约定**
>
> - OpenClaw 会按照 [`skills.entries.<key>`](https://docs.openclaw.ai/tools/skills-config) [配置](https://docs.openclaw.ai/tools/skills-config) 把 API Key 和自定义配置注入到进程环境变量中。
> - 本技能约定使用环境变量 **`STOCK_API_KEY`** 作为主密钥，并在 `metadata.openclaw.primaryEnv` 中声明，以便通过 `skills.entries.openclaw-stock-skill.apiKey` 统一配置。
> - 推荐的 OpenClaw 配置示例（`~/.openclaw/openclaw.json`）：
>
> ```json5
> {
>   skills: {
>     entries: {
>       "openclaw-stock-skill": {
>         enabled: true,
>         // 建议在 OpenClaw UI 的 Skill 参数面板里填写 apiKey，
>         // Gateway 会自动将其写入 STOCK_API_KEY 环境变量
>         apiKey: { source: "env", provider: "default", id: "STOCK_API_KEY" },
>         env: {
>           // 可在这里直接写死，或通过系统环境变量覆盖
>           STOCK_API_KEY: "YOUR_REAL_STOCK_API_KEY"
>         },
>         config: {
>           // 可选：覆盖默认域名
>           baseUrl: "https://data.diemeng.chat"
>         }
>       }
>     }
>   }
> }
> ```
>
> 参考文档：[Skills Config](https://docs.openclaw.ai/tools/skills-config)、[Skills](https://docs.openclaw.ai/tools/skills)

## ⚠️ 重要说明

### 1. 权限开通与 403 错误

如果 API 返回 **403 错误**，说明您的账号没有开通对应接口的权限。
请务必访问官网 <https://data.diemeng.chat/>（海外请访问 `https://mg.diemeng.chat/`），在个人中心开通所需权限（如股票行情、实时快照、可转债等）。

### 2. 接口类型区分

- **实时接口**：
  - `get_stock_snapshot_daily`（不传日期或传今日）：获取最新实时快照（价格、成交量、五档盘口等）。
  - `get_stock_snapshot_push_history`：获取实时推送的历史记录。
  - `get_call_auction`：获取集合竞价数据。
- **历史接口**：
  - `get_daily_data`：获取历史日 K 线。
  - `get_kline_data`：获取历史周期K线（周K、月K）。
  - `get_kline_adj_data`：获取复权历史周期K线（周K、月K）。
  - `get_history_data`：获取历史分钟线。
  - `get_finance_data`：获取历史财务指标。
  - `get_financial_indicator`：获取财务指标报表数据（stock\_financial\_indicator）。
  - `get_income_statement`：获取利润表数据（stock\_income）。
  - `get_balancesheet`：获取资产负债表数据（stock\_balancesheet）。
  - `get_cashflow_statement`：获取现金流量表数据（stock\_cashflow）。
  - `get_main_fund_flow`：获取大小单资金金流向。
  - `get_main_fund_flow_overview`：获取主力资金流向总览。
  - `get_cyq_chips`：获取筹码峰分布。
  - `get_holder_number`：获取股东人数数据。
  - `get_pledge_stat`：获取股票质押统计数据。
  - `get_margin_detail`：获取融资融券明细数据。
  - `get_stock_snapshot_daily`（传历史日期）：获取历史快照。
- **指数与板块接口**：
  - `get_index_history`：获取指数分钟级历史数据。
  - `get_index_realtime_history`：获取指数当天实时 1 分钟级别分时数据。
  - `get_index_weight`：获取指数月度成分和权重数据（index_code 必传，可按 stock_code 和 trade_date 筛选）。
  - `get_ths_sector_categories`：获取同花顺板块分类数据。
  - `get_ths_constituent_stocks`：获取同花顺成分股数据。
  - `get_dc_blocks`：获取东方财富板块列表。
  - `get_dc_daily`：获取东方财富板块日K（按交易日或板块代码）。
  - `get_dc_block_stocks`：获取东方财富板块成分股（支持板块/日期/股票筛选，空参默认最新日期）。
  - `get_tdx_block_stocks`：获取通达信板块成分股，返回分页结构 `data.total/page/page_size/list`，其中 `list` 项包含 `block_code`、`block_name`、`block_type`、`stock_code`。

## 总体说明

- **获取正确的 API Key 并验证**：
  - **一定要获取到正确的 apiKey 才可以调用接口。**
  - **获取途径**：优先从环境变量 `STOCK_API_KEY` 读取，或从当前目录的 `config.json` 获取。如果在 Skill 面板配置了也会注入到环境变量中。
- **基础域名**：默认接口的域名是 `data.diemeng.chat`，**如果是海外 IP 则访问 `mg.diemeng.chat`**。
- **鉴权方式**：所有需要权限的接口都必须带上 API Key，并且**必须放到 HTTP Header 里面**：
  - `apiKey: <STOCK_API_KEY>`（强制要求）
  - `Content-Type: application/json`
- **返回结构**：
  - 大多数接口返回：`{ "code": 200, "msg": "成功", "data": { ... } }`
  - 少数列表类接口直接返回数组或简单结构，实际响应以 JSON 为准。
- **限流与黑名单**：
  - API Key 及 IP 都有严格限流与黑名单逻辑：
    - 无效 API Key 多次尝试会触发封禁（参见后端 `DataAccessVerifier` 实现）。
    - 需优先缓存和复用同