macos-menubar-tuist-app

macos-menubar-tuist-app

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

核心规则

• 除非明确要求，否则应用应仅运行于菜单栏。默认使用 LSUIElement = true。
• 将传输和解码逻辑放在视图之外。不要在 SwiftUI 视图主体中调用网络请求。
• 将状态转换放在存储层（@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（或工作区清单）存在。
• 更改启动行为前，先阅读现有运行脚本。

2. 编写代码前先探查后端行为

• 使用 curl 验证端点结构、身份验证要求和分页行为。
• 如果端点忽略 limit/page，则实现完整列表处理，并在存储层本地截取。

3. 自底向上实现各层

• 先定义／调整模型。
• 添加或更新客户端请求／解码逻辑。
• 更新存储层的刷新、筛选和缓存策略。
• 最后接入视图。

4. 精简应用接线代码

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

5. 统一启动体验

• 确保运行脚本在重新启动前会先停止已有实例。
• 确保运行脚本不会意外打开 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 目标位置： 将运行／停止脚本作为规范的本地运行路径。

• 刷新后菜单 UI 卡顿或状态不一致： 将派生状态和筛选逻辑移入存储层；让视图只负责渲染。

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

• 功能需求只是快速修补 UI： 在更改行／菜单展示之前，先追踪模型／客户端／存储层中的根本原因。

完成检查清单

• 除非明确要求更改，否则保留仅运行于菜单栏的行为。
• 不要在 SwiftUI 视图主体中放置网络和状态逻辑。
• 确保 Tuist 清单和运行脚本与实际构建／运行流程保持一致。
• 对已修改的部分运行验证矩阵。
• 报告实际运行的命令及其结果。