ssmcp 統一工作空間橋接器 是做什麼的?
探索機器及其能力
首先呼叫 list。使用每個客戶端的選用 title 來理解其任務,然後檢查其 name 與 cwd。透過其回傳的 id 來選擇客戶端;標題、名稱與主機名稱僅為標籤,可能重複。在 code_mode 中使用 tools.search(clientId,{query,limit:20}) 來定位精簡的工具摘要;在呼叫前,可請求 include_schemas:true 以取得完整的原生描述。在較舊的 Broker 上,使用 list({client_id}) 或 tools(clientId,cursor) 進行分頁。請尊重每個原生後端的權限與核准政策。
每次工具目錄遍歷都應停留在其回傳的游標上。其頁面共享一個快照,即使原生工具目錄發生變更亦然;發出一個不含游標的新請求以發現更新。一個客戶端最多保留四個快照與總共 64 MiB 的序列化 JSON。每次成功的頁面讀取會重置 120 秒的空閒逾時,但快照在建立後最多 900 秒就會過期。無效的游標不會重置逾時,且重複使用未變更的目錄不會重置其建立時間;LRU 與容量限制可能會提前將其回收。如果伺服器回報快照已過期或已回收,請重新啟動探索。
目前的客戶端以 type:"shell" 連接,並提供一個主要互動式終端機、額外的獨立終端機、獨立指令工作、檔案與上下文工具,無需 Harness。背景探索會檢查已安裝的 Provider,僅註冊那些版本、啟動策略、握手與實際目錄皆可用的介面。ssmcp.harnesses.list 會回報狀態與診斷資訊;不可用的 Provider 不會移除 Shell 或其他工具。從啟動指令中移除過時的 -t、--type、--backend 以及尾隨的後端參數。
探索不得安裝執行環境、依賴項或 Harness、提交模型請求,或放寬原生權限。請勿將離線套件快取視為不會安裝任何東西的證明。未經驗證安全啟動的 Provider 將保持不可用。Pi 探索僅透過 SSMCP_PI_RPC_SOCKET 連接到一個已明確設定、已初始化的原生 JSONL RPC 工作階段。絕對 Unix socket 及其直屬父目錄必須屬於目前 UID,不得具有群組/其他權限,且不得為符號連結;在五秒的 get_state 握手前,會檢查連接的對等 UID、已安裝的二進位檔與版本。OpenCode 探索僅附加到一個位於 http://127.0.0.1:PORT/ 的現有服務(SSMCP_OPENCODE_URL、OPENCODE_PASSWORD)。需要明確的連接埠與根路徑;代理、重新導向、其他主機、使用者資訊、查詢與片段都會被拒絕。原生探索僅讀取資訊與 OpenAPI;事件訂閱是延遲的。遺失的端點意味著不可用。兩個轉接器都不會啟動外部服務或停用使用者擴充功能來製造完整的目錄。
list 與 tools 使用同一個註冊表,保留具有路由命名空間的原生 Schema 與描述。命名空間包括 codex.*、claude.*、pi.*、opencode.*,以及在其原生 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 工具 Schema 的列舉。
透過 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 "Describe this session's task" --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 陣列、授權工作空間內可選的現有 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 讀取較舊的位元組。如果在啟動後觀察失敗,請在重試前使用 status/read 檢查錯誤的 job_id;請勿啟動重複的工作。
使用 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 時,保持相同的 client/query/limit/schema 選項。搜尋減少了模型可見的目錄輸出與手動分頁,而非第一個底層頁面掃描。每個頁面仍需授權並計入呼叫預算;使用 max_pages 進行有限的工作。已變更或已過期的頁面需要重新啟動探索。過大的 Schema 會明確失敗,而非被截斷。請參閱 ssmcp://limits 了解預算;此輔助函式需要更新的 Broker。
使用 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 結果。Schema 仍具有權威性。對於獨立的原生呼叫,使用 Promise.all;每個呼叫都需個別授權。並行的 Cargo 指令仍可能爭奪其共享的建置鎖。
重複使用操作員現有的 Chrome
當使用者指名一個現有的 Chrome 工作階段時,從 call(id,"ssmcp.browser.discover",{}) 與 ssmcp.harnesses.list 開始。探索會讀取元資料;已安裝的擴充功能檔案不會建立已配對、已授權的連線。除非驗證過程明確要求且使用者同意,否則請勿啟動隔離的設定檔或瀏覽器二進位檔。檢查已發現的瀏覽器擴充功能,如果找到配對的 "Chrome MCP",請透過其已發現的 ssmcp.browser.tool 名稱呼叫。
如果中繼資料包含 wsEndpoint,請使用 Playwright 的 connect_over_cdp 連接到該端點。驗證 webSocketDebuggerUrl 是否是 ws://127.0.0.1:*,並確保所有網路請求都保留在本地主機。call(id,"playwright.connect",{wsEndpoint, ...}) 會設定一個受支援的瀏覽器連線。
只有在探索成功時,才在 code_mode 的 availableFunctions 中使用瀏覽器工具。所有 ssmcp 瀏覽器工具都共享同一個配對的瀏覽器工作階段。
設定 Linux rsync 傳輸
使用基於 rsync 的檔案傳輸,在客戶端之間或客戶端與本機工作空間之間複製目錄樹與檔案。Rsync 必須安裝在來源與目標主機上。
選項應為單一字串,或是一組字串/值的列表。如果省略,ssmcp 使用 "-avz"。如果 use_sudo:true,來源讀取與目標寫入兩者都使用 sudo。傳輸支援進度事件、基於工作 ID 的取消、exclude 與 include 模式篩選(也支援 --exclude-from=FILE),以及 max_size 跳過。傳輸預設為非遞迴,並遵守操作員的 SSH 金鑰政策。透過 jobs.* 管理 rsync 工作:
| 輔助函式 | 用途 |
|---|---|
jobs.run | 啟動雙向 rsync 傳輸工作 |
jobs.list | 列出所有傳輸工作及其狀態 |
jobs.events | 讀取工作進度事件 |
jobs.status | 檢查特定傳輸工作的狀態 |
jobs.cancel | 取消執行中的傳輸工作 |
jobs.forget | 從保留記錄中移除工作 |
jobs.output | 讀取傳輸的輸出日誌 |
使用 jobs.run(id,{source,target,options,use_sudo,cwd,type:"up"|"down"|"sync"})。預設的 type 為 "sync"。一個客戶端最多可以有 4 個執行中的傳輸與 32 個保留的工作記錄。
設定迴路 TCP 轉發
使用 ssmcp.listen 在客戶端上建立一個 TCP 監聽端點,以允許從主機工作空間(或在配置時從其他位置)到客戶端網路的 TCP 連線。實現迴路轉發。
const listener = await call(id, "ssmcp.listen", {
host: "127.0.0.1", // 在客戶端上繫結的介面
port: 8080, // 在客戶端上繫結的連接埠
forward: {
host: "internal.service.local", // 轉發目標主機
port: 80 // 轉發目標連接埠
}
});
ssmcp.listen 會回傳一個監聽器,其狀態為 "listening" 或 "error"。在 code_mode 完成時,所有監聽器會自動關閉。
批次傳送資源
const resources = await resources.read(id, [
"ssmcp://guide",
"ssmcp://limits",
"ssmcp://clients"
]);
對於客戶端特定的 URI,使用 resources.templates(id).flatMap(t => t.uriTemplate(...)) 解析。
使用離線資源搜尋
const ids = [
{ id: "dev", root: "/home/user/projects/" },
{ id: "docs", root: "/var/docs/" }
];
const results = await tools.search(ids, { query: "authentication", limit: 20 });
跨多個客戶端搜尋。每個結果包含 clientId 與 root。
覆蓋原生憑證
await exec.credentials(id, {
host: "git.example.com",
type: "ssh",
username: "git",
privateKey: "..." // 選擇性
});
這會將憑證提供給原生 CLI。覆蓋是短暫的,並與客戶端工作階段綁定;它們不會被保留。
重新整理與重新載入
使用 reload(id,{register_harnesses:true}) 來要求客戶端重新載入其 Harness 與工具目錄,無需中斷現有工作階段。客戶端會重新評估其已安裝的 Harness,但會保持其快照與執行中工作不變。
使用 refresh(id) 來要求客戶端重新掃描其檔案系統(例如,針對 skills/agents)。
保留資源
客戶端資源會受到其原生 MCP 伺服器配置的限制。在發出多個記憶體密集型請求時,請注意客戶端串流、快照大小與連線數量的限制。在長時間執行的工作階段中,請監控客戶端健康狀態,並處理具有新鮮探索結果的斷線。
設定 User-Agent
ssmcp MCP 伺服器會回報一個 user-agent 字串,用於識別伺服器。使用 user-agent 進行記錄與相容性檢查。