diff --git a/mcp/tools.json b/mcp/tools.json index bd3456d..c1decc8 100644 --- a/mcp/tools.json +++ b/mcp/tools.json @@ -2190,7 +2190,7 @@ }, { "name": "terminal_open", - "description": "在指定在线 Windows、Linux 或 Android 主机上打开一个持久 shell 会话并返回 session_id 与终端模式。后续 terminal_exec 复用该会话(cwd/环境变量跨命令保持),用毕须 terminal_close。Linux/Android 使用 POSIX PTY(UTF-8,is_pty=true),Android 的 shell 是 /system/bin/sh(mksh)。", + "description": "在指定在线 Windows、Linux 或 Android 主机上打开一个持久 shell 会话并返回 session_id 与终端模式。后续 terminal_exec 复用该会话(cwd/环境变量跨命令保持),用毕须 terminal_close。若该主机已有持久会话(包括 terminal_exec 隐式创建的),直接复用并返回 reused:true,不会报 -32003。Linux/Android 使用 POSIX PTY(UTF-8,is_pty=true),Android 的 shell 是 /system/bin/sh(mksh)。", "gate": "terminal", "write": true, "platforms": [ @@ -2221,6 +2221,10 @@ "description": "true=PTY(UTF-8)(Windows ConPTY / Linux PTY);false=老 cmd 管道(GBK)", "type": "boolean" }, + "reused": { + "description": "true=该主机已有持久会话,本次直接复用(未新建);false=本次新建", + "type": "boolean" + }, "session_id": { "description": "持久会话 token,后续 terminal_exec / terminal_close 用", "type": "string" @@ -2235,7 +2239,7 @@ }, { "name": "terminal_exec", - "description": "在已打开的持久会话中执行一条命令,或轮询取回正在运行的命令输出。带 command 时执行并在 timeout_ms 内等待;等待超时返回 done:false 与已产生的部分输出,会话不销毁(命令仍在远端运行)。不带 command、只传 session_id 时进入轮询模式:继续等待并取回增量输出,直到 done:true(此时有 exit_code)。命令不受白名单约束。PTY 会话(新 Windows 客户端 ConPTY / Linux 与新版 Android 的 POSIX PTY)下可用管道 | 与 && / || 串联,退出码取整条管道/串联,适合「ls -1 | wc -l」这类先过滤再回传的用法;不要用后台执行符 &(POSIX)或换行。老非 PTY Windows 客户端仍不支持 & 与 |,请拆成多条调用。", + "description": "在已打开的持久会话中执行一条命令,或轮询取回正在运行的命令输出。带 command 时执行并在 timeout_ms 内等待;等待超时返回 done:false 与已产生的部分输出,会话不销毁(命令仍在远端运行)。session_id 可省略:自动复用该主机已有的持久会话,没有就隐式打开一个(结果里有 session_id 与 reused),不必先 terminal_open。不带 command、只传 session_id 时进入轮询模式:继续等待并取回增量输出,直到 done:true(此时有 exit_code)。命令不受白名单约束。PTY 会话(新 Windows 客户端 ConPTY / Linux 与新版 Android 的 POSIX PTY)下可用管道 | 与 && / || 串联,退出码取整条管道/串联,适合「ls -1 | wc -l」这类先过滤再回传的用法;不要用后台执行符 &(POSIX)或换行。老非 PTY Windows 客户端仍不支持 & 与 |,请拆成多条调用。", "gate": "terminal", "write": true, "platforms": [ @@ -2259,7 +2263,7 @@ "type": "integer" }, "session_id": { - "description": "terminal_open 返回的 session_id", + "description": "会话 token。带 command 时可省略:自动复用该主机已有的持久会话,没有就在内部打开一个(结果里有 session_id 与 reused)。轮询模式必须提供", "type": "string" }, "timeout_ms": { @@ -2268,8 +2272,7 @@ } }, "required": [ - "id", - "session_id" + "id" ], "type": "object" }, @@ -2291,6 +2294,14 @@ "description": "退出码(done=true 时提供):PTY 客户端(Windows ConPTY / Linux PTY)为命令的真实退出码;老客户端(非 PTY)仅区分 0/非 0;-1=未知(shell 进程退出)", "type": "integer" }, + "is_pty": { + "description": "true=PTY(UTF-8)(Windows ConPTY / Linux PTY);false=老 cmd 管道(GBK)", + "type": "boolean" + }, + "reused": { + "description": "true=复用了该主机已有的持久会话;false=本次隐式新建(省略 session_id 时)", + "type": "boolean" + }, "session_id": { "description": "会话 token,原样回传,便于续接轮询", "type": "string" diff --git a/server/2015Remote/McpServer.cpp b/server/2015Remote/McpServer.cpp index 5d16468..c285fa0 100644 --- a/server/2015Remote/McpServer.cpp +++ b/server/2015Remote/McpServer.cpp @@ -324,7 +324,9 @@ const char* kServerInstructions = u8"remote_mouse / remote_keyboard 用归一化坐标(0..1)操作 → 必须 remote_close 释放会话,闲置会话会被回收。" u8"要防止真人操作打断自动化时用 remote_block_input 锁定对端键鼠(Windows/Android;必须带 max_block_ms,到期自动解除;" u8"客户端无管理员权限时 Windows 会让 BlockInput 静默失败,成功只代表命令已送达)。\n" - u8"命令执行:exec_command 一次性取输出;需要保持 cd 或环境变量时用 terminal_open + terminal_exec,用毕 terminal_close。\n" + u8"命令执行:exec_command 一次性取输出(受白名单约束)。terminal_exec 无需先 terminal_open:带 command 时" + u8"自动复用或创建该主机的持久会话(cwd/环境变量跨命令保持,闲置 300 秒回收),结果里带回 session_id," + u8"后续轮询用它;只有需要显式管理会话时才用 terminal_open / terminal_close。\n" u8"\n" u8"5) 客户端平台差异\n" u8"工具能否执行取决于目标主机的平台,这与服务端开关无关,两者是叠加关系。调用前用 " @@ -2501,7 +2503,7 @@ std::string BuildToolsListResult(const Json::Value& id) { { Json::Value tool(Json::objectValue); tool["name"] = "terminal_open"; - tool["description"] = u8"在指定在线 Windows、Linux 或 Android 主机上打开一个持久 shell 会话并返回 session_id 与终端模式。后续 terminal_exec 复用该会话(cwd/环境变量跨命令保持),用毕须 terminal_close。Linux/Android 使用 POSIX PTY(UTF-8,is_pty=true),Android 的 shell 是 /system/bin/sh(mksh)。"; + tool["description"] = u8"在指定在线 Windows、Linux 或 Android 主机上打开一个持久 shell 会话并返回 session_id 与终端模式。后续 terminal_exec 复用该会话(cwd/环境变量跨命令保持),用毕须 terminal_close。若该主机已有持久会话(包括 terminal_exec 隐式创建的),直接复用并返回 reused:true,不会报 -32003。Linux/Android 使用 POSIX PTY(UTF-8,is_pty=true),Android 的 shell 是 /system/bin/sh(mksh)。"; tool["inputSchema"] = BuildTerminalOpenInputSchema(); tool["outputSchema"] = BuildTerminalOpenOutputSchema(); tools.append(tool); @@ -2509,7 +2511,7 @@ std::string BuildToolsListResult(const Json::Value& id) { { Json::Value tool(Json::objectValue); tool["name"] = "terminal_exec"; - tool["description"] = u8"在已打开的持久会话中执行一条命令,或轮询取回正在运行的命令输出。带 command 时执行并在 timeout_ms 内等待;等待超时返回 done:false 与已产生的部分输出,会话不销毁(命令仍在远端运行)。不带 command、只传 session_id 时进入轮询模式:继续等待并取回增量输出,直到 done:true(此时有 exit_code)。命令不受白名单约束。PTY 会话(新 Windows 客户端 ConPTY / Linux 与新版 Android 的 POSIX PTY)下可用管道 | 与 && / || 串联,退出码取整条管道/串联,适合「ls -1 | wc -l」这类先过滤再回传的用法;不要用后台执行符 &(POSIX)或换行。老非 PTY Windows 客户端仍不支持 & 与 |,请拆成多条调用。"; + tool["description"] = u8"在已打开的持久会话中执行一条命令,或轮询取回正在运行的命令输出。带 command 时执行并在 timeout_ms 内等待;等待超时返回 done:false 与已产生的部分输出,会话不销毁(命令仍在远端运行)。session_id 可省略:自动复用该主机已有的持久会话,没有就隐式打开一个(结果里有 session_id 与 reused),不必先 terminal_open。不带 command、只传 session_id 时进入轮询模式:继续等待并取回增量输出,直到 done:true(此时有 exit_code)。命令不受白名单约束。PTY 会话(新 Windows 客户端 ConPTY / Linux 与新版 Android 的 POSIX PTY)下可用管道 | 与 && / || 串联,退出码取整条管道/串联,适合「ls -1 | wc -l」这类先过滤再回传的用法;不要用后台执行符 &(POSIX)或换行。老非 PTY Windows 客户端仍不支持 & 与 |,请拆成多条调用。"; tool["inputSchema"] = BuildTerminalExecInputSchema(); tool["outputSchema"] = BuildTerminalExecOutputSchema(); tools.append(tool); @@ -4774,6 +4776,10 @@ Json::Value BuildTerminalOpenOutputSchema() { pty["type"] = "boolean"; pty["description"] = u8"true=PTY(UTF-8)(Windows ConPTY / Linux PTY);false=老 cmd 管道(GBK)"; props["is_pty"] = pty; + Json::Value reused(Json::objectValue); + reused["type"] = "boolean"; + reused["description"] = u8"true=该主机已有持久会话,本次直接复用(未新建);false=本次新建"; + props["reused"] = reused; Json::Value schema(Json::objectValue); schema["type"] = "object"; schema["properties"] = props; @@ -4792,7 +4798,7 @@ Json::Value BuildTerminalExecInputSchema() { props["id"] = idProp; Json::Value sid(Json::objectValue); sid["type"] = "string"; - sid["description"] = u8"terminal_open 返回的 session_id"; + sid["description"] = u8"会话 token。带 command 时可省略:自动复用该主机已有的持久会话,没有就在内部打开一个(结果里有 session_id 与 reused)。轮询模式必须提供"; props["session_id"] = sid; Json::Value cmdProp(Json::objectValue); cmdProp["type"] = "string"; @@ -4811,7 +4817,6 @@ Json::Value BuildTerminalExecInputSchema() { schema["properties"] = props; Json::Value required(Json::arrayValue); required.append("id"); - required.append("session_id"); schema["required"] = required; return schema; } @@ -4830,6 +4835,14 @@ Json::Value BuildTerminalExecOutputSchema() { sid["type"] = "string"; sid["description"] = u8"会话 token,原样回传,便于续接轮询"; props["session_id"] = sid; + Json::Value ptyProp(Json::objectValue); + ptyProp["type"] = "boolean"; + ptyProp["description"] = u8"true=PTY(UTF-8)(Windows ConPTY / Linux PTY);false=老 cmd 管道(GBK)"; + props["is_pty"] = ptyProp; + Json::Value reusedProp(Json::objectValue); + reusedProp["type"] = "boolean"; + reusedProp["description"] = u8"true=复用了该主机已有的持久会话;false=本次隐式新建(省略 session_id 时)"; + props["reused"] = reusedProp; Json::Value exitProp(Json::objectValue); exitProp["type"] = "integer"; exitProp["description"] = u8"退出码(done=true 时提供):PTY 客户端(Windows ConPTY / Linux PTY)为命令的真实退出码;老客户端(非 PTY)仅区分 0/非 0;-1=未知(shell 进程退出)"; @@ -4908,8 +4921,25 @@ std::string BuildTerminalOpen(const Json::Value& id, const Json::Value& args, CM if (GetIntArg(args, "timeout_ms", v) && v > 0 && v <= 600000) timeoutMs = v; std::string sessionId = GenerateRandomToken(); - if (!mcp.BeginTermOpen(devId, sessionId)) - return BuildError(id, -32003, "Device busy: a terminal session is already active for this host"); + if (!mcp.BeginTermOpen(devId, sessionId)) { + // 该 host 已有持久会话(可能是 terminal_exec 隐式建的):直接复用它并返回 token, + // 而不是报 -32003 让调用方对着一个看不见的会话干瞪眼(P0-1 风险 2)。 + bool reusedPty = false; + if (mcp.ReuseTermSession(devId, sessionId, reusedPty) != 0) + return BuildError(id, -32003, "Device busy: a terminal session for this host is still starting"); + Json::Value reusedResult(Json::objectValue); + Json::Value reusedSc(Json::objectValue); + reusedSc["session_id"] = sessionId; + reusedSc["is_pty"] = reusedPty; + reusedSc["reused"] = true; + reusedResult["structuredContent"] = reusedSc; + Json::Value reusedText(Json::objectValue); + reusedText["session_id"] = sessionId; + reusedText["reused"] = true; + SetStructuredTextPayload(reusedResult, reusedText); + reusedResult["isError"] = false; + return BuildResult(id, reusedResult); + } BYTE cmd = COMMAND_SHELL; if (!ctx->Send2Client(&cmd, 1)) { @@ -4934,6 +4964,7 @@ std::string BuildTerminalOpen(const Json::Value& id, const Json::Value& args, CM Json::Value structuredContent(Json::objectValue); structuredContent["session_id"] = sessionId; structuredContent["is_pty"] = isPty; + structuredContent["reused"] = false; result["structuredContent"] = structuredContent; Json::Value content(Json::arrayValue); @@ -4952,13 +4983,15 @@ std::string BuildTerminalOpen(const Json::Value& id, const Json::Value& args, CM static std::string BuildTerminalExecResult(const Json::Value& id, const std::string& sessionId, const std::string& output, bool done, bool closed, int exitCode, bool truncated, size_t droppedBytes, - int elapsedMs) { + int elapsedMs, bool isPty, bool reused) { const int finalExit = done ? (closed ? -1 : exitCode) : -1; Json::Value structuredContent(Json::objectValue); structuredContent["stdout"] = output; structuredContent["done"] = done; structuredContent["session_id"] = sessionId; + structuredContent["is_pty"] = isPty; + structuredContent["reused"] = reused; if (done) structuredContent["exit_code"] = finalExit; structuredContent["truncated"] = truncated; if (droppedBytes > 0) structuredContent["dropped_bytes"] = (Json::UInt64)droppedBytes; @@ -5005,13 +5038,12 @@ std::string BuildTerminalExec(const Json::Value& id, const Json::Value& args, CM const bool posix = (ctx->GetAdditionalData(RES_CLIENT_TYPE) == "LNX" || ctx->GetAdditionalData(RES_CLIENT_TYPE) == "APK"); - std::string sessionId = GetStringArg(args, "session_id"); - if (sessionId.empty()) - return BuildError(id, -32602, "Missing required parameter: session_id"); - - // command 省略 = 轮询模式(P0-2);command 与 session_id 之外都不再是必填。 + // command 省略 = 轮询模式(P0-2);session_id 可省略(P0-1:带 command 时自动建/复用默认会话)。 std::string command = Trim(GetStringArg(args, "command")); const bool isPoll = command.empty(); + std::string sessionId = GetStringArg(args, "session_id"); + if (isPoll && sessionId.empty()) + return BuildError(id, -32602, "Missing required parameter: session_id (polling needs the session token)"); auto sessionError = [&](int code) -> std::string { // 区分「会话被超时/退出/关闭销毁」与「session_id 写错」「另一条命令在飞」(评审 P1)。 @@ -5046,6 +5078,32 @@ std::string BuildTerminalExec(const Json::Value& id, const Json::Value& args, CM const auto started = std::chrono::steady_clock::now(); std::string nonce, cmdLine, sentLine; bool isPty = false; + bool reused = true; // session_id 由调用方提供或复用了已有会话 + + // 没给 session_id:复用该主机已有的持久会话;没有就按 terminal_open 的同一路径隐式建一个 + // (对外不暴露 open/close,结果里带回 session_id 与 reused)。 + if (sessionId.empty()) { + int openOrReuse = mcp.OpenOrReuseTermSession(devId, sessionId, reused); + if (openOrReuse != 0) + return BuildError(id, -32003, "Device busy: a terminal session for this host is still starting"); + if (!reused) { + BYTE openCmd = COMMAND_SHELL; + if (!ctx->Send2Client(&openCmd, 1)) { + mcp.ClearTermPending(devId); + return BuildError(id, -32004, "Failed to send command to host"); + } + context* openSubCtx = nullptr; + bool openPty = false; + if (!mcp.WaitTerminalReady(devId, openSubCtx, openPty, CMcpServer::Instance().ToolTimeoutMs())) + return BuildError(id, -32001, "Timeout waiting for shell to start"); + if (parent) { + std::string text = "host " + std::to_string(devId) + " term-open (implicit): session " + sessionId; + parent->PostMessageA(WM_SHOWERRORMSG, + (WPARAM)new CString(ToAnsi(text, 936).c_str()), + (LPARAM)new CString(_TR("MCP持久终端"))); + } + } + } if (!isPoll) { // 先只读查会话形态:PTY 会话才允许管道/串联;失败时状态不变。 @@ -5116,7 +5174,7 @@ std::string BuildTerminalExec(const Json::Value& id, const Json::Value& args, CM finalChunk); return BuildTerminalExecResult(id, sessionId, stdoutStr, done, closed, exitCode, - truncated, droppedBytes, elapsedMs); + truncated, droppedBytes, elapsedMs, isPty, reused); } // tools/call:terminal_close(关闭持久会话;幂等,session_id 不匹配报错) @@ -10969,6 +11027,41 @@ bool CMcpServer::BeginTermOpen(uint64_t device_id, const std::string& sessionId) return true; } +int CMcpServer::OpenOrReuseTermSession(uint64_t device_id, std::string& sessionId, bool& reused) { + std::lock_guard lk(m_TermMutex); + auto it = m_TermSessions.find(device_id); + if (it != m_TermSessions.end()) { + TermSession& s = it->second; + // 已有一条在用的持久会话:直接复用(忙不忙由 BeginTermCommand 判断)。 + if (s.persistent && s.started && !s.closed) { + sessionId = s.sessionId; + reused = true; + return 0; + } + // 有 open 正在建立 / 一次性 exec_command 在跑:单设备单终端,报忙。 + return 2; + } + TermSession s; + s.sessionId = GenerateRandomToken(); + s.persistent = true; + s.lastActiveAt = time(nullptr); + sessionId = s.sessionId; + m_TermSessions[device_id] = std::move(s); + reused = false; + return 0; +} + +int CMcpServer::ReuseTermSession(uint64_t device_id, std::string& sessionId, bool& isPty) { + std::lock_guard lk(m_TermMutex); + auto it = m_TermSessions.find(device_id); + if (it == m_TermSessions.end()) return 2; + TermSession& s = it->second; + if (!s.persistent || !s.started || s.closed) return 2; + sessionId = s.sessionId; + isPty = s.isPty; + return 0; +} + // 墓碑:记下会话被销毁的原因,供后续 terminal_exec 给出可区分文案。 // 调用方必须持有 m_TermMutex。会话不存在时记录是为了让「上一次超时后用户重试」能看懂。 void CMcpServer::MarkTermDestroyedLocked(uint64_t device_id, const std::string& sessionId, diff --git a/server/2015Remote/McpServer.h b/server/2015Remote/McpServer.h index c0e04cd..27fbb19 100644 --- a/server/2015Remote/McpServer.h +++ b/server/2015Remote/McpServer.h @@ -258,6 +258,15 @@ public: // 登记持久终端挂起(复用单设备单终端约束;sessionId 由调用方生成)。 bool BeginTermOpen(uint64_t device_id, const std::string& sessionId); + // terminal_exec 不带 session_id 时:复用该主机已有的持久会话;没有就登记一个挂起会话。 + // 返回:0=ok(reused=true 复用已有会话;false=本次新建,调用方需发 COMMAND_SHELL 并 + // WaitTerminalReady);2=已有会话但尚未就绪(并发 open,调用方报 -32003)。 + int OpenOrReuseTermSession(uint64_t device_id, std::string& sessionId, bool& reused); + + // terminal_open 撞上已有会话时复用它(不再报 -32003):0=ok(输出 token 与 isPty); + // 2=已有会话但尚未就绪(有 open 在并发建立中)。 + int ReuseTermSession(uint64_t device_id, std::string& sessionId, bool& isPty); + // 复位单条命令字段并置 busy;输出 subCtx/isPty。 // 返回:0=ok;1=会话不存在;2=sessionId 不匹配;3=未就绪;4=忙(另一条命令在飞); // 5=shell 已退出。1/2 之外的原因由 DescribeTermDestroyed 提供可读文案。