MCP — AI 控制

Terminality 既是可见桌面应用，也能在同一进程中提供 MCP。AI 代理通过六个类型化工具操作人类正在看到的同一批 Session。

可选的 HTTP 服务默认停止并只监听本机；只有用户主动修改后才会扩大网络范围。

快速开始

{
  "mcpServers": {
    "szt": {
      "command": "/path/to/szt-desktop",
      "args": ["--mcp"]
    }
  }
}

使用 --mcp 启动后，Terminality 正常打开应用窗口，同时在 stdin / stdout 上提供 MCP；客户端关闭传输时，进程随之退出。

工具

工具	作用
szt_list_session_create_info	列出实时 QCS 目标与连接方式
szt_create_session	用不透明的 createInfoId 创建并聚焦 AI 可见 Tab
szt_list_sessions	列出人类与 AI 创建的全部可见 Session
szt_close_session	结束连接，但保留已结束的 Tab
szt_list_session_operations	返回实时操作、输入输出 Schema 与安全标记
szt_operate_session	调用一个当前已发布的操作

Session 模型

Pane 只负责展示和布局；MCP 的公开能力是由 libszt RemoteControlService 投影出来的稳定可见 Session。

字段	含义
sessionId	某一代可见内容的稳定能力 ID
runtimeSessionId	可选的私有终端运行时 ID；工具输入永远不需要它
origin	human 或 ai
kind	localTerminal、sshTerminal、sftpFiles、omini 等
state	pending、running、ready、disconnected、ended 等真实状态

替换 Pane 内容会轮换公开 Session ID，迟到操作无法触达同一布局位置里的新连接。终端重连只会轮换私有运行时 ID。关闭连接后 Tab 仍保留；MCP 不提供布局删除原语。

操作能力

每次操作前都应重新发现能力：

• 本地、SSH、Telnet 与 Omini 终端提供 terminal.read、terminal.input。输入是精确 UTF-8；只有显式设置 appendEnter 才会追加回车。
• SFTP 与 Omini 文件提供 files.list、files.startUpload、files.startDownload、files.viewTask、files.listTasks，以及暂停、恢复、取消、重试任务操作。

传输启动后立即返回 taskId，任务与全局传输抽屉共用同一个 TransferService。尚未实现适配器的 Session 返回空操作列表。

安全

• terminal.input 与 szt_operate_session 被标记为破坏性、非幂等、开放世界操作；客户端应保持审批策略。
• Session 操作会激活所属窗口、聚焦 Pane 并将窗口置前，AI 行为始终可见。
• 每次上传或下载都会在原生窗口中展示确切本地路径与冲突策略；用户单次批准后，libszt 才能打开自动化提供的路径。
• 应用持续显示 MCP 连接状态与最近一次操作。
• 每次 stdio 客户端启动拥有独立可见进程；可选的设置托管 HTTP 服务默认只监听本机，暴露到局域网时强制认证。

szt_list_session_create_info
  → szt_create_session(createInfoId)
  → szt_list_session_operations(sessionId)
  → szt_operate_session(sessionId, operationId, arguments)
  → 用 files.viewTask 观察 taskId
  → 遇到过期会话：重新列出，不盲目重试