把运行中的界面,
一层层拆开看。

3D 分层查看 iOS、macOS App 的视图层级,实时改属性、查布局问题,还能交给 AI 助手直接操作。

  • 免费使用
  • macOS 14 及以上
  • Apple 公证
  • 内置自动更新
  • v0.3.0
UILabel“京都”
UIView › UIResponder › NSObject
第 6 层
UIStackView 76 × 66
0 19 0 0
76 × 47
原点0, 0 窗口坐标20, 186
NodeID
#36
text
京都
font
.SFNS-Heavy 40.0
textColor
#FFFFFF 100%

这一层的读数取自 App 本身。点模型里的其他层,读数跟着换。

12月5日 - 12月10日
京都 · 日本,5 晚。古城漫步、地道美食与山海风光,一次说走就走的旅行。
美食人文徒步
预算 (SwiftUI)
正常
35%已花费
交通¥1,634
住宿¥1,376
餐饮¥860
门票¥430
行程安排
第 1 天抵达 · 入住町家下午逛锦市场,晚上祇园散步
第 2 天清水寺与二年坂
30°
京都
日本 · 5 晚

拖动旋转,点任一层看读数

不改一行代码,启动就能调试

选一个 App 点“启动”,Lumen 注入采集端、启动并自动连上。日志、检查器、画布也一起升级了。

0.3.0 新版本
演示视频
  1. 启动调试
  2. 3D 分层与路径栏
  3. 几何读数卡
  4. App 自定义属性
  5. 应用日志

“启动调试”窗口(⌘N)列出模拟器中的 App、Mac 应用、iOS 安装包与 USB 真机,启动过程逐步显示,成功后自动连接。

  • 模拟器未启动的模拟器自动开机,也可以先安装 .app 再启动
  • iOS 安装包Apple 芯片的 Mac 上直接运行 .ipa,可按 iPhone 机型尺寸运行
  • 真机用 Xcode 中登录的 Apple ID 自动重签安装,免费账号即可,到期前提醒续签
  • Mac 应用Hardened Runtime 的 App 自动重签副本,原 App 不改动
画布工具条与路径栏
工具条贴在画布上缘,底部路径栏从根到所选节点逐段可点;按遮罩裁剪,网页、Metal、Lottie 内容完整显示。
层级深度与聚焦
⌥⌘1…⌥⌘5 按窗口与控制器展开;聚焦到某个节点只看它的子树,Esc 退出;按 App 记住展开状态。
遮罩诊断
审计找出被 mask 整个挡住或只露出一小部分的视图,并说明原因与修法。
断线保留现场
App 退出或崩溃后,最后的层级、详情与纹理继续可看,可另存为快照;App 回来自动切回实时。
控制台补全
方法名预测与 Tab 补全,参数按签名逐个填写;返回的对象可以继续调用。
三种界面语言
简体中文、English、繁體中文随时切换;外观可跟随系统、浅色或深色。

看清、改动、诊断,一个窗口完成

上面的模型照着这一屏画。连上运行中的 App,层级、3D 画布与检查器同屏,指向任一标注看它对应的部件。

Lumen 浅色界面:左侧层级树选中 UILabel“京都”,中间 3D 画布把“京都”行程页一层层展开,右侧几何读数卡显示 76 × 47 与四边距离,底部状态栏显示加载完成 0.60 s、190 个节点 Lumen 深色界面:3D 分层展开“京都”行程页,选中 UILabel“京都”,几何读数卡 76 × 47
13D 画布图层逐层展开层间距可调缩放 69%缩放 74%
2层级树190 个节点UILabel “京都”
3几何读数卡76 × 47父 UIStackView 76 × 66上 0 左 0右 0 下 19
4属性检查器UILabel 12 项,可直接改text 京都font .SFNS-Heavy 40.0
5路径栏… › UIStackView › UILabel
6状态栏加载完成 0.60 s加载完成 0.59 s190 个节点
  1. 1
    3D 画布图层逐层展开,层间距可调
  2. 2
    层级树190 个节点,选中 UILabel “京都”
  3. 3
    几何读数卡76 × 47,下边距 19
  4. 4
    属性检查器UILabel 12 项,可直接改
  5. 5
    路径栏… › UIStackView › UILabel
  6. 6
    状态栏加载完成 0.60 s加载完成 0.59 s,190 个节点
  • iOS / iPadOS
  • tvOS
  • visionOS
  • macOS AppKit
  • SwiftUI

选中任意视图,属性立刻可改

检查器按类分组列出属性,改完 App 里马上生效,不用重新编译。右边就是那层“京都”,试着改一下。

  • 拖动微调数值、取色、改文本,修改可撤销
  • 看清来历继承链、所属 ViewController、实例变量名
  • 调用方法在控制台调用节点、layer 或 VC 上的方法
UILabel #36
京都
日本 · 5 晚
font
40.0
alpha
1
textColor
$ lumen set 36 UIView.alpha 1

一键审计,问题直接标在画布上

文字截断、对比度不足、触控区域过小、遮挡、无障碍缺失,逐条列出并定位到视图。点右侧一条,画布上对应的框会亮起。

  • 点击诊断某一点命中了谁、其他视图为何被跳过
  • 约束诊断Auto Layout 歧义与优先级一目了然
  • 可进 CI导出报告,按阈值判定构建失败
审计
12月5日 - 12月10日
美食 人文 徒步
行程安排
第 1 天
抵达 · 入住町家
下午逛锦市场,晚上祇园散步
截断
对比度
触控区域

让 AI 助手亲眼看到你的界面

内置 MCP 服务,Claude Code、Codex、Cursor 能读层级、截图、审计、改属性,再回到源码修复。

  • 一行命令接入Claude Code、Codex、ChatGPT、Cursor
  • 选择器查询UIButton[text*="登录"]:visible
  • 命令行同样可用脚本与 CI 直接调用 lumen

三步连上你的 App

采集端 LumenServer 只进 Debug 构建,发布包里没有它。

  1. 下载安装

    按芯片选择安装包,拖进「应用程序」。不确定芯片时看「关于本机」。

  2. 接入 App

    四种方式任选:SPM、CocoaPods、一键脚本,或不改工程直接注入启动。Swift、Objective-C、SwiftUI、AppKit 都支持。

  3. 打开 Lumen

    启动被调试的 App,Lumen 自动发现并连接。模拟器、Mac App、USB 真机都无需配置。

Xcode 中 File → Add Package Dependencies,输入 https://github.com/wangwanjie/Lumen.git,把 LumenServer 加到 App target;或写进 Package.swift:

Package.swift
.package(url: "https://github.com/wangwanjie/Lumen.git", from: "0.3.0"),
// target 依赖
.product(name: "LumenServer", package: "Lumen"),

启动时调用:

Swift
#if DEBUG
import LumenServer
#endif

#if DEBUG
LumenServer.start()
#endif
Objective-C
#if DEBUG
@import LumenServer;
#endif

#if DEBUG
[LumenServer start];
#endif

SPM 会在 Release 中也链接 LumenServer,#if DEBUG 保证它不启动。希望 Release 包完全不含采集端时,用 CocoaPods 或一键脚本。

局域网连接设置
  1. Info.plist 设置 LumenAllowsNetworkConnections = YES,或调用 LumenServer.start(allowsNetworkConnections: true);
  2. 在 Info.plist 中声明本地网络权限(见下);首次运行时在设备上允许;
  3. Lumen 设置中勾选“发现局域网设备”,命令行加 --network。
Info.plist
<key>NSLocalNetworkUsageDescription</key>
<string>用于 Lumen 界面调试(仅 Debug 构建)</string>
<key>NSBonjourServices</key>
<array>
  <string>_lumen._tcp</string>
</array>

一行命令,让 AI 看见界面

lumen mcp 以 MCP 服务运行,读层级、截图、审计、改属性、定位源码都能交给 AI。

Terminal
claude mcp add lumen -- /Applications/Lumen.app/Contents/Helpers/lumen mcp

输入 /mcp 确认已连接;内置排查流程 /mcp__lumen__lumen_ui_debug_workflow 可直接使用。

命令行同样好用

lumen 随 App 安装,--json 输出稳定结构,适合脚本和 CI。

Terminal
sudo ln -sf /Applications/Lumen.app/Contents/Helpers/lumen /usr/local/bin/lumen
lumen apps                                    # 已集成的 App
lumen hierarchy --depth 4                     # 层级树
lumen query 'UIButton[text*="登录"]:visible' # 选择器查询
lumen screenshot 12 -o node.png               # 节点截图
lumen audit --fail-on error                   # 审计,出错退出码 1
lumen set 12 UIView.alpha 0.5                 # 运行时改属性

完整命令见 README,或运行 lumen help。

直接复制这些提示词

Claude Code、Codex、ChatGPT、Cursor 通用

按钮点了没反应

排查
登录页的「忘记密码」按钮点了没反应。用 Lumen 查一下它是被别的视图挡住了,还是触控区域太小,告诉我原因和该改哪个文件。
find_text hit_test locate_source

大字号下文字被截断

排查
订单详情页的价格标签在 iPhone SE 上被截断了。用 Lumen 把字号调到最大,看看还有哪些文字被截断,分析约束问题并给出修改方案。
set_appearance audit get_constraints

照设计稿写页面并核对

写页面
按 design/profile.png 用 SwiftUI 写个人资料页。写完在模拟器里运行,用 Lumen 读取层级和截图,与设计稿对照,列出间距、字号、颜色的偏差并修正,直到和设计稿一致。
get_hierarchy get_node screenshot

先在运行中试,再写进代码

写页面
首页的卡片看起来太挤了。用 Lumen 直接在运行中的 App 里试三组圆角、内边距和阴影的组合,每组截图给我挑,我选定后再改源码。
query set_attribute screenshot

深色模式下文字看不清

改 bug
深色模式下设置页的分组标题看不清。用 Lumen 切到深色模式复现,找出写死颜色的地方并修复,修完重新运行再验证一遍。
set_appearance accessibility locate_source

修复后做回归对比

改 bug
改这个 bug 之前,先用 Lumen 把当前页面存成快照 before。改完重新运行,和 before 对比,确认只有预期的视图发生了变化,再跑一遍审计确保没有新问题。
snapshot_save snapshot_diff audit

调试界面要用的,都在这里

2D / 3D 画布
Metal 渲染,可调层间距,间距测量。
SwiftUI 视图树
控件、修饰符链与 @State 值。
时间轴
回看每次层级变化,比较两个时间点。
设计稿对比
叠加参考图,给出还原度。
无障碍检查
按 VoiceOver 顺序列出元素与 traits。
外观覆盖
运行时切深色、大字号、从右到左。
.lumen 归档
完整快照存成单个文件,离线打开。
零改动注入
不改工程,一键注入 Mac App、模拟器、iOS 安装包与 USB 真机。
手势面板
大纲行首竖条标出手势,点按查看并开关。
屏蔽的类
按类名隐藏图层及子树,可临时显示。
目标卡片
按平台与设备分组,标明 USB、Wi-Fi、模拟器。
后台自动恢复
App 进入后台时提示,回到前台自动刷新。
控制台执行方法
在控制台调用节点、layer 或 VC 上的方法。
点击诊断
某一点命中了谁、其他视图为何被跳过。
修改记录
运行时改过的属性留有记录,修改可撤销。
应用日志
在 Lumen 底部面板查看被调试 App 的日志。

数据只留在你的 Mac 上

所有数据只在本机的 Lumen 与被调试 App 之间传输,不上传任何服务器。

只进 Debug 构建
各种接入方式都只在 Debug 配置启用采集端。
默认只听本机
采集端监听 127.0.0.1,局域网访问需显式开启。
密码框掩码
安全输入框的文本一律以掩码返回。

现在就拆开看看

免费使用,macOS 14 及以上,Apple 芯片与 Intel 均可用。