Fix(mcp): list the whole directory before paging list_files

list_files stopped parsing at 500 entries, so a larger directory reported
total=500 with hasMore=false and offsets past 500 returned nothing: the model
was told a false limit and could not reach the tail. Parse the full
TOKEN_FILE_LIST payload (100000 cap only to bound a pathological directory),
page over it, and report truncated=true plus a summary note when the cap hits.

Only an empty path now means list drives. Windows "." "/" "\" are normalized
to empty in BuildListFiles, while Linux/macOS "/" is a real root directory and
is listed; OnDriveList no longer keeps its own copy of the magic-path rule.

The file-manager channel carries GBK both ways (Windows FindFirstFileA;
common/FileManager.h runs gbkToUtf8 on incoming paths, utf8ToGbk on outgoing
names). The old CP_UTF8 choice for LNX/MAC decoded GBK names wrongly and sent
UTF-8 paths to a client that treats them as GBK. Paths now go out as GBK, or
as raw UTF-8 when GBK cannot represent them (the client's iconv then passes
the bytes through). Names decode GBK-first, UTF-8 on failure: UTF-8-first
misreads ~18% of common hanzi whose GBK bytes are also valid UTF-8.

Go's server gets the same contract: 100000 cap, truncated in
structuredContent, and the cap check after a real record so an exact-cap
listing with trailing padding is not called truncated. tools_minimal.json is
regenerated; the Go truncation test and the design doc are updated.

Debug server builds; check_platform_table, gen_go_tools --check and
go test ./... pass. The Release instance was not rebuilt or restarted.

Co-Authored-By: deepseek-flash
This commit is contained in:
yuanyuanxianganddeepseek-flash committed 2026-11-13 12:13:20 +01:00
1 parent 42dd70fe20
commit 5e012019ba
6 files changed
+137 -40

No files matched your search

+87 -20
View File
@@ -549,17 +549,38 @@ Json::Value ParseDriveList(const std::vector<BYTE>& data, UINT cp) {
return arr;
}
// 文件管理通道上的名字解码。协议约定是客户端 ANSI/GBK(Windows 的 FindFirstFileA、
// Linux/macOS 的 common/FileManager.h 都按 GBK 收发),但 POSIX 客户端的 utf8ToGbk
// 遇到 GBK 无法表示的字符会原样返回 UTF-8。cp=CP_UTF8(POSIX 调用方)时先按 GBK
// 严格解码:能解开就当 GBK(线上常态);解不开说明客户端透传了 UTF-8,按 UTF-8 用。
// 反过来「先试 UTF-8」不行——约 18% 的常用汉字 GBK 双字节恰好也是合法 UTF-8
// (如 目录 = C4 BF C2 BC = "Ŀ¼"),会解成拉丁字母。已知限制:透传的 UTF-8
// 字节若恰好也是合法 GBK(例如 emoji)仍会被当 GBK 解,客户端侧编码转换本身不可逆。
std::string DecodeListingName(const char* s, UINT cp) {
if (cp == CP_UTF8) {
if (MultiByteToWideChar(936, MB_ERR_INVALID_CHARS, s, -1, NULL, 0) > 0)
return ToUtf8(s, 936);
return std::string(s);
}
return ToUtf8(s, cp);
}
// 解析 TOKEN_FILE_LIST 缓冲(data[0]=token,其后为
// [attr:1][filename\0][sizeHigh:4][sizeLow:4][ftLastWriteTime:8] 记录)。
// 文件名为客户端 ANSI(编码由 cp 指定);attr 非 0 表示目录(FILE_ATTRIBUTE_DIRECTORY)。
Json::Value ParseFileList(const std::vector<BYTE>& data, int maxEntries, UINT cp) {
// 文件名为客户端 ANSI(编码由 cp 指定,见 DecodeListingName);attr 非 0 表示目录
// (FILE_ATTRIBUTE_DIRECTORY)。
// maxEntries 只限制构建出的条目数:超出时提前返回,并通过 truncated 告知数据里还有
// 更多记录(调用方据此区分「目录就这么大」和「服务端解析上限到了」)。
Json::Value ParseFileList(const std::vector<BYTE>& data, int maxEntries, UINT cp,
bool* truncated = nullptr) {
Json::Value arr(Json::arrayValue);
if (truncated) *truncated = false;
if (data.size() < 2) return arr;
const char* p = (const char*)data.data();
size_t len = data.size();
size_t off = 1;
int count = 0;
while (off + 1 <= len && count < maxEntries) {
while (off + 1 <= len) {
bool isDir = (p[off] & FILE_ATTRIBUTE_DIRECTORY) != 0;
off += 1;
@@ -567,6 +588,10 @@ Json::Value ParseFileList(const std::vector<BYTE>& data, int maxEntries, UINT cp
size_t nlen = BoundedStrlen(name, len - off);
if (nlen >= len - off) break;
if (nlen == 0) break; // 空记录 = 尾部零填充(LocalAlloc 对齐),停止解析
if (count >= maxEntries) { // 还有记录但已达上限:数据不完整
if (truncated) *truncated = true;
break;
}
off += nlen + 1;
if (off + 16 > len) break;
@@ -584,7 +609,7 @@ Json::Value ParseFileList(const std::vector<BYTE>& data, int maxEntries, UINT cp
Json::Int64 mtime = (Json::Int64)(ft / 10000000ULL) - 11644473600LL;
Json::Value item(Json::objectValue);
item["name"] = ToUtf8(name, cp);
item["name"] = DecodeListingName(name, cp);
item["isDir"] = isDir;
item["size"] = (Json::UInt64)size;
item["mtime"] = mtime;
@@ -1963,7 +1988,9 @@ Json::Value BuildListFilesInputSchema() {
Json::Value pathProp(Json::objectValue);
pathProp["type"] = "string";
pathProp["description"] = u8"要列举的目录路径(如 C:\\Windows);省略或传空则返回驱动器列表";
pathProp["description"] = u8"要列举的目录路径(如 C:\\Windows 或 /etc)。省略或传空返回驱动器列表;"
u8"Windows 上 \".\"、\"/\"、\"\\\\\" 视同省略;Linux/macOS 上 \"/\" 是根目录,"
u8"按真实目录列举。";
props["path"] = pathProp;
AppendBatchIdsProp(props);
@@ -2021,6 +2048,13 @@ Json::Value BuildListFilesOutputSchema() {
fileItems["properties"] = fileProps;
filesProp["items"] = fileItems;
props["files"] = filesProp;
// 目录条目超过解析上限(10 万条)时为 true,此时 total 只是上限内的数量。
Json::Value truncatedProp(Json::objectValue);
truncatedProp["type"] = "boolean";
truncatedProp["description"] = u8"目录条目超过服务端解析上限(100000 条)时为 true;"
u8"仅在返回 files 时可能出现,此时 total 不是真实总数。";
props["truncated"] = truncatedProp;
AppendPageOutputProps(props);
Json::Value schema(Json::objectValue);
@@ -2225,7 +2259,7 @@ std::string BuildToolsListResult(const Json::Value& id) {
{
Json::Value tool(Json::objectValue);
tool["name"] = "list_files";
tool["description"] = u8"列举指定在线主机的目录。省略或空 path 返回驱动器列表(drives);给定 path 返回该目录一层内的文件/子目录(files,最多 500 条,含 name/isDir/size/mtime)。只读。";
tool["description"] = u8"列举指定在线主机的目录。省略或空 path 返回驱动器列表(drives);给定 path 返回该目录一层内的文件/子目录(files,含 name/isDir/size/mtime),整目录解析后按 limit/offset 分页(默认 100 条、上限 1000 条,total/hasMore 是真实的目录条目数;目录超过 10 万条时按上限截断并返回 truncated=true)。Windows 上 \".\"/\"/\"/\"\\\\\" 视同省略 path;Linux/macOS 上 \"/\" 是根目录。只读。";
tool["inputSchema"] = BuildListFilesInputSchema();
tool["outputSchema"] = BuildListFilesOutputSchema();
@@ -3604,6 +3638,7 @@ static std::string BuildRemoteWin32Error(const Json::Value& id, DWORD win32err,
// tools/call:list_files(列盘走 COMMAND_LIST_DRIVE→TOKEN_DRIVE_LIST;
// 列目录走 COMMAND_LIST_DRIVE 开子链接后,再下发 COMMAND_LIST_FILES→TOKEN_FILE_LIST)
static const int kListFilesMaxEntries = 100000; // 解析上限,仅为兜住病态目录
std::string BuildListFiles(const Json::Value& id, const Json::Value& args, CMy2015RemoteDlg* parent) {
uint64_t devId = 0;
std::string err;
@@ -3615,16 +3650,32 @@ std::string BuildListFiles(const Json::Value& id, const Json::Value& args, CMy20
return BuildError(id, -32002, "Host not found or offline: " + std::to_string(devId));
std::string path = GetStringArg(args, "path");
bool listDrives = path.empty() || path == "." || path == "/" || path == "\\";
// 目录路径/文件名编码按 clientType 判定:Windows 走 A 接口(FindFirstFileA 等)= 客户端
// ANSI(GBK/936),不随 CLIENT_CAP_UTF8 转 UTF-8;LNX/MAC 文件系统天然 UTF-8。不能用
// GetClientEncoding——它按能力位返回 CP_UTF8,会误解 Windows 客户端的 GBK 文件名。
// 编码:文件管理通道在线上是客户端 ANSI/GBK —— Windows 客户端走 A 接口
// (FindFirstFileA);Linux/macOS 客户端在 common/FileManager.h 里对收到的路径做
// gbkToUtf8、对发出的名字做 utf8ToGbk,与 download_file/upload_file 的 936 约定
// 一致。不能用 GetClientEncoding——它按能力位返回 CP_UTF8,会误解线上的 GBK 字节。
// 名字解析对 POSIX 用 CP_UTF8 作「先按 GBK 严格解、解不开再当 UTF-8」的开关
// (客户端 utf8ToGbk 遇到 GBK 无法表示的字符会原样透传 UTF-8),见 DecodeListingName。
CString clientType = ctx->GetAdditionalData(RES_CLIENT_TYPE);
UINT cp = (clientType == "LNX" || clientType == "MAC") ? CP_UTF8 : 936;
const bool posixFs = (clientType == "LNX" || clientType == "MAC");
const UINT nameCp = posixFs ? CP_UTF8 : 936;
// 下发前把 UTF-8 path 转成客户端 ANSI(空/./\/\\ 为 ASCII,转换后不变),OnDriveList 直接用。
std::string ansiPath = ToAnsi(path, cp);
// Windows 上 "."、"/"、"\\" 是「列盘」的历史写法;POSIX 上 "/" 是真实目录
// (根目录),不能当列盘。列盘统一用空 path 下发给 OnDriveList。
const bool listDrives = path.empty() ||
(!posixFs && (path == "." || path == "/" || path == "\\"));
std::string ansiPath;
if (!listDrives) {
if (posixFs) {
// 客户端对收到的路径先做 gbkToUtf8:能转 GBK 就发 GBK;含 GBK 表示不了的
// 字符(韩文等)时客户端 iconv 会失败并原样使用输入,所以这里直接发 UTF-8,
// 两边才能对上(ToAnsi 在这里会静默替换成 '?')。
if (!Utf8ToCpExact(path, 936, ansiPath)) ansiPath = path;
} else {
ansiPath = ToAnsi(path, 936);
}
}
CMcpServer& mcp = CMcpServer::Instance();
if (!mcp.BeginPending(devId, "list_files", ansiPath))
@@ -3647,11 +3698,13 @@ std::string BuildListFiles(const Json::Value& id, const Json::Value& args, CMy20
Json::Value drives(Json::arrayValue);
Json::Value files(Json::arrayValue);
bool truncated = false;
if (listDrives) {
drives = ParseDriveList(data, cp);
drives = ParseDriveList(data, nameCp);
} else {
// 服务端按 500 条截断(避免子连接/JSON 过大),再按 limit/offset 取窗口。
files = ParseFileList(data, 500, cp);
// 整目录解析后再分页:先按 500 条截断会让 total/hasMore 说谎(超过 500 条的
// 目录永远翻不到后面的条目)。上限 100000 条只为兜住病态目录。
files = ParseFileList(data, kListFilesMaxEntries, nameCp, &truncated);
}
PageWindow page = ResolvePageWindow(args);
@@ -3660,8 +3713,12 @@ std::string BuildListFiles(const Json::Value& id, const Json::Value& args, CMy20
Json::Value result(Json::objectValue);
Json::Value structuredContent(Json::objectValue);
if (listDrives) structuredContent["drives"] = pageItems;
else structuredContent["files"] = pageItems;
if (listDrives) {
structuredContent["drives"] = pageItems;
} else {
structuredContent["files"] = pageItems;
structuredContent["truncated"] = truncated; // 一律带出,便于按 schema 校验
}
WritePageFields(structuredContent, page);
result["structuredContent"] = structuredContent;
@@ -3669,6 +3726,13 @@ std::string BuildListFiles(const Json::Value& id, const Json::Value& args, CMy20
Json::Value item(Json::objectValue);
item["type"] = "text";
item["text"] = listDrives ? PageSummary(page, u8"个驱动器") : PageSummary(page, u8"个条目");
if (truncated)
item["text"] = item["text"].asString() +
std::string(u8"目录条目超过服务端解析上限 ") +
std::to_string(kListFilesMaxEntries) +
std::string(u8" 条,total 只是上限内的数量;请缩小目录范围") +
(posixFs ? std::string(u8"。")
: std::string(u8"或改用 search_file。"));
content.append(item);
result["content"] = content;
result["isError"] = false;
@@ -11311,7 +11375,7 @@ ListingLookup LookupInListing(const std::vector<BYTE>& data, const std::string&
return ListingLookup::Unknown;
}
if (data[0] != TOKEN_FILE_LIST) return ListingLookup::Unknown;
// 不在服务端截断:默认那 500 条是给界面用的窗口,这里要扫全(大小仍由客户端单包上限约束)。
// 复核要扫全整个列表(list_files 自己也已整目录解析;这里上限只为兜底)。
const Json::Value items = ParseFileList(data, 1000000, 936);
for (unsigned int i = 0; i < items.size(); ++i) {
const std::string name = JsonStrField(items[i], "name");
@@ -14006,7 +14070,10 @@ bool CMcpServer::OnDriveList(uint64_t device_id, context* subCtx, const BYTE* bu
searchFile = true;
it->second.subCtx = subCtx; // 超时停搜 / 收尾要用
} else {
listDrives = path.empty() || path == "." || path == "/" || path == "\\";
// 列盘一律用空 path 表示:Windows 的 "."、"/"、"\\" 已在 BuildListFiles 归一化成
// 空串;POSIX 上 "/" 与 "." 是真实目录,必须按目录下发。这里不再自行判魔法路径,
// 免得两个地方口径不一致。
listDrives = path.empty();
if (listDrives) {
it->second.data.assign(buf, buf + len);
it->second.done = true;
+18 -14
View File
@@ -31,10 +31,11 @@ import (
// ctx answered, which is also how late packets from a previous sub-conn are
// told apart from the current one.
const (
// fileListMaxEntries matches the published contract: tools.json advertises
// "最多 500 条" and the Win32 server parses 500 entries, so a larger
// directory is cut here too (the summary tells the model it was cut).
fileListMaxEntries = 500
// fileListMaxEntries is the parse cap shared with the Win32 server: the
// directory is parsed in full and paged afterwards, so total/hasMore stay
// true; only a pathological directory is cut here, and structuredContent
// then carries truncated=true and the summary says so.
fileListMaxEntries = 100000
// fileRecordFixedLen is attr(1) + size(8) + FILETIME(8).
fileRecordFixedLen = 17
@@ -522,15 +523,17 @@ func parseFileList(p []byte) ([]fileEntry, bool) {
out := make([]fileEntry, 0, 64)
off := 0
for off < len(p) {
if len(out) >= fileListMaxEntries {
return out, true
}
attr := p[off]
off++
name, n, ok := cString(p[off:])
if !ok || n == 0 {
break
}
// Cap check after a real record is seen: trailing zero padding (an empty
// name) must not report truncation when the listing is exactly at the cap.
if len(out) >= fileListMaxEntries {
return out, true
}
off += n + 1
if off+fileRecordFixedLen-1 > len(p) {
break
@@ -609,12 +612,13 @@ func listFilesResult(args listFilesArgs, drives []driveEntry, files []fileEntry,
begin := min(offset, total)
end := min(begin+limit, total)
structured = map[string]any{
"files": files[begin:end],
"total": total,
"totalAll": total,
"limit": limit,
"offset": offset,
"hasMore": end < total,
"files": files[begin:end],
"total": total,
"totalAll": total,
"limit": limit,
"offset": offset,
"hasMore": end < total,
"truncated": truncated,
}
text = pageSummary(total, limit, offset, "个条目")
header = []string{"name", "isDir", "size", "mtime"}
@@ -627,7 +631,7 @@ func listFilesResult(args listFilesArgs, drives []driveEntry, files []fileEntry,
}
}
if truncated {
text += fmt.Sprintf("目录条目超过 %d 条,只解析了前 %d 条。", fileListMaxEntries, fileListMaxEntries)
text += fmt.Sprintf("目录条目超过 %d 条,total 只是上限内的数量,请缩小目录范围。", fileListMaxEntries)
}
text = appendRows(text, header, rows)
return newToolResult(text, structured)
+19 -1
View File
@@ -723,7 +723,10 @@ func TestListFilesTruncationNote(t *testing.T) {
}
sc := c.res.StructuredContent.(map[string]any)
checkInt(t, sc, "total", fileListMaxEntries)
if !strings.Contains(c.res.Content[0].Text, "只解析了前") {
if v, ok := sc["truncated"].(bool); !ok || !v {
t.Fatalf("structuredContent truncated = %#v, want true", sc["truncated"])
}
if !strings.Contains(c.res.Content[0].Text, "total 只是上限内的数量") {
t.Fatalf("summary does not mention the cap: %q", c.res.Content[0].Text)
}
// The note must stay on its own line, before the table.
@@ -743,3 +746,18 @@ func TestParseFileListEntryCap(t *testing.T) {
t.Fatalf("parsed %d entries, truncated=%v", len(files), truncated)
}
}
func TestParseFileListAtCapIsNotTruncated(t *testing.T) {
// Exactly cap entries followed by the client's zero padding: nothing was
// dropped, so the summary must not claim truncation.
var buf []byte
for i := 0; i < fileListMaxEntries; i++ {
buf = append(buf, 0, 'a', 0)
buf = append(buf, make([]byte, 16)...)
}
buf = append(buf, 0, 0, 0)
files, truncated := parseFileList(buf)
if len(files) != fileListMaxEntries || truncated {
t.Fatalf("parsed %d entries, truncated=%v", len(files), truncated)
}
}
+6 -2
View File
@@ -434,7 +434,7 @@
},
{
"name": "list_files",
"description": "列举指定在线主机的目录。省略或空 path 返回驱动器列表(drives);给定 path 返回该目录一层内的文件/子目录(files,最多 500 条,含 name/isDir/size/mtime)。只读。",
"description": "列举指定在线主机的目录。省略或空 path 返回驱动器列表(drives);给定 path 返回该目录一层内的文件/子目录(files,含 name/isDir/size/mtime),整目录解析后按 limit/offset 分页(默认 100 条、上限 1000 条,total/hasMore 是真实的目录条目数;目录超过 10 万条时按上限截断并返回 truncated=true)。Windows 上 \".\"/\"/\"/\"\\\\\" 视同省略 path;Linux/macOS 上 \"/\" 是根目录。只读。",
"inputSchema": {
"anyOf": [
{
@@ -469,7 +469,7 @@
"type": "integer"
},
"path": {
"description": "要列举的目录路径(如 C:\\Windows);省略或传空则返回驱动器列表",
"description": "要列举的目录路径(如 C:\\Windows 或 /etc)。省略或传空返回驱动器列表;Windows 上 \".\"、\"/\"、\"\\\\\" 视同省略;Linux/macOS 上 \"/\" 是根目录,按真实目录列举。",
"type": "string"
}
},
@@ -539,6 +539,10 @@
},
"totalAll": {
"type": "integer"
},
"truncated": {
"description": "目录条目超过服务端解析上限(100000 条)时为 true;仅在返回 files 时可能出现,此时 total 不是真实总数。",
"type": "boolean"
}
},
"type": "object"