Dropstone CLI

權限

控制哪些操作需要核准才能執行。

Dropstone 使用 permission 設定來決定某個操作應該自動執行、提示你核准，還是遭到封鎖。

舊版的 tools 布林值設定已棄用；它已併入 permission。舊的 tools 設定仍受支援以維持向後相容性。

操作

每個權限規則會解析為以下其中一種：

  • "allow"：不需核准即可執行
  • "ask"：提示要求核准
  • "deny"：封鎖該操作

設定

你可以全域設定權限（使用 *），並覆寫特定工具。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "*": "ask",
    "bash": "allow",
    "edit": "deny"
  }
}

你也可以一次設定所有權限：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": "allow"
}

精細規則（物件語法）

對於大多數權限，你可以使用物件來根據工具輸入套用不同的操作。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny",
      "grep *": "allow"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    }
  }
}

規則會依模式比對進行評估，最後符合的規則勝出。常見的模式是將萬用字元 "*" 規則放在最前面，然後在後面放置更具體的規則。

萬用字元

權限模式使用簡單的萬用字元比對：

  • * 符合零個或多個任意字元
  • ? 完全符合一個字元
  • 所有其他字元會逐字比對

家目錄展開

你可以在模式開頭使用 ~ 或 $HOME 來參照你的家目錄。這對於 external_directory 規則特別有用。

  • ~/projects/* -> /Users/username/projects/*
  • $HOME/projects/* -> /Users/username/projects/*
  • ~ -> /Users/username

外部目錄

使用 external_directory 來允許觸及 Dropstone 啟動時工作目錄以外路徑的工具呼叫。這適用於任何以路徑作為輸入的工具（例如 read、edit、glob、grep 以及許多 bash 指令）。

家目錄展開（例如 ~/...）只會影響模式的撰寫方式。它不會讓外部路徑成為目前工作區的一部分，因此工作目錄以外的路徑仍必須透過 external_directory 允許。

例如，這允許存取 ~/projects/personal/ 下的所有內容：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    }
  }
}

此處允許的任何目錄都會繼承與目前工作區相同的預設值。由於 read 預設為 allow，因此除非另有覆寫，否則 external_directory 下的項目也允許讀取。當工具應在這些路徑中受到限制時，請新增明確規則，例如在保留讀取的同時封鎖編輯：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    },
    "edit": {
      "~/projects/personal/**": "deny"
    }
  }
}

將清單集中在受信任的路徑上，並視需要為其他工具（例如 bash）疊加額外的允許或拒絕規則。

可用的權限

Dropstone 權限以工具名稱作為索引鍵，並加上一些安全防護：

  • read：讀取檔案（比對檔案路徑）
  • edit：所有檔案修改（涵蓋 edit、write、patch）
  • glob：檔案萬用字元比對（比對 glob 模式）
  • grep：內容搜尋（比對 regex 模式）
  • bash：執行 shell 指令（比對解析後的指令，例如 git status --porcelain）
  • task：啟動子代理（比對子代理類型）
  • skill：載入技能（比對技能名稱）
  • lsp：執行 LSP 查詢（目前不支援精細規則）
  • question：在執行期間向使用者提問
  • webfetch：擷取 URL（比對 URL）
  • websearch：網路搜尋（比對查詢）
  • external_directory：當工具觸及專案工作目錄以外的路徑時觸發
  • doom_loop：當相同工具呼叫以相同輸入重複 3 次時觸發

預設值

如果你未指定任何內容，預設的 build 代理會在一切操作前詢問。核准是預設值，而非例外：

{
  "permission": {
    "*": "ask",
    "read": {
      "*": "ask",
      "*.env": "ask",
      "*.env.*": "ask",
      "*.env.example": "ask"
    },
    "external_directory": { "*": "ask" },
    "question": "deny",
    "plan_enter": "deny",
    "plan_exit": "deny",
    "mode_switch": "deny"
  }
}

你已核准的目錄會在目前工作階段的其餘時間內以 "allow" 加入 external_directory。

你的設定會疊加在這些預設值之上，且你的規則會勝出。它不會取代預設值：將 edit 設為 "allow" 會讓 read 維持在 "ask"，因此請明確列出你打算變更的每個權限。

accept all 代理則改從 "*": "allow" 開始，且 external_directory 完全允許。.env 和 .env.* 的讀取仍會詢問，理由是自動核准執行並不等同於同意交出機密。

無頭模式與伺服器模式

在互動模式下，"ask" 是無害的：你會收到提示並核准。在 dropstone serve、CI 或任何其他沒有人在鍵盤前的情況下，沒有人可以詢問，因此呼叫會停在 "status": "running"，請求會掛起而不是失敗。沒有逾時，也沒有可捕捉的錯誤。

由於 build 代理會在一切操作前詢問，這是預設結果而非邊緣案例。部分設定也無法解救你：允許 edit 會讓 read 維持在 "ask"，而代理第一次開啟檔案時執行就會掛起。

有兩種修正方式。你可以執行 accept all 代理，它從 "*": "allow" 開始：

curl -X POST ".../session/$SID/message" -d '{ "agent": "accept all", ... }'

或者留在 build 並明確列出完整的允許清單，預設拒絕，這樣後續版本新增的工具就不會默默開始掛起你的執行：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "*": "deny",
    "read": "allow",
    "edit": "allow",
    "glob": "allow",
    "grep": "allow",
    "bash": "allow"
  }
}

將範圍縮小到工作實際需要的項目。只會讀取和回報的代理沒有理由持有 edit 或 bash。

請注意，accept all 在讀取 .env 和 .env.* 前仍會詢問。如果無人的執行必須讀取其中一個，請明確允許它，並謹慎為之。

Note

如果無頭執行停止產生輸出且從未返回，請使用 GET /session/:id/message 檢查工作階段中的最後一則訊息。工具部分卡在 "status": "running" 就是這個問題，而不是模型速度慢。

「Ask」的作用

當 Dropstone 提示核准時，UI 會提供三種結果：

  • once：僅核准此請求
  • always：核准符合建議模式的未來請求（在目前 Dropstone 工作階段的其餘時間內）
  • reject：拒絕請求

always 會核准的模式集合由工具提供（例如，bash 核准通常會將安全指令前綴加入白名單，例如 git status*）。

代理

你可以為每個代理覆寫權限。代理權限會與全域設定合併，且代理規則優先。了解更多 關於代理權限的資訊。

Note

請參閱上方精細規則（物件語法）一節，以取得更詳細的模式比對範例。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git commit *": "deny",
      "git push *": "deny",
      "grep *": "allow"
    }
  },
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git *": "allow",
          "git commit *": "ask",
          "git push *": "deny",
          "grep *": "allow"
        }
      }
    }
  }
}

你也可以在 Markdown 中設定代理權限：

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---

Only analyze code and suggest changes.

Tip

對帶有引數的指令使用模式比對。"grep *" 允許 grep pattern file.txt，而單獨的 "grep" 則會封鎖它。像 git status 這樣的指令適用於預設行為，但在傳遞引數時需要明確的權限（例如 "git status *"）。

Ctrl+I