18 — MCP / Agent probe（Phase 0）

状态：Phase 0（Foundation API）。让 AI agent 以 JSON 形式结构化访问实时 UI —— 无需解析 Console。MCP wrapper（工具注册）是独立的、仅限开发环境的阶段，不属于本包的一部分。

这是什么

SusUiProbe 是建立在现有诊断能力之上的一个轻量 C# 外观（façade）。它返回 JSON 字符串， 并且默认不写入 Console（agent 解析的是返回值，而不是日志）。 它仅在 UNITY_EDITOR || DEVELOPMENT_BUILD 下编译 —— 不会出现在正式发布的播放器中。

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)	对所有公开 Prop<T>：{ type, name?, visualState?, <propName>: value, … }
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），agent 一次调用即可获取 UI 树，无需 read_console， 也无需按 [LA]/[FP] 过滤。

与现有诊断的关系

• ScreenAudit（Runtime/Diagnostics）—— 面向人的 Console 转储（保留用于手动调试）。
• SusDiagnostics（位于下游 UI 包中）—— 供诊断面板使用的 JSON 转储；SusUiProbe 在 core 中重复了这一逻辑（core 不依赖下游 UI 包），因此该外观位于免费包中。
• SusSetupValidator（Editor）—— ValidateSetupJson 的数据来源。

后续（未来阶段）

• Phase 1：✅ 已完成（仅限开发环境，位于本包之外）。工具 sus_ui_tree / sus_ui_props / sus_ui_health / sus_setup_validate 通过 [McpForUnityTool(..., Group="ui")] + HandleCommand(JObject) 自动注册到 CoplayDev MCPForUnity，并封装 SusUiProbe。对 Coplay 的引用只存在于这个仅限开发环境的 editor 程序集中； core 保持无依赖。
• Phase 2：act 工具（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 工具位于仅限开发环境的 editor 程序集中（本包之外）。
• [ ] 在 Unity 中运行：确认 probe+tools 能编译且测试通过（需要 Editor）。