Feature(mcp): let terminal_exec open or reuse a session implicitly

terminal_exec no longer requires session_id. Given a command and no
session_id, it reuses the host's persistent terminal session or opens one
through the same path as terminal_open, and reports session_id, is_pty and
reused in the result so the caller can keep using it. Polling still
requires the session token.

terminal_open now returns the existing session with reused:true instead of
-32003 when one is already active. An implicitly created session is
invisible to the caller, so rejecting would silently lock the host's single
terminal slot and leave exec_command failing with a busy error. A session
that is still starting, or one owned by a one-shot exec_command, still
answers -32003.

The server instruction line that told models to always pair terminal_open
with terminal_close is updated accordingly.

Co-Authored-By: deepseek-flash
This commit is contained in:
yuanyuanxianganddeepseek-flash committed 2026-11-12 16:01:13 +01:00
1 parent 3fe3a11494
commit 0378e96470
3 files changed
+132 -19

No files matched your search

+107 -14
View File
@@ -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<std::mutex> 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<std::mutex> 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,