# 如何接入

视频教程：[WorkBuddy、豆包工作台与 Agent 连接使用](./video-tutorials.md)，支持在文档页内播放。

Orange Hitick 当前提供 3 种接入方式：

1. MCP 接入
2. Skill 接入
3. 手动接入

无论使用哪种方式，调用本站接口都必须提供 `ApiToken`。

## 1. 获取 ApiToken

`ApiToken` 获取方式：

1. 访问 [https://open.hitick.top](https://open.hitick.top)
2. 注册账号并登录
3. 打开 **令牌管理** 页面，查看你的 `ApiToken`

`ApiToken` 是一个以 `sk-` 开头的字符串，例如 `sk-xxxxxxxx`。
后续所有业务接口调用都需要提供 `ApiToken`。

## 2. 方式一：MCP 接入

如果你的 Agent 或客户端支持 MCP，可以直接添加 Orange Hitick 的 MCP 服务。

MCP 接入的优势：

- 当 Orange Hitick 新增能力、扩展工具或更新服务端实现时，Agent 侧通常可以自动感知最新 MCP 能力
- 一般不需要你手动同步本地接入文档
- 适合希望长期保持能力自动更新的场景

把下面这段提示词复制给你的 Agent，并将 `<your_api_token>` 替换为你自己的 `ApiToken`：

```text
请帮我在当前 Agent 或客户端中配置并启用下面的 MCP 服务。请自行识别当前客户端的 MCP 配置方式并完成配置，配置完成后验证是否能正常发现和调用工具；如果需要重启或重新连接，请明确告诉我。

MCP URL：https://api.hitick.top/mcp
HTTP Header：X-API-Token: <your_api_token>
```

接入后，Agent 就可以通过 MCP 方式调用 Orange Hitick 提供的数据能力。

测试方法：

接入完成后，向 Agent 发送下面这句话：

```text
使用hitick mcp获取黄金的最新信息
```

如果 Agent 能通过 Hitick MCP 返回黄金的最新信息，说明 MCP 已接入成功。

## 3. 方式二：Skill 接入

如果你使用的是支持 Skill 的 Agent，可以直接把对应的 Skill 文档 URL 发给 Agent，Agent 会按文档说明自动完成接入。

Skill 接入的特点：

- Skill 文档接入后，Agent 依据你提供的文档 URL 和文档内容完成封装
- 如果 Orange Hitick 后续新增能力、调整参数或更新接入方式，已经复制给 Agent 的旧 Skill 文档不会自动更新
- 当 Skill 文档有更新时，你需要将最新版本的文档 URL 或文档内容重新提供给 Agent，手动完成同步

当前可用 Skill 文档：

- [基础数据 Skill](./api/basic-data-skill.md)
- [波动率数据 Skill](./api/vol-data-skill.md)
- [席位四榜 Skill](./api/seat-analysis-skill.md)
- [主观信号 Skill](./api/subjective-signal-skill.md)
- [Polymarket Up/Down Skill](./api/polymarket-up-down-skill.md)
- [Trump Statements Skill](./api/trump-statements-skill.md)

推荐做法：

1. 选择你要接入的能力对应的 Skill 文档
2. 将 Skill 文档 URL 发给 Agent
3. 明确告诉 Agent 你的 `ApiToken`
4. 由 Agent 按文档中的接口定义、参数结构和调用规范完成接入

推荐提示词：

```text
下面是 Orange Hitick 的 Skill 文档 URL，请你先阅读文档，再按文档要求完成接入，并在后续调用中使用我提供的 ApiToken。

要求：
1. 先访问并阅读这份 Skill 文档
2. 按文档里的接口定义、参数结构和调用规范完成封装
3. 如果需要发起调用，使用我提供的 ApiToken
4. 优先先帮我完成一个最小可用示例，确认已经接通

我的 ApiToken：<your_api_token>

Skill 文档 URL（按需选择其一）：
- 基础数据：https://open.hitick.top/doc/raw/api/basic-data-skill.md
- 波动率数据：https://open.hitick.top/doc/raw/api/vol-data-skill.md
- 席位四榜：https://open.hitick.top/doc/raw/api/seat-analysis-skill.md
- 主观信号：https://open.hitick.top/doc/raw/api/subjective-signal-skill.md
- Polymarket Up/Down：https://open.hitick.top/doc/raw/api/polymarket-up-down-skill.md
- Trump Statements：https://open.hitick.top/doc/raw/api/trump-statements-skill.md
```

说明：

- Skill 方式适合让 Agent 自动生成工具封装、调用代码或接入配置
- Skill 文档不会像 MCP 一样自动跟随后端能力更新
- 调用本站接口时仍必须提供 `ApiToken`
- 建议只把 `ApiToken` 通过安全配置方式提供给 Agent，并在调用时注入参数

## 4. 方式三：手动接入

如果你希望自己写代码调用 API，可以直接按照本文档和各能力文档完成接入。平台目前覆盖基础数据、波动率数据、席位四榜、主观信号、Polymarket Up/Down 和 Trump Statements 数据。

### 4.1 基本调用规则

- 基础域名：`https://api.hitick.top`
- 鉴权请求头：`X-API-Token`
- 返回结构：统一为 `ApiResponse`

统一返回示例：

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

说明：

- `code = 0` 表示请求成功
- 具体业务结果在 `data` 字段中

### 4.2 手动接入流程

1. 从 [https://open.hitick.top](https://open.hitick.top) 获取 `ApiToken`
2. 选择你要调用的服务能力
3. 按对应 API 文档构造 HTTP 请求
4. 在请求头中带上 `X-API-Token`
5. 解析返回的 `code`、`message` 和 `data`

### 4.3 API 文档入口

- [基础数据 API / Skill 文档](./api/basic-data-skill.md)
- [波动率数据 API / Skill 文档](./api/vol-data-skill.md)
- [席位四榜 API / Skill 文档](./api/seat-analysis-skill.md)
- [主观信号 API / Skill 文档](./api/subjective-signal-skill.md)
- [Polymarket Up/Down API / Skill 文档](./api/polymarket-up-down-skill.md)
- [Trump Statements API / Skill 文档](./api/trump-statements-skill.md)

### 4.4 调用示例

以基础数据目录接口为例：

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

## 5. 选择建议

- 想快速让 Agent 直接可用：优先用 MCP 接入
- 想在后续新增能力时尽量自动更新：优先用 MCP 接入
- 想让 Agent 按文档自动生成接入逻辑：用 Skill 接入
- 如果使用 Skill 接入，要接受后续需要手动同步新版 Skill 文档
- 想自己控制调用逻辑和代码实现：用手动接入

## 6. 安全建议

- 不要把 `ApiToken` 提交到 Git 仓库
- 不要把 `ApiToken` 直接写死在前端代码中
- 优先让 Agent 将 `ApiToken` 保存到客户端的安全配置中