伺服器

透過 HTTP 與 dropstone 伺服器互動。

dropstone serve 指令會執行一個無頭 HTTP 伺服器，並公開一個 Dropstone 用戶端可以使用的 OpenAPI 端點。

使用方式

dropstone serve [--port <number>] [--hostname <string>] [--cors <origin>]

選項

旗標	說明	預設值
`--port`	要監聽的連接埠	`4096`
`--hostname`	要監聽的主機名稱	`127.0.0.1`
`--mdns`	啟用 mDNS 探索	`false`
`--mdns-domain`	mDNS 服務的自訂網域名稱	`dropstone.local`
`--cors`	允許的其他瀏覽器來源	`[]`

--cors 可以多次傳遞：

dropstone serve --cors http://localhost:5173 --cors https://app.example.com

驗證

設定 DROPSTONE_SERVER_PASSWORD 以使用 HTTP 基本驗證保護伺服器。使用者名稱預設為 dropstone，或設定 DROPSTONE_SERVER_USERNAME 來覆寫它。這同時適用於 dropstone serve 和 dropstone web。

DROPSTONE_SERVER_PASSWORD=your-password dropstone serve

Agent 憑證

DROPSTONE_SERVER_PASSWORD 保護伺服器本身。它不會告訴 agent 如何連線到 Dropstone。在無人值守的機器上，沒有已登入的帳戶可以繼承，因此請透過 provider 設定傳遞 API 金鑰：

{
  "provider": {
    "dropstone": {
      "options": {
        "apiKey": "dsk_live_...",
        "baseURL": "https://api.dropstone.io/api/v1"
      }
    }
  }
}

baseURL 很重要。API 金鑰在 /api/v1 被接受，而不是在 /v1，而且傳送到 /v1 的金鑰會被拒絕，並出現 403 Invalid token format. Please log in again. 的錯誤。請在此處設定它，而不是透過 DROPSTONE_BASE_URL，因為後者也用於建構帳戶、使用量和記憶體端點，如果你將它指向一個帶有版本的路徑，這些端點將會失效。

在 dropstone.io/dashboard/settings 產生金鑰。

Note

預設的 build agent 會在每次工具呼叫前詢問。這裡沒有任何東西可以回答該提示，因此請求會掛起而不是失敗。請傳送 "agent": "accept all" 或設定明確的權限允許清單。請參閱權限。

傳送提示

POST /session/:id/message 需要 agent 和 model 兩者。省略 model 不會解析出預設值：該輪次會回傳 200，但 body 為空，且不會執行任何操作。

curl -X POST "http://127.0.0.1:4096/session/$SID/message?directory=$PWD" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "build",
    "model": { "providerID": "dropstone", "modelID": "dropstone-pro" },
    "parts": [{ "type": "text", "text": "Add error handling to src/index.ts" }]
  }'

失敗的輪次仍然會回傳 200。原因在 data.info.error，而不是在傳輸層級，因此請檢查該欄位，而不是依賴狀態碼。

運作方式

dropstone serve 透過 OpenAPI 3.1 HTTP 端點公開 Dropstone 的功能。相同的端點也用於產生 SDK。

當你想要以程式化方式驅動 Dropstone 時，請使用伺服器：從腳本、CI 管線或你自己的整合。互動式 session 和伺服器是獨立的。無論你是否已開啟互動式 session，執行 dropstone serve 都會啟動一個全新的獨立伺服器。

你可以使用 --hostname 和 --port 旗標覆寫綁定位址。

規格

伺服器會發布一個 OpenAPI 3.1 規格，可以在以下位置檢視：

http://<hostname>:<port>/doc

例如，http://localhost:4096/doc。使用此規格來產生用戶端或檢查請求和回應型別。或者也可以在 Swagger 瀏覽器中檢視它。

API

dropstone 伺服器公開以下 API。

全域

方法	路徑	說明	回應
`GET`	`/global/health`	取得伺服器健康狀態和版本	`{ healthy: true, version: string }`
`GET`	`/global/event`	取得全域事件 (SSE 串流)	事件串流

專案

方法	路徑	說明	回應
`GET`	`/project`	列出所有專案	`Project[]`
`GET`	`/project/current`	取得目前專案	`Project`

路徑與 VCS

方法	路徑	說明	回應
`GET`	`/path`	取得目前路徑	`Path`
`GET`	`/vcs`	取得目前專案的 VCS 資訊	`VcsInfo`

設定

方法	路徑	說明	回應
`GET`	`/config`	取得設定資訊	`Config`
`PATCH`	`/config`	更新設定	`Config`

Sessions

方法	路徑	說明	備註
`GET`	`/session`	列出所有 sessions	回傳 `Session[]`
`POST`	`/session`	建立新的 session	body: `{ parentID?, title? }`, 回傳 `Session`
`GET`	`/session/status`	取得所有 sessions 的 session 狀態	回傳 `{ [sessionID: string]:` `SessionStatus` `}`
`GET`	`/session/:id`	取得 session 詳細資料	回傳 `Session`
`DELETE`	`/session/:id`	刪除 session 及其所有資料	回傳 `boolean`
`PATCH`	`/session/:id`	更新 session 屬性	body: `{ title? }`, 回傳 `Session`
`GET`	`/session/:id/children`	取得 session 的子 sessions	回傳 `Session[]`
`GET`	`/session/:id/todo`	取得 session 的待辦事項清單	回傳 `Todo[]`
`POST`	`/session/:id/init`	分析應用程式並建立 `AGENTS.md`	body: `{ messageID, providerID, modelID }`, 回傳 `boolean`
`POST`	`/session/:id/fork`	在訊息處分叉現有 session	body: `{ messageID? }`, 回傳 `Session`
`POST`	`/session/:id/abort`	中止執行中的 session	回傳 `boolean`
`GET`	`/session/:id/diff`	取得此 session 的 diff	query: `messageID?`, 回傳 `FileDiff[]`
`POST`	`/session/:id/summarize`	總結 session	body: `{ providerID, modelID }`, 回傳 `boolean`
`POST`	`/session/:id/revert`	還原訊息	body: `{ messageID, partID? }`, 回傳 `boolean`
`POST`	`/session/:id/unrevert`	還原所有已還原的訊息	回傳 `boolean`
`POST`	`/session/:id/permissions/:permissionID`	回應權限請求	body: `{ response, remember? }`, 回傳 `boolean`

訊息

方法	路徑	說明	備註
`GET`	`/session/:id/message`	列出 session 中的訊息	query: `limit?`, 回傳 `{ info:` `Message, parts:` `Part[]}[]`
`POST`	`/session/:id/message`	傳送訊息並等待回應	body: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`, 回傳 `{ info:` `Message, parts:` `Part[]}`
`GET`	`/session/:id/message/:messageID`	取得訊息詳細資料	回傳 `{ info:` `Message, parts:` `Part[]}`
`POST`	`/session/:id/prompt_async`	非同步傳送訊息 (不等待)	body: 與 `/session/:id/message` 相同, 回傳 `204 No Content`
`POST`	`/session/:id/command`	執行斜線指令	body: `{ messageID?, agent?, model?, command, arguments }`, 回傳 `{ info:` `Message, parts:` `Part[]}`
`POST`	`/session/:id/shell`	執行 shell 指令	body: `{ agent, model?, command }`, 回傳 `{ info:` `Message, parts:` `Part[]}`

指令

方法	路徑	說明	回應
`GET`	`/command`	列出所有指令	`Command[]`

檔案

方法	路徑	說明	回應
`GET`	`/find?pattern=<pat>`	在檔案中搜尋文字	包含 `path`、`lines`、`line_number`、`absolute_offset`、`submatches` 的相符物件陣列
`GET`	`/find/file?query=<q>`	依名稱尋找檔案和目錄	`string[]` (路徑)
`GET`	`/find/symbol?query=<q>`	尋找工作區符號	`Symbol[]`
`GET`	`/file?path=<path>`	列出檔案和目錄	`FileNode[]`
`GET`	`/file/content?path=<p>`	讀取檔案	`FileContent`
`GET`	`/file/status`	取得受追蹤檔案的狀態	`File[]`

`/find/file` 查詢參數

query (必要)：搜尋字串 (模糊比對)
type (選用)：將結果限制為 "file" 或 "directory"
directory (選用)：覆寫搜尋的專案根目錄
limit (選用)：最大結果數 (1–200)
dirs (選用)：舊版旗標 ("false" 僅回傳檔案)

LSP、格式化工具與 MCP

方法	路徑	說明	回應
`GET`	`/lsp`	取得 LSP 伺服器狀態	`LSPStatus[]`
`GET`	`/formatter`	取得格式化工具狀態	`FormatterStatus[]`
`GET`	`/mcp`	取得 MCP 伺服器狀態	`{ [name: string]:` `MCPStatus` `}`
`POST`	`/mcp`	動態新增 MCP 伺服器	body: `{ name, config }`, 回傳 MCP 狀態物件

Agents

方法	路徑	說明	回應
`GET`	`/agent`	列出所有可用的 agents	`Agent[]`

日誌

方法	路徑	說明	回應
`POST`	`/log`	寫入日誌項目。Body: `{ service, level, message, extra? }`	`boolean`

驗證

方法	路徑	說明	回應
`PUT`	`/auth/:id`	為指定的目標設定驗證憑證。	`boolean`

事件

方法	路徑	說明	回應
`GET`	`/event`	伺服器傳送事件串流。第一個事件是 `server.connected`，然後是匯流排事件	伺服器傳送事件串流

文件

方法	路徑	說明	回應
`GET`	`/doc`	OpenAPI 3.1 規格	包含 OpenAPI 規格的 HTML 頁面

GitLab

SDK

伺服器