MaaFramework 开发指南

核心原则

• 以 MaaFramework 官方文档、Schema 和源码为语义首要依据。
• 在 MaaPipelineEditor 仓库中工作时，官方源码默认指 dev/docs/社区参考项目索引.md 登记的本地参考仓库；本地克隆与 GitHub 上游属于同一源码来源，不得因需要“官方源码”而绕过本地仓库访问远端。
• 准确区分 Project、Pipeline、Bundle、Resource、Task、Entry、Node、Controller、Tasker、Context、Agent 等概念。
• 不根据旧 MPE 实现反推 MaaFramework 行为；新增或修改 MFW 相关能力前核对当前参考版本的文档与 API。
• 设计 JSON/JSONC 修改流程时考虑注释、格式、字段顺序和精确位置，禁止默认用普通反序列化再整体序列化破坏源文件。

本地参考源码

需要参考 MaaFramework 或社区项目实现时：

1. 先完整读取仓库根目录的 dev/docs/社区参考项目索引.md，按其中的“按任务选择参考项目”确定项目，并从索引解析本地路径；不要凭记忆猜测目录。
2. 优先使用索引中的本地仓库进行 rg、文件读取、git log、git blame 和版本对比。开始引用前记录其当前 commit；需要判断新旧时再检查本地分支和远端跟踪信息。
3. 本地仓库缺失或明确需要更新时，不要在系统临时目录或其他位置另行 git clone。用户要求同步或更新时使用 sync-reference-projects skill 的统一流程；只读任务中若版本新旧会实质性影响结论，则说明本地状态并取得同步授权。
4. 仅当索引未收录所需项目，或本地仓库确实无法提供任务所需内容时，才访问 GitHub、Raw URL 或远端 API；访问前说明原因。远端查询不得替代对现有本地参考仓库的检查。

常用本地入口（均以 MaaPipelineEditor 仓库根目录为基准）：

• MaaFramework：../maa-refs/MaaFramework
• maa-support-extension（MSE）：../maa-refs/maa-support-extension
• 其余项目：以 dev/docs/社区参考项目索引.md 为准。

参考文档索引

按任务类型选择对应参考文件：

项目结构识别

一个标准 MaaFramework 项目通常包含：

project/
├── interface.json          # ProjectInterface V2 声明
├── assets/
│   ├── resource/           # Bundle：pipeline/、image/、model/
│   │   ├── pipeline/
│   │   ├── image/
│   │   ├── model/ocr/
│   │   └── default_pipeline.json
│   └── interface_zh.json   # 多语言翻译（可选）
└── agent/                  # Agent 自定义扩展（可选）

识别顺序：

1. 确认 interface.json 存在并解析 interface_version。
2. 解析 controller、resource、task、option、preset、group 等字段。
3. 按 resource.path 定位 Bundle，递归读取 pipeline/ 下所有 JSON/JSONC。
4. 需要运行时信息再加载控制器；静态分析阶段不假设设备已连接。

Pipeline 处理工作流

1. 读取 pipeline/ 目录下所有 JSON/JSONC（以 . 开头的目录/文件被忽略；以 $ 开头的 root 字段被忽略）。
2. 解析节点时支持 v1（recognition/action 字符串及同级参数字段）和 v2（recognition/action 为 { type, param } 对象）混用。
3. 识别引用关系：next、on_error、roi、target 可引用节点名或 [Anchor]锚点名。
4. 修改 Pipeline 时：
   • 保留 JSONC 注释与字段顺序；
   • 使用精确位置编辑而非整体重写；
   • 引用变更时同步检查引用目标是否存在。
5. 需要算法/动作字段定义时查阅 3.1-任务流水线协议.md。

ProjectInterface V2 处理工作流

1. 确认 interface_version 为 2。
2. 解析核心字段：name、version、controller、resource、task、option、preset、group、import、agent、pretask、global_option、setting。
3. 处理 import 合并规则：
   • task、preset、group、pretask、setting：追加；
   • option：对象合并，后导入覆盖先导入；
   • global_option：追加并按 option 键名去重，保留先出现项。
4. 处理 option 覆盖优先级：global_option < resource.option < controller.option < task.option。
5. 启动 Agent 子进程时按 v2.5.0+ 约定注入 PI_* 环境变量，详见 3.3-ProjectInterfaceV2协议.md 的 Agent 子进程环境变量小节。
6. 需要字段完整定义时查阅 3.3-ProjectInterfaceV2协议.md。

集成与运行时

1. 优先使用项目确定的语言 Binding（如 Python Binding）。
2. 核心对象生命周期：创建 Resource → 加载 Bundle → 创建 Controller → 连接设备 → 创建 Tasker → 绑定 Resource 和 Controller → 执行任务。
3. 自定义识别/动作优先通过 Agent 进程实现；AgentServer 注册自定义逻辑后由 AgentClient 在运行时调用。
4. 监听回调时按 2.3-回调协议.md 解析 message 与 details_json，注意线程安全与快速返回。
5. 需要控制器截图/输入方式配置时查阅 2.4-控制方式说明.md。

常见陷阱

• 不要把 Pipeline JSON 当作完整 MFW 项目；项目还需要 interface.json、资源目录、可能的 Agent。
• timeout 作用于当前节点的 next 列表识别超时，而非当前节点自身的 recognition 等待时间。
• roi/target 的字符串引用支持节点名和 [Anchor]锚点名；引用为空时视为识别/动作失败。
• default_pipeline.json 在 Bundle 根目录与 pipeline/ 同级，按 Bundle 加载顺序合并，已加载节点不受后续默认值影响。
• Pipeline 文件支持 JSONC，但能否使用以对应版本官方行为或明确工具契约为准；修改时避免破坏注释。