代理

配置和使用专用代理。

代理是专门的 AI 助手，可以为特定任务和工作流程进行配置。它们允许你创建具有自定义提示词、模型和工具访问权限的专注工具。

Tip

使用计划代理来分析代码和审查建议，而无需进行任何代码更改。

你可以在会话期间切换代理，或使用 @ 提及来调用它们。

类型

Dropstone 中有两种类型的代理：主代理和子代理。

主代理

主代理是你直接交互的主要助手。你可以使用 Tab 键或配置的 switch_agent 键位绑定在它们之间循环切换。这些代理处理你的主要对话。工具访问权限通过权限配置：例如，Build 启用了所有工具，而 Plan 则受到限制。

Tip

你可以在会话期间使用 Tab 键在主代理之间切换。

Dropstone 附带两个内置主代理，Build 和 Plan。我们将在下面介绍它们。

子代理

子代理是主代理可以为特定任务调用的专门助手。你也可以通过在消息中 @提及 它们来手动调用。

Dropstone 附带两个内置子代理，General 和 Explore。我们将在下面介绍它们。

内置代理

Dropstone 附带两个内置主代理和两个内置子代理。

使用 build

模式: primary

Build 是默认的主代理，启用了所有工具。这是开发工作的标准代理，你需要完全访问文件操作和系统命令。

使用 plan

模式: primary

一个受限代理，专为规划和设计。我们使用权限系统来给你更多控制权，并防止意外更改。默认情况下，以下所有内容都设置为 ask：

file edits：所有写入、补丁和编辑
bash：所有 bash 命令

当你希望 LLM 分析代码、建议更改或创建计划而不对你的代码库进行任何实际修改时，此代理非常有用。

使用 general

模式: subagent

一个通用代理，用于研究复杂问题和执行多步骤任务。具有完整的工具访问权限（除 todo 外），因此可以在需要时进行文件更改。使用它来并行运行多个工作单元。

使用 explore

模式: subagent

一个快速、只读的代理，用于探索代码库。不能修改文件。当你需要按模式快速查找文件、搜索代码关键字或回答有关代码库的问题时，请使用此代理。

使用 compaction

模式: primary

隐藏的系统代理，将长上下文压缩为较小的摘要。它在需要时自动运行，并且在 UI 中不可选择。

使用 title

模式: primary

隐藏的系统代理，生成简短的会话标题。它自动运行，并且在 UI 中不可选择。

使用 summary

模式: primary

隐藏的系统代理，创建会话摘要。它自动运行，并且在 UI 中不可选择。

用法

对于主代理，在会话期间使用 Tab 键循环切换它们。你也可以使用配置的 switch_agent 键位绑定。
子代理可以通过以下方式调用：
- 自动由主代理根据其描述为专门任务调用。
- 通过在消息中 @提及 子代理手动调用。例如：
```
@general help me search for this function
```
会话间导航：当子代理创建子会话时，使用 session_child_first（默认：<Leader>+Down）从父会话进入第一个子会话。
进入子会话后，使用：
- session_child_cycle（默认：Right）循环到下一个子会话
- session_child_cycle_reverse（默认：Left）循环到上一个子会话
- session_parent（默认：Up）返回父会话
这让你可以在主对话和专门的子代理工作之间切换。

配置

你可以自定义内置代理或通过配置创建自己的代理。代理可以通过两种方式配置：

JSON

在 dropstone.json 配置文件中配置代理：

{
  "$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 文件定义代理。将它们放置在：

全局：~/.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 文件名成为代理名称。例如，review.md 创建一个 review 代理。

选项

让我们详细看看这些配置选项。

描述

使用 description 选项提供代理功能以及何时使用的简要描述。

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

这是一个必需的配置选项。

温度

使用 temperature 配置控制 LLM 响应的随机性和创造性。

较低的值使响应更专注和确定性，而较高的值增加创造性和可变性。

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

温度值通常范围从 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}"
    }
  }
}

如果未指定温度，Dropstone 会为每个层级使用合理的默认值。

最大步骤

控制代理在被强制仅以文本响应之前可以执行的代理迭代的最大次数。这允许希望控制成本的用户设置代理操作的限制。

如果未设置，代理将继续迭代，直到模型选择停止或用户中断会话。

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

当达到限制时，代理会收到一个特殊的系统提示，指示它总结其工作并推荐剩余任务。

已弃用

旧的 maxSteps 字段已弃用。请改用 steps。

禁用

设置为 true 以禁用代理。

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

提示词

使用 prompt 配置为此代理指定自定义系统提示文件。提示文件应包含特定于代理目的的说明。

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

此路径相对于配置文件所在位置。因此，它适用于全局 Dropstone 配置和项目特定配置。

模型

使用 model 配置覆盖此代理的模型。对于使用针对不同任务优化的不同模型非常有用。例如，使用更快的模型进行规划，使用更强大的模型进行实现。

Tip

如果你未指定模型，主代理使用全局配置的模型，而子代理继承调用它们的主代理的模型。

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

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

工具（已弃用）

tools 已弃用。对于新配置、更新和更细粒度的控制，请优先使用代理的 permission 字段。

允许你控制此代理中可用的工具。你可以通过将特定工具设置为 true 或 false 来启用或禁用它们。在代理的 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

代理特定的配置会覆盖全局配置。

你也可以在旧的 tools 条目中使用通配符来同时控制多个工具。例如，要禁用来自 MCP 服务器的所有工具：

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

了解更多关于工具的信息。

权限

你可以配置权限来管理代理可以执行的操作。每个权限键可以设置为：

"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`	当代理似乎卡住时的恢复提示

read、edit、glob、grep、list、bash、task、external_directory、lsp 和 skill 接受简写操作（"allow" | "ask" | "deny"）或 glob/模式 → 操作的对象以进行细粒度控制。其余键仅接受简写操作。

Note

权限键作为通配符模式与底层工具名称匹配，因此相同的语法适用于内置工具、自定义工具和 MCP 工具。例如，"mymcp_*": "deny" 拒绝来自 MCP 服务器的所有工具，而 "mymcp_search": "ask" 针对单个工具。

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

你可以按代理覆盖这些权限。

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

你也可以在 Markdown 代理中设置权限。

---
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 模式。

{
  "$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"
        }
      }
    }
  }
}

了解更多关于权限的信息。

模式

使用 mode 配置控制代理的模式。mode 选项用于确定代理的使用方式。

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

mode 选项可以设置为 primary、subagent 或 all。如果未指定 mode，则默认为 all。

隐藏

使用 hidden: true 从 @ 自动完成菜单中隐藏子代理。对于只应由其他代理通过 Task 工具以编程方式调用的内部子代理非常有用。

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

这仅影响用户在自动完成菜单中的可见性。如果权限允许，隐藏的代理仍然可以由模型通过 Task 工具调用。

Note

仅适用于 mode: subagent 代理。

任务权限

使用 permission.task 控制代理可以通过 Task 工具调用的子代理。使用 glob 模式进行灵活匹配。

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

当设置为 deny 时，子代理会从 Task 工具描述中完全移除，因此模型不会尝试调用它。

Tip

规则按顺序评估，最后匹配的规则获胜。在上面的示例中，orchestrator-planner 同时匹配 *（拒绝）和 orchestrator-*（允许），但由于 orchestrator-* 在 * 之后，结果是 allow。

Tip

用户始终可以通过 @ 自动完成菜单直接调用任何子代理，即使代理的任务权限会拒绝它。

颜色

使用 color 选项自定义代理在 UI 中的视觉外观。这会影响代理在界面中的显示方式。

使用有效的十六进制颜色（例如，#FF5733）或主题颜色：primary、secondary、accent、success、warning、error、info。

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

Top P

使用 top_p 选项控制响应多样性。作为控制随机性的温度的替代方案。

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

值范围从 0.0 到 1.0。较低的值更专注，较高的值更多样化。

附加选项

你在代理配置中指定的任何其他选项都会直接传递作为模型选项。对于 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 查看可用的层级。

创建代理

你可以使用以下命令创建新代理：

dropstone agent create

这个交互式命令将：

询问将代理保存在哪里；全局或项目特定。
代理应做什么的描述。
生成适当的系统提示和标识符。
让你选择代理应允许的权限（你未选择的任何内容都会被拒绝）。
最后，创建一个包含代理配置的 markdown 文件。

使用案例

以下是一些不同代理的常见使用案例。

Build 代理：启用所有工具的完整开发工作
Plan 代理：在不进行更改的情况下进行分析和规划
Review 代理：具有只读访问权限以及文档工具的代码审查
Debug 代理：专注于使用 bash 和读取工具进行调查
Docs 代理：具有文件操作但没有系统命令的文档编写

示例

以下是一些你可能觉得有用的示例代理。

Tip

有一个你想分享的代理？联系我们，我们将展示它。

文档代理

---
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)

代理

类型

主代理

子代理

内置代理

使用 build

使用 plan

使用 general

使用 explore

使用 compaction

使用 title

使用 summary

用法

配置

JSON

Markdown

选项

描述

温度

最大步骤

禁用

提示词

模型

工具（已弃用）

权限

模式

隐藏

任务权限

颜色

Top P

附加选项

创建代理

使用案例

示例

文档代理

安全审计员

本页内容