伺服器

透過 HTTP 與 dropstone 伺服器互動。

dropstone serve 命令執行一個無頭 HTTP 伺服器，公開一個 OpenAPI 端點供 Dropstone 用戶端使用。

使用方式

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

運作方式

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

當您想以程式設計方式驅動 Dropstone 時使用伺服器：從指令碼、CI 管道或您自己的整合。互動式工作階段和伺服器是獨立的。執行 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`

工作階段

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

訊息

方法	路徑	描述	備註
`GET`	`/session/:id/message`	列出工作階段中的訊息	查詢：`limit?`，傳回 `{ info:` `Message, parts:` `Part[]}[]`
`POST`	`/session/:id/message`	傳送訊息並等待回應	本體：`{ 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`	非同步傳送訊息 (不等待)	本體：與 `/session/:id/message` 相同，傳回 `204 No Content`
`POST`	`/session/:id/command`	執行斜線命令	本體：`{ messageID?, agent?, model?, command, arguments }`，傳回 `{ info:` `Message, parts:` `Part[]}`
`POST`	`/session/:id/shell`	執行 shell 命令	本體：`{ 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 伺服器	本體：`{ name, config }`，傳回 MCP 狀態物件

代理

方法	路徑	描述	回應
`GET`	`/agent`	列出所有可用的代理	`Agent[]`

日誌

方法	路徑	描述	回應
`POST`	`/log`	寫入日誌項目。本體：`{ service, level, message, extra? }`	`boolean`

驗證

方法	路徑	描述	回應
`PUT`	`/auth/:id`	設定給定目標的驗證認證。	`boolean`

事件

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

文件

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

GitLab

SDK

伺服器