設定

使用 Dropstone JSON 設定檔。

您可以使用 JSON 設定檔來設定 Dropstone。

格式

Dropstone 支援 JSON 和 JSONC（帶註解的 JSON）兩種格式。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "dropstone/dropstone-pro",
  "autoupdate": true,
  "server": {
    "port": 4096,
  },
}

位置

您可以將設定檔放在幾個不同的位置，且它們具有不同的優先順序。

Note

設定檔會被合併，而不是被取代。來自下列設定位置的設定會被組合在一起。後面的設定僅在鍵值衝突時覆蓋前面的設定。所有設定中不衝突的設定都會被保留。

例如，如果您的全域設定設定了 autoupdate: true，而您的專案設定設定了 model: "dropstone/dropstone-pro"，最終的設定將包含這兩個設定。

優先順序

設定來源依下列順序載入（後面的來源覆蓋前面的來源）：

遠端設定（來自 .well-known/dropstone）- 組織預設值
全域設定（~/.config/dropstone/dropstone.json）- 使用者偏好
自訂設定（DROPSTONE_CONFIG 環境變數）- 自訂覆寫
專案設定（專案中的 dropstone.json）- 專案特定設定
.dropstone 目錄 - agents、commands、plugins
受管設定檔（macOS 上的 /Library/Application Support/dropstone/）- 管理員控制
macOS 受管偏好設定（透過 MDM 的 .mobileconfig）- 最高優先順序，使用者無法覆寫

這表示專案設定可以覆寫全域預設值，而全域設定可以覆寫遠端組織預設值。受管設定會覆寫所有其他設定。

Note

.dropstone 和 ~/.config/dropstone 目錄使用複數名稱作為子目錄：agents/、commands/、modes/、plugins/、skills/、tools/。也支援單數名稱（例如 agent/）以向後相容。

遠端

組織可以透過其網域上的 .well-known/dropstone 端點提供預設設定。對於帳戶已註冊該組織的使用者，Dropstone 會在首次登入時自動取得此設定。

遠端設定會最先載入，作為基礎層。所有其他設定來源（全域、專案）都可以覆寫這些預設值。

例如，如果您的組織提供了預設停用的 MCP 伺服器：

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

您可以在本機設定中啟用特定的伺服器：

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

全域

將您的全域 Dropstone 設定放在 ~/.config/dropstone/dropstone.json。使用全域設定來設定使用者層級的偏好，例如模型和權限。

對於工作階段層級的設定（按鍵綁定、捲動、滑鼠擷取），請使用 ~/.config/dropstone/tui.json。

全域設定會覆寫遠端組織預設值。

每個專案

在您的專案根目錄中加入 dropstone.json。專案設定在標準設定檔中具有最高的優先順序 - 它會覆寫全域和遠端設定。

對於專案特定的工作階段設定，請在旁邊加入 tui.json。

Tip

將專案特定的設定放在專案的根目錄中。

當 Dropstone 啟動時，它會在目前目錄中尋找設定檔，或向上遍歷到最近的 Git 目錄。

這也可以安全地簽入 Git，並使用與全域設定相同的 schema。

自訂路徑

使用 DROPSTONE_CONFIG 環境變數指定自訂設定檔路徑。

export DROPSTONE_CONFIG=/path/to/my/custom-config.json
dropstone run "Hello world"

自訂設定在優先順序中介於全域設定和專案設定之間載入。

受管設定

組織可以強制執行使用者無法覆寫的設定。受管設定在最高優先順序層級載入。

檔案型

將 dropstone.json 或 dropstone.jsonc 檔案放入系統受管設定目錄：

平台	路徑
macOS	`/Library/Application Support/dropstone/`
Linux	`/etc/dropstone/`
Windows	`%ProgramData%\dropstone`

這些目錄需要管理員/root 權限才能寫入，因此使用者無法修改它們。

macOS 受管偏好設定

在 macOS 上，Dropstone 會從 ai.dropstone.managed 偏好設定網域讀取受管偏好設定。透過 MDM（Jamf、Kandji、FleetDM）部署 .mobileconfig，設定就會自動被強制執行。

Dropstone 會檢查這些路徑：

/Library/Managed Preferences/<user>/ai.dropstone.managed.plist
/Library/Managed Preferences/ai.dropstone.managed.plist

plist 鍵直接對應到 dropstone.json 欄位。MDM 中繼資料鍵（PayloadUUID、PayloadType 等）會自動被移除。

建立 .mobileconfig

使用 ai.dropstone.managed PayloadType。Dropstone 設定鍵直接放在 payload dict 中：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key>
      <string>ai.dropstone.managed</string>
      <key>PayloadIdentifier</key>
      <string>com.example.dropstone.config</string>
      <key>PayloadUUID</key>
      <string>GENERATE-YOUR-OWN-UUID</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>share</key>
      <string>disabled</string>
      <key>server</key>
      <dict>
        <key>hostname</key>
        <string>127.0.0.1</string>
      </dict>
      <key>permission</key>
      <dict>
        <key>*</key>
        <string>ask</string>
        <key>bash</key>
        <dict>
          <key>*</key>
          <string>ask</string>
          <key>rm -rf *</key>
          <string>deny</string>
        </dict>
      </dict>
    </dict>
  </array>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadIdentifier</key>
  <string>com.example.dropstone</string>
  <key>PayloadUUID</key>
  <string>GENERATE-YOUR-OWN-UUID</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
</dict>
</plist>

使用 uuidgen 產生唯一的 UUID。自訂設定以符合您組織的需求。

透過 MDM 部署

Jamf Pro： 電腦 > 設定檔 > 上傳 > 範圍設定到目標裝置或智慧型群組
FleetDM： 將 .mobileconfig 加入您的 gitops 儲存庫，位於 mdm.macos_settings.custom_settings 下，然後執行 fleetctl apply

在裝置上驗證

雙擊 .mobileconfig 以在本機安裝進行測試（會顯示在系統設定 > 隱私權與安全性 > 設定檔中），然後執行：

dropstone debug config

所有受管偏好設定鍵都會出現在解析後的設定中，且無法被使用者或專案設定覆寫。

Schema

主要的設定 schema 定義在 dropstone.io/config.json。

工作階段層級的設定（tui.json）使用 dropstone.io/tui.json。

您的編輯器應該能夠根據 schema 進行驗證和自動完成。

工作階段設定

使用專用的 tui.json（或 tui.jsonc）檔案來設定工作階段層級的設定：捲動行為、滑鼠擷取、diff 渲染等。

{
  "$schema": "https://dropstone.io/schema/tui.json",
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto",
  "mouse": true
}

dropstone.json 中舊版的 theme、keybinds 和與工作階段相關的鍵已棄用，並會在可能的情況下自動遷移。

伺服器

您可以透過 server 選項設定 dropstone serve 和 dropstone web 指令的伺服器設定。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

可用的選項：

port - 監聽的連接埠。
hostname - 監聽的主機名稱。當啟用 mdns 且未設定 hostname 時，預設為 0.0.0.0。
mdns - 啟用 mDNS 服務探索。這允許網路上的其他裝置探索您的 Dropstone 伺服器。
mdnsDomain - mDNS 服務的自訂網域名稱。預設為 dropstone.local。對於在同一網路上執行多個實例很有用。
cors - 當從瀏覽器型用戶端使用 HTTP 伺服器時，允許 CORS 的額外來源。值必須是完整的來源（scheme + host + 可選的 port），例如 https://app.example.com。

在此了解更多關於伺服器的資訊。

Shell

您可以使用 shell 選項設定互動式終端機所使用的 shell。相容的 shell 也會用於 agent 工具呼叫。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "shell": "pwsh"
}

如果未指定，Dropstone 會根據您的作業系統自動探索並使用合理的預設值（例如 Windows 上的 pwsh 或 cmd.exe，macOS/Linux 上的 /bin/zsh 或 /bin/bash）。您可以提供絕對路徑或簡短名稱。

工具

您可以透過 tools 選項管理 LLM 可以使用的工具。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

在此了解更多關於工具的資訊。

模型

使用 model 選項設定您的預設模型。Dropstone 提供三個等級：

等級	模型 ID
Fast	`dropstone/dropstone-fast`
Pro	`dropstone/dropstone-pro`
Heavy	`dropstone/dropstone-heavy`

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "dropstone/dropstone-pro"
}

使用 variant 固定預設的推理深度：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "dropstone/dropstone-pro",
  "variant": "high"
}

有效的 variant 值為 low、medium、high、xhigh。請參閱 Models 以了解完整說明。

small_model 選項為輕量級任務（例如標題產生）設定單獨的模型。預設情況下，Dropstone 會選擇合適的等級；您可以明確覆寫它：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "dropstone/dropstone-pro",
  "small_model": "dropstone/dropstone-fast"
}

Agents

您可以透過 agent 選項為特定任務設定專門的 agents。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "dropstone/dropstone-pro",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // Disable file modification tools for review-only agent
        "write": false,
        "edit": false,
      },
    },
  },
}

您也可以使用 ~/.config/dropstone/agents/ 或 .dropstone/agents/ 中的 markdown 檔案來定義 agents。在此了解更多。

預設 agent

您可以使用 default_agent 選項設定預設 agent。這決定了在未明確指定時使用哪個 agent。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "default_agent": "plan"
}

預設 agent 必須是主要 agent（不是子 agent）。這可以是內建的 agent，例如 "build" 或 "plan"，或是您定義的自訂 agent。如果指定的 agent 不存在或是子 agent，Dropstone 會回退到 "build" 並顯示警告。

此設定適用於所有介面：互動式工作階段、單次執行（dropstone run）和 GitHub Action。

指令

您可以透過 command 選項為重複性任務設定自訂指令。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "dropstone/dropstone-fast",
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component",
    },
  },
}

您也可以使用 ~/.config/dropstone/commands/ 或 .dropstone/commands/ 中的 markdown 檔案來定義指令。在此了解更多。

按鍵對應

在 tui.json 中使用 keymap 自訂鍵盤快捷鍵。

{
  "$schema": "https://dropstone.io/schema/tui.json",
  "keymap": {
    "sections": {
      "global": {
        "command.palette.show": "ctrl+p"
      }
    }
  }
}

keymap 會與內建預設值合併，因此您只需要設定想要變更的快捷鍵。

較舊的 keybinds 欄位已棄用，且僅在 keymap 不存在時才適用。

在此了解更多。

快照

Dropstone 使用快照來追蹤 agent 操作期間的檔案變更，讓您可以在工作階段中復原和還原變更。快照預設為啟用。

對於大型儲存庫或具有許多子模組的專案，快照系統可能會導致索引緩慢和大量的磁碟使用。您可以使用 snapshot 選項停用快照。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "snapshot": false
}

請注意，停用快照表示 agent 所做的變更無法透過 UI 回滾。

自動更新

Dropstone 會在啟動時自動下載任何新的更新。您可以使用 autoupdate 選項停用此功能。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "autoupdate": false
}

如果您不想要更新，但希望在有新版本可用時收到通知，請將 autoupdate 設定為 "notify"。請注意，這僅在不是透過套件管理器（例如 Homebrew）安裝時才有效。

格式化器

您可以透過 formatter 選項啟用和設定程式碼格式化器。省略它以保持格式化器停用。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "formatter": true
}

使用物件來保持內建格式化器啟用，同時設定覆寫或自訂格式化器。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

在此了解更多關於格式化器的資訊。

LSP 伺服器

您可以透過 lsp 選項啟用和設定 LSP 伺服器。省略它以保持 LSP 停用。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "lsp": true
}

使用物件來保持內建 LSP 伺服器啟用，同時設定覆寫或自訂 LSP 伺服器。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "lsp": {
    "typescript": {
      "disabled": true
    }
  }
}

在此了解更多關於 LSP 伺服器的資訊。

權限

預設情況下，dropstone 允許所有操作，無需明確核准。您可以使用 permission 選項變更此行為。

例如，若要確保 edit 和 bash 工具需要使用者核准：

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

在此了解更多關於權限的資訊。

壓縮

您可以透過 compaction 選項控制上下文壓縮行為。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

auto - 當上下文已滿時自動壓縮工作階段（預設：true）。
prune - 移除舊的工具輸出以節省 tokens（預設：true）。
reserved - 壓縮的 token 緩衝區。保留足夠的視窗以避免在壓縮期間溢出。

監視器

您可以透過 watcher 選項設定檔案監視器的忽略模式。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

模式遵循 glob 語法。使用此選項將嘈雜的目錄排除在檔案監視之外。

MCP 伺服器

您可以透過 mcp 選項設定想要使用的 MCP 伺服器。

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

在此了解更多。

外掛程式

外掛程式使用自訂工具、鉤子和整合來擴充 Dropstone。

將外掛程式檔案放在 .dropstone/plugins/ 或 ~/.config/dropstone/plugins/。您也可以透過 plugin 選項從 npm 載入外掛程式。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "plugin": ["@my-org/custom-plugin", "./local-plugin.ts"]
}

在此了解更多。

指令

您可以透過 instructions 選項設定您正在使用的模型的指令。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

這接受指令檔案的路徑和 glob 模式陣列。在此了解更多關於規則的資訊。

實驗性

experimental 鍵包含正在積極開發中的選項。

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

不穩定

實驗性選項不穩定。它們可能隨時變更或移除，恕不另行通知。

變數

您可以在設定檔中使用變數替換來引用環境變數和檔案內容。

環境變數

使用 {env:VARIABLE_NAME} 來替換環境變數：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "{env:DROPSTONE_MODEL}"
}

如果環境變數未設定，它將被替換為空字串。

檔案

使用 {file:path/to/file} 來替換檔案的內容：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "instructions": ["./custom-instructions.md"]
}

檔案路徑可以是：

相對於設定檔目錄
或以 / 或 ~ 開頭的絕對路徑

這些對於以下情況很有用：

包含大型指令檔案而不使您的設定檔雜亂無章。
在多個設定檔之間共用常見的設定片段。

Keybindings

Models

設定

格式

位置

優先順序

遠端

全域

每個專案

自訂路徑

受管設定

檔案型

macOS 受管偏好設定

Schema

工作階段設定

伺服器

Shell

工具

模型

Agents

預設 agent

指令

按鍵對應

快照

自動更新

格式化器

LSP 伺服器

權限

壓縮

監視器

MCP 伺服器

外掛程式

指令

實驗性

變數

環境變數

檔案

本頁內容