Fix(mcp): bound host_inspect, precheck remote_open, name the busy holder

Three smaller contract fixes that remove ways for an agent call to hang
or fail without an explanation:

- host_inspect with several aspects opens one sub-connection per aspect
  (5s ready + 12s list each), so all ten could run ~170s and outlive the
  caller's HTTP timeout. After 60s no new aspect is started; the running
  one finishes on its own timeout and the skipped ones land in
  errors.<aspect> with code -32001 and a "skipped:" message, so the model
  can retry with fewer aspects.
- remote_open checked nothing before opening the hidden screen session.
  A Linux host that declares capability bits but not
  CLIENT_CAP_SCREEN_PREVIEW has no X11 display, so capture and injection
  cannot work: return -32005 immediately instead of waiting out
  timeout_ms and then reporting a sub-connection timeout. Android is
  deliberately excluded -- its SCREEN_PREVIEW bit tracks accessibility
  (API 30+ takeScreenshot for get_screenshot), while remote control uses
  MediaProjection capture and dispatchGesture, which can work without it.
  Old hosts with empty caps are still let through.
- The -32003 busy errors in remote_open now append the DescribeBusy
  suffix (tool, elapsed), matching the other busy paths.

tools.json descriptions are kept byte-identical to the C++ literals.
Debug build green; check_platform_table, gen_go_tools --check and
go test ./... pass.

Co-Authored-By: deepseek-flash
This commit is contained in:
yuanyuanxianganddeepseek-flash committed 2026-11-13 12:43:37 +01:00
1 parent d49ebe521d
commit 61b9031269
3 files changed
+46 -7

No files matched your search

+2 -2
View File
@@ -1692,7 +1692,7 @@
},
{
"name": "remote_open",
"description": "在指定在线 Windows、Linux 或 Android 主机上建立远程控制会话(隐藏屏幕子连接)并返回 session_id、抓屏帧尺寸(screen_w/screen_h)与目标(target)。默认推整屏/整虚拟桌面(可能等比缩放);可用 window_hwnd 只推一个窗口,或用 region 只推一个矩形区域,带宽、延迟和点击精度都更好,此时归一化坐标 0..1 相对该目标帧。后续 remote_mouse/remote_keyboard 用归一化坐标(0..1)注入输入,用毕须 remote_close。Linux 需要 X11/Xorg(或 XWayland)桌面,纯 Wayland 会话无法抓屏/注入;window_hwnd/region 仅支持声明 CLIENT_CAP_WINDOW_INFO 的新 Windows 客户端。Windows 多显示器下整屏目标需要新版客户端(整虚拟桌面抓屏),老客户端会被拒绝;window 目标不依赖虚拟桌面抓屏,不受此限。Android 主机只支持整屏目标,输入被翻译成触摸手势与全局动作(见 remote_mouse / remote_keyboard);抓屏依赖客户端已授权录屏(MediaProjection),未授权时 remote_open 会一直等不到屏幕子连接,注入还依赖无障碍服务在跑(未开启时命令照样下发但不生效,且没有回执)。",
"description": "在指定在线 Windows、Linux 或 Android 主机上建立远程控制会话(隐藏屏幕子连接)并返回 session_id、抓屏帧尺寸(screen_w/screen_h)与目标(target)。默认推整屏/整虚拟桌面(可能等比缩放);可用 window_hwnd 只推一个窗口,或用 region 只推一个矩形区域,带宽、延迟和点击精度都更好,此时归一化坐标 0..1 相对该目标帧。后续 remote_mouse/remote_keyboard 用归一化坐标(0..1)注入输入,用毕须 remote_close。Linux 需要 X11/Xorg(或 XWayland)桌面,纯 Wayland 会话无法抓屏/注入(这类主机直接返回 -32005);window_hwnd/region 仅支持声明 CLIENT_CAP_WINDOW_INFO 的新 Windows 客户端。Windows 多显示器下整屏目标需要新版客户端(整虚拟桌面抓屏),老客户端会被拒绝;window 目标不依赖虚拟桌面抓屏,不受此限。Android 主机只支持整屏目标,输入被翻译成触摸手势与全局动作(见 remote_mouse / remote_keyboard);抓屏依赖客户端已授权录屏(MediaProjection),未授权时 remote_open 会一直等不到屏幕子连接,注入还依赖无障碍服务在跑(未开启时命令照样下发但不生效,且没有回执)。",
"gate": "remote_control",
"write": true,
"platforms": [
@@ -3468,7 +3468,7 @@
},
{
"name": "host_inspect",
"description": "一次取回在线 Windows 主机的多类主机管理信息(原 10 个 host_list_* 工具合并)。aspects 必填、可多选:processes(进程:PID/架构/窗口标题/路径/优先级/线程数/用户/工作集与文件大小)| windows(当前可见顶层窗口;只含可见窗口,单次最多 96 条,超出时 truncated=true 且列表不完整,不能据此断定某窗口不存在;hwnd 可交给 host_control_window / operate_window)| network(网络连接,进程视角、含 UDP;与 list_network_connections 的「连接管理」数据源不同)| software(已安装软件,来自注册表 Uninstall 项;不提供卸载)| browser_history(IE 浏览历史,隐私数据)| favorites(IE 收藏夹,隐私数据)| win32_services(Win32 服务;服务名可用于 host_control_service)| driver_services(驱动服务;字段同 win32_services)| scheduled_tasks(计划任务;任务名 + folder 可用于 host_control_task)| hosts_file(按行返回并自动识别 UTF-8/GBK)。注意:win32_services / driver_services 要求客户端以管理员权限运行——非提权客户端拿不到 SCM 句柄后直接不回应,调用会在约 12 秒后超时(同等场景 list_services 会明确报 access denied)。过滤参数按 aspect 生效、其余忽略(见各参数说明),在服务端完成且先于分页:total 为命中数、totalAll 为该项全部条目数。单个 aspect 时顶层就是该项的列表结果(与合并前的旧工具一致);多个 aspect 时汇总在 results.<aspect>,某个 aspect 失败只记入 errors.<aspect>、不影响其它 aspect,全部失败才 isError=true。每多选一个 aspect 就多一次子连接,耗时线性增长,不需要的不要选。只读。",
"description": "一次取回在线 Windows 主机的多类主机管理信息(原 10 个 host_list_* 工具合并)。aspects 必填、可多选:processes(进程:PID/架构/窗口标题/路径/优先级/线程数/用户/工作集与文件大小)| windows(当前可见顶层窗口;只含可见窗口,单次最多 96 条,超出时 truncated=true 且列表不完整,不能据此断定某窗口不存在;hwnd 可交给 host_control_window / operate_window)| network(网络连接,进程视角、含 UDP;与 list_network_connections 的「连接管理」数据源不同)| software(已安装软件,来自注册表 Uninstall 项;不提供卸载)| browser_history(IE 浏览历史,隐私数据)| favorites(IE 收藏夹,隐私数据)| win32_services(Win32 服务;服务名可用于 host_control_service)| driver_services(驱动服务;字段同 win32_services)| scheduled_tasks(计划任务;任务名 + folder 可用于 host_control_task)| hosts_file(按行返回并自动识别 UTF-8/GBK)。注意:win32_services / driver_services 要求客户端以管理员权限运行——非提权客户端拿不到 SCM 句柄后直接不回应,调用会在约 12 秒后超时(同等场景 list_services 会明确报 access denied)。过滤参数按 aspect 生效、其余忽略(见各参数说明),在服务端完成且先于分页:total 为命中数、totalAll 为该项全部条目数。单个 aspect 时顶层就是该项的列表结果(与合并前的旧工具一致);多个 aspect 时汇总在 results.<aspect>,某个 aspect 失败只记入 errors.<aspect>、不影响其它 aspect,全部失败才 isError=true。每多选一个 aspect 就多一次子连接,耗时线性增长,不需要的不要选;多个 aspect 共用 60 秒预算,用尽后不再下发新的 aspect(正在跑的会跑完),跳过的逐个记入 errors(code=-32001,message 以 skipped 开头),少选几项重试即可。只读。",
"gate": "machine",
"platforms": [
"win"
+24 -2
View File
@@ -52,6 +52,11 @@ const int kActionTimeoutMs = 12000; // 动作 → 客户端自动回的刷新
// 每步最多 12s,故留 60s 余量;单步等待再按剩余时间收敛。
const int kSessionDeadlineMs = 60000;
// host_inspect 多 aspect 的总预算(软截止):每个 aspect 最坏 5s 就绪 + 12s 列表,10 个
// 全选要 170s,HTTP 调用方会先超时。60 秒后不再下发新的 aspect,正在跑的那个按自身
// 超时跑完;跳过的逐个记入 errors,让调用方看到「没来得及取」而不是一直等。
const int kInspectTotalBudgetMs = 60000;
// 单个包的上限:正常列表远小于此;超过即视为异常,置 clientError 并断开子连接。
const size_t kMaxPacketBytes = 8u * 1024u * 1024u;
@@ -2194,9 +2199,24 @@ std::string BuildHostInspect(const Json::Value& id, const Json::Value& args,
Json::Value errors(Json::objectValue);
std::string summary;
int okCount = 0, failCount = 0;
const auto deadline = std::chrono::steady_clock::now() +
std::chrono::milliseconds(kInspectTotalBudgetMs);
for (const InspectAspect* a : aspects) {
InspectRun run;
if (!summary.empty()) summary += u8";";
// 总预算用尽:剩余的 aspect 不再下发。逐个记入 errors(而不是让整个调用失败),
// 调用方据此知道是「没来得及取」,可以少选几项重试。
if (std::chrono::steady_clock::now() >= deadline) {
Json::Value e(Json::objectValue);
e["code"] = -32001;
e["message"] = std::string("skipped: host_inspect used up its ") +
std::to_string(kInspectTotalBudgetMs / 1000) +
"s budget; retry with fewer aspects or a faster host";
errors[a->name] = e;
failCount++;
summary += std::string(a->what) + u8":跳过(总预算用尽)";
continue;
}
InspectRun run;
if (RunInspectAspect(*a, id, args, parent, run)) {
results[a->name] = run.sc;
okCount++;
@@ -3188,7 +3208,9 @@ void AppendTools(Json::Value& tools) {
u8"total 为命中数、totalAll 为该项全部条目数。"
u8"单个 aspect 时顶层就是该项的列表结果(与合并前的旧工具一致);多个 aspect 时汇总在 "
u8"results.<aspect>,某个 aspect 失败只记入 errors.<aspect>、不影响其它 aspect,全部失败才 isError=true。"
u8"每多选一个 aspect 就多一次子连接,耗时线性增长,不需要的不要选。只读。",
u8"每多选一个 aspect 就多一次子连接,耗时线性增长,不需要的不要选;多个 aspect 共用 "
u8"60 秒预算,用尽后不再下发新的 aspect(正在跑的会跑完),跳过的逐个记入 errors"
u8"(code=-32001,message 以 skipped 开头),少选几项重试即可。只读。",
BuildHostInspectInputSchema(), BuildHostInspectOutputSchema());
}
+20 -3
View File
@@ -2579,7 +2579,7 @@ std::string BuildToolsListResult(const Json::Value& id) {
{
Json::Value tool(Json::objectValue);
tool["name"] = "remote_open";
tool["description"] = u8"在指定在线 Windows、Linux 或 Android 主机上建立远程控制会话(隐藏屏幕子连接)并返回 session_id、抓屏帧尺寸(screen_w/screen_h)与目标(target)。默认推整屏/整虚拟桌面(可能等比缩放);可用 window_hwnd 只推一个窗口,或用 region 只推一个矩形区域,带宽、延迟和点击精度都更好,此时归一化坐标 0..1 相对该目标帧。后续 remote_mouse/remote_keyboard 用归一化坐标(0..1)注入输入,用毕须 remote_close。Linux 需要 X11/Xorg(或 XWayland)桌面,纯 Wayland 会话无法抓屏/注入;window_hwnd/region 仅支持声明 CLIENT_CAP_WINDOW_INFO 的新 Windows 客户端。Windows 多显示器下整屏目标需要新版客户端(整虚拟桌面抓屏),老客户端会被拒绝;window 目标不依赖虚拟桌面抓屏,不受此限。Android 主机只支持整屏目标,输入被翻译成触摸手势与全局动作(见 remote_mouse / remote_keyboard);抓屏依赖客户端已授权录屏(MediaProjection),未授权时 remote_open 会一直等不到屏幕子连接,注入还依赖无障碍服务在跑(未开启时命令照样下发但不生效,且没有回执)。";
tool["description"] = u8"在指定在线 Windows、Linux 或 Android 主机上建立远程控制会话(隐藏屏幕子连接)并返回 session_id、抓屏帧尺寸(screen_w/screen_h)与目标(target)。默认推整屏/整虚拟桌面(可能等比缩放);可用 window_hwnd 只推一个窗口,或用 region 只推一个矩形区域,带宽、延迟和点击精度都更好,此时归一化坐标 0..1 相对该目标帧。后续 remote_mouse/remote_keyboard 用归一化坐标(0..1)注入输入,用毕须 remote_close。Linux 需要 X11/Xorg(或 XWayland)桌面,纯 Wayland 会话无法抓屏/注入(这类主机直接返回 -32005);window_hwnd/region 仅支持声明 CLIENT_CAP_WINDOW_INFO 的新 Windows 客户端。Windows 多显示器下整屏目标需要新版客户端(整虚拟桌面抓屏),老客户端会被拒绝;window 目标不依赖虚拟桌面抓屏,不受此限。Android 主机只支持整屏目标,输入被翻译成触摸手势与全局动作(见 remote_mouse / remote_keyboard);抓屏依赖客户端已授权录屏(MediaProjection),未授权时 remote_open 会一直等不到屏幕子连接,注入还依赖无障碍服务在跑(未开启时命令照样下发但不生效,且没有回执)。";
tool["inputSchema"] = BuildRemoteOpenInputSchema();
tool["outputSchema"] = BuildRemoteOpenOutputSchema();
tools.append(tool);
@@ -5578,6 +5578,21 @@ std::string BuildRemoteOpen(const Json::Value& id, const Json::Value& args, CMy2
if (!ResolveScreenCtrlSessionHost(id, args, parent, devId, ctx, errJson))
return errJson;
// 能力位前置:Linux 的抓屏与注入都走 X11(Xorg/XWayland),客户端只在 DISPLAY 可用时
// 才在登录里声明 CLIENT_CAP_SCREEN_PREVIEW;声明了能力位(非空 caps)却没有这一位,
// 说明是纯 Wayland/无 X11 的会话,抓不到帧也注入不了——提前返回 -32005,免得白等
// timeout_ms 再报「子连接超时」,还留下一次 web-triggered 标记的清理。老客户端
// (caps 为空)无从判定,与多显示器门一样按放行处理(老的 COMMAND_SCREEN_SPY 链路仍可用)。
// Android 不能套这个门:APK 的 SCREEN_PREVIEW 位只代表 API 30+ 且无障碍在运行(用于
// get_screenshot 的 takeScreenshot),而远程控制抓屏走 MediaProjection、注入走
// dispatchGesture——没有这一位的主机远程控制仍可能可用。
CString hostClientType = ctx->GetAdditionalData(RES_CLIENT_TYPE);
const bool declaresCaps = !ctx->GetClientData(ONLINELIST_CAPABILITIES).IsEmpty();
if (declaresCaps && hostClientType == "LNX" && !ctx->SupportsScreenPreview())
return BuildError(id, -32005,
"Remote control requires screen preview capability (X11/Xorg desktop on Linux); "
"this host does not declare it");
// ---- 帧目标(可选):window_hwnd 只推窗口,region 只推矩形;缺省推整屏/整虚拟桌面 ----
uint32_t windowHwnd = 0;
bool hasWindow = false;
@@ -5675,7 +5690,8 @@ std::string BuildRemoteOpen(const Json::Value& id, const Json::Value& args, CMy2
// 与人类远程桌面观看互斥:已有屏幕子连接(web 观看)→ 拒绝,避免向人类正在看的画面注入。
if (WebService().HasActiveSession(devId))
return BuildError(id, -32003, "Device busy: a remote desktop session is already active for this host");
return BuildError(id, -32003, BusyMessage(
"Device busy: a remote desktop session is already active for this host", devId));
int timeoutMs = CMcpServer::Instance().ToolTimeoutMs();
int v = 0;
@@ -5683,7 +5699,8 @@ std::string BuildRemoteOpen(const Json::Value& id, const Json::Value& args, CMy2
std::string sessionId = GenerateRandomToken();
if (!mcp.BeginScreenCtrlOpen(devId, sessionId))
return BuildError(id, -32003, "Device busy: a remote control session is already active for this host");
return BuildError(id, -32003, BusyMessage(
"Device busy: a remote control session is already active for this host", devId));
// 失败清理:会话 + 隐藏对话框 + web-triggered 标记(StartRemoteDesktop 先置标记再发送)。
auto abortOpen = [&]() {