Feature: Add persistent remote terminal MCP tools

Add terminal_open / terminal_exec / terminal_close so an AI can hold one shell session per Windows host and run a sequence of commands with cwd and environment preserved, instead of the one-shot exec_command. The persistent terminal is a separate full-command write capability gated by McpTerminal (default off) plus McpReadonly=0, with no whitelist and full audit. One device maps to one terminal session via the shared m_TermSessions map; idle sessions are swept after 300s. terminal_exec rejects commands that contain & or | (they corrupt the sentinel control-operator chain) as well as control characters. Also harden exec_command and terminal_exec against newline/CR injection, fix a dangling subCtx after an abrupt shell disconnect, and refresh lastActiveAt on command completion. Add en/zh-TW translations for the new UI strings and a design document covering both exec_command and the persistent terminal. Co-Authored-By: deepseek-v4-pro
Feature: Add exec_command MCP tool
2026-08-24 19:11:16 +02:00 · 2026-08-23 23:23:20 +02:00
8 changed files with 1669 additions and 5 deletions
@@ -0,0 +1,471 @@
+# MCP 远程命令与持久终端 — 设计与实现
+
+> 本文档覆盖 MCP 侧两类**命令执行**能力：
+> 1. **一次性命令 `exec_command`**（P3a）—— 每次新建一个 shell、跑一条命令、读完即关。
+> 2. **持久终端 `terminal_open` / `terminal_exec` / `terminal_close`**（P4）—— 同一主机**一个** shell 会话，跨命令保持 cwd 与环境变量。
+>
+> 阅读顺序建议：先读 `docs/Mcp_Design.md`（Phase 1：HTTP 协议、token 校验、配置、`list_online_hosts`）与 `docs/Mcp_Phase2_Design.md`（模式 A/A′/B、工具路线图、P2a–P3a 概要），再读本文档的**实现级细节**。本文档是后续人员 / 大模型接手与排查问题的主参考。
+
+---
+
+## 1. 术语与总览
+
+| 术语 | 含义 |
+|---|---|
+| **一次性命令** | `exec_command`：无状态，每次独立 shell，命令结束即 `CancelIO` 关闭子链接。 |
+| **持久终端** | `terminal_open`→`terminal_exec`×N→`terminal_close`：有状态，cwd/env 跨命令保持。 |
+| **哨兵（sentinel）** | 包装在命令尾部的一段随机标记，用于在输出流里定位「命令真实退出码」并截断输出。 |
+| **子链接（sub-connection / `context*`）** | 客户端为 shell 建立的独立网络连接，`context` 是其服务端句柄。 |
+| **主连接（`FindMainContext`）** | 客户端与控制端的常驻长连接，用于下发 `COMMAND_*`。 |
+| **isPty** | `true`=ConPTY（UTF-8，`cp=CP_UTF8`）；`false`=老 cmd 管道（GBK，`cp=936`）。 |
+
+两类能力**共享同一套底层机制**（终端链路、编码、哨兵、状态机 map、审计），区别只在**生命周期**（一次性 vs 保持）与**安全门**（白名单 vs 无白名单 + 独立开关）。这也是为什么它们会互相排他（见 §6.3）。
+
+---
+
+## 2. 共享基础设施
+
+### 2.1 客户端终端链路（两种能力通用）
+
+无论一次性还是持久，shell 的建立过程完全相同：
+
+```
+服务端                    客户端
+  │  COMMAND_SHELL（主连接） ──►  客户端创建 shell 子连接
+  │  ◄── TOKEN_SHELL_START 或 TOKEN_TERMINAL_START（子连接）
+  │         ↓ MessageHandle 顶部判定 IsTermPending → 交给 RegisterTerminalContext 接管
+  │  COMMAND_NEXT（+ 若 PTY 先发 CMD_TERMINAL_RESIZE 80x24）──►  客户端启动 shell 输出回流
+  │  ◄── 持续 shell 输出（TOKEN_TERMINAL_DATA 之类，经 IsTerminalContext 路由到 OnTerminalData）
+  │  ◄── TOKEN_TERMINAL_CLOSE（shell 进程退出）→ OnTerminalClosed
+```
+
+关键点：
+- **`COMMAND_NEXT` 不能漏发**——客户端读线程靠它才启动输出回流，漏发会导致 shell 在跑但输出永不送回（`RegisterTerminalContext` 内的注释明确强调）。
+- **PTY 需先告知初始尺寸 80×24**，否则 TUI 尺寸错乱。
+- `TOKEN_SHELL_START` 与 `TOKEN_TERMINAL_START` 二选一：老 `ShellManager`（cmd 管道）回前者，ConPTY 回后者；服务端在 `MessageHandle` 里据此判定 `isPty`。
+
+### 2.2 编码
+
+| isPty | 底层 | 服务端 cp |
+|---|---|---|
+| `true` | ConPTY | `CP_UTF8` |
+| `false` | 老 cmd 管道 | `936`（GBK） |
+
+- **发送方向**：命令/哨兵行先 UTF-8 组好，再 `ToAnsi(line, cp)` 转成客户端编码，追加 `"\r\n"`。
+- **接收方向**：原始字节 `ToUtf8(raw, cp)` 转回 UTF-8。
+- 哨兵是纯 ASCII，两种编码下字节一致，编码无关。
+
+### 2.3 哨兵机制
+
+命令被包装成一行复合命令：
+
+```
+[@echo off & ] <cmd> 2>&1 && echo __MCP_DONE_<nonce>__0 || echo __MCP_DONE_<nonce>__1
+```
+
+- `@echo off & ` **仅 ConPTY 需要**（抑制 ConPTY 把输入整行回显）。老 `ShellManager` 已自行跳过回显，加 `@echo off` 反而破坏它的回显跳过逻辑。
+- `&&` / `||` 控制操作符取**命令真实退出码**（`%errorlevel%` 在复合句中解析期展开、已过期，故不能用 `%errorlevel%`）。
+- `<nonce>` 为 8 位随机 hex（`GenerateRandomToken().substr(0,8)`），保证命令真实输出不可能恰好包含完整哨兵串。
+- `2>&1` 让 stderr 也走哨兵链，stdout/stderr 都能被捕获且退出码正确。
+
+**`FindSentinel`（检测）** 用 `rfind` **从后往前**找，且要求哨兵在**行首**（`p==0` 或前一个字节是 `\n`），后跟 `0` 或 `1`：
+
+```cpp
+size_t from = npos;
+while (true) {
+    size_t p = s.rfind(marker, from);
+    bool lineStart = (p == 0) || (s[p-1] == '\n');
+    if (lineStart && s[p+marker.size()] 是 '0' 或 '1') { exitCode=...; pos=p; return true; }
+    from = p - 1;
+}
+```
+
+为什么要「从后往前 + 行首」：ConPTY 会把**整条命令行回显**进输出流，回显里的哨兵字样嵌在 `&& echo ... || echo ...` 中间、前面是空格（非行首）。若用 `rfind` 直取，回显包先于真实输出到达时会命中回显里的 `__1` 提前结束、截断真实输出。行首校验能排除回显行。老 `ShellManager` 无回显，输出里只有真实哨兵（仍在行首），逻辑一致。
+
+### 2.4 输出清洗管线
+
+从原始字节到返回 `stdout` 字符串，固定五步（`CleanTerminalOutput`，一次性命令为内联等价逻辑）：
+
+```
+raw 字节
+  → ToUtf8(raw, cp)                      按 2.2 编码解码
+  → StripAnsi(...)                       剥 CSI/OSC/单字节 ESC，去彩色码
+  → CRLF → LF                            "\r\n" 归一为 "\n"
+  → StripEchoedCommand(stdout, sentLine) 剔 ConPTY 输入行回显（见下）
+  → TrimRight(...)                       去尾部空白
+```
+
+**`StripEchoedCommand`（回显剔除）**：ConPTY 的 `ENABLE_ECHO_INPUT` 会在 `@echo off` 生效**之前**把整条输入命令行回显进输出流。修复方法是在**服务端**把「刚发送的、含唯一 nonce 的完整命令行」（`SendTerminalCommandLine` 的返回值）从输出里整行 `find` + 剔除：
+
+```cpp
+static std::string StripEchoedCommand(const std::string& s, const std::string& echoedLine) {
+    if (echoedLine.empty() || s.empty()) return s;
+    size_t p = s.find(echoedLine);
+    if (p == npos) return s;
+    size_t q = p + echoedLine.size();
+    if (q < s.size() && s[q] == '\n') ++q;   // CRLF 已归一为 \n
+    return s.substr(0, p) + s.substr(q);
+}
+```
+
+- 因 `echoedLine` 含随机 nonce，命令真实输出不可能恰好相同 → 不会误删合法输出。
+- 老 `ShellManager` 无回显，`find` 不到该行 → 无操作，安全。
+
+### 2.5 状态机与互斥（两类能力共用）
+
+```cpp
+struct TermSession {
+    bool      started;      // false=已发 COMMAND_SHELL 待 START；true=已接管
+    context*  subCtx;       // shell 子连接上下文
+    bool      isPty;        // ConPTY(UTF-8) / cmd 管道(GBK)
+    std::string command;    // 原始 UTF-8 命令（审计用）
+    std::string nonce;      // 哨兵随机串
+    std::vector<BYTE> data; // 收集的原始 shell 输出
+    size_t    sentPos;      // 哨兵在 data 中的位置
+    int       exitCode;     // 0/1/-1
+    bool      done;         // 哨兵命中
+    bool      closed;       // TOKEN_TERMINAL_CLOSE（进程退出）
+    // ── 以下为持久终端新增 ──
+    std::string sessionId;  // 持久会话 token（一次性 exec 为空）
+    bool      persistent;   // 是否持久会话
+    bool      busy;         // 一条命令在飞（terminal_exec 复位 → WaitTermCommand 返回）
+    time_t    lastActiveAt; // idle 回收用（秒）
+};
+
+std::mutex                    m_TermMutex;             // 保护下面两个 map
+std::condition_variable       m_TermCv;
+std::map<uint64_t, TermSession>  m_TermSessions;       // device_id → 会话
+std::map<context*, uint64_t>     m_TermContextToDevice; // subCtx → device_id（顶部路由）
+```
+
+- `m_TermContextToDevice` 是**反向索引**：`MessageHandle` 顶部用 `IsTerminalContext(subCtx)` 判定「这个子链接的输出是否该路由到 MCP 的 `OnTerminalData`，而不是打开 MFC 终端对话框」。
+- `httplib` 默认多线程处理请求 → **多个 `tools/call` 会并发**。所有会话状态都靠 `m_TermMutex` + `busy` 串行化，**不要假定请求串行**。
+
+---
+
+## 3. 一次性命令 `exec_command`
+
+### 3.1 安全门（顺序）
+
+```
+ParseHostIdArg           → -32602 参数非法
+FindMainContext          → -32002 主机不存在/离线
+clientType==LNX/MAC      → -32005 仅 Windows
+command 为空              → -32602
+mcp.IsReadonly()         → -32006 只读模式默认开，需 McpReadonly=0
+含 &|<>^ 五元字符         → -32008 防注入绕过白名单
+含控制字符（\r\n 等 <0x20） → -32008 防换行拆分绕过白名单
+白名单前缀校验            → -32007 不在白名单
+```
+
+- **白名单**：`IsCommandAllowed` 做「trim + ASCII 小写后前缀匹配」，且前缀后须为空/空格/制表符（防 `dirx` 误配 `dir`）。配置为空时回落到内置 `kDefaultCmdWhitelist`：
+  ```
+  dir,type,cd,chdir,ver,hostname,whoami,where,tasklist,systeminfo,ipconfig,netstat,
+  path,set,find,findstr,reg query,sc query,
+  ping,tracert,nslookup,getmac,driverquery,query,gpresult,
+  arp -a,route print,schtasks /query
+  ```
+- **元字符门 `&|<>^`** 是**安全门**（拒绝 shell 注入/命令拼接），比持久终端的 `&|` 更严。
+- **控制字符门**：同时拒绝所有 `<0x20` 的控制字符（`\r`/`\n` 等）。否则 `dir \n rd /s /q ...` 这种带内嵌换行的命令会通过「前缀 `dir` + 空格」的白名单校验，却在 `cmd.exe` 里被换行拆成两条独立命令、执行任意后续行——彻底绕过只读白名单。这是 2026-08-24 独立审查发现并修复的**安全漏洞**。
+
+### 3.2 流程
+
+```
+BeginTermPending(devId, command, nonce)   → false 则 -32003（该 host 已有终端会话）
+ctx->Send2Client(COMMAND_SHELL)            → 失败 ClearTermPending + -32004
+WaitTerminalReady(devId, subCtx, isPty, timeoutMs)
+                                           → 超时 -32001（内部已自清理）
+组哨兵行 Send2Client                        （见 §2.3）
+WaitTerminalDone(devId, raw, exitCode, closed, timeoutMs)
+                                           → 超时 -32001（内部已自清理 + 调用方 CancelIO）
+subCtx->CancelIO()                         ← 一次性：读完即关子链接，结束 shell
+清洗输出（§2.4）
+审计：PostMessageA(WM_SHOWERRORMSG, ..., "MCP命令执行")
+返回 { stdout, exit_code }
+```
+
+### 3.3 `WaitTerminalDone` 三态（一次性专用）
+
+- **哨兵命中（done）**：`out` = `data[0..sentPos)`（截断到哨兵前），`exitCode=0/1`，**擦除会话+路由**，返回 true。
+- **进程退出（closed）**：`out` = 全部 `data`（无哨兵），`exitCode=-1`，擦除会话+路由，返回 true。
+- **超时**：擦除会话+路由，返回 false（调用方 `CancelIO`）。
+
+---
+
+## 4. 持久终端 `terminal_open` / `terminal_exec` / `terminal_close`
+
+### 4.1 工具契约
+
+| 工具 | 入参（required） | 出参 |
+|---|---|---|
+| `terminal_open` | `id`（+`timeout_ms`） | `session_id`(32hex)、`is_pty`(bool) |
+| `terminal_exec` | `id`、`session_id`、`command`（+`timeout_ms`） | `stdout`、`exit_code` |
+| `terminal_close` | `id`、`session_id` | `closed`(bool，恒 true) |
+
+`session_id` 由服务端 `GenerateRandomToken()` 生成（32 hex / 128 bit）。
+
+### 4.2 共享前置 `ResolveTerminalSessionHost`
+
+`terminal_open` / `terminal_exec` 复用（`terminal_close` 为幂等内联版，见 §4.5）：
+
+```
+IsTerminalEnabled() && !IsReadonly()  → -32006（需 McpTerminal=1 且 McpReadonly=0）
+ParseHostIdArg                          → -32602
+FindMainContext                         → -32002 主机不存在/离线
+clientType==LNX/MAC                     → -32005 仅 Windows
+```
+
+### 4.3 `terminal_open`
+
+```
+SweepIdleTerminals(300)                 ← 先回收闲置会话
+ResolveTerminalSessionHost
+sessionId = GenerateRandomToken()
+BeginTermOpen(devId, sessionId)         → false 则 -32003（单设备单终端）
+ctx->Send2Client(COMMAND_SHELL)          → 失败 ClearTermPending + -32004
+WaitTerminalReady(...)                   → 超时 -32001（自清理）
+审计 "term-open"
+返回 { session_id, is_pty }
+```
+
+**关键**：`WaitTerminalReady` 成功后**不擦除会话**（与一次性相反）——会话要留给后续 `terminal_exec`。此时 `started=true`、`busy=false`，shell 空闲运行。
+
+### 4.4 `terminal_exec`
+
+```
+SweepIdleTerminals(300)
+ResolveTerminalSessionHost
+session_id 为空            → -32602
+command 为空               → -32602
+command 含 & 或 |          → -32008（正确性门，见 §4.6）
+nonce = 随机 8 hex
+BeginTermCommand(devId, sessionId, command, nonce, subCtx, isPty)
+                           → false 则 -32002（不存在/不匹配/未就绪/忙碌/已关）
+sentLine = SendTerminalCommandLine(subCtx, isPty, command, nonce)
+WaitTermCommand(devId, raw, exitCode, closed, timeoutMs)
+                           → 超时：subCtx->CancelIO() + -32001
+                           → closed：subCtx->CancelIO()（会话已被清理，仅对称无害）
+stdoutStr = CleanTerminalOutput(raw, cp, sentLine)
+审计 "term-exec [sessionId]: command"
+返回 { stdout, exit_code }
+```
+
+**`WaitTermCommand` 三态（持久专用，与一次性不同）**：
+
+- **哨兵命中（done）**：`busy=false`、刷新 `lastActiveAt`、`out` 截到 `sentPos`、**保留会话**，返回 true。← 这是「持久」的核心：命令完成后 shell 不关。
+- **进程退出（closed）**：`out`=全部 `data`、`exitCode=-1`、**擦除会话+路由**，返回 true。
+- **超时**：擦除会话+路由，返回 false（调用方 `CancelIO`）。
+
+### 4.5 `terminal_close`
+
+```
+SweepIdleTerminals(300)
+IsTerminalEnabled() && !IsReadonly()  → -32006
+ParseHostIdArg                          → -32602
+session_id 为空                          → -32602
+CloseTermSession(devId, sessionId)
+    r==2（sessionId 不匹配）             → -32002（防拼错静默泄漏真会话）
+审计 "term-close"
+返回 { closed: true }
+```
+
+`CloseTermSession` 返回值语义：**0**=已关闭；**1**=会话不存在（幂等，仍返回 `{closed:true}`）；**2**=sessionId 不匹配（报错）。
+
+### 4.6 正确性门 `&|`（非安全门）
+
+`terminal_exec` **拒绝含 `&` 或 `|` 的命令**（`find_first_of("&|")`，含 `&&`/`||`/`|`），报 `-32008`。原因：哨兵包装 `cmd 2>&1 && echo ... || echo ...` 假定命令是「扁平」的，命令内含 `&`/`|` 会与包装的控制操作符合流、导致退出码失真/输出归属不清。
+
+- 这是**正确性限制，不是白名单**——持久终端本就不设白名单。
+- 同样拒绝 `<0x20` 的控制字符（`\r`/`\n`）：换行会把命令拆成多行、只有末行被哨兵包装，导致退出码与输出归属失真。
+- `> < ^`（重定向 / 转义）**允许**：不破坏哨兵链。AI 把链式/管道命令拆成多条 `terminal_exec` 调用即可（cwd/env 保持，等价）。
+
+对比：一次性 `exec_command` 因有白名单，其元字符门更严（`&|<>^` 五元字符全拒，§3.1）。
+
+---
+
+## 5. 状态机方法明细
+
+### 5.1 一次性命令专用
+
+| 方法 | 作用 |
+|---|---|
+| `BeginTermPending(devId, cmd, nonce)` | 锁内登记会话；已有会话则 false（单设备单终端）。 |
+| `WaitTerminalReady(devId, subCtx, isPty, timeout)` | 等 `started`；超时**擦除**并返回 false。成功输出 `subCtx`/`isPty`，**不擦**。 |
+| `WaitTerminalDone(...)` | 等 `done||closed`；三态见 §3.3。 |
+| `ClearTermPending(devId)` | 发送失败等提前退出路径的清理。 |
+| `IsTermPending(devId)` | `MessageHandle` 判定是否有待接管的终端会话。 |
+| `RegisterTerminalContext(devId, subCtx, isPty)` | 子连接就绪接管：置 `started/subCtx/isPty`、登记反向索引、发 `COMMAND_NEXT`(+PTY resize)、`notify_all`。 |
+| `IsTerminalContext(subCtx)` | `MessageHandle` 顶部路由判定。 |
+| `OnTerminalData(subCtx, data, len)` | 追加输出、`FindSentinel` 命中置 `done` + `notify`；`done||closed` 时忽略迟到数据。 |
+| `OnTerminalClosed(subCtx)` | 置 `closed`；空闲持久会话直接擦；`notify_all` 唤醒 busy 等待线程。 |
+
+### 5.2 持久终端专用
+
+| 方法 | 作用 |
+|---|---|
+| `BeginTermOpen(devId, sessionId)` | 锁内建持久会话（`persistent=true`、`lastActiveAt=now`）；已有会话 false。 |
+| `BeginTermCommand(devId, sid, cmd, nonce, subCtx, isPty)` | 锁内校验「persistent && sid 匹配 && started && !busy && !closed」→ 置 `busy=true`、**原子复位** `data/sentPos/exitCode/done/closed`、更新 `command/nonce/lastActiveAt`。 |
+| `WaitTermCommand(...)` | 等 `done||closed`；三态见 §4.4。 |
+| `CloseTermSession(devId, sid)` | 不存在→1；sid 不匹配→2；`busy` 时仅置 `closed`+notify（交等待线程清理，防双重擦除）；非 busy 直接擦+锁外 `CancelIO`。 |
+| `SweepIdleTerminals(idleTimeoutSec)` | 回收 `persistent && !busy && difftime(now,lastActiveAt)>idle` 的会话；收集后锁外 `CancelIO`。 |
+
+### 5.3 `OnTerminalClosed` 的泄漏修复
+
+`OnTerminalClosed` 有**两个入口**：
+
+1. `MessageHandle` 的 `TOKEN_TERMINAL_CLOSE` 分支（客户端 shell 优雅退出时发 token）。
+2. `OfflineProc`（`2015RemoteDlg.cpp`）——连接**骤然断开**（网络断/客户端崩溃，无 token）时，与 `WebService().OnTerminalClosed` 并列调用 `McpServer().OnTerminalClosed`。此入口是 2026-08-24 独立审查发现缺失并补齐的：否则骤断的持久终端会话会在 `m_TermSessions`/`m_TermContextToDevice` 里留悬空 `subCtx`，连接池复用地地址后会误路由新连接、甚至 `CancelIO` 掉无关连接。
+
+shell 进程退出时，若是一个**空闲持久会话**（`persistent && !busy && started`），没有等待线程会清理它，会泄漏死 `subCtx`。故：
+
+```cpp
+s.closed = true;
+if (s.persistent && !s.busy && s.started) {
+    m_TermContextToDevice.erase(subCtx);   // 空闲持久会话：直接擦（无需 CancelIO，已死）
+    m_TermSessions.erase(sit);
+}
+m_TermCv.notify_all();   // busy 场景唤醒等待线程由其清理；一次性 exec 路径不变
+```
+
+---
+
+## 6. 并发模型与不变量
+
+### 6.1 关键不变量
+
+- **`CancelIO` 一律在 `m_TermMutex` 之外**（所有路径：`BuildExecCommand`、`BuildTerminalExec`、`CloseTermSession`、`SweepIdleTerminals`）。这是硬约束——`CancelIO` 可能阻塞/回调，锁内调用会死锁。
+- **`wait_for` 期间不持有会被他人擦除的迭代器**：等待线程（`WaitTermCommand`）持 `it`，但**只有它自己**会在超时/closed 路径擦除该会话；`terminal_close`/`sweep` 因 `busy` 标志而**不会**擦除「正在等待的命令」的会话。这就是 `busy` 标志的核心作用。
+- **单设备单终端**：`terminal_*` 与 `exec_command` 因**共享 `m_TermSessions`** 而互斥（双向 `-32003`）。`BeginTermPending` 与 `BeginTermOpen` 都做「已有会话则 false」。
+
+### 6.2 `busy` 标志生命周期
+
+```
+terminal_exec:  BeginTermCommand 置 busy=true
+                Send2Client
+                WaitTermCommand 返回时：
+                  done 路径   → busy=false（保留会话）
+                  closed 路径 → 会话被擦除
+                  超时路径    → 会话被擦除
+terminal_close（会话忙时）→ 仅置 closed=true + notify，不擦，交等待线程清理
+```
+
+### 6.3 互斥矩阵
+
+| | `exec_command` | `terminal_*` | `list_files`/`get_screenshot` 等 |
+|---|---|---|---|
+| `exec_command` | 互斥（-32003） | 互斥（-32003） | 无关（各用 `m_Pending`） |
+| `terminal_*` | 互斥 | 单设备单终端 | 无关 |
+
+> Web 终端与 MCP 终端各用独立 map，理论上可同设备并存（既有现象，非本次范围）。
+
+### 6.4 idle 回收语义
+
+`SweepIdleTerminals(300)`：`lastActiveAt` 在 `BeginTermOpen` / `BeginTermCommand` **（命令开始时）**更新，**命令完成后不刷新**。因此「两次命令间隔 < 300s」的活跃会话安全；「一次长命令 + 长时间无新命令」的会话会在最后一次命令开始 300s 后被回收。回收是非惰性的——每次 `terminal_*` 入口先 sweep，所以空闲会话不会在无请求时被后台主动关闭（但也不占后台定时器资源）。用 `difftime` 比较防时钟回拨下溢。
+
+---
+
+## 7. 安全模型
+
+| 维度 | `exec_command` | 持久终端 |
+|---|---|---|
+| 开关 | `McpReadonly=0` | `McpTerminal=1` **且** `McpReadonly=0`（默认 `McpTerminal=0`） |
+| 白名单 | 有（内置/自定义前缀白名单） | **无**（完整 shell，可写命令、重定向、改环境） |
+| 元字符门 | `&|<>^` + 控制字符全拒（安全门） | `&|` + 换行拒（正确性门） |
+| 审计 | `WM_SHOWERRORMSG` 标题「MCP命令执行」 | 标题「MCP持久终端」（open/exec/close 各一条） |
+| 生命周期 | 命令结束即关 | 会话保持，闲置 300s 回收，`terminal_close` 显式关 |
+| 会话隔离 | 单设备单终端 | 单设备单终端 + `session_id` 校验防串用 |
+
+审计实现：`PostMessageA(WM_SHOWERRORMSG, new CString(...), new CString(_TR("...标题...")))` → 进入服务端 `m_MessageLog`，`get_audit_log` 可查。审计不可关闭。
+
+---
+
+## 8. 配置项
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `McpEnabled` | 0 | MCP 总开关 |
+| `McpPort` | 6544 | 监听端口 |
+| `McpBind` | 127.0.0.1 | 绑定地址（默认仅回环） |
+| `McpToken` | （空→运行时兜底） | Bearer token |
+| `McpReadonly` | 1 | 只读模式（禁 `exec_command` 与持久终端） |
+| `McpCmdWhitelist` | （空→内置白名单） | `exec_command` 白名单，逗号分隔 |
+| `McpTerminal` | 0 | 持久终端开关（要求 `McpReadonly=0`） |
+
+**存储位置**：Release 版存**注册表** `HKCU\Software\YAMA\settings`（**不是** `settings.ini`；`settings.ini` 仅 Debug 版读取）。改动需**重启程序**生效。
+
+**启动读取**（`2015RemoteDlg.cpp`）：
+```cpp
+McpServer().SetReadonly(THIS_CFG.GetInt("settings", "McpReadonly", 1) != 0);
+McpServer().SetCmdWhitelist(THIS_CFG.GetStr("settings", "McpCmdWhitelist", ""));
+McpServer().SetTerminalEnabled(THIS_CFG.GetInt("settings", "McpTerminal", 0) != 0);
+```
+
+**工具可见性**：`terminal_*` 三个工具在 `tools/list` 里**仅在** `IsTerminalEnabled() && !IsReadonly()` 时出现（门控在 `BuildToolsListResult`）。故默认配置下 `tools/list` 看不到它们。
+
+---
+
+## 9. 错误码
+
+| 码 | 含义 | 触发点 |
+|---|---|---|
+| `-32001` | 超时 | `WaitTerminalReady`/`WaitTermCommand`/`WaitPending` 等超时 |
+| `-32002` | 主机/会话不存在 | `FindMainContext` 失败、`session_id` 不匹配/未就绪/已关 |
+| `-32003` | 设备忙 | 单设备单终端冲突、同 host 已有挂起请求 |
+| `-32004` | 发送失败 | `Send2Client` 失败 |
+| `-32005` | 非 Windows | LNX/MAC 客户端 |
+| `-32006` | 已禁用/只读 | `IsReadonly()` 或 `!IsTerminalEnabled()` |
+| `-32007` | 白名单拒绝 | `IsCommandAllowed` false |
+| `-32008` | 含禁用字符 | `exec_command` 的 `&|<>^`；`terminal_exec` 的 `&|` |
+| `-32602` | 参数非法 | `ParseHostIdArg` 失败、缺 required 参数 |
+| `-32700` | JSON 解析错误 | 请求体非合法 JSON-RPC |
+
+---
+
+## 10. 排查指南（供后续人员/大模型）
+
+### 10.1 `exec_command` 返回 `-32001` 超时
+
+- 先看是不是**目标机环境问题**而非代码 bug：`nslookup`/`where` 在部分机器会因 DNS/文件系统异常稳定超时（见项目记忆）。裸 `nslookup <host>` 卡默认重试 20~40s > MCP 超时；`where cmd.exe` 在特定机器卡 PATH 解析。
+- 服务端行为正确：超时返回 `-32001` 并清理终端会话，不挂起/崩溃。
+
+### 10.2 `terminal_*` 在 `tools/list` 里看不到
+
+- 检查 `McpTerminal=1` **且** `McpReadonly=0`。任一不满足，工具不出现且调用返回 `-32006`。
+- 改配置后需**重启程序**（注册表配置启动时读）。
+
+### 10.3 `terminal_exec` 返回 `-32002`
+
+- 会话已被回收（闲置 >300s）、shell 已退出、或 `session_id` 拼错。重新 `terminal_open`。
+- `terminal_close` 的 `-32002` 特指 **session_id 不匹配**（防串用）。
+
+### 10.4 `-32003` 设备忙
+
+- 单设备单终端：同 host 已有终端会话（持久或一次性）在飞。等它结束或 `terminal_close`。
+- 紧接 `terminal_close`（会话 busy 时）后立刻 `terminal_open` 可能偶发 `-32003`：busy 会话的关闭是「标记 closed + 交等待线程清理」，清理完成前有极短窗口。重试一次即可，非死锁。
+
+### 10.5 stdout 里出现命令本身 / 哨兵
+
+- 命令本身回显 = ConPTY 输入回显，已由 `StripEchoedCommand` 服务端剔除（§2.4）。若仍出现，检查是否该行因编码（非 PTY 老管道的 GBK）与 `echoedLine` 字节不一致而 `find` 不到——老管道本应无回显。
+- 哨兵 `__MCP_DONE_...` 出现 = 哨兵截断/清洗异常，通常意味着命令含 `&|` 破坏了控制操作符链（持久终端会提前 `-32008` 拒绝，一次性会 `-32008` 拒绝五元字符）。
+
+### 10.6 中文/乱码
+
+- 输出乱码：检查 `isPty` 与 `cp` 是否匹配（PTY=UTF-8，老管道=GBK）。
+- **`get_audit_log` 中文乱码**：已知问题（GBK 写入 UTF-8 JSON），影响**所有**审计条目，非终端特有，暂未修复。
+
+### 10.7 会话泄漏 / 子链接不关
+
+- 三个擦除点：`WaitTermCommand`（closed/超时）、`CloseTermSession`、`SweepIdleTerminals`；以及 `OnTerminalClosed` 对**空闲持久会话**的直接擦除（§5.3）。排查时确认 shell 退出路径 `OnTerminalClosed` 是否命中、`COMMAND_NEXT` 是否漏发导致输出永不回流。
+
+---
+
+## 11. 关键源文件索引
+
+| 文件 | 内容 |
+|---|---|
+| `server/2015Remote/McpServer.h` | `TermSession` 结构、`BeginTermOpen/Command/WaitTermCommand/CloseTermSession/SweepIdleTerminals` 声明、`m_terminalEnabled` |
+| `server/2015Remote/McpServer.cpp` | `BuildExecCommand`（~1946）、`BuildTerminalOpen/Exec/Close`（~2345）、状态机方法（~2660）、`FindSentinel`（~2569）、`StripEchoedCommand`（~1935）、`SendTerminalCommandLine`（~2192）、`CleanTerminalOutput`（~2206）、`ResolveTerminalSessionHost`（~2160） |
+| `server/2015Remote/McpSettingsDlg.h/.cpp` | `IDC_MCP_TERMINAL` 复选框、回填/落盘 `McpTerminal` |
+| `server/2015Remote/2015RemoteDlg.cpp` | 启动读 `McpTerminal` → `SetTerminalEnabled` |
+
+> 构建由 VS2019（MSBuild v143）完成；项目工具集 v142，无法在外部环境构建。
@@ -2190,6 +2190,11 @@ BOOL CMy2015RemoteDlg::OnInitDialog()

        McpServer().SetParentDlg(this);
        McpServer().SetToken(mcpToken);
+        // 安全配置：只读默认 1（exec_command 默认禁用）；白名单空则用内置只读前缀。
+        McpServer().SetReadonly(THIS_CFG.GetInt("settings", "McpReadonly", 1) != 0);
+        McpServer().SetCmdWhitelist(THIS_CFG.GetStr("settings", "McpCmdWhitelist", ""));
+        // 持久终端开关：默认关；要求只读关（McpReadonly=0）才生效（工具列表/分派双重门控）。
+        McpServer().SetTerminalEnabled(THIS_CFG.GetInt("settings", "McpTerminal", 0) != 0);
        if (!McpServer().Start(mcpBind, mcpPort)) {
            Mprintf("McpServer start failed on %s:%d\n", mcpBind.c_str(), mcpPort);
        } else {
@@ -5155,6 +5160,12 @@ BOOL CALLBACK CMy2015RemoteDlg::OfflineProc(CONTEXT_OBJECT* ContextObject)
        WebService().OnTerminalClosed(ContextObject);
    }

+    // MCP 终端（一次性 exec / 持久终端）的 shell 子上下文断开：同步清理会话，避免悬空 subCtx
+    // 被连接池复用时误路由新连接（与 WebService 清理同理，需在 RemoveFromHostList 之前）。
+    if (McpServer().IsRunning() && McpServer().IsTerminalContext(ContextObject)) {
+        McpServer().OnTerminalClosed(ContextObject);
+    }
+
    SOCKET nSocket = ContextObject->sClientSocket;

 	CDialogBase* p = (CDialogBase*)ContextObject->hDlg;
@@ -5505,6 +5516,18 @@ VOID CMy2015RemoteDlg::MessageHandle(CONTEXT_OBJECT* ContextObject)
        return;
    }

+    // ===== MCP exec_command 的 shell 子上下文：被 MCP 接管时，数据走 OnTerminalData =====
+    // 与上方 Web 终端同构：MCP 接管的 shell 子上下文不开 MFC 对话框，hDlg 为 NULL，
+    // 每个数据包都落到 MessageHandle 顶部分支，转发给 McpServer 做哨兵检测。
+    if (McpServer().IsTerminalContext(ContextObject)) {
+        if (len == 1 && cmd == TOKEN_TERMINAL_CLOSE) {
+            McpServer().OnTerminalClosed(ContextObject);
+        } else {
+            McpServer().OnTerminalData(ContextObject, szBuffer, len);
+        }
+        return;
+    }
+
    // 【L】：主机上下线和授权
    // 【x】：对话框相关功能
    switch (cmd) {
@@ -6408,6 +6431,11 @@ VOID CMy2015RemoteDlg::MessageHandle(CONTEXT_OBJECT* ContextObject)
            // hDlg 留 NULL：后续数据继续走 MessageHandle 顶部的 IsTerminalContext 分支
            break;
        }
+        // MCP exec_command 触发的 shell 子上下文：交给 McpServer 接管（老 cmd 管道，GBK）。
+        if (McpServer().IsTermPending(devId)) {
+            McpServer().RegisterTerminalContext(devId, ContextObject, /*isPty*/false);
+            break;
+        }
        g_2015RemoteDlg->SendMessage(WM_OPENSHELLDIALOG, 0, (LPARAM)ContextObject);
        break;
    }
@@ -6418,6 +6446,11 @@ VOID CMy2015RemoteDlg::MessageHandle(CONTEXT_OBJECT* ContextObject)
            WebService().RegisterTerminalContext(devId, ContextObject, /*isPty*/true);
            break;
        }
+        // MCP exec_command 触发的 PTY 子上下文：交给 McpServer 接管（ConPTY，UTF-8）。
+        if (McpServer().IsTermPending(devId)) {
+            McpServer().RegisterTerminalContext(devId, ContextObject, /*isPty*/true);
+            break;
+        }

        // 三个前置条件，缺任何一个都回退到经典终端，并把原因贴到信息列表。
        // SYSTEM 场景：WebView2 不支持 LocalSystem token，会出现"窗口能弹但页面空白"，
@@ -10,6 +10,7 @@
 #include <map>
 #include <vector>
 #include <cstdint>
+#include <ctime>

 // httplib 与 Windows 头部的 min/max 宏冲突，按 file_server.h 的既有约定处理。
 #undef min
@@ -98,6 +99,70 @@ public:
    bool WaitPendingRegistry(uint64_t device_id, std::vector<BYTE>& subkeys,
                             std::vector<BYTE>& values, int timeoutMs);

+    // ===== P3：exec_command（Windows 一次性远程命令，复刻 Web 终端链路）=====
+    // 流程：工具线程 BeginTermPending → 主连接下发 COMMAND_SHELL → 客户端 shell 子连接回
+    // TOKEN_TERMINAL_START / TOKEN_SHELL_START → RegisterTerminalContext 接管 → 发
+    // COMMAND_NEXT(+PTY resize) 启动输出回流 → 工具线程发哨兵命令行 → OnTerminalData 收集
+    // 并做哨兵检测 → WaitTerminalDone 取 stdout + exit_code → CancelIO 关子链接。
+    // 单设备单终端（MVP）：BeginTermPending 命中已有会话即拒绝，避免同设备并发归属歧义。
+
+    // 该 host 是否已有待接管的终端会话（MessageHandle TOKEN_*_START 分支调用）。
+    bool IsTermPending(uint64_t device_id);
+
+    // 终端子连接就绪：接管（登记 subCtx/isPty、清 pending、发 COMMAND_NEXT 唤醒回流）。
+    void RegisterTerminalContext(uint64_t device_id, context* subCtx, bool isPty);
+
+    // 终端子连接是否已被 MCP 接管（MessageHandle 顶部据此把 shell 输出路由到 OnTerminalData）。
+    bool IsTerminalContext(context* subCtx);
+
+    // 追加 shell 输出并做哨兵检测（命中置 done 并唤醒等待者）。
+    void OnTerminalData(context* subCtx, const BYTE* data, ULONG len);
+
+    // shell 进程退出（TOKEN_TERMINAL_CLOSE）。
+    void OnTerminalClosed(context* subCtx);
+
+    // 工具线程：登记终端挂起（false = 该 host 已有终端会话）。
+    bool BeginTermPending(uint64_t device_id, const std::string& command, const std::string& nonce);
+
+    // 工具线程：等待子连接回 START 并接管（true = 已接管，输出 subCtx/isPty）。
+    bool WaitTerminalReady(uint64_t device_id, context*& subCtx, bool& isPty, int timeoutMs);
+
+    // 工具线程：等待输出收集完成（哨兵命中 / 进程退出 / 超时）。
+    // 成功 true：out=截断到哨兵前的原始字节、exitCode=0/1（进程退出无哨兵时 -1）、closed=是否进程退出。
+    bool WaitTerminalDone(uint64_t device_id, std::vector<BYTE>& out, int& exitCode, bool& closed, int timeoutMs);
+
+    // 工具线程：清理终端挂起（发送失败等提前退出路径）。
+    void ClearTermPending(uint64_t device_id);
+
+    // ===== P4：持久远程终端（terminal_open / terminal_exec / terminal_close）=====
+    void SetTerminalEnabled(bool enabled) { m_terminalEnabled = enabled; }
+    bool IsTerminalEnabled() const { return m_terminalEnabled; }
+
+    // 登记持久终端挂起（复用单设备单终端约束；sessionId 由调用方生成）。
+    bool BeginTermOpen(uint64_t device_id, const std::string& sessionId);
+
+    // 复位单条命令字段并置 busy；输出 subCtx/isPty。false = 不存在/不匹配/未就绪/忙碌/已关。
+    bool BeginTermCommand(uint64_t device_id, const std::string& sessionId,
+                          const std::string& command, const std::string& nonce,
+                          context*& subCtx, bool& isPty);
+
+    // 等待本条命令完成（done || closed || 超时）。done=保持会话；closed/超时=清理会话+路由。
+    bool WaitTermCommand(uint64_t device_id, std::vector<BYTE>& out, int& exitCode,
+                         bool& closed, int timeoutMs);
+
+    // 关闭持久终端（校验 sessionId；CancelIO + 清理路由/会话）。
+    // 返回：0=已关闭；1=会话不存在（幂等）；2=sessionId 不匹配（调用方报错）。
+    int CloseTermSession(uint64_t device_id, const std::string& sessionId);
+
+    // idle 回收：关闭 lastActiveAt 超时且非 busy 的持久会话。返回回收数量。
+    int SweepIdleTerminals(time_t idleTimeoutSec);
+
+    // 安全配置（启动时由 CMy2015RemoteDlg 读 THIS_CFG 后设置）。
+    void SetReadonly(bool readonly) { m_readonly = readonly; }
+    void SetCmdWhitelist(const std::string& whitelist) { m_cmdWhitelist = whitelist; }
+    bool IsReadonly() const { return m_readonly; }
+    const std::string& GetCmdWhitelist() const { return m_cmdWhitelist; }
+
 private:
    CMcpServer();
    ~CMcpServer();
@@ -131,6 +196,33 @@ private:

    // get_screenshot 的 reqId 发生器（16 位，跳过 0）。与 MFC 预览的 m_PreviewReqId 各自独立计数。
    std::atomic<uint16_t>        m_PreviewReqId{1};
+
+    // ===== P3：exec_command 终端会话（受 m_TermMutex 保护）=====
+    struct TermSession {
+        bool              started = false;   // false=已发 COMMAND_SHELL 待 START；true=已接管
+        context*          subCtx  = nullptr; // shell 子连接上下文
+        bool              isPty   = false;   // true=ConPTY(UTF-8)；false=老 cmd 管道(GBK)
+        std::string       command;           // 原始 UTF-8 命令（审计用）
+        std::string       nonce;             // 哨兵随机串
+        std::vector<BYTE> data;              // 收集的原始 shell 输出
+        size_t            sentPos = 0;       // 哨兵在 data 中的位置
+        int               exitCode = -1;
+        bool              done = false;      // 哨兵命中
+        bool              closed = false;    // TOKEN_TERMINAL_CLOSE（进程退出）
+        // ===== 新增（持久终端）=====
+        std::string       sessionId;         // 持久会话 token（一次性 exec 为空）
+        bool              persistent = false;
+        bool              busy = false;      // 一条命令在飞（terminal_exec 复位→WaitTermCommand 返回）
+        time_t            lastActiveAt = 0;  // idle 回收用（秒）
+    };
+    std::mutex                       m_TermMutex;
+    std::condition_variable          m_TermCv;
+    std::map<uint64_t, TermSession>  m_TermSessions;         // device_id → 会话
+    std::map<context*, uint64_t>     m_TermContextToDevice;  // subCtx → device_id（顶部路由）
+
+    bool        m_readonly = true;
+    std::string m_cmdWhitelist;
+    bool        m_terminalEnabled = false;   // 持久终端开关（默认关；要求 m_readonly=false）
 };

 // 全局访问器（仿 WebService()，见 WebService.h 末尾）
@@ -46,6 +46,52 @@ void BuildDialogTemplate(std::vector<BYTE>& out, LPCWSTR caption, short cx, shor
    while (out.size() % 4) out.push_back(0); // DWORD align
 }

+// 把白名单文本规范化为「逗号分隔、逐项去首尾空白、去空项」的存储格式。
+// 换行视作分隔符（与逗号等价），便于多行输入。
+std::string NormalizeWhitelist(const std::string& raw)
+{
+    std::string norm;
+    norm.reserve(raw.size());
+    for (char ch : raw)
+        norm += (ch == '\r' || ch == '\n') ? ',' : ch;
+
+    std::vector<std::string> items;
+    size_t start = 0;
+    while (start < norm.size()) {
+        size_t comma = norm.find(',', start);
+        std::string item = norm.substr(start, comma == std::string::npos ? std::string::npos : comma - start);
+        size_t b = item.find_first_not_of(" \t\r\n");
+        if (b != std::string::npos) {
+            size_t e = item.find_last_not_of(" \t\r\n");
+            item = item.substr(b, e - b + 1);
+        } else {
+            item.clear();
+        }
+        if (!item.empty()) items.push_back(item);
+        if (comma == std::string::npos) break;
+        start = comma + 1;
+    }
+
+    std::string out;
+    for (size_t i = 0; i < items.size(); ++i) {
+        if (i) out += ",";
+        out += items[i];
+    }
+    return out;
+}
+
+// 存储格式（逗号分隔）→ 多行展示（每行一条）。
+std::string WhitelistForDisplay(const std::string& stored)
+{
+    std::string disp;
+    disp.reserve(stored.size());
+    for (char ch : stored) {
+        if (ch == ',') disp += "\r\n";
+        else disp += ch;
+    }
+    return disp;
+}
+
 } // namespace

 BEGIN_MESSAGE_MAP(CMcpSettingsDlg, CDialog)
@@ -60,7 +106,7 @@ INT_PTR CMcpSettingsDlg::DoModal()
 {
    USES_CONVERSION;
    CString title = _TR("MCP设置");
-    BuildDialogTemplate(m_Template, T2CW(title), 320, 150);
+    BuildDialogTemplate(m_Template, T2CW(title), 320, 360);
    InitModalIndirect((LPCDLGTEMPLATE)m_Template.data());
    return CDialog::DoModal();
 }
@@ -87,6 +133,16 @@ BOOL CMcpSettingsDlg::OnInitDialog()
    m_lblToken.Create(_TR("Token"), WS_CHILD | WS_VISIBLE, r0, this, (UINT)-1);
    m_editToken.Create(WS_CHILD | WS_VISIBLE | WS_BORDER | WS_TABSTOP | ES_AUTOHSCROLL,
                       r0, this, IDC_MCP_TOKEN);
+    m_btnReadonly.Create(_TR("只读模式（禁命令执行）"),
+                         WS_CHILD | WS_VISIBLE | WS_TABSTOP | BS_AUTOCHECKBOX,
+                         r0, this, IDC_MCP_READONLY);
+    m_btnTerminal.Create(_TR("启用持久终端（全命令，无白名单）"),
+                         WS_CHILD | WS_VISIBLE | WS_TABSTOP | BS_AUTOCHECKBOX,
+                         r0, this, IDC_MCP_TERMINAL);
+    m_lblWhitelist.Create(_TR("命令白名单"), WS_CHILD | WS_VISIBLE, r0, this, (UINT)-1);
+    m_editWhitelist.Create(WS_CHILD | WS_VISIBLE | WS_BORDER | WS_TABSTOP |
+                           ES_MULTILINE | ES_AUTOVSCROLL | ES_WANTRETURN | WS_VSCROLL,
+                           r0, this, IDC_MCP_WHITELIST);
    m_btnOK.Create(_TR("确定"), WS_CHILD | WS_VISIBLE | WS_TABSTOP | BS_DEFPUSHBUTTON,
                   r0, this, IDOK);
    m_btnCancel.Create(_TR("取消"), WS_CHILD | WS_VISIBLE | WS_TABSTOP | BS_PUSHBUTTON,
@@ -102,6 +158,10 @@ BOOL CMcpSettingsDlg::OnInitDialog()
        m_editBind.SendMessage(WM_SETFONT, (WPARAM)hFont, MAKELPARAM(TRUE, 0));
        m_lblToken.SendMessage(WM_SETFONT, (WPARAM)hFont, MAKELPARAM(TRUE, 0));
        m_editToken.SendMessage(WM_SETFONT, (WPARAM)hFont, MAKELPARAM(TRUE, 0));
+        m_btnReadonly.SendMessage(WM_SETFONT, (WPARAM)hFont, MAKELPARAM(TRUE, 0));
+        m_btnTerminal.SendMessage(WM_SETFONT, (WPARAM)hFont, MAKELPARAM(TRUE, 0));
+        m_lblWhitelist.SendMessage(WM_SETFONT, (WPARAM)hFont, MAKELPARAM(TRUE, 0));
+        m_editWhitelist.SendMessage(WM_SETFONT, (WPARAM)hFont, MAKELPARAM(TRUE, 0));
        m_btnOK.SendMessage(WM_SETFONT, (WPARAM)hFont, MAKELPARAM(TRUE, 0));
        m_btnCancel.SendMessage(WM_SETFONT, (WPARAM)hFont, MAKELPARAM(TRUE, 0));
    }
@@ -112,11 +172,18 @@ BOOL CMcpSettingsDlg::OnInitDialog()
    std::string bind = THIS_CFG.GetStr("settings", "McpBind", "127.0.0.1");
    std::string tok = THIS_CFG.GetStr("settings", "McpToken", "");
    if (tok.empty()) tok = GenerateRandomToken();
+    int readonly = THIS_CFG.GetInt("settings", "McpReadonly", 1);
+    int terminal = THIS_CFG.GetInt("settings", "McpTerminal", 0);
+    std::string whitelist = THIS_CFG.GetStr("settings", "McpCmdWhitelist", "");

    m_btnEnable.SetCheck(enabled ? BST_CHECKED : BST_UNCHECKED);
    m_editPort.SetWindowText(CString(std::to_string(port).c_str()));
    m_editBind.SetWindowText(CString(bind.c_str()));
    m_editToken.SetWindowText(CString(tok.c_str()));
+    m_btnReadonly.SetCheck(readonly ? BST_CHECKED : BST_UNCHECKED);
+    m_btnTerminal.SetCheck(terminal ? BST_CHECKED : BST_UNCHECKED);
+    // 白名单存储为逗号分隔，展示为每行一条。
+    m_editWhitelist.SetWindowText(CString(WhitelistForDisplay(whitelist).c_str()));

    LayoutControls(cli.Width(), cli.Height());
    return TRUE;
@@ -124,11 +191,14 @@ BOOL CMcpSettingsDlg::OnInitDialog()

 void CMcpSettingsDlg::OnOK()
 {
-    CString sPort, sBind, sToken;
+    CString sPort, sBind, sToken, sWhitelist;
    m_editPort.GetWindowText(sPort);
    m_editBind.GetWindowText(sBind);
    m_editToken.GetWindowText(sToken);
+    m_editWhitelist.GetWindowText(sWhitelist);
    bool enabled = (m_btnEnable.GetCheck() == BST_CHECKED);
+    bool readonly = (m_btnReadonly.GetCheck() == BST_CHECKED);
+    bool terminal = (m_btnTerminal.GetCheck() == BST_CHECKED);

    // 端口校验：1-65535
    int port = atoi(CT2A(sPort));
@@ -151,10 +221,16 @@ void CMcpSettingsDlg::OnOK()
    THIS_CFG.SetInt("settings", "McpPort", port);
    THIS_CFG.SetStr("settings", "McpBind", bind);
    THIS_CFG.SetStr("settings", "McpToken", token);
+    THIS_CFG.SetInt("settings", "McpReadonly", readonly ? 1 : 0);
+    THIS_CFG.SetInt("settings", "McpTerminal", terminal ? 1 : 0);
+    std::string whitelist = CT2A(sWhitelist);
+    whitelist = NormalizeWhitelist(whitelist);
+    THIS_CFG.SetStr("settings", "McpCmdWhitelist", whitelist);

    // 拆成两段可翻译的单行键，中间用 \r\n 连接（多行键无法在 INI 中表示）
    MessageBox(_TR("MCP 设置已保存。") + _T("\r\n") +
-               _TR("启用/端口/绑定地址/Token 的改动需重启程序生效。"),
+               _TR("启用/端口/绑定地址/Token/只读/白名单/持久终端的改动需重启程序生效。") + _T("\r\n") +
+               _TR("持久终端仅在只读模式关闭时生效。"),
               _TR("提示"), MB_ICONINFORMATION);

    CDialog::OnOK();
@@ -185,6 +261,17 @@ void CMcpSettingsDlg::LayoutControls(int cx, int cy)
    m_editToken.MoveWindow(margin + labelW, y - 2, cx - margin * 2 - labelW, rowH);
    y += rowH + gap;

+    m_btnReadonly.MoveWindow(margin, y, cx - margin * 2, 22);
+    y += 30;
+
+    m_btnTerminal.MoveWindow(margin, y, cx - margin * 2, 22);
+    y += 30;
+
+    const int whitelistH = 90;
+    m_lblWhitelist.MoveWindow(margin, y, labelW, rowH);
+    m_editWhitelist.MoveWindow(margin + labelW, y - 2, cx - margin * 2 - labelW, whitelistH);
+    y += whitelistH + gap;
+
    int bottomY = cy - margin - btnH;
    m_btnCancel.MoveWindow(cx - margin - btnW, bottomY, btnW, btnH);
    m_btnOK.MoveWindow(cx - margin - btnW * 2 - gap, bottomY, btnW, btnH);
@@ -26,11 +26,18 @@ private:
        IDC_MCP_PORT   = 1002,  // 端口编辑框
        IDC_MCP_BIND   = 1003,  // 绑定地址编辑框
        IDC_MCP_TOKEN  = 1004,  // Token 编辑框
+        IDC_MCP_READONLY  = 1005,  // 「只读模式」复选框（默认勾选，禁 exec_command）
+        IDC_MCP_WHITELIST = 1006,  // 命令白名单编辑框（多行，逗号/换行分隔，空 = 内置只读前缀）
+        IDC_MCP_TERMINAL  = 1007,  // 「启用持久终端」复选框（全命令，无白名单，要求只读关）
    };

    CButton m_btnEnable;
    CStatic m_lblPort, m_lblBind, m_lblToken;
    CEdit   m_editPort, m_editBind, m_editToken;
+    CButton m_btnReadonly;
+    CButton m_btnTerminal;
+    CStatic m_lblWhitelist;
+    CEdit   m_editWhitelist;
    CButton m_btnOK, m_btnCancel;

    std::vector<BYTE> m_Template;  // 内存 DLGTEMPLATE 字节
@@ -1987,4 +1987,10 @@ MCP
 端口需为 1-65535 的数字=Port must be a number between 1 and 65535
 Token 不能为空=Token cannot be empty
 MCP 设置已保存。=MCP settings saved.
-启用/端口/绑定地址/Token 的改动需重启程序生效。=Changes to enable/port/bind address/token take effect after restart.
+启用/端口/绑定地址/Token/只读/白名单/持久终端的改动需重启程序生效。=Changes to enable/port/bind/token/read-only/whitelist/persistent terminal take effect after restart.
+只读模式（禁命令执行）=Read-only mode (disable command execution)
+命令白名单=Command whitelist
+MCP命令执行=MCP command execution
+启用持久终端（全命令，无白名单）=Enable persistent terminal (full commands, no whitelist)
+持久终端仅在只读模式关闭时生效。=Persistent terminal takes effect only when read-only mode is off.
+MCP持久终端=MCP persistent terminal
@@ -1978,4 +1978,10 @@ MCP
 端口需为 1-65535 的数字=連接埠需為 1-65535 的數字
 Token 不能为空=Token 不能為空
 MCP 设置已保存。=MCP 設定已儲存。
-启用/端口/绑定地址/Token 的改动需重启程序生效。=啟用/連接埠/綁定位址/Token 的變更需重新啟動程式後生效。
+启用/端口/绑定地址/Token/只读/白名单/持久终端的改动需重启程序生效。=啟用/連接埠/綁定位址/Token/唯讀/白名單/持久終端的變更需重新啟動程式後生效。
+只读模式（禁命令执行）=唯讀模式（禁命令執行）
+命令白名单=命令白名單
+MCP命令执行=MCP命令執行
+启用持久终端（全命令，无白名单）=啟用持久終端（完整命令，無白名單）
+持久终端仅在只读模式关闭时生效。=持久終端僅在唯讀模式關閉時生效。
+MCP持久终端=MCP持久終端