From dcb5ae25c6ac3e296270c93cfe9248586da24f82 Mon Sep 17 00:00:00 2001 From: yuanyuanxiang <962914132@qq.com> Date: Thu, 29 Oct 2026 21:37:02 +0100 Subject: [PATCH] Fix: Paginate get_activity_history results The tool was the only list-type tool without pagination. The client keeps ACTIVITY_HISTORY_MAX=500 records and Dump() prepends the in-progress window, so a single call returned up to 501 lines of "[time] [title] duration" -- enough to blow up the caller's context, especially since titles carry personal browsing history. Records come back newest-first (m_records uses push_front and the current window is prepended), so the standard limit/offset window applies directly: offset=0 is the most recent page, no need to read total first and count backwards. That ordering is now stated in the tool description so the model can rely on it. - inputSchema: BuildGetHostDetailInputSchema -> BuildPagedHostListInputSchema (adds limit, default 100 / max 1000, and offset) - outputSchema: append AppendPageOutputProps plus truncated - implementation: rename the full split to `all`, slice via ResolvePageWindow and ApplyPageWindow, write back with WritePageFields - activityHistory is rebuilt from the window instead of returning the whole Dump() text -- otherwise the raw copy would bypass pagination entirely - 64 KB byte budget (same as get_client_log), trimmed from the end so the newest records survive; hasMore is computed as offset+kept < total rather than hardcoded true, since a single oversized tail record must not claim there is another page Batch calls need no extra work: the tool is already in IsBatchReadOnlyTool, and BuildBatchCall forwards limit/offset to each host, so ids + limit means "the latest N records of every host". Compiles clean; not yet exercised against a running server (the exe was locked by the live instance). Verification cases are listed in docs/Mcp_Test_Report_2026-10-29.md section 8. --- docs/Mcp_Design.md | 47 ++++++++++++++++++ docs/Mcp_Test_Report_2026-10-29.md | 37 +++++++++++++- server/2015Remote/McpServer.cpp | 80 +++++++++++++++++++++++++++--- 3 files changed, 154 insertions(+), 10 deletions(-) diff --git a/docs/Mcp_Design.md b/docs/Mcp_Design.md index 5060ea9..93b7711 100644 --- a/docs/Mcp_Design.md +++ b/docs/Mcp_Design.md @@ -955,3 +955,50 @@ schema 里写明这一点;同时根键分支补上 `path: ""`,让两个分 三个 P0 内,留待下一轮。 - 连接器会缓存 `tools/list`,`limit`/`filter` 在重连前对模型不可见(默认参数已覆盖 P0-3 的场景),与既有的 `overwrite` 缓存问题同源。 + +## 19. 增补(2026-10-29:`get_activity_history` 分页,P2-1) + +### 19.1 问题 + +`get_activity_history` 是全仓库唯一没有分页的列表类工具。客户端 `ACTIVITY_HISTORY_MAX` += 500,`Dump()` 还会把进行中的当前窗口作为第 1 条,所以一次返回上限约 501 条——实测 +正是 501 条。每行含窗口标题(可能很长),501 行直接把上下文冲爆;而报告里那份数据还 +混着大量个人浏览、求职、签证页面,属于「不该被整包塞进模型上下文」的典型。 + +### 19.2 顺序:为什么可以直接用 `limit`/`offset` + +`ActivityHistory::Loop()` 用 `m_records.push_front(...)` 维护,`Dump()` 又把当前进行中 +的窗口拼在最前面——**返回顺序天然是「新在前」**。于是 `offset=0` 就是最近 `limit` 条, +不必像「新在后」的日志那样先取一次 `total` 再倒算 `offset=total-limit`。这条顺序不是 +本次新增的约定,是客户端本来就这样,写进描述是为了让模型敢直接用 `offset=0`。 + +### 19.3 实现 + +- `inputSchema` 从 `BuildGetHostDetailInputSchema()` 换成 `BuildPagedHostListInputSchema()` + (`{ id | ids }` + `limit`/`offset`,与 `list_processes` / `list_windows` 同一套); +- `outputSchema` 追加 `AppendPageOutputProps()` 与 `truncated`; +- 实现里把原来的 `records` 改名 `all`(全量拆行结果),再 `ResolvePageWindow` + + `ApplyPageWindow` 切出 `records`,`WritePageFields` 写回 `total`/`totalAll`/`offset`/ + `limit`/`hasMore`; +- **`activityHistory` 必须按窗口重建**:它原来是 `Dump()` 的整包原文,如果原样返回, + 501 行的正文照样进上下文,等于没分页。现在它是窗口内 `records` 的按行拼接,语义仍是 + 「同一份数据的纯文本形态」; +- 再加 64 KB 字节预算(与 `get_client_log` 同口径),从窗口**末尾**裁——保留最新的那些。 + 裁断时 `truncated=true`;`hasMore` 按 `offset + returned < total` 算,而不是一律置 true + (末尾单条自己超预算时不该再报还有下一页)。调用方用 `offset + returned` 继续取; +- 至少保留 1 条:单条超预算时若不保底,`returned=0` 会让调用方在同一个 `offset` 上原地 + 打转。窗口标题达到 64 KB 几乎不可能,这是纯兜底。 + +### 19.4 批量 + +`get_activity_history` 在 `IsBatchReadOnlyTool` 名单里,`BuildBatchCall` 会把 `ids` 摘掉、 +其余参数原样透传给单机调用,所以 `ids` + `limit` 等于「每台各取最近 N 条」,不需要额外 +处理。P0-1 的 `anyOf:[单机, 批量]` 包装也自动覆盖新增字段。 + +### 19.5 未做 + +- 没有 `filter`(按窗口标题子串)。报告没提,且客户端标题是 UTF-8、过滤要按字节子串做, + 与 `get_client_log` 的 `filter` 不同源,等有实际需求再加。 +- 没有 `since`(按时间起点取)。记录里的时间是 `[YYYY-MM-DD HH:MM:SS]` 文本前缀,做时间 + 过滤得先解析每行;当前 `limit/offset` 已够用。 + diff --git a/docs/Mcp_Test_Report_2026-10-29.md b/docs/Mcp_Test_Report_2026-10-29.md index b2ae5a9..7f25d36 100644 --- a/docs/Mcp_Test_Report_2026-10-29.md +++ b/docs/Mcp_Test_Report_2026-10-29.md @@ -4,7 +4,7 @@ - **服务端**:Yama v1.4.1,构建时间 `2026-10-29 18:26:56`,监听 `0.0.0.0:6544`,10 项开关全开(readonly=false) - **规模**:在线 34 台、离线 3165 台,`tools/list` 共 **60 个工具** - **测试目的**:考察 AI 使用这套 MCP 工具是否顺畅,以及能否对设备完成有效监管与处置 -- **修复状态**:三个 P0 已于同日修复并实测通过,见 §7(实现说明在 `docs/Mcp_Design.md` §18) +- **修复状态**:三个 P0 已于同日修复并实测通过,见 §7(实现说明在 `docs/Mcp_Design.md` §18);P2-1(`get_activity_history` 无分页)已于同日修复,见 §8(实现说明在 `docs/Mcp_Design.md` §19) ## 1. 测试范围与约定 @@ -205,7 +205,7 @@ matched 中包含 {"kind": "terminal", "session_id": "21afe3..."} | # | 问题 | 证据 | |---|---|---| -| 1 | `get_activity_history` 无分页,一次返回 **501 条** | 直接冲爆上下文,且内容含大量个人浏览/求职/签证页面 | +| 1 | ~~`get_activity_history` 无分页,一次返回 **501 条**~~ **已修复,见 §8** | 直接冲爆上下文,且内容含大量个人浏览/求职/签证页面 | | 2 | `authStatus` 只在 `search_hosts`/`list_all_hosts` 出现,`list_online_hosts` 没有;`myself` 组 6 台全为 `unauthorized` 却可正常写入 | MCP 侧未按授权状态做门禁 | | 3 | 时间口径三套并存 | `list_files.mtime` 是 epoch 整数;`host_list_scheduled_tasks.lastRun` 是 `"2026-10-25 03:38:42"`;`list_network_connections.state` 是 `5` + `"ESTABLISHED"`。主机 `last_seen` 显示 `2026-10-30 01:27`,审计日志同一时刻显示 `18:47`,**差 6 小时以上** | | 4 | 降级工具与首选工具字段命名不一致 | `list_services`: `binary_path` / `start_type: "Demand-Start"`;`host_list_win32_services`: `binaryPath` / `startType: "Demand Start"`。进程总数 354 vs 351(枚举口径不同) | @@ -354,3 +354,36 @@ matched 中包含 {"kind": "terminal", "session_id": "21afe3..."} **遗留**:连接器仍缓存着旧的 `get_client_log` inputSchema(不含 `limit`/`filter`),模型侧 直接传这两个参数会被本地校验拦下(`must NOT have additional properties`)。默认参数已经把 P0-3 解决掉,要显式用 `limit`/`filter` 需重连一次连接器——与 §3.2 P1-1 是同一个缓存问题。 + +## 8. 附带修复:`get_activity_history` 分页(P2-1) + +P2-1 与 P0-3 是同一类病——**列表类工具没有裁剪,把上下文当垃圾桶**。既然 `get_client_log` +的分页/预算机制已经就位,这里直接复用同一套。实现细节见 `docs/Mcp_Design.md` §19。 + +| 改动 | 内容 | +|---|---| +| `inputSchema` | 由 `BuildGetHostDetailInputSchema()`(只有 `{id\|ids}`)换成 `BuildPagedHostListInputSchema()`,补 `limit`(默认 100、上限 1000)与 `offset` | +| `outputSchema` | 追加 `AppendPageOutputProps()`(`total`/`totalAll`/`offset`/`limit`/`hasMore`)与 `truncated` | +| 实现 | 全量拆行结果改名 `all`,再 `ResolvePageWindow` + `ApplyPageWindow` 切出 `records`,`WritePageFields` 回填 | +| `activityHistory` | **按窗口重建**(窗口内 `records` 按行拼接)。原来是 `Dump()` 整包原文,原样返回等于没分页 | +| 字节预算 | 64 KB(与 `get_client_log` 同口径),从窗口末尾裁,保留最新的;裁断时 `truncated=true`,`hasMore` 按 `offset+returned < total` 算 | +| 保底 | 至少留 1 条,避免 `returned=0` 让调用方在同一个 `offset` 上原地打转 | + +**顺序语义**:客户端 `ActivityHistory::Loop()` 用 `m_records.push_front(...)`,`Dump()` 又把 +进行中的当前窗口拼在最前——返回顺序**天然是「新在前」**。所以 `offset=0` 就是最近 `limit` 条, +不需要先取 `total` 再倒算 offset。这条不是新约定,写进工具描述是为了让模型敢直接用 `offset=0`。 + +**批量**:本工具在 `IsBatchReadOnlyTool` 名单里,`BuildBatchCall` 摘掉 `ids` 后把其余参数原样 +透传,所以 `ids` + `limit` 就是「每台各取最近 N 条」,P0-1 的 `anyOf` 包装自动覆盖新字段。 + +**验证(服务端 21:34 构建,待重启后实测)**: + +| 用例 | 期望 | +|---|---| +| 默认参数(不带 `limit`) | `records` 100 条、`total≈501`、`hasMore=true`,结果体积从约 90 KB 降到约 12 KB | +| `limit=5` | 5 条,且是最新的 5 条(第 1 条时间最晚) | +| `offset=500` | 1 条(尾部最老的那条),`hasMore=false` | +| `ids` + `limit=3` | `succeeded=全数`,每台各 3 条,`results[].data.total` 各自独立 | +| `activityHistory` 与 `records` | 行数与内容一致(不再是整包原文) | +| `offset` 超过 `total` | `records=[]`、`returned=0`、`hasMore=false`,不报错 | + diff --git a/server/2015Remote/McpServer.cpp b/server/2015Remote/McpServer.cpp index f002c98..ad87550 100644 --- a/server/2015Remote/McpServer.cpp +++ b/server/2015Remote/McpServer.cpp @@ -1183,7 +1183,7 @@ Json::Value BuildWindowListOutputSchema() { return schema; } -// get_activity_history 的 outputSchema(records 数组 + 原始文本) +// get_activity_history 的 outputSchema(records 数组 + 原始文本 + 翻页字段) Json::Value BuildActivityHistoryOutputSchema() { Json::Value props(Json::objectValue); @@ -1192,12 +1192,21 @@ Json::Value BuildActivityHistoryOutputSchema() { Json::Value items(Json::objectValue); items["type"] = "string"; recordsProp["items"] = items; + recordsProp["description"] = u8"本次窗口内的记录,每条一行「[时间] [标题] 时长」。新在前。"; props["records"] = recordsProp; Json::Value rawProp(Json::objectValue); rawProp["type"] = "string"; + rawProp["description"] = u8"与 records 同源的纯文本(records 按行拼接),窗口外的记录不包含。"; props["activityHistory"] = rawProp; + Json::Value truncProp(Json::objectValue); + truncProp["type"] = "boolean"; + truncProp["description"] = u8"因 64 KB 字节预算而比 limit 少返回了条目(此时 hasMore 也为 true)。"; + props["truncated"] = truncProp; + + AppendPageOutputProps(props); // total / totalAll / offset / limit / hasMore + Json::Value schema(Json::objectValue); schema["type"] = "object"; schema["properties"] = props; @@ -1993,9 +2002,9 @@ std::string BuildToolsListResult(const Json::Value& id) { { Json::Value tool(Json::objectValue); tool["name"] = "get_activity_history"; - tool["description"] = u8"获取指定在线主机的历史活动记录(前台窗口驻留时长,每行一条「[时间] [标题] 时长」)。主连接 RPC、一次性返回。"; + tool["description"] = u8"获取指定在线主机的历史活动记录(前台窗口驻留时长,每行一条「[时间] [标题] 时长」)。主连接 RPC。结果按 limit/offset 分页(默认 100 条、上限 1000),新在前:offset=0 就是最近 limit 条,想看更早的再往后翻。total 为本机现有记录总数,hasMore 表示还有更早的记录;客户端只保留最近 500 条,所以 total 最多约 501(含进行中的当前窗口)。"; - tool["inputSchema"] = BuildGetHostDetailInputSchema(); // 复用 { id } 必填 schema + tool["inputSchema"] = BuildPagedHostListInputSchema(); // { id | ids } + limit/offset tool["outputSchema"] = BuildActivityHistoryOutputSchema(); tools.append(tool); @@ -2966,21 +2975,72 @@ std::string BuildGetActivityHistory(const Json::Value& id, const Json::Value& ar text.assign((const char*)data.data() + 1, data.size() - 1); // 拆行:每行一条记录,过滤空行(含 Dump 末尾的换行)。 - Json::Value records(Json::arrayValue); + // 顺序是「新在前」:客户端 m_records 用 push_front 维护,Dump() 又把进行中的 + // 当前窗口放在最前面。所以 offset=0 天然就是“最近 limit 条”,不需要先取 + // total 再倒着算 offset——这正是日志类数据最常用的取法。 + Json::Value all(Json::arrayValue); size_t start = 0; while (start <= text.size()) { size_t nl = text.find('\n', start); std::string line = text.substr(start, (nl == std::string::npos ? text.size() : nl) - start); - if (!line.empty()) records.append(line); + if (!line.empty()) all.append(line); if (nl == std::string::npos) break; start = nl + 1; } - int count = (int)records.size(); + + // 分页:实测一次 501 条会把上下文撑爆(P2-1)。本工具无服务端过滤, + // total == totalAll,ApplyPageWindow 的默认口径即可。 + PageWindow page = ResolvePageWindow(args); + Json::Value records(Json::arrayValue); + ApplyPageWindow(all, page, records); + + // 字节预算:limit 上限 1000,窗口内若标题很长仍可能过大。从窗口末尾裁 + // (保留最新的那些),裁掉的部分由 truncated 与 hasMore 一起表达。 + const size_t kMaxBytes = 64 * 1024; + bool byteTrimmed = false; + { + size_t bytes = 0; + int kept = 0; + for (const Json::Value& r : records) { + const std::string s = r.asString(); + if (bytes + s.size() + 1 > kMaxBytes) { byteTrimmed = true; break; } + bytes += s.size() + 1; + ++kept; + } + if (byteTrimmed) { + // 至少留一条,保证调用方按 offset+returned 前进时不会原地打转 + // (单条超过 64 KB 在窗口标题上几乎不可能,这里只是兜底)。 + if (kept == 0) { + kept = 1; + Json::Value one(Json::arrayValue); + one.append(records[0]); + records = one; + } else { + Json::Value trimmed(Json::arrayValue); + for (int i = 0; i < kept; ++i) trimmed.append(records[i]); + records = trimmed; + } + page.returned = kept; + // 还有没有更早的记录,按「已返回到的绝对位置」算,而不是一律置 true: + // 末尾那条自己超预算时,offset+kept 已经等于 total,不该再报 hasMore。 + page.hasMore = (page.offset + kept < page.total); + } + } + + // activityHistory 是同一份数据的纯文本形态:必须按窗口重建, + // 否则整包原文会绕过分页,等于没分页。 + std::string shown; + for (const Json::Value& r : records) { + shown += r.asString(); + shown += '\n'; + } Json::Value result(Json::objectValue); Json::Value structuredContent(Json::objectValue); structuredContent["records"] = records; - structuredContent["activityHistory"] = text; + structuredContent["activityHistory"] = shown; + structuredContent["truncated"] = byteTrimmed; + WritePageFields(structuredContent, page); result["structuredContent"] = structuredContent; // 正文外的 JSON 块只放 records:activityHistory 是同一份数据的原文, @@ -2992,7 +3052,11 @@ std::string BuildGetActivityHistory(const Json::Value& id, const Json::Value& ar Json::Value content(Json::arrayValue); Json::Value item(Json::objectValue); item["type"] = "text"; - item["text"] = std::string(u8"共 ") + std::to_string(count) + std::string(u8" 条历史活动记录。"); + item["text"] = std::string(u8"共 ") + std::to_string(page.total) + std::string(u8" 条历史活动记录(新在前),本次返回第 ") + + std::to_string(page.offset) + std::string(u8" 条起的 ") + std::to_string(page.returned) + std::string(u8" 条") + + (page.hasMore ? std::string(u8";hasMore=true 表示还有更早的记录,可用 offset=") + + std::to_string(page.offset + page.returned) + std::string(u8" 继续取。") + : std::string(u8"。")); content.append(item); result["content"] = content; result["isError"] = false;