Repository navigation
Releases
Releases · UnpxreTW/Bellhop
v1.0.0
Bellhop 定版——介面經 review 定案,四個子系統完整:Terminal 控制、子程序執行、視窗控制、螢幕截圖。自 v0.1.0 以來的變更:
新工具
screen_capture:截圖(全螢幕/指定 Terminal 視窗,CGWindowID 精準對位+region fallback)- 視窗子系統六顆:
window_list/window_save_layout/window_layout_list(唯讀、零新權限)+window_focus/window_set_frame/window_restore_layout(需 Accessibility 權限,未授權回可行動錯誤)
子程序執行強化
- 逾時保護+SIGTERM→寬限→SIGKILL 升級路徑;SIGKILL 後等待補上限(
abandoned獨立狀態) - Task 取消即終止子程序,且取消不再等滿逾時窗
- 輸出
truncated標記區分「表面成功」與「真成功」;逾時錯誤帶出已收到的輸出供診斷
其他
- CI build/test 分檔;SwiftStyleKit 2.1.0。
下載與驗證
附件:Bellhop(arm64 執行檔)、SHA256SUMS。
shasum -a 256 -c SHA256SUMS # 驗 integrity
xattr -dr com.apple.quarantine Bellhop # 去 Gatekeeper quarantine本版只附 arm64(Apple Silicon)。Intel 或要 universal 請自行
swift build -c release(見 README〈開發〉)。
v0.1.0
下載與驗證
附件:Bellhop(arm64 執行檔)、SHA256SUMS。
shasum -a 256 -c SHA256SUMS # 驗 integrity
xattr -dr com.apple.quarantine Bellhop # 去 Gatekeeper quarantineSHA-256(Bellhop) = c53a00464fc3244dff65acbfa09900973e8357846b758517ccfdbf0cef11c71b
本版只附 arm64(Apple Silicon)。Intel 或要 universal 請自行
swift build -c release(見 README〈開發〉)。
Bellhop 的第一個版本——用 Swift 寫的 MCP server,讓 MCP client(Claude Code 等)透過具名、強型別的工具操作 macOS。本版提供 Terminal.app 控制三工具,全走 Apple Event(osascript)、不靠 GUI 截圖點擊,螢幕鎖定下也可達。
工具
| 工具 | 作用 | 參數 |
|---|---|---|
terminal_open |
開新 Terminal 視窗,可選 cd 進目錄再跑命令,回傳新分頁識別碼 | command、cwd(皆可選) |
terminal_run |
在指定 window_id 的視窗跑命令;視窗忙碌(有前景程式在跑)就拒跑、不注入 |
command、window_id(皆必填) |
terminal_list_windows |
列出開啟中的視窗 id、標題、busy 狀態 |
無 |
設計
- 具名工具,不是通用 runner:每個工具有 JSON Schema 參數,不暴露 generic
run_shell。 - Apple Event、非 GUI:
do script鎖屏可達;不走 computer-use 截圖點擊。 terminal_run安全守則:執行前查busy of window,忙碌就回isError。do script是「把命令打進該視窗當前程式」,故只在視窗閒置於 shell 提示字元時乾淨執行——跑著程式的視窗(含其他 Claude/編輯器 session)自動受保護、不被誤注入。
安裝
swift build -c release註冊(寫進 ~/.claude.json 頂層 mcpServers,與其他 server 同層):
"bellhop": {
"type": "stdio",
"command": "/絕對路徑/Bellhop/.build/release/Bellhop"
}claude mcp list 應顯示 bellhop ✔ Connected。
需求
- macOS 14+
- Swift 6.2(Xcode 26+)
- Terminal.app 已授 Automation 權限給
osascript