完善 Custom Controller 支持

[Zwlin98]

功能描述 / Feature Description

Feature Request: 完善 Custom Controller 支持

问题

MaaFramework 通过 MaaCustomControllerCreate C API 和各语言 binding 的 CustomController 基类，支持在同一进程内实现自定义控制器。但这个能力无法跨进程使用：

• Agent 子进程（通过 AgentServer）只能注册 Custom Recognition 和 Custom Action，不能注册 Controller
• PI V2 的 controller.type 只有 6 种内置类型（Adb | Win32 | MacOS | PlayCover | Gamepad | WlRoots），没有 Custom

结果是：使用自定义控制器的项目既不能通过 interface.json 声明控制器，也不能通过 agent 子进程提供控制器实现，无法使用任何 PI Client（MaaPiCli、MFAWPF、MFAA 等）。只能自己写入口程序。

使用场景

• 远程控制：控制端和被控端不在同一台机器，控制器通过 RPC 转发截图和输入操作（如从 Linux 控制 Windows 桌面应用，无法走 Adb/Win32）
• 自定义设备：嵌入式设备、工业屏等，截图和输入走私有协议
• CI Mock：Pipeline 验证环节使用 Mock 控制器，不依赖真实设备

这些场景的 pipeline / resource / task / option 和内置控制器完全一样，只有控制器的创建方式不同。

需要的改动

1. Framework：AgentServer 支持注册 Controller

现有 AgentServer 支持：

• register_custom_recognition(name, recognition) — 注册识别器
• register_custom_action(name, action) — 注册动作

需要新增类似能力，让 agent 子进程可以通过 socket 提供控制器实现（screencap、click、swipe 等回调），PI Client 侧通过 MaaCustomControllerCreate 创建对应的 controller handle。

2. PI V2：controller.type 新增 "Custom"

interface.json 示例：

"controller": [
    {
        "name": "RemoteDevice",
        "label": "远程设备",
        "type": "Custom",
        "custom": {
            "child_exec": "python",
            "child_args": ["./my_controller.py", "--addr", "192.168.1.100:50051"]
        },
        "display_short_side": 720
    }
]

custom 块复用 agent 的 child_exec / child_args 约定。PI Client 启动子进程时追加连接标识，子进程通过该标识注册控制器回调。整体模式和 agent 注册识别/动作一致，只是注册的对象变成控制器。

用户体验

• 项目在 interface.json 中声明 Custom 控制器，和声明 Adb / Win32 一样
• 用户打开 MFAWPF 等 PI Client，能看到并选择 Custom 控制器
• 选中后 PI Client 自动启动子进程、完成控制器注册、加载资源、跑任务
• task / option / preset / resource 等现有功能全部正常工作

兼容性

• 不使用 "type": "Custom" 的项目完全不受影响
• 旧版 PI Client 遇到未知 type 会解析失败（现有行为：Invalid Controller Type → 整个 interface.json 加载失败）。如果项目需要同时兼容旧版 Client，可以在 interface.json 中同时声明内置控制器和 Custom 控制器，或通过 import 拆分
• 不改现有 6 种内置控制器的行为
• 不改 pipeline / resource / task / option 协议

MaaFramework 版本 / Version

v5.10.1

其他信息 / Additional Information

No response

[Zwlin98]

主要想讨论下上游对支持此功能的想法, 后续可以由我可以来做实现

[MistEO]

#1119 有计划的，但是咕咕（）