macos-menubar-tuist-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

macos-menubar-tuist-app

macOS菜单栏Tuist应用

Build and maintain macOS menubar apps with a Tuist-first workflow and stable launch scripts. Preserve strict architecture boundaries so networking, state, and UI remain testable and predictable.

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

Core Rules

核心规则

Keep the app menubar-only unless explicitly told otherwise. Use
```
LSUIElement = true
```
by default.
Keep transport and decoding logic outside views. Do not call networking from SwiftUI view bodies.
Keep state transitions in a store layer (
```
@Observable
```
or equivalent), not in row/view presentation code.
Keep model decoding resilient to API drift: optional fields, safe fallbacks, and defensive parsing.
Treat Tuist manifests as the source of truth. Do not rely on hand-edited generated Xcode artifacts.
Prefer script-based launch for local iteration when
```
tuist run
```
is unreliable for macOS target/device resolution.
Prefer
```
tuist xcodebuild build
```
over raw
```
xcodebuild
```
in local run scripts when building generated projects.

默认仅保留菜单栏应用模式，除非另有明确要求。默认设置
```
LSUIElement = true
```
。
将传输和解码逻辑置于视图之外。禁止在SwiftUI视图体中调用网络请求。
将状态转换放在存储层（
```
@Observable
```
或等效实现）中，而非行/视图展示代码里。
让模型解码具备抗API变更能力：使用可选字段、安全回退和防御性解析。
将Tuist清单视为唯一可信源。不要依赖手动编辑的Xcode生成产物。
当
```
tuist run
```
在macOS目标/设备解析方面不可靠时，优先使用基于脚本的启动方式进行本地迭代。
构建生成的项目时，在本地运行脚本中优先使用
```
tuist xcodebuild build
```
而非原生
```
xcodebuild
```
。

Expected File Shape

预期文件结构

Use this placement by default:

```
Project.swift
```
: app target, settings, resources,
```
Info.plist
```
keys
```
Sources/*Model*.swift
```
: API/domain models and decoding
```
Sources/*Client*.swift
```
: requests, response mapping, transport concerns
```
Sources/*Store*.swift
```
: observable state, refresh policy, filtering, caching
```
Sources/*Menu*View*.swift
```
: menu composition and top-level UI state
```
Sources/*Row*View*.swift
```
: row rendering and lightweight interactions
```
run-menubar.sh
```
: canonical local restart/build/launch path
```
stop-menubar.sh
```
: explicit stop helper when needed

默认采用以下文件布局：

```
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
```
：必要时使用的显式停止辅助脚本

Workflow

工作流程

Confirm Tuist ownership

Verify
```
Tuist.swift
```
and
```
Project.swift
```
(or workspace manifests) exist.
Read existing run scripts before changing launch behavior.

Probe backend behavior before coding assumptions

Use
```
curl
```
to verify endpoint shape, auth requirements, and pagination behavior.
If endpoint ignores
```
limit/page
```
, implement full-list handling with local trimming in the store.

Implement layers from bottom to top

Define/adjust models first.
Add or update client request/decoding logic.
Update store refresh, filtering, and cache policy.
Wire views last.

Keep app wiring minimal

Keep app entry focused on scene/menu wiring and dependency injection.
Avoid embedding business logic in
```
App
```
or menu scene declarations.

Standardize launch ergonomics

Ensure run script restarts an existing instance before relaunching.
Ensure run script does not open Xcode as a side effect.
Use
```
tuist generate --no-open
```
when generation is required.
When the run script builds the generated project, prefer
```
TUIST_SKIP_UPDATE_CHECK=1 tuist xcodebuild build ...
```
instead of invoking raw
```
xcodebuild
```
directly.

确认Tuist所有权

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

在编码假设前探查后端行为

使用
```
curl
```
验证端点结构、认证要求和分页行为。
如果端点忽略
```
limit/page
```
参数，在存储层实现全列表处理及本地裁剪。

从下到上实现各层

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

最小化应用连接逻辑

应用入口仅聚焦于场景/菜单连接和依赖注入。
避免在
```
App
```
或菜单场景声明中嵌入业务逻辑。

标准化启动体验

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

Validation Matrix

验证矩阵

Run validations after edits:

bash

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

If launch workflow changed:

bash

./run-menubar.sh

If shell scripts changed:

bash

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

编辑完成后运行以下验证：

bash

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

如果启动工作流有变更：

bash

./run-menubar.sh

如果Shell脚本有变更：

bash

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

Failure Patterns and Fix Direction

故障模式与修复方向

```
tuist run
```
cannot resolve the macOS destination: Use run/stop scripts as canonical local run path.
Menu UI is laggy or inconsistent after refresh: Move derived state and filtering into the store; keep views render-only.
API payload changes break decode: Relax model decoding with optional fields and defaults, then surface missing data safely in UI.
Feature asks for quick UI patch: Trace root cause in model/client/store before changing row/menu presentation.

```
tuist run
```
无法解析macOS目标：使用启动/停止脚本作为标准的本地运行路径。
菜单UI在刷新后卡顿或行为不一致：将派生状态和过滤逻辑移至存储层；仅让视图负责渲染。
API负载变更导致解码失败：放宽模型解码规则，使用可选字段和默认值，然后在UI中安全地展示缺失数据。
需求要求快速修复UI：先排查模型/客户端/存储层的根本原因，再修改行/菜单展示代码。

Completion Checklist

完成检查清单

Preserve menubar-only behavior unless explicitly changed.
Keep network and state logic out of SwiftUI view bodies.
Keep Tuist manifests and run scripts aligned with actual build/run flow.
Run the validation matrix for touched areas.
Report concrete commands run and outcomes.

除非明确变更，否则保留仅菜单栏的行为。
禁止在SwiftUI视图体中包含网络和状态逻辑。
确保Tuist清单和运行脚本与实际构建/运行流程一致。
对修改过的部分运行验证矩阵。
报告执行的具体命令及结果。