核心概念

Dropstone 是一款在终端中运行的代理式编码工具。它可以读取代码、运行命令、规划更改、编辑文件并验证结果。本页涵盖了你只需学习一次的核心概念：代理运行的循环、它可以访问的内容、会话如何工作、上下文如何管理，以及权限如何让你保持掌控。

代理循环

当你给 Dropstone 一个任务时，它会经历三个阶段：收集上下文、采取行动和验证结果。这些阶段会相互融合。Dropstone 全程使用工具，无论是读取文件以理解你的代码、编辑以进行更改，还是运行测试以检查其工作。

这个循环会根据你的要求进行调整。关于代码库的问题可能只需要收集上下文。修复 bug 会循环经历所有三个阶段。大型重构可能涉及大量验证。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 可以看到你的整个项目，所以它可以跨项目工作。当你要求它“修复认证 bug”时，它会搜索相关文件，读取多个文件以理解上下文，跨文件进行协调编辑，运行测试以验证，并在你要求时提交。这与只能看到当前文件的内联代码助手不同。

会话

每个交互式会话都保存在本地。每条消息、每次工具使用和每个结果都会写入会话记录，这使得撤销、恢复和分叉过去的工作成为可能。

会话是独立的。新会话以全新的上下文窗口开始，不记得之前的对话。持久知识应放在 AGENTS.md 中，而不是对话历史中。

恢复或分叉会话

使用 dropstone --continue（或 dropstone -c）恢复会重新打开当前目录中最近的会话，并向其追加新消息。按 id 恢复特定会话使用 dropstone --session <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 高效协作

一些往往能产生更好结果的模式。

这是一场对话

你不需要一个完美的初始提示。从你想要什么开始，看看代理做什么，然后纠正它：

修复登录 bug

不，问题出在会话处理上，不是表单验证

你不是在重新开始。你是在迭代。每一轮都会细化代理的理解。

中断并引导

你可以随时重定向 Dropstone：

• 按 Esc 立即停止。当前工具调用被取消，Dropstone 等待你的下一条指令。
• 输入更正并按 Enter，无需等待。Dropstone 会在当前操作完成后立即读取，并在决定下一步之前进行调整。

一开始就具体明确

你的初始提示越精确，需要的更正就越少。引用文件、提及约束、指向示例模式：

结账流程对持过期卡的用户是坏的。
在 src/payments/ 中查找问题，尤其是令牌刷新。
先写一个失败的测试，然后修复它。

模糊的提示也能工作，但你会花更多时间引导。像上面这样的具体提示通常第一次尝试就能成功。

给 Dropstone 一些可以验证的东西

当代理可以检查自己的工作时，它的表现会更好。包含测试用例、预期输出或验收标准：

实现 validateEmail。测试用例：
  'user@example.com' -> true
  'invalid'           -> false
  'user@.com'         -> false
之后运行测试。

先探索再实现

对于复杂问题，将研究与编码分开。切换到计划模式（Tab），让 Dropstone 研究相关代码，通过对话完善计划，然后切换回构建模式执行：

阅读 src/auth/ 并解释我们目前如何处理会话。
然后提出一个添加 OAuth 支持的计划。

审查计划，对你不同意的任何内容提出异议，然后让 Dropstone 实现。这种两阶段方法比直接写代码能产生持续更好的结果。

委派，而不是指挥

把 Dropstone 当作一位能干的同事。提供上下文和方向，然后信任代理去弄清楚细节：

结账流程对持过期卡的用户是坏的。
相关代码在 src/payments/ 中。
调查并修复它。

你不需要指定要读取哪些文件、运行哪些命令或按什么顺序做事。Dropstone 会从提示中自行解决。

下一步