mda-project-guide

# MDA 项目指南 ## 适用范围 当你正在 `C:\Users\12042\Documents\GitHub\MDA` 仓库中工作，并且任务涉及以下内容时使用本 skill： - Pipeline JSON 编写、调试或命名。 - Project Interface 任务文件生成或修改。 - `assets/interface.json`、`assets/tasks/`、`assets/locales/interface/`。 - MDA 的 `agent/go-service/` 自定义组件。 - 需要判断 MDA 现有业务域、任务选项、locale 语言范围或路径约定。 本 skill 只记录 MDA 项目特例；MaaFramework 通用规则请先看： - `pipeline-guide` - `pipeline-debug` - `generate-pi-task` - `go-service-guide` ## 项目结构 MDA 采用 MaaFramework / Project Interface / MXU 风格结构： ```text MDA/ ├── AGENTS.md ├── assets/ │ ├── interface.json │ ├── tasks/ │ ├── locales/interface/ │ │ ├── zh_cn.json │ │ └── en_us.json │ ├── locales/go-service/ │ │ ├── zh_cn.json │ │ └── en_us.json │ └── resource/pipeline/ ├── agent/go-service/ └── tools/schema/ ``` 关键文件： | 路径 | 用途 | | ------------------------------------- | --------------------------------------------------------------------- | | `assets/interface.json` | Project Interface 主配置，包含 import、group、controller、resource 等 | | `assets/tasks/*.json` | PI 任务定义和 option 配置 | | `assets/tasks/preset/*.json` | 预设任务组合 | | `assets/resource/pipeline/**.json` | MaaFramework Pipeline 节点 | | `assets/locales/interface/zh_cn.json` | 界面中文文案 | | `assets/locales/interface/en_us.json` | 界面英文文案 | | `tools/schema/*.json` | Pipeline / PI / Custom schema | | `agent/go-service/` | Go Agent 自定义逻辑 | ## MDA locale 范围 MDA 当前 interface locale 主要维护： - `zh_cn` - `en_us` 新增任务或 option 时，默认只同步这两个文件。不要按其它项目习惯擅自补 `zh_tw`、`ja_jp`、`ko_kr`，除非用户明确要求或项目新增了对应 locale 文件。 所有用户可见文本在任务文件中使用 `$` i18n key，例如： ```json "label": "$task.Shop.label" ``` ## 常见业务域 MDA Pipeline 当前常见业务域包括： | Domain | 说明 | | ----------------------- | ---------------------- | | `Advise` | 咨询 / 剧情 / 剧集相关 | | `Arena` | 竞技场相关 | | `Battle` | 战斗通用流程 | | `Common` | 通用 UI、弹窗、交互 | | `CoordinatedOperations` | 协同作战 | | `DailyRewards` | 日常奖励 | | `Event` | 活动通用域 | | `Interception` | 拦截战 | | `Login` | 登录流程 | | `MapPushing` | 推图 | | `Navigation` | 导航和回到主界面 | | `Outpost` | 前哨基地 | | `RedDotClear` | 红点清理 | | `Shop` | 商店 | | `SimulationRoom` | 模拟室 | | `TribeTower` | 企业塔 / 阵营塔 | 新增节点时优先沿用现有目录与 Domain；不要为了单个节点新建同义 Domain。 ## Pipeline 命名习惯 MDA 使用通用 MaaFramework PascalCase 命名规则，并倾向于： - 入口：`<Domain>Main` - 编排：`<Domain><Subtask>Flow` - 进入页面：`<Domain>Enter<Page>` - 页面确认：`<Domain><Page>Entered` - 页面状态：`<Domain>On<Page>Page` - UI 可见：`<Domain><Object>Visible` - 点击/选择/领取：`<Domain>Click<Object>`、`Select`、`Claim`、`Purchase` - 确认：`<Domain>Confirm<Object>` 或 `CommonConfirm<Object>` MDA 命名中特别注意： - 新节点不要再用 `FlagInX` 表达页面状态。 - `Visible` 节点不要过度拆分；如果只被一个点击节点使用且没有组合识别价值，优先合并进点击节点。 - `Entered` 节点可以只被一个进入流程引用，只要它承担“进入成功哨兵”职责，就不是无意义中转节点。 ## Project Interface 任务文件 MDA 任务文件位于 `assets/tasks/`，当前包括： - `Advise.json` - `Arena.json` - `CashShop.json` - `CoordinatedOperations.json` - `DailyRewards.json` - `Interception.json` - `LargeEvent.json` - `MapPushing.json` - `Outpost.json` - `RedDotClear.json` - `Shop.json` - `SimulationRoom.json` - `SmallEvent.json` - `TribeTower.json` 新增任务文件后，`assets/interface.json` 的 `import[]` 使用相对路径： ```json "tasks/MyTask.json" ``` 而不是： ```json "assets/tasks/MyTask.json" ``` ## MDA 选项建模示例 这些例子来自 MDA 现有任务，用于辅助判断 `generate-pi-task` 的 option 类型。 | Task File | Option | Type | 说明 | | --------------------- | --------------------------- | --------------- | -------------------------------------- | | `Arena.json` | `SpecialReward` | `switch` | 单个是否领取奖励的开关 | | `Arena.json` | `EnterRookieArena` | `switch` | 单个是否进入该竞技场的开关 | | `Interception.json` | `InterceptionType` | `select` | Normal / Anomaly 互斥 | | `Interception.json` | `NormalyInterceptionLevel` | nested `select` | 普通拦截的难度子选项 | | `Interception.json` | `AnomalyInterceptionTarget` | nested `select` | 异常拦截的目标子选项 | | `Interception.json` | `ManualInterceptionBattle` | `switch` | 单个功能开关 | | `Shop.json` | `ArenaShopItemList` | `checkbox` | 多个独立商店物品可同时购买 | | `Shop.json` | `RecyclingShopList` | `checkbox` | 多个独立可回收物品，存在默认选择 | | `Shop.json` | `CommonShopFreeGoods` | `switch` | 单个是否领取免费商品开关 | | `SimulationRoom.json` | `StartOverlock` | `switch` | Yes case 下嵌套 `AutoBIOSSetting` | | `SimulationRoom.json` | `AutoBIOSSetting` | nested `switch` | 自动难度子开关 | | `Outpost.json` | `DefenseRewards` | `switch` | 默认开启时可设置 `default_case: "Yes"` | | `TribeTower.json` | `EnterCommonTower` | `switch` | 默认关闭时可按既有风格让 No 在 Yes 前 | 判断原则： - `select`：互斥路线，case 之间要互相禁用。 - `checkbox`：独立列表，case 通常只启用自身节点。 - `switch`：单个是否执行的功能。 - nested option：只有某个 case 激活后才显示的子配置。 ## MDA Go Service MDA 存在 `agent/go-service/`，当前包含： - `main.go` - `register.go` - `logger.go` - `pkg/pienv` - `pkg/resource` - `pkg/i18n` - `pkg/maafocus` - `taskersink/aspectratio` - `taskersink/hdrcheck` - `taskersink/processcheck` - `taskersink/membership` 开发 Go 组件时： - 先看 `agent/go-service/register.go` 的聚合方式。 - 新包应有自己的 `Register()`。 - 注册名必须与 Pipeline Custom 节点一致。 - 日志和包结构遵循当前已有 Go 代码。 - 如果新增用户可见文案，同时维护 `assets/locales/go-service/zh_cn.json` 和 `en_us.json`。 ## Windows / PowerShell 约束 MDA 的 `AGENTS.md` 明确项目运行环境为 Windows / PowerShell 7。 执行命令时： - 优先使用 PowerShell 语法。 - 路径带空格时加双引号。 - 不要默认使用 Bash heredoc、`grep`、`find`、`sed`、`awk` 等 Unix 写法。 - 文件搜索和读取优先使用 Claude Code 专用工具。 ## 与通用 skill 的配合方式 - 写 Pipeline：先用 `pipeline-guide`，再用本 skill 确认 MDA Domain、locale 范围和任务结构。 - 调试 Pipeline：先用 `pipeline-debug`，再用本 skill 判断 MDA 现有命名和任务语义。 - 生成 PI task：先用 `generate-pi-task`，再用本 skill 参考 MDA 选项建模示例。 - 写 Go Service：先用 `go-service-guide`，再用本 skill 确认 MDA 的包和 locale 目录。 ## 自检清单 - [ ] 新增/修改的任务文件已被 `assets/interface.json` import。 - [ ] 只维护 MDA 当前存在的 interface locale：`zh_cn`、`en_us`。 - [ ] Pipeline 节点 Domain 与现有目录和业务域一致。 - [ ] option 类型符合 MDA 既有建模习惯。 - [ ] `pipeline_override` 节点名真实存在。 - [ ] Go 组件已注册到 `registerAll()`。