From 929065e7bef935199b84d42a1d22914d341e36d3 Mon Sep 17 00:00:00 2001 From: yuanyuanxiang <962914132@qq.com> Date: Sun, 25 Oct 2026 14:37:28 +0100 Subject: [PATCH] Feature: Filter the MCP host lists by group, OS and client type list_online_hosts and list_all_hosts could only page, so finding "the hosts in this group" or "the Linux ones" meant walking pages or falling back to search_hosts, which has no client type filter and treats online and offline hosts differently. Both tools now accept group, os and client_type. They are substring matches, combined with AND and case-insensitive over ASCII, matching the semantics search_hosts already used, and the shared implementation keeps the two tools from drifting apart. The filter runs before paging, so total counts the matches and totalAll keeps the pre-filter size, and the summary switches to the "matches" wording with a trailing line naming the unfiltered size - a mistyped condition then shows up immediately instead of silently returning nothing. Offline hosts carry no clientType in their stored record, so a client_type filter never matches them; the tool description says so and points at os for that case. Verified on the Debug instance: client_type=exe matches the single EXE host while client_type=lnx matches nothing and still reports totalAll=1; list_all_hosts with group=default matches all 3161 recorded hosts and splits them into 1 online and 3160 offline, and os=zzz matches none. The smoke test gains two checks and passes 28/28. Co-Authored-By: deepseek-flash --- docs/Mcp_Design.md | 10 ++++ server/2015Remote/McpServer.cpp | 83 +++++++++++++++++++++++++++++---- tools/mcp_smoke.ps1 | 4 ++ 3 files changed, 89 insertions(+), 8 deletions(-) diff --git a/docs/Mcp_Design.md b/docs/Mcp_Design.md index 6013c75..4d14ec7 100644 --- a/docs/Mcp_Design.md +++ b/docs/Mcp_Design.md @@ -626,3 +626,13 @@ token 只从 `-Token` / env 读取,不落仓库、不打印;无在线主机 - `sessions` 各项各取各自的锁、取完即放,是「大致同一时刻」的估算值,不能当一致性快照用。 - 工具注解登记为只读 + 非破坏性 + 幂等 + 不触达外部主机;`tools/list` 总数变为 53。 - 验证(Debug 实例):返回 `Yama v1.4.1,已运行 17 秒,监听 127.0.0.1:6545;在线主机 1 台、离线 3160 台`;`terminal_open` 期间 `sessions.terminal=1`、`terminal_close` 后回到 0;冒烟脚本 26/26 通过(新增 3 项:正常返回、版本/端口/开关齐全、不含 token)。 + +### 11.3 C3 主机列表过滤:`list_online_hosts` / `list_all_hosts` + +这两个工具原先只有分页,想找「某个分组」「某个平台」的主机只能翻页或改用 `search_hosts`(后者不支持 `client_type`,且对在线/离线的取舍规则不同)。 + +- 新增三个可选入参(两个工具共用同一套实现):`group` / `os` / `client_type`,均为子串匹配、ASCII 不区分大小写、AND 组合,口径与 `search_hosts` 一致。 +- 过滤在分页之前生效:`total` 为命中台数、`totalAll` 为过滤前总数(`list_online_hosts` 是全部在线数,`list_all_hosts` 是主机库总数);摘要改用「共 N 台主机匹配」并补一句过滤前规模,写错条件时一眼能看出来。 +- `list_all_hosts` 摘要里的在线/离线拆分也按命中条目统计。 +- **离线主机没有 `clientType`**(历史记录里不存这个字段),所以带 `client_type` 条件时离线主机不会命中——按平台筛历史主机用 `os`。 +- 验证(Debug 实例):`client_type=exe` 命中 1 台(`EXE`/`os=Windows 11`),`client_type=lnx` 命中 0 台但 `totalAll` 仍为 1;`list_all_hosts` 带 `group=default` 命中 3161 台并正确拆分在线 1 / 离线 3160,`os=zzz` 命中 0 台;冒烟脚本 28/28 通过(新增过滤未命中、totalAll 不变 2 项断言)。 diff --git a/server/2015Remote/McpServer.cpp b/server/2015Remote/McpServer.cpp index 2afba75..a8a1554 100644 --- a/server/2015Remote/McpServer.cpp +++ b/server/2015Remote/McpServer.cpp @@ -580,6 +580,53 @@ void CollectAllHosts(CMy2015RemoteDlg* parent, Json::Value& hosts, LeaveCriticalSection(&parent->m_cs); } +// ===== C3:list_online_hosts / list_all_hosts 的公共过滤 ===== +// 口径与 search_hosts 一致:条件都可选、AND 组合、子串匹配、ASCII 不区分大小写。 +// 只过滤已有字段,不额外拉取主机数据;离线主机没有 clientType(历史记录里不存), +// 所以带 client_type 条件时离线主机不会命中——需要按平台筛历史主机请用 os。 +struct HostListFilter { + std::string group; + std::string os; + std::string clientType; + bool Any() const { return !group.empty() || !os.empty() || !clientType.empty(); } +}; + +HostListFilter ReadHostListFilter(const Json::Value& args) { + HostListFilter f; + f.group = GetStringArg(args, "group"); + f.os = GetStringArg(args, "os"); + f.clientType = GetStringArg(args, "client_type"); + return f; +} + +void ApplyHostListFilter(const Json::Value& in, const HostListFilter& f, Json::Value& out) { + out = Json::Value(Json::arrayValue); + for (Json::Value::ArrayIndex i = 0; i < in.size(); ++i) { + const Json::Value& h = in[i]; + if (!f.group.empty() && !ContainsCI(JsonStrField(h, "group"), f.group)) continue; + if (!f.os.empty() && !ContainsCI(JsonStrField(h, "os"), f.os)) continue; + if (!f.clientType.empty() && !ContainsCI(JsonStrField(h, "clientType"), f.clientType)) continue; + out.append(h); + } +} + +void AppendHostListFilterProps(Json::Value& props) { + Json::Value groupProp(Json::objectValue); + groupProp["type"] = "string"; + groupProp["description"] = u8"按分组过滤(子串,不区分大小写)。省略则不过滤。"; + props["group"] = groupProp; + + Json::Value osProp(Json::objectValue); + osProp["type"] = "string"; + osProp["description"] = u8"按操作系统过滤(子串,不区分大小写,如 Windows、Linux、Android)。省略则不过滤。"; + props["os"] = osProp; + + Json::Value typeProp(Json::objectValue); + typeProp["type"] = "string"; + typeProp["description"] = u8"按客户端类型过滤(子串,不区分大小写,如 EXE、LNX、MAC)。离线主机没有该字段,不会命中。省略则不过滤。"; + props["client_type"] = typeProp; +} + // ========== 工具 schema ========== // 单台主机字段 schema(hosts 数组元素 / 单机详情共用的形状) @@ -698,6 +745,7 @@ Json::Value BuildListAllHostsInputSchema() { offlineProp["description"] = u8"是否包含离线主机(历史连接过、当前未连接的),默认 true"; props["offline"] = offlineProp; + AppendHostListFilterProps(props); AppendPagingProps(props); Json::Value schema(Json::objectValue); @@ -1365,11 +1413,12 @@ std::string BuildToolsListResult(const Json::Value& id) { tool["name"] = "list_online_hosts"; // 说明文字为 UTF-8:项目 /execution-charset:.936 会把普通窄字面量编译成 GBK, // 故用 u8 前缀确保输出到 JSON 的字节是 UTF-8。 - tool["description"] = u8"获取当前所有在线主机的列表,包含计算机名、IP、操作系统、版本、备注、分组、活动窗口、延迟等实时信息。结果按 limit/offset 分页(默认 100 条,上限 1000),total 为在线主机总数,hasMore 表示还有下一页。tls=true 表示该客户端登录时使用了 TLS 加密传输(登录时上报,非实时探测;老客户端恒为 false)。"; + tool["description"] = u8"获取当前所有在线主机的列表,包含计算机名、IP、操作系统、版本、备注、分组、活动窗口、延迟等实时信息。可选 group / os / client_type 三个过滤条件(均可选、AND 组合、子串匹配、ASCII 不区分大小写),过滤在分页之前生效:total 为命中台数,totalAll 为全部在线台数。结果按 limit/offset 分页(默认 100 条,上限 1000),hasMore 表示还有下一页。tls=true 表示该客户端登录时使用了 TLS 加密传输(登录时上报,非实时探测;老客户端恒为 false)。"; Json::Value inputSchema(Json::objectValue); inputSchema["type"] = "object"; Json::Value props(Json::objectValue); + AppendHostListFilterProps(props); AppendPagingProps(props); inputSchema["properties"] = props; inputSchema["required"] = Json::Value(Json::arrayValue); @@ -1396,7 +1445,7 @@ std::string BuildToolsListResult(const Json::Value& id) { { Json::Value tool(Json::objectValue); tool["name"] = "list_all_hosts"; - tool["description"] = u8"列出服务端已知的全部主机:在线主机(实时信息)与离线主机(历史连接过、当前未连接,来自主机列表记录)。在线主机字段同 list_online_hosts;离线主机另有 last_seen(最后一次登录时间)、install_time 字段,但没有 rtt/version/activeWindow 等实时字段。authStatus 为主机授权状态(unauthorized/authorized_by_super/authorized_by_admin/forbidden)。默认两类都返回;结果按 limit/offset 分页(默认 100 条,上限 1000),total 为总条数。"; + tool["description"] = u8"列出服务端已知的全部主机:在线主机(实时信息)与离线主机(历史连接过、当前未连接,来自主机列表记录)。在线主机字段同 list_online_hosts;离线主机另有 last_seen(最后一次登录时间)、install_time 字段,但没有 rtt/version/activeWindow 等实时字段,也没有 clientType。authStatus 为主机授权状态(unauthorized/authorized_by_super/authorized_by_admin/forbidden)。默认两类都返回;可选 group / os / client_type 过滤(AND 组合、子串匹配、ASCII 不区分大小写),过滤在分页之前生效:total 为命中台数,totalAll 为主机库总数。结果按 limit/offset 分页(默认 100 条,上限 1000)。"; tool["inputSchema"] = BuildListAllHostsInputSchema(); tool["outputSchema"] = BuildHostOutputSchema(); @@ -1810,9 +1859,15 @@ std::string BuildListOnlineHosts(const Json::Value& id, const Json::Value& args, Json::Value all(Json::arrayValue); CollectOnlineHosts(parent, all); + // 过滤在分页之前:total 是命中数,totalAll 是全部在线数(与 get_audit_log 同口径)。 + HostListFilter filter = ReadHostListFilter(args); + Json::Value matched; + ApplyHostListFilter(all, filter, matched); + PageWindow page = ResolvePageWindow(args); Json::Value hosts; - ApplyPageWindow(all, page, hosts); + ApplyPageWindow(matched, page, hosts); + if (filter.Any()) page.totalAll = (int)all.size(); Json::Value result(Json::objectValue); Json::Value structuredContent(Json::objectValue); @@ -1820,10 +1875,14 @@ std::string BuildListOnlineHosts(const Json::Value& id, const Json::Value& args, WritePageFields(structuredContent, page); result["structuredContent"] = structuredContent; + std::string text = PageSummary(page, filter.Any() ? u8"台主机匹配" : u8"台主机在线"); + if (filter.Any()) + text += std::string(u8"在线共 ") + std::to_string((int)all.size()) + std::string(u8" 台。"); + Json::Value content(Json::arrayValue); Json::Value item(Json::objectValue); item["type"] = "text"; - item["text"] = PageSummary(page, u8"台主机在线"); + item["text"] = text; content.append(item); result["content"] = content; result["isError"] = false; @@ -1839,14 +1898,20 @@ std::string BuildListAllHosts(const Json::Value& id, const Json::Value& args, CM Json::Value hosts(Json::arrayValue); CollectAllHosts(parent, hosts, includeOnline, includeOffline); + // 过滤先于统计与分页:total/totalAll 与摘要里的在线/离线数都按命中条目算。 + HostListFilter filter = ReadHostListFilter(args); + Json::Value matched; + ApplyHostListFilter(hosts, filter, matched); + int onlineCount = 0; - for (unsigned int i = 0; i < hosts.size(); ++i) { - if (hosts[i]["online"].asBool()) onlineCount++; + for (unsigned int i = 0; i < matched.size(); ++i) { + if (matched[i]["online"].asBool()) onlineCount++; } PageWindow page = ResolvePageWindow(args); Json::Value pageItems; - ApplyPageWindow(hosts, page, pageItems); + ApplyPageWindow(matched, page, pageItems); + if (filter.Any()) page.totalAll = (int)hosts.size(); Json::Value result(Json::objectValue); Json::Value structuredContent(Json::objectValue); @@ -1857,9 +1922,11 @@ std::string BuildListAllHosts(const Json::Value& id, const Json::Value& args, CM Json::Value content(Json::arrayValue); Json::Value item(Json::objectValue); item["type"] = "text"; - std::string text = PageSummary(page, u8"台主机"); + std::string text = PageSummary(page, filter.Any() ? u8"台主机匹配" : u8"台主机"); text += std::string(u8"其中在线 ") + std::to_string(onlineCount) + std::string(u8",离线 ") + std::to_string(page.total - onlineCount) + std::string(u8"。"); + if (filter.Any()) + text += std::string(u8"主机库共 ") + std::to_string((int)hosts.size()) + std::string(u8" 台。"); item["text"] = text; content.append(item); result["content"] = content; diff --git a/tools/mcp_smoke.ps1 b/tools/mcp_smoke.ps1 index a8b490c..fdacea0 100644 --- a/tools/mcp_smoke.ps1 +++ b/tools/mcp_smoke.ps1 @@ -126,6 +126,10 @@ $sc = $online.result.structuredContent Check 'list_online_hosts 带分页字段' (HasPaging $sc) Check 'list_online_hosts 每条都有 id/online' (@($sc.hosts | Where-Object { -not $_.id -or $_.online -ne $true }).Count -eq 0) +$noMatch = Rpc '' $null 'list_online_hosts' @{ group = 'zzz-no-such-group' } +Check 'list_online_hosts 过滤未命中返回 0 条' ($noMatch.error -eq $null -and [int]$noMatch.result.structuredContent.total -eq 0) +Check 'list_online_hosts 过滤后 totalAll 仍是全部在线数' ([int]$noMatch.result.structuredContent.totalAll -eq [int]$sc.totalAll) + $all = Rpc '' $null 'list_all_hosts' @{ limit = 5 } Check 'list_all_hosts 带分页字段' (HasPaging $all.result.structuredContent)