配置

使用 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，并使用与全局配置相同的架构。

自定义路径

使用 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 配置键直接进入有效负载字典：

<?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： Computers > Configuration Profiles > Upload > 范围到目标设备或智能组
FleetDM： 将 .mobileconfig 添加到您的 gitops 存储库中的 mdm.macos_settings.custom_settings 下，并运行 fleetctl apply

在设备上验证

双击 .mobileconfig 以在本地安装进行测试（显示在 System Settings > Privacy & Security > Profiles 中），然后运行：

dropstone debug config

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

架构

主配置架构定义在 dropstone.io/config.json 中。

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

您的编辑器应该能够根据架构进行验证和自动完成。

会话配置

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

{
  "$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 服务器时允许的其他来源。值必须是完整来源（scheme + host + 可选端口），例如 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"
}

代理

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

{
  "$schema": "https://dropstone.io/schema/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "dropstone/dropstone-pro",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // Disable file modification tools for review-only agent
        "write": false,
        "edit": false,
      },
    },
  },
}

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

默认代理

您可以使用 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": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "dropstone/dropstone-fast",
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component",
    },
  },
}

您也可以在 ~/.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 - 删除旧的工具输出以节省令牌（默认：true）。
reserved - 压缩的令牌缓冲区。留下足够的窗口以避免压缩期间溢出

监视器

您可以通过 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 托管偏好设置

架构

会话配置

服务器

Shell

工具

模型

代理

默认代理

命令

键盘映射

快照

自动更新

格式化程序

LSP 服务器

权限

压缩

监视器

MCP 服务器

插件

说明

实验性

变量

环境变量

文件

本頁內容