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.
This commit is contained in:
1 parent
56a937fabb
commit
dcb5ae25c6
3 files changed
+154
-10
No files matched your search
@@ -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` 已够用。
|
||||
|
||||
@@ -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`,不报错 |
|
||||
|
||||
@@ -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;
|
||||
|
||||
Reference in new issue
Block a user