remote_block_input rejected anything but Windows because the Android client had no COMMAND_SCREEN_BLOCK_INPUT handler. This adds the overlay on the client and the server gating, and wires up COMMAND_SCREEN_BLANK. Client: the accessibility service hangs a full-screen TYPE_ACCESSIBILITY_OVERLAY on itself. block=true makes it transparent and touchable so it swallows physical taps; black=true paints it black. Both are absolute states, so repeated commands are idempotent, and the handler clears the overlay when the screen sub-connection dies (Android has no "released when the calling thread exits" fallback). During a remote gesture the overlay is flipped to FLAG_NOT_TOUCHABLE, mirroring Windows' BlockInput(false) wrap; the flag change and the injection must be separated by a short delay or the gesture is swallowed. Server: CLIENT_CAP_PRIVACY_OVERLAY distinguishes new APKs from old ones; Linux/macOS and old APKs still get -32005 up front. Tool masks, instructions and mcp/tools.json follow the change. COMMAND_SCREEN_BLANK is implemented but not exposed as a tool: MediaProjection captures the overlay, so blacking out the screen blinds the operator too and cannot emulate Windows' WDA_EXCLUDEFROMCAPTURE. Verified on the Android 15 emulator: blocked taps are swallowed while remote clicks still land, the block re-arms after each gesture, the watchdog auto-unblocks at the deadline, a dropped sub-connection clears the overlay, and a black overlay shows up in both screencap and get_screenshot. The committed ghost.apk is stale; rebuild before release. Co-Authored-By: deepseek-flash
MCP 工具清单维护
mcp/tools.json 是 MCP 全部 61 个工具的单一来源候选:工具名、描述、
inputSchema、outputSchema,以及运行时不可见的开关元信息(gate / write / manage)。
它的用途不限于给 Go 服务端复用。当前 26KB 的工具描述埋在 11k 行 C++ 里, 没有人能整体 review 一遍;抽成一份 JSON 后可以 diff、可以搜索、可以一眼看出 哪些工具描述含糊或功能重叠。
文件
| 路径 | 作用 |
|---|---|
mcp/tools.json |
工具清单本体(生成产物,勿手工编辑) |
tools/mcp_tools/dump_tools.py |
从运行中的服务端抓 tools/list |
tools/mcp_tools/make_tools_json.py |
把抓取结果转成 tools.json(含 gate / platforms 表) |
tools/mcp_tools/verify_tools.py |
校验 tools.json 与服务端是否一致 |
tools/mcp_tools/check_platform_table.py |
校验 tools.json 的 platforms 与 C++ kToolPlatforms 一致 |
更新流程
改动 C++ 里的工具定义(McpServer.cpp / McpMachine.cpp / McpChat.cpp)之后:
# 0. 先重编并启动主控端,确保服务端跑的是新代码
cd C:/github/YAMA
# 1. 抓取(token 自动从注册表读;端口自动探测 6545/6544)
python tools/mcp_tools/dump_tools.py "" /tmp/tools_raw.json
# 2. 生成
python tools/mcp_tools/make_tools_json.py /tmp/tools_raw.json mcp/tools.json
# 3. 校验
python tools/mcp_tools/verify_tools.py --live mcp/tools.json
第 3 步输出 PASS: 61 个工具完全一致 才算成功。
如果工具数量变了
make_tools_json.py 里的 GATE 和 PLATFORMS 两张表是手工维护的,新增工具会直接报错退出:
!! GATE 表缺少 1 个工具: ['new_tool']
!! PLATFORMS 表缺少 1 个工具: ['new_tool']
这是有意为之——gate / write / manage 三项在运行时不可见,只能从 C++
注册点的 if 条件读出来,必须人工确认。补表时对照:
McpServer.cpp:BuildToolsListResult—— 内联的 41 个McpMachine.cpp:AppendTools—— 16 个(总开关IsMachineEnabled用 early return)McpChat.cpp:AppendTools—— 4 个(总开关IsChatEnabled用 early return)
PLATFORMS 还要额外核对各平台客户端有没有实现对应命令,见下节。
字段说明
| 字段 | 含义 |
|---|---|
gate |
该工具出现所需的开关(null = 无条件)。取值:machine / chat / terminal / remote_control / file_transfer / file_write / keylog / manage |
write |
需要 !McpReadonly |
manage |
额外需要 McpManage(仅 kill_network_connection 用到) |
platforms |
该工具涉及的任一主机都必须落在此集合内:win / lnx / mac / apk |
roles |
仅多主机工具才有。按参数名细分平台,表达 platforms 说不清的方向性能力 |
impl |
已实现该工具的服务端:mfc / go / both |
gate / write / manage 只描述可见性,不描述行为。像
「McpMachine 开启时 host_list_processes 优先、关闭时退回 list_processes」
这类互斥/降级关系属于逻辑,仍然留在代码里。
platforms 怎么判定
只看各平台客户端有没有实现对应命令,不能看「是否引用了 COMMAND_ 常量」。 两个真实的反例:
android/.../main.cpp里COMMAND_SYSTEM和COMMAND_SHELL都有case分支, 但内容是LOGI("... (not implemented)")—— 引用 ≠ 实现。macos/能处理COMMAND_SEND_FILE_V2,但DefaultCaps()在 macOS 上只给V2|UTF8,没有SCREEN_PREVIEW,所以get_screenshot在 macOS 上仍不可用。
判定时要同时看命令实现和能力位:
| 依据 | 位置 |
|---|---|
| 命令分支 | client/、linux/main.cpp、macos/main.mm、android/app/src/main/cpp/main.cpp |
| 能力位 | common/commands.h 的 LOGIN_INFOR::DefaultCaps();Linux 另在 linux/main.cpp:RefreshLoginCaps 追加 SCREEN_PREVIEW |
当前分布(61 个工具):
| platforms | 数量 | 典型工具 |
|---|---|---|
win+lnx+mac+apk |
10 | 只读写服务端本地数据:list_online_hosts / get_audit_log / mcp_* |
win+lnx+mac |
6 | 进程列表、文件列取、日志、V2 文件传输、copy_files_c2c |
win+lnx |
12 | remote_* 全族、get_screenshot、get_activity_history、exec_command / terminal_* / kill_process |
win |
33 | 服务 / 注册表 / 键日志 / 文件写 / list_windows / get_foreground_window / host_* / chat_* / power_action |
注意 exec_command / terminal_* / kill_process 不在 win+lnx+mac 组:
macOS 客户端其实有对应实现(macos/main.mm:753 的 ShellworkingThread 跑 PTY,
SystemManager.mm 有 COMMAND_KILLPROCESS 分支),但服务端刻意拦着
(McpServer.cpp:3652 注释「macOS 本轮不开放」、6870)。平台表按实际行为标,
不按客户端能力标。
list_windows 只有 Windows 可用,这个坑很隐蔽:Linux 的
SystemManager.h:38 和 macOS 的 SystemManager.mm:39 都有 COMMAND_WSLIST
的 case 分支,看起来是支持的。但 BuildListWindows 把命令发在主连接上
(McpServer.cpp:2931),而这两个平台的主循环只处理 COMMAND_SYSTEM
(起 SystemManager 子连接),WSLIST 在子连接里才被处理——走不到。实测 Linux
上直接超时 -32001。那两个 case 是给 SystemDlg 窗口管理用的,不是 MCP 这条路径。
Windows 是在主循环里处理的(client/KernelManager.cpp:1491),所以正常。
平台优先级(产品定位)
支持面是刻意设计的阶梯,不是历史遗留:
| 平台 | 覆盖 | 定位 |
|---|---|---|
| win | 60 / 60 (100%) | 唯一全量支持的平台,所有工具都以它为准 |
| lnx | 27 / 60 (45%) | 第二梯队,桌面场景基本可用 |
| mac | 16 / 60 (27%) | 第三梯队 |
| apk | 10 / 60 (17%) | 第三梯队,仅服务端本地类工具 |
check_platform_table.py 把「Windows 全量」做成了不变式:任何工具缺 win
直接报错,同时检查 win >= lnx >= mac/apk 的阶梯不倒挂。新增工具时若只标了
lnx,脚本会拦下。
判断平台归属时以 Windows 为基线:先确认它在 Windows 上成立,再逐级确认
Linux、macOS、Android。反过来做(从 Android 往上推)容易把「客户端有实现」
误当成「服务端放行」——exec_command 在 macOS 上就是这种情况。
注意 exec_command / terminal_* / kill_process 不在 win+lnx+mac 组:
macOS 客户端其实有对应实现(macos/main.mm:753 的 ShellworkingThread 跑 PTY,
SystemManager.mm 有 COMMAND_KILLPROCESS 分支),但服务端刻意拦着
(McpServer.cpp:3652 注释「macOS 本轮不开放」、6870)。平台表按实际行为标,
不按客户端能力标——将来开放这几项时,要同时改表、roles 无关、和 instructions。
make_tools_json.py 会做一致性检查:描述里声称「仅 Windows」但 platforms 含
其他平台时直接报错,防止描述与事实再次漂移。
方向性能力(roles)
platforms 是无序集合,只能表达「任一参与端都落在这个集合内」。
copy_files_c2c 两端的要求不同,单靠它表达不了:
"platforms": ["win", "lnx", "mac"],
"roles": {
"src_id": ["win"],
"dst_id": ["win", "lnx", "mac"]
}
依据是 McpServer.cpp:6591-6609:
- 源端只有 Windows 实现了 C2C 发送逻辑(
client/KernelManager.cpp), 代码对LNX/MAC直接返回-32005 - 目标端只需
CLIENT_CAP_V2收包,posixDst分支专门处理 LNX/MAC 的路径形态 (接收端把\归一化成/后按绝对路径落盘)
Linux / macOS 只能当接收方,不能当发送方。 这是当前唯一的非对称工具。
新增同类工具时,platforms 填两端并集,方向性写进 roles,并在 C++ 的
CollectTargetReqs 里同步一份 AddIdReq —— check_platform_table.py 会校验
tools.json / C++ / 脚本三方一致。
与 instructions 的对应
server/2015Remote/McpServer.cpp 的 kServerInstructions 第 5 节(客户端平台差异)
是这份矩阵的面向模型的摘要。改 PLATFORMS 时同步改那一节,否则模型看到的
说明会和数据不一致。
运行时门禁
platforms 不只是文档,它还被编进 McpServer.cpp 的 kToolPlatforms 表,
由 DispatchSingleHostTool 开头的 CheckToolPlatform 执行硬校验:
平台不匹配时直接返回 -32005,不会下发命令也不会白等超时。
批量调用走 BuildBatchCall → DispatchSingleHostTool,自动被覆盖。
门禁需要从入参里拿到目标主机 id 才能判断平台。绝大多数工具用 id,
copy_files_c2c 用 src_id / dst_id(两端都查)——这是目前唯一的例外,
由 C++ 的 CollectTargetIds 处理。新增受限平台的工具时,如果入参里没有 id,
必须在 CollectTargetIds 和 check_platform_table.py 的 ID_ALIASES 两处同时登记,
否则门禁会静默放行。check_platform_table.py 会检查这件事。
总开关:McpPlatformGuard(默认 1),关掉后 CheckToolPlatform 直接返回放行。
python tools/mcp_tools/check_platform_table.py
# PASS: 61 个工具的 platforms 两边完全一致,且门禁都能拿到主机 id
与 Go 服务端的关系
impl 字段就是给 Go 端裁剪用的:标 mfc 的工具表示 Go 端还没有对应能力。
Go 端补齐某个工具的底层命令后,把它改成 both。
注意 Go 端目前只有 5 类客户端命令(SCREEN_SPY / NEXT / SCREEN_CONTROL /
BYE / SHELL),所以短期内 impl: both 的工具不会多。
前置条件
- 服务端在运行(
McpEnabled=1) - Release 版读注册表
HKCU\Software\YAMA\settings,Debug 版读<exe目录>\settings.ini—— 抓不到工具时先确认跑的是哪个构建 - 抓取时所有开关都应为开,否则拿到的是子集而非全集