AdaTile-MCP v1.0

Адаптивный препроцессорный слой нарезки изображений высокого разрешения (MCP) для целевой модели DeepSeek deepseek-v4-flash-vision-exp. По шестинедельному плану «Руководства по построению проекта AdaTile-MCP (v1.2)» выполнены все фазы 0–5. Прогресс и фактические данные — в STATE.md, актуальный список обнаруженных проблем — в KNOWN_ISSUES.md.

Шестиуровневый конвейер (pipeline_v1)

L1 быстрый канал (magic bytes / ленивое декодирование / понижение разрешения при превышении лимита / прямая отправка маленьких изображений) → L2 салиентность (спектральный остаток, CPU по умолчанию, опционально U²-Netp, деградация по тайм-ауту Watchdog) → L3 адаптивная нарезка (связные компоненты / предварительное распределение бюджета / выбор непрерывных блоков / вариант document fine) → L4 сборка и загрузка (конвейерное кодирование тайлов на уровне tile с последующей загрузкой, трёхуровневый кэш, шесть жёстких проверок соответствия, цепочка деградации) → L5 потоковый вызов (принудительный вывод json_object, TTFT в двух измерениях, повторные попытки и глобальный запасной вариант) → L6 объединение на основе правил (IOU>0.3 и одна метка → общий bbox).

Related MCP server: image-tiler-mcp-server

Описание поведения при деградации

Базовые показатели качества и задержки (фактические измерения, подробнее в experiments/*.json)

• Первичная обработка: p95 = 1116 мс (включая реальную загрузку) / при попадании в кэш = 134 мс; TTFT 847 мс / 613 мс; 10 параллельных запросов — 100 % успех.

• Сравнение и абляция четырёх вариантов Phase 5: experiments/phase5_results.json

Требования к окружению

• Python 3.11+ (внутри проекта .venv — 3.13)

• Переменная окружения DEEPSEEK_API_KEY (получить на платформе DeepSeek)

• Активация venv в Windows/Git Bash: source .venv/Scripts/activate

• На новой машине настройка одной командой: setup.bat (Windows) / setup.sh (macOS/Linux) — см. следующий раздел

Подключение с нуля (новая машина / любой агент)

.venv и ключ не распространяются вместе с репозиторием; на новой машине достаточно 5 шагов:

1. Установить Python 3.11+ (при установке в Windows отметьте "Add to PATH").

2. Получить код: git clone https://github.com/Mutton-hub/adatile-mcp.git (или скопируйте этот каталог без .venv).

3. Установить окружение: в корне проекта выполнить setup.bat (Windows) или ./setup.sh (macOS/Linux) — автоматически создаётся .venv и устанавливаются все зависимости из requirements.txt.

4. Настроить ключ: задать переменную окружения DEEPSEEK_API_KEY, либо скопировать .env.example в .env и заполнить (выберите один из двух вариантов; .env уже исключён через .gitignore).

5. Зарегистрировать MCP: настройте конфигурацию агента — как в таблице ниже — указав на абсолютный путь к run.bat (Windows) / run.sh (Unix) в вашем локальном репозитории; после перезапуска сессии сначала вызовите adatile_status для самопроверки.

Если на одной машине подключаются несколько агентов, достаточно повторить шаг 5 (каждый клиент настраивается отдельно); окружение и ключ общие.

Регистрация MCP — подходит для любого локального агента/harness

Сервер — стандартный MCP (по умолчанию stdio; http/sse опционально); могут подключаться следующие клиенты. Порядок определения ключа: переменная окружения DEEPSEEK_API_KEY → файл .env в корне проекта (скопируйте .env.example в .env и заполните — удобно для клиентов, где сложно задавать переменные окружения).

Общая форма для всех клиентов с поддержкой stdio MCP. Замените <repo> на фактический абсолютный путь после клонирования/получения репозитория (при пути с китайскими символами или пробелами обязательно используйте абсолютный путь):

{
  "mcpServers": {
    "adatile-mcp": {
      "command": "<repo>\\run.bat",
      "args": []
    }
  }
}

Лаунчер run.bat автоматически находит venv (на macOS/Linux используйте <repo>/run.sh). Можно также напрямую указать <repo>/.venv/Scripts/python.exe + server.py.

Пример конфигурации уровня проекта для ZCode (<repo>/.zcode/config.json, после клонирования распространяется в составе репозитория):

{
  "mcp": {
    "servers": {
      "adatile-mcp": {
        "command": "C:\\path\\to\\cloned-repo\\run.bat",
        "args": []
      }
    }
  }
}

Использование после подключения (любой агент/harness)

1. Настройте ключ: задайте переменную окружения DEEPSEEK_API_KEY или скопируйте .env.example в <repo>/.env и заполните его (.env исключён через .gitignore, поэтому не попадёт в версию контроля; adatile_status позволит проверить, что ключ готов).

2. Зарегистрируйте MCP-сервер (таблица выше) и перезапустите сессию клиента.

3. Сначала вызовите adatile_status (ноль API-вызовов, ноль затрат), чтобы подтвердить настройку ключа и локальные возможности L1–L6.

4. Затем вызовите analyze_high_res_image, передав image_path (локальный абсолютный путь) и task_hint.

5. Превалирую используйте merged_answer; bbox в objects/tile_details можно использовать для точного позиционирования.

6. Для уточняющих вопросов по тому же изображению просто повторно вызовите тот же image_path — внутренний трёхуровневый кэш сработает автоматически, управлять file_id вручную не нужно.

Пример HTTP-режима (контейнер/remote harness):

./run.sh --transport http --host 0.0.0.0 --port 8765
# MCP endpoint: http://<host>:8765/mcp

После подключения сначала вызовите adatile_status (ноль API-вызовов), чтобы проверить настройку ключа и локальные возможности, затем вызывайте analyze_high_res_image.

Инструмент: analyze_high_res_image

Возвращает: merged_answer, objects (разбор по возможности), tile_details (включая bbox и file_id), latency_ms, token_usage, upload_stats, route (direct_pass / tile_pipeline).

Часто используемые команды

# 生成测试集 A（50 张 4K 合成图 + ground_truth.json）
.venv/Scripts/python.exe experiments/cases/gen_set_a.py --n 10 --seed 42

# Phase 0 校准实验（先跑一票否决用例！）
.venv/Scripts/python.exe experiments/run_phase0.py --cases TC-0.1.8 TC-0.3.1 TC-0.4.2
.venv/Scripts/python.exe experiments/run_phase0.py --list        # 查看全部用例
.venv/Scripts/python.exe experiments/run_phase0.py --full        # 含重型用例
.venv/Scripts/python.exe experiments/run_phase0.py --rounds 10   # TTFT 轮数控制费用

# 本地自检（无 API 调用）
.venv/Scripts/python.exe -m pytest tests/test_local.py -q

# stdio 端到端冒烟测试（真实子进程 + 官方 MCP SDK，零 API 调用）
.venv/Scripts/python.exe tests/stdio_smoke.py

System Prompt на стороне агента (шаблон B, разденом 3.3 руководства)

当用户上传高分辨率图像（总像素 > 64 万）时：
1. 调用 analyze_high_res_image 工具，传入 image_path 和 task_hint（上传与切片由工具自动经 Files API 完成）；
2. task_hint：文字识别→"ocr"；全景描述→"describe"；具体元素→"detect"；
3. 优先使用 merged_answer；tile_details 中的 bbox 可精确定位；
4. 同一张图的追问请复用工具（内部缓存自动命中）；
5. 禁止直接将原图 base64 传给 VLM——必须走本工具，否则细节丢失。

Поведение при деградации (Phase 0)

• L1 — повреждение / неподдерживаемый формат → структурированная ошибка {stage:"L1", reason:...}, путь деградации отсутствует

• Маленькое изображение (≤640 000 пикселей) → DirectPass single direct transfer

• Files API недоступен → у основного варианта пока нет автоматической деградации (в Phase 3 реализуется цепочка деградации с полным инлайном)