18 — MCP / Agent probe (Phase 0)

Статус: Phase 0 (Foundation API). Даёт AI-агенту структурированный доступ к live UI в виде JSON — без парсинга Console. MCP wrapper (регистрация tools) — отдельная, development-only фаза и не входит в этот пакет.

Что это такое

SusUiProbe — тонкий C#-фасад над существующей диагностикой. Он возвращает JSON-строки и по умолчанию не пишет в Console (агент парсит возвращаемое значение, а не логи). Компилируется только под UNITY_EDITOR || DEVELOPMENT_BUILD — не попадает в release-плеер.

API

Runtime — Sharq.Core.Diagnostics.SusUiProbe:

Метод	Возвращает
GetTreeJson(VisualElement root, int maxDepth = 10, bool emitToConsole = false)	плоский JSON-массив узлов: depth,type,name,classes,sus,children,w,h,x,y,text?,hidden?,invisible?,pickable?
GetPropsJson(SusComponent component, bool emitToConsole = false)	{ type, name?, visualState?, <propName>: value, … } для всех публичных Prop<T>
GetPropsJson(VisualElement root, string nameOrType, bool emitToConsole = false)	то же, после поиска компонента по #name или имени типа; { "error":"not found" }, если не найден
GetHealthJson(VisualElement root, bool emitToConsole = false)	{ totalElements, susComponents, totalChildren, maxDepth, anomalies:[] }

Editor — Sharq.Core.Editor.Diagnostics.SusUiProbeEditor:

Метод	Возвращает
ValidateSetupJson()	{ ok:bool, issues:[ { severity, category, message, fix? } ] } (обёртка над SusSetupValidator, без Console/dialog)

Пример

using Sharq.Core.Diagnostics;

var root = susApp.ScreenHost;               // or UIDocument.rootVisualElement
string tree   = SusUiProbe.GetTreeJson(root);
string health = SusUiProbe.GetHealthJson(root);
string props  = SusUiProbe.GetPropsJson(root, "HomeScreen");
// in the editor:
string setup  = Sharq.Core.Editor.Diagnostics.SusUiProbeEditor.ValidateSetupJson();

Через Unity MCP (execute_code) агент получает UI-дерево за один вызов, без read_console и без фильтрации по [LA]/[FP].

Связь с существующей диагностикой

• ScreenAudit (Runtime/Diagnostics) — дамп в Console для человека (сохранён для ручной отладки).
• SusDiagnostics (в downstream UI-пакетах) — JSON-дампы для панели диагностики; SusUiProbe повторяет эту логику в core (core не зависит от downstream UI-пакетов), поэтому фасад живёт в бесплатном пакете.
• SusSetupValidator (Editor) — источник для ValidateSetupJson.

Дальше (следующие фазы)

• Phase 1: ✅ DONE (development-only, вне этого пакета). Tools sus_ui_tree / sus_ui_props / sus_ui_health / sus_setup_validate автоматически регистрируются в CoplayDev MCPForUnity через [McpForUnityTool(..., Group="ui")] + HandleCommand(JObject), оборачивая SusUiProbe. Ссылка на Coplay живёт только в этой development-only editor-сборке; core остаётся без зависимостей.
• Phase 2: act-tools (router.push, ui.set_prop, ui.click, sharq.regen).
• Phase 3: Docs MCP + Storybook.

DoD Phase 0

• [x] Фасад SusUiProbe с выключенной по умолчанию Console (emitToConsole=false).
• [x] EditMode smoke: SusUiProbeTests — probe возвращает парсящийся JSON.
• [x] Phase 1: SUS MCP tools в development-only editor-сборке (вне этого пакета).
• [ ] Прогнать в Unity: убедиться, что probe+tools компилируются и тесты зелёные (нужен Editor).