The destination writes every chunk unconditionally, so a second call with the same arguments re-sent the whole file and returned exactly the same result as the first. Measured on an 11 MB log: the target's mtime moved and the entry count did not, and the caller had no way to tell a real transfer from a repeat. upload_file and download_file already answer this with overwrite/skipped; copy_files_c2c was the one that did not. The skip decision has to be made on the server, because the receiving end does not check whether the file exists. Before opening the transfer, a default call now lists one level of dst_dir through ListRemoteTopLevelNames - the helper upload_file already uses - and drops the paths whose basename is already there. If everything is dropped the call returns success without creating a transfer id at all, so no host is occupied and nothing is sent. overwrite=true restores the old unconditional behaviour. Name comparison follows the destination filesystem: folded on Windows, exact on POSIX. That needed a foldCase parameter on the helper, defaulted to true so upload_file keeps its behaviour. dst_dir is handed to the listing without its trailing separator, because the client concatenates "%s\*.*" and a trailing one produces "C://*.*", which FindFirstFile rejects. search_file hit the same thing. No protocol change and no client change: the packet layout, the receiver and both client platforms are untouched. Verified against a real server (build 2026-10-29 14:34:33) with a Windows 11 source and both an Ubuntu 24.04 and a Windows 11 destination. A second default call returns file_count=0, skipped=1, an empty transfer_id and skip_check_failed=false with the target's mtime unchanged; overwrite=true advances the mtime (1793276909 -> 1793281657) and reports skipped=0; a call into a non-existent directory creates it and lands the file flat; a Windows destination folds case, so a placeholder SETTINGS.INI makes a later settings.ini skip, while a POSIX destination leaves both files side by side. One documented case does not hold, and the expectation was mine rather than the code's. "Destination occupied by another tool" was supposed to fail the pre-check and still transfer with skip_check_failed=true, but BeginC2CTransfer consults the same m_Pending registry for src_id and dst_id, so the transfer is refused with -32003 before the fallback can carry it. The other door - a directory that can be written but not listed - showed the pre-check succeeding instead of failing: the Linux client reports EACCES as an empty directory rather than TOKEN_FILE_LIST_ERROR, so the call goes on to overwrite. skip_check_failed is therefore a timeout backstop that is hard to reach deliberately; the field stays, and 14.9.2 no longer claims that a busy host reaches the fallback. Section 14.9 of the design doc records the contract, those results, and one wrong turn worth keeping: an earlier round concluded that single-file C2C nested the whole absolute path under dst_dir, and added receiver-side hardening for it. The nesting came from the ad-hoc JSON-RPC test harness, which passed JSON on the command line where the shell folded \\ into \/ before Python parsed it, so the source client received a path with no backslashes left and its basename fallback - which looks for a backslash - returned the whole path. The same file sent through the real MCP client produces a clean basename. That hardening has been reverted; the defect was in the test, not the product. Co-Authored-By: deepseek-flash
60 KiB
YAMA MCP 文件传输功能设计(download_file / upload_file / copy_files_c2c)
状态:设计定稿(经专家审查修订,结论见 §13)。
download_file(P1)已实施并验收;upload_file(P2)已实施(详见 §7,评审修订见 §13.1)。copy_files_c2c(P3,客户端间直传、服务端只中继)已实施(见 §14)。download_file采用 V2 文件传输协议(CMD_DOWN_FILES_V2+ 流式子连接 + SHA-256 校验),upload_file复用服务端既有FileBatchTransferWorkerV2(主连接同步驱动),copy_files_c2c复用 V2 的 C2C 中继(dstClientID != 0)。三者共享同一套「文件会话」注册表。 读者:MCP 后续功能研发/评审人员。 关联文档:Mcp_Phase2_Design.md(双模式无头驱动机制)、FILE_TRANSFER_V2.md(V2 协议清单)、Mcp_Design.md(Phase 1 协议/架构/配置)。
1. 背景与目标
MCP 目前已暴露 list_files(只读列目录,McpServer.cpp:1741),但没有文件传输工具:把远程主机的文件/目录拉回主控本机(下载),或把本机文件推到远程(上传),只能通过 GUI 文件管理器手工操作。
本技术书解决:
download_file(本期 P1)——远程文件/目录 → 主控本机指定目录,复用 V2 推送协议,带 SHA-256 完整性校验、支持大文件。upload_file(后续 P2)——主控本机文件/目录 → 远程指定目录,复用服务端 V2 发送器。- 一套共享的「流式文件会话」基础设施——一次投入,下载/上传两处受益,镜像现有终端(
TermSession)与远程控制(ScreenCtrlSession)会话模式。
2. 现状回顾
| 能力 | 现有协议/命令 | 服务端现有实现 | 是否暴露给 MCP |
|---|---|---|---|
| 远程列目录 | COMMAND_LIST_DRIVE→TOKEN_DRIVE_LIST;COMMAND_LIST_FILES→TOKEN_FILE_LIST |
McpServer.cpp:1741(list_files) |
✅ |
| 远程→本地下载(V1) | COMMAND_DOWN_FILES(commands.h:166) + TOKEN_FILE_SIZE/DATA/FINISH |
FileManagerDlg.cpp:2164 / file/CFileManagerDlg.cpp:1136 |
❌ 仅 GUI |
| 远程→本地下载(V2) | CMD_DOWN_FILES_V2(94, commands.h:260) + COMMAND_SEND_FILE_V2(85) + COMMAND_FILE_COMPLETE_V2(91) |
FileManagerDlg.cpp:3337-3384(下发)、2756(RecvFileChunkV2 落盘) |
❌ 仅 GUI |
| 本地→远程上传(V2) | FileBatchTransferWorkerV2(服务端作 sender) |
2015RemoteDlg.cpp:7572 |
❌ 仅 GUI |
2.1 关键事实
-
V2 下载的客户端会另开一条新子连接:
client/FileManager.cpp:1101-1190UploadToRemoteV2()解析完文件列表后,new IOCPClient(...)→EnableSubConnAuth()→ConnectServer(...)(FileManager.cpp:1170-1172),在独立鉴权子连接上推COMMAND_SEND_FILE_V2分块 +COMMAND_FILE_COMPLETE_V2校验包。即下载 ≠ 复用文件管理器那条子链接,而是一条持续流子链接——正属Mcp_Phase2_Design.md §4.3当初判定「本期不做」的流式能力。 -
接收端
RecvFileChunkV2无 UI 可调:CDlgFileSend.cpp:128已RecvFileChunkV2(buf, len, nullptr, nullptr, hash, hmac, 0)无头落盘;落盘状态在SimplePlugins/file_upload.cpp内部按transferID自维护,天然适合 MCP 无头复用。 -
V2 落盘路径由客户端回填:
CMD_DOWN_FILES_V2的targetDir是主控本机保存目录(FileManagerDlg.cpp:3370m_Local_Path);客户端把它拼进每个 chunk 的filename发回,服务端RecvFileChunkV2直接按该完整路径写盘。因此「下载保存到哪」由服务端在命令里指定、客户端原样回填。
3. 协议选型(已定:V2)
| 维度 | V2 推送(选定) | V1 拉取(回退) |
|---|---|---|
| 命令 | CMD_DOWN_FILES_V2 + COMMAND_SEND_FILE_V2 + COMMAND_FILE_COMPLETE_V2 |
COMMAND_DOWN_FILES + TOKEN_FILE_SIZE/DATA/FINISH |
| 连接 | 客户端新开一条鉴权流式子连接 | 复用文件管理器子链接 |
| 完整性 | ✅ SHA-256(COMMAND_FILE_COMPLETE_V2) |
❌ 无 |
| 大文件 | ✅ 64 位偏移,>4GB | 64 位偏移但无校验 |
| 客户端代码 | ✅ 已存在,是当前 GUI 正规路径 | ⚠️ 遗留路径 |
| MCP 侧复杂度 | 需路由一条新流式子连接(新增会话注册表) | 需在 MessageHandle 维护「发 CONTINUE/收 DATA」状态机,逐块 ACK 慢 |
结论:采用 V2。 代价是服务端要新增「流式文件会话」注册与路由;但这是 upload_file 同样要复用的基础设施,一次投入两处受益。V1 仅作「不想引入新子连接路由」时的降级备案,不在本期实现。
4. 设计原则
- 复用现有协议,不新造命令:
CMD_DOWN_FILES_V2、COMMAND_SEND_FILE_V2、COMMAND_FILE_COMPLETE_V2、COMMAND_LIST_DRIVE全部为common/commands.h既有;客户端零改动(upload 方向例外:COMMAND_SEND_FILE_V2需懒初始化文件模块,见 §7.8)。 - 无头接管复用会话模式:镜像
McpServer.h的TermSession/ScreenCtrlSession,新增FileTransferSession;MessageHandle用IsFileTransferContext(context*)判定是否路由到 MCP 无头落盘,否则回落 GUI 进度框。 - 单设备单传输会话:与终端/远程控制一致,避免同 host 并发传输的归属歧义;并发返回
-32003 Device busy。 - 超时与清理是硬约束:大文件传输是长任务,超时需独立于
kMcpToolTimeoutMs(20s);断线/超时必须清会话 + 关子链接 + 删半成品文件。 - 输出 schema 先行:两个工具先在
tools/list声明完整inputSchema/outputSchema。
5. 核心机制:流式文件会话
5.1 会话注册表(McpServer.h/.cpp)
struct FileTransferSession {
std::string tool; // "download_file" / "upload_file"
std::string localDir; // download: 本机落盘目录(规范化后绝对路径,用于穿越校验)
std::string remotePath; // 审计用原始远程路径(UTF-8)
uint64_t transferID = 0; // 绑定后从首包填充(download);upload 由本端 GenerateTransferID()
uint32_t totalFiles = 0; // 完成判定:首个 COMMAND_SEND_FILE_V2 chunk 的 totalFiles(§13 F4)
uint32_t filesDone = 0; // 完成判定:累计收到的 COMMAND_FILE_COMPLETE_V2 数
bool done = false;
int error = 0; // FEV2_* / 自定义
std::vector<FileEntry> files; // {path, size} 已落盘/已发送文件
std::vector<FileEntry> skipped; // overwrite=false 时跳过的同名文件
time_t startAt = 0;
};
std::mutex m_FileXferMutex;
std::map<uint64_t, FileTransferSession> m_FileXferSessions; // device_id → 会话
取消
m_FileXferContextToDevice映射与IsFileTransferContext(context*):流式子连接经TOKEN_CONN_AUTH已把clientID钉在ContextObject上(2015RemoteDlg.cpp:6411 SetID),分派时直接用ContextObject->GetClientID()定位device_id,无需 context 路由表(§13 F1)。
配套接口(与 BeginTermPending / OnTerminalData / WaitTerminalDone 同构):
bool BeginFileTransferPending(uint64_t device_id, const std::string& tool,
const std::string& localDir, const std::string& remotePath);
bool IsFileTransferPending(uint64_t device_id); // 分支顶部守卫
void OnFileChunkV2(uint64_t device_id, const BYTE* buf, ULONG len); // 路径校验 + 无头 RecvFileChunkV2
void OnFileCompleteV2(uint64_t device_id, const BYTE* buf, ULONG len);// SHA-256 + filesDone 计数
bool WaitFileTransferDone(uint64_t device_id, int timeoutMs, std::vector<FileEntry>& out);
void ClearFileTransfer(uint64_t device_id); // 失败/超时/断线收尾(删半成品)
5.2 流式子连接的路由(device_id 键,镜像 TOKEN_DRIVE_LIST 守卫)
V2 下载的数据包 COMMAND_SEND_FILE_V2(85) / COMMAND_FILE_COMPLETE_V2(91) 本就由 MessageHandle 按 ContextObject->GetClientID() 分派(2015RemoteDlg.cpp:5842 / 6101)。MCP 只需在这两个 case 的 dstClientID==0(M2C)分支顶部加守卫:
case COMMAND_SEND_FILE_V2: {
FileChunkPacketV2* pkt = (FileChunkPacketV2*)szBuffer;
if (pkt->dstClientID == 0) {
uint64_t devId = ContextObject->GetClientID();
if (McpServer().IsFileTransferPending(devId)) { // ← 新增守卫:无头接管
McpServer().OnFileChunkV2(devId, szBuffer, len);
break; // 不建 CDlgFileSend、不设 hDlg
}
// ... 原 GUI 逻辑(建 CDlgFileSend + OnReceiveComplete)不变
}
// ... C2C 分支(dstClientID != 0)完全不动
}
TOKEN_CONN_AUTH(6378) 完全不动——它只负责把clientID钉在 ctx 上,下载复用既有行为。TOKEN_DRIVE_LIST(6430) 既有IsPending(devId)守卫扩展复用:OnDriveList识别当前挂起工具为download_file时,改发CMD_DOWN_FILES_V2而非COMMAND_LIST_FILES,发完即CancelIO文件管理器子链接(数据走新流式子连接,§13 F3)。- 守卫为假时全部回落原 GUI/C2C 路径——对既有功能零影响(原则 #1,§13 F7)。
6. download_file 设计(P1)
6.1 工具 Schema
input: {
id: string (必填, 主机 id)
remote_path: string (必填, 远程文件或目录绝对路径, 如 C:\Users\shaun\Pictures)
local_dir: string (必填, 主控本机保存目录; 不存在会自动创建)
overwrite: boolean (可选, 默认 false; true 覆盖同名文件, false 则跳过)
timeout_ms: integer (可选, 默认 600000, 上限 3600000)
}
output: {
files: [{ path: string, size: integer, sha256: string }] // 实际落盘文件
total_bytes: integer
skipped: integer
}
6.2 时序
MCP工具线程 服务端 MessageHandle 客户端
│ 1. BeginFileTransferPending(id,"download_file",localDir,remotePath) │
│ 2. 主连接发 COMMAND_LIST_DRIVE ────────────────────────────────────────► 开文件管理器子链接
│ 3. ◄── TOKEN_DRIVE_LIST ─────────────────────┤
│ OnDriveList → 锁外下发 CMD_DOWN_FILES_V2[targetDir\0][remote_path\0]\0 │
│ 4. ────────────────────────────────────────► UploadToRemoteV2()
│ (客户端另开一条鉴权流式子连接 ConnectServer)
│ 5. 新子连接 TOKEN_CONN_AUTH 钉 clientID → 后续分块按 device_id 守卫接管 │
│ 6. ◄── COMMAND_SEND_FILE_V2 分块流 ──────────┤
│ → OnFileChunkV2 → RecvFileChunkV2() 无头落盘
│ 7. ◄── COMMAND_FILE_COMPLETE_V2(SHA-256) ────┤
│ 8. 校验通过 → done → 唤醒工具线程 → CancelIO 两条子连接 → 返回 │
6.3 服务端改动
McpServer.h:新增FileTransferSession结构 + 注册表 + 接口声明(§5.1)。McpServer.cpp:BuildDownloadFileInputSchema/OutputSchema+BuildDownloadFile(...)(tools/call分派);OnFileChunkV2:先路径校验(chunkfilename规范化后仍在local_dir内,防..穿越,§13 F5)→ 调RecvFileChunkV2(buf,len,nullptr,nullptr,hash,hmac,0)无头落盘,记totalFiles/进度;OnFileCompleteV2:HandleFileCompleteV2校验 SHA-256 →filesDone++;filesDone==totalFiles时置done+notify(§13 F4);hash/hmac镜像FileManagerDlg.cpp:2755的GetPwdHash()/GetHMAC(100),兼容客户端 M2Chmac为空(client/FileManager.cpp:1167,§13 F6);ClearFileTransfer(发送失败/超时/断线):CancelIO子链接 + 删除半成品。
2015RemoteDlg.cpp(MessageHandle):COMMAND_SEND_FILE_V2(85)、COMMAND_FILE_COMPLETE_V2(91) 的dstClientID==0分支顶部加IsFileTransferPending(devId)守卫;TOKEN_DRIVE_LIST处扩展OnDriveList识别download_file改发CMD_DOWN_FILES_V2。TOKEN_CONN_AUTH与 C2C 分支完全不动。McpSettingsDlg.cpp/.h:新增McpFileTransfer配置项(默认 0)。
6.4 落盘与路径安全
- 发
CMD_DOWN_FILES_V2前把local_dir规范化为绝对路径并CreateDirectory;targetDir用 ANSI(MBCS 构建本机路径)。 - 每收到一个 chunk,校验其
filename规范化后前缀必须在local_dir内(防..穿越,呼应FILE_TRANSFER_V2.md §8.3已识别的风险);逃逸则置error并CancelIO。 - 编码:
remote_path走 UTF-8→ANSI(936)(复用McpServer.cpp既有ToAnsi,与list_files一致)。POSIX 目标端的路径规则见 §15。
6.5 超时与并发
- P1 范围:同步 + 单文件/已打包目录。一次
tools/call阻塞到底,不引入 job/task 异步模型(决策见 §12)。核心场景「先terminal_exec压缩成单 zip,再download_file拉回」天然是单文件,同步足够。 - 默认
timeout_ms=600000、上限 3600000,因大文件远超kMcpToolTimeoutMs(20s)。 - 单飞互斥(§13 F2):
BeginFileTransferPending与既有一次性m_Pending双向互斥——下载登记时占用m_Pending,反之BeginPending也检查m_FileXferSessions,保证同 host 任意时刻只一个 MCP 工具在飞;并发返回-32003 Device busy。 - 断线(
OfflineProc擦会话)+ 超时(删半成品)双收尾。
7. upload_file 设计(P2)
7.1 工具 Schema
input: {
id: string (必填, 目标主机 id)
local_path: string (必填, 主控本机文件或目录绝对路径; 目录递归上传)
remote_dir: string (必填, 远程主机保存目录; 不存在会自动创建)
overwrite: boolean (可选, 默认 false; true 覆盖同名文件, false 跳过)
timeout_ms: integer (可选, 默认 600000, 上限 3600000)
}
output: {
files: [{ path: string, size: integer, sha256: string }] // 已发送文件(远程完整路径);P2 sha256 恒为空串(见 §7.5)
total_bytes: integer
skipped: integer
}
7.2 方向与连接(与 download 的关键差异)
| 维度 | download_file(P1) | upload_file(P2) |
|---|---|---|
| 数据方向 | 远程客户端 → 主控 | 主控 → 远程客户端 |
| 发送方 | 客户端(UploadToRemoteV2 → FileBatchTransferWorkerV2) |
主控(FileBatchTransferWorkerV2) |
| 连接 | 客户端新开一条鉴权流式子连接 | 复用主连接(ctx->Send2Client),无子连接 |
| 完成信号 | 客户端发 COMMAND_FILE_COMPLETE_V2,服务端 OnFileCompleteV2 校验计数 |
服务端作为发送方自己发 COMMAND_FILE_COMPLETE_V2(SHA-256),客户端 HandleFileCompleteV2 校验 |
| MessageHandle 改动 | 2 处守卫分支 + OnDriveList 扩展 |
零改动(客户端 KernelManager.cpp:1381 接收,但需懒初始化文件模块,见 §7.8) |
修正旧稿(§13.1 评审):旧稿写「只需等客户端回
COMMAND_FILE_COMPLETE_V2」是错的。V2 协议里 COMPLETE 包恒由发送方发、接收方校验,无接收方→发送方 ACK。upload 的服务端是发送方,故它发 COMPLETE 而非「等」。这也意味着 upload 比 download 更简单——无需路由外来流式子连接、无需OnFileCompleteV2计数。
7.3 时序
MCP工具线程 主连接 (ctx→Send2Client) 客户端 KernelManager
1. 校验 McpFileTransfer=1 && McpReadonly=0(§8)
2. CollectLocalFiles({local_path}) 收集本机文件+目录项(目录项在前、子项随后)
3. (overwrite=false) list_files 预检 remote_dir 一层 → 得已存在顶层名 → skip 列表
4. BeginFileUpload(id) 登记会话(单设备单传输互斥标记,§6.5)
5. 同步驱动(工具线程内):FileBatchTransferWorkerV2(files, remote_dir, cb, f, hash, hmac, opts)
6. ── COMMAND_SEND_FILE_V2 分块流 ───► RecvFileChunkV2 落盘
7. ── COMMAND_FILE_COMPLETE_V2(SHA256)► HandleFileCompleteV2 校验
8. worker 同步返回 → ClearFileTransfer → 返回 files/total_bytes/skipped
7.4 服务端改动
McpServer.h:新增BeginFileUpload(id),登记FileTransferSession{tool="upload_file", startAt}作为单设备单传输互斥标记(与m_Pending/m_FileXferSessions互斥,见 §6.5)。upload 走主连接、工具线程同步驱动FileBatchTransferWorkerV2,会话无fmSubCtx/streamSubCtx/fileEntries/done等字段(ClearFileTransfer对空指针安全)。McpServer.cpp:BuildUploadFileInputSchema/OutputSchema+BuildUploadFile(...)(tools/call分派);- 无头回调
UploadSendChunkHeadless(user, chunk, data, size):经UploadCallbackData{parent,clientID,deadline}里parent->FindHost(clientID)定位 ctx →ctx->Send2Client(data,size);客户端离线或整体超时返回 false 中止(镜像 GUISendFileChunkToClientV2,去掉dlg进度,见2015RemoteDlg.cpp:7424-7459); - 收集:本地
CollectLocalFiles递归(common/file_upload.cpp:38的ExpandDirectories未在file_upload.h导出,故在 McpServer.cpp 本地同构实现,目录项在前、子项随后); - overwrite 预检:复用
list_files的COMMAND_LIST_DRIVE→TOKEN_DRIVE_LIST→COMMAND_LIST_FILES→TOKEN_FILE_LIST机制列remote_dir一层(顶层名,不递归),过滤同名 →skipped; - 驱动:
FileBatchTransferWorkerV2(files, remote_dir, &cb, headlessCallback, nullptr, GetPwdHash(), GetHMAC(100), opts);opts.transferID=GenerateTransferID()、srcClientID=0、dstClientID=clientID、enableResume=false; - 完成判定:
result==0 && FindHost(clientID)!=nullptr(镜像 GUISendFilesToClientV2Internal末尾)。
2015RemoteDlg.cpp(MessageHandle):零改动。McpSettingsDlg.cpp/.h:零改动(McpFileTransfer已存在,§8 复用)。
7.5 完整性边界(诚实声明)
- V2 无接收方→发送方 ACK:客户端
HandleFileCompleteV2校验失败只打日志(RecvFileChunkV2返回 8,KernelManager.cpp:1381不回传主控)。 - P2 的
output.files[].sha256恒为空串:FileBatchTransferWorkerV2内部会为每个文件自算 SHA-256 并写入COMMAND_FILE_COMPLETE_V2包发给客户端,但该值不回传调用方;服务端侧又无导出的 SHA-256 工具函数可自行复算。故 P2 输出不填 sha256(延后 P3:worker 回传哈希,或服务端引入 SHA-256 工具)。传输完整性仍依赖客户端本地HandleFileCompleteV2校验(与 GUI upload / C2C 同权,属 V2 协议既有边界,非 MCP 引入)。 - 若未来需要「接收方验真回执」,需新增反向 ACK 包(协议扩展,进 P3)——Linux 目标端的
receiver_ack已实现,复用 §14 的 176 回执(见 §15),Windows 目标端仍为false。
7.6 overwrite 语义
overwrite=false(默认):发送前用list_files预检remote_dir一层(顶层名,不递归),本地顶层项名已存在者整体跳过(单文件精确、目录整体跳过),文件条目计入skipped(目录项不计)。编码 UTF-8→ANSI(936),与list_files/download_file一致。overwrite=true:全量发送(客户端RecvFileChunkV2覆盖写)。- 代价:一次预检往返;对称于 download 的「本地同名跳过」语义。
7.7 安全
- 门槛
McpFileTransfer=1 && McpReadonly=0(§8):upload 写远程盘,复用「允许写」主开关。 remote_dir路径规范化(防..穿越到预期目录之外)。local_path是主控本机路径(信任本地文件系统),主要风险是 AI 误推敏感文件/覆盖远程关键文件——由McpReadonly=0+ 审计兜底(与terminal_*/remote_*同款「开关+审计」,不加目录黑名单,见 §12.1)。
7.8 客户端改动(实施期修正,评审见 §13.1 U7)
RecvFileChunkV2 依赖全局 g_status==1(SimplePlugins/file_upload.cpp:2812 if (!g_status) return -1;),但客户端主连接此前从不初始化文件传输模块——InitFileUpload 只在 FileManager/ScreenManager 构造里成对调用(下载/屏幕方向),上传走主连接时 g_status==0,每个 chunk 都被 RecvFileChunkV2 直接丢弃(表现为落盘 0 字节 / 截断)。
修法:在 client/KernelManager.cpp 的 COMMAND_SEND_FILE_V2 分支加懒初始化(进程内仅一次):
static bool s_v2RecvInited = false;
if (!s_v2RecvInited) {
InitFileUpload({}, m_LoginMsg, m_LoginSignature, 64, 50, Logf);
s_v2RecvInited = true;
}
int n = RecvFileChunkV2((char*)szBuffer, ulLength, m_conn, nullptr, m_hash, m_hmac, m_MyClientID);
要点(独立评审结论,均为安全):
- 与
FileManager.cpp:40的 Init 参数逐字节一致({},m_LoginMsg,m_LoginSignature, 64, 50,Logf),不新增路径。 static保证进程内只初始化一次,主连接重连(ClientDll.cpp:660/665反复SAFE_DELETE+new CKernelManager)不反复 Init/Uninit;~CKernelManager保持原样不UninitFileUpload,故g_threadCount从 1 起永不归 0,g_status恒为 1。InitFileUpload幂等(g_fileStatesMtx+g_threadCount引用计数,二次调用g_threadCount>1早退)、非阻塞(仅置标志 + 派生 detach 线程)、license 校验在启动期licenseInit()后必过、verifyMessage对空签名return false(license.cpp:244)不会越界。- 影响面:主连接
OnReceive无 V1COMMAND_SEND_FILE分支,g_status=1只作用于RecvFileChunkV2;FileManager/ScreenManager的成对 Init/Uninit 只是在 1↔2 间震荡,语义不变。
8. 安全门
| 工具 | 定性 | 门槛 |
|---|---|---|
download_file |
不改远程状态,但数据外带 | McpFileTransfer=1(仅此一开关;不依赖 McpReadonly,与 list_files/get_screenshot 同权) |
upload_file |
写远程盘 | McpFileTransfer=1 且 McpReadonly=0(复用既有「允许写」主开关) |
- 只新增一个开关
McpFileTransfer(默认 0):download 只看它;upload 额外要求McpReadonly=0。决策依据见 §12。 tools/list据此隐藏两个工具(与exec_command/terminal_*/remote_*同款开关判断)。- 审计:
host_id + tool + remote_path + local_dir + 结果,写Mprintf+ 审计日志。
9. 改动文件清单
| 文件 | 改动 |
|---|---|
server/2015Remote/McpServer.h |
FileTransferSession + 注册表 + 8 个接口声明 |
server/2015Remote/McpServer.cpp |
download_file schema/实现 + 会话状态机 + 路由分支 |
server/2015Remote/2015RemoteDlg.cpp |
MessageHandle:COMMAND_SEND_FILE_V2(85) / COMMAND_FILE_COMPLETE_V2(91) 两处守卫分支 + TOKEN_DRIVE_LIST 处 OnDriveList 扩展;TOKEN_CONN_AUTH 不动 |
server/2015Remote/McpSettingsDlg.cpp/.h |
McpFileTransfer 配置项 |
(P2)server/2015Remote/McpServer.h |
FileTransferSession.tool 增 "upload_file";新增 BeginFileUpload(id)(单设备单传输互斥标记) |
(P2)server/2015Remote/McpServer.cpp |
upload_file schema/实现:无头回调 UploadSendChunkHeadless + CollectLocalFiles 收集 + overwrite 预检(复用 list_files 链路)+ 驱动 FileBatchTransferWorkerV2(复用主连接,无子连接路由) |
(P2)client/KernelManager.cpp |
COMMAND_SEND_FILE_V2 分支加懒初始化 InitFileUpload(g_status 由 0 置 1,见 §7.8) |
(2026-10-27)common/FileTransferV2.h |
POSIX 接收端:发送 FileCompletePacketV2(含流式 SHA-256)、下载失败回 TOKEN_DOWNLOAD_ERROR(errno→Win32 映射);见 §15 |
(2026-10-27)common/sha256_posix.h |
新增:POSIX 侧最小流式 SHA-256(Windows 侧仍走 BCrypt,见 common/VerifyV2.h) |
客户端:UploadToRemoteV2 / RecvFileChunkV2 / FileBatchTransferWorkerV2 均已存在、未改动;仅 COMMAND_SEND_FILE_V2 分支新增懒初始化(见 §7.8)。
10. 分阶段实施与回滚
- P1:
download_file+McpFileTransfer开关 + 路由分支。可独立合入、独立验收(真实主机拖回一个目录,SHA-256 与certutil -hashfile比对一致)。 - P2:
upload_file(§7,主连接复用 + 发送方驱动,MessageHandle零改动)。可独立合入、独立验收(推一个目录到真实主机,SHA-256 与源文件certutil -hashfile比对一致)。 - P3(可选):断点续传(需先验证服务端续传状态落盘;文件管理器侧现
enableResume=false,client/FileManager.cpp:1164)、大文件进度流式上报。 - 回滚:改动集中在
McpServer.*+MessageHandle三个if分支,revert 当期 commit 即可,不影响既有 GUI 文件管理器。
11. 测试点
- 单文件 / 目录(含中文名、深层嵌套)下载;SHA-256 与
certutil -hashfile比对一致。 overwrite=false同名跳过;local_dir不存在自动创建。- 路径穿越:
remote_path含..或 chunk 文件名逃逸local_dir时被拒。 - 大文件(>2GB)超时与断线;并发下载同主机返回
-32003。 - 编码:GBK 中文文件名往返无乱码(与
list_files同规则)。 - 断线收尾:传输中客户端掉线 → 会话擦除 + 半成品删除,无句柄/内存泄漏。
- 上传(P2):单文件 / 目录(含中文名、深层嵌套)上传;
remote_dir不存在自动创建;SHA-256 与源文件certutil -hashfile比对一致。 - 上传
overwrite=false同名跳过(skipped计数);overwrite=true覆盖。 - 上传
remote_dir含..逃逸被拒;大文件(>2GB)超时与断线;并发上传/上传-下载同主机返回-32003。 - 上传编码:GBK 中文文件名往返无乱码。
12. 决策记录(以「简单易用」为原则)
原则:最少开关、最少认知负担、复用既有机制、不为低频场景预留复杂度;只有威胁模型确实需要时才加复杂度。
12.1 download 数据外带 → 不加目录白名单,信任 McpFileTransfer + 审计
- 威胁模型:MCP 默认
127.0.0.1+ token;「数据外带」的实际顾虑是 AI 误操作或提示注入。但一旦开启terminal_exec(全 shell、无白名单),外带通道远大于 download,目录白名单对已开终端者是冗余防御。 - 一致性:
terminal_*/remote_*均只有开关 + 审计、无路径白名单;给 download 单独加白名单是特例,增加解释负担。 - 简单:工具契约保持
id + remote_path + local_dir,不引入「允许根目录」概念。 - 逃生舱:若未来确有需要,复用
McpCmdWhitelist那种单字符串配置作可选收紧项,进 P3,不进 P1。
12.2 大文件模型 → P1 同步 + 大超时,收窄到单文件/已打包目录
- MCP 是 request/response;为一次性传输引入「提交任务 + 轮询进度 + 任务清理」违背「简单 + 每阶段独立可交付」。
- 核心场景(先压缩成单 zip 再拉回)天然是单文件,同步足够;
get_screenshot已先例式地内联返回字节。 - 异步任务模型进 P3,且只在确有超大流式需求时才做,不预建。
12.3 upload 开关 → 单一 McpFileTransfer,upload 复用 McpReadonly=0
download_file=McpFileTransfer=1(不依赖McpReadonly):它只读远程,与list_files/get_screenshot同权,readonly 语义本就只拦「改远程」。upload_file=McpFileTransfer=1 && McpReadonly=0:upload 改远程,复用既有「允许写」主开关,与terminal_*/remote_*的X && !Readonly模式一致。- 只新增 1 个开关;代价是「不能只开 upload 不开 download」——这是可接受的简化(无人有此诉求)。
13. 专家审查记录(实施前)
原则优先级:① 对既有功能影响最小 → ② 简单易用 → ③ 优先 V2。逐条核对了 2015RemoteDlg.cpp 的 MessageHandle 分派、client/FileManager.cpp 与 SimplePlugins/file_upload.cpp 的实现,结论如下:
| # | 审查发现 | 结论 |
|---|---|---|
| F1 | 路由机制比草案更简单:COMMAND_SEND_FILE_V2(5842)/COMMAND_FILE_COMPLETE_V2(6101) 本就按 ContextObject->GetClientID() 分派,流式子连接经 TOKEN_CONN_AUTH(6411 SetID) 钉住 clientID |
无需 context 路由表。改为 device_id 键 + 两个 case 顶部的 IsFileTransferPending(devId) 守卫,TOKEN_CONN_AUTH 完全不动 |
| F2 | 一次性 m_Pending 与新增文件会话可能并发冲突(同 host 双工具) |
BeginFileTransferPending 与 m_Pending 双向互斥,同 host 全 MCP 工具单飞 |
| F3 | 文件管理器子链接发完 CMD_DOWN_FILES_V2 后即无用(数据走新流式子连接) |
OnDriveList 发完命令即 CancelIO 该子链接;客户端 UploadToRemoteV2 用独立 IOCPClient,不依赖它 |
| F4 | 完成信号是每文件一个 COMMAND_FILE_COMPLETE_V2(FileCompletePacketV2.fileIndex) |
会话记 totalFiles(首 chunk)/filesDone(complete 计数),filesDone==totalFiles 才算 done |
| F5 | RecvFileChunkV2 内部直接按 chunk filename 落盘 |
MCP 在调用前校验 filename 规范化仍在 local_dir 内,逃逸即取消传输 |
| F6 | RecvFileChunkV2 需正确 hash/hmac |
镜像 FileManagerDlg.cpp:2755 的 GetPwdHash()/GetHMAC(100);客户端 M2C hmac 为空(FileManager.cpp:1167) |
| F7 | 三处改动均为「加 if 守卫 + 现有逻辑作 else」,C2C 分支不动 | 结构性满足原则 #1,对既有 GUI/C2C 零影响 |
判定:7 项问题均已在正文对应章节修正,无阻塞项,定稿。
13.1 upload_file 评审记录(P2,实施前)
核对了 2015RemoteDlg.cpp 的 SendFilesToClientV2Internal/SendFileChunkToClientV2(GUI upload 发送方)、SimplePlugins/file_upload.cpp 的 FileBatchTransferWorkerV2/RecvFileChunkV2、client/KernelManager.cpp:1381 的接收分支,结论:
| # | 审查发现 | 结论 |
|---|---|---|
| U1 | 旧稿「服务端等客户端回 COMMAND_FILE_COMPLETE_V2」方向写反 |
COMPLETE 恒由发送方发、接收方 HandleFileCompleteV2 校验,无 ACK 回传。upload 服务端是发送方 → 发 COMPLETE,不是「等」 |
| U2 | upload 走主连接(ctx->Send2Client),不像 download 要客户端新开鉴权流式子连接 |
MessageHandle 零改动;无需 IsFileTransferPending 路由守卫、无需 OnFileCompleteV2 收包计数 |
| U3 | 复用 FileBatchTransferWorkerV2 时回调需无头版 |
镜像 GUI SendFileChunkToClientV2 去掉 dlg 进度,m_parent->FindHost(clientID) 定位 ctx;离线返回 false 中止 |
| U4 | 完成判定无接收方回执 | result==0 && FindHost(clientID)!=nullptr(与 GUI SendFilesToClientV2Internal 末尾一致);output.sha256 恒为空串,非接收方验真(见 §7.5) |
| U5 | overwrite=false 需预知远程同名文件 |
复用 list_files 的 COMMAND_LIST_DRIVE→TOKEN_DRIVE_LIST 预检 remote_dir,过滤同名进 skipped |
| U6 | 本地文件收集 | common/file_upload.cpp:38 ExpandDirectories 未在 file_upload.h 导出,改为 McpServer.cpp 本地 CollectLocalFiles 同构实现(目录项在前、子项随后) |
| U7 | 实施验证发现:客户端主连接 g_status==0,RecvFileChunkV2 逐 chunk return -1(上传落盘 0 字节/截断) |
客户端 COMMAND_SEND_FILE_V2 分支加懒初始化(§7.8):static 一次 + 永久引用计数、析构不 Uninit;与 FileManager.cpp:40 参数一致,独立评审确认无稳定性风险 |
判定:7 项均已写入 §7 对应小节,无阻塞项,定稿。
13.2 实施后修复记录(2026-10-25)
| # | 问题 | 修复 |
|---|---|---|
| R1 | 纯目录树下载必超时:完成判定 filesDone >= totalFiles - directoryCount 只在 OnFileCompleteV2 里跑,而客户端对目录项不发 COMMAND_FILE_COMPLETE_V2。空目录/只有子目录的树期望文件数为 0,永远等不到 COMPLETE → 只能干等 timeout_ms(默认 600s)后报 1002 |
OnFileChunkV2 的目录分支里,directoryCount >= totalFiles(即全部条目都是目录)时直接置 done + notify。实测空目录 0.2s 返回、3 文件目录树回归正常 |
| R2 | 断线无清理 → 悬空子连接指针:FileTransferSession.fmSubCtx / streamSubCtx 是裸 context*,OfflineProc 只清了终端/远程控制/聊天,没有文件传输的钩子(§6.5 声称的「断线擦会话」实现缺失)。客户端传输中掉线后 connection 被连接池回收,工具线程超时路径仍对其 CancelIO() → 悬空指针/误取消他人连接 |
新增 m_FileXferContextToDevice 反查表(受 m_FileXferMutex 保护,ClearFileTransfer 同步擦除),OfflineProc 增 OnFileTransferContextClosed:清指针并移除反查项;流式子连接断开即判失败(error=1003,立即唤醒工具线程),文件管理器子连接断开只清指针(数据走流式子连接,不判失败)。实测传输中杀掉客户端:1s 返回 Connection lost(原来要等满 timeout_ms),服务端存活;重启客户端后连续两次下载、一次上传均正常 |
14. 增补(2026-10-26):C2C 直传 copy_files_c2c
14.1 动机
运维里经常要在两台客户端之间拷文件。此前的变通流程是「download_file 拉到主控本机 → upload_file 再推上去」,数据在服务端磁盘上落一遍、两倍耗时。文件传输 V2 本身已经支持 C2C:FileChunkPacketV2.dstClientID != 0 时,服务端把包原样中继给目标客户端,目标端在自己的主连接上 RecvFileChunkV2 落盘,服务端不解析、不落盘。
但客户端现有的 C2C 入口只有一个 COMMAND_CLIPBOARD_V2(Ctrl+V),文件来源固定是本端剪贴板/资源管理器选中项,服务端无法指定路径。因此新增一条「服务端给源端一份显式路径清单」的命令。
14.2 协议(common/commands.h / common/file_upload.h)
CLIENT_CAP_C2C_PATHS 0x0008 // LOGIN_INFOR 能力位,仅 Windows 客户端置位(源端)
CLIENT_CAP_C2C_RECV_ACK 0x0010 // 作为目标端会回执落盘结果,目前仅 Linux 客户端置位(macOS 不置位)
COMMAND_C2C_SEND_FILES = 174, // 服务端 → 源客户端主连接
TOKEN_C2C_SEND_RESULT = 175, // 源客户端 → 服务端(源端自开的传输子连接上)
TOKEN_C2C_RECV_RESULT = 176, // 目标客户端 → 服务端(目标端主连接上)
| 包 | 布局 | 说明 |
|---|---|---|
C2CSendFilesPacket |
cmd(1) transferID(8) srcClientID(8) dstClientID(8) hash(64) hmac(16) flags(1) = 106 B |
后接 dst_dir\0,再是 path1\0 … pathN\0,以额外一个 \0 结束(ANSI/936) |
C2CSendResultPacket |
cmd(1) transferID(8) dstClientID(8) status(4) win32err(4) workerRc(4) fileCount(4) totalBytes(8) = 41 B(#pragma pack(1)) |
175:status 0=全部发出、FEV2_FILE_NOT_FOUND/FEV2_ACCESS_DENIED(带首个 win32 码)、1001=发送线程失败(看 workerRc)。176:status 0=全部落盘成功,否则为映射后的 FEV2_*;win32err 位置放首个 errno;workerRc 恒 0 |
老客户端不认识 174(服务端按 CLIENT_CAP_C2C_PATHS 提前拒绝,-32005 提示升级);老服务端不认识 175/176,走 default 丢弃,无兼容风险。回执用独立的 176而不是复用 175:同一台主机可能同时是 A 传输的目标端和 B 传输的源端,复用会让服务端把回执误当成源端结果去 latch done。
14.3 客户端(client/KernelManager.cpp)
OnC2CSendFiles:解析dst_dir与路径清单 →ExpandEnvironmentStringsA展开%VAR%→ 目录按CollectFilesRecursiveV2同语义递归展开,且目录项本身也入列(目标端据此建空目录)→ 统计fileCount/totalBytes。EnsureV2TransferInited():FileBatchTransferWorkerV2依赖进程级的InitFileUpload(g_status==1),否则直接返回 -1。源端可能从未打开文件管理器、也没接收过上传,所以发送前显式初始化;与接收分支共用同一份static一次性初始化(InitFileUpload/UninitFileUpload成对,重复 Init 会重置状态)。- 新开一个
EnableSubConnAuth()的子连接 →FileBatchTransferWorkerV2(files, targetDir=dst_dir, …, opts{dstClientID=dst, enableResume=false}),回调即Send2Server。子连接经TOKEN_CONN_AUTH校验后,服务端把它钉成源主连接的 clientID。 - 发送结束后在同一条子连接上回
C2CSendResultPacket,然后关闭子连接。任何早退分支(路径非法/全部不可访问/连不上服务端)都先回一包结果——否则工具侧只能干等超时。
14.4 服务端
- 会话:
BeginC2CTransfer(src, dst, transferID)把会话键在源设备上(tool="copy_files_c2c"、dstClientID),与m_Pending、目标端文件会话双向互斥;WaitC2CDone只等源端那包结果,没有停滞看门狗(源端全程只在最后回一包,大文件中途静默是正常的),只有总超时。 - 中继:完全复用
COMMAND_SEND_FILE_V2/COMMAND_FILE_COMPLETE_V2的dstClientID != 0分支,零改动。 - 必须抑制源端的进度对话框(实施中踩到的坑):该分支原本会在源端子连接上挂一个
CDlgFileSend显示进度。而NotifyProc对挂了hDlg的连接会把后续包交给对话框的OnReceiveComplete——源端最后那包 175 就被当成 V1 文件块解析(服务端 trace 里是RecvFileChunk failed: 3),MCP 侧只会超时。现在用IsC2CTransferPending(src, dst)判定:MCP 发起的 C2C 不建对话框,包照常落到MessageHandle;MFC 手动 C2C(Ctrl+V / 文件管理器)行为完全不变。 - 落盘位置:目标端收到的目录是
dst_dir,文件名取各路径相对公共父目录的部分(库内GetCommonRoot语义)。例如发D:\data\a.txt与D:\data\sub\,目标是C:\backup,则得到C:\backup\a.txt、C:\backup\sub\b.bin;dst_dir不存在时由接收端自动创建。- Windows 目标:
dst_dir必须是绝对 Windows 路径(C:\backup),服务端补尾部\后交给源端拼接。 - Linux/macOS 目标:
dst_dir必须是绝对 POSIX 路径(/home/user/incoming、/tmp/recv),不得含\。源端仍然只是把dst_dir与相对路径纯字符串拼接(targetDir + relPath,库内不经过任何 Windows 路径 API),因此得到"/tmp/recv\sub\b.bin";POSIX 接收端GetTargetDir()为空时会把\归一化成/、去盘符、补前导/再MakeDirs,正好落到/tmp/recv/sub/b.bin。这条路径不需要改 Windows 客户端。 - 目标端类型来自
RES_CLIENT_TYPE(LNX/MAC视为 POSIX),服务端在建会话前校验形态,不合法直接-32602。
- Windows 目标:
- 目标端回执:目标端声明
CLIENT_CAP_C2C_RECV_ACK(当前只有 Linux)时,服务端在源端结果之后再WaitC2CReceiver(≤5 s,250 ms 切片)等一包 176;没有该能力位的目标端(Windows、macOS、老客户端)直接跳过,不增加任何延迟。回执状态记在FileTransferSession的recv*字段,与源端的done/status互不覆盖。
14.5 工具契约
入参:src_id、dst_id(必填,且不得相同)、paths(必填,文件或目录,1..N,源端 Windows 绝对路径)、dst_dir(必填,绝对路径;Windows 目标用 C:\x,Linux/macOS 目标用 /x)、timeout_ms(默认 600000,上限 3600000)、overwrite(默认 false,见 §14.9)。
出参(structuredContent):transfer_id、src_id、dst_id、dst_dir、file_count、total_bytes、receiver_ack、skipped、skip_check_failed。
receiver_ack 三种取值:
true且status==0:目标端已确认全部条目落盘(file_count/total_bytes是目标端实收值,与源端统计一致)。false:目标端不支持回执(Windows/macOS/老客户端),或目标端中途断线——源端只保证「包已全部发出」,请用list_files复核。- 目标端回执报错时工具不返回
structuredContent,而是下面的-32011错误。
| 码 | 触发 |
|---|---|
-32602 |
缺参 / id 非法 / 源目标相同 / paths、dst_dir 含 .. 段或内嵌 NUL / 编码无法转 936 / POSIX 目标的 dst_dir 不是绝对 /… 或含 \ |
-32002 |
源或目标主机不在线 |
-32003 |
源或目标已有在飞传输(单设备单传输) |
-32004 |
命令下发失败 |
-32005 |
源端是老客户端(无 CLIENT_CAP_C2C_PATHS)、或源端是 Linux/macOS(目标端可以是 Linux/macOS) |
-32006 |
McpFileTransfer=0 或 McpReadonly=1(改远程);任一端不支持 V2 |
-32009 / -32010 |
源端路径不存在(win32 2/3)/ 拒绝访问(win32 5) |
-32011 |
目标端写入失败:收到 176 回执且 status != 0;文案带 status、首个 errno(13/1→权限、2→路径不存在、28→磁盘满)与实收文件数 |
-32001 |
等源端结果超时(传输可能仍在进行);或支持回执的目标端在源端完成后 5 s 内没有回执(对 total_bytes>0 的传输才判失败;全空文件传输没有数据块、目标端无从学到 totalFiles,按无回执处理) |
14.6 限制
- 回执只覆盖 Linux 目标端:Windows 目标端(V2 接收实现里没有回执通道)与 macOS(
macos/main.mm的客户端对象是函数内局部变量,没有全局主连接句柄)仍是receiver_ack:false,只能确认「包已全部发出」,要确认落盘请用list_files核对目标端。 - 不做断点续传(
enableResume=false):C2C 的续传查询/应答会多两跳,v1 从简;失败即整包重发。 - 源端必须是 Windows 客户端(
CLIENT_CAP_C2C_PATHS只有 Windows 置位);目标端可以是 Windows / Linux / macOS。 - POSIX 目标的路径限制:
dst_dir与文件名的 UTF-8 → ANSI 转换固定用 CP936(协议字段没有编码标志位),GBK 无法表示的字符(如ö、ß)会变成?;POSIX 目标的dst_dir必须是绝对/…且不含\;Linux 侧文件名按收到的字节原样落盘(大多是 GBK 字节),在 UTF-8 环境里ls会显示为乱码但内容与 SHA-256 正确。要根治需要为 V2 名字字段引入 UTF-8 标志位,本次不做。 - 空文件不会被创建(协议现状,与目标端类型无关):worker 对 0 字节文件不发数据块,只发
FileCompletePacketV2,接收端没有对应分支去open(O_CREAT)。空目录会创建。 - 一次只允许一对主机间的单个传输(源、目标各自都要求空闲),避免与
download_file/upload_file抢同一主机的连接。
14.7 验证(Debug 实例 + 两个 Debug 客户端副本,同一台机器不同目录 → 不同 client_id)
数据确实走「源客户端子连接 → 服务端中继 → 目标客户端主连接」:
| 用例 | 结果 |
|---|---|
| 发 2 个文件(其一中文名)+ 1 个目录(含 3 MB 二进制与空子目录) | 3 个文件 SHA-256 全对,空目录被创建,file_count=3、耗时 3.2s |
dst_dir 不存在(…\recv\fresh\nested) |
自动创建,文件到位 |
src_id == dst_id / 源路径不存在 / 目标离线 / dst_dir 含 .. |
-32602 / -32009(win32=3) / -32002 / -32602 |
tools/mcp_smoke.ps1(含主机类工具,41 项) |
全通过;新增 copy_files_c2c 同主机 -32602、目标离线 -32002 两项 |
14.8 增补(2026-10-27):Linux 作为目标端 + 落盘回执
改动面:服务端门禁按目标端类型校验 dst_dir(§14.4);Linux 接收端 common/FileTransferV2.h 统计每个
transferID 的定案条目,全部定案后从主连接回一包 TOKEN_C2C_RECV_RESULT(176);服务端新增
OnC2CRecvResult / WaitC2CReceiver,在源端结果之后等回执并把它变成 receiver_ack 或 -32011。
接收端记账要点(都在 FileTransferV2.h 的 RecvProgress 里):
- 条目定案有三个来源:目录项包(
FFV2_DIRECTORY,无 LAST_CHUNK)、最后一块数据、空文件的完成包; 源端重发(最多 3 次)与「最后一块 + 完成包」都会重复命中同一fileIndex,用doneFiles/doneDirs去重。 totalFiles只能从数据块/目录包学到(FileCompletePacketV2没有该字段);目录项也计入totalFiles, 所以判据是doneFiles + doneDirs >= totalFiles。errno只在失败瞬间有效,open 失败处紧接着就有Mprintf,因此在失败点立刻取值再传递;fstat复核最终大小,大小不符记EIO。- 回执在锁外发送;
reply->IsConnected()失败只记日志,不影响已落盘的文件。
验证(Debug 实例 6543/6546,WSL Ubuntu 24.04 里新编译的 linux/ghost 以 yuan(1000) 运行):
| 用例 | 结果 |
|---|---|
Windows → Linux,dst_dir=/tmp/yama_c2c/recv,2 个文件(其一中文名)+ 目录(含 3 MB 二进制与空子目录) |
3 个文件 SHA-256 全对、sub/empty 空目录已建,receiver_ack:true、file_count=3、total_bytes=3147539(与源端一致),耗时 3.2 s |
dst_dir=/tmp/yama_c2c/fresh/nested(不存在) |
自动创建,receiver_ack:true |
POSIX 目标给 dst_dir=C:\tmp\x |
-32602 "use an absolute POSIX path such as /home/user/incoming" |
POSIX 目标给不可写位置 /proc/yama_c2c |
-32011 "no such file or directory (status=3, errno=2, files=1)" |
| 只发一个 0 字节文件 | 成功返回、receiver_ack:false(无数据块 → 接收端学不到 totalFiles → 不回执),不误报 -32001 |
| 只发一个空目录 | 目录包携带 totalFiles → 回执到达,receiver_ack:true、file_count=0,目录已创建 |
| Windows → Windows 回归(原 c2c_test 用例) | 全部与改动前一致,receiver_ack:false,耗时 3.2 s(未增加等待) |
upload_file/download_file(dstClientID=0) |
不进回执分支(FinishC2CItem 首行即 dstClientID==0 返回),行为不变 |
15. 增补(2026-10-27):download_file / upload_file 支持 Linux/macOS 主机
§6/§7 的原始实现只允许 Windows 目标端(LNX/MAC 直接 -32005)。本次打通:
upload_file(主控 → 目标端):不需要客户端新指令。POSIX 接收端本来就实现了COMMAND_SEND_FILE_V2(common/FileTransferV2.h),dstClientID != 0的包按 C2C 语义处理,目标目录由包里的 name 派生 (§14.4 的 POSIX 规则)。服务端只放开门禁 + 按目标端类型校验remote_dir形态。download_file(目标端 → 主控):走客户端文件管理器子连接的CMD_DOWN_FILES_V2,Linux/macOS 的 文件管理器在common/FileManager.h里(与 Windowsclient/FileManager.cpp同构)。缺的两块在 POSIX 接收侧补齐:
15.1 接收端改动(common/FileTransferV2.h,Linux 与 macOS 共用)
- 发送
FileCompletePacketV2(SendFilesV2每个文件末尾):cmd(1) transferID(8) srcClientID(8) dstClientID(8) fileIndex(4) fileSize(8) sha256(32),SHA-256 边读边算(新增common/sha256_posix.h, 自包含流式实现;Windows 侧继续用 BCrypt)。服务端OnFileCompleteV2凭它计filesDone并校验摘要—— 没有它 MCP 的下载会话永远等不到完成判定。- 读失败 / 文件在传输中被截断(短读):仍把末块发出去,但不发完成包(不谎报校验通过),服务端按
fileSize收不全而失败。 - 发送失败(
Send2Server返回 false)同样不发完成包。
- 读失败 / 文件在传输中被截断(短读):仍把末块发出去,但不发完成包(不谎报校验通过),服务端按
- 下载失败回
TOKEN_DOWNLOAD_ERROR:[cmd:1][win32err:4 LE],与 WindowsCFileManager::SendDownloadError一致。触发点:remote_paths为空(win32 87)、所有路径 stat 失败 / 展开后无文件(首个 errno 映射ENOENT/ENOTDIR→2/3、EACCES/EPERM→5,其余→2)。服务端据此立即失败,不用等停滞看门狗。
15.2 服务端改动(server/2015Remote/McpServer.cpp)
BuildDownloadFile/BuildUploadFile:RES_CLIENT_TYPE为LNX/MAC时按 POSIX 校验路径: 必须以/开头、不得含\(会被客户端WinPathToLinux归一化成/,语义会漂)、不得含..段, 否则-32602并给出示例;upload_file的remote_dir单独给/是合法的(写到根目录,通常因权限回-32011)。 Windows 目标端行为与之前逐字节一致。BeginFileUpload(device_id, transfer_id)现在登记dstClientID/transferID,OnC2CRecvResult同时匹配copy_files_c2c与upload_file的会话(键分别是源端与目标端,都用dstClientID + transferID定位)。upload_file因此也能拿到真实回执:Linux 目标端声明CLIENT_CAP_C2C_RECV_ACK,发送完成后等 ≤5 s,receiver_ack参与输出。- 空文件(仅 POSIX 目标):
FileBatchTransferWorkerV2对 0 字节文件不发数据块,只发完成包,而完成包 没有路径字段,POSIX 接收端无从建文件(会「回执成功但文件不存在」)。服务端在驱动 worker 前,为每个 0 字节文件补一个长度 0 的FFV2_LAST_CHUNK块(名字拼法与 worker 一致:targetDir + relPath), 接收端据此open(O_CREAT);随后 worker 的完成包只用于去重。Windows 目标端不注入——保持原有行为 (Windows 目标端的空文件仍不会被创建,属 V2 协议既有边界,见 §14.6)。 - 下载完成判定(F4 的补强):条目顺序由客户端决定,目录可能排在最后(如空子目录),所以
OnFileChunkV2的目录分支现在按filesDone + directoryCount >= totalFiles判完成。此前只比目录数, 目录排在文件之后时整次下载会干等到超时(实测 4 个文件全部 COMPLETE 后仍卡 60 s)。
15.3 工具契约变化
| 工具 | 变化 |
|---|---|
download_file |
支持 LNX/MAC 目标端(remote_path 用绝对 POSIX 路径);新增错误来源 -32009/-32010(来自客户端 TOKEN_DOWNLOAD_ERROR) |
upload_file |
支持 LNX/MAC 目标端(remote_dir 用绝对 POSIX 路径);输出新增 receiver_ack(boolean);新增 -32011(目标端回执报写入失败)与 -32001(声明会回执却不回,且传输含字节) |
upload_file 的错误补充(其余码与 §7.7 一致):
| 码 | 触发 |
|---|---|
-32011 |
目标端回了 176 且 status != 0;文案带 status、首个 errno、实收文件数(13/1→权限、2→路径不存在、28→磁盘满) |
-32001 |
传输完成但支持回执的目标端在 5 s 内没有回执(目标端可能中途掉线);全 0 字节的传输不判失败(接收端学不到 totalFiles,无从回执) |
receiver_ack 语义与 §14.5 一致:true 只可能来自 Linux 目标端;Windows 目标与 macOS 目标恒为 false
(macOS 编译侧 macos/main.mm 没有全局主连接句柄,本次未接线),要确证落盘请用 list_files 复核。
15.4 验证(Debug 实例 6543/6546,WSL Ubuntu 24.04 的 linux/ghost 以 yuan(1000) 运行)
源目录含:a.txt(12 B)、empty.txt(0 B)、sub/b.bin(3 MB)、emptydir/、中文名.txt(14 B)。
| 用例 | 结果 |
|---|---|
upload_file → /tmp/yama_mcp/final |
4 文件 + 空目录到位,SHA-256 全对(ddda4069…/e3b0c442…/834dcf1d…/b2a71864…),receiver_ack:true,total_bytes=3145754 |
同上 overwrite=false 重传 |
全部跳过(skipped=4),不发包 |
download_file 整目录 |
4 文件 + 空目录,SHA-256 全对,total_bytes=3145754 |
| 单文件 / 单文件中文名 / 只含空子目录的目录 | 均成功(后者 0.2 s 级返回,不再等超时) |
download_file 不存在的路径 |
-32009(errno 2 → win32 2) |
remote_path 给 C:\tmp\x 或含 .. |
-32602 |
upload_file 到 / 或 /root/yama_x(非 root) |
-32011(errno 13/2) |
Windows 目标端 upload_file / download_file / copy_files_c2c 回归 |
与改动前一致(Windows 目标的空文件仍不落地,receiver_ack 仍为 false) |
注:WSL 重启后 Linux 客户端的 machine-id 会变,id 随之改变,测试脚本以运行时 list_online_hosts 为准。
14.9 增补(2026-10-29):overwrite 与 skipped
14.9.1 问题(实测)
同一份文件连续 C2C 两次,目标端 mtime 从 1793276750 变为 1793276909(重写),大小不变、
条目数不变 —— 即每次都全量重发。更麻烦的是两次返回值完全相同:
第一次: file_count=1, total_bytes=11595168, receiver_ack=true
第二次: file_count=1, total_bytes=11595168, receiver_ack=true
调用方无法分辨「这次真的传了」还是「跳过了」。upload_file / download_file 有 overwrite +
skipped,只有 C2C 缺这一对。
14.9.2 做法(纯服务端,协议零改动)
目标端收包是无条件覆盖写(RecvFileChunkV2 不判断是否存在),所以跳过只能在服务端做:
发起传输前先列一次目标目录,把重名的顶层项从 paths 里剔掉。协议、客户端一律不动。
overwrite=false(默认)时,调用ListRemoteTopLevelNames(upload_file已在用的同一个 helper,McpServer.cpp)列dst_dir一层;- 逐个
paths取 basename,与目标端已有名字比对:Windows 目标不区分大小写,POSIX 目标区分 (为此给 helper 加了foldCase参数,默认true保持upload_file行为不变); - 命中的路径剔除并计入
skipped;全被剔除则直接返回成功,不发起传输、不建 transferID; - 目标目录不存在时 helper 返回空集(
ERROR_FILE_NOT_FOUND/ERROR_PATH_NOT_FOUND视为空), 正好等价于「无同名项」,不会挡住「传到新目录」; - 预检失败不报错:预检本身失败时退回「全量发送」,并置
skip_check_failed=true。 不能让一次检查失败把本该成功的传输挡掉——这是与upload_file不同的取舍 (upload_file在预检失败时直接-32001失败)。 注意这个 fallback 的实际可达范围很窄:目标主机被在飞传输或别的工具占用时,预检确实 失败,但紧接着的BeginC2CTransfer也查同一套m_Pending/m_FileXferSessions互斥, 会直接返回-32003,根本走不到「全量发送」那一步(见 §14.9.5)。真正能置位的只有 「列举超时或异常,而设备此刻空闲」。
dst_dir 传给 helper 时用不带尾分隔符的形态(dstDirListAnsi):客户端拼 "%s\*.*",
带尾分隔符会拼成 C://*.* 让 FindFirstFile 失败,与 search_file 踩过的是同一个坑。
14.9.3 契约
| 字段 | 语义 |
|---|---|
overwrite(入参,bool,默认 false) |
false:目标目录已有同名顶层项则跳过;true:维持旧行为,无条件重发 |
skipped(出参,int) |
本次因已存在而跳过的顶层项数;overwrite=true 时恒为 0 |
skip_check_failed(出参,bool) |
true 表示没能预检目标目录(主机忙/超时/拒绝访问),本次按全量发送,skipped 不可信 |
14.9.4 验证
服务端重建并重启后(exe_build_time=2026-10-29 14:34:33,PID 12160)实测:
| 用例 | 结果 |
|---|---|
1. 同一文件连传两次,第二次 overwrite=false |
通过:file_count=0、skipped=1、transfer_id=""、skip_check_failed=false,目标端 mtime 不变 |
2. overwrite=true 重传 |
通过:file_count=1、skipped=0,目标端 mtime 1793276909 → 1793281657(推进 4748 s),条目数不变 |
| 3. 传到不存在的新目录 | 通过:目录自动创建,单文件落成 <dst_dir>/<basename>(如 /home/shaun/c2c_probe3/settings.ini) |
| 4. 目标主机被别的工具占住(在飞) | 不可按原描述构造:返回 -32003 而不是「全量发送 + skip_check_failed=true」,详见 §14.9.5 |
| 5. Windows 目标 + 大小写不同的同名文件 | 通过:目标 C:\Temp\c2c_case5 预置 SETTINGS.INI(23 B),传 settings.ini → skipped=1、file_count=0、transfer_id="",目录内仍只有 SETTINGS.INI |
6. Linux 目标 + SETTINGS.INI vs settings.ini |
通过:目标 /home/shaun/c2c_case6 预置 SETTINGS.INI(23 B),传 settings.ini → skipped=0、file_count=1,两个文件并存(23 B 与 1528 B) |
用例 1、2、3 的目标端是 Ubuntu 24.04(ubuntu-24 / Ubuntu24),源端是 Windows 11(IOU-Station);
用例 5 的目标端是 Windows 11(MS084)。
14.9.5 用例 4 的期望不成立(实测)
原用例假设「目标主机被别的工具占住 → 预检失败 → 仍能传完,skip_check_failed=true」。实测两条
路径都走不到那个结果:
- 占住目标(后台
download_file一份 17 MB 日志,随即发起 C2C):返回-32003 Device busy: source or destination host already has a transfer in flight。 原因是BeginC2CTransfer(McpServer.cpp)除了查自己的m_FileXferSessions,还查src_id/dst_id的m_Pending——与预检BeginPending的互斥条件是同一套。预检失败后 落到它这里仍然被拒,skip_check_failed因此不可观测。 - 让列举失败但写入成功(
chmod 333,可写不可读):预检没有失败。Linux 客户端把EACCES当成「目录里没有条目」上报(不是TOKEN_FILE_LIST_ERROR),服务端于是skip_check_failed=false、skipped=0,随后照常覆盖写,文件确实写进了 1528 字节。 即这一路是 fail-open:列不出来的目录,overwrite=false不会保护其中已有的同名文件。
因此 skip_check_failed 现在只作为「列举超时/异常且设备空闲」的兜底存在,难以稳定构造,
字段保留。若要真正验证它,需要让 WaitPending 超时(例如临时挂起客户端进程),代价是可能
把主机判成离线,本轮没有做。
14.9.6 一次误报的复盘(重要,避免重犯)
本轮曾判定「单文件 C2C 落盘会多出 C:/… 目录树,只有目录/多文件正常」,并据此在
common/FileTransferV2.h 里加了一段接收端路径加固。该结论是错的,加固已还原。
根因是自制的 JSON-RPC 直连测试脚本:为了绕过连接器缓存的 tools/list(它还没有
overwrite 字段),脚本用命令行参数传 JSON,而命令行传递层会把 \\ 折成 \/,
于是 Python 解析出来的路径已经是 C://ProgramData//HTS//…(双正斜杠)。源端拿到一条
没有任何反斜杠的路径后,GetRelativePath 的 basename 兜底用 find_last_of('\\') 找分隔符,
找不到就把整条绝对路径当相对路径返回 —— 于是落盘成 <dst_dir>/C:/ProgramData/…。
也就是说:缺陷在测试工具里,不在产品里。 同一个文件、同一个 dst_dir,用连接器
(标准 JSON 转义)调用时源端发出的名字是干净的 /home/shaun/c2c_probe3/settings.ini。
教训:
- 传含反斜杠的路径给自测脚本时,必须走文件或 stdin,不要走命令行参数;
- 判定「产品有 bug」之前,先用真实 MCP 客户端复现一次,别只信自建 harness;
- 中继侧/接收侧的日志只能证明「收到的字节是什么」,不能证明「上游是谁写坏的」。