執行工具
執行指令與管理套件的工具。
| 工具 | 說明 |
|---|---|
run_command |
以 argv 執行程式（argv-only schema，透過 go-pkg/sandbox 包裹沙箱）。不含 shell metacharacter（|、&&、>、*、~）的單純指令直接呼叫，不會被包進 sh；pipe、重導向與 globbing 需明確使用 ['sh','-c','...']，其腳本會被逐指令解析驗證 —— 每個執行檔都必須是裸指令名，列於 denied_command 者一律拒絕。['cd','<path>'] 為特例，驗證路徑後會變更 Executor.WorkDir；rm 會改為移入垃圾桶而非刪除。自 v1.0.25 起沙箱預設關閉網路：需要連線的指令（git clone / fetch / pull / push、npm / pip / brew install、go mod download、curl）須設定 network: true，而這類呼叫永不視為唯讀，一律經過確認 gate。唯讀 allowlist（configs/jsons/read_only_command.json，410 筆，並合併 config.json 的 read_only_command）上的指令跳過確認 gate：自 v1.0.25 起比對執行檔加上最多兩個後續參數（git status、docker ps、kubectl get、ls...），任一參數為敏感路徑時取消比對結果。v1.0.23 新增的專用唯讀指令工具（run_command_readonly，可並行執行）已於 v1.0.25 移除，短暫存在的 run_script 則從未進入正式版本；請改用 run_command，它一律循序執行。要寫到 $HOME 之外時，該次呼叫帶上 write_paths，經密碼驗證核准後才綁入。sudo 一律拒絕（無論單獨執行或在 sh -c 內），並提示去掉 sudo 改宣告 write_paths，由此觸發 sudo 確認。自 v1.0.11 起 file watcher 在啟動前就被擋下：--watch / --watch=...、chokidar 執行檔，或解析後會跑到 watcher 的 npm / pnpm / yarn / bun script —— package script 會從 package.json 解析出來並最多往下追 5 層，sh -c 內的也一樣 —— 因為 run_command 會等行程結束，而 watcher 永遠不會結束。錯誤訊息會指出該改跑哪個 one-shot build |
pkg_manage |
在沙箱外驅動 Linux 套件管理器（apt / dnf / yum / pacman / apk），讓 bwrap 無法授予的 root 操作仍可運作。action 為 install / remove / update / upgrade / search / info；package 只接受裸套件名 —— 不帶旗標、不指定版本、不接受第二個套件 —— 除 update 與 upgrade 外皆為必填。僅在 Linux 註冊。run_command 無法取代：sudo 在 bwrap 內沒有作用。語言執行環境（node / python）→ 以 run_command 搭配 mise、fnm 或 uv；語言層套件（pip / npm / cargo）→ run_command |