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:
yuanyuanxiang committed 2026-10-29 21:37:02 +01:00
1 parent 56a937fabb
commit dcb5ae25c6
3 files changed
+154 -10

No files matched your search

+47
View File
@@ -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` 已够用。
+35 -2
View File
@@ -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`,不报错 |
+72 -8
View File
@@ -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;