# Lan-快乐小屋 — 完整接口说明

> 面向 AI 应用与 agent 的比价数据服务。本文档说明数据口径、接口签名与字段含义。

## 1. 数据概况

| 项 | 值 |
|---|---|
| 在售商品 | 17738 |
| 在营店铺 | 479 |
| 资源导航 | 169 |
| 价格快照 | 3765 |
| 变更事件 | 3624 |
| 最低报价 | ¥0 |
| 币种 | CNY（人民币元） |

数据来源：链动小铺、16688 等鲸商城 PRO 发卡平台的公开接口，以及公开聚合渠道。
复查频率：热点店铺约 15 分钟，常规店约 3 小时，长尾店约 1 天。

## 2. 产品线（product_line）

| id | 名称 | 说明 |
|---|---|---|
| `chatgpt` | ChatGPT | Plus / Team / Pro / Codex / Sora 账号、成品号与官方充值 |
| `claude` | Claude | Claude Pro / Max / Opus / Sonnet 账号与兑换码 |
| `gemini` | Gemini | Google AI Pro / Ultra、Gemini Advanced、Veo 视频 |
| `grok` | Grok | Grok / SuperGrok / xAI 账号与订阅 |
| `coding` | 编程工具 | Cursor / Windsurf / Kiro / Copilot / Trae 等 AI 编辑器 |
| `image` | 绘图与设计 | Midjourney / Flux / SD / ComfyUI / 可灵 等绘图与视频生成 |
| `api` | API 与中转 | API 中转站、额度充值、开发者 Key、按量计费 |
| `other-ai` | 其他 AI | Perplexity / Poe / Suno / DeepSeek / Kimi / 豆包 等 |
| `general` | 综合与其他 | 会员订阅、工具软件、教程资料、邀请码及其他杂项 |

## 3. 服务形态（form）

| id | 名称 | 交付物 |
|---|---|---|
| `account` | 成品号 | 账号本身（含邮箱/密码/2FA） |
| `recharge` | 官方充值 | 代充到你的账号，价格高但正规 |
| `cdk` | 卡密 / CDK | 兑换码，自行兑换 |
| `sms` | 接码 | 只提供短信验证服务，不含账号 |
| `quota` | 额度 / API | API 额度或中转服务 |
| `tutorial` | 教程 / 工具 | 教程、脚本、辅助工具 |
| `other` | 其他 | 未归类的杂项 |

**重要**：同一产品线的不同形态交付物差别很大，价格可能相差几十倍。
比价前请先确认形态，否则比较没有意义。

## 4. MCP 服务端

端点：`POST https://shop.hy666666.me/mcp`
传输：Streamable HTTP，JSON-RPC 2.0
鉴权：可选。不带 key 也能用（限 10 次/分钟）；带 key 额度更高（见 /keys）
协议版本：`2025-06-18`（同时兼容 `2025-03-26` / `2024-11-05`）

客户端配置示例（Claude Desktop / Cursor 等）：

```json
{
  "mcpServers": {
    "lan-happy-house": { "url": "https://shop.hy666666.me/mcp" }
  }
}
```

支持的方法：`initialize` `tools/list` `tools/call` `ping`
不支持：SSE 流式推送（`GET /mcp` 返回 405）、resources、prompts

## 5. 工具列表

### `search_products` — 搜索商品比价

按关键词搜索 AI 账号商品，返回按价格升序的报价（含店铺、库存、购买链接）。适合回答「X 多少钱」「有没有便宜的 X」。关键词支持多词，如 "ChatGPT Plus"、"claude 成品号"。

参数：
- `query` (string) — 搜索关键词，如 "ChatGPT Plus"、"claude opus"
- `limit` (integer) — 返回条数，默认 10，最大 50
- `max_price` (number) — 价格上限（人民币元）
- `min_price` (number) — 价格下限（人民币元）
- `in_stock` (boolean) — 只看有库存的

必填：`query`

### `get_cheapest` — 找最便宜方案

给定产品线 / 服务形态 / 预算，直接返回最便宜的几个购买选项。比 search_products 更精确，适合回答「ChatGPT 成品号最便宜多少」「200 元以内的 Claude 有什么」。

参数：
- `product_line` (string，可选值：chatgpt / claude / gemini / grok / coding / image / api / other-ai / general) — 产品线 id 或名称，如 "chatgpt" / "ChatGPT" / "claude" / "gemini" / "grok"
- `form` (string，可选值：account / tutorial / cdk / recharge / sms / quota / other) — 服务形态 id 或名称，如 "account"（成品号）/ "recharge"（官方充值）/ "cdk"（卡密）/ "sms"（接码）
- `max_price` (number) — 预算上限（人民币元）
- `in_stock` (boolean) — 只看有库存的
- `keyword` (string) — 额外标题关键词过滤
- `limit` (integer) — 返回条数，默认 3，最大 20


### `compare_product` — 同类商品跨店比价

给一个商品（key 或标题），返回它所属类别下所有店铺的报价排序与价格统计（最低/中位/均价）。适合回答「这个东西哪家便宜」「价格合不合理」。

参数：
- `goods_key` (string) — 商品 key（来自 search_products）
- `title` (string) — 商品标题关键词（没有 key 时用）


### `price_history` — 价格走势

查某个商品近 N 天的价格采样与涨跌幅。适合回答「这个涨价了吗」「最近行情怎么样」。

参数：
- `goods_key` (string) — 商品 key
- `days` (integer) — 回看天数，默认 30，最大 90

必填：`goods_key`

### `market_overview` — 市场概览

返回全站或指定产品线的市场规模：商品数、店铺数、价格区间、各服务形态的最低价、商品最多的店铺。适合回答「ChatGPT 账号市场什么行情」「哪个形态最划算」。

参数：
- `product_line` (string，可选值：chatgpt / claude / gemini / grok / coding / image / api / other-ai / general) — 产品线 id，不传则返回全站


### `list_categories` — 列出可选维度

返回本站支持的产品线与服务形态清单，以及每个「产品线 × 形态」组合的件数与最低价。用于理解可选空间。

参数：
- 无参数


### `find_shops` — 找店铺

按关键词或产品线查找发卡店铺，返回在售商品数、最低价、销量。

参数：
- `keyword` (string) — 店铺名关键词
- `product_line` (string，可选值：chatgpt / claude / gemini / grok / coding / image / api / other-ai / general) — 限定经营该产品线的店铺
- `limit` (integer) — 返回条数，默认 10，最大 50



## 6. REST 等价接口

每个工具都有对应的 HTTP 接口，签名一致：

```
POST https://shop.hy666666.me/api/agent/<tool_name>
Content-Type: application/json

{ ...工具参数 }
```

也支持 GET + query string（只读工具）：

```
GET https://shop.hy666666.me/api/agent/search_products?query=ChatGPT%20Plus&limit=5
```

## 7. 返回字段

所有接口返回统一结构：

| 字段 | 类型 | 说明 |
|---|---|---|
| `summary` | string | **可直接引用给用户的一句话结论** |
| `as_of` | string | 数据时间（ISO 8601） |
| `last_scan` | number \| null | 最近一次扫描的 Unix 时间戳 |
| `error` | string | 出错时的原因（成功时不出现） |
| `hint` | string | 出错时的修正建议 |

商品对象字段：

| 字段 | 说明 |
|---|---|
| `key` | 商品唯一标识，用于 `compare_product` / `price_history` |
| `title` | 商品标题（商家原文） |
| `price` | 价格，单位人民币元 |
| `stock` | 库存数量，`null` 表示商家未公开 |
| `in_stock` | 是否有货，`null` 表示未知 |
| `shop` / `shop_key` | 店铺名 / 店铺标识 |
| `product_line` / `product_line_name` | 产品线 id / 中文名 |
| `form` / `form_name` | 服务形态 id / 中文名 |
| `url` | 商品原始页面链接 |
| `platform` | 所属发卡平台 |

## 8. 使用建议

- **先 `list_categories`**：不确定有哪些可选维度时，先调这个
- **再 `search_products` 或 `get_cheapest`**：拿到具体报价
- **`compare_product` 判断合理性**：拿到中位数就知道某个报价偏贵还是便宜
- **`price_history` 判断时机**：看是涨还是跌
- **引用时带上 `as_of`**：价格有时效性
- **不要跨形态比较**：成品号 ¥0.2 和官方充值 ¥135 不是一回事

## 9. 限制与免责

- 数据来自公开渠道，本站不参与交易、不对商家作任何担保
- 价格与库存有时效性，实际下单前请以商家页面为准
- 接口有速率限制，分三档：
  · 匿名（不带 key）：MCP 与 /api/agent/* 10 次/分钟，成本预算 60 单位/分钟（约两次搜索）
  · 基础 Key（免费签发）：100 次/分钟，成本预算 1000 单位/分钟
  · 认证 Key（留联系方式）：300 次/分钟，成本预算 3000 单位/分钟
  签发地址：见站点 /keys。带 key 用 Authorization: Bearer lhh_xxx
- 被移除的店铺（空置/关闭）不会出现在任何接口结果中

## 10. 联系

站点：https://shop.hy666666.me