参与开发

AutoMAA 是 Swift Package Manager 项目，界面使用 SwiftUI，最低支持 macOS 14。构建需要 Apple Silicon Mac 和 Xcode 26（Swift 6.2）或兼容工具链；单元测试不需要安装游戏、PlayCover 或 MAA。

从源码运行

bash

git clone https://github.com/Rememorio/AutoMAA.git
cd AutoMAA
swift test --parallel
./scripts/build-app.sh
open .build/AutoMAA.app --args --data-directory /tmp/automaa-development

构建产物位于 .build/AutoMAA.app。构建脚本使用当前 Xcode 选定的 macOS SDK，并在打包前校验四个可执行文件的链接 SDK 版本，保留 macOS 14 部署目标。上面的启动命令使用独立数据目录，同时隔离配置、日志和 LaunchAgent，并关闭系统 LaunchAgent 集成与自动更新检查。界面测试始终使用这一入口，不读取或覆盖日常使用的配置。

上游协议范围

任务生成参数与配置结构对照 MaaCore v6.20.1、MAA 集成文档和 maa-cli v0.7.7 的任务 schema与连接 schema。临期理智药使用 medicine_expire_days，公招保留标签使用 preserve_tags；不生成旧字段 expiring_medicine、skip_robot 或已失效的 expedite_times。

AutoMAA 提供已建模的日常任务参数。三星招聘许可保留量、基建副手换班、限时活动签到和回收站（Recycle）换班暂未提供配置入口；不会自动启用这些选项。基建设施按方案中明确列出的设施派发，自定义训练位参数由外部排班 JSON 交给 MaaCore 解析。maa-cli 的 Profile 连接方式、额外资源加载顺序和服务器游戏日偏移保持独立核对；作战结果与回调解析的依据见下文。

代码从哪里看

目录	职责
`Sources/AutoMAA/`	SwiftUI 界面、状态与交互；共享视觉组件位于 `Theme.swift`
`Sources/AutoMAAKit/`	配置模型、校验、MAA 文件生成、工作流、存储与系统集成
`Sources/AutoMAARunner/`	定时任务使用的无界面入口
`Sources/AutoMAAResourceProbe/`	在独立进程中验证 MaaCore 与识别资源组合
`Sources/AutoMAAUpdater/`	App 替换、失败回滚与重新启动
`Tests/AutoMAAKitTests/`	核心逻辑与隔离测试
`scripts/`	构建、打包与验证脚本
`docs/`	用户指南和文档站

修改配置通常从 Models.swift 与 ConfigurationValidation.swift 开始，任务参数转换位于 MAAConfigurationWriter.swift，运行顺序、重试和断点位于 WorkflowRunner.swift。可测试逻辑应留在 AutoMAAKit，避免在界面层重复实现。

界面与交互

视觉规则见 DESIGN.md，导航、保存、反馈与恢复行为见 UX-CONTRACT.md。修改前先查对应约定和共享组件：

位置	职责
`RootView.swift`、`InterfaceComponents.swift`	主窗口工具栏、侧栏与方案/记录分栏
`ActionControls.swift`、`ClipboardCopyButton.swift`	图标与文字操作、尺寸稳定的复制反馈
`SettingsPresentation.swift`、`SettingsView.swift`	独立设置窗口、固定标题和内容高度适配
`EntityEditorSheet.swift`、`PlanExecutionArrangement.swift`	草稿表单、校验、取消与明确提交
`ApplicationFeedback.swift`	按所属窗口呈现普通操作反馈与保存错误

任务执行与运行准备共用 AppModel 和 AutoMAAKit 的状态；方案页、总览与 macOS 菜单保持相同的运行和停止语义。界面约定发生变化时，同步修改对应文档与组件。隔离验收范围见发版指南。

工作流与上游接口

账号准备使用按客户端与账号生成的 StartUp 任务，显式设置 start_game_enabled=false，通过 maa run --no-auto-reconnect 执行；服务器映射、账号片段和独立 Profile 保持一致。客户端生命周期和有界恢复由 WorkflowRunner 管理。不能用带服务器参数的 maa startup 替代：该预设会开启 Core 内部重启，而 PlayTools 支持停止游戏但不能重新启动游戏。依据见 maa-cli 启动预设、MaaCore 启动任务和 PlayTools 控制器。

作战结果判定与续跑状态位于 FightExecution.swift，关卡记忆位于 FightStageMemory.swift。当前实现对照 MaaCore v6.18.0 和 maa-cli v0.7.5：每次作战命令通过 MAA_STATE_DIR 使用独立 Core 日志，结算依据 StageDrops 回调，cur_times 按每次结算累加；缺少该值时使用由 FightTimes.series 绑定到对应开战与结算的批次倍率，两者均未知时显示次数下限。SanityBeforeStage 与紧随其后的消耗、倍率共同判断单局理智不足，不以整批连战消耗代替单局消耗。maa-cli 摘要的次数在开打时增加，不能单独证明完成；剿灭导航失败也不能证明周奖励已满。

账号准备与非作战任务同样使用命令独立的临时 MAA_STATE_DIR，保持配置、Core、资源和热更新缓存的路径不变，目录行为依据 maa-cli 目录定义与 Core 初始化。失败或取消后，MAACommandDiagnostics.swift 从当前日志及轮转备份各读取最多 256 KiB 的末尾，保留最多 64 KiB 的近期回调和错误，并在清理前写入诊断日志；截断、不完整行和读取失败均有说明。摘要分别保留可读取片段中的首次异常、最后观察到的步骤和最终错误；首次异常即使被近期输出淘汰也保留脱敏、有长度上限的摘要，但不被解释为根因。展示摘要不参与成功、账号匹配、重试或断点判定；原始临时日志及 Core 生成的其他诊断文件随后删除。

MAACoreLog 提供有界的本次命令日志快照，StartupNavigationObservation 独立解析原始结构化回调。只有日志完整，且顺序确认 StartUp 与 AccountSwitchTask 开始、Settings 操作完成、返回账号选择页的 ProcessTask 失败、账号切换与任务链失败时，才允许一次受控重启；取消、账号匹配错误和明确人工处理提示不进入该恢复路径。日志截断、缺失、回调矛盾或进入其他界面时保持保守处理。恢复与连接异常、非作战超时共用每账号一次的额度，不改变任务成功和断点依据。导航与账号匹配的阶段划分已对照 MaaCore v6.18.0 与 v6.19.0 的 AccountSwitchTask；v6.19.0 调整了设置页导航资源，未改变这里使用的切号回调结构。

作战类型与显示名称分开保存。ProcessTask 开始处理 EndOfAction 或 EndOfActionAnnihilation 时记录结算类型，再与对应的掉落结果关联；有效周奖励进度也能证明是剿灭，不要求达到上限。Core 先运行掉落插件，再转发 SubTaskCompleted，因此不能等待完成事件再判断前面的掉落。未知类型、无效编号和不完整结果不会覆盖常规关卡记忆。上游依据见 StageDropsTaskPlugin、AbstractTask 回调顺序、StageNavigationTask 和 maa-cli 作战摘要。对应行为使用隔离回调样例与工作流测试覆盖。

已有目标时，自动换关只接受作战前的 StageNavigationTask 失败，或已点击上次作战入口后的导航失败；进入 FightBegin、发现战斗画面、超时或掉线都会阻止自动换关。选关与各次尝试在 WorkflowRunner 中串行执行，已选兜底在派发前持久化。兜底结果与原目标分开保存，不能更新恢复记录；所有服务器共享这套判断。

每周剿灭策略与状态位于 WeeklyAnnihilation.swift。策略属于方案，周状态按客户端、账号与服务器区分；只以明确周奖励上限或手动确认为本周完成，单次成功与理智不足均不能替代。游戏周使用 maa-cli v0.7.5 的服务器时间偏移：官服、Bilibili、繁中服为 UTC+4，日服、韩服为 UTC+5，国际服为 UTC−11；这些偏移已包含游戏日 04:00 的边界，不是当地民用时区。每周从游戏日周一开始；派发时固定周标识，跨周结果不会误记为新周完成。未确认结果跨周仍阻止自动补打。

ExecutionState.prepareWeeklyAnnihilation 统一供 Runner 与界面续跑状态使用，恢复剿灭可执行性时保留每日常规阶段与其他步骤。派发前分别原子保存每日目标和共享周状态；任何写入失败均停止派发，未完成的保存不能伪装成成功。PlanContinuation.fightRecoveryItems 提供独立于历史日志的当前处理项，方案页和运行记录共用 FightRecoveryActions。WeeklyAnnihilationStore.confirmComplete 在进程锁内重新读取并校验当前游戏周记录，仅更新周状态，不启动工作流。入口不可用只有在完整任务回调证明尚未进入作战时才可安全跳过，证据不足仍保留待确认。

常规关卡的开战前检查

FightStageInspection 通过隔离配置中的 Custom 任务复用 MaaCore 的关卡页 OCR。独立 Profile 启用 user_resource，生成的节点使用专属名称，重置继承的动作、分支与子任务；仅“前往上次作战”和返回终端导航可点击，开始作战和全权委托识别节点只观察。没有 Fight 任务，也不用 times = 0 模拟探测。只接受本次隔离日志中完整成功的 Custom 回调；检查失败不派发作战。

选择顺序为当前/上次常规关卡、账号恢复目标、方案兜底。剿灭前保存常规目标；没有目标时可使用配置兜底；已有目标的每个后续候选仅在明确未开战的选关失败后尝试一次。最近成功关卡、待恢复目标与临时兜底分别保存；只有成功结算更新成功记录。待确认续跑固定使用已派发目标，不重新跟随游戏。手动选择与自动兜底恰好相同时无法区分，手动设置常规目标可以解除该恢复状态。

识别流程依据 MaaCore v6.18.0 的任务资源、Custom 接口和 maa-cli Profile 资源配置。继承模板匹配的节点需要显式指定图片名，避免 Core 按新任务名查找不存在的图片。

修改与验证

提交方式、编码要求和测试隔离规范见 CONTRIBUTING.md。外部贡献者通过 fork、分支和 Pull Request 合入 main。

按改动范围运行相应检查：

改动范围	验证命令
所有改动	`git diff --check`
Swift 代码	`swift test --parallel`
SwiftUI、应用入口或系统集成	另运行 `./scripts/build-app.sh`，使用独立数据目录检查界面
README 或文档	`npm ci`、`npm run docs:build`、`./scripts/check-public-content.sh`
打包脚本或发行结构	`./scripts/verify-release.sh`

账号切换、端口释放、断点、取消和 MAA 参数的修改需要相应回归测试。测试不得连接真实游戏、默认 MaaTools 地址或用户数据；LaunchAgent 测试还需注入临时目录并关闭系统集成。

文档修改见文档站维护。维护者发版流程集中在 RELEASE.md；编码代理还应遵循 AGENTS.md。

参与开发 ​

从源码运行 ​

上游协议范围 ​

代码从哪里看 ​

界面与交互 ​

工作流与上游接口 ​

常规关卡的开战前检查 ​

修改与验证 ​