开发工作流

命令索引

命令	用途
task doctor	检查 Xcode、Swift、XcodeGen 和 plist
task generate	从 project.yml 重新生成 Xcode 工程
task build	构建 iOS 模拟器版本
task ios:run	构建、安装并启动真机或模拟器版本
task build:mac	构建 macOS 版本
task test	构建 XCTest 测试包
task test:run	在指定模拟器执行 XCTest
task verify	执行基线环境检查与 iOS 构建
task verify:all	验证 iOS、macOS 和测试目标
task state:paths	显示首次运行状态的本地路径
task reset:user-state	备份并清理 macOS 用户状态
task wiki:build	安装锁定依赖并构建 Wiki
task wiki:dev	启动 Wiki 开发服务器
task clean	删除生成的构建与 Wiki 缓存

修改项目结构

project.yml 是项目、Target、Scheme、源码路径、资源路径和 Build Setting 的事实来源。结构变化按以下顺序处理：

1. 修改 project.yml。
2. 同步 Taskfile.yml、AGENTS.md 和文档中的路径。
3. 删除确有必要重建的生成输出。
4. 执行 task generate。
5. 执行 task verify。

不要手工修改 *.xcodeproj/project.pbxproj 作为长期修复。生成的 Xcode 工程可以丢弃并重建。

代码组织

• Swift 文件保持小而单一，按 App、Design、Models、Storage、Views 和 Platform 职责组织。
• 设置、语言、英文回退和外观能力属于模板基线，派生应用不能在无明确产品决定时移除。
• 默认使用本地数据；引入外部依赖前说明其必要性和隐私影响。
• UI 文本通过本地化键读取，不在 View 中拼接句子。

验证范围

所有修改至少执行 task verify。偏好、本地化、持久化和设置行为变化还需执行 task test。权限、签名、entitlement、数据存储或 UI 变化应在提交说明中写明对应的验证结果。

Wiki 变化执行 task wiki:build，构建会检查配置、Markdown 链接和静态站点生成是否正常。