Feature: Add window info RPC for foreground checks and window activation

Add a capability-gated main-connection RPC (COMMAND_MCP_WINDOW_INFO=179 /
TOKEN_MCP_WINDOW_INFO=180) that returns visible top-level windows with UTF-8
titles, screen rectangles, foreground flag and z-order, so MCP can verify
focus before injecting input. New tool get_foreground_window; host_list_windows
switches to the richer fields; host_control_window and operate_window gain
action=activate; remote_keyboard and remote_mouse gain expect_hwnd,
require_foreground and report_foreground. Old clients keep the previous
behavior: the RPC is refused up front via CLIENT_CAP_WINDOW_INFO.

The client caps a response at 96 windows (about 101 KB, under MAX_SEND_BUFFER).
Signal the cut-off in the mode byte (0x80) instead of silently dropping windows:
host_list_windows now reports truncated=true and says the list is incomplete,
and activate verification reports state=unknown with reason=list_truncated
rather than claiming the window is gone. expect_hwnd is checked only after the
session is validated, so an invalid session_id no longer burns a window RPC and
no longer reports a window error for a session that does not exist. Nullable
output fields (foreground, window) are declared as ["object","null"] so strict
clients do not reject responses.

Co-Authored-By: deepseek-flash
This commit is contained in:
yuanyuanxianganddeepseek-flash committed 2026-11-10 15:09:24 +01:00
1 parent c7e23f750d
commit b2c0d81396
18 files changed
+1298 -68

No files matched your search

+120 -16
View File
@@ -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<BYTE> 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<WindowEntry> 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<BYTE> 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<WindowEntry> 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<BYTE> 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());
}