diff --git a/docs/Mcp_Design.md b/docs/Mcp_Design.md index 4d14ec7..4eb2ff9 100644 --- a/docs/Mcp_Design.md +++ b/docs/Mcp_Design.md @@ -636,3 +636,15 @@ token 只从 `-Token` / env 读取,不落仓库、不打印;无在线主机 - `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 项断言)。 + +### 11.4 C4 `search_file` 结果侧过滤 + +`search_file` 的搜索条件(根目录 + 通配模式)由客户端执行,改不动;但把匹配项拿回服务端后可以再筛一遍,省掉 AI 端逐条比对。 + +- 新增四个可选入参,**都在服务端对已收集的匹配项做过滤**,不减少客户端侧搜索耗时: + - `min_size` / `max_size`:字节数,整数,闭区间;负数或非数字返回 `-32602`;两者都给出且 `min_size > max_size` 返回 `-32602`。 + - `modified_after`:接受 `YYYY-MM-DD`(当天 00:00:00 之后)或 `YYYY-MM-DD HH:MM:SS`;格式不符返回 `-32602`。客户端返回的 `modified` 是定宽 `"YYYY-MM-DD HH:MM:SS"`,可直接字典序比较,所以两种写法都合法(`"2026-01-01" <= "2026-01-01 08:00:00"`)。 + - `name_only`:布尔,命中项只保留 `path` / `name` 两个字段,适合只要文件清单时省 token。 +- 过滤在分页之前:`total` 为命中条数、`totalAll` 为过滤前条数;摘要补一句「过滤前共 N 条(大小/修改时间/精简字段过滤在服务端进行,不减少客户端搜索耗时)」。 +- 过滤只看服务端已收到的条目,所以仍受 `max_results` / `timeout_ms` 截断:客户端没搜完时,过滤结果也是部分的(`truncated` / `finished` 字段照旧反映这一点)。 +- 验证(Debug 实例,根目录 `C:\Windows\Fonts`、`*.ttf`):基线 255 条;`min_size=1000000` → 39 条且 `totalAll=255`;`name_only=true` 每条只有 `path`/`name`;`modified_after=2026-01-01` → 165 条、`2026-06-03 00:00:00` → 130 条、`2027-01-01` → 0 条;`min_size=-5`、`min_size=10 & max_size=5`、`modified_after=2026/01/01`、`modified_after=2026-01-01 12:00` 均返回预期的 `-32602`。冒烟脚本 33/33 通过(新增 3 项:`min_size` 过滤后 `totalAll` 不变、`name_only` 精简字段、非法 `modified_after` 返回 `-32602`;后三项需带 `-SearchPath` 才执行)。 diff --git a/server/2015Remote/McpServer.cpp b/server/2015Remote/McpServer.cpp index a8a1554..7e5c014 100644 --- a/server/2015Remote/McpServer.cpp +++ b/server/2015Remote/McpServer.cpp @@ -1830,7 +1830,7 @@ std::string BuildToolsListResult(const Json::Value& id) { { Json::Value tool(Json::objectValue); tool["name"] = "search_file"; - tool["description"] = u8"在指定主机(仅 Windows)的某个目录下按文件名搜索文件(不区分大小写;pattern 不含通配符时按子串匹配,含 * / ? 时按通配符匹配)。客户端始终递归子目录(深度 32、最多 10000 条,跳过隐藏+系统目录与符号链接),结果边搜边收集、按 limit/offset 分页;finished=false 表示到达 timeout_ms 时限、返回的是部分结果(服务端已通知客户端停止搜索)。单次最多收集 5000 条 / 4 MB,超出时 truncated=true。注意:客户端递归用无界 wsprintf 拼 MAX_PATH 缓冲,整盘/深目录搜索会栈溢出(Debug 客户端弹 Run-Time Check Failure #2 并挂住搜索线程,Release 静默破坏栈)——请只搜具体的中浅层目录,不要从盘符根开始扫。"; + tool["description"] = u8"在指定主机(仅 Windows)的某个目录下按文件名搜索文件(不区分大小写;pattern 不含通配符时按子串匹配,含 * / ? 时按通配符匹配)。客户端始终递归子目录(深度 32、最多 10000 条,跳过隐藏+系统目录与符号链接),结果边搜边收集、按 limit/offset 分页;finished=false 表示到达 timeout_ms 时限、返回的是部分结果(服务端已通知客户端停止搜索)。单次最多收集 5000 条 / 4 MB,超出时 truncated=true。可选 min_size / max_size(字节)与 modified_after(YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS)在服务端做结果侧过滤,name_only=true 只返回 path 与 name;这些过滤不减少客户端搜索耗时,total 为命中数、totalAll 为过滤前条数。注意:客户端递归用无界 wsprintf 拼 MAX_PATH 缓冲,整盘/深目录搜索会栈溢出(Debug 客户端弹 Run-Time Check Failure #2 并挂住搜索线程,Release 静默破坏栈)——请只搜具体的中浅层目录,不要从盘符根开始扫。"; tool["inputSchema"] = BuildSearchFileInputSchema(); tool["outputSchema"] = BuildSearchFileOutputSchema(); tools.append(tool); @@ -5595,6 +5595,27 @@ Json::Value BuildSearchFileInputSchema() { toProp["description"] = u8"搜索时限(毫秒),默认 20000,范围 1000-120000。到时限会通知客户端停止搜索,返回已收到的部分结果(finished=false)。"; props["timeout_ms"] = toProp; + // ===== C4:结果侧过滤 ===== + Json::Value minProp(Json::objectValue); + minProp["type"] = "integer"; + minProp["description"] = u8"只保留大小不小于该字节数的条目。目录项也会参与比较(客户端上报的目录 size 恒为 0),只想看文件时用 min_size=1。"; + props["min_size"] = minProp; + + Json::Value maxProp(Json::objectValue); + maxProp["type"] = "integer"; + maxProp["description"] = u8"只保留不大于该字节数的条目。与 min_size 同时给出时区间取交集。"; + props["max_size"] = maxProp; + + Json::Value maProp(Json::objectValue); + maProp["type"] = "string"; + maProp["description"] = u8"只保留修改时间晚于该时刻的条目,格式 YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS(主机本地时间)。只给日期时按「该日 00:00:00 之后」理解。"; + props["modified_after"] = maProp; + + Json::Value nameOnlyProp(Json::objectValue); + nameOnlyProp["type"] = "boolean"; + nameOnlyProp["description"] = u8"true 时每条只返回 path 与 name,省略 dir/size/modified,用于结果集很大时省流量。默认 false。"; + props["name_only"] = nameOnlyProp; + AppendPagingProps(props); Json::Value schema(Json::objectValue); @@ -5671,6 +5692,51 @@ std::string BuildSearchFile(const Json::Value& id, const Json::Value& args, CMy2 timeoutMs = v; } + // ===== C4:结果侧过滤参数(全部在服务端做,客户端仍只做「按名字匹配 + 递归」)===== + // 读可选的字节数参数:0=未给出;1=已给出;-1=非法(负数/非数字)。 + auto readSizeArg = [](const Json::Value& a, const char* key, uint64_t& out) -> int { + if (!a.isMember(key)) return 0; + const Json::Value& val = a[key]; + if (val.isNumeric() && val.asDouble() < 0) return -1; + if (!ReadUInt64(val, out)) return -1; + return 1; + }; + uint64_t minSize = 0, maxSize = 0; + int hasMinSize = readSizeArg(args, "min_size", minSize); + int hasMaxSize = readSizeArg(args, "max_size", maxSize); + if (hasMinSize < 0) + return BuildError(id, -32602, "min_size must be a non-negative integer (bytes)"); + if (hasMaxSize < 0) + return BuildError(id, -32602, "max_size must be a non-negative integer (bytes)"); + if (hasMinSize == 1 && hasMaxSize == 1 && minSize > maxSize) + return BuildError(id, -32602, "min_size must not be greater than max_size"); + + // 客户端 modified 是固定宽度的 "YYYY-MM-DD HH:MM:SS",所以边界值可直接按字典序比较。 + std::string modifiedAfter; + if (args.isMember("modified_after")) { + if (!args["modified_after"].isString()) + return BuildError(id, -32602, "modified_after must be a string"); + modifiedAfter = Trim(args["modified_after"].asString()); + if (!modifiedAfter.empty()) { + bool shaped = (modifiedAfter.size() == 10 || modifiedAfter.size() == 19); + for (size_t i = 0; shaped && i < modifiedAfter.size(); ++i) { + const char c = modifiedAfter[i]; + if (i == 4 || i == 7) shaped = (c == '-'); + else if (i == 10) shaped = (c == ' '); + else if (i == 13 || i == 16) shaped = (c == ':'); // 19 位形式才有 + else shaped = (c >= '0' && c <= '9'); + } + if (!shaped) + return BuildError(id, -32602, + "modified_after must look like YYYY-MM-DD or YYYY-MM-DD HH:MM:SS"); + } + } + + bool nameOnly = args.isMember("name_only") && args["name_only"].isBool() && + args["name_only"].asBool(); + const bool hasResultFilter = hasMinSize == 1 || hasMaxSize == 1 || + !modifiedAfter.empty() || nameOnly; + std::string ansiPath, ansiPattern; if (!Utf8ToCpExact(path, 936, ansiPath)) return BuildError(id, -32602, @@ -5748,9 +5814,37 @@ std::string BuildSearchFile(const Json::Value& id, const Json::Value& args, CMy2 all = filtered; } + // C4:结果侧过滤。注意它发生在收集之后——客户端的 5000 条 / 4 MB 收集上限 + // 仍在过滤之前生效,命中太多时该 truncated 还是会 truncated。 + const int collected = (int)all.size(); + if (hasResultFilter) { + Json::Value filtered(Json::arrayValue); + for (const Json::Value& rec : all) { + if (hasMinSize == 1 || hasMaxSize == 1) { + uint64_t sz = rec["size"].asUInt64(); + if (hasMinSize == 1 && sz < minSize) continue; + if (hasMaxSize == 1 && sz > maxSize) continue; + } + if (!modifiedAfter.empty()) { + std::string m = JsonStrField(rec, "modified"); + if (m.empty() || m <= modifiedAfter) continue; // 字典序即时间序(格式固定) + } + if (nameOnly) { + Json::Value slim(Json::objectValue); + slim["path"] = rec["path"]; + slim["name"] = rec["name"]; + filtered.append(slim); + } else { + filtered.append(rec); + } + } + all = filtered; + } + PageWindow page = ResolvePageWindow(args); Json::Value pageItems; ApplyPageWindow(all, page, pageItems); + if (hasResultFilter) page.totalAll = collected; // total 是命中数,totalAll 是过滤前条数 Json::Value result(Json::objectValue); Json::Value structuredContent(Json::objectValue); @@ -5761,6 +5855,9 @@ std::string BuildSearchFile(const Json::Value& id, const Json::Value& args, CMy2 result["structuredContent"] = structuredContent; std::string text = PageSummary(page, u8"个匹配项"); + if (hasResultFilter) + text += std::string(u8"过滤前共 ") + std::to_string(collected) + + std::string(u8" 条(大小/修改时间/精简字段过滤在服务端进行,不减少客户端搜索耗时)。"); if (!finished) text += u8" 搜索在时限内未完成,以上为已收到的部分结果(可加大 timeout_ms 重试)。"; if (truncated) diff --git a/tools/mcp_smoke.ps1 b/tools/mcp_smoke.ps1 index fdacea0..0449d6f 100644 --- a/tools/mcp_smoke.ps1 +++ b/tools/mcp_smoke.ps1 @@ -200,6 +200,23 @@ if (-not $SkipHost) { } else { Check 'search_file 带 finished/truncated 字段' (($null -ne $ss.finished) -and ($null -ne $ss.truncated)) Check 'search_file 命中项字段完整' (@($ss.files | Where-Object { -not $_.path -or $null -eq $_.size }).Count -eq 0) + + # C4:结果侧过滤(大小 / 修改时间 / 精简字段),全部在服务端做 + $base0 = [int]$ss.totalAll + $big = Rpc '' $null 'search_file' @{ id = $HostId; path = $SearchPath; pattern = '*.exe'; + limit = 3; timeout_ms = 5000; min_size = 1073741824 } + $bs = $big.result.structuredContent + Check 'search_file min_size 过滤后 totalAll 不变' ` + ($big.error -eq $null -and [int]$bs.totalAll -eq $base0 -and [int]$bs.total -le $base0) + $slim = Rpc '' $null 'search_file' @{ id = $HostId; path = $SearchPath; pattern = '*.exe'; + limit = 3; timeout_ms = 5000; name_only = $true } + $sl = @($slim.result.structuredContent.files) + Check 'search_file name_only 只返回 path/name' ` + ($slim.error -eq $null -and @($sl | Where-Object { $_.size -or $_.modified -or $_.dir }).Count -eq 0) + $bad = Rpc '' $null 'search_file' @{ id = $HostId; path = $SearchPath; pattern = '*.exe'; + modified_after = '2026/01/01' } + Check 'search_file 非法 modified_after 返回 -32602' ` + ($bad.error -and [int]$bad.error.code -eq -32602) } } else { Write-Host " 未指定 -SearchPath,跳过 search_file 测试(深目录会触发客户端已知的 MAX_PATH 栈溢出)。" -ForegroundColor Yellow