ssmcp 统一工作空间桥接
发现机器及其能力
先调用 list。使用每个客户端的可选 title 来理解其任务,然后检查其 name 和 cwd。通过返回的 id 选择客户端;标题、名称和主机名是标签,可能会重复。在 code_mode 内部使用 tools.search(clientId,{query,limit:20}) 来定位简洁的工具摘要;在调用之前请求 include_schemas:true 以获取完整的原生描述符。在较旧的代理上,使用 list({client_id}) 或 tools(clientId,cursor) 分页。尊重每个原生后端的权限和批准策略。
每次工具目录遍历都在其返回的光标上进行。即使原生工具目录发生变化,其页面也共享同一个快照;发起一个新的无光标请求以发现更新。一个客户端最多保留四个快照和总共 64 MiB 的序列化 JSON。每次成功的页面读取都会重置 120 秒的空闲超时,但快照在创建后最多 900 秒后过期。无效的光标不会重置超时,重新使用未更改的目录也不会重置其创建时间;LRU 和容量限制可能更早地将其驱逐。如果服务器报告快照已过期或被驱逐,请重新开始发现。
当前客户端以 type:"shell" 连接,并提供主交互式终端、额外的独立终端、独立命令作业、文件和上下文工具,无需工具链。后台发现会检查已安装的提供程序,并仅注册版本、启动策略、握手和实际目录可用的接口。ssmcp.harnesses.list 报告状态和诊断信息;不可用的提供程序不会移除 Shell 或其他工具。从启动命令中移除过时的 -t、--type、--backend 和尾部后端参数。
发现不得安装运行时、依赖项或工具链,提交模型请求,或放宽原生权限。不要将离线包缓存视为不会安装任何东西的证据。没有验证安全启动的提供程序仍然不可用。Pi 发现仅通过 SSMCP_PI_RPC_SOCKET 连接到明确配置且已初始化的原生 JSONL RPC 会话。绝对 Unix 套接字及其直接父目录必须属于当前 UID,没有组/其他权限,并且不是符号链接;在五秒的 get_state 握手之前,会检查连接的 peers UID、已安装的二进制文件和版本。OpenCode 发现仅附加到 http://127.0.0.1:PORT/ 处的现有服务(SSMCP_OPENCODE_URL、OPENCODE_PASSWORD)。需要明确的端口和根路径;拒绝代理、重定向、其他主机、用户信息、查询和片段。原生发现仅读取信息和 OpenAPI;事件订阅是惰性的。缺失的端点意味着不可用。两个适配器都不会启动外部服务或禁用用户扩展来制造完整的目录。
list 和 tools 使用同一个注册表,保留带有路由命名空间的原生模式和描述符。命名空间包括 codex.*、claude.*、pi.*、opencode.*,以及当 Playwright 的原生 MCP 发现成功时还包括 playwright.*;确切的名称来自当前目录。Codex MCP 工具通过原生 mcpServerStatus/list 枚举,并通过 mcpServer/tool/call 转发;选择发现的 codex.mcp.* 名称,无需硬编码服务器。Pi 仅在可用时公开 pi.rpc、ssmcp.pi.events、ssmcp.pi.requests 和 ssmcp.pi.respond 桥接操作。CLI 安装或已知的控制命令列表不是其模型、插件或内部 MCP 工具模式的枚举。
通过 MCP 资源或 code_mode 内的 resources.read(uri) 读取 ssmcp://guide、ssmcp://limits 和 ssmcp://clients。使用 resources.templates() 获取客户端特定的资源。当连接的客户端版本较旧时,检查当前目录。
code_mode 在 MCP 服务器上运行。其文件系统和回环网络不是调用者的工作区。要将沙箱或其他计算机包含在传输中,请在该环境中运行单独的 ssmcp 客户端,并选择其返回的 ID。从要共享的目录启动它:
cd /path/to/workspace
ssmcp --name workspace --title "描述此会话的任务" --allow YOUR_GITHUB_LOGIN@github [email protected]
使用运营商配置的 SSH 目标和授权身份。不要复制私有 SSH 密钥、禁用主机密钥检查或绕过网络策略。如果调用者环境无法连接,请报告该确切限制并继续处理可访问的对等点。
检查可用的技能和指令文件
使用 context.roots(id) 查看工作区和任何显式的只读上下文根。从 skills.view(id) 开始,获取紧凑的 Markdown 索引,或使用 skills.list(id,options) 获取元数据。使用相同的扫描选项跟随 next_cursor。名称可以重复;通过根和路径选择,然后调用 skills.read(id,{path}) 获取完整的 SKILL.md。
agents.resolve(id,{path:"src/lib.rs"}) 返回指令来源和从根到目标的确切内容。agents.list 仅返回来源,agents.read 读取选定的文件。在每个目录中,ssmcp 选择第一个非空的 AGENTS.override.md、AGENTS.md 或 agents.md。在应用相关指令之前审查出处和诊断信息。
默认根是客户端的启动工作区。运营商可以通过重复的 --context-root PATH 添加最多八个只读根;使用 root 选项显式选择其返回的 ID。直接包含技能文件夹的根可以使用 paths:["."] 进行扫描。这些上下文根不会扩展普通文件写入权限。这是当前的磁盘视图,不是后端模型加载的提示的清单。元数据解析使用文档化的 YAML 子集;读取诊断信息,不要从正文文本推断缺失的描述。
运行和管理命令
使用 exec 执行带有退出状态和单独 stdout/stderr 的独立命令。传递 argv 数组、授权的 workspace 内的可选现有 cwd 以及可选的 env 覆盖。每次启动都会创建一个独立的进程和管道;它不会通过交互式 PTY 排队输入。对于管道或 shell 扩展,显式调用平台 shell。命令不会继承交互式终端内后续的 cd 或环境更改。
const client = clients.find(c => c.id === "CLIENT_ID_FROM_LIST");
if (!client) throw new Error("Select an online client from list");
return await exec.run(client.id, {
command: ["git", "status", "--short"],
cwd: client.cwd,
wait_ms: 5000,
max_bytes: 16384
});
读取 job_id、running、state、exit_code、stdout、stderr、两个输出光标和 snapshot。成功的启动仅确认启动。如果进程元数据包含 pid_role,请在报告 PID 时保留它;监督者 PID 不是命令 PID。仅在 running:false 时评估最终退出状态;即使帮助程序成功解析,非零退出码也是命令失败。snapshot 包含最新的原子状态和输出元数据。wait_timed_out 记录等待步骤;后续读取可能已显示完成。
保持等待与命令生命周期分离。wait_ms 默认为 5000,接受 0..60000;超时后命令仍在运行。命令的 timeout_ms 默认为 0,表示没有执行期限;正值最高 900000 会在超时时终止其进程树。设置足够长的外部 code_mode.timeout_ms 以覆盖整个序列。JavaScript 截止日期不会撤销已启动的命令。
对于长时间运行的工作,使用 exec.start(clientId,{command,cwd}) 启动并立即返回其 job_id。在后续请求中继续:
| 辅助函数 | 目的 |
|---|---|
exec.list(clientId) | 查找正在运行和保留的已完成作业 |
exec.status(clientId,jobId) | 检查当前状态、持续时间、退出码和工件元数据 |
exec.wait(clientId,jobId,{wait_ms:5000}) | 在有限间隔内等待完成 |
exec.read(clientId,jobId,{stdout_cursor,stderr_cursor,max_bytes,wait_ms}) | 读取增量输出和原子 snapshot |
exec.cancel(clientId,jobId) | 终止拥有的进程树并检查返回的状态 |
exec.forget(clientId,jobId) | 释放已完成作业的保留记录 |
exec.events(clientId,{cursor,max_events,wait_ms}) | 读取有限命令事件 |
在读取之间分别携带 stdout_cursor 和 stderr_cursor。每个流每次读取最多返回 32768 字节;*_base64 保留精确字节,*_eof 标识其结尾。如果 *_truncated 为 true,则从相应的 snapshot.stdout.artifact 或 snapshot.stderr.artifact 读取较早的字节。如果启动后观察失败,请在重试之前检查错误的 job_id 并使用 status/read;不要启动重复的工作。
使用 exec.parallel(clientId,[{command:[...]},...],{concurrency:4}) 执行最多 32 个命令,使用 1..8 个工作线程。每个工作线程等待其命令实际结束后再启动下一个;初始 wait_ms:0 永远不会释放正在运行的槽位。结果保持输入顺序,并包含 fulfilled/value 或 rejected/reason。观察失败时,如果可用则保留 job_id 并停止该工作线程;从未启动的排队条目标记为 not_started:true。检查每个退出码,并在重试前恢复不确定的作业。内部有限等待计入 code_mode 的 128 次调用预算和外部超时。对于持久化服务器,使用 exec.start。并行输出默认为每个流 2048 字节。
每个客户端预期最多 32 个正在运行的作业和 128 个保留记录。达到记录限制时,新启的动作会驱逐最旧的已完成作业;正在运行的作业保持注册状态。作业在 code_mode 完成后继续存在,但在客户端断开连接或重新加载时停止。forget 不会立即删除输出工件。使用 exec.* 处理命令;jobs.* 管理 rsync 传输作业。当需要共享的交互式 shell 时,使用 terminal.*,并且不要从一次终端读取推断命令完成。
写入后台输入并选择终端
在调用 exec.write(clientId,jobId,{data,close_stdin:true}) 之前,使用 stdin:"pipe" 启动命令。使用 data_base64 进行二进制输入;切勿同时提供两种形式。每次写入限制为 32 KiB。检查 written、remaining_bytes、timed_out 和 closed;仅重试未写入的后缀。在所有字节被接受后关闭输入会发送 EOF。输入正文不会复制到审计日志中。
使用 terminal.open(clientId,{name,cwd,select}) 启动独立的交互式 shell,然后使用其 terminal_id 进行 terminal.write/read/status/resize。保持输出光标分离。terminal.list 报告选定的本地视图;terminal.select 更改视图和人类键盘目标,而其他会话继续运行。F7 循环切换会话,F6 选择审计日志。省略 terminal_id 始终针对主终端,与选定的视图无关。terminal.close 结束额外的会话;主终端随连接一起结束。最多可以打开 16 个终端。
当当前调用者/模型已知时,将 controller:{name,model} 与外部 code_mode 请求一起传递。客户端将此声明显示为调用者报告,而不是经过验证的提供者身份。切勿从应用程序名称猜测模型。MCP clientInfo 可以标识应用程序;未知模型保持未知。在依赖旧客户端显示声明之前,检查 list 的 controller_metadata。
使用 cua.status 和原生 cua 截图/输入/窗口方法进行计算机使用;cua.browser 共享浏览器方法。使用 image(await cua.screenshot(clientId,args)) 发出截图,并单独返回坐标元数据。通过在其当前工具目录中发现的精确 codex.mcp.* 名称调用 Codex 连接的 CUA MCP。保留原生错误、图像内容和批准状态;不要调用另一个模型来代理这些操作。
执行其他原生工具
const client = clients.find(c => c.id === "CLIENT_ID_FROM_LIST");
if (!client) throw new Error("Select an online client from list");
return await tools.search(client.id, {query:"browser", limit:10, include_schemas:true});
搜索匹配不区分大小写的名称/描述子字符串。默认情况下,它返回名称、观察到的路由命名空间和缩短为 240 个 Unicode 字符的描述;include_schemas 保留完整的原生描述符。在继续使用 nextCursor 时,保持相同的客户端/查询/限制/模式选项。搜索减少模型可见的目录输出和手动分页,而不是第一个底层页面扫描。每个页面仍然经过授权并计入调用预算;使用 max_pages 进行限定的工作。更改或过期的页面需要重新开始发现。过大的模式会显式失败而不是被截断。有关预算,请参阅 ssmcp://limits;该帮助程序需要更新的代理。
调用发现的操作:await call(clientId, toolName, arguments)。检查 isError 并在存在时读取 structuredContent。简短结果保持内联;过大的后端结果返回工件元数据而不是完整正文。等待每个调用。仅返回任务所需的输出。除非用户授权,否则切勿通过原生后端启动代理或模型。
原生命令原语是 ssmcp.exec.start/list/status/wait/read/write/cancel/events,加上用于已完成记录的 ssmcp.exec.forget。当较旧的服务器缺少 exec 帮助程序时,使用 call(clientId, toolName, arguments) 调用这些发现的工具,并检查完整的 MCP 结果。模式仍然是权威的。对于独立的原生调用,使用 Promise.all;每个调用都单独授权。并发的 Cargo 命令仍然可能争夺其共享的构建锁。
重用操作员现有的 Chrome
当用户命名现有的 Chrome 会话时,从 call(id,"ssmcp.browser.discover",{}) 和 ssmcp.harnesses.list 开始。发现读取元数据;已安装的扩展文件不建立配对、授权的连接。不要启动隔离的 prof