Agents

設定並使用專業化的 Agents。

Agents 是專門化的 AI 助手，可針對特定任務與工作流程進行設定。它們讓你能建立具備自訂提示詞、模型與工具存取權限的專用工具。

Tip

使用 plan agent 來分析程式碼與檢視建議，而不進行任何程式碼變更。

你可以在工作階段中切換 agents，或使用 @ 提及來呼叫它們。

類型

Dropstone 中有兩種類型的 agents：primary agents 與 subagents。

Primary agents

Primary agents 是你直接互動的主要助手。你可以使用 Tab 鍵或你設定的 switch_agent 按鍵綁定在它們之間循環切換。這些 agents 處理你的主要對話。工具存取權限是透過權限設定：例如，Build 啟用了所有工具，而 Plan 則受到限制。

Tip

你可以在工作階段中使用 Tab 鍵在 primary agents 之間切換。

Dropstone 內建兩個 primary agents：Build 與 Plan。我們將在下方說明。

Subagents

Subagents 是專門化的助手，primary agents 可以針對特定任務呼叫它們。你也可以在訊息中**@提及**它們來手動呼叫。

Dropstone 內建兩個 subagents：General 與 Explore。我們將在下方說明。

內建

Dropstone 內建兩個 primary agents 與兩個 subagents。

使用 build

模式：primary

Build 是預設的 primary agent，啟用了所有工具。這是標準的開發工作 agent，適用於需要完整檔案操作與系統指令存取權限的情境。

使用 plan

模式：primary

一個受限的 agent，專為規劃與分析設計。我們使用權限系統來給你更多控制，並防止非預期的變更。預設情況下，以下所有項目都設定為 ask：

file edits：所有寫入、修補與編輯
bash：所有 bash 指令

當你希望 LLM 分析程式碼、建議變更或建立計畫，而不對你的程式碼庫進行任何實際修改時，這個 agent 非常有用。

使用 general

模式：subagent

一個通用型 agent，用於研究複雜問題與執行多步驟任務。具備完整的工具存取權限（除了 todo），因此可以在需要時進行檔案變更。使用它來平行執行多個工作單元。

使用 explore

模式：subagent

一個快速、唯讀的 agent，用於探索程式碼庫。無法修改檔案。當你需要快速依模式尋找檔案、搜尋程式碼中的關鍵字，或回答關於程式碼庫的問題時，請使用它。

使用 compaction

模式：primary

隱藏的系統 agent，將長上下文壓縮成較小的摘要。它在需要時自動執行，且無法在 UI 中選取。

使用 title

模式：primary

隱藏的系統 agent，產生簡短的工作階段標題。它自動執行，且無法在 UI 中選取。

使用 summary

模式：primary

隱藏的系統 agent，建立工作階段摘要。它自動執行，且無法在 UI 中選取。

使用方式

對於 primary agents，在工作階段中使用 Tab 鍵循環切換。你也可以使用你設定的 switch_agent 按鍵綁定。
Subagents 可以透過以下方式呼叫：
- 自動由 primary agents 根據其描述針對專門任務呼叫。
- 手動在訊息中**@提及** subagent。例如：
```
@general help me search for this function
```
在工作階段之間導覽：當 subagents 建立子工作階段時，使用 session_child_first（預設：<Leader>+Down）從父工作階段進入第一個子工作階段。
進入子工作階段後，使用：
- session_child_cycle（預設：Right）循環到下一個子工作階段
- session_child_cycle_reverse（預設：Left）循環到上一個子工作階段
- session_parent（預設：Up）返回父工作階段
這讓你能在主對話與專門化的 subagent 工作之間切換。

設定

你可以自訂內建的 agents 或透過設定建立自己的 agents。Agents 可以透過兩種方式設定：

JSON

在你的 dropstone.json 設定檔中設定 agents：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "dropstone/dropstone-pro",
      "prompt": "{file:./prompts/build.txt}",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "model": "dropstone/dropstone-fast",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "dropstone/dropstone-pro",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "permission": {
        "edit": "deny"
      }
    }
  }
}

Markdown

你也可以使用 markdown 檔案定義 agents。將它們放置在：

全域：~/.config/dropstone/agents/
專案特定：.dropstone/agents/

---
description: Reviews code for quality and best practices
mode: subagent
model: dropstone/dropstone-pro
temperature: 0.1
permission:
  edit: deny
  bash: deny
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

markdown 檔案名稱會成為 agent 名稱。例如，review.md 會建立一個 review agent。

選項

讓我們詳細檢視這些設定選項。

Description

使用 description 選項提供 agent 功能與使用時機的簡短描述。

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

這是一個必填的設定選項。

Temperature

使用 temperature 設定控制 LLM 回應的隨機性與創造力。

較低的值使回應更專注且確定，而較高的值則增加創造力與多樣性。

{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Temperature 值通常介於 0.0 到 1.0 之間：

0.0-0.2：非常專注且確定的回應，適合程式碼分析與規劃
0.3-0.5：平衡的回應並帶有一些創造力，適合一般開發任務
0.6-1.0：更具創造力且多樣的回應，適合腦力激盪與探索

{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

如果未指定 temperature，Dropstone 會使用針對每個層級調整的合理預設值。

Max steps

控制 agent 在被強制僅以文字回應之前可以執行的 agentic 迭代次數上限。這讓想要控制成本的使用者可以設定 agentic 動作的限制。

如果未設定，agent 會持續迭代，直到模型選擇停止或使用者中斷工作階段。

{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

當達到限制時，agent 會收到一個特殊的系統提示詞，指示它以工作摘要與建議的剩餘任務來回應。

已棄用

舊版的 maxSteps 欄位已棄用。請改用 steps。

Disable

設定為 true 以停用該 agent。

{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

使用 prompt 設定為此 agent 指定自訂的系統提示詞檔案。提示詞檔案應包含針對 agent 用途的指示。

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

此路徑相對於設定檔所在位置。因此這同時適用於全域 Dropstone 設定與專案特定設定。

Model

使用 model 設定覆寫此 agent 的模型。這對於使用針對不同任務最佳化的不同模型非常有用。例如，使用較快的模型進行規劃，使用能力較強的模型進行實作。

Tip

如果你未指定模型，primary agents 使用全域設定的模型，而 subagents 則繼承呼叫它們的 primary agent 的模型。

{
  "agent": {
    "plan": {
      "model": "dropstone/dropstone-fast"
    }
  }
}

模型 ID 使用 dropstone/<tier> 格式。使用 dropstone/dropstone-fast、dropstone/dropstone-pro 或 dropstone/dropstone-heavy。

Tools（已棄用）

tools 已棄用。對於新的設定、更新與更精細的控制，請優先使用 agent 的 permission 欄位。

允許你控制此 agent 中可用的工具。你可以透過將特定工具設定為 true 或 false 來啟用或停用它們。在 agent 的 tools 設定中，true 等同於 {"*": "allow"} 權限，false 等同於 {"*": "deny"} 權限。

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

Note

Agent 特定的設定會覆寫全域設定。

你也可以在舊版的 tools 項目中使用萬用字元來同時控制多個工具。例如，停用來自某個 MCP server 的所有工具：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

了解更多關於 tools 的資訊。

Permissions

你可以設定權限來管理 agent 可以執行的動作。每個權限鍵可以設定為：

"ask"：在執行工具前提示核准
"allow"：允許所有操作，無需核准
"deny"：停用該工具

可用的權限鍵如下：

鍵	控制的工具
`read`	`read`
`edit`	`write`、`edit`、`apply_patch`
`glob`	`glob`
`grep`	`grep`
`list`	`list`
`bash`	`bash`
`task`	`task`
`external_directory`	任何讀取或寫入專案工作樹之外檔案的工具
`todowrite`	`todowrite`、`todoread`
`webfetch`	`webfetch`
`websearch`	`websearch`
`lsp`	`lsp`
`skill`	`skill`
`question`	`question`
`doom_loop`	當 agent 似乎卡住時的復原提示

read、edit、glob、grep、list、bash、task、external_directory、lsp 與 skill 接受簡寫動作（"allow" | "ask" | "deny"）或 glob/pattern → 動作的物件以進行精細控制。其餘鍵僅接受簡寫動作。

Note

權限鍵會以萬用字元 pattern 比對底層工具名稱，因此相同的語法適用於內建工具、自訂工具與 MCP 工具。例如，"mymcp_*": "deny" 會拒絕來自某個 MCP server 的所有工具，而 "mymcp_search": "ask" 則針對單一工具。

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

你可以針對每個 agent 覆寫這些權限。

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

你也可以在 Markdown agents 中設定權限。

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---

Only analyze code and suggest changes.

你可以為特定的 bash 指令設定權限。

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

這可以接受 glob pattern。

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

你也可以使用 * 萬用字元來管理所有指令的權限。由於最後符合的規則優先，請將 * 萬用字元放在前面，並將特定規則放在後面。

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

了解更多關於 permissions 的資訊。

Mode

使用 mode 設定控制 agent 的模式。mode 選項用於決定 agent 的使用方式。

{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

mode 選項可以設定為 primary、subagent 或 all。如果未指定 mode，預設為 all。

Hidden

使用 hidden: true 將 subagent 從 @ 自動完成選單中隱藏。這對於僅應由其他 agents 透過 Task 工具以程式方式呼叫的內部 subagents 非常有用。

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

這只影響使用者在自動完成選單中的可見性。如果權限允許，隱藏的 agents 仍然可以被模型透過 Task 工具呼叫。

Note

僅適用於 mode: subagent 的 agents。

Task permissions

使用 permission.task 控制 agent 可以透過 Task 工具呼叫哪些 subagents。使用 glob patterns 進行彈性比對。

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

當設定為 deny 時，該 subagent 會從 Task 工具的描述中完全移除，因此模型不會嘗試呼叫它。

Tip

規則依序評估，且最後符合的規則優先。在上述範例中，orchestrator-planner 同時符合 *（deny）與 orchestrator-*（allow），但由於 orchestrator-* 在 * 之後，結果為 allow。

Tip

使用者隨時可以透過 @ 自動完成選單直接呼叫任何 subagent，即使 agent 的 task permissions 會拒絕它。

Color

使用 color 選項自訂 agent 在 UI 中的視覺外觀。這會影響 agent 在介面中的顯示方式。

使用有效的十六進位顏色（例如 #FF5733）或主題顏色：primary、secondary、accent、success、warning、error、info。

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

使用 top_p 選項控制回應的多樣性。這是 temperature 的替代方案，用於控制隨機性。

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

數值範圍從 0.0 到 1.0。較低的值更專注，較高的值更多樣。

Additional

你在 agent 設定中指定的任何其他選項都會直接傳遞作為模型選項。對於 Dropstone 的層級，支援的傳遞選項是推理深度與文字詳細程度：

{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "dropstone/dropstone-heavy",
      "variant": "xhigh",
      "textVerbosity": "low"
    }
  }
}

Tip

執行 dropstone models 以查看可用的層級。

建立 agents

你可以使用以下指令建立新的 agents：

dropstone agent create

這個互動式指令會：

詢問要將 agent 儲存在哪裡；全域或專案特定。
詢問 agent 應該做什麼的描述。
產生適當的系統提示詞與識別碼。
讓你選擇 agent 應該被允許的權限（你未選擇的任何項目都會被拒絕）。
最後，建立包含 agent 設定的 markdown 檔案。

使用案例

以下是一些不同 agents 的常見使用案例。

Build agent：完整開發工作，啟用所有工具
Plan agent：分析與規劃，不進行變更
Review agent：程式碼審查，具備唯讀存取權限與文件工具
Debug agent：專注於調查，啟用 bash 與 read 工具
Docs agent：文件撰寫，具備檔案操作但無系統指令

範例

以下是一些你可能覺得有用的範例 agents。

Tip

有一個你想分享的 agent 嗎？與我們聯繫，我們會將它展示出來。

文件 agent

---
description: Writes and maintains project documentation
mode: subagent
permission:
  bash: deny
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:

- Clear explanations
- Proper structure
- Code examples
- User-friendly language

安全稽核員

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
permission:
  edit: deny
---

You are a security expert. Focus on identifying potential security issues.

Look for:

- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

Models

Rules (AGENTS.md)

Agents

類型

Primary agents

Subagents

內建

使用 build

使用 plan

使用 general

使用 explore

使用 compaction

使用 title

使用 summary

使用方式

設定

JSON

Markdown

選項

Description

Temperature

Max steps

Disable

Prompt

Model

Tools（已棄用）

Permissions

Mode

Hidden

Task permissions

Color

Top P

Additional

建立 agents

使用案例

範例

文件 agent

安全稽核員

本頁內容