参考客户端工具

Mafia.Server.ReferenceClient

Легковесный клиент для Mafia Server: HTTP, WebSocket, MCP (stdio) и автономный агент.

Что это дает

• Быстрый запуск без правок C#.
• Один файл appsettings.json для всех настроек.
• Простые режимы: sample, mcp, agent.
• Настройка роли и поведения бота через конфиг.

Быстрый старт

1. Поднимите backend.
2. Заполните tools/Mafia.Server.ReferenceClient/appsettings.json.
3. Запустите проект.

sample:

dotnet run --project tools/Mafia.Server.ReferenceClient

mcp:

dotnet run --project tools/Mafia.Server.ReferenceClient -- --mode mcp --config tools/Mafia.Server.ReferenceClient/appsettings.json

agent:

dotnet run --project tools/Mafia.Server.ReferenceClient -- --mode agent --config tools/Mafia.Server.ReferenceClient/appsettings.json

Простой appsettings (новая схема)

{
  "server": {
    "url": "https://localhost:7230"
  },
  "auth": {
    "mode": "login",
    "user": "alice",
    "password": "alice-pass",
    "token": ""
  },
  "bot": {
    "role": "joiner",
    "displayName": "Player",
    "roomName": "Reference Room",
    "roomId": "",
    "playersCount": 4,
    "preset": "Party",
    "style": "balanced",
    "autoReady": true,
    "autoStartIfHost": true,
    "maxRuntimeSeconds": 180
  },
  "ai": {
    "enabled": false,
    "apiKey": "",
    "quality": "cheap",
    "baseUrl": "https://api.openai.com",
    "timeoutMs": 5000,
    "temperature": 0.2,
    "maxTokens": 300
  }
}

Опционально: расширенные настройки без дополнительных команд

• Если рядом с appsettings.json есть файл appsettings.advanced.json, он автоматически накладывается поверх базового конфига.
• Это не требует copy, rename и не требует отдельного --config.
• Базовый сценарий остается тем же: настроил appsettings.json и запустил.
• В репозитории appsettings.advanced.json заполнен безопасными дефолтами и не ломает базовый старт.

Что важно по авторизации

• auth.mode = "login": используется auth.user + auth.password.
• auth.mode = "token": используется auth.token.
• В клиенте больше нет useDevAccessToken и нет выдачи debug/admin токенов.

Как управлять поведением бота

• bot.role: host или joiner.
• bot.style: quiet, balanced, aggressive.
• ai.enabled = false: rule-based решения (без LLM затрат).
• ai.enabled = true: LLM режим.

Профили качества модели (ai.quality):

• cheap: gpt-4.1-nano для всего.
• balanced: nano по умолчанию + mini для голосования.
• high: gpt-4.1-mini для всех шаблонов.

Практический порядок для продакта:

• Начать с ai.enabled=false.
• Затем включить ai.enabled=true + quality=cheap.
• Поднимать до balanced/high только по результатам QA.

Настройки для prompt-инженера (без C#)

Для тонкой настройки можно добавить блок advanced:

• advanced.prompt.*: persona, стиль, цели, размер контекста.
• advanced.decisionPolicy.*: что LLM может делать в фазах, тайм-буферы, allow-list команд.

Контекст, который видит агент

Агент работает не "вслепую":

• читает актуальный snapshot комнаты,
• читает поток событий WS,
• хранит внутренний timeline решений и исходов,
• применяет command gate (валидность команды по фазе/состоянию).

MCP tools (player-only)

• auth_login
• rooms_list
• room_create
• room_join
• room_snapshot
• command_send
• ws_pull_events

Admin-инструменты в MCP surface не публикуются.

Документация

• Подробный гайд запуска: tools/Mafia.Server.ReferenceClient/INTEGRATOR_GUIDE.md
• Полный справочник полей: tools/Mafia.Server.ReferenceClient/APPSETTINGS_FIELD_GUIDE.md
• Пример overlay-конфига: tools/Mafia.Server.ReferenceClient/appsettings.advanced.json

Smoke тест

dotnet test src/Games/Mafia/Mafia.Server.Integration.Tests/Mafia.Server.Integration.Tests.csproj --filter ReferenceClient