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:
1 parent
3fe3a11494
commit
0378e96470
3 files changed
+132
-19
No files matched your search
+16
-5
@@ -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"
|
||||
|
||||
+107
-14
@@ -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,
|
||||
|
||||
@@ -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 提供可读文案。
|
||||
|
||||
Reference in new issue
Block a user