geo-sleuth: скилл, который определяет место по фотографии

geo-sleuth — это агент-скилл, который определяет место съёмки по фотографии и показывает весь ход рассуждений. Он оформлен по стандарту Agent Skill: одна папка с файлом SKILL.md и Python-скриптами. Скилл работает с Claude Code, Codex, Cursor, Gemini CLI, OpenCode и GitHub Copilot, а также с любым другим агентом, который читает SKILL.md и умеет запускать команды в терминале. Проект открыт под лицензией MIT и собрал больше четырёх тысяч звёзд на GitHub.

Сценарий использования выглядит так. Вы даёте агенту фото и просите найти, где сделан снимок. Через некоторое время агент возвращает координаты с радиусом погрешности, направление камеры и контрольное изображение на спутниковом снимке. Метод работает даже когда на фото нет ни одной надписи: геометрия OpenStreetMap, данные о рельефе, спутниковые снимки и панорамы улиц несут поиск сами по себе.

Геометрия вместо догадок

Главный принцип проекта — считать, а не угадывать. Расстояние между опорами моста превращается в линейку для оценки удалённости. Тени дают азимут и время суток. Линия горного хребта становится отпечатком, который можно сверить с данными о высотах.

Дисциплина доказательств устроена строго. Каждое утверждение в отчёте обязано ссылаться на команду, которая реально выполнялась в сессии, и на файл с её результатом. Численность населения или известность места доказательством не считаются. Исключить кандидата можно только на основе прочитанных или вычисленных данных.

Разделение ролей тоже необычное: скрипты ранжируют, решает модель. Около двадцати узких скриптов ищут, считают и сортируют кандидатов. Модель выбирает лишь из нескольких лучших вариантов и предлагает гипотезы. Ответ всегда содержит координаты с радиусом ошибки, направление камеры, контрольное изображение и уровень уверенности.

Три разобранных кейса

В репозитории опубликованы три истории с фотографиями без GPS и без надписей. Для каждого кейса указано, что скилл прочитал на снимке, как сужал поиск и насколько попал.

Рисовое поле и виадук (Китай, точность ±2 м). На фото печь у убранного рисового поля, виадук и гора. Опоры на виадуке выдали электрифицированную железную дорогу. Скилл выгрузил из OpenStreetMap 27 335 участков железнодорожных мостов региона, посчитал для каждого горизонт по данным высот и оставил 171 точку. Затем он перебрал 14 372 позиции камеры и сравнил силуэты хребтов с фото, после чего наложил три лучшие линии на снимок и оставил одну. Финальный шаг: 17 опор виадука превратились в 17 азимутов, и равномерность расстояний между ними и дорогой дала точку с погрешностью ±2 м. Весь прогон занял около 72 минут.

Пустынный горизонт (Цинхай, 87 м). Дюна, голые горы и линии электропередач. Скилл прошёл сканированием вдоль всех ЛЭП четырёх провинций, но застрял: лучшие точки давали почти одинаковую ошибку. Причина нашлась в наклоне телефона на 1° — он сдвигает хребет у края кадра примерно на 10 пикселей. В скрипт подгонки добавили решение для крена камеры, и правильная точка сразу оторвалась от остальных. Слепой повторный прогон новым агентом завершился в 87 м от подтверждённой позиции за 32 минуты.

Вишня на улице Ванкувера (точность 3 м). Номера и уличная мебель указали на город, но кварталов в нём около десяти тысяч. Кандидатов дали открытые данные города о деревьях: 1095 крупных цветущих вишен сошлись в 97 кварталах. Тени машин и уклон улицы сократили список, сравнение с панорамами 2009 и 2024 годов подтвердило ответ. Слепой прогон занял 53 минуты и попал в 3 м.

Авторы честно оговаривают: обе слепые проверки — это регрессионные тесты, а не оценка точности на незнакомых фото. Эти снимки уже решали раньше, и уроки вошли в скилл.

Как устроен скилл

Работа делится на три слоя.

Набор скриптов покрывает весь конвейер: чтение EXIF, OCR, обратный поиск по картинке в Baidu и Yandex, таблицы улик (телефонные коды, сторона движения, префиксы номеров), запросы к OpenStreetMap, работа с данными о высотах и силуэтами хребтов, расчёт позиции камеры, сравнение наземных снимков через DINOv2 и SIFT, панорамы Baidu и Google Street View. Полный список с источниками данных — в справочнике скилла.

Установка и требования

Установка одной командой через официальный CLI:

npx skills add Oldcircle/geo-sleuth

CLI спросит, какие агенты должны получить скилл. Альтернатива — скопировать папку skills/geo-sleuth вручную: каталог ~/.agents/skills/ читают Codex, Cursor, Gemini CLI, OpenCode и GitHub Copilot, а для Claude Code подойдёт символическая ссылка в ~/.claude/skills/.

Требования: Python 3.10+, uv, curl и агент с доступом к терминалу. Перед первым запуском стоит попросить агента выполнить doctor.py из папки скриптов — он проверит окружение и браузер. Обратный поиск по картинке требует Chrome или Playwright Chromium. Скрипты с моделями при первом запуске скачивают веса объёмом около 2,4 ГБ и умеют работать на CUDA, MPS и CPU.

Развитие проекта

В планах: операторские тесты для скриптов рельефа, Google Lens как третий поисковик по картинке, CI на Linux и Windows и публичный набор слепых тестов с итоговой метрикой точности.

Правила для контрибьюторов изложены в CONTRIBUTING.md и заслуживают внимания сами по себе. Изменение ядра принимают только если оно чинит реальное фото, которое раньше не решалось, и не ломает остальные случаи. Эталонный пример такого изменения — крен камеры из кейса с пустыней: правило сделали общим с ограничением в 1°, воспроизвести эффект до и после можно двумя командами из примера в репозитории.

Отдельная строка в README касается ответственного использования: запускать скилл можно только на своих фотографиях или на снимках, которые вы имеете право анализировать. Искать людей, не давших согласие, запрещено.