SuperAPI AI 工具集

cmux-debugging

编程与开发

查看项目

更新于 10-16 00:05

技能介绍

用途:面向 cmux 开发者的调试指南,覆盖调试日志、性能剖析、Debug 菜单与运行时陷阱,帮助在 DEBUG 构建中定位键盘、鼠标、焦点、分屏、标签页等问题。

调试事件日志:将调试事件埋点写入统一的 DEBUG 构建日志。未打标签的 Debug 应用日志写入 /tmp/cmux-debug.log;带标签(./scripts/reload.sh --tag <tag>)写入 /tmp/cmux-debug-<tag>.log。可用 tail -f "$(cat /tmp/cmux-last-debug-log-path 2>/dev/null || echo /tmp/cmux-debug.log)" 跟踪。reload.sh 会把当前日志路径写入 /tmp/cmux-last-debug-log-path,把所选 dev CLI 路径写入 /tmp/cmux-last-cli-path,并将 /tmp/cmux-cli 与 $HOME/.local/bin/cmux-dev 指向该 CLI。实现位于 Packages/macOS/CMUXDebugLog/Sources/CMUXDebugLog/DebugEventLog.swift,应用侧为 Sources/App/DebugLogging.swift,二者均为 #if DEBUG,调用点需用 #if DEBUG / #endif 包裹。cmuxDebugLog("message") 实时加时间戳追加,由 500 条环形缓冲支撑,dump() 可写全量缓冲到文件。稳定事件前缀包括 focus.panel、focus.bonsplit、focus.firstResponder、focus.moveFocus、tab.select、tab.close、tab.dragStart、tab.drop、pane.focus、pane.drop、divider.dragStart。

性能剖析:对带标签构建用 xctrace record --attach <pid> 或 sample <pid> 附加到进程。切勿对任何 cmux bundle 使用 xctrace --launch 或 Instruments 启动模式,也不要退出、杀死或重启用户正在运行的 cmux(com.cmuxterm.app),因其持有实时智能体会话。

Debug 菜单:DEBUG 构建在 macOS 菜单栏提供 Debug 菜单,用户所说“debug menu/window”即指此。Debug > Debug Windows 存放布局、颜色与行为调优面板,按字母排序无分隔线。新增需创建带共享单例的 NSWindowController 子类,在 Sources/cmuxApp.swift 的菜单注册,并用 @AppStorage 绑定的 SwiftUI 视图支撑实时修改。

运行时陷阱:自定义拖放 UTTypes 须在 Resources/Info.plist 的 UTExportedTypeDeclarations 声明;不要添加应用级 display link 或手动 ghostty_surface_draw 循环;WindowTerminalHostView.hitTest() 每个事件(含键盘)都会运行,performHitTest 中 allowsPortalPointerHitTesting 守卫外不得加工作;TabItemView 用 Equatable 与 .equatable() 跳过输入时 body 重算,新增读取需同步更新 ==;TerminalSurface.forceRefresh() 每次按键运行,禁止分配、文件 I/O 或格式化;SurfaceSearchOverlay 须从 GhosttySurfaceScrollView 挂载;LazyVStack/LazyHStack/List/ForEach 边界下的视图只接收不可变快照与闭包;SwiftUI body 调用的函数不得改状态或调度写入;Foundation、SwiftUI、AttributeGraph、WebKit 语义随 macOS 大版本变化,需在报告者系统上复现。

限制:资料未提供安装方式、收费与平台支持等细节。