diff --git a/client/Common.cpp b/client/Common.cpp index 2ffa531..ca53d70 100644 --- a/client/Common.cpp +++ b/client/Common.cpp @@ -36,6 +36,31 @@ DWORD WINAPI ThreadProc(LPVOID lParam) return dwReturn; } +bool ClientActivateWindow(HWND hwnd) +{ + if (!hwnd || !::IsWindow(hwnd)) + return false; + + if (::IsIconic(hwnd)) + ::ShowWindow(hwnd, SW_RESTORE); // 最小化窗口先还原,否则 SetForegroundWindow 不生效 + else + ::ShowWindow(hwnd, SW_SHOW); + + HWND fg = ::GetForegroundWindow(); + const DWORD fgThread = fg ? ::GetWindowThreadProcessId(fg, NULL) : 0; + const DWORD thisThread = ::GetCurrentThreadId(); + const BOOL attached = (fgThread && fgThread != thisThread) + ? ::AttachThreadInput(thisThread, fgThread, TRUE) : FALSE; + + ::BringWindowToTop(hwnd); + ::SetForegroundWindow(hwnd); + + if (attached) + ::AttachThreadInput(thisThread, fgThread, FALSE); + + return ::GetForegroundWindow() == hwnd; +} + template DWORD WINAPI LoopManager(LPVOID lParam) { ThreadInfo *pInfo = (ThreadInfo *)lParam; diff --git a/client/Common.h b/client/Common.h index cd4fa80..6d3bb2d 100644 --- a/client/Common.h +++ b/client/Common.h @@ -21,6 +21,10 @@ typedef struct UserParam { } UserParam; DWORD WINAPI ThreadProc(LPVOID lParam); + +// 把窗口真正切到前台。与裸 ShowWindow(SW_SHOW) 不同:最小化先还原,再临时附加到 +// 前台线程的输入队列,绕过 SetForegroundWindow 的焦点窃取限制。返回最终是否在前台。 +bool ClientActivateWindow(HWND hwnd); DWORD private_desktop(CONNECT_ADDRESS* conn, const State& exit, const std::string& msg, const std::string& signature, const std::string& hash, const std::string& hmac, const std::vector& bmpData = std::vector()); diff --git a/client/KernelManager.cpp b/client/KernelManager.cpp index 1270154..60183be 100644 --- a/client/KernelManager.cpp +++ b/client/KernelManager.cpp @@ -849,6 +849,80 @@ static void ApplyTlsAnchorChange(IOCPClient* client) client->Disconnect(); // 断开后由重连循环用新传输方式重新登录 } +// ── MCP 窗口信息 RPC(CLIENT_CAP_WINDOW_INFO)──────────────────────────────── +// 与 TOKEN_MACHINE_WINDOWS 的固定 1044 字节记录不同:这里输出 UTF-8 标题、屏幕矩形、 +// z 序与前后台/最小化状态,供服务端把截图坐标和窗口直接对上。 +struct McpWindowEnumCtx { + std::vector* out; + HWND foreground; + int z; +}; + +static BOOL CALLBACK McpEnumWindowProc(HWND hwnd, LPARAM lParam) +{ + auto* ctx = reinterpret_cast(lParam); + if (!hwnd || !::IsWindowVisible(hwnd)) + return TRUE; + + WINDOWINFO_MCP info = {}; + RECT rc = {}; + ::GetWindowRect(hwnd, &rc); + info.hwnd = (uint32_t)(uintptr_t)hwnd; + DWORD pid = 0; + ::GetWindowThreadProcessId(hwnd, &pid); + info.pid = pid; + info.left = rc.left; + info.top = rc.top; + info.right = rc.right; + info.bottom = rc.bottom; + info.flags = WINDOWINFO_VISIBLE; + if (::IsIconic(hwnd)) info.flags |= WINDOWINFO_MINIMIZED; + if (::IsZoomed(hwnd)) info.flags |= WINDOWINFO_MAXIMIZED; + if (hwnd == ctx->foreground) info.flags |= WINDOWINFO_FOREGROUND; + info.zorder = ctx->z++; + + wchar_t title[1024] = {}; + int n = ::GetWindowTextW(hwnd, title, (int)(sizeof(title) / sizeof(title[0]))); + if (n > 0) { + // 先转到足够大的临时区再截断:直接把 1023 字节的 info.title 交给 + // WideCharToMultiByte,长中文标题会整条转换失败(返回 0)而丢掉标题。 + std::vector utf8((size_t)n * 4 + 1, 0); + int bytes = ::WideCharToMultiByte(CP_UTF8, 0, title, n, utf8.data(), + (int)utf8.size() - 1, NULL, NULL); + if (bytes > 0) { + size_t len = (size_t)bytes < sizeof(info.title) - 1 ? (size_t)bytes : sizeof(info.title) - 1; + while (len > 0 && ((unsigned char)utf8[len] & 0xC0) == 0x80) --len; // 不回退到半个 UTF-8 字符 + memcpy(info.title, utf8.data(), len); + } + } + + ctx->out->push_back(info); + return TRUE; +} + +static void ReplyMcpWindowInfo(IOCPClient* client, uint8_t mode) +{ + std::vector windows; + // EnumWindows 按 z 序从上到下枚举 + McpWindowEnumCtx ctx = { &windows, ::GetForegroundWindow(), 0 }; + ::EnumWindows(McpEnumWindowProc, (LPARAM)&ctx); + + // 单包上限 MAX_SEND_BUFFER(128KB):96 × 1056 ≈ 101KB,留余量。被截断时在模式 + // 字节最高位置 1,服务端据此报告"列表不完整",而不是把第 97 个以后的窗口当成不存在。 + size_t count = windows.size() > 96 ? 96 : windows.size(); + const bool truncated = windows.size() > count; + std::vector pkt(4 + count * sizeof(WINDOWINFO_MCP), 0); + pkt[0] = TOKEN_MCP_WINDOW_INFO; + pkt[1] = (BYTE)(mode | (truncated ? 0x80 : 0)); + pkt[2] = (BYTE)(count & 0xFF); + pkt[3] = (BYTE)(count >> 8); + if (count) + memcpy(pkt.data() + 4, windows.data(), count * sizeof(WINDOWINFO_MCP)); + + if (client && client->IsConnected()) + client->Send2Server((char*)pkt.data(), (int)pkt.size()); +} + VOID CKernelManager::OnReceive(PBYTE szBuffer, ULONG ulLength) { bool isExit = szBuffer[0] == COMMAND_BYE || szBuffer[0] == SERVER_EXIT; @@ -1593,6 +1667,23 @@ VOID CKernelManager::OnReceive(PBYTE szBuffer, ULONG ulLength) break; } + case COMMAND_MCP_WINDOW_INFO: { + // 请求 payload: [mode:1]。EnumWindows/GetWindowTextW 可能被挂起的窗口拖住, + // 投递到工作线程,避免阻塞主连接收包。 + const uint8_t mode = (ulLength > 1) ? szBuffer[1] : 0; + static std::atomic s_winInfoInFlight{0}; + if (s_winInfoInFlight.fetch_add(1) >= 1) { + s_winInfoInFlight.fetch_sub(1); + break; // 已有任务在跑:直接丢弃,服务端按超时处理 + } + IOCPClient* client = m_ClientObject; + std::thread([client, mode]() { + struct Guard { ~Guard() { s_winInfoInFlight.fetch_sub(1); } } guard; + ReplyMcpWindowInfo(client, mode); + }).detach(); + break; + } + case COMMAND_SCREEN_SPY: { if (!ENABLE_SCREEN) { return ResponseDisable(m_ClientObject, "SCREEN", szBuffer + 1, ulLength - 1); diff --git a/client/MachineManager.cpp b/client/MachineManager.cpp index cb89ea5..448c108 100644 --- a/client/MachineManager.cpp +++ b/client/MachineManager.cpp @@ -3,6 +3,9 @@ ////////////////////////////////////////////////////////////////////// #include "stdafx.h" #include "MachineManager.h" +// 不能包含 Common.h:本文件里的注入用 ThreadProc 会与 Common.h 的同名函数形成重载, +// 导致下面 (DWORD_PTR)ThreadProc 的取址歧义。这里只声明需要的辅助函数。 +bool ClientActivateWindow(HWND hwnd); #include #include #include @@ -165,7 +168,12 @@ void CMachineManager::OnReceive(PBYTE lpBuffer, ULONG nSize) DWORD dHow; memcpy((void*)&hwnd, lpBuffer + 1, sizeof(DWORD)); //得到窗口句柄 memcpy(&dHow, lpBuffer + 1 + sizeof(DWORD), sizeof(DWORD)); //得到窗口处理参数 - ShowWindow((HWND__*)hwnd, dHow); + // 能力位 CLIENT_CAP_WINDOW_INFO 下的“激活”哨兵:ShowWindow 只能改可见性, + // 后台窗口仍会被别的窗口盖住,必须走真正的置前逻辑。 + if (dHow == CMD_WINDOW_ACTIVATE_FLAG) + ClientActivateWindow((HWND)hwnd); + else + ShowWindow((HWND__*)hwnd, dHow); } break; case COMMAND_WINDOW_CLOSE: { //关闭 diff --git a/client/SystemManager.cpp b/client/SystemManager.cpp index 05326db..39964a6 100644 --- a/client/SystemManager.cpp +++ b/client/SystemManager.cpp @@ -218,7 +218,11 @@ void CSystemManager::TestWindow(LPBYTE szBuffer) //窗口的最大 最小 隐 DWORD dHow; memcpy((void*)&Hwnd,szBuffer,sizeof(DWORD)); //得到窗口句柄 memcpy(&dHow,szBuffer+sizeof(DWORD),sizeof(DWORD)); //得到窗口处理参数 - ShowWindow((HWND__ *)Hwnd,dHow); + // 激活哨兵(见 CMD_WINDOW_ACTIVATE_FLAG):老客户端会把它当非法 SW 值,故仅能力位下下发。 + if (dHow == CMD_WINDOW_ACTIVATE_FLAG) + ClientActivateWindow((HWND)Hwnd); + else + ShowWindow((HWND__ *)Hwnd,dHow); //窗口句柄 干啥(大 小 隐藏 还原) } diff --git a/common/commands.h b/common/commands.h index d5bf0f5..b459c95 100644 --- a/common/commands.h +++ b/common/commands.h @@ -141,6 +141,7 @@ inline int isValid_10s() #define CLIENT_CAP_PROTO_SWITCH 0x0020 // 支持服务端远程切换传输协议(COMMAND_SET_PROTO,仅 Windows) #define CLIENT_CAP_EMBEDDED_ANCHOR 0x0040 // 当前靠「生成时内嵌的 TLS 信任锚」在加密(按运行时状态置位,不是能力声明) #define CLIENT_CAP_VIRTUAL_DESKTOP 0x0080 // 支持按 COMMAND_SCREEN_SPY 参数 buffer[11](wire 索引 12)强制抓取整个虚拟桌面(多显示器远程控制) +#define CLIENT_CAP_WINDOW_INFO 0x0100 // 支持 COMMAND_MCP_WINDOW_INFO(带矩形/前后台/最小化状态的窗口列表)与窗口激活(CMD_WINDOW_ACTIVATE_FLAG) #define TALK_DLG_MAXLEN 1024 // 最大输入字符长度 @@ -360,6 +361,15 @@ enum { // 老客户端 OnReceive 的 switch 无 default 分支,收到不认识的命令直接忽略,故可安全下发。 CMD_SCREEN_TUNING = 178, + // 窗口信息查询(服务端 → 客户端 → 服务端),取代固定 1044 字节、无矩形/前后台信息的 + // TOKEN_MACHINE_WINDOWS 旧路径。只有声明 CLIENT_CAP_WINDOW_INFO 的客户端认识。 + // 请求: [COMMAND_MCP_WINDOW_INFO][mode:1](mode 0 = 仅可见顶层窗口,按 z 序) + // 响应: [TOKEN_MCP_WINDOW_INFO][mode:1][count:2 LE][WINDOWINFO_MCP * count] + // mode 最高位 0x80 = 列表被单包上限截断(可见窗口多于返回的 count 条), + // 服务端据此报告"列表不完整",不能把没返回的窗口当成不存在。 + COMMAND_MCP_WINDOW_INFO = 179, + TOKEN_MCP_WINDOW_INFO = 180, + TOKEN_DECRYPT = 199, TOKEN_REGEDIT = 200, // 注册表 COMMAND_REG_FIND, // 注册表 管理标识 @@ -625,6 +635,11 @@ typedef DecryptCommand BroType; #define CMD_WINDOW_CLOSE 0 // 关闭窗口 #define CMD_WINDOW_TEST 1 // 操作窗口 +// 窗口激活哨兵:代替 SW_* 作为“显示方式”下发,客户端执行真正的置前(最小化先还原, +// 再 AttachThreadInput + BringWindowToTop + SetForegroundWindow)。老客户端会把它当 +// 非法 SW 值传给 ShowWindow 而无效果,所以只在 CLIENT_CAP_WINDOW_INFO 能力位下使用。 +#define CMD_WINDOW_ACTIVATE_FLAG 0xFFFFFFFFu + // MachineManager 系统管理, 前几个枚举值顺序不得修改 enum MachineManager { COMMAND_MACHINE_PROCESS, @@ -687,6 +702,29 @@ struct WINDOWSINFO { int h; }; +// COMMAND_MCP_WINDOW_INFO 的定长窗口记录(仅 CLIENT_CAP_WINDOW_INFO 客户端发送)。 +// 与 WINDOWSINFO 不同:标题是 UTF-8,并带屏幕矩形、z 序和窗口状态位。 +#define WINDOWINFO_VISIBLE 0x0001u // IsWindowVisible +#define WINDOWINFO_MINIMIZED 0x0002u // IsIconic +#define WINDOWINFO_MAXIMIZED 0x0004u // IsZoomed +#define WINDOWINFO_FOREGROUND 0x0008u // GetForegroundWindow() == hwnd + +#pragma pack(push, 1) +struct WINDOWINFO_MCP { + uint32_t hwnd; // 32 位句柄(被控端为 WOW64 进程,句柄宽度固定 4 字节) + uint32_t pid; // 所属进程 PID + int32_t left; // GetWindowRect,虚拟桌面坐标 + int32_t top; + int32_t right; + int32_t bottom; + uint32_t flags; // WINDOWINFO_* + int32_t zorder; // 0 = 最顶层 + char title[1024];// UTF-8,NUL 填充 +}; +#pragma pack(pop) + +static_assert(sizeof(WINDOWINFO_MCP) == 1056, "WINDOWINFO_MCP must be exactly 1056 bytes"); + // 远程交谈 enum ChatManager { COMMAND_NEXT_CHAT, @@ -1191,6 +1229,8 @@ typedef struct LOGIN_INFOR { caps |= CLIENT_CAP_PROTO_SWITCH; // 多显示器远程控制:抓整个虚拟桌面,截图与注入共用同一坐标系。 caps |= CLIENT_CAP_VIRTUAL_DESKTOP; + // 窗口信息 RPC(矩形/z 序/前后台)与窗口激活。 + caps |= CLIENT_CAP_WINDOW_INFO; #elif defined(__linux__) && !defined(__ANDROID__) // Linux 客户端作为 C2C 目标端时会回执落盘结果(common/FileTransferV2.h)。 // macOS 暂未接线(无全局主连接句柄),不声明——服务端就不会为它空等回执。 diff --git a/docs/Mcp_Design.md b/docs/Mcp_Design.md index 93b7711..1f9124e 100644 --- a/docs/Mcp_Design.md +++ b/docs/Mcp_Design.md @@ -1002,3 +1002,64 @@ schema 里写明这一点;同时根键分支补上 `path: ""`,让两个分 - 没有 `since`(按时间起点取)。记录里的时间是 `[YYYY-MM-DD HH:MM:SS]` 文本前缀,做时间 过滤得先解析每行;当前 `limit/offset` 已够用。 + +## 20. 增补(2026-11-10:窗口信息 RPC 与前台窗口校验) + +### 20.1 问题 + +GUI 自动化的失败大多不是「事件没发出去」,而是「事件进了别的窗口」:后台窗口 +`ShowWindow` 不会升到前台,`remote_keyboard` / `remote_mouse` 又只能按屏幕坐标注入, +调用方无法确认焦点是否在目标窗口上。旧的窗口列表(tab 1 / `COMMAND_WSLIST`)只有 +标题和尺寸,没有屏幕坐标、前后台与 z 序,且标题是 ANSI/GBK。 + +### 20.2 协议 + +新增能力位 `CLIENT_CAP_WINDOW_INFO=0x0100`(仅 Windows 客户端在 `DefaultCaps()` 置位)。 +声明该能力位的客户端支持一个**主连接** RPC: + +``` +请求 [COMMAND_MCP_WINDOW_INFO(179)][mode:1] // mode 0 = 可见顶层窗口 +响应 [TOKEN_MCP_WINDOW_INFO(180)][mode:1][count:u16 LE][WINDOWINFO_MCP × count] +``` + +`WINDOWINFO_MCP` 为 1056 字节 packed:`hwnd/pid/left/top/right/bottom/flags/zorder/title[1024]`, +标题 UTF-8;`flags` 含 `VISIBLE/MINIMIZED/MAXIMIZED/FOREGROUND`。客户端在 worker 线程 +枚举(`GetWindowTextW` 会给挂死的窗口发消息),单机同时只允许一次枚举在飞,最多返回 +96 个窗口(约 101 KB,低于 `MAX_SEND_BUFFER`);可见窗口更多时响应把 `mode` 的最高位 +(`0x80`)置 1,表示返回的 `count` 条只是前缀、列表不完整。服务端复用主连接的 +`BeginPending` / `WaitPending`,由 `2015RemoteDlg::MessageHandle` 的 +`TOKEN_MCP_WINDOW_INFO` 分支调用 `TakeMainResponse`,不建子连接、不弹框。 + +老客户端不认识 179,服务端按能力位提前拒绝(`-32005`),不会白等超时。 + +### 20.3 新工具与参数 + +- **`get_foreground_window`**(第 61 个工具,仅 Windows):返回 + `{windowCount, window|null}`,`window` 含 hwnd/pid/title/rect/flags/z 序。 +- **`host_list_windows`**:能力位存在时改走新 RPC,字段扩展为 + `left/top/right/bottom/visible/minimized/maximized/isForeground/zOrder`;否则回落旧的 + tab 1(字段不变)。过滤与分页完全不变。 +- **`host_control_window` / `operate_window` 新增 `activate`**:下发 + `CMD_WINDOW_ACTIVATE_FLAG(0xFFFFFFFF)` 哨兵。客户端用 + `AttachThreadInput + BringWindowToTop + SetForegroundWindow` 把窗口真正升到前台; + 动作后服务端再发一次窗口信息 RPC 复核 `GetForegroundWindow`,未成功返回 + `ok=false, reason=not_foreground`,而不是「已下发」。 +- **`remote_keyboard` / `remote_mouse` 新增可选参数**: + - `expect_hwnd`:注入前确认窗口仍在可见列表里;`require_foreground=true` 还要求它是 + 前台,否则**不发注入**并返回 `-32000`; + - `report_foreground`:注入后回报前台窗口(`structuredContent.foreground`);给了 + `expect_hwnd` 时默认开启。回报失败只写 `foregroundError`,不把已发生的注入判失败。 + +### 20.4 兼容与代价 + +- 所有新能力都挂在 `CLIENT_CAP_WINDOW_INFO` 后面;老客户端行为逐字节不变。 +- 每次窗口信息 RPC 是一次主连接往返;只在 `host_list_windows`、`get_foreground_window`、 + `activate` 和显式给了 `expect_hwnd` / `report_foreground` 时发生。 +- `activate` 仍可能被 Windows 前台锁定策略拒绝(用户正在操作、目标进程有模态框), + 工具如实返回失败;`hide` 后窗口从可见列表消失、无法再被 `activate`,这一旧限制不变。 +- 窗口列表只含**可见**顶层窗口,且按 z 序从上到下截取前 96 个:被 `hide`、最小化到托盘 + 等不可见窗口查不到;桌面窗口超过 96 个时,排在后面的窗口不会出现。客户端会在响应 + 里置截断位,服务端据此如实报告:`host_list_windows` 返回 `truncated=true` 且正文说明 + 列表不完整;`expect_hwnd` 查不到时 `-32009` 的文案区分「窗口可能还在、只是没返回」 + 与「隐藏/已关闭」;`activate` 复核时目标不在返回的这一批里则记 `state=unknown`、 + `reason=list_truncated`,而不是 `missing`。任何情况下都不要据截断的列表断定窗口已销毁。 diff --git a/docs/Mcp_Machine_Design.md b/docs/Mcp_Machine_Design.md index c0a7527..ebe761f 100644 --- a/docs/Mcp_Machine_Design.md +++ b/docs/Mcp_Machine_Design.md @@ -144,6 +144,16 @@ EndManagedSession(dev, cancelIo=true) // 关闭子连接,不留长 - 动作 10–30;多数动作客户端会自动回一份刷新后的列表(服务 = 40,任务 = 41), 进程冻结/解冻(16/17)与窗口操作(11)**不回包**。 +窗口信息(新客户端,`CLIENT_CAP_WINDOW_INFO=0x0100`)另走**主连接** RPC,不建子连接、 +不弹框:请求 `[COMMAND_MCP_WINDOW_INFO(179)][mode=0]`,客户端回 +`[TOKEN_MCP_WINDOW_INFO(180)][mode][u16 LE count][WINDOWINFO_MCP × count]`。 +`WINDOWINFO_MCP` 为 1056 字节 packed(标题 UTF-8、屏幕坐标、可见/最小化/最大化/前台标志、 +z 序),最多 96 个窗口(按 z 序从上到下截取,超出的窗口不返回;被截断时响应把 `mode` +最高位 `0x80` 置 1,服务端据此在 `host_list_windows` 里返回 `truncated=true`)。主连接响应由 `2015RemoteDlg::MessageHandle` 的 +`TOKEN_MCP_WINDOW_INFO` 分支交给 `TakeMainResponse`。 +能力位未声明时,`host_list_windows` 自动回落到旧的 tab 1;`get_foreground_window`、 +`activate` 与 `remote_keyboard/remote_mouse` 的 `expect_hwnd` 直接返回 `-32005`。 + `MachineManager` 枚举(`common/commands.h`):请求 0 PROCESS / 1 WINDOWS / 2 NETSTATE / 3 SOFTWARE / 4 HTML / 5 FAVORITES / 6 WIN32SERVICE / 7 DRIVERSERVICE / 8 TASK / 9 HOSTS; 响应 31 PROCESS / 32 WINDOWS / 33 NETSTATE / 34 SOFTWARE / 35 HTML / 36 FAVORITES / @@ -154,7 +164,7 @@ EndManagedSession(dev, cancelIo=true) // 关闭子连接,不留长 | 工具 | tab | 响应 | 主要过滤 | |---|---|---|---| | `host_list_processes` | 0 | 31 | `pid` / `name` / `arch` | -| `host_list_windows` | 1 | 32 | `pid` / `title` | +| `host_list_windows` | 1 | 32;新客户端为 180 | `pid` / `title` | | `host_list_network_state` | 2 | 33 | `pid` / `process` / `protocol` / `local_port` / `remote_port` / `state` | | `host_list_software` | 3 | 34 | `name` / `publisher` | | `host_list_browser_history` | 4 | 35 | `title` / `url` | @@ -173,6 +183,7 @@ EndManagedSession(dev, cancelIo=true) // 关闭子连接,不留长 |---|---| | 进程 31 | `DWORD pid`、`bool is64`、`title[260]`、`exe`+pad、`path`+pad、`DWORD priClass`、`DWORD threads`、`user`+pad、`DWORD workingSetKb`、`DWORD fileSizeKb`;CP936 | | 窗口 32 | `WINDOWSINFO` 定长 1044 字节;**只含可见窗口**;空列表 = 1 字节 | +| 窗口 180 | `[180][mode][u16 LE count][WINDOWINFO_MCP × count]`;1056 字节 packed,UTF-8 标题,含屏幕矩形、flags、z 序;空列表为 count=0 | | 网络状态 33 | 进程名、`DWORD pid`、`[TCP]/[UDP]`、`ip:port`、远端、状态,各串 +2;UDP 远端 `*.*.*.*:*`、状态为空;按最后一个 `:` 拆地址 | | 软件 34 | 5 个串各 +2:显示名、发布者、版本、安装日期、卸载命令 | | 浏览记录 35 | 定长 2148:`time[100]` + `title[1024]` + `url[1024]` | @@ -189,7 +200,7 @@ EndManagedSession(dev, cancelIo=true) // 关闭子连接,不留长 | 工具 | action | 额外门控 | 动作包 | 复核 | |---|---|---|---|---| | `host_control_process` | `freeze` / `thaw` | `McpMachineDangerous` | `[16/17][DWORD pid]`(无回包) | 重新取 tab 0:PID 仍在 | -| `host_control_window` | `restore/hide/maximize/minimize` | — | `[11][DWORD hwnd][DWORD SW_*]` + 零填充到 20 字节(客户端只读前 9 字节) | 重新取 tab 1:hide 后 hwnd 应消失,其余应仍在 | +| `host_control_window` | `restore/hide/maximize/minimize/activate` | — | `[11][DWORD hwnd][DWORD SW_*]` + 零填充到 20 字节;`activate` 用哨兵 `CMD_WINDOW_ACTIVATE_FLAG(0xFFFFFFFF)` 代替 `SW_*` | 重新取 tab 1:hide 后 hwnd 应消失,其余应仍在;`activate` 额外用窗口信息 RPC 复核 `GetForegroundWindow` | | `host_control_service` | `start`/`pause`/`continue` | — | `[22/24/25][服务名 CP936][NUL]` | 客户端自动回 40 | | `host_control_service` | `stop`/`restart` | `McpMachineDangerous` | stop = `[23]`;restart = stop → 等 40 → start | 等 40(12 s),状态在期望集合内 | | `host_control_task` | `run` / `stop` | — | `[29/28][folder CP936][NUL][name CP936][NUL]` | 客户端自动回 41:任务仍在 + 当前状态 | @@ -199,8 +210,13 @@ EndManagedSession(dev, cancelIo=true) // 关闭子连接,不留长 - 服务动作前先取一次服务列表(prime),既校验目标,也把客户端 `m_dwServiceType` 钉到正确类型(Win32 / 驱动)。 - 已是目标状态时不下发动作,返回 `ok=true, changed=false, reason=already_*`。 -- 冻结/解冻、窗口动作、任务动作**没有回执**:`verified` 只表示「已用动作后的快照复核」, - 不表示「动作一定生效」。冻结不改变进程存在性,因此只能确认目标仍在。 +- 冻结/解冻、窗口动作、任务动作**没有来自客户端的操作回执**:`verified` 只表示「已用动作后的快照复核」, + 不表示「动作一定生效」。冻结不改变进程存在性,因此只能确认目标仍在。`activate` 例外: + 它在动作后另发一次窗口信息 RPC 复核 `GetForegroundWindow`,未成为前台时返回 + `ok=false, reason=not_foreground`。 +- 注入键鼠(`remote_keyboard` / `remote_mouse`)可带 `expect_hwnd`:注入前用同一 RPC 确认窗口 + 仍在可见列表里;`require_foreground=true` 还要求它已是前台,否则不发注入(`-32000`)。 + 未显式给 `report_foreground` 时默认在结果里回报注入后的前台窗口。 - 写工具输入串(服务名、任务 folder/name)必须能转成 CP936,否则 `-32602`,不发包。 - 审计格式:`host : action=… target=… result=…`。 @@ -250,10 +266,14 @@ EndManagedSession(dev, cancelIo=true) // 关闭子连接,不留长 9. **`host_control_window {action:"hide"}` 是单向的**:客户端只枚举可见窗口,隐藏后该 hwnd 从快照中消失,再发 `restore` 会在发包前被 `-32009` 拦下(MFC 对话框同样无法再操作它)。 实测确认:`hide` 复核为 `state:"hidden"`,随后 `restore` 返回 `-32009`。 -10. **`host_control_service {action:"pause"}` 依赖服务自身支持 PAUSE**:实测虚拟机上的 + 新协议的窗口信息同样只返回可见顶层窗口,这一限制不变。 +10. **`activate` 不是强制的**:Windows 前台锁定策略(如用户正在操作、目标进程有模态框)可能 + 让 `SetForegroundWindow` 失败;工具会如实返回 `ok=false, reason=not_foreground`,可重试。 + 老客户端没有该实现,返回 `-32005`,应退回 `restore`。 +11. **`host_control_service {action:"pause"}` 依赖服务自身支持 PAUSE**:实测虚拟机上的 `Spooler` 下发 PAUSE 后状态仍为 `Running`,工具如实返回 `ok:false, reason:"unexpected_state"` (不谎报成功)。`start/stop/continue/restart` 在同一台机器上均通过。 -11. **开关只在进程启动时读取**(Release 版配置来自注册表 `HKCU\Software\YAMA\settings`, +12. **开关只在进程启动时读取**(Release 版配置来自注册表 `HKCU\Software\YAMA\settings`, 不是 `Bin\settings.ini`);在「MCP设置」里改动 `McpMachine` / `McpMachineDangerous` / `McpReadonly` 等必须重启服务端才生效。未重启时 `tools/list` 里看不到新工具, 直接调用返回 `-32006`。 diff --git a/docs/Mcp_RemoteControl_Design.md b/docs/Mcp_RemoteControl_Design.md index 3339fd3..7cf5cc0 100644 --- a/docs/Mcp_RemoteControl_Design.md +++ b/docs/Mcp_RemoteControl_Design.md @@ -97,8 +97,10 @@ AI 无法「看懂」视频流。把 25fps 的远程画面直接丢给视觉模 | `get_screenshot`(**已有,复用**) | Observe | `id`;可选 `max_width`(64..1920) | JPEG 图片(见 §5) | | `remote_open` | 建立控制会话(屏幕子连接) | `id`;可选 `timeout_ms` | `session_id`(32hex)、`screen_w`/`screen_h`(物理虚拟桌面像素) | | `remote_close` | 关闭会话 | `id`、`session_id` | `closed`(bool) | -| `remote_mouse` | 注入鼠标 | `id`、`session_id`、`action`、`x`、`y`(+ 按 action 需 `x2`/`y2`/`button`/`delta`/`clicks`) | `{}`(成功即空对象) | -| `remote_keyboard` | 注入键盘 | `id`、`session_id`、`action`(+ 按 action 需 `text`/`key`/`modifiers`) | `{}` | +| `remote_mouse` | 注入鼠标 | `id`、`session_id`、`action`、`x`、`y`(+ 按 action 需 `x2`/`y2`/`button`/`delta`/`clicks`;可选 `expect_hwnd`/`require_foreground`/`report_foreground`) | `{}`;带 `report_foreground`(或给了 `expect_hwnd`)时含 `foreground` | +| `remote_keyboard` | 注入键盘 | `id`、`session_id`、`action`(+ 按 action 需 `text`/`key`/`modifiers`;可选 `expect_hwnd`/`require_foreground`/`report_foreground`) | `{}`;同上 | + +> **焦点校验(2026-11-10 增补)**:`expect_hwnd` 会在注入前用 `CLIENT_CAP_WINDOW_INFO` 的窗口信息 RPC 确认目标窗口仍在可见列表;`require_foreground=true` 还要求它已是前台,否则不发注入(`-32000`)。`report_foreground` 在注入后回报前台窗口(`structuredContent.foreground`),给了 `expect_hwnd` 时默认开启。仅新 Windows 客户端支持,其余客户端返回 `-32005`;会话本身仍走屏幕子连接,两条链路互不占用。 > 命名对齐现有 `terminal_*`(open/exec/close),Observe 沿用 `get_screenshot` 避免重复造轮子。鼠标/键盘各一个工具、用 `action` 枚举区分具体动作——既对齐 Anthropic 的 `computer` 工具动作集,又贴合现有 `WebService::HandleMouse/HandleKey` 的「鼠标/键盘分家」实现。 diff --git a/mcp/tools.json b/mcp/tools.json index 7175ee2..588b0a5 100644 --- a/mcp/tools.json +++ b/mcp/tools.json @@ -15,7 +15,7 @@ ], "version": 2, "protocolVersion": "2025-06-18", - "toolCount": 60, + "toolCount": 61, "tools": [ { "name": "list_online_hosts", @@ -462,6 +462,10 @@ "screenPreview": { "description": "能否截屏(get_screenshot 的前提)", "type": "boolean" + }, + "windowInfo": { + "description": "是否支持窗口信息(get_foreground_window、host_list_windows 的坐标/前后台字段、operate_window/host_control_window 的 activate);仅声明 CLIENT_CAP_WINDOW_INFO 的新客户端为 true", + "type": "boolean" } }, "type": "object" @@ -898,10 +902,11 @@ }, { "name": "get_activity_history", - "description": "获取指定在线主机的历史活动记录(前台窗口驻留时长,每行一条「[时间] [标题] 时长」)。主连接 RPC。结果按 limit/offset 分页(默认 100 条、上限 1000),新在前:offset=0 就是最近 limit 条,想看更早的再往后翻。total 为本机现有记录总数,hasMore 表示还有更早的记录;客户端只保留最近 500 条,所以 total 最多约 501(含进行中的当前窗口)。", + "description": "获取指定在线主机的历史活动记录。Windows 与有桌面的 Linux 客户端返回前台窗口驻留记录,每行一条「[时间] [标题] 时长」;无桌面的 Linux 客户端返回登录记录与 shell 命令历史,每行带「[登录]」或「[命令]」标签(首行为「[来源]」说明)。主连接 RPC。结果按 limit/offset 分页(默认 100 条、上限 1000),新在前:offset=0 就是最近 limit 条,想看更早的再往后翻。total 为本机现有记录总数,hasMore 表示还有更早的记录;窗口后端只保留最近 500 条,所以 total 最多约 501(含进行中的当前窗口)。", "gate": null, "platforms": [ - "win" + "win", + "lnx" ], "impl": "mfc", "inputSchema": { @@ -1088,6 +1093,89 @@ "type": "object" } }, + { + "name": "get_foreground_window", + "description": "获取指定在线 Windows 主机当前的前台窗口(GetForegroundWindow):标题、hwnd、pid、虚拟桌面坐标矩形、是否最小化/最大化、z 序与可见窗口总数。注入键鼠前先用它确认焦点在目标窗口上(remote_keyboard / remote_mouse 的 expect_hwnd 也可做同样的前置校验)。主连接 RPC、一次性返回;要求客户端能力位 CLIENT_CAP_WINDOW_INFO(新客户端),老客户端返回 -32005。只读。", + "gate": null, + "platforms": [ + "win" + ], + "impl": "mfc", + "inputSchema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段" + } + }, + "required": [ + "id" + ] + }, + "outputSchema": { + "type": "object", + "properties": { + "window": { + "type": [ + "object", + "null" + ], + "properties": { + "hwnd": { + "type": "integer" + }, + "pid": { + "type": "integer" + }, + "left": { + "type": "integer" + }, + "top": { + "type": "integer" + }, + "right": { + "type": "integer" + }, + "bottom": { + "type": "integer" + }, + "width": { + "type": "integer" + }, + "height": { + "type": "integer" + }, + "zOrder": { + "type": "integer" + }, + "title": { + "type": "string" + }, + "visible": { + "type": "boolean" + }, + "minimized": { + "type": "boolean" + }, + "maximized": { + "type": "boolean" + }, + "isForeground": { + "type": "boolean" + } + } + }, + "windowCount": { + "type": "integer" + } + }, + "required": [ + "window", + "windowCount" + ] + } + }, { "name": "list_files", "description": "列举指定在线主机的目录。省略或空 path 返回驱动器列表(drives);给定 path 返回该目录一层内的文件/子目录(files,最多 500 条,含 name/isDir/size/mtime)。只读。", @@ -2169,7 +2257,7 @@ }, { "name": "remote_open", - "description": "在指定在线 Windows 或 Linux 主机上建立远程控制会话(隐藏屏幕子连接)并返回 session_id 与物理屏幕分辨率(screen_w/screen_h)。后续 remote_mouse/remote_keyboard 用归一化坐标(0..1)注入输入,用毕须 remote_close。Linux 需要 X11/Xorg(或 XWayland)桌面,纯 Wayland 会话无法抓屏/注入;多显示器暂不支持。", + "description": "在指定在线 Windows 或 Linux 主机上建立远程控制会话(隐藏屏幕子连接)并返回 session_id 与抓屏帧尺寸(screen_w/screen_h,可能是等比缩放后的整屏/整虚拟桌面像素)。后续 remote_mouse/remote_keyboard 用归一化坐标(0..1)注入输入,用毕须 remote_close。Linux 需要 X11/Xorg(或 XWayland)桌面,纯 Wayland 会话无法抓屏/注入;Windows 多显示器需要新版客户端(整虚拟桌面抓屏),老客户端会被拒绝(Linux 截屏/注入天然使用整个 X root,不受此限)。", "gate": "remote_control", "write": true, "platforms": [ @@ -2196,11 +2284,11 @@ "outputSchema": { "properties": { "screen_h": { - "description": "物理屏幕高度(虚拟桌面像素)", + "description": "抓屏帧高度(发送帧像素)", "type": "integer" }, "screen_w": { - "description": "物理屏幕宽度(虚拟桌面像素),用于把归一化坐标 0..1 映射为像素", + "description": "抓屏帧宽度(发送帧像素:整屏或整虚拟桌面,可能已等比缩放),用于把归一化坐标 0..1 映射为像素", "type": "integer" }, "session_id": { @@ -2258,7 +2346,7 @@ }, { "name": "remote_keyboard", - "description": "向已建立的远程控制会话注入键盘事件。action 可选 key_down / key_up / key_press / type:前三种需 key(虚拟键名,如 ENTER/TAB/F5/LEFT/CTRL/ALT/SHIFT/WIN,Linux 侧映射为 X11 keysym),type 需 text(仅 ASCII 文本;非 ASCII 请用 remote_clipboard + Ctrl+V)。modifiers 可选(CTRL/ALT/SHIFT/WIN)。", + "description": "向已建立的远程控制会话注入键盘事件。action 可选 key_down / key_up / key_press / type:前三种需 key(虚拟键名,如 ENTER/TAB/F5/LEFT/CTRL/ALT/SHIFT/WIN,Linux 侧映射为 X11 keysym),type 需 text(仅 ASCII 文本;非 ASCII 请用 remote_clipboard + Ctrl+V)。modifiers 可选(CTRL/ALT/SHIFT/WIN)。可选 expect_hwnd:注入前先确认目标窗口仍在可见列表里(整数或 0x 字符串);配合 require_foreground=true 还要求它已是前台,否则不发注入返回 -32000;同时默认在结果里回报注入后的前台窗口(structuredContent.foreground),用于确认按键真的进了目标窗口。窗口校验仅新 Windows 客户端支持,其他客户端返回 -32005。", "gate": "remote_control", "write": true, "platforms": [ @@ -2294,6 +2382,21 @@ "text": { "description": "文本(type 用,仅 ASCII;非 ASCII 请走 remote_clipboard + Ctrl+V)", "type": "string" + }, + "expect_hwnd": { + "type": [ + "integer", + "string" + ], + "description": "可选:注入前先确认目标窗口仍在当前可见窗口列表中(整数或 0x 前缀字符串)。顺带默认回报前台窗口;仅新 Windows 客户端支持(否则 -32005)。" + }, + "require_foreground": { + "type": "boolean", + "description": "可选:配合 expect_hwnd,要求该窗口已是前台,否则不发注入并返回 -32000。默认 false" + }, + "report_foreground": { + "type": "boolean", + "description": "可选:注入后回报前台窗口(structuredContent.foreground)。给了 expect_hwnd 时默认 true" } }, "required": [ @@ -2304,13 +2407,29 @@ "type": "object" }, "outputSchema": { - "properties": {}, - "type": "object" + "type": "object", + "properties": { + "expectedWindow": { + "type": "object", + "description": "expect_hwnd 时注入前的目标窗口快照" + }, + "foreground": { + "type": [ + "object", + "null" + ], + "description": "注入后的前台窗口(report_foreground 时返回;无前台窗口为 null)" + }, + "foregroundError": { + "type": "string", + "description": "前台回报失败的原因(注入本身已成功)" + } + } } }, { "name": "remote_mouse", - "description": "向已建立的远程控制会话注入鼠标事件。action 可选 move / down / up / click / right_click / middle_click / drag / scroll;坐标 x/y(及 drag 的 x2/y2)为归一化 0..1 浮点。button 可选 left/middle/right(默认 left);click 的 clicks 可选 1/2/3(默认 1);scroll 的 delta 正=向下滚、负=向上滚。", + "description": "向已建立的远程控制会话注入鼠标事件。action 可选 move / down / up / click / right_click / middle_click / drag / scroll;坐标 x/y(及 drag 的 x2/y2)为归一化 0..1 浮点。button 可选 left/middle/right(默认 left);click 的 clicks 可选 1/2/3(默认 1);scroll 的 delta 正=向下滚、负=向上滚。可选 expect_hwnd / require_foreground / report_foreground 与 remote_keyboard 同义(新 Windows 客户端),可用它确认点击确实落在目标窗口。", "gate": "remote_control", "write": true, "platforms": [ @@ -2374,6 +2493,21 @@ "y2": { "description": "拖拽终点 Y(仅 drag)", "type": "number" + }, + "expect_hwnd": { + "type": [ + "integer", + "string" + ], + "description": "可选:注入前先确认目标窗口仍在当前可见窗口列表中(整数或 0x 前缀字符串)。顺带默认回报前台窗口;仅新 Windows 客户端支持(否则 -32005)。" + }, + "require_foreground": { + "type": "boolean", + "description": "可选:配合 expect_hwnd,要求该窗口已是前台,否则不发注入并返回 -32000。默认 false" + }, + "report_foreground": { + "type": "boolean", + "description": "可选:注入后回报前台窗口(structuredContent.foreground)。给了 expect_hwnd 时默认 true" } }, "required": [ @@ -2386,8 +2520,24 @@ "type": "object" }, "outputSchema": { - "properties": {}, - "type": "object" + "type": "object", + "properties": { + "expectedWindow": { + "type": "object", + "description": "expect_hwnd 时注入前的目标窗口快照" + }, + "foreground": { + "type": [ + "object", + "null" + ], + "description": "注入后的前台窗口(report_foreground 时返回;无前台窗口为 null)" + }, + "foregroundError": { + "type": "string", + "description": "前台回报失败的原因(注入本身已成功)" + } + } } }, { @@ -2781,7 +2931,7 @@ }, { "name": "operate_window", - "description": "对指定在线 Windows 主机的窗口执行操作:close(关闭)/show(显示)/hide(隐藏)/minimize(最小化)/maximize(最大化)/restore(还原)。hwnd 取 list_windows 或 host_list_windows 返回的 hwnd。ok 仅表示已下发(窗口句柄可能已失效)。关闭窗口只有本工具能做,host_control_window 不提供 close,且它会重新枚举可见窗口复核结果。dry_run=true 只校验 hwnd 是否还在可见窗口列表里并返回该窗口信息,不发送任何命令。", + "description": "对指定在线 Windows 主机的窗口执行操作:close(关闭)/show(显示)/hide(隐藏)/minimize(最小化)/maximize(最大化)/restore(还原)/activate(激活到前台)。hwnd 取 list_windows 或 host_list_windows 返回的 hwnd。ok 仅表示已下发(窗口句柄可能已失效);action=activate 例外:工具会在动作后用窗口信息 RPC 复核 GetForegroundWindow,返回 ok/state(foreground|background|missing)/window,旧客户端不支持时返回 -32005(可退回 show)。关闭窗口只有本工具能做,host_control_window 不提供 close,且它会重新枚举可见窗口复核结果。dry_run=true 只校验 hwnd 是否还在可见窗口列表里并返回该窗口信息,不发送任何命令。", "gate": "manage", "write": true, "platforms": [ @@ -2791,7 +2941,7 @@ "inputSchema": { "properties": { "action": { - "description": "操作:close(关闭) | show(显示) | hide(隐藏) | minimize(最小化) | maximize(最大化) | restore(还原)", + "description": "操作:close(关闭) | show(显示) | hide(隐藏) | minimize(最小化) | maximize(最大化) | restore(还原) | activate(激活到前台,需新客户端)", "type": "string" }, "dry_run": { @@ -2824,12 +2974,27 @@ "type": "boolean" }, "ok": { - "description": "命令已下发(不代表窗口已按预期变化)", + "description": "命令已下发(不代表窗口已按预期变化);action=activate 时为前台复核结果", "type": "boolean" }, "window": { - "description": "dry_run 时的目标窗口(hwnd/title/status/pid)", - "type": "object" + "description": "dry_run 时的目标窗口;action=activate 时为复核到的窗口快照(hwnd/title/pid/rect/flags 等),复核未找到为 null", + "type": [ + "object", + "null" + ] + }, + "state": { + "type": "string", + "description": "action=activate 时的复核状态:foreground / background / missing / unknown" + }, + "verifyError": { + "type": "string", + "description": "action=activate 且前台复核请求失败时的错误说明" + }, + "truncated": { + "description": "为 true 时表示复核用的可见窗口列表被 96 条单次上限截断,未找到目标不代表窗口不存在(此时 state=unknown)", + "type": "boolean" } }, "type": "object" @@ -3757,7 +3922,7 @@ }, { "name": "host_list_windows", - "description": "列出在线 Windows 主机上当前可见的顶层窗口(主机管理「窗口」标签页)。只包含可见窗口,故隐藏后窗口会从结果中消失。hwnd 可用于 host_control_window 或 operate_window。首选:支持服务端过滤(pid / title),仅在它没有出现在 tools/list 里(McpMachine=0)时退回 list_windows。", + "description": "列出在线 Windows 主机上当前可见的顶层窗口(主机管理「窗口」标签页)。只包含可见窗口,故隐藏后窗口会从结果中消失;单次最多返回 96 条,可见窗口更多时 truncated=true 且列表不完整(不能据此断定某个窗口不存在)。hwnd 可用于 host_control_window 或 operate_window。首选:支持服务端过滤(pid / title),仅在它没有出现在 tools/list 里(McpMachine=0)时退回 list_windows。", "gate": "machine", "platforms": [ "win" @@ -3839,7 +4004,7 @@ "type": "integer" }, "hwnd": { - "description": "窗口句柄(十进制)", + "description": "窗口句柄(十进制;也可用作 host_control_window / operate_window 的 hwnd)", "type": "integer" }, "pid": { @@ -3850,11 +4015,51 @@ }, "width": { "type": "integer" + }, + "left": { + "type": "integer", + "description": "窗口矩形左边界(屏幕坐标,可能为负,多显示器时常见)" + }, + "top": { + "type": "integer", + "description": "窗口矩形上边界(屏幕坐标)" + }, + "right": { + "type": "integer", + "description": "窗口矩形右边界(屏幕坐标,不含边界);width = right - left" + }, + "bottom": { + "type": "integer", + "description": "窗口矩形下边界(屏幕坐标,不含边界);height = bottom - top" + }, + "visible": { + "type": "boolean", + "description": "是否可见;当前列表只含可见窗口,故恒为 true" + }, + "minimized": { + "type": "boolean", + "description": "是否最小化" + }, + "maximized": { + "type": "boolean", + "description": "是否最大化" + }, + "isForeground": { + "type": "boolean", + "description": "是否为当前前台窗口(全表最多一个 true)" + }, + "zOrder": { + "type": "integer", + "description": "z 序,0 = 最顶层;数值越小越靠前" } }, "type": "object" }, "type": "array" + }, + "truncated": { + "description": "为 true 时表示客户端的可见窗口多于单次返回上限(96 条),列表不完整", + "type": "boolean" } }, "required": [ @@ -5355,7 +5560,7 @@ }, { "name": "host_control_window", - "description": "对在线 Windows 主机的窗口执行可恢复操作:restore(还原)/hide(隐藏)/maximize(最大化)/minimize(最小化)。hwnd 取 host_list_windows 或 list_windows 返回的 hwnd。动作后重新枚举可见窗口复核:hide 后 hwnd 应消失,其余动作后仍应存在。不提供关闭窗口——需要 close / show 时改用 operate_window。dry_run=true 只核实 hwnd 并返回窗口信息。", + "description": "对在线 Windows 主机的窗口执行可恢复操作:restore(还原)/hide(隐藏)/maximize(最大化)/minimize(最小化)/activate(激活到前台)。hwnd 取 host_list_windows 或 list_windows 返回的 hwnd。动作后重新枚举可见窗口复核:hide 后 hwnd 应消失,其余动作后仍应存在;activate 会额外复核 GetForegroundWindow,目标未成为前台则 ok=false、reason=not_foreground。activate 需要新客户端(窗口信息能力),旧客户端返回 -32005,可退回 restore。不提供关闭窗口——需要 close / show 时改用 operate_window。dry_run=true 只核实 hwnd 并返回窗口信息。", "gate": "machine", "write": true, "platforms": [ @@ -5365,12 +5570,13 @@ "inputSchema": { "properties": { "action": { - "description": "restore/hide/maximize/minimize", + "description": "restore/hide/maximize/minimize/activate", "enum": [ "restore", "hide", "maximize", - "minimize" + "minimize", + "activate" ], "type": "string" }, diff --git a/server/2015Remote/2015RemoteDlg.cpp b/server/2015Remote/2015RemoteDlg.cpp index 44a271d..777eddc 100644 --- a/server/2015Remote/2015RemoteDlg.cpp +++ b/server/2015Remote/2015RemoteDlg.cpp @@ -6629,6 +6629,15 @@ VOID CMy2015RemoteDlg::MessageHandle(CONTEXT_OBJECT* ContextObject) dlg->AppendLog(text); break; } + case TOKEN_MCP_WINDOW_INFO: { + // 主连接 RPC:窗口信息(仅 CLIENT_CAP_WINDOW_INFO 客户端回复)。MCP 挂起时同步取走; + // 无挂起(已超时/迟到)直接丢弃——主连接不能 CancelIO。 + uint64_t winDevId = ContextObject->GetClientID(); + if (McpServer().IsPending(winDevId)) { + McpServer().TakeMainResponse(winDevId, ContextObject->GetBuffer(0), ContextObject->GetBufferLength()); + } + break; + } case TOKEN_CLIENT_MSG: { // MCP 工具在飞时不弹客户端的老式提示框:新客户端在失败分支同时发结构化 token(已能 // 让工具立即返回错误)和老 ClientMsg(只为兼容老服务端),后者会让 MCP 调用在服务端 diff --git a/server/2015Remote/McpInternal.cpp b/server/2015Remote/McpInternal.cpp index 11499fe..a34b116 100644 --- a/server/2015Remote/McpInternal.cpp +++ b/server/2015Remote/McpInternal.cpp @@ -1,6 +1,7 @@ #include "stdafx.h" #include "McpInternal.h" #include "context.h" // context 接口(GetClientID/IsLogin) +#include "McpServer.h" // 窗口信息 RPC 复用主连接的挂起/等待机制 #include "2015RemoteDlg.h" // CMy2015RemoteDlg 成员(m_HostList/m_cs)+ WM_SHOWERRORMSG #include "LangManager.h" // _TR @@ -179,6 +180,94 @@ bool IsWindowsClient(context* ctx) { return !(t == "LNX" || t == "MAC" || t == "APK"); } +// ===== 窗口信息 RPC ===== + +Json::Value WindowEntryToJson(const WindowEntry& e) { + Json::Value item(Json::objectValue); + item["hwnd"] = (Json::UInt)e.hwnd; + item["pid"] = (Json::UInt)e.pid; + item["title"] = e.title; + item["left"] = e.left; + item["top"] = e.top; + item["right"] = e.right; + item["bottom"] = e.bottom; + item["width"] = e.right - e.left; + item["height"] = e.bottom - e.top; + item["visible"] = (e.flags & WINDOWINFO_VISIBLE) != 0; + item["minimized"] = (e.flags & WINDOWINFO_MINIMIZED) != 0; + item["maximized"] = (e.flags & WINDOWINFO_MAXIMIZED) != 0; + item["isForeground"] = (e.flags & WINDOWINFO_FOREGROUND) != 0; + item["zOrder"] = e.zorder; + return item; +} + +int FetchWindowInfo(context* ctx, uint64_t devId, const char* tool, int timeoutMs, + std::vector& out, std::string& errMsg, bool* truncated) { + out.clear(); + errMsg.clear(); + if (truncated) *truncated = false; + if (!ctx) { + errMsg = "host context unavailable"; + return 2; + } + if (!ctx->SupportsWindowInfo()) { + errMsg = "host client does not support window info (old client)"; + return 4; + } + + CMcpServer& mcp = McpServer(); + if (!mcp.BeginPending(devId, tool ? tool : "window_info")) { + errMsg = "device busy: another request is pending for this host"; + return 1; + } + + BYTE req[2] = { (BYTE)COMMAND_MCP_WINDOW_INFO, 0 }; // mode 0 = 可见顶层窗口 + if (!ctx->Send2Client(req, sizeof(req))) { + mcp.ClearPending(devId); + errMsg = "failed to send window info request"; + return 2; + } + + std::vector data; + if (!mcp.WaitPending(devId, data, timeoutMs > 0 ? timeoutMs : mcp.ToolTimeoutMs())) { + errMsg = "timeout waiting for window info"; + return 2; + } + + if (data.size() < 4 || data[0] != (BYTE)TOKEN_MCP_WINDOW_INFO) { + errMsg = "invalid window info response"; + return 3; + } + // 模式字节最高位 = 客户端枚举到的可见窗口超过单包上限,返回的 count 条不完整。 + if (truncated) *truncated = (data[1] & 0x80) != 0; + const size_t count = (size_t)data[2] | ((size_t)data[3] << 8); + if (data.size() < 4 + count * sizeof(WINDOWINFO_MCP)) { + errMsg = "truncated window info response"; + return 3; + } + + out.reserve(count); + for (size_t i = 0; i < count; ++i) { + WINDOWINFO_MCP rec; + memcpy(&rec, data.data() + 4 + i * sizeof(WINDOWINFO_MCP), sizeof(rec)); + + WindowEntry e; + e.hwnd = rec.hwnd; + e.pid = rec.pid; + e.left = rec.left; + e.top = rec.top; + e.right = rec.right; + e.bottom = rec.bottom; + e.flags = rec.flags; + e.zorder = rec.zorder; + char title[sizeof(rec.title) + 1] = { 0 }; + memcpy(title, rec.title, sizeof(rec.title)); // 客户端保证 NUL 填充;再兜底截断 + e.title = title; + out.push_back(std::move(e)); + } + return 0; +} + size_t BoundedStrlen(const char* p, size_t avail) { size_t n = 0; while (n < avail && p[n]) ++n; @@ -397,6 +486,7 @@ const ToolHints kToolHints[] = { // 已落盘的记录),故按「可写、可破坏」登记。 { "get_keylog", false, true, false, true }, { "get_screenshot", true, false, true, true }, + { "get_foreground_window", true, false, true, true }, { "list_registry", true, false, true, true }, { "download_file", true, false, true, true }, // 只读主机(写的是主控本机目录) { "search_file", true, false, true, true }, diff --git a/server/2015Remote/McpInternal.h b/server/2015Remote/McpInternal.h index 8a86cb0..a9d9a8b 100644 --- a/server/2015Remote/McpInternal.h +++ b/server/2015Remote/McpInternal.h @@ -14,6 +14,7 @@ #include #include +#include class CMy2015RemoteDlg; class context; @@ -79,6 +80,33 @@ bool ParseHostIdArg(const Json::Value& args, uint64_t& out, std::string& err); // 在 m_HostList 中按 clientID 找在线主 context(锁内遍历 m_cs)。 context* FindMainContext(CMy2015RemoteDlg* parent, uint64_t id); +// ===== 窗口信息 RPC(CLIENT_CAP_WINDOW_INFO)===== + +// 一条窗口记录(WINDOWINFO_MCP 的解码结果;标题已转 UTF-8)。 +struct WindowEntry { + uint32_t hwnd = 0; + uint32_t pid = 0; + int32_t left = 0; + int32_t top = 0; + int32_t right = 0; + int32_t bottom = 0; + uint32_t flags = 0; // WINDOWINFO_* + int32_t zorder = -1; // 0 = 最顶层 + std::string title; // UTF-8 +}; + +// WindowEntry → 输出 JSON(hwnd/pid/title/left/top/right/bottom/width/height/visible/ +// minimized/maximized/isForeground/zOrder)。机器管理与远程控制共用同一字段口径。 +Json::Value WindowEntryToJson(const WindowEntry& e); + +// 下发 COMMAND_MCP_WINDOW_INFO(主连接 RPC,不建子连接、不弹框),解析 TOKEN_MCP_WINDOW_INFO。 +// timeoutMs <= 0 时取 McpServer().ToolTimeoutMs()。out 按客户端的 z 序返回。 +// 返回:0=ok;1=设备忙;2=发送失败/超时;3=响应畸形;4=客户端未声明 CLIENT_CAP_WINDOW_INFO。 +// truncated(可选):true 表示客户端还有更多可见窗口没装进这个包(单包上限 96 条)。 +int FetchWindowInfo(context* ctx, uint64_t devId, const char* tool, int timeoutMs, + std::vector& out, std::string& errMsg, + bool* truncated = nullptr); + // 客户端是否为 Windows 形态(EXE/DLL/MEXE/SC/MDLL);LNX / MAC / APK 返回 false。 // 用于「只有 Windows 客户端实现了这个能力」的判断(注册表、窗口、服务等)。 bool IsWindowsClient(context* ctx); diff --git a/server/2015Remote/McpMachine.cpp b/server/2015Remote/McpMachine.cpp index f5f8e7e..2a8bb8f 100644 --- a/server/2015Remote/McpMachine.cpp +++ b/server/2015Remote/McpMachine.cpp @@ -297,7 +297,7 @@ std::string BuildStructuredResult(const Json::Value& id, const Json::Value& sc, std::string BuildListResult(const Json::Value& id, const char* arrayKey, const Json::Value& page, int total, int totalAll, int offset, int limit, bool hasMore, - const std::string& text) { + const std::string& text, bool truncated = false) { Json::Value sc(Json::objectValue); sc[arrayKey] = page; sc["total"] = total; @@ -305,6 +305,8 @@ std::string BuildListResult(const Json::Value& id, const char* arrayKey, sc["offset"] = offset; sc["limit"] = limit; sc["hasMore"] = hasMore; + // 只有窗口列表会因为客户端单包上限被截断;其它列表不写这个字段,输出形状不变。 + if (truncated) sc["truncated"] = true; return BuildStructuredResult(id, sc, text); } @@ -1704,14 +1706,37 @@ static std::string BuildHostListWindows(const Json::Value& id, const Json::Value if (!GetOptIntArg(id, args, "pid", 0, 0x7FFFFFFF, pidFilter, errJson)) return errJson; std::string title = OptStr(args, "title"); - std::vector data; - if (!FetchMachineTab(id, ht, "host_list_windows", (BYTE)COMMAND_MACHINE_WINDOWS, - (BYTE)TOKEN_MACHINE_WINDOWS, data, errJson)) - return errJson; + Json::Value all(Json::arrayValue); + bool winTruncated = false; + if (ht.mainCtx->SupportsWindowInfo()) { + // 新协议:主连接 RPC,返回 UTF-8 标题、屏幕坐标、前后台与 z 序。 + std::vector wins; + std::string ferr; + int rc = FetchWindowInfo(ht.mainCtx, ht.dev, "host_list_windows", 0, wins, ferr, &winTruncated); + if (rc == 1) + return BuildError(id, kErrBusy, + BusyMessage("Device busy: another MCP request is pending for this host", ht.dev)); + if (rc == 4) + return BuildError(id, kErrUnsupported, "Host does not support window info (old client)"); + if (rc != 0) + return BuildError(id, rc == 2 ? kErrTimeout : kErrGeneric, + "Failed to get window list: " + ferr); + for (const WindowEntry& e : wins) { + Json::Value item = WindowEntryToJson(e); + // 旧 tab 1 每条都带 canSee;新路径只枚举可见窗口(隐藏窗口根本不在列表里), + // 故这里恒为 true,补字段只为避免同一工具的输出字段随客户端版本变化。 + item["canSee"] = (e.flags & WINDOWINFO_VISIBLE) != 0; + all.append(item); + } + } else { + std::vector data; + if (!FetchMachineTab(id, ht, "host_list_windows", (BYTE)COMMAND_MACHINE_WINDOWS, + (BYTE)TOKEN_MACHINE_WINDOWS, data, errJson)) + return errJson; - Json::Value all; - std::string perr; - if (!ParseWindows(data, 936, all, perr)) return ParseErrorToJson(id, "window list", perr); + std::string perr; + if (!ParseWindows(data, 936, all, perr)) return ParseErrorToJson(id, "window list", perr); + } auto pred = [&](const Json::Value& item) { if (pidFilter >= 0 && item["pid"].asUInt() != (Json::UInt)pidFilter) return false; @@ -1724,8 +1749,15 @@ static std::string BuildHostListWindows(const Json::Value& id, const Json::Value Json::Value page = FilterAndPage(all, pred, paging, total, hasMore); std::string text = std::string(u8"共 ") + std::to_string(total) + u8" 个可见窗口(全部 " + std::to_string(totalAll) + u8" 个)"; + if (winTruncated) { + // 客户端单包只能装 96 条:total/totalAll 只统计到返回的这一批,offset 也翻不到 + // 被截掉的部分,必须让调用方看到"列表不完整",不能当成窗口不存在。 + text = std::string(u8"共 ") + std::to_string(total) + u8" 个匹配窗口(本次返回 " + + std::to_string(totalAll) + u8" 个;可见窗口超过单次上限 96,列表不完整," + u8"请勿据此断定窗口不存在)"; + } return BuildListResult(id, "windows", page, total, totalAll, - paging.offset, paging.limit, hasMore, text); + paging.offset, paging.limit, hasMore, text, winTruncated); } // ---- host_list_network_state ---- @@ -2227,12 +2259,15 @@ static std::string BuildHostControlWindow(const Json::Value& id, const Json::Val if (!RequireWritable(id, errJson)) return errJson; std::string action = ToLowerAscii(OptStr(args, "action")); + bool activate = (action == "activate"); DWORD sw = 0; if (action == "restore") sw = SW_RESTORE; else if (action == "hide") sw = SW_HIDE; else if (action == "maximize") sw = SW_SHOWMAXIMIZED; else if (action == "minimize") sw = SW_SHOWMINIMIZED; - else return BuildError(id, -32602, "Invalid action: expected restore, hide, maximize or minimize"); + else if (activate) sw = CMD_WINDOW_ACTIVATE_FLAG; + else return BuildError(id, -32602, + "Invalid action: expected restore, hide, maximize, minimize or activate"); uint32_t hwnd = 0; if (!ReadHwndArg(id, args, hwnd, errJson)) return errJson; @@ -2240,6 +2275,12 @@ static std::string BuildHostControlWindow(const Json::Value& id, const Json::Val HostTool ht; if (!ResolveHost(id, args, parent, ht, true, errJson)) return errJson; + // 后台窗口仅 ShowWindow 不会升到前台,activate 需要新客户端的 + // AttachThreadInput + SetForegroundWindow 实现(CLIENT_CAP_WINDOW_INFO)。 + if (activate && !ht.mainCtx->SupportsWindowInfo()) + return BuildError(id, kErrUnsupported, + "activate requires a newer client (window info capability); use restore instead"); + ManagedSession session; if (!session.Open(id, "host_control_window", ht, false, nullptr, errJson)) return errJson; @@ -2277,6 +2318,55 @@ static std::string BuildHostControlWindow(const Json::Value& id, const Json::Val return errJson; } + if (activate) { + session.Finish(); + Sleep(300); // 给客户端激活线程 / 系统前台切换留出时间 + std::vector wins; + std::string ferr; + bool winTruncated = false; + int rc = FetchWindowInfo(ht.mainCtx, ht.dev, "host_control_window", 0, wins, ferr, + &winTruncated); + if (rc == 1) + return BuildError(id, kErrBusy, + BusyMessage("Device busy: another MCP request is pending for this host", ht.dev)); + if (rc != 0) + return BuildError(id, rc == 2 ? kErrTimeout : kErrGeneric, + "activate sent, but foreground verification failed: " + ferr); + + const WindowEntry* target = nullptr; + for (const WindowEntry& e : wins) { + if (e.hwnd == hwnd) target = &e; + } + bool isForeground = target && (target->flags & WINDOWINFO_FOREGROUND) != 0; + // 列表装不下全部可见窗口时,没找到目标不代表窗口消失,只代表结果未知。 + const char* state = target ? (isForeground ? "foreground" : "background") + : (winTruncated ? "unknown" : "missing"); + + AuditManageAction(parent, ht.dev, "host_control_window", + action + " hwnd=" + std::to_string(hwnd) + " result=" + state); + + if (!target) { + if (winTruncated) + return BuildActionResult(id, false, false, false, action, + "hwnd=" + std::to_string(hwnd), state, "list_truncated", + u8"动作已下发,但复核用的窗口列表被单次上限截断(可见窗口" + u8"超过 96 个),目标不在返回的这一批里,无法确认是否已到前台。"); + return BuildActionResult(id, false, true, false, action, + "hwnd=" + std::to_string(hwnd), state, "window_gone", + u8"动作已下发,但复核时目标窗口不在可见窗口列表中(可能已关闭" + u8"或已隐藏)。"); + } + if (!isForeground) { + return BuildActionResult(id, false, true, false, action, + "hwnd=" + std::to_string(hwnd), state, "not_foreground", + u8"动作已下发,但目标窗口仍未成为前台窗口。常见原因:系统前台锁定" + u8"策略、目标进程正在处理模态框,或该窗口已最小化。可重试。"); + } + return BuildActionResult(id, true, true, true, action, + "hwnd=" + std::to_string(hwnd), state, "", + u8"窗口已激活并成为前台窗口(复核 GetForegroundWindow 一致)。"); + } + std::vector after; if (!session.Request(id, (BYTE)COMMAND_MACHINE_WINDOWS, (BYTE)TOKEN_MACHINE_WINDOWS, after, errJson)) @@ -2619,12 +2709,21 @@ Json::Value ProcessItemSchema() { Json::Value WindowItemSchema() { Json::Value p(Json::objectValue); - p["hwnd"] = PropInt(u8"窗口句柄(十进制)"); + p["hwnd"] = PropInt(u8"窗口句柄(十进制;也可用作 host_control_window / operate_window 的 hwnd)"); p["title"] = PropStr(); p["pid"] = PropInt(); p["width"] = PropInt(); p["height"] = PropInt(); p["canSee"] = PropBool(u8"客户端是否可抓取该窗口画面"); + p["left"] = PropInt(u8"窗口矩形左边界(屏幕坐标,可能为负,多显示器时常见)"); + p["top"] = PropInt(u8"窗口矩形上边界(屏幕坐标)"); + p["right"] = PropInt(u8"窗口矩形右边界(屏幕坐标,不含边界);width = right - left"); + p["bottom"] = PropInt(u8"窗口矩形下边界(屏幕坐标,不含边界);height = bottom - top"); + p["visible"] = PropBool(u8"是否可见;当前列表只含可见窗口,故恒为 true"); + p["minimized"] = PropBool(u8"是否最小化"); + p["maximized"] = PropBool(u8"是否最大化"); + p["isForeground"] = PropBool(u8"是否为当前前台窗口(全表最多一个 true)"); + p["zOrder"] = PropInt(u8"z 序,0 = 最顶层;数值越小越靠前"); return p; } @@ -2802,9 +2901,14 @@ void AppendTools(Json::Value& tools) { Json::Value props(Json::objectValue); props["pid"] = PropInt(u8"按所属进程 PID 过滤"); props["title"] = PropStr(u8"按窗口标题子串过滤"); + Json::Value outSchema = MakeListOutputSchema("windows", WindowItemSchema()); + // 客户端单个响应包最多装 96 条窗口;超出时这里给出 true,表示 windows + // 只是可见窗口的一个前缀,翻页也取不到剩下的部分。 + outSchema["properties"]["truncated"] = + PropBool(u8"为 true 时表示客户端的可见窗口多于单次返回上限(96 条),列表不完整"); AddTool(tools, "host_list_windows", - u8"列出在线 Windows 主机上当前可见的顶层窗口(主机管理「窗口」标签页)。只包含可见窗口,故隐藏后窗口会从结果中消失。hwnd 可用于 host_control_window 或 operate_window。首选:支持服务端过滤(pid / title),仅在它没有出现在 tools/list 里(McpMachine=0)时退回 list_windows。", - ReadInputSchemaBatch(props), MakeListOutputSchema("windows", WindowItemSchema())); + u8"列出在线 Windows 主机上当前可见的顶层窗口(主机管理「窗口」标签页)。只包含可见窗口,故隐藏后窗口会从结果中消失;单次最多返回 96 条,可见窗口更多时 truncated=true 且列表不完整(不能据此断定某个窗口不存在)。hwnd 可用于 host_control_window 或 operate_window。首选:支持服务端过滤(pid / title),仅在它没有出现在 tools/list 里(McpMachine=0)时退回 list_windows。", + ReadInputSchemaBatch(props), outSchema); } { Json::Value props(Json::objectValue); @@ -2914,8 +3018,8 @@ void AppendTools(Json::Value& tools) { { Json::Value props(Json::objectValue); props["id"] = HostIdProp(); - props["action"] = PropStrEnum(u8"restore/hide/maximize/minimize", - { "restore", "hide", "maximize", "minimize" }); + props["action"] = PropStrEnum(u8"restore/hide/maximize/minimize/activate", + { "restore", "hide", "maximize", "minimize", "activate" }); Json::Value hwnd(Json::objectValue); Json::Value types(Json::arrayValue); types.append("integer"); @@ -2925,7 +3029,7 @@ void AppendTools(Json::Value& tools) { props["hwnd"] = hwnd; props["dry_run"] = PropBool(u8"true 时只校验 hwnd 仍在可见窗口列表里并返回该窗口,不下发操作,默认 false"); AddTool(tools, "host_control_window", - u8"对在线 Windows 主机的窗口执行可恢复操作:restore(还原)/hide(隐藏)/maximize(最大化)/minimize(最小化)。hwnd 取 host_list_windows 或 list_windows 返回的 hwnd。动作后重新枚举可见窗口复核:hide 后 hwnd 应消失,其余动作后仍应存在。不提供关闭窗口——需要 close / show 时改用 operate_window。dry_run=true 只核实 hwnd 并返回窗口信息。", + u8"对在线 Windows 主机的窗口执行可恢复操作:restore(还原)/hide(隐藏)/maximize(最大化)/minimize(最小化)/activate(激活到前台)。hwnd 取 host_list_windows 或 list_windows 返回的 hwnd。动作后重新枚举可见窗口复核:hide 后 hwnd 应消失,其余动作后仍应存在;activate 会额外复核 GetForegroundWindow,目标未成为前台则 ok=false、reason=not_foreground。activate 需要新客户端(窗口信息能力),旧客户端返回 -32005,可退回 restore。不提供关闭窗口——需要 close / show 时改用 operate_window。dry_run=true 只核实 hwnd 并返回窗口信息。", MakeSchema(props, { "id", "action", "hwnd" }), ActionOutputSchema()); } diff --git a/server/2015Remote/McpServer.cpp b/server/2015Remote/McpServer.cpp index 029b8fa..4faf8d4 100644 --- a/server/2015Remote/McpServer.cpp +++ b/server/2015Remote/McpServer.cpp @@ -320,6 +320,7 @@ const char* kServerInstructions = u8"进程排查:host_list_processes 或 list_processes 定位,kill_process 结束。这类动作没有真实回执," u8"拿到 ok 后应再列一次复核,不要凭 ok 断言已生效。\n" u8"GUI 自动化:remote_open 取得 session_id 与分辨率(screen_w/screen_h)→ get_screenshot 看画面 → " + u8"get_foreground_window 确认前台窗口(或用 remote_mouse / remote_keyboard 的 expect_hwnd 做前置校验)→ " u8"remote_mouse / remote_keyboard 用归一化坐标(0..1)操作 → 必须 remote_close 释放会话,闲置会话会被回收。" u8"要防止真人操作打断自动化时用 remote_block_input 锁定对端键鼠(必须带 max_block_ms,到期自动解除;" u8"客户端无管理员权限时 Windows 会让 BlockInput 静默失败,成功只代表命令已送达)。\n" @@ -331,13 +332,14 @@ const char* kServerInstructions = u8"支持面从宽到窄依次是 win > lnx > mac ≈ apk:Windows 是唯一全量支持的平台,Linux 次之," u8"macOS 与 Android 只覆盖一部分。拿不准时按这个顺序假设。\n" u8"win(EXE / DLL / MEXE / SC / MDLL):全部工具可用。\n" - u8"lnx(LNX):不支持服务、注册表、键日志、活动历史、文件搜索/删除/移动/建目录、" - u8"窗口列表(list_windows)、网络连接列表与断开" + u8"lnx(LNX):不支持服务、注册表、键日志、文件搜索/删除/移动/建目录、" + u8"窗口列表(list_windows)与窗口信息(get_foreground_window)、网络连接列表与断开" u8"(list_network_connections / kill_network_connection)、" u8"块输入、host_* 全族、chat_* 全族、operate_window、power_action。远程控制与截屏要求目标机" u8"有 X11/Xorg(或 XWayland)桌面,纯 Wayland 或无桌面的服务器不行。\n" u8"mac(MAC):在 lnx 的基础上,还不支持远程控制全族(remote_open / remote_close / " u8"remote_mouse / remote_keyboard / remote_clipboard)、get_screenshot、" + u8"活动历史(get_activity_history)、" u8"exec_command、terminal_open / terminal_exec / terminal_close" u8"(客户端有 PTY 实现,但服务端本轮未开放)、kill_process;" u8"文件传输、进程列表、日志可用。\n" @@ -1034,6 +1036,9 @@ Json::Value BuildHostDetailOutputSchema() { capProps["fileTransferV2"] = boolProp(u8"是否支持 V2 文件传输(download_file / upload_file 的前提)"); capProps["c2cPaths"] = boolProp(u8"能否按路径清单接收另一台主机的文件(copy_files_c2c 源端的前提)"); capProps["registry"] = boolProp(u8"是否有 Windows 注册表可查(list_registry);仅 Windows 客户端为 true"); + capProps["windowInfo"] = boolProp( + u8"是否支持窗口信息(get_foreground_window、host_list_windows 的坐标/前后台字段、" + u8"operate_window/host_control_window 的 activate);仅声明 CLIENT_CAP_WINDOW_INFO 的新客户端为 true"); Json::Value caps(Json::objectValue); caps["type"] = "object"; caps["properties"] = capProps; @@ -1362,7 +1367,7 @@ Json::Value BuildOperateWindowInputSchema() { Json::Value actionProp(Json::objectValue); actionProp["type"] = "string"; - actionProp["description"] = u8"操作:close(关闭) | show(显示) | hide(隐藏) | minimize(最小化) | maximize(最大化) | restore(还原)"; + actionProp["description"] = u8"操作:close(关闭) | show(显示) | hide(隐藏) | minimize(最小化) | maximize(最大化) | restore(还原) | activate(激活到前台,需新客户端)"; props["action"] = actionProp; Json::Value dryRunProp(Json::objectValue); @@ -1377,7 +1382,7 @@ Json::Value BuildOperateWindowOutputSchema() { Json::Value props(Json::objectValue); Json::Value ok(Json::objectValue); ok["type"] = "boolean"; - ok["description"] = u8"命令已下发(不代表窗口已按预期变化)"; + ok["description"] = u8"命令已下发(不代表窗口已按预期变化);action=activate 时为前台复核结果"; props["ok"] = ok; Json::Value dryProp(Json::objectValue); @@ -1390,10 +1395,30 @@ Json::Value BuildOperateWindowOutputSchema() { props["action"] = actionProp; Json::Value windowProp(Json::objectValue); - windowProp["type"] = "object"; - windowProp["description"] = u8"dry_run 时的目标窗口(hwnd/title/status/pid)"; + // action=activate 复核时若没找到目标窗口,window 为 null(字段存在但值为空)。 + Json::Value windowTypes(Json::arrayValue); + windowTypes.append("object"); + windowTypes.append("null"); + windowProp["type"] = windowTypes; + windowProp["description"] = u8"dry_run 时的目标窗口;action=activate 时为复核到的窗口快照(hwnd/title/pid/rect/flags 等),复核未找到为 null"; props["window"] = windowProp; + Json::Value stateProp(Json::objectValue); + stateProp["type"] = "string"; + stateProp["description"] = u8"action=activate 时的复核状态:foreground / background / missing / unknown"; + props["state"] = stateProp; + + Json::Value verifyErrProp(Json::objectValue); + verifyErrProp["type"] = "string"; + verifyErrProp["description"] = u8"action=activate 且前台复核请求失败时的错误说明"; + props["verifyError"] = verifyErrProp; + + Json::Value truncProp(Json::objectValue); + truncProp["type"] = "boolean"; + truncProp["description"] = u8"为 true 时表示复核用的可见窗口列表被 96 条单次上限截断," + u8"未找到目标不代表窗口不存在(此时 state=unknown)"; + props["truncated"] = truncProp; + Json::Value schema(Json::objectValue); schema["type"] = "object"; schema["properties"] = props; @@ -1751,6 +1776,56 @@ Json::Value BuildScreenshotOutputSchema() { return schema; } +// 窗口对象 schema(get_foreground_window 的 window 字段,与 WindowEntryToJson 同口径) +Json::Value BuildWindowObjectSchema() { + Json::Value obj(Json::objectValue); + obj["type"] = "object"; + Json::Value p(Json::objectValue); + const char* ints[] = { "hwnd", "pid", "left", "top", "right", "bottom", + "width", "height", "zOrder" }; + for (const char* f : ints) { + Json::Value s(Json::objectValue); + s["type"] = "integer"; + p[f] = s; + } + Json::Value title(Json::objectValue); + title["type"] = "string"; + p["title"] = title; + const char* bools[] = { "visible", "minimized", "maximized", "isForeground" }; + for (const char* f : bools) { + Json::Value s(Json::objectValue); + s["type"] = "boolean"; + p[f] = s; + } + obj["properties"] = p; + return obj; +} + +// get_foreground_window 的 outputSchema(window 为 null 表示当前没有可枚举的前台窗口) +Json::Value BuildGetForegroundWindowOutputSchema() { + Json::Value props(Json::objectValue); + + Json::Value winProp = BuildWindowObjectSchema(); + Json::Value winTypes(Json::arrayValue); + winTypes.append("object"); + winTypes.append("null"); + winProp["type"] = winTypes; + props["window"] = winProp; + + Json::Value cntProp(Json::objectValue); + cntProp["type"] = "integer"; + props["windowCount"] = cntProp; + + Json::Value schema(Json::objectValue); + schema["type"] = "object"; + schema["properties"] = props; + Json::Value required(Json::arrayValue); + required.append("window"); + required.append("windowCount"); + schema["required"] = required; + return schema; +} + // get_screenshot 的 inputSchema(id 必填,max_width 可选) Json::Value BuildGetScreenshotInputSchema() { Json::Value props(Json::objectValue); @@ -1774,6 +1849,24 @@ Json::Value BuildGetScreenshotInputSchema() { return schema; } +// get_foreground_window 的 inputSchema(id 必填) +Json::Value BuildGetForegroundWindowInputSchema() { + Json::Value props(Json::objectValue); + + Json::Value idProp(Json::objectValue); + idProp["type"] = "string"; + idProp["description"] = u8"主机 id,取 list_online_hosts / search_hosts 返回的 id 字段"; + props["id"] = idProp; + + Json::Value schema(Json::objectValue); + schema["type"] = "object"; + schema["properties"] = props; + Json::Value required(Json::arrayValue); + required.append("id"); + schema["required"] = required; + return schema; +} + // list_files 的 inputSchema(id 必填,path 可选;path 缺省/空 = 列盘) Json::Value BuildListFilesInputSchema() { Json::Value props(Json::objectValue); @@ -2046,6 +2139,18 @@ std::string BuildToolsListResult(const Json::Value& id) { tools.append(tool); } + // 7b) get_foreground_window(窗口信息 RPC,CLIENT_CAP_WINDOW_INFO,仅 Windows) + { + Json::Value tool(Json::objectValue); + tool["name"] = "get_foreground_window"; + tool["description"] = u8"获取指定在线 Windows 主机当前的前台窗口(GetForegroundWindow):标题、hwnd、pid、虚拟桌面坐标矩形、是否最小化/最大化、z 序与可见窗口总数。注入键鼠前先用它确认焦点在目标窗口上(remote_keyboard / remote_mouse 的 expect_hwnd 也可做同样的前置校验)。主连接 RPC、一次性返回;要求客户端能力位 CLIENT_CAP_WINDOW_INFO(新客户端),老客户端返回 -32005。只读。"; + + tool["inputSchema"] = BuildGetForegroundWindowInputSchema(); + tool["outputSchema"] = BuildGetForegroundWindowOutputSchema(); + + tools.append(tool); + } + // 8) list_files(P2c:文件链路,列盘/列目录) { Json::Value tool(Json::objectValue); @@ -2359,7 +2464,7 @@ std::string BuildToolsListResult(const Json::Value& id) { { Json::Value tool(Json::objectValue); tool["name"] = "remote_keyboard"; - tool["description"] = u8"向已建立的远程控制会话注入键盘事件。action 可选 key_down / key_up / key_press / type:前三种需 key(虚拟键名,如 ENTER/TAB/F5/LEFT/CTRL/ALT/SHIFT/WIN,Linux 侧映射为 X11 keysym),type 需 text(仅 ASCII 文本;非 ASCII 请用 remote_clipboard + Ctrl+V)。modifiers 可选(CTRL/ALT/SHIFT/WIN)。"; + tool["description"] = u8"向已建立的远程控制会话注入键盘事件。action 可选 key_down / key_up / key_press / type:前三种需 key(虚拟键名,如 ENTER/TAB/F5/LEFT/CTRL/ALT/SHIFT/WIN,Linux 侧映射为 X11 keysym),type 需 text(仅 ASCII 文本;非 ASCII 请用 remote_clipboard + Ctrl+V)。modifiers 可选(CTRL/ALT/SHIFT/WIN)。可选 expect_hwnd:注入前先确认目标窗口仍在可见列表里(整数或 0x 字符串);配合 require_foreground=true 还要求它已是前台,否则不发注入返回 -32000;同时默认在结果里回报注入后的前台窗口(structuredContent.foreground),用于确认按键真的进了目标窗口。窗口校验仅新 Windows 客户端支持,其他客户端返回 -32005。"; tool["inputSchema"] = BuildRemoteKeyboardInputSchema(); tool["outputSchema"] = BuildRemoteKeyboardOutputSchema(); tools.append(tool); @@ -2367,7 +2472,7 @@ std::string BuildToolsListResult(const Json::Value& id) { { Json::Value tool(Json::objectValue); tool["name"] = "remote_mouse"; - tool["description"] = u8"向已建立的远程控制会话注入鼠标事件。action 可选 move / down / up / click / right_click / middle_click / drag / scroll;坐标 x/y(及 drag 的 x2/y2)为归一化 0..1 浮点。button 可选 left/middle/right(默认 left);click 的 clicks 可选 1/2/3(默认 1);scroll 的 delta 正=向下滚、负=向上滚。"; + tool["description"] = u8"向已建立的远程控制会话注入鼠标事件。action 可选 move / down / up / click / right_click / middle_click / drag / scroll;坐标 x/y(及 drag 的 x2/y2)为归一化 0..1 浮点。button 可选 left/middle/right(默认 left);click 的 clicks 可选 1/2/3(默认 1);scroll 的 delta 正=向下滚、负=向上滚。可选 expect_hwnd / require_foreground / report_foreground 与 remote_keyboard 同义(新 Windows 客户端),可用它确认点击确实落在目标窗口。"; tool["inputSchema"] = BuildRemoteMouseInputSchema(); tool["outputSchema"] = BuildRemoteMouseOutputSchema(); tools.append(tool); @@ -2438,7 +2543,7 @@ std::string BuildToolsListResult(const Json::Value& id) { { Json::Value tool(Json::objectValue); tool["name"] = "operate_window"; - tool["description"] = u8"对指定在线 Windows 主机的窗口执行操作:close(关闭)/show(显示)/hide(隐藏)/minimize(最小化)/maximize(最大化)/restore(还原)。hwnd 取 list_windows 或 host_list_windows 返回的 hwnd。ok 仅表示已下发(窗口句柄可能已失效)。关闭窗口只有本工具能做,host_control_window 不提供 close,且它会重新枚举可见窗口复核结果。dry_run=true 只校验 hwnd 是否还在可见窗口列表里并返回该窗口信息,不发送任何命令。"; + tool["description"] = u8"对指定在线 Windows 主机的窗口执行操作:close(关闭)/show(显示)/hide(隐藏)/minimize(最小化)/maximize(最大化)/restore(还原)/activate(激活到前台)。hwnd 取 list_windows 或 host_list_windows 返回的 hwnd。ok 仅表示已下发(窗口句柄可能已失效);action=activate 例外:工具会在动作后用窗口信息 RPC 复核 GetForegroundWindow,返回 ok/state(foreground|background|missing)/window,旧客户端不支持时返回 -32005(可退回 show)。关闭窗口只有本工具能做,host_control_window 不提供 close,且它会重新枚举可见窗口复核结果。dry_run=true 只校验 hwnd 是否还在可见窗口列表里并返回该窗口信息,不发送任何命令。"; tool["inputSchema"] = BuildOperateWindowInputSchema(); tool["outputSchema"] = BuildOperateWindowOutputSchema(); tools.append(tool); @@ -2758,6 +2863,8 @@ void AppendHostTechnicalDetail(CMy2015RemoteDlg* parent, uint64_t devId, Json::V caps["fileTransferV2"] = ctx->SupportsFileV2(); caps["c2cPaths"] = ctx->SupportsC2CPaths(); caps["registry"] = IsWindowsClient(ctx); + // windowInfo → get_foreground_window / host_list_windows 的矩形与 activate(SupportsWindowInfo) + caps["windowInfo"] = ctx->SupportsWindowInfo(); host["capabilities"] = caps; } @@ -3173,6 +3280,59 @@ std::string BuildGetScreenshot(const Json::Value& id, const Json::Value& args, C return BuildResult(id, result); } +// tools/call:get_foreground_window(窗口信息 RPC,主连接,不建子链接、不弹框) +std::string BuildGetForegroundWindow(const Json::Value& id, const Json::Value& args, + CMy2015RemoteDlg* parent) { + uint64_t devId = 0; + std::string err; + if (!ParseHostIdArg(args, devId, err)) + return BuildError(id, -32602, err); + + context* ctx = FindMainContext(parent, devId); + if (!ctx) + return BuildError(id, -32002, "Host not found or offline: " + std::to_string(devId)); + + std::vector wins; + std::string ferr; + int rc = FetchWindowInfo(ctx, devId, "get_foreground_window", 0, wins, ferr); + if (rc == 1) + return BuildError(id, -32003, BusyMessage("Device busy: another request is pending for this host", devId)); + if (rc == 4) + return BuildError(id, -32005, "Host does not support window info (old client)"); + if (rc != 0) + return BuildError(id, rc == 2 ? -32001 : -32000, "Failed to get window info: " + ferr); + + const WindowEntry* fg = nullptr; + for (const WindowEntry& e : wins) { + if (e.flags & WINDOWINFO_FOREGROUND) { fg = &e; break; } + } + + Json::Value structuredContent(Json::objectValue); + structuredContent["windowCount"] = (Json::UInt)wins.size(); + structuredContent["window"] = fg ? WindowEntryToJson(*fg) : Json::Value(Json::nullValue); + + Json::Value result(Json::objectValue); + result["structuredContent"] = structuredContent; + + Json::Value content(Json::arrayValue); + Json::Value item(Json::objectValue); + item["type"] = "text"; + if (fg) { + item["text"] = std::string(u8"前台窗口:") + fg->title + + " (hwnd=" + std::to_string(fg->hwnd) + + ", pid=" + std::to_string(fg->pid) + + ", rect=" + std::to_string(fg->left) + "," + std::to_string(fg->top) + "," + + std::to_string(fg->right) + "," + std::to_string(fg->bottom) + ")"; + } else { + item["text"] = std::string(u8"未找到前台窗口(可能被 UAC/安全桌面遮挡,或客户端为老版本)"); + } + content.append(item); + result["content"] = content; + result["isError"] = false; + + return BuildResult(id, result); +} + // 新客户端的结构化失败回报布局:[token:1][win32/status:4 LE]。读取其中 4 字节错误码。 static DWORD ReadWin32Payload(const std::vector& data) { DWORD v = 0; @@ -5043,6 +5203,25 @@ Json::Value BuildRemoteKeyboardInputSchema() { mods["description"] = u8"修饰键(可选):CTRL/ALT/SHIFT/WIN"; props["modifiers"] = mods; + Json::Value expect(Json::objectValue); + Json::Value expectTypes(Json::arrayValue); + expectTypes.append("integer"); + expectTypes.append("string"); + expect["type"] = expectTypes; + expect["description"] = u8"可选:注入前先确认目标窗口仍在当前可见窗口列表中(整数或 0x 前缀字符串)。" + u8"顺带默认回报前台窗口;仅新 Windows 客户端支持(否则 -32005)。"; + props["expect_hwnd"] = expect; + + Json::Value requireFg(Json::objectValue); + requireFg["type"] = "boolean"; + requireFg["description"] = u8"可选:配合 expect_hwnd,要求该窗口已是前台,否则不发注入并返回 -32000。默认 false"; + props["require_foreground"] = requireFg; + + Json::Value reportFg(Json::objectValue); + reportFg["type"] = "boolean"; + reportFg["description"] = u8"可选:注入后回报前台窗口(structuredContent.foreground)。给了 expect_hwnd 时默认 true"; + props["report_foreground"] = reportFg; + Json::Value schema(Json::objectValue); schema["type"] = "object"; schema["properties"] = props; @@ -5056,6 +5235,26 @@ Json::Value BuildRemoteKeyboardInputSchema() { Json::Value BuildRemoteKeyboardOutputSchema() { Json::Value props(Json::objectValue); + + Json::Value windowProp(Json::objectValue); + windowProp["type"] = "object"; + windowProp["description"] = u8"expect_hwnd 时注入前的目标窗口快照"; + props["expectedWindow"] = windowProp; + + Json::Value fgProp(Json::objectValue); + // report_foreground 时若系统没有可枚举的前台窗口,foreground 为 null。 + Json::Value fgTypes(Json::arrayValue); + fgTypes.append("object"); + fgTypes.append("null"); + fgProp["type"] = fgTypes; + fgProp["description"] = u8"注入后的前台窗口(report_foreground 时返回;无前台窗口为 null)"; + props["foreground"] = fgProp; + + Json::Value fgErr(Json::objectValue); + fgErr["type"] = "string"; + fgErr["description"] = u8"前台回报失败的原因(注入本身已成功)"; + props["foregroundError"] = fgErr; + Json::Value schema(Json::objectValue); schema["type"] = "object"; schema["properties"] = props; @@ -5078,6 +5277,142 @@ static bool SendScreenCtrlEvents(context* subCtx, const std::vector& batc return true; } +// ===== 输入注入的窗口校验(expect_hwnd / require_foreground / report_foreground)===== +// +// 键鼠注入走屏幕子连接,窗口信息走主连接 RPC,两条链路互不占用,可安全地一前一后。 +// 这些辅助只在调用方显式要求时才发 RPC:注入本身不能因为「查不到前台窗口」而失败。 + +// 解析可选 hwnd(非零整数,或 "0x..." / 十进制字符串)。 +static bool GetOptionalWindowArg(const Json::Value& args, const char* key, uint32_t& out, + bool& present, std::string& err) { + present = false; + out = 0; + if (!args.isMember(key) || args[key].isNull()) return true; + + const Json::Value& v = args[key]; + uint64_t val = 0; + if (v.isNumeric()) { + if (v.isDouble()) { + double d = v.asDouble(); + if (d < 1.0 || d > 4294967295.0 || d != (double)(uint64_t)d) { + err = std::string("Invalid ") + key + ": expected a non-zero integer window handle"; + return false; + } + val = (uint64_t)d; + } else { + Json::Int64 n = v.asInt64(); + if (n <= 0) { + err = std::string("Invalid ") + key + ": expected a non-zero window handle"; + return false; + } + val = (uint64_t)n; + } + } else if (v.isString()) { + const std::string s = Trim(v.asString()); + char* end = nullptr; + if (s.size() > 2 && s[0] == '0' && (s[1] == 'x' || s[1] == 'X')) + val = strtoull(s.c_str() + 2, &end, 16); + else + val = strtoull(s.c_str(), &end, 10); + if (end == s.c_str() || *end != '\0') { + err = std::string("Invalid ") + key + ": expected a decimal integer or 0x-prefixed hex"; + return false; + } + } else { + err = std::string("Invalid ") + key + ": expected an integer or string window handle"; + return false; + } + + if (val == 0 || val > 0xFFFFFFFFull) { + err = std::string("Invalid ") + key + ": window handle out of range"; + return false; + } + out = (uint32_t)val; + present = true; + return true; +} + +static bool GetOptionalBoolArg(const Json::Value& args, const char* key, bool& out, + std::string& err) { + out = false; + if (!args.isMember(key) || args[key].isNull()) return true; + if (!args[key].isBool()) { + err = std::string("Invalid ") + key + ": expected a boolean"; + return false; + } + out = args[key].asBool(); + return true; +} + +struct WindowLookup { + int rc = 0; // FetchWindowInfo 返回码 + std::string err; + bool found = false; + bool foreground = false; + bool truncated = false; // 客户端可见窗口多于单包上限,列表不完整 + Json::Value json; // 目标窗口快照;未找到时为 null +}; + +// 按 hwnd 在最新可见窗口列表里查找(只发一次窗口信息 RPC)。 +static WindowLookup LookupWindow(context* ctx, uint64_t devId, const char* tool, uint32_t hwnd) { + WindowLookup w; + std::vector wins; + w.rc = FetchWindowInfo(ctx, devId, tool, 0, wins, w.err, &w.truncated); + if (w.rc != 0) { w.truncated = false; return w; } + for (const WindowEntry& e : wins) { + if (e.hwnd == hwnd) { + w.found = true; + w.foreground = (e.flags & WINDOWINFO_FOREGROUND) != 0; + w.json = WindowEntryToJson(e); + break; + } + } + return w; +} + +// 窗口信息 RPC 失败 → 序列化的 JSON-RPC 错误(与 get_foreground_window 同一错误口径)。 +static std::string WindowRpcErrorJson(const Json::Value& id, uint64_t devId, int rc, + const std::string& err) { + if (rc == 1) + return BuildError(id, -32003, BusyMessage("Device busy: another request is pending for this host", devId)); + if (rc == 4) + return BuildError(id, -32005, "Host does not support window info (old client)"); + return BuildError(id, rc == 2 ? -32001 : -32000, "Window check failed: " + err); +} + +// expect_hwnd 在窗口列表里没命中:列表被单包上限截断时不能说"窗口不存在", +// 只能说明它没出现在返回的这一批里。 +static std::string WindowNotFoundErrorJson(const Json::Value& id, uint32_t hwnd, bool truncated) { + const std::string win = "Window hwnd=" + std::to_string(hwnd); + if (truncated) + return BuildError(id, -32009, win + " is not in the returned window list, and that list was " + "truncated at 96 windows (the host has more visible windows), " + "so the window may still exist; verify with host_list_windows " + "or use the foreground window"); + return BuildError(id, -32009, win + " is not in the current visible window list " + "(hidden, closed, or not a visible top-level window)"); +} + +// 注入后回报前台窗口。失败只写 foregroundError:注入已经发生,不能因此把工具判失败。 +static void AppendForegroundReport(Json::Value& structuredContent, context* ctx, uint64_t devId, + const char* tool) { + Sleep(150); + std::vector wins; + std::string ferr; + int rc = FetchWindowInfo(ctx, devId, tool, 0, wins, ferr); + if (rc != 0) { + structuredContent["foregroundError"] = ferr; + return; + } + for (const WindowEntry& e : wins) { + if (e.flags & WINDOWINFO_FOREGROUND) { + structuredContent["foreground"] = WindowEntryToJson(e); + return; + } + } + structuredContent["foreground"] = Json::Value(Json::nullValue); +} + // tools/call:remote_keyboard(键盘注入;成功返回空对象) std::string BuildRemoteKeyboard(const Json::Value& id, const Json::Value& args, CMy2015RemoteDlg* parent) { CMcpServer& mcp = CMcpServer::Instance(); @@ -5140,6 +5475,28 @@ std::string BuildRemoteKeyboard(const Json::Value& id, const Json::Value& args, if (batch.empty()) return BuildError(id, -32602, "No key events generated"); + // ---- expect_hwnd / require_foreground:注入前核对目标窗口(可选,走窗口信息 RPC)---- + uint32_t expectHwnd = 0; + bool hasExpect = false, requireForeground = false, reportForeground = false; + { + std::string oerr; + if (!GetOptionalWindowArg(args, "expect_hwnd", expectHwnd, hasExpect, oerr)) + return BuildError(id, -32602, oerr); + if (!GetOptionalBoolArg(args, "require_foreground", requireForeground, oerr)) + return BuildError(id, -32602, oerr); + if (!GetOptionalBoolArg(args, "report_foreground", reportForeground, oerr)) + return BuildError(id, -32602, oerr); + if (requireForeground && !hasExpect) + return BuildError(id, -32602, "require_foreground requires expect_hwnd"); + if ((hasExpect || reportForeground) && !ctx->SupportsWindowInfo()) + return BuildError(id, -32005, + "expect_hwnd/report_foreground require window info capability, " + "which this host does not support (newer Windows clients only)"); + // 未显式指定 report_foreground 时,只要给了 expect_hwnd 就默认回报前台窗口。 + if (!args.isMember("report_foreground") || args["report_foreground"].isNull()) + reportForeground = hasExpect; + } + // 校验 session_id/busy 并置 busy(注入期间 close/sweep/断线不擦会话,镜像终端 busy 模式)。 context* subCtx = nullptr; int screenW = 0, screenH = 0; @@ -5147,6 +5504,26 @@ std::string BuildRemoteKeyboard(const Json::Value& id, const Json::Value& args, if (r == 2) return BuildError(id, -32003, "Device busy: another injection is in flight for this session"); if (r == 1) return BuildError(id, -32002, "Remote control session not found, not ready, or closed: " + sessionId); + // 窗口核对放在会话校验之后:session_id 无效时应当先报会话错误,不白跑一次 RPC; + // busy 已置上,窗口不满足时必须先释放再返回。 + WindowLookup expectWin; + if (hasExpect) { + expectWin = LookupWindow(ctx, devId, "remote_keyboard", expectHwnd); + std::string winErr; + if (expectWin.rc != 0) + winErr = WindowRpcErrorJson(id, devId, expectWin.rc, expectWin.err); + else if (!expectWin.found) + winErr = WindowNotFoundErrorJson(id, expectHwnd, expectWin.truncated); + else if (requireForeground && !expectWin.foreground) + winErr = BuildError(id, -32000, "Window hwnd=" + std::to_string(expectHwnd) + + " is not the foreground window; activate it first " + "(host_control_window / operate_window action=activate)"); + if (!winErr.empty()) { + mcp.EndScreenCtrlAction(devId, sessionId); + return winErr; + } + } + bool ok = SendScreenCtrlEvents(subCtx, batch); mcp.EndScreenCtrlAction(devId, sessionId); @@ -5166,7 +5543,10 @@ std::string BuildRemoteKeyboard(const Json::Value& id, const Json::Value& args, } Json::Value result(Json::objectValue); - result["structuredContent"] = Json::Value(Json::objectValue); + Json::Value structuredContent(Json::objectValue); + if (hasExpect) structuredContent["expectedWindow"] = expectWin.json; + if (reportForeground) AppendForegroundReport(structuredContent, ctx, devId, "remote_keyboard"); + result["structuredContent"] = structuredContent; Json::Value content(Json::arrayValue); Json::Value item(Json::objectValue); item["type"] = "text"; @@ -5280,6 +5660,25 @@ Json::Value BuildRemoteMouseInputSchema() { del["description"] = u8"滚动量(仅 scroll;正=向下滚,负=向上滚,与 Web 控制台一致;仅垂直滚轮,忽略 button)"; props["delta"] = del; + Json::Value expect(Json::objectValue); + Json::Value expectTypes(Json::arrayValue); + expectTypes.append("integer"); + expectTypes.append("string"); + expect["type"] = expectTypes; + expect["description"] = u8"可选:注入前先确认目标窗口仍在当前可见窗口列表中(整数或 0x 前缀字符串)。" + u8"顺带默认回报前台窗口;仅新 Windows 客户端支持(否则 -32005)。"; + props["expect_hwnd"] = expect; + + Json::Value requireFg(Json::objectValue); + requireFg["type"] = "boolean"; + requireFg["description"] = u8"可选:配合 expect_hwnd,要求该窗口已是前台,否则不发注入并返回 -32000。默认 false"; + props["require_foreground"] = requireFg; + + Json::Value reportFg(Json::objectValue); + reportFg["type"] = "boolean"; + reportFg["description"] = u8"可选:注入后回报前台窗口(structuredContent.foreground)。给了 expect_hwnd 时默认 true"; + props["report_foreground"] = reportFg; + Json::Value schema(Json::objectValue); schema["type"] = "object"; schema["properties"] = props; @@ -5295,6 +5694,26 @@ Json::Value BuildRemoteMouseInputSchema() { Json::Value BuildRemoteMouseOutputSchema() { Json::Value props(Json::objectValue); + + Json::Value windowProp(Json::objectValue); + windowProp["type"] = "object"; + windowProp["description"] = u8"expect_hwnd 时注入前的目标窗口快照"; + props["expectedWindow"] = windowProp; + + Json::Value fgProp(Json::objectValue); + // report_foreground 时若系统没有可枚举的前台窗口,foreground 为 null。 + Json::Value fgTypes(Json::arrayValue); + fgTypes.append("object"); + fgTypes.append("null"); + fgProp["type"] = fgTypes; + fgProp["description"] = u8"注入后的前台窗口(report_foreground 时返回;无前台窗口为 null)"; + props["foreground"] = fgProp; + + Json::Value fgErr(Json::objectValue); + fgErr["type"] = "string"; + fgErr["description"] = u8"前台回报失败的原因(注入本身已成功)"; + props["foregroundError"] = fgErr; + Json::Value schema(Json::objectValue); schema["type"] = "object"; schema["properties"] = props; @@ -5355,6 +5774,28 @@ std::string BuildRemoteMouse(const Json::Value& id, const Json::Value& args, CMy if (!GetNormCoord(args, "y2", ny2, coordErr)) return BuildError(id, -32602, coordErr); } + // ---- expect_hwnd / require_foreground:注入前核对目标窗口(可选,走窗口信息 RPC)---- + uint32_t expectHwnd = 0; + bool hasExpect = false, requireForeground = false, reportForeground = false; + { + std::string oerr; + if (!GetOptionalWindowArg(args, "expect_hwnd", expectHwnd, hasExpect, oerr)) + return BuildError(id, -32602, oerr); + if (!GetOptionalBoolArg(args, "require_foreground", requireForeground, oerr)) + return BuildError(id, -32602, oerr); + if (!GetOptionalBoolArg(args, "report_foreground", reportForeground, oerr)) + return BuildError(id, -32602, oerr); + if (requireForeground && !hasExpect) + return BuildError(id, -32602, "require_foreground requires expect_hwnd"); + if ((hasExpect || reportForeground) && !ctx->SupportsWindowInfo()) + return BuildError(id, -32005, + "expect_hwnd/report_foreground require window info capability, " + "which this host does not support (newer Windows clients only)"); + if (!args.isMember("report_foreground") || args["report_foreground"].isNull()) + reportForeground = hasExpect; + } + WindowLookup expectWin; + // 校验 session_id/busy 并置 busy,同时取抓屏帧尺寸(screenW/H>0 由会话就绪保证)。 context* subCtx = nullptr; int screenW = 0, screenH = 0; @@ -5362,6 +5803,25 @@ std::string BuildRemoteMouse(const Json::Value& id, const Json::Value& args, CMy if (r == 2) return BuildError(id, -32003, "Device busy: another injection is in flight for this session"); if (r == 1) return BuildError(id, -32002, "Remote control session not found, not ready, or closed: " + sessionId); + // 窗口核对放在会话校验之后:session_id 无效时应当先报会话错误,不白跑一次 RPC; + // busy 已置上,窗口不满足时必须先释放再返回。 + if (hasExpect) { + expectWin = LookupWindow(ctx, devId, "remote_mouse", expectHwnd); + std::string winErr; + if (expectWin.rc != 0) + winErr = WindowRpcErrorJson(id, devId, expectWin.rc, expectWin.err); + else if (!expectWin.found) + winErr = WindowNotFoundErrorJson(id, expectHwnd, expectWin.truncated); + else if (requireForeground && !expectWin.foreground) + winErr = BuildError(id, -32000, "Window hwnd=" + std::to_string(expectHwnd) + + " is not the foreground window; activate it first " + "(host_control_window / operate_window action=activate)"); + if (!winErr.empty()) { + mcp.EndScreenCtrlAction(devId, sessionId); + return winErr; + } + } + // 归一化坐标 → 发送帧像素(round + clamp 到 [0, screen-1];客户端 PointConversion 再换算为物理坐标) auto toPxX = [&](double n) -> int { int p = (int)(n * screenW + 0.5); return p < 0 ? 0 : (p > screenW - 1 ? screenW - 1 : p); }; auto toPxY = [&](double n) -> int { int p = (int)(n * screenH + 0.5); return p < 0 ? 0 : (p > screenH - 1 ? screenH - 1 : p); }; @@ -5430,7 +5890,10 @@ std::string BuildRemoteMouse(const Json::Value& id, const Json::Value& args, CMy } Json::Value result(Json::objectValue); - result["structuredContent"] = Json::Value(Json::objectValue); + Json::Value structuredContent(Json::objectValue); + if (hasExpect) structuredContent["expectedWindow"] = expectWin.json; + if (reportForeground) AppendForegroundReport(structuredContent, ctx, devId, "remote_mouse"); + result["structuredContent"] = structuredContent; Json::Value content(Json::arrayValue); Json::Value item(Json::objectValue); item["type"] = "text"; @@ -7066,8 +7529,15 @@ std::string BuildOperateWindow(const Json::Value& id, const Json::Value& args, C else if (action == "restore") dHow = SW_NORMAL; // 1 else if (action == "maximize") dHow = SW_MAXIMIZE; // 3 else if (action == "minimize") dHow = SW_MINIMIZE; // 6 + else if (action == "activate") { + // 后台窗口仅 ShowWindow 不会升到前台:依赖新客户端的激活实现。 + if (!ctx->SupportsWindowInfo()) + return BuildError(id, -32005, + "activate requires a newer client (window info capability); use show instead"); + dHow = CMD_WINDOW_ACTIVATE_FLAG; + } else return BuildError(id, -32602, - "Invalid action: " + action + " (expect close|show|hide|minimize|maximize|restore)"); + "Invalid action: " + action + " (expect close|show|hide|minimize|maximize|restore|activate)"); lpMsgBuf[0] = CMD_WINDOW_TEST; memcpy(lpMsgBuf + 1, &h, sizeof(DWORD)); memcpy(lpMsgBuf + 1 + sizeof(DWORD), &dHow, sizeof(DWORD)); @@ -7145,6 +7615,60 @@ std::string BuildOperateWindow(const Json::Value& id, const Json::Value& args, C AuditManageAction(parent, devId, "operate_window", "action=" + action + " hwnd=" + std::to_string(hwnd)); + if (action == "activate") { + Sleep(300); // 给客户端激活线程 / 系统前台切换留出时间 + std::vector wins; + std::string ferr; + bool winTruncated = false; + int rc = FetchWindowInfo(ctx, devId, "operate_window", 0, wins, ferr, &winTruncated); + if (rc == 1) + return BuildError(id, -32003, BusyMessage("Device busy: another request is pending for this host", devId)); + + const WindowEntry* target = nullptr; + if (rc == 0) { + for (const WindowEntry& e : wins) { + if (e.hwnd == (uint32_t)hwnd) { target = &e; break; } + } + } + bool isForeground = target && (target->flags & WINDOWINFO_FOREGROUND) != 0; + // 列表被 96 条上限截断时,没找到目标只是"没看到",不能断言窗口不存在。 + const bool listIncomplete = (rc == 0 && winTruncated); + std::string state = (rc != 0) ? "unknown" + : (!target ? (listIncomplete ? "unknown" : "missing") + : (isForeground ? "foreground" : "background")); + + Json::Value result(Json::objectValue); + Json::Value structuredContent(Json::objectValue); + structuredContent["ok"] = isForeground; + structuredContent["action"] = action; + structuredContent["state"] = state; + structuredContent["window"] = target ? WindowEntryToJson(*target) : Json::Value(Json::nullValue); + if (rc != 0) + structuredContent["verifyError"] = ferr; + else if (listIncomplete) + structuredContent["truncated"] = true; + result["structuredContent"] = structuredContent; + + Json::Value content(Json::arrayValue); + Json::Value item(Json::objectValue); + item["type"] = "text"; + if (isForeground) + item["text"] = u8"窗口已激活并成为前台窗口(复核 GetForegroundWindow 一致)"; + else if (rc != 0) + item["text"] = u8"窗口操作已下发,但前台复核失败:" + ferr; + else if (!target && listIncomplete) + item["text"] = u8"窗口操作已下发,但复核用的窗口列表被单次上限截断(可见窗口超过 96 个)," + u8"目标不在返回的这一批里,无法确认是否已到前台"; + else if (!target) + item["text"] = u8"窗口操作已下发,但复核时目标窗口不在可见窗口列表中(可能已关闭或已隐藏)"; + else + item["text"] = u8"窗口操作已下发,但目标窗口仍未成为前台窗口(可能被系统前台锁定策略拦下,可重试)"; + content.append(item); + result["content"] = content; + result["isError"] = false; + return BuildResult(id, result); + } + Json::Value result(Json::objectValue); Json::Value structuredContent(Json::objectValue); structuredContent["ok"] = true; @@ -8838,6 +9362,8 @@ const ToolPlatform kToolPlatforms[] = { { "upload_file", kPlatWin|kPlatLnx|kPlatMac }, // ---- win+lnx ---- 远程控制全族 + 需 SCREEN_PREVIEW 的截屏 + macOS 未开放项 { "get_screenshot", kPlatWin|kPlatLnx }, + // 窗口信息 RPC 只在 Windows 客户端实现(CLIENT_CAP_WINDOW_INFO) + { "get_foreground_window", kPlatWin }, { "remote_open", kPlatWin|kPlatLnx }, { "remote_close", kPlatWin|kPlatLnx }, { "remote_keyboard", kPlatWin|kPlatLnx }, @@ -9192,6 +9718,7 @@ std::string DispatchSingleHostTool(const Json::Value& id, const std::string& too if (toolName == "list_windows") return BuildListWindows(id, args, parent); if (toolName == "get_activity_history") return BuildGetActivityHistory(id, args, parent); if (toolName == "get_screenshot") return BuildGetScreenshot(id, args, parent); + if (toolName == "get_foreground_window") return BuildGetForegroundWindow(id, args, parent); if (toolName == "list_files") return BuildListFiles(id, args, parent); if (toolName == "list_services") return BuildListServices(id, args, parent); if (toolName == "get_client_log") return BuildGetClientLog(id, args, parent); diff --git a/server/2015Remote/context.h b/server/2015Remote/context.h index d437d59..ee71397 100644 --- a/server/2015Remote/context.h +++ b/server/2015Remote/context.h @@ -114,6 +114,15 @@ public: return (strtoul(caps.GetString(), nullptr, 16) & CLIENT_CAP_VIRTUAL_DESKTOP) != 0; } + // 检查客户端是否支持窗口信息 RPC(COMMAND_MCP_WINDOW_INFO / TOKEN_MCP_WINDOW_INFO): + // 带屏幕矩形、z 序、前后台/最小化状态的窗口列表,以及窗口激活(CMD_WINDOW_ACTIVATE_FLAG)。 + // 未声明的老客户端只能走固定 1044 字节、无矩形的 TOKEN_MACHINE_WINDOWS 旧路径。 + bool SupportsWindowInfo() const { + CString caps = GetClientData(ONLINELIST_CAPABILITIES); + if (caps.IsEmpty()) return false; + return (strtoul(caps.GetString(), nullptr, 16) & CLIENT_CAP_WINDOW_INFO) != 0; + } + // 检查客户端是否支持远程协议切换(COMMAND_SET_PROTO)。老客户端没有这个命令, // 收到也会走 default 丢弃,服务端据此把「协议切换」菜单置灰。 bool SupportsProtoSwitch() const { diff --git a/tools/mcp_tools/README.md b/tools/mcp_tools/README.md index c4935ef..9712358 100644 --- a/tools/mcp_tools/README.md +++ b/tools/mcp_tools/README.md @@ -1,6 +1,6 @@ # MCP 工具清单维护 -`mcp/tools.json` 是 MCP 全部 60 个工具的**单一来源候选**:工具名、描述、 +`mcp/tools.json` 是 MCP 全部 61 个工具的**单一来源候选**:工具名、描述、 inputSchema、outputSchema,以及运行时不可见的开关元信息(`gate` / `write` / `manage`)。 它的用途不限于给 Go 服务端复用。当前 26KB 的工具描述埋在 11k 行 C++ 里, @@ -35,7 +35,7 @@ python tools/mcp_tools/make_tools_json.py /tmp/tools_raw.json mcp/tools.json python tools/mcp_tools/verify_tools.py --live mcp/tools.json ``` -第 3 步输出 `PASS: 60 个工具完全一致` 才算成功。 +第 3 步输出 `PASS: 61 个工具完全一致` 才算成功。 ### 如果工具数量变了 @@ -49,7 +49,7 @@ python tools/mcp_tools/verify_tools.py --live mcp/tools.json 这是有意为之——`gate` / `write` / `manage` 三项在运行时不可见,只能从 C++ 注册点的 `if` 条件读出来,必须人工确认。补表时对照: -- `McpServer.cpp:BuildToolsListResult` —— 内联的 40 个 +- `McpServer.cpp:BuildToolsListResult` —— 内联的 41 个 - `McpMachine.cpp:AppendTools` —— 16 个(总开关 `IsMachineEnabled` 用 early return) - `McpChat.cpp:AppendTools` —— 4 个(总开关 `IsChatEnabled` 用 early return) @@ -87,14 +87,14 @@ python tools/mcp_tools/verify_tools.py --live mcp/tools.json | 命令分支 | `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` | -当前分布(60 个工具): +当前分布(61 个工具): | platforms | 数量 | 典型工具 | |---|---|---| | `win+lnx+mac+apk` | 10 | 只读写服务端本地数据:`list_online_hosts` / `get_audit_log` / `mcp_*` | | `win+lnx+mac` | 6 | 进程列表、文件列取、日志、V2 文件传输、`copy_files_c2c` | -| `win+lnx` | 11 | `remote_*` 全族、`get_screenshot`、`exec_command` / `terminal_*` / `kill_process` | -| `win` | 33 | 服务 / 注册表 / 键日志 / 文件写 / **`list_windows`** / `host_*` / `chat_*` / `power_action` | +| `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, @@ -186,7 +186,7 @@ macOS 客户端其实有对应实现(`macos/main.mm:753` 的 `ShellworkingThre ```bash python tools/mcp_tools/check_platform_table.py -# PASS: 60 个工具的 platforms 两边完全一致,且门禁都能拿到主机 id +# PASS: 61 个工具的 platforms 两边完全一致,且门禁都能拿到主机 id ``` ## 与 Go 服务端的关系 diff --git a/tools/mcp_tools/make_tools_json.py b/tools/mcp_tools/make_tools_json.py index bdbde7e..61b069f 100644 --- a/tools/mcp_tools/make_tools_json.py +++ b/tools/mcp_tools/make_tools_json.py @@ -29,6 +29,7 @@ GATE = { "list_windows": (None, False, False), "get_activity_history": (None, False, False), "get_screenshot": (None, False, False), + "get_foreground_window": (None, False, False), "list_files": (None, False, False), "list_services": (None, False, False), "get_client_log": (None, False, False), @@ -177,7 +178,8 @@ PLATFORMS = { "control_service": _WIN, "list_registry": _WIN, "get_keylog": _WIN, - "get_activity_history": _WIN, + "get_activity_history": _WL, # Windows 前台窗口;Linux 桌面/无桌面均有实现(linux/main.cpp) + "get_foreground_window": _WIN, # 窗口信息 RPC:CLIENT_CAP_WINDOW_INFO,仅 Windows 客户端声明 "search_file": _WIN, "delete_path": _WIN, "move_path": _WIN,