内容
# 赫尔墨斯市场工具
**Wildberries** 和 **Ozon** 的商品搜索/比较工具，适用于 [赫尔墨斯](https://hermes-agent.nousresearch.com) 代理。连接方式为 MCP 服务器。
比较和推荐由 LLM 自行完成；工具仅提供标准化数据。
状态：**Wildberries 和 Ozon 均已准备就绪**（每个平台的搜索/卡片/评论）。
单个请求 `marketplace="all"` 可在两个平台上搜索。详见 `SPEC.md`。
## 工具
| 工具 | 功能 |
|---|---|
| `marketplace_search` | 商品搜索 → 标准化结果（价格、评分、评论、链接、预览） |
| `get_product_card` | 完整商品卡片：特性、描述、图片 URL |
| `get_reviews` | 评论（按有用性/新鲜度排序） |
## 安装
```bash
git clone <repo> hermes-marketplace-tools
cd hermes-marketplace-tools
uv venv && uv pip install -e .
uv run python -m camoufox fetch # Ozon 使用 headless 浏览器（~300 MB，一次性）
```
> Ozon 使用 headless 浏览器（camoufox）。WB 使用 HTTP，不需要浏览器。
> `playwright` 版本固定为 1.50.0；更新版本会导致与 firefox 构建的 camoufox 协议冲突。
## 配置
通过环境变量 `PROXY_URL` 设置代理（SOCKS5，RU-IP）。**请勿提交凭证。**
```bash
export PROXY_URL="socks5h://USER:PASS@pool.proxy.market:10000"
```
## 连接到赫尔墨斯
在 `~/.hermes/config.yaml` 中：
```yaml
mcp_servers:
marketplace:
command: "/path/to/hermes-marketplace-tools/.venv/bin/python"
args: ["-m", "mcp_server.server"]
env:
PROXY_URL: "socks5h://USER:PASS@pool.proxy.market:10000"
```
编辑配置文件后 **重启赫尔墨斯**；MCP 服务器将在启动时加载。
工具将显示为 `mcp_marketplace_marketplace_search` 等。
## 本地运行（无需赫尔墨斯）
```bash
PROXY_URL="socks5h://..." .venv/bin/python -m mcp_server.server # 通过 stdio 启动 MCP
```
要检查核心逻辑，请参见 `marketplace_core`（可直接导入 `MarketplaceService`；未来 Telegram 机器人也将使用它）。
## 关于 WB 的注意事项（故障时重要）
- 所有流量均通过代理（RU-IP）；价格以分币为单位。
- `card.wb.ru/v4` 对 Chrome 的 TLS 配置返回 403；客户端使用 `impersonate="safari"`。
- 图片 URL 按模式 `basket-{NN}.wbbasket.ru/...` 收集；编号 `NN` 自我修复并缓存在 `~/.hermes/marketplace_cache.sqlite` 中。
- WB 端点为非官方，且有时会更改版本；详见 `SPEC.md`（附录 A）。
