用途:诊断 GPUI 窗口布局故障,如元素消失、内容被裁剪、尺寸错误、flex 布局异常与溢出。
主要能力:提供快速诊断流程(添加高亮调试 div 探针、构建并截图、读取截图判断容器是否正常),常用探针写法如 .child(div().h(px(50.)).w_full().bg(gpui::red())),诊断后需移除探针,不应提交。总结了常见 flex 失败模式,例如 flex 列中 overflow_hidden() 下内容区因 min-height auto 无法收缩而挤掉固定高度元素,修复方式是给可扩展内容区加 .min_h_0() 或 .min_h(px(0.));规范的可滚动加固定模式为 .child(div().flex_1().w_full().min_h(px(0.)).child(main_content))。列出常见错误与症状,如缺少 min_h_0()、缺少 overflow_hidden()、给只需 flex_1() 的包装加 flex()+flex_col()、对嵌套 flex 子项用 h_full()。
布局转储:通过 stdin JSONL 协议触发,例如 {"type":"debug.layout_dump","window":"ai","path":"./target/layout_ai.json"},可选 ids、include_tree、include_by_id、pretty 字段,stdout 返回确认。转储 JSON 含 schema_version、window、scale_factor、tree 与 by_id,节点 ID 来自 .id("name") 或 @node:123。文档另列实现挂点与原子写文件示例。
适用场景:AI 窗口输入区等元素的不变量断言,如 ai-input-area 高度宽度大于 0、ai-composer 高度等于 36px。
限制:布局转储为设计规格,需修改 GPUI crate 的 TaffyLayoutEngine 才能实现;缺失功能、收费与平台信息暂未提供。