Dice Chess Wiki

05 Бот-платформа — анонимный Bot API (дизайн)

5 min read

🤖 Бот-платформа — анонимный Bot API (дизайн)

Статус: черновик дизайна · 2026-06-28. Развивает ADR-0009 (форма Lichess, админ-токены для 4–5 команд) в открытую самообслуживаемую платформу. Решение вынесено в ADR-0010. Опирается на честность кубиков ADR-0008 и серверный авторитет фазы 3.

Цель. Сторонние команды и одиночки пишут своих Dice-Chess-ботов и тестируют их на нашей платформе — от «попробовать за 2 минуты» до «мощная арена соревнований ботов с разными режимами подключения, вплоть до облачных функций». Bot-API в форме Lichess у нас уже построен (ndjson event/game-стримы, REST-команды, токены, reference-bot, keep-alive); этот документ — про то, как открыть его наружу для произвольных авторов.

1. Две парадигмы подключения

Connect-in (Lichess)Submit-and-run (CodinGame / Battlecode / Kaggle)
Кто запускает ботаРазработчик (где угодно)Платформа в песочнице
Что даёт платформаAPI + токенSandbox + оркестратор матчей
Наша стоимость/рискНизкиеВысокие (запуск чужого кода, изоляция, CPU)
Сильно дляРазработки, casual, постоянного ботаЧестных турниров, лидербордов

Решение: connect-in — фундамент (у нас уже есть), submit-and-run — финальная амбиция (отдельный милстоун с песочницей, лесенка п.9). Доводим connect-in до полноценной открытой платформы; submit-and-run — когда понадобится честный «чемпионат без доверия к чужому always-on».

2. Идентичность — три тира

Расширяем Principal.Bot из ADR-0009 до трёх уровней доступа (одна Principal-система, не три account-системы):

  1. Анонимный / эфемерный — POST /bot/anon → временный токен на bot:anon:<uuidv7> (опц. ник). Ноль регистрации. Всегда unranked. Для разработки и теста. В духе anonymous-first (гости же играют HvH без аккаунта, ADR-0003).
  2. Зарегистрированный бот-аккаунт — durable bot:team:<team>:<name> (как в ADR-0009), upgrade-to-bot. Нужен для рейтинга/лидерборда (иначе результаты бессмысленны). Завязан на систему аккаунтов (лесенка п.5).
  3. Админ-токен (сейчас) — PLAY_BOT_TOKENS, для наших house/официальных ботов (greedy и т.п.).

Чистая линия: тестировать — без регистрации (unranked песочница); соревноваться за рейтинг — с регистрацией. Это и открыто, и сохраняет смысл рейтинга.

3. Анонимный доступ — POST /bot/anon

  • Минтит эфемерный Bearer-токен на bot:anon:<uuidv7>; опц. { "name": "..." } — display-лейбл, namespaced так, что аноним не может выдать себя за house/registered бота (anti-masquerade на уровне типа токена, как в ADR-0009).
  • Хранится в in-memory BotAuth-реестре (БД нет до п.4 Persistence); TTL + idle-eviction, чтобы анон-токены не копились.
  • Принципал помечен unranked — не несёт рейтингового веса, когда появятся рейтинги.
  • Сразу работает со всем существующим Bot-API: /bot/stream/event, вызвать house-бота, принять вызов, играть. → issue #41.

Защита от абьюза (открытость по определению): per-IP лимит на минт токенов и одновременные коннекты, TTL, кап одновременных игр на принципала, аккуратные 429. Тюнинг: локальная итерация разработчика — не троттлится; скрипт-спамер — троттлится. → issue #42.

4. Тестовый цикл (что аноним может уже на п.1)

Чтобы тестировать, боту нужен оппонент — до открытого лобби (п.3) есть два пути, оба работают на текущем сервере:

  • vs house-бот — прямой вызов POST /bot/challenge/house/greedy (наш always-on reference-bot на rpi). Бот принимает/играет.
  • Self-play — POST /games уже возвращает оба seat-токена; один процесс ведёт обе стороны (идеально для отладки своей стратегии). Документируем как «test mode».

Онбординг: reference-bot превращаем в forkable starter-kit — стратегия = одна явная замена (вызов движка), транспорт/стриминг не трогаешь; README-quickstart (anon-токен → PLAY_API_BASE_URL+BOT_TOKEN → запуск); пример self-play. → issue reference-bot#3.

5. Матчмейкинг (кратко; детали — в лобби-милстоуне)

  • Сейчас: прямой вызов (договорный матч) + self-play.
  • Лобби / open seeks (п.3): create-seek → список лобби → join, единое для guest/user/bot — боты и люди сами организуют партии; зрительский просмотр. Твоя идея «создал игру → она в лобби → другой подключился».
  • Авто-пул / арены — спаривание сервером; турниры с зеркальными костями (ADR-0009), Glicko-2 ладдер.

6. Где крутятся боты

  • Локально на машине разработчика — главный режим для теста. Указал токен + URL (play-api.jc.id.lv или LAN), играешь. Ноль инфры у нас, любой язык. (Внутри LAN — напрямую http://192.168.10.3:8040, в обход Cloudflare/AdGuard.)
  • Always-on (как наш reference-bot на rpi) — постоянный бот команды / house-боты / ладдер.
  • Облачная функция (Azure/AWS/GCP) — это смена транспорта. Наша модель — долгоживущие стримы (event+game ndjson), а serverless request/response с лимитом времени → стрим отвалится. Чтобы зашли функции, нужен webhook/poll-режим рядом со стримингом → п.8 Multi-mode connectivity. Цена: SSRF/ретраи/доступность URL бота. Для большинства тестов локальный запуск проще serverless в любом случае.

7. Честность и воспроизводимость — наши козыри

  • Provably-fair кости. Сервер коммитит хэш сид-сида в начале и раскрывает в конце (commit-reveal CSPRNG, ADR-0008) → сторонняя команда проверяет, что кости не подкручены против её бота. Для платформы чужих ботов это прямая фича доверия. Доведение (раскрытие сида + клиентская энтропия) — п.2, issue #13.
  • Детерминированный реплей по сиду. Сид + ходы → точное воспроизведение → бесценно для отладки чужого бота. Тот же милстоун.

8. Лесенка милстоунов (бот-хребет)

Полная лесенка — в 01 Дорожная карта и в milestones репо dicechess-play-api (capability-названия, хребет только там, без дублей по репо):

  1. Bot API: anonymous self-service ← делаем сейчас (этот документ)
  2. Provably-fair dice & deterministic replay
  3. Lobby, open seeks & spectating
  4. Persistence (Postgres play schema) — гейт для 5–6
  5. Accounts & registered bots
  6. Ratings & bot leaderboard (Glicko-2)
  7. Tournaments & arenas
  8. Multi-mode connectivity (serverless / cloud bots)
  9. Submit-and-run sandbox arena

Параллельно (вне хребта): HvH UX, Scale & edge split.

9. Что отложено

  • Durable идентичность/persistence (п.4) — пока всё in-memory; казуальная песочница (1–3) живёт без БД.
  • Рейтинги/лидерборды (п.6) — требуют аккаунтов (п.5) и Postgres (п.4).
  • Serverless/webhook (п.8) и submit-and-run (п.9) — после того, как connect-in-платформа обкатана.
  • Серверный «человек-vs-бот» на сайте — нужен клиентский флоу «бросить вызов боту» (HvBot сейчас = клиентский /play, фаза 1).

🔗 ADR-0010 Анонимные self-service боты · ADR-0009 Бот-API и турниры · ADR-0008 Честность кубиков — server CSPRNG + commit-reveal · 04 Фаза 3 — Human-vs-Human (дизайн) · 01 Дорожная карта

Graph View

Backlinks