mda-project-guide

name	mda-project-guide
description	MDA 项目专属开发指南。用于在 MDA 中编写或审查 MaaFramework Pipeline、Project Interface 任务、locale、go-service 组件时补充项目结构、业务域、命名习惯和现有任务选项示例。与通用 pipeline-guide、pipeline-debug、generate-pi-task、go-service-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 风格结构：

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，例如：

"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[] 使用相对路径：

"tasks/MyTask.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()。