核心概念

Dropstone 是一個在終端機中運行的代理式編碼工具。它可以讀取程式碼、執行命令、規劃變更、編輯檔案，並驗證結果。本頁涵蓋你只需要學習一次的核心概念：代理運行的循環、它能存取什麼、工作階段如何運作、上下文如何管理，以及權限如何讓你保持掌控。

代理循環

當你給 Dropstone 一個任務時，它會經歷三個階段：收集上下文、採取行動、驗證結果。這些階段會相互融合。Dropstone 全程使用工具，無論是讀取檔案以理解你的程式碼、編輯以進行變更，還是執行測試以檢查其工作。

這個循環會根據你的要求調整。關於程式碼庫的問題可能只需要收集上下文。錯誤修正會循環經歷所有三個階段。大型重構可能需要大量驗證。Dropstone 會根據從上一步學到的內容來決定每個步驟需要什麼，將數十個動作串聯起來，並在過程中修正方向。

你也是這個循環的一部分。你可以隨時中斷以重新引導、補充上下文，或要求不同的方法。Dropstone 自主運作，但會持續回應你的輸入。

代理循環由兩個元件驅動：負責推理的模型，以及負責行動的工具。

模型

Dropstone 使用專為編碼設計的模型。共有三個等級，每個等級針對不同類型的工作進行調校：

在工作階段中可使用 /effort low、/effort medium、/effort high 或 /effort xhigh 切換等級，或按 Ctrl+T 循環切換。當本指南說「Dropstone 決定」或「Dropstone 選擇」時，就是模型在進行推理。

工具

工具是讓 Dropstone 具備代理能力的關鍵。沒有工具，模型只能產生文字。有了工具，它就能行動：讀取你的程式碼、編輯檔案、執行命令、搜尋網路，以及與外部服務互動。每個工具結果都會回饋到循環中，影響下一個決策。

內建工具分為五個類別：

Dropstone 會根據你的提示及其沿途學到的內容來選擇使用哪些工具。當你說「修正失敗的測試」時，它可能會：

1. 執行測試套件以查看哪些測試失敗
2. 讀取錯誤輸出
3. 搜尋相關的原始碼檔案
4. 讀取這些檔案以理解程式碼
5. 編輯它們以修正問題
6. 再次執行測試以驗證

每次工具使用都會回傳資訊，影響下一步。這就是代理循環的實際運作。

內建工具是基礎。你可以透過技能擴展 Dropstone 的知識、透過 MCP 伺服器連接外部服務，並將工作委派給子代理。如需完整的內建工具清單，請參閱內建工具。

Dropstone 能存取什麼

當你在某個目錄中執行 dropstone 時，代理會獲得以下存取權限：

• 你的專案。 工作目錄及子目錄中的檔案，以及經你許可的其他檔案。
• 你的終端機。 任何你可以自己執行的命令：建置工具、git、套件管理器、系統工具、腳本。如果你能從命令列執行，Dropstone 也能。
• 你的 git 狀態。 目前分支、未提交的變更、已暫存的檔案，以及最近的提交歷史。
• 你的 AGENTS.md。 位於儲存庫根目錄的 markdown 檔案，你可以在其中撰寫專案特定的慣例、建置命令、注意事項，以及任何 Dropstone 每次工作階段都應該知道的事。
• 你設定的擴充功能。 用於外部服務的 MCP 伺服器、用於工作流程的技能，以及用於委派工作的子代理。

因為 Dropstone 能看到你的整個專案，所以它可以跨檔案工作。當你要求它「修正驗證錯誤」時，它會搜尋相關檔案、讀取數個檔案以理解上下文、在它們之間進行協調編輯、執行測試以驗證，並在你要求時提交。這與只能看到目前檔案的內嵌程式碼助手不同。

工作階段

每個互動式工作階段都會儲存在本機。每則訊息、工具使用與結果都會寫入工作階段記錄，這使得復原、恢復與分叉過往工作成為可能。

工作階段彼此獨立。新工作階段會以全新的上下文視窗開始，沒有先前對話的記憶。持久性的知識應放在 AGENTS.md 中，而非對話歷史中。

恢復或分叉工作階段

使用 dropstone --continue（或 dropstone -c）恢復會重新開啟目前目錄中最近的工作階段，並將新訊息附加到其中。使用 dropstone --session <id> 可恢復特定 ID 的工作階段。

# 繼續此目錄中的最後一個工作階段
dropstone -c

# 恢復特定工作階段
dropstone --session 7f3a82b1

# 將現有工作階段分叉為新的對話
dropstone --session 7f3a82b1 --fork

分叉會將歷史複製到新的工作階段 ID，保留原始工作階段不受影響。當你想探索替代方向而不失去原始脈絡時，這很有用。

上下文視窗

上下文視窗容納你的對話歷史、檔案內容、命令輸出、AGENTS.md、已載入的技能與系統指令。隨著你工作，視窗會逐漸填滿。Dropstone 會自動壓縮較舊的內容，但對話早期的指令可能會遺失。

幾個經驗法則：

• 將持久性規則放在 AGENTS.md 中，而非聊天訊息中。聊天訊息版本會被壓縮掉；AGENTS.md 版本會在每次工作階段重新載入。
• 技能按需載入。 Dropstone 在工作階段開始時會看到技能描述，但只有在技能被呼叫時才會載入完整內容。
• 子代理擁有自己的全新上下文。 它們的工作不會使主對話膨脹；完成後，它們會回傳摘要。

安全性：檢查點與權限

Dropstone 有兩個安全機制。檢查點讓你可以復原代理所做的變更。權限控制代理可以在不詢問的情況下做什麼。

以檢查點復原

每次檔案編輯都是可逆的。在 Dropstone 編輯檔案之前，它會快照目前的內容。如果出了問題，使用 /undo 一次回退一個編輯週期，或使用 /redo 重播已復原的步驟。

/undo            # 還原最後一個編輯週期
/redo            # 重播最近復原的步驟

檢查點是工作階段本機的，與 git 分開。它們只涵蓋檔案變更。觸及遠端系統（資料庫、已部署的服務、網路 API）的動作無法被檢查點化，這就是為什麼 Dropstone 在執行具有外部副作用的命令前會先詢問。

控制 Dropstone 能做什麼

Dropstone 在第一次想要執行敏感動作時會要求核准：編輯檔案、執行 shell 命令、呼叫網路。核准一次後，相同操作在整個工作階段中就不會再提示。

在工作階段中使用 Tab 在兩種操作模式之間切換：

• 建置模式。 預設模式。Dropstone 可以編輯檔案並執行命令（需經核准）。當你想交付變更時使用此模式。
• 規劃模式。 唯讀。Dropstone 可以調查程式碼庫、收集上下文並產生計畫，但不能編輯或執行任何東西。當你想在變更之前研究系統時使用此模式。

若要預先核准命令並完全跳過提示，請在專案的權限設定中列出它們。例如：

{
  "permissions": {
    "allow": ["git status", "git diff", "npm test", "npm run lint"]
  }
}

如需組織層級的政策、更精細的模式，以及範圍解析的運作方式，請參閱權限指南。

與 Dropstone 有效協作

以下是一些往往能產生更好結果的模式。

這是一場對話

你不需要完美的第一個提示。從你想要什麼開始，看看代理做什麼，然後修正它：

修正登入錯誤

不，問題在於工作階段處理，而不是表單驗證

你不是在重新開始。你是在迭代。每一輪都會精煉代理的理解。

中斷與引導

你可以隨時重新引導 Dropstone：

• 按下 Esc 立即停止。目前的工具呼叫會被取消，Dropstone 會等待你的下一個指令。
• 輸入修正並按下 Enter，無需等待。Dropstone 會在目前動作完成後立即讀取它，並在決定下一步之前進行調整。

事先具體明確

你的初始提示越精確，需要的修正就越少。引用檔案、提及限制、指向範例模式：

結帳流程對卡片過期的使用者來說壞了。
在 src/payments/ 中尋找問題，尤其是 token 重新整理。
先寫一個失敗的測試，然後修正它。

模糊的提示也能運作，但你會花更多時間引導。像上面這樣的具體提示通常第一次嘗試就能成功。

給 Dropstone 一些可以驗證的依據

當代理可以檢查自己的工作時，表現會更好。包含測試案例、預期輸出或驗收標準：

實作 validateEmail。測試案例：
  'user@example.com' -> true
  'invalid'           -> false
  'user@.com'         -> false
之後執行測試。

先探索再實作

對於複雜問題，將研究與編碼分開。切換到規劃模式（Tab），讓 Dropstone 研究相關程式碼，透過對話精煉計畫，然後切換回建置模式執行：

讀取 src/auth/ 並解釋我們目前如何處理工作階段。
然後提出一個加入 OAuth 支援的計畫。

審查計畫，對任何你不同意的地方提出異議，然後讓 Dropstone 實作。這種兩階段方法比直接寫程式碼能持續產生更好的結果。

委派，而非指揮

將 Dropstone 視為一位能幹的同事。提供上下文與方向，然後信任代理去弄清楚細節：

結帳流程對卡片過期的使用者來說壞了。
相關程式碼在 src/payments/ 中。
調查並修正它。

你不需要指定要讀取哪些檔案、要執行哪些命令，或要以什麼順序做事。Dropstone 會從提示中自行解決。

下一步