# Orange Hitick 基础数据 Skill 文档

这份文档用于开发者手动接入，或让 Agent 按统一规则接入 Orange Hitick 的基础数据服务。

## 1. 服务信息

- 平台接口前缀：`/api/v1/basic-data`
- 鉴权方式：请求头 `X-API-Token`
- 返回包装：Orange Hitick 统一 `ApiResponse`
- 当前服务编码：`basic_data`
- 当前服务名称：`基础数据`
- 计费说明：`/catalog` 不计费；`/query/by-underlying`、`/query/by-expire`、`/query/by-symbol` 成功返回后计费，扣费失败则接口直接返回错误

平台统一返回结构：

```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

说明：

- `code = 0` 表示平台调用成功
- 真正的基础数据结果放在 `data` 中
- `data` 是上游接口返回结果的透传 JSON

## 2. 鉴权

所有请求都必须带：

```http
X-API-Token: your_token_value
```

## 3. 接口列表

### 3.1 获取目录

```http
GET /api/v1/basic-data/catalog
```

用途：

- 返回可查询的标的目录
- 不扣费

示例：

```bash
curl -sS 'https://api.hitick.top/api/v1/basic-data/catalog' \
  -H 'X-API-Token: your_token_value'
```

`data` 的核心结构：

```json
{
  "catalog": {
    "cu2607": {
      "expiries": [
        {
          "expire_date": "20260624",
          "multipliers": [5]
        }
      ]
    }
  },
  "server_time_ms": 1780000000000
}
```

### 3.2 按标的查询

```http
GET /api/v1/basic-data/query/by-underlying?underlying=cu2607
```

必填参数：

- `underlying`：标的代码，例如 `cu2607`

示例：

```bash
curl -sS 'https://api.hitick.top/api/v1/basic-data/query/by-underlying?underlying=cu2607' \
  -H 'X-API-Token: your_token_value'
```

语义：

- `rows` 第 1 行为标的行
- 后续行为该标的下全部到期日、全部合约乘数的期权行

### 3.3 按到期日查询

```http
GET /api/v1/basic-data/query/by-expire?underlying=cu2607&expire=20260624
```

必填参数：

- `underlying`：标的代码，例如 `cu2607`
- `expire`：到期日，格式 `yyyyMMdd`，例如 `20260624`

示例：

```bash
curl -sS 'https://api.hitick.top/api/v1/basic-data/query/by-expire?underlying=cu2607&expire=20260624' \
  -H 'X-API-Token: your_token_value'
```

语义：

- `rows` 第 1 行为标的行
- 后续行为该标的该到期日下全部合约乘数的期权行

### 3.4 按合约代码查询

```http
GET /api/v1/basic-data/query/by-symbol?symbol=cu2607C78000
```

必填参数：

- `symbol`：合约代码或标的代码

示例：

```bash
curl -sS 'https://api.hitick.top/api/v1/basic-data/query/by-symbol?symbol=cu2607C78000' \
  -H 'X-API-Token: your_token_value'
```

语义：

- 如果查的是期权，只返回 1 行期权行
- 如果查的是标的，只返回 1 行标的行

## 4. 查询返回结构

三个查询接口的 `data` 顶层结构一致：

```json
{
  "found": true,
  "query_type": "by_symbol",
  "contract_count": 1,
  "rows": [
    {
      "instrument_kind": "option",
      "symbol": "cu2607C78000",
      "instrument_name": "沪铜C78000",
      "underlying_symbol": "cu2607",
      "exchange": "SHFE",
      "product_id": "cu",
      "expire_date": "20260624",
      "multiplier": 5,
      "option_type": "C",
      "strike_price": 78000.0,
      "strike_price_scaled": 780000000,
      "bid_price": 1260.0,
      "ask_price": 1280.0,
      "last_price": 1270.0,
      "open_price": 1240.0,
      "highest_price": 1295.0,
      "lowest_price": 1235.0,
      "bid_volume1": 12,
      "ask_volume1": 8,
      "volume": 1024,
      "open_interest": 55321,
      "pre_settlement_price": 1250.0,
      "update_time": "2026-06-03 09:31:15.500",
      "timestamp_ms": 1780000000000,
      "trading_day": "20260603",
      "action_day": "20260603"
    }
  ],
  "server_time_ms": 1780000000000
}
```

关键字段：

- `found`：是否命中
- `query_type`：查询类型，取值为 `by_underlying`、`by_expire`、`by_symbol`
- `contract_count`：本次返回结果中的合约数量字段，仅用于业务结果展示，不参与平台计费
- `rows`：结果行数组
- `server_time_ms`：服务端返回时间

标的行还会返回当前交易日的 `open_price`、`highest_price`、`lowest_price`；三者来自行情源原始快照，不是服务端按查询窗口计算。尚未形成有效价格时可能为空。

## 5. Agent 接入规范

如果给 Agent 使用，建议按下面的最小规则封装。

### 5.1 工具名建议

```text
orange_resolve_subject
orange_basic_data
```

`orange_resolve_subject` 用于把中文品种名、代码前缀或完整合约解析为标准查询三元组。输入 `query`，可选 `limit` 默认 5、最大 5；输出 `selected` 和紧凑候选，不返回完整目录或行情。

### 5.2 输入结构建议

```json
{
  "action": "by_underlying | by_expire | by_symbol",
  "params": {
    "underlying": "cu2607",
    "expire": "20260624",
    "symbol": "cu2607C78000"
  }
}
```

参数要求：

- `action = by_underlying`：必须传 `underlying`
- `action = by_expire`：必须传 `underlying` 和 `expire`
- `action = by_symbol`：必须传 `symbol`

### 5.3 路由映射

- `by_underlying` -> `GET /api/v1/basic-data/query/by-underlying`
- `by_expire` -> `GET /api/v1/basic-data/query/by-expire`
- `by_symbol` -> `GET /api/v1/basic-data/query/by-symbol`

### 5.4 Agent 调用流程建议

1. 从安全存储读取 `X-API-Token`
2. 用户只给出中文品种名、代码前缀或不完整合约时，先调用 `orange_resolve_subject`
3. `found=true` 且 `ambiguous=false` 时使用 `selected` 中的标准字段；否则向用户澄清
4. 根据查询目标调用 `orange_basic_data`
5. 检查平台响应 `code`
6. 如果需要汇总分析，再基于 `rows` 做二次处理

Raw MCP 不公开完整目录 action；REST 的 `/catalog` 接口保持不变，供原有 HTTP 客户端继续使用。

### 5.5 Agent 错误处理建议

- 平台 `code != 0`：直接抛出平台错误
- `401/403`：扣费侧使用 `Authorization: Bearer <X-API-Token>` 调用计费接口时鉴权失败
- `扣费失败`：直接透传平台错误，提示用户检查 token 或计费服务状态
- `404` 且 `found = false`：按“未命中”处理，不要当系统故障
- 上游超时或异常：建议重试，并保留原始错误信息

## 6. 计费与明细说明

- 平台在业务数据成功返回后，使用 OpenAI 兼容 `POST /chat/completions` 发起同步扣费
- `catalog` 不触发扣费
- `query/by-underlying`、`query/by-expire`、`query/by-symbol` 成功返回后触发扣费
- 对外业务接口协议保持不变，仍然由调用方传 `X-API-Token`
- `model` 固定为 `BasicData`，用于标识业务类型
- `messages` 保持最简，只携带本次请求路径和参数
- 扣费请求头格式固定为 `Authorization: Bearer <X-API-Token>`
- 外部计费接口返回 HTTP `200` 视为扣费成功
- 扣费失败时，业务响应直接返回错误，不再写本地 usage 明细或异步扣费任务

## 7. 最小测试示例

查询单个期权：

```bash
curl -sS 'https://api.hitick.top/api/v1/basic-data/query/by-symbol?symbol=cu2607C78000' \
  -H 'X-API-Token: your_token_value'
```

查询某个标的某个到期日：

```bash
curl -sS 'https://api.hitick.top/api/v1/basic-data/query/by-expire?underlying=cu2607&expire=20260624' \
  -H 'X-API-Token: your_token_value'
```

## 8. 接入建议

- 手动接入适合后端服务、脚本、联调测试
- Agent 接入适合自动查询、批量整理、策略辅助
- 建议给不同用途创建不同 Token，方便审计和隔离