Feature: Add list_files and get_screenshot MCP tools

Add the two P2c MCP tools on top of the P2b protocol. list_files lists
drives (COMMAND_LIST_DRIVE -> TOKEN_DRIVE_LIST) or a directory (follow-up
COMMAND_LIST_FILES -> TOKEN_FILE_LIST on the same one-shot sub-link);
get_screenshot reuses the screen-preview RPC with a per-host reqId
correlation so stale or MFC-preview responses fall through to the MFC
path untouched. Both share the P2b single-flight pending registry.

Fix file/process name encoding: the client reads process names, paths and
file names via the ANSI (A) APIs, so they are GBK on Windows regardless of
the CLIENT_CAP_UTF8 capability bit (which governs window titles only).
Decode by clientType (LNX/MAC = UTF-8, Windows = 936) rather than
GetClientEncoding, and convert the list_files path to the client ANSI code
page before sending. Sync Mcp_Phase2_Design.md with the P2c design and the
encoding correction.

Co-Authored-By: deepseek-v4-pro

docs/Mcp_Phase2_Design.md

@@ -1,6 +1,6 @@
 # YAMA MCP 功能开发技术书（Phase 2 及后续）
 
-> **状态**：设计定稿（已按两轮评审修订）；P2a、P2b 已实现并经真实主机验证（`search_hosts` / `get_host_detail` / `list_processes` / `list_windows` / `get_activity_history`）。
+> **状态**：设计定稿（已按两轮评审修订）；P2a、P2b 已实现并经真实主机验证（`search_hosts` / `get_host_detail` / `list_processes` / `list_windows` / `get_activity_history`）；P2c 已实现、待实机验证（`get_screenshot` / `list_files`）。
 > **读者**：MCP 后续功能的研发/评审人员。
 > **关联文档**：[Mcp_Design.md](./Mcp_Design.md)（Phase 1 的协议、架构、配置与菜单设计）。
 > **核心目标**：让 MCP 从「单个只读工具」平滑演进为「分阶段、可回滚、影响面可控」的工具集，**不一次性大改现有功能**。
@@ -112,9 +112,11 @@ MCP 工具 tools/call
 - **有子链接、有 subCtx**：数据落在子 context 上，非主 context。子 context 的 `GetClientID()` 已由 `TOKEN_CONN_AUTH`（`2015RemoteDlg.cpp:6291` 的 `SetID`）钉成主连接 clientID，故 `IsPending(devId)` 能与主 context 的 `device_id` 对上。
 - **用完即关**：MCP 拦截后 `CancelIO()` 关闭子链接（客户端 IOCPClient 以 `exit_while_disconnect=true` 构造，会随断开退出）；不关会泄漏子链接。
 - **与 MFC 对话框可并存**：MCP 与 MFC 对话框**各自使用独立的子链接**（客户端每次 `COMMAND_SYSTEM`/`COMMAND_WSLIST` 都新建一条），因此两者互不阻塞——MCP 的一次性调用不会导致 MFC 无法查看进程/窗口，反之亦然。无请求 id 的串扰靠「每 host 单飞行」（§4.4）规避，而非「与 MFC 对话框互斥」。
-- **编码**：进程名/路径为客户端 ANSI（CP_ACP）；窗口标题为客户端 UTF-8（按能力位 `CLIENT_CAP_UTF8` 判别，老客户端回落 CP_ACP）。
+- **编码**：进程名/路径按 clientType 判定（Windows=GBK/936、LNX/MAC=UTF-8，进程枚举走 A 接口不随 `CLIENT_CAP_UTF8` 转 UTF-8）；窗口标题为客户端 UTF-8（按能力位 `CLIENT_CAP_UTF8` 判别，老客户端回落 CP936）。
 - **请求关联**：无请求 id → 每 host 单飞行（§4.4）。
 
+- **文件列举也走 A′（`list_files`）**：列盘与进程/窗口同构（`COMMAND_LIST_DRIVE`→一次性子链接→`TOKEN_DRIVE_LIST` 即关）；列目录则在此一次性子链接上**多一轮** `COMMAND_LIST_FILES`→`TOKEN_FILE_LIST` 后再关。故 `list_files` 归入模式 A′，而非原设计的模式 A（详见 §6.3）。
+
 > **模式 A0（主连接单向命令，无响应）**：`kill_process`（`COMMAND_KILLPROCESS`）、`send_message`（`COMMAND_TALK`）这类「发完即走」的命令没有 MCP 需要的响应数据，**不需要** §4.4 的挂起注册表/超时/单飞行——`Send2Client` 后直接返回成功。它是模式 A 的退化情形，实现最简单。
 
 ### 4.3 模式 B：子链接流式（终端 / 完整屏幕 / 完整文件）
@@ -192,8 +194,8 @@ Web 是长连接，子链接可长驻；MCP 是**一次性 request/response**。
 | P2b（已实现并验证） | `list_processes` | 主机进程列表 | `COMMAND_SYSTEM`→（子链接）`TOKEN_PSLIST` | **A′** | 只读 |
 | P2b（已实现并验证） | `list_windows` | 主机窗口列表 | `COMMAND_WSLIST`→（子链接）`TOKEN_WSLIST` | **A′** | 只读 |
 | P2b（已实现并验证） | `get_activity_history` | 单机历史活动（文本快照） | `COMMAND_QUERY_ACTIVITY`(159)→`TOKEN_REPORT_ACTIVITY`(160) | **A** | 只读 |
-| P2c | `get_screenshot` | 单帧屏幕截图（JPEG） | `COMMAND_SCREEN_PREVIEW_REQ`→`TOKEN_SCREEN_PREVIEW_RSP` | **A** | 只读 |
-| P2c | `list_files` | 目录列举 | `COMMAND_LIST_DRIVE`/`COMMAND_LIST_FILES`→`TOKEN_DRIVE_LIST`/`TOKEN_FILE_LIST` | **A** | 只读 |
+| P2c（已实现） | `get_screenshot` | 单帧屏幕截图（JPEG） | `COMMAND_SCREEN_PREVIEW_REQ`→`TOKEN_SCREEN_PREVIEW_RSP` | **A** | 只读 |
+| P2c（已实现） | `list_files` | 目录列举 | `COMMAND_LIST_DRIVE`→`TOKEN_DRIVE_LIST`（列盘）/ 同子链接再 `COMMAND_LIST_FILES`→`TOKEN_FILE_LIST`（列目录） | **A′** | 只读 |
 | P3 | `exec_command` | 执行命令、返回 stdout | `COMMAND_SHELL`→`TOKEN_SHELL_START`/`TOKEN_SHELL_DATA` | **B** | **写** |
 | P3 | `send_message` | 给被控端弹消息 | `COMMAND_TALK`(220) | **A0** | 写（低危） |
 | P3 | `kill_process` | 结束进程 | `COMMAND_KILLPROCESS` | **A0** | **写** |
@@ -201,7 +203,7 @@ Web 是长连接，子链接可长驻；MCP 是**一次性 request/response**。
 
 ### 5.2 Phase 2：只读观测（低风险，无写操作）
 
-全部只读，不改变被控端任何状态，token 模型不变（仍单一静态 token）。P2a 纯内存、零改动；P2b/P2c 引入模式 A 无头接管，但只读、可回滚。
+全部只读，不改变被控端任何状态，token 模型不变（仍单一静态 token）。P2a 纯内存、零改动；P2b/P2c 引入模式 A/A′ 无头接管，但只读、可回滚。
 
 ### 5.3 Phase 3：安全写操作（需单独评审）
 
@@ -238,7 +240,7 @@ Web 是长连接，子链接可长驻；MCP 是**一次性 request/response**。
 
 - `McpServer.h/.cpp`：
   - 加 §4.4 的 `m_Pending` 注册表 + `IsPending`/`TakeMainResponse`/`BeginPending`/`WaitPending`/`ClearPending`，每 host 单飞行检查。
-  - 加解析器 `ParseProcessList`（PID/name/arch/path，CP_ACP 转 UTF-8）、`ParseWindowList`（hwnd/title/status/pid，标题按能力位解码）；两者都用 `BoundedStrlen` 有界读 + 「空记录 = 尾部零填充」终止，规避客户端 `LocalSize` 对齐引入的尾部零字节。
+  - 加解析器 `ParseProcessList`（PID/name/arch/path，按 clientType 编码转 UTF-8）、`ParseWindowList`（hwnd/title/status/pid，标题按能力位解码）；两者都用 `BoundedStrlen` 有界读 + 「空记录 = 尾部零填充」终止，规避客户端 `LocalSize` 对齐引入的尾部零字节。
   - 加三个工具：`list_processes`（发 `COMMAND_SYSTEM`）、`list_windows`（发 `COMMAND_WSLIST`）、`get_activity_history`（发 `COMMAND_QUERY_ACTIVITY`）。
 - `2015RemoteDlg.cpp` 的 `MessageHandle`：
   - `TOKEN_PSLIST`/`TOKEN_WSLIST` 分支（子 context）：`if (McpServer().IsPending(devId)) { TakeMainResponse(devId, GetBuffer(0), GetBufferLength()); ContextObject->CancelIO(); break; }`（**在 UI 线程、IO 线程阻塞期间同步拷贝**；用完即关子链接）。
@@ -250,7 +252,7 @@ Web 是长连接，子链接可长驻；MCP 是**一次性 request/response**。
 - MFC 双击进程/窗口管理弹框仍正常（回归点）；MFC 历史活动对话框仍正常（回归点）。
 - MCP `list_processes` 返回 `[{pid,name,arch,path}]`；`list_windows` 返回 `[{hwnd,title,status,pid}]`；`get_activity_history` 返回 `{records:[...], activityHistory}`（UTF-8 文本，逐行拆记录）。
 - 超时（如对离线主机）返回 `-32001` 而非挂死；同 host 并发第二次调用返回 `-32003`「设备忙」；发送失败返回 `-32004`。
-- 中文进程名/窗口标题无乱码（进程名 CP_ACP、窗口标题按能力位 UTF-8）。
+- 中文进程名/窗口标题无乱码（进程名按 clientType 解码、窗口标题按能力位 UTF-8）。
 
 **验证记录**（2026-08-19，真实在线主机实测）：
 - `list_processes`（Windows 11 主机）：`pid`/`name`/`arch`/`path` 完整；`pid==0` 仅 1 条（合法 `[System Process]`），无尾部零填充空记录——padding 防护生效。
@@ -261,18 +263,48 @@ Web 是长连接，子链接可长驻；MCP 是**一次性 request/response**。
 
 **回滚**：revert `McpServer.h` + `McpServer.cpp` + `MessageHandle` 两处 `if` 分支。
 
-### 6.3 P2c：`get_screenshot` + `list_files`（模式 A）
+### 6.3 P2c：`get_screenshot` + `list_files`（模式 A / A′）✅ 已实现（待实机验证）
 
-**`get_screenshot`（屏幕预览链路，主连接 RPC）**：
+> 本节按实际实现修订：`get_screenshot` 是**主连接 RPC**（模式 A，有 reqId 关联）；`list_files` 是**一次性子链接**（模式 A′）——列盘 `COMMAND_LIST_DRIVE`→`TOKEN_DRIVE_LIST` 即关，列目录则在 `TOKEN_DRIVE_LIST` 到达时就地同子链接再发 `COMMAND_LIST_FILES`→`TOKEN_FILE_LIST` 后关链。原设计把 `list_files` 误标为模式 A，已纠正（与 §4.2′ 对进程/窗口的同类纠正一致）。
 
-- 复用**现有双击预览机制** `COMMAND_SCREEN_PREVIEW_REQ`(247)→`TOKEN_SCREEN_PREVIEW_RSP`(248)（`common/commands.h:416-455`，单帧 JPEG，`ScreenPreviewReq`/`ScreenPreviewRspHeader`），`ctx->Send2Client` 发请求、主连接回响应，**不建子链接、不弹框**。
-- `ScreenPreviewReq.reqId` 提供请求关联，可丢弃过期响应。
-- 客户端能力位 `CLIENT_CAP_SCREEN_PREVIEW`(0x0004，仅 Windows 客户端声明)：非 Windows 主机返回「不支持」错误。
-- 若后续需要更高清/控制，再升级为完整屏幕子链接（模式 B，需 `RegisterScreenContext` 接管）。
+**`get_screenshot`（屏幕预览链路，主连接 RPC，模式 A）**：
 
-**`list_files`**：复用经典文件链路 `COMMAND_LIST_DRIVE`→`TOKEN_DRIVE_LIST` 与 `COMMAND_LIST_FILES`→`TOKEN_FILE_LIST`（模式 A）。**明确范围**：本阶段只做经典链路；项目另有 `COMMAND_GET_FOLDER`(66)、插件版 `TOKEN_DRIVE_LIST_PLUGIN`(150)、V2 文件传输，均列为非目标。文件列表可能较大，需**分页/上限**（首期限 `path` 一层、条目上限 500），避免 JSON 响应过大。
+- 复用现有双击预览机制 `COMMAND_SCREEN_PREVIEW_REQ`(247)→`TOKEN_SCREEN_PREVIEW_RSP`(248)（`common/commands.h:416-455`，单帧 JPEG，`ScreenPreviewReq`/`ScreenPreviewRspHeader`），`ctx->Send2Client` 发请求、主连接回响应，**不建子链接、不弹框**。
+- 复用 MFC 预览的 RTT/FRP 自适应参数挑选 `ChooseScreenPreviewParams` + `SendScreenPreviewRequest`，不重复实现 `GetTargetQualityLevel`。
+- **请求关联**：`ScreenPreviewReq.reqId` 提供关联；MCP 用独立 16 位 reqId 发生器（`NextPreviewReqId`，跳过 0）+ `SetPendingReqId` 登记期望值，`TakePreviewResponse` 只接受「挂起命中 + reqId 一致」的响应，过期/他途（MFC 预览并发）响应原样回落到 MFC 路径。
+- 客户端能力位 `CLIENT_CAP_SCREEN_PREVIEW`(0x0004，仅 Windows 客户端声明)：非 Windows 主机返回 `-32005`「不支持」。
+- 返回结构：`content[0] = {type:"image", data: base64(JPEG), mimeType:"image/jpeg"}` + `structuredContent.image = {mimeType,width,height,bytes}`（元数据，不含 base64，避免二次膨胀）。
 
-**验收**：`get_screenshot` 返回 JPEG（base64 或经 MCP 图片内容类型）；Windows 主机正常、非 Windows 返回明确「不支持」；`list_files` 正确列目录且有大列表保护。
+**`list_files`（文件链路，一次性子链接，模式 A′）**：
+
+- 复用经典文件链路 `COMMAND_LIST_DRIVE`→`TOKEN_DRIVE_LIST` 与 `COMMAND_LIST_FILES`→`TOKEN_FILE_LIST`。**明确范围**：本阶段只做经典链路；项目另有 `COMMAND_GET_FOLDER`(66)、插件版 `TOKEN_DRIVE_LIST_PLUGIN`(150)、V2 文件传输，均列为非目标。
+- **两种调用形态**：
+  - `path` 缺省/空（或 `.`/`/`/`\`）→ 只列盘：`COMMAND_LIST_DRIVE` 开子链接，`TOKEN_DRIVE_LIST` 到达即取走盘列表并关链（与进程/窗口同构的 A′）。
+  - `path` 指定目录 → 列目录：`TOKEN_DRIVE_LIST` 到达时 `OnDriveList` 就地同子链接下发 `COMMAND_LIST_FILES`+`path`（`BuildListFiles` 已按客户端 ANSI 转好，`OnDriveList` 不再转），等 `TOKEN_FILE_LIST` 取走并关链。
+- **编码**：盘符类型名/文件系统、文件名、`path` 均按 **clientType** 判定（与进程名/路径一致）：Windows 走 A 接口（`FindFirstFileA`/`GetLogicalDriveStringsA`/`SHGetFileInfoA` 等）= 客户端 ANSI(GBK/936)；LNX/MAC 文件系统天然 UTF-8。**不能用 `GetClientEncoding`**——它按能力位返回 CP_UTF8，会误解声明 `CLIENT_CAP_UTF8` 的 Windows 客户端（其文件名实为 GBK）。解析用 `ToUtf8(buf, cp)`、下发用 `ToAnsi(path, cp)`，`cp = (clientType=="LNX"||"MAC") ? CP_UTF8 : 936`。
+- **大列表保护**：`ParseFileList(data, 500, cp)` 条目上限 500，避免 JSON 响应过大。
+- 返回结构：列盘 → `structuredContent.drives[]`；列目录 → `structuredContent.files[]`（`{name,isDir,size,mtime}`，mtime 为 Unix 秒）。
+
+**改动**：
+
+- `McpServer.h/.cpp`：
+  - 挂起注册表扩展：`PendingRequest` 增 `path`、`expectedReqId` 字段；`BeginPending(devId, tool, path)` 重载，新增 `NextPreviewReqId`/`SetPendingReqId`/`TakePreviewResponse`/`OnDriveList` 四方法。
+  - 解析器：`ParseDriveList`（`[letter][type][totalMB:4][freeMB:4][typeName\0][fileSystem\0]`，`letter=='\0'` 终止）、`ParseFileList`（`[attr][filename\0][sizeHigh:4][sizeLow:4][ft:8]`，空记录/上限 500 终止）。
+  - 工具：`get_screenshot`（模式 A）、`list_files`（模式 A′），注册 schema（`get_screenshot` 无 inputSchema、`list_files` 带可选 `path`）。
+- `2015RemoteDlg.cpp` 的 `MessageHandle`（三处拦截）：
+  - `TOKEN_SCREEN_PREVIEW_RSP`（主 context）：`TakePreviewResponse(devId, reqId, szBuffer, len)` 命中则 break（**不 CancelIO**，主连接不可关）。
+  - `TOKEN_DRIVE_LIST`（子 context）：`if (IsPending) { OnDriveList(...) ? CancelIO() : /*继续等*/ break; }`（列盘关链、列目录不关）。
+  - `TOKEN_FILE_LIST`（子 context，**新增 case**）：`if (IsPending) TakeMainResponse(...); CancelIO();`（无论命中都关孤儿子链接，防泄漏）。
+
+**影响面**：`MessageHandle` 仅新增 `if` 分支与一个 `TOKEN_FILE_LIST` case；非 MCP 触发时 `IsPending` 为假、`TOKEN_FILE_LIST` case 在 MFC 路径下因 `hDlg` 接管根本不进 `MessageHandle`，现有 MFC 文件管理/屏幕预览弹框路径不变。
+
+**验收 / 实机验证点（待构建后执行）**：
+- MFC 双击文件管理弹框仍正常（回归点）；MFC 双击预览缩略图仍正常（回归点）。
+- MCP `get_screenshot` 返回 JPEG（base64 + 元数据），Windows 主机正常；非 Windows 主机（或未声明 `CLIENT_CAP_SCREEN_PREVIEW`）返回 `-32005`。
+- MCP `list_files`（无 `path`）返回 `drives[]`；`list_files(path="C:\\")` 返回 `files[]`（含目录/文件/大小/mtime），中文文件名无乱码；条目 >500 时截断为 500。
+- 错误路径：缺 `id`/非数字 `id` → `-32602`；未知/离线主机 → `-32002`；同 host 并发 → `-32003`；发送失败 → `-32004`；超时 → `-32001`。
+
+**回滚**：revert `McpServer.h` + `McpServer.cpp` + `MessageHandle` 三处拦截。
 
 ### 6.4 P3a：`exec_command`（模式 B，写操作，评审后实施）
 
@@ -399,7 +431,7 @@ Web 是长连接，子链接可长驻；MCP 是**一次性 request/response**。
 
 1. **P2a**（`search_hosts` + `get_host_detail`）✅ ——纯内存、零风险，已实现，验证「多工具 dispatch」模式。
 2. **P2b**（`list_processes` + `list_windows` + `get_activity_history`）✅ ——首次引入**模式 A′ 一次性子链接**（进程/窗口）与**模式 A 主连接 RPC**（历史活动）无头接管，把 §4.2/§4.2′ 的机制跑通并沉淀成 §7 配方。
-3. **P2c**（`get_screenshot` 走屏幕预览链路 + `list_files`）——补上「看」的能力，仍是只读、模式 A。
+3. **P2c**（`get_screenshot` 走屏幕预览链路 + `list_files`）✅ ——补上「看」的能力，仍是只读（`get_screenshot` 模式 A、`list_files` 模式 A′）。
 4. **P3a**（`exec_command`）——首次引入**模式 B 子链接流式**，在 P2 的挂起机制成熟后，走完安全评审再落地写操作。
 
 每完成一期即提交、验收，再进入下一期，保持「有序、平稳、循序渐进」。