Полная документация ниже — автоматически из репозитория cucumberian/spb-gorzdrav-skill (ветка main). Оригинальные материалы проекта распространяются на условиях его лицензии.

spb-gorzdrav — скилл для агента: API Горздрава СПб

Набор инструкций (skill) для LLM-агентов, который учит агента пользоваться
публичным REST API портала gorzdrav.spb.ru —
городского сервиса записи к врачам Санкт-Петербурга.

Три уровня работы:

1. Чтение — район → поликлиника (ЛПУ) → специальность → врач → свободные
   слоты → ссылка на запись. Без авторизации и без персональных данных.
2. Мониторинг — отслеживание появления новых талонов в цикле, по заранее
   заданным целям, с ретраями по кодам и бюджетом запросов.
3. Запись и отмена — полный цикл от имени пользователя: по ФИО + дате
   рождения (patient/search; полис ОМС — чтобы найти прикреплённые ЛПУ через
   oms/attachment/lpus?polisN=), appointment/create, контроль через
   GET /appointments, patient/update, appointment/cancel.

Уровень 3 возможен только по явной просьбе владельца данных, с обязательным
предупреждением о том, куда именно уходят персональные данные — провайдеру модели,
на которой работает агент, на эту машину и на портал, — и с подтверждением каждого
действия. Формулировка предупреждения — в SKILL.md, раздел 0.

Установка

Скилл совместим с агентскими средами, читающими каталог ~/.agents/skills
(Claude Code, DeepSeek Harness и т.п.):

git clone https://github.com/cucumberian/spb-gorzdrav-skill.git ~/.agents/skills/spb-gorzdrav

Зависимости: только curl (Linux/macOS; в Windows — curl.exe, помните,
что в PowerShell curl — алиас на Invoke-WebRequest). Python и jq не нужны,
скриптов и кода в скилле нет — только инструкции и curl-рецепты.

Структура

spb-gorzdrav/
├── SKILL.md                # правила, сессия/токен, рецепты, мониторинг, ошибки
├── reference/
│   ├── api.md              # read-эндпоинты: параметры, образцы ответов, errorCode
│   └── write-api.md        # ПДн-путь: полис, patient/search, create/cancel/update
├── README.md               # этот файл
└── LICENSE                 # MIT

Пример диалога

Пользователь: найди мне зубного врача на ближайшее время, я на
[адрес в Калининском районе].

Агент опрашивает API: ЛПУ района → стоматологии → специальности → врачи →
реальные свободные слоты (appointments), считает расстояние от дома и
отвечает списком: «стоматология N, пр. Большеохтинский 27 (~1 км) — свободен
06.10 в 09:15» + ссылка на портал с параметрами (район, ЛПУ, специальность,
врач). Персональных данных не потребовалось.

Пользователь: запиши меня к этому врачу сам.

Агент сначала показывает предупреждение: полис/ФИО уходят агенту, провайдеру
модели, на котором он работает, попадают в файлы на этой машине и в запросы на
портал, назад не забираются — и предлагает записаться самому по ссылке. После
явного согласия собирает минимум данных и показывает карточку, а не JSON:

Проверь, всё ли верно: Иванов И. И., 01.02.1990, полис оканчивается на
1111 · поликлиника на Н-ском пр., 10 · к терапевту, врач
Петров П. П. · приём 09.10, 17:20, кабинет 105.
Подтверждаешь?

После «да» записывает и обязательно сверяет результат со списком записей
портала. patientId, тела запросов и коды ошибок человек не видит: агент
переводит их на человеческий язык и показывает технические детали только по
явной просьбе.

Что внутри SKILL.md

• Раздел 0 «Персональные данные»: готовый текст предупреждения пользователю
  до запроса полиса/ФИО — с перечислением всех получателей (провайдер модели,
  эта машина, портал), требование явного информированного согласия, запрет просить
  СНИЛС, паспорт, пароль ЕСИА и коды из СМС, маскирование (полис — последние 4
  цифры, ФИО — инициалы), правила хранения и удаления, эхо-подтверждение перед
  create/cancel, dry-run первого прогона.
• Сессия и токен: сервер выдаёт токен заголовком token каждого ответа,
  клиент шлёт его обратно; ЕСИА для записи не нужна (esiaId: null).
• Два входа в данные: справочник (район → ЛПУ) и полис ОМС
  (oms/attachment/lpus?polisN= — прикреплённые ЛПУ одним запросом).
• id специальности уникален в пределах ЛПУ, глобален только ferId: в
  целях хранить ferId, локальный id резолвить на каждом цикле.
• Форматы appointmentId зависят от МИС поликлиники: живым обходом 14 ЛПУ
  получено 5 видов (<visitStart>|<id врача>, <врач>_<дата>_<время>_<кабинет>,
  компактная метка времени, просто число, дд.мм.гггг;чч:мм;<число>), шестой —
  <врач>_<дата>_<время> — только из вики ⚠️. Генерировать id самому запрещено,
  брать строго из appointments.
• Мониторинг появления талонов описан словами: цель, состояние между
  циклами, отслеживание новых слотов, ретраи по кодам, лимиты и стоп-условия —
  без кода.
• Карта errorCode с 615 (ретраить), 751 (уже есть активная запись —
  не сбой), 645, 660, requestId для техподдержки; правило «смотреть
  success, а не HTTP-код».
• Вежливость к городскому API: User-Agent, sleep 1, дефолтный интервал
  опроса ≥30 с, агрессивный режим только по явной просьбе и с автоостановкой.
• Как отдавать результат человеку: карточка подтверждения вместо тела запроса,
  запрет показывать JSON, имена полей API, patientId и коды ошибок (только по
  явной просьбе), перевод errorCode в человеческие формулировки, строка талона
  с днём недели, телефоном ЛПУ и ссылкой на Яндекс.Карты.
• Разметка непроверенного: пункты, взятые из документации и чужих клиентов,
  помечены ⚠️ и требуют перепроверки живым запросом.

Про персональные данные

• Предупреждение перед сбором данных обязательно и должно называть всех
  получателей: провайдер модели, на которой работает агент (текст диалога с полисом
  и ФИО уходит к нему в API), эта машина (файлы и логи) и портал (gorzdrav.spb.ru).
  Провайдера положено называть конкретно, а не «куда-то в облако»; удаление копии
  у провайдера — только по его процедуре, агент её не выполняет.
• Скилл сам ничего не хранит: если человек согласился, агент ведёт профиль
  пациента в одном локальном файле gorzdrav-profile.json с правами 600 вне
  репозиториев и удаляет его по просьбе.
• ФИО врачей в примерах — плейсхолдеры. В живой выдаче там настоящие имена и
  отчества: показывать их пользователю только в пределах нужного ответа и не
  сохранять в артефактах, логах и сниппетах.
• Данные пациента (полис, ФИО, дата рождения, patientId, телефон, email) не
  попадают в отчёты, имена файлов, сообщения коммитов и в ссылки, которые агент
  показывает человеку.
• Все примеры в скилле — с синтетическими значениями (patientId=1234567,
  Иванов И. И., someone@example.com).

Источники и благодарности

• Вики-описание API и клиент с записью по полису ОМС:
  egorantonov/gorzdrav
  (wiki,
  веб-клиент)
• Клиент мониторинга и автозаписи: cucumberian/gorzdrav_spb_checkbot
• Образцы ответов в reference/api.md сняты с API (реальные имена действующих
  лиц заменены).

Лицензия

MIT