配置

使用 Dropstone JSON 配置文件。

您可以使用 JSON 配置文件来配置 Dropstone。

格式

Dropstone 支持 JSON 和 JSONC（带注释的 JSON）两种格式。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "dropstone/dropstone-pro",
  "autoupdate": true,
  "server": {
    "port": 4096,
  },
}

位置

您可以将配置文件放在几个不同的位置，它们具有不同的优先级顺序。

Note:

配置文件会被合并，而不是被替换。来自以下配置位置的设置会被组合在一起。后面的配置仅在键冲突时覆盖前面的配置。所有配置中的非冲突设置都会被保留。

例如，如果您的全局配置设置了 autoupdate: true，而项目配置设置了 model: "dropstone/dropstone-pro"，最终配置将同时包含这两个设置。

优先级顺序

配置源按以下顺序加载（后面的源覆盖前面的源）：

远程配置（来自 .well-known/dropstone）- 组织默认设置
全局配置（~/.config/dropstone/dropstone.json）- 用户偏好
自定义配置（DROPSTONE_CONFIG 环境变量）- 自定义覆盖
项目配置（项目中的 dropstone.json）- 项目特定设置
.dropstone 目录 - agents、commands、plugins
托管配置文件（macOS 上的 /Library/Application Support/dropstone/）- 管理员控制
macOS 托管偏好设置（通过 MDM 的 .mobileconfig）- 最高优先级，用户无法覆盖

这意味着项目配置可以覆盖全局默认值，全局配置可以覆盖远程组织默认值。托管设置覆盖所有其他设置。

Note:

.dropstone 和 ~/.config/dropstone 目录使用复数名称作为子目录：agents/、commands/、modes/、plugins/、skills/、tools/。为向后兼容，也支持单数名称（例如 agent/）。

远程

组织可以通过其域名上的 .well-known/dropstone 端点提供默认配置。对于账户已注册到该组织的用户，Dropstone 会在首次登录时自动获取此配置。

远程配置首先加载，作为基础层。所有其他配置源（全局、项目）都可以覆盖这些默认值。

例如，如果您的组织提供了默认禁用的 MCP 服务器：

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

您可以在本地配置中启用特定的服务器：

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

全局

将您的全局 Dropstone 配置放在 ~/.config/dropstone/dropstone.json 中。使用全局配置来设置用户级偏好，如模型和权限。

对于会话级设置（按键绑定、滚动、鼠标捕获），请使用 ~/.config/dropstone/tui.json。

全局配置覆盖远程组织默认值。

每个项目

在项目根目录中添加 dropstone.json。项目配置在标准配置文件中具有最高优先级 - 它覆盖全局和远程配置。

对于项目特定的会话设置，请在其旁边添加 tui.json。

提示:

将项目特定配置放在项目的根目录中。

当 Dropstone 启动时，它会在当前目录中查找配置文件，或向上遍历到最近的 Git 目录。

这也可以安全地提交到 Git，并使用与全局配置相同的 schema。

自定义路径

使用 DROPSTONE_CONFIG 环境变量指定自定义配置文件路径。

export DROPSTONE_CONFIG=/path/to/my/custom-config.json
dropstone run "Hello world"

在优先级顺序中，自定义配置在全局配置和项目配置之间加载。

托管设置

组织可以强制实施用户无法覆盖的配置。托管设置在最高优先级层级加载。

基于文件

将 dropstone.json 或 dropstone.jsonc 文件放入系统托管的配置目录：

平台	路径
macOS	`/Library/Application Support/dropstone/`
Linux	`/etc/dropstone/`
Windows	`%ProgramData%\dropstone`

这些目录需要管理员/root 权限才能写入，因此用户无法修改它们。

macOS 托管偏好设置

在 macOS 上，Dropstone 从 ai.dropstone.managed 偏好域读取托管偏好设置。通过 MDM（Jamf、Kandji、FleetDM）部署 .mobileconfig，设置将自动强制执行。

Dropstone 检查以下路径：

/Library/Managed Preferences/<user>/ai.dropstone.managed.plist
/Library/Managed Preferences/ai.dropstone.managed.plist

plist 键直接映射到 dropstone.json 字段。MDM 元数据键（PayloadUUID、PayloadType 等）会自动剥离。

创建 .mobileconfig

使用 ai.dropstone.managed PayloadType。Dropstone 配置键直接放在 payload 字典中：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key>
      <string>ai.dropstone.managed</string>
      <key>PayloadIdentifier</key>
      <string>com.example.dropstone.config</string>
      <key>PayloadUUID</key>
      <string>GENERATE-YOUR-OWN-UUID</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>share</key>
      <string>disabled</string>
      <key>server</key>
      <dict>
        <key>hostname</key>
        <string>127.0.0.1</string>
      </dict>
      <key>permission</key>
      <dict>
        <key>*</key>
        <string>ask</string>
        <key>bash</key>
        <dict>
          <key>*</key>
          <string>ask</string>
          <key>rm -rf *</key>
          <string>deny</string>
        </dict>
      </dict>
    </dict>
  </array>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadIdentifier</key>
  <string>com.example.dropstone</string>
  <key>PayloadUUID</key>
  <string>GENERATE-YOUR-OWN-UUID</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
</dict>
</plist>

使用 uuidgen 生成唯一的 UUID。自定义设置以匹配您组织的要求。

通过 MDM 部署

Jamf Pro: 计算机 > 配置配置文件 > 上传 > 范围到目标设备或智能组
FleetDM: 将 .mobileconfig 添加到您的 gitops 仓库中的 mdm.macos_settings.custom_settings 下，然后运行 fleetctl apply

在设备上验证

双击 .mobileconfig 以在本地安装进行测试（显示在系统设置 > 隐私与安全性 > 配置文件中），然后运行：

dropstone debug config

所有托管偏好设置键都会出现在解析后的配置中，并且无法被用户或项目配置覆盖。

Schema

主配置 schema 定义在 dropstone.io/config.json。

会话级配置（tui.json）使用 dropstone.io/tui.json。

您的编辑器应该能够根据 schema 进行验证和自动补全。

会话配置

使用专用的 tui.json（或 tui.jsonc）文件进行会话级设置：滚动行为、鼠标捕获、diff 渲染等。

{
  "$schema": "https://dropstone.io/schema/tui.json",
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto",
  "mouse": true
}

dropstone.json 中旧的 theme、keybinds 和与会话相关的键已弃用，并会在可能的情况下自动迁移。

服务器

您可以通过 server 选项配置 dropstone serve 和 dropstone web 命令的服务器设置。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

可用选项：

port - 监听的端口。
hostname - 监听的主机名。当启用 mdns 且未设置主机名时，默认为 0.0.0.0。
mdns - 启用 mDNS 服务发现。这允许网络上的其他设备发现您的 Dropstone 服务器。
mdnsDomain - mDNS 服务的自定义域名。默认为 dropstone.local。适用于在同一网络上运行多个实例。
cors - 使用基于浏览器的客户端通过 HTTP 服务器时，允许的额外 CORS 来源。值必须是完整的来源（协议 + 主机 + 可选端口），例如 https://app.example.com。

在此了解更多关于服务器的信息。

Shell

您可以使用 shell 选项配置交互式终端使用的 shell。兼容的 shell 也用于代理工具调用。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "shell": "pwsh"
}

如果未指定，Dropstone 将根据您的操作系统自动发现并使用合理的默认值（例如 Windows 上的 pwsh 或 cmd.exe，macOS/Linux 上的 /bin/zsh 或 /bin/bash）。您可以提供绝对路径或短名称。

工具

您可以通过 tools 选项管理 LLM 可以使用的工具。

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

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

模型

使用 model 选项设置您的默认模型。Dropstone 提供三个层级：

层级	模型 ID
Fast	`dropstone/dropstone-fast`
Pro	`dropstone/dropstone-pro`
Heavy	`dropstone/dropstone-heavy`

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "dropstone/dropstone-pro"
}

使用 variant 固定默认推理深度：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "dropstone/dropstone-pro",
  "variant": "high"
}

有效的 variant 值为 low、medium、high、xhigh。有关完整说明，请参阅模型。

small_model 选项为标题生成等轻量任务配置单独的模型。默认情况下，Dropstone 会选择适当的层级；您可以显式覆盖它：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "dropstone/dropstone-pro",
  "small_model": "dropstone/dropstone-fast"
}

Agents

您可以通过 agent 选项为特定任务配置专门的 agents。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "agent": {
    "code-reviewer": {
      "description": "审查代码以发现最佳实践和潜在问题",
      "model": "dropstone/dropstone-pro",
      "prompt": "您是一名代码审查员。专注于安全性、性能和维护性。",
      "tools": {
        // 为仅审查的代理禁用文件修改工具
        "write": false,
        "edit": false,
      },
    },
  },
}

您还可以使用 ~/.config/dropstone/agents/ 或 .dropstone/agents/ 中的 markdown 文件定义 agents。在此了解更多。

默认代理

您可以使用 default_agent 选项设置默认代理。这决定了在未明确指定时使用哪个代理。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "default_agent": "plan"
}

默认代理必须是主代理（不是子代理）。这可以是内置代理，如 "build" 或 "plan"，也可以是您定义的自定义代理。如果指定的代理不存在或是子代理，Dropstone 将回退到 "build" 并发出警告。

此设置适用于所有界面：交互式会话、单次运行（dropstone run）和 GitHub Action。

命令

您可以通过 command 选项为重复性任务配置自定义命令。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "command": {
    "test": {
      "template": "运行完整的测试套件并生成覆盖率报告，显示任何失败。\n关注失败的测试并提出修复建议。",
      "description": "运行带覆盖率的测试",
      "agent": "build",
      "model": "dropstone/dropstone-fast",
    },
    "component": {
      "template": "创建一个名为 $ARGUMENTS 的新 React 组件，支持 TypeScript。\n包含正确的类型定义和基本结构。",
      "description": "创建一个新组件",
    },
  },
}

您还可以使用 ~/.config/dropstone/commands/ 或 .dropstone/commands/ 中的 markdown 文件定义命令。在此了解更多。

按键映射

在 tui.json 中使用 keymap 自定义键盘快捷键。

{
  "$schema": "https://dropstone.io/schema/tui.json",
  "keymap": {
    "sections": {
      "global": {
        "command.palette.show": "ctrl+p"
      }
    }
  }
}

keymap 与内置默认值合并，因此您只需配置要更改的快捷键。

较旧的 keybinds 字段已弃用，仅在 keymap 不存在时生效。

在此了解更多。

快照

Dropstone 使用快照来跟踪代理操作期间的文件更改，使您能够在会话中撤销和还原更改。快照默认启用。

对于大型仓库或包含许多子模块的项目，快照系统可能导致索引缓慢和大量磁盘使用。您可以使用 snapshot 选项禁用快照。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "snapshot": false
}

请注意，禁用快照意味着代理所做的更改无法通过 UI 回滚。

自动更新

Dropstone 会在启动时自动下载任何新更新。您可以使用 autoupdate 选项禁用此功能。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "autoupdate": false
}

如果您不想更新，但希望在新版本可用时收到通知，请将 autoupdate 设置为 "notify"。请注意，这仅适用于未通过包管理器（如 Homebrew）安装的情况。

格式化器

您可以通过 formatter 选项启用和配置代码格式化器。省略此选项以保持格式化器禁用。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "formatter": true
}

使用对象来保持内置格式化器启用，同时配置覆盖或自定义格式化器。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

在此了解更多关于格式化器的信息。

LSP 服务器

您可以通过 lsp 选项启用和配置 LSP 服务器。省略此选项以保持 LSP 禁用。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "lsp": true
}

使用对象来保持内置 LSP 服务器启用，同时配置覆盖或自定义 LSP 服务器。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "lsp": {
    "typescript": {
      "disabled": true
    }
  }
}

在此了解更多关于 LSP 服务器的信息。

权限

默认情况下，Dropstone 允许所有操作，无需明确批准。您可以使用 permission 选项更改此行为。

例如，要确保 edit 和 bash 工具需要用户批准：

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

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

压缩

您可以通过 compaction 选项控制上下文压缩行为。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

auto - 当上下文已满时自动压缩会话（默认：true）。
prune - 删除旧的工具输出以节省 token（默认：true）。
reserved - 压缩的 token 缓冲区。留出足够的窗口以避免压缩期间溢出。

监视器

您可以通过 watcher 选项配置文件监视器的忽略模式。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

模式遵循 glob 语法。使用此选项排除文件监视中的嘈杂目录。

MCP 服务器

您可以通过 mcp 选项配置要使用的 MCP 服务器。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "mcp": {}
}

在此了解更多。

插件

插件通过自定义工具、钩子和集成扩展 Dropstone。

将插件文件放在 .dropstone/plugins/ 或 ~/.config/dropstone/plugins/ 中。您还可以通过 plugin 选项从 npm 加载插件。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "plugin": ["@my-org/custom-plugin", "./local-plugin.ts"]
}

在此了解更多。

指令

您可以通过 instructions 选项配置您所用模型的指令。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

这接受指令文件的路径和 glob 模式数组。在此了解更多关于规则的信息。

实验性

experimental 键包含正在积极开发中的选项。

{
  "$schema": "https://dropstone.io/schema/config.json",
  "experimental": {}
}

不稳定:

实验性选项不稳定。它们可能随时更改或删除，恕不另行通知。

变量

您可以在配置文件中使用变量替换来引用环境变量和文件内容。

环境变量

使用 {env:VARIABLE_NAME} 替换环境变量：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "{env:DROPSTONE_MODEL}"
}

如果环境变量未设置，它将被替换为空字符串。

文件

使用 {file:path/to/file} 替换文件内容：

{
  "$schema": "https://dropstone.io/schema/config.json",
  "instructions": ["./custom-instructions.md"]
}

文件路径可以是：

相对于配置文件目录的路径
或以 / 或 ~ 开头的绝对路径

这些对于以下情况很有用：

包含大型指令文件而不会使配置混乱。
在多个配置文件之间共享常见的配置片段。

Keybindings

Models

配置

格式

位置

优先级顺序

远程

全局

每个项目

自定义路径

托管设置

基于文件

macOS 托管偏好设置

Schema

会话配置

服务器

Shell

工具

模型

Agents

默认代理

命令

按键映射

快照

自动更新

格式化器

LSP 服务器

权限

压缩

监视器

MCP 服务器

插件

指令

实验性

变量

环境变量

文件

本页内容