---

name: macos-menubar-tuist-app description: 构建、重构或审查使用 Tuist 的 SwiftUI macOS 菜单栏应用。 risk: safe source: "Dimillian/Skills (MIT)" date_added: "2026-03-25"

macos-menubar-tuist-app

使用 Tuist 优先的工作流和稳定的启动脚本来构建和维护 macOS 菜单栏应用。保持严格的架构边界，使网络层、状态层和 UI 层保持可测试和可预测。

适用场景

• 当你在开发使用 Tuist 和 SwiftUI 构建的 LSUIElement 菜单栏工具时。
• 当你需要 Tuist 清单文件、启动脚本或菜单栏应用的架构指导时。

核心规则

• 除非明确要求，否则保持应用仅为菜单栏模式。默认使用 LSUIElement = true。
• 将传输和解码逻辑放在视图之外。不要在 SwiftUI 视图 body 中调用网络请求。
• 将状态转换放在 store 层（@Observable 或等效方案），而不是在行/视图展示代码中。
• 保持模型解码对 API 变化的弹性：可选字段、安全回退和防御性解析。
• 将 Tuist 清单文件视为唯一真实来源。不要依赖手动编辑的生成 Xcode 产物。
• 当 tuist run 对 macOS 目标/设备解析不可靠时，优先使用基于脚本的启动方式进行本地迭代。
• 在本地运行脚本中构建生成的项目时，优先使用 tuist xcodebuild build 而非原始 xcodebuild。

预期文件结构

默认使用以下布局：

• Project.swift：应用目标、设置、资源、Info.plist 键
• Sources/*Model*.swift：API/领域模型和解码
• Sources/*Client*.swift：请求、响应映射、传输相关
• Sources/*Store*.swift：可观察状态、刷新策略、过滤、缓存
• Sources/*Menu*View*.swift：菜单组合和顶层 UI 状态
• Sources/*Row*View*.swift：行渲染和轻量交互
• run-menubar.sh：标准本地重启/构建/启动路径
• stop-menubar.sh：需要时的显式停止辅助脚本

工作流程

1. 确认 Tuist 所有权

• 验证 Tuist.swift 和 Project.swift（或工作区清单）是否存在。
• 在更改启动行为之前先阅读现有运行脚本。

1. 在编码假设之前探测后端行为

• 使用 curl 验证端点结构、认证要求和分页行为。
• 如果端点忽略 limit/page，在 store 中实现全列表处理并进行本地裁剪。

1. 从底层到顶层实现各层

• 首先定义/调整模型。
• 添加或更新客户端请求/解码逻辑。
• 更新 store 的刷新、过滤和缓存策略。
• 最后连接视图。

1. 保持应用连接最小化

• 保持应用入口专注于场景/菜单连接和依赖注入。
• 避免在 App 或菜单场景声明中嵌入业务逻辑。

1. 标准化启动体验

• 确保运行脚本在重新启动前先重启现有实例。
• 确保运行脚本不会作为副作用打开 Xcode。
• 需要生成时使用 tuist generate --no-open。
• 当运行脚本构建生成的项目时，优先使用 TUIST_SKIP_UPDATE_CHECK=1 tuist xcodebuild build ... 而非直接调用原始 xcodebuild。

验证矩阵

编辑后运行验证：

TUIST_SKIP_UPDATE_CHECK=1 tuist xcodebuild build -scheme <TargetName> -configuration Debug

如果启动工作流发生变化：

./run-menubar.sh

如果 shell 脚本发生变化：

bash -n run-menubar.sh
bash -n stop-menubar.sh
./run-menubar.sh

故障模式和修复方向

• tuist run 无法解析 macOS 目标： 使用 run/stop 脚本作为标准本地运行路径。

• 刷新后菜单 UI 卡顿或不一致： 将派生状态和过滤移入 store；保持视图仅负责渲染。

• API 负载变化导致解码中断： 使用可选字段和默认值放宽模型解码，然后在 UI 中安全地展示缺失数据。

• 功能需求要求快速 UI 补丁： 在更改行/菜单展示之前，先在模型/客户端/store 中追踪根本原因。

完成检查清单

• 除非明确更改，否则保持仅菜单栏行为。
• 保持网络和状态逻辑不在 SwiftUI 视图 body 中。
• 保持 Tuist 清单文件和运行脚本与实际构建/运行流程一致。
• 对涉及的区域运行验证矩阵。
• 报告运行的具体命令和结果。

限制

• 仅在任务明确匹配上述范围时使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停下来要求澄清。