razbor-servisa

---
name: razbor-servisa
description: |
  Метод-рефлекс: как превратить ЛЮБОЙ сторонний сервис в CLI-инструмент для агента, когда у сервиса
  нет удобного «разъёма». Скилл сам определяет ситуацию доступа (есть открытый API / API кривой и
  неполный / API нет вообще) и ведёт по нужной ветке: собрать по докам API, либо подсмотреть скрытый
  API прямо в браузере — режим разработчика (F12) → вкладка Network → Copy as cURL → сборка CLI под
  стек проекта → генерация Skill, чтобы агент сам звал команды.
  Обязательно используй этот скилл, когда задача касается ЧУЖОГО/СТОРОННЕГО сервиса: интеграция,
  автоматизация или повторение его логики (маркетплейс, банк, CRM, сервис рассылок и подобные),
  а также по фразам: «изучить бэкенд сайта», «посмотреть через режим разработчика / F12 / DevTools»,
  «у сервиса нет API», «реверс скрытого API», «собрать CLI под сервис», «повторить то, что делает
  этот сервис», «как этот сайт общается со своим сервером». Это универсальный метод — применяй его в
  любом проекте, где мы изучаем или подключаем внешний сервис.
  НЕ для внутренней логики, БД или UI собственного проекта — только для внешних сервисов.
user-invocable: true
---

# razbor-servisa — сторонний сервис → CLI для агента

Цель: дать агенту «кнопку» для работы с чужим сервисом, у которого нет удобного способа автоматизации. Мы не пишем гору кода вручную — разбираем, **как сервис общается со своим сервером**, и собираем маленький инструмент (CLI), который повторяет ту же логику.

Главный принцип: **опирайся на факты, а не на догадки**. Реальный источник правды — либо официальная документация API, либо настоящие запросы, которые браузер шлёт серверу. Ничего не выдумывай — ни endpoint'ов, ни полей, ни форматов, которых не видел своими глазами.

---

## 0. Безопасность — прочитай первым, это не формальность

- **Только СВОЙ кабинет и СВОИ данные.** Автоматизируем аккаунт, к которому у пользователя есть законный доступ (его подписка/логин). Не трогаем чужие аккаунты, не собираем чужие данные.
- **Секреты — в `.env`, никогда в код и никогда в чат.** Токен, cookie, ключ доступа — читаются из окружения. Если увидел ключ в коде — вынеси в `.env`, предупреди пользователя.
- **Чтение — свободно. Действие — с подтверждением.** Достать список, прочитать данные — можно сразу. Любая операция, которая **меняет** что-то на стороне сервиса (создать/удалить/отправить сообщение/оплатить/изменить настройки), выполняется только после явного «да» от пользователя: сначала опиши, что и зачем, потом делай.
- **Не обходи капчу и антибот-защиту.** Если сервис требует капчу — это стоп-сигнал, скажи пользователю.
- **Уважай правила сервиса.** Условия использования у каждого свои; проверить, что автоматизация своего аккаунта ими не запрещена, — ответственность пользователя. Заметил прямой запрет — предупреди.

### Что этот скилл НЕ делает

Не парсит чужие сайты ради чужих данных, не обходит защиту от ботов, не собирает информацию об аккаунтах, к которым у пользователя нет доступа. Это инструмент автоматизации **своего собственного кабинета** — того, куда пользователь и так каждый день заходит руками.

---

## 1. Шаг 0 — определи ситуацию доступа (развилка)

Не гадай — проверь. Узнай у пользователя точное название сервиса, найди страницу «для разработчиков / API / docs» (WebSearch/WebFetch). Дальше одна из трёх ситуаций:

| Ситуация | Признак | Ветка |
|----------|---------|-------|
| **A. Есть открытый API** | Есть дока «как подключиться программой» (Ozon, WB, Т-Банк, YooKassa, Telegram) | → §2 |
| **B. API есть, но кривой** | Дока неполная, часть операций только в личном кабинете, примеры устарели | → §3 |
| **C. API нет вообще** | Только личный кабинет через сайт (частый случай у российских сервисов) | → §4 |

Если не понял, какая ситуация, — так и скажи пользователю: «Проверю, есть ли у [сервиса] открытый API». Не притворяйся, что знаешь.

---

## 2. Ветка A — есть открытый API

Самый простой случай.

1. Найди и прочитай документацию API (дай её себе через WebFetch / чтение страницы).
2. Разберись с **аутентификацией**: ключ в заголовке? OAuth? Где пользователь берёт ключ (обычно в настройках кабинета).
3. Отбери endpoint'ы **под конкретные задачи пользователя** (заказы, остатки, цены — не «весь API», а нужное).
4. Собери CLI → §5.

---

## 3. Ветка B — API есть, но неполный

Гибрид A и C.

1. Всё, что задокументировано, собери по докам (как в §2).
2. Недостающие операции (те, что живут только в личном кабинете) добери реверсом (как в §4).
3. Склей обе части в один CLI — для пользователя это единый инструмент, ему всё равно, что под капотом два источника.

---

## 4. Ветка C — API нет: реверс через браузер

Идея простая: сайт как-то же показывает данные в личном кабинете — значит, он сам обменивается ими со своим сервером. Мы этот обмен **подсматриваем** и повторяем.

### Как снять «скрытый API»

1. **Открой личный кабинет пользователя в браузере с активной сессией.**
   - **Базовый путь (работает у всех):** пользователь открывает кабинет в своём обычном браузере, где уже залогинен, и жмёт `F12` → вкладка **Network**.
   - **Если у агента есть браузерные инструменты** (MCP-подключение к браузеру с методами вида `navigate` / `read_page` / `read_network_requests`) — быстрее: агент сам открывает страницу и читает запросы, пользователю не надо ничего копировать. Предпочтительно подключение к **реальному браузеру пользователя** — там уже есть авторизация. Встроенный браузер тоже подойдёт, но сессию придётся поднимать заново.
2. **Пощёлкай нужный раздел** («Мои заказы», «Диалоги», «Товары»). В момент клика браузер шлёт запросы серверу.
3. **Сними запросы.** Ручной путь (основной): пользователь щёлкает правой кнопкой на нужную строку запроса → **Copy → Copy as cURL** и вставляет получившуюся строку в чат — агент её разберёт. Если браузерные инструменты подключены, агент читает запросы сам (получит URL, метод, заголовки, тело, ответ).
4. **Отдели настоящий API от вёрстки.** Нас интересуют **XHR/fetch к бэкенду** (обычно возвращают JSON), а не загрузка картинок, шрифтов и скриптов. Фильтруй по типу и по тому, где реально лежат нужные данные.
5. **Разбери обмен** по каждому нужному запросу:
   - базовый URL API и путь endpoint'а;
   - как передаётся **авторизация** (cookie? `Authorization: Bearer <token>`? CSRF-токен в заголовке?);
   - формат **тела запроса** и **ответа** (структура JSON, ключевые поля);
   - пагинация (offset/cursor), сортировка, фильтры;
   - коды и формат **ошибок**.
6. **Задокументируй найденное** — мини-спека endpoint'ов (метод, URL, что принимает, что отдаёт). Это фундамент CLI; без неё ты соберёшь инструмент «на память» — а это запрещено.

### Важное про токен

Часто токен живёт в cookie или `localStorage` и **протухает**. Сразу продумай, как его обновлять (перелогин / refresh-запрос), иначе CLI будет работать один час и умирать. Токен — в `.env`, не в код.

---

## 5. Сборка CLI — под стек проекта

1. **Определи стек проекта** и собери CLI на нём (инструмент должен лечь в кодовую базу без чужеродных зависимостей):
   - есть `package.json` → Node/TypeScript;
   - есть `pyproject.toml` / `requirements.txt` → Python;
   - непонятно / вне проекта → Python по умолчанию.
2. **Форма CLI, удобная агенту:**
   - одна команда = одна задача (`orders list`, `price update`);
   - вывод в **JSON** (флаг `--json`) — чтобы агент читал машинно;
   - `--help` с описанием команд — чтобы агент понимал, что инструмент умеет;
   - ключ/токен из `.env`, не хардкод.
3. **Учти российские особенности данных** (кодировка, даты/суммы, ИНН/КПП с нулями, rate limit) — `references/rossiyskie-osobennosti.md`.
4. **Перевод снятого запроса в код** — шпаргалка `references/curl-to-cli.md`.

### Отдельный случай: у программы есть открытые исходники

Всё выше — про **закрытый облачный сервис**, где кода мы не видим и единственный источник правды — запросы браузера. Но если автоматизировать надо программу с **открытым исходным кодом** (десктопный редактор, open-source утилита), ситуация другая: там есть готовые инструменты, которые собирают CLI прямо по коду — разбирают внутренности и генерируют команды автоматически. Поищи такой инструмент, прежде чем писать руками: на открытом коде он экономит часы. Для закрытого SaaS он бесполезен — анализировать нечего.

---

## 6. Проверка — одна реальная команда

Не верь коду на слово — выполни один настоящий вызов (например, «покажи последние 5 заказов»). Вернулись данные → инструмент живой. Ошибка → читай текст ошибки и чини по нему (частые причины — протух токен, сменился формат ответа, rate limit).

---

## 7. Skill для агента — чтобы звал сам

Инструмент готов, но агент пока не знает, когда его звать. Сделай **короткий Skill к собранному CLI**: по каким фразам звать («покажи мои заказы», «обнови остатки»), пара примеров команд, на что обратить внимание. Тогда на человеческую фразу агент сам вызовет нужную команду.

Если в системе есть скилл-конструктор (`skill-creator` и подобные) — сделай через него. Если нет — напиши `SKILL.md` руками: заголовок с `name` и `description` (описание = когда звать, по каким фразам), дальше список команд с примерами. Положить в `~/.claude/skills/<имя>/SKILL.md`.

---

## 8. Куда писать находки

- **Метод** (эти шаги) — уже здесь, в скилле. Не дублируй.
- **Конкретику по сервису** (реальные endpoint'ы, формат токена, обнаруженные грабли) — в заметки того проекта, где строим на основе сервиса: `docs/`, `knowledge/` или любая папка с документацией. Разобрал — сразу дописывай, чтобы в следующий раз не снимать заново.

⚠️ **Эти заметки — приватные.** В них попадают адреса внутренних endpoint'ов и структура авторизации конкретного аккаунта. Держи их в приватном репозитории проекта и не публикуй. Сам метод (этот скилл) публичный — находки по сервисам нет.

---

## Референсы (читать точечно под шаг)

- `references/rossiyskie-osobennosti.md` — странности данных у российских сервисов и как их лечить.
- `references/curl-to-cli.md` — как из снятого запроса собрать код CLI.