Плагины

Напишите собственные плагины для расширения Dropstone.

Плагины позволяют расширить Dropstone, подключаясь к различным событиям и настраивая поведение. Вы можете создавать плагины для добавления новых функций, интеграции с внешними сервисами или изменения поведения Dropstone по умолчанию.

Использование плагина

Есть два способа загрузки плагинов.

Из локальных файлов

Поместите файлы JavaScript или TypeScript в директорию плагинов.

.dropstone/plugins/ - плагины уровня проекта
~/.config/dropstone/plugins/ - глобальные плагины

Файлы в этих директориях автоматически загружаются при запуске.

Из npm

Укажите пакеты npm в файле конфигурации.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "plugin": ["@my-org/internal-plugin", "dropstone-notify-on-idle"]
}

Поддерживаются как обычные, так и scoped пакеты npm.

Как устанавливаются плагины

npm плагины устанавливаются автоматически с использованием Bun при запуске. Пакеты и их зависимости кэшируются в ~/.cache/dropstone/node_modules/.

Локальные плагины загружаются непосредственно из директории плагинов. Для использования внешних пакетов необходимо создать package.json в директории конфигурации (см. Зависимости), или опубликовать плагин в npm и добавить его в конфигурацию.

Порядок загрузки

Плагины загружаются из всех источников и все хуки выполняются последовательно. Порядок загрузки:

Глобальная конфигурация (~/.config/dropstone/dropstone.json)
Конфигурация проекта (dropstone.json)
Глобальная директория плагинов (~/.config/dropstone/plugins/)
Директория плагинов проекта (.dropstone/plugins/)

Дублирующиеся пакеты npm с одинаковым именем и версией загружаются один раз. Однако локальный плагин и npm плагин с похожими именами загружаются отдельно.

Создание плагина

Плагин — это модуль JavaScript/TypeScript, который экспортирует одну или несколько функций плагина. Каждая функция получает объект контекста и возвращает объект хуков.

Зависимости

Локальные плагины и пользовательские инструменты могут использовать внешние пакеты npm. Добавьте package.json в директорию конфигурации с необходимыми зависимостями.

{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}

Dropstone запускает bun install при старте для установки этих зависимостей. Ваши плагины и инструменты смогут их импортировать.

import { escape } from "shescape"

export const MyPlugin = async (ctx) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "bash") {
        output.args.command = escape(output.args.command)
      }
    },
  }
}

Базовая структура

export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")

  return {
    // Hook implementations go here
  }
}

Функция плагина получает:

project: информация о текущем проекте.
directory: текущая рабочая директория.
worktree: путь к git worktree.
client: клиент Dropstone SDK для взаимодействия с агентом.
$: shell API Bun для выполнения команд.

Поддержка TypeScript

Для плагинов TypeScript вы можете импортировать типы из пакета плагина:

import type { Plugin } from "@blankline/dropstone-plugin"

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Type-safe hook implementations
  }
}

События

Плагины могут подписываться на события, как показано ниже в разделе примеров. Вот список доступных событий.

События команд

command.executed

События файлов

file.edited
file.watcher.updated

События установки

installation.updated

События LSP

lsp.client.diagnostics
lsp.updated

События сообщений

message.part.removed
message.part.updated
message.removed
message.updated

События разрешений

permission.asked
permission.replied

События сервера

server.connected

События сессии

session.created
session.compacted
session.deleted
session.diff
session.error
session.idle
session.status
session.updated

События задач

todo.updated

События shell

shell.env

События инструментов

tool.execute.after
tool.execute.before

Примеры

Вот несколько примеров плагинов, которые вы можете использовать для расширения dropstone.

Отправка уведомлений

Отправляйте уведомления при возникновении определённых событий:

export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    event: async ({ event }) => {
      // Send notification on session completion
      if (event.type === "session.idle") {
        await $`osascript -e 'display notification "Session completed!" with title "dropstone"'`
      }
    },
  }
}

Мы используем osascript для запуска AppleScript на macOS. Здесь мы используем его для отправки уведомлений.

Защита .env

Предотвратите чтение файлов .env в dropstone:

export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Do not read .env files")
      }
    },
  }
}

Внедрение переменных окружения

Внедряйте переменные окружения во все выполнения shell (инструменты AI и пользовательские терминалы):

export const InjectEnvPlugin = async () => {
  return {
    "shell.env": async (input, output) => {
      output.env.MY_API_KEY = "secret"
      output.env.PROJECT_ROOT = input.cwd
    },
  }
}

Пользовательские инструменты

Плагины также могут добавлять пользовательские инструменты в dropstone:

import { type Plugin, tool } from "@blankline/dropstone-plugin"

export const CustomToolsPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      mytool: tool({
        description: "This is a custom tool",
        args: {
          foo: tool.schema.string(),
        },
        async execute(args, context) {
          const { directory, worktree } = context
          return `Hello ${args.foo} from ${directory} (worktree: ${worktree})`
        },
      }),
    },
  }
}

Вспомогательная функция tool создаёт пользовательский инструмент, который может вызывать dropstone. Она принимает функцию схемы Zod и возвращает определение инструмента с:

description: описание того, что делает инструмент
args: схема Zod для аргументов инструмента
execute: функция, которая выполняется при вызове инструмента

Ваши пользовательские инструменты будут доступны dropstone наряду со встроенными инструментами.

Note:

Если инструмент плагина имеет то же имя, что и встроенный инструмент, инструмент плагина имеет приоритет.

Логирование

Используйте client.app.log() вместо console.log для структурированного логирования:

export const MyPlugin = async ({ client }) => {
  await client.app.log({
    body: {
      service: "my-plugin",
      level: "info",
      message: "Plugin initialized",
      extra: { foo: "bar" },
    },
  })
}

Уровни: debug, info, warn, error. Подробнее см. в справке SDK.

Хуки компактификации

Настройте контекст, включаемый при компактификации сессии:

import type { Plugin } from "@blankline/dropstone-plugin"

export const CompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Inject additional context into the compaction prompt
      output.context.push(`
## Custom Context

Include any state that should persist across compaction:
- Current task status
- Important decisions made
- Files being actively worked on
`)
    },
  }
}

Хук experimental.session.compacting срабатывает перед тем, как LLM генерирует сводку продолжения. Используйте его для внедрения контекста, специфичного для вашей области, который стандартный запрос компактификации может пропустить.

Вы также можете полностью заменить запрос компактификации, установив output.prompt:

import type { Plugin } from "@blankline/dropstone-plugin"

export const CustomCompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Replace the entire compaction prompt
      output.prompt = `
You are generating a continuation prompt for a long-running coding session.

Summarize:
1. The current task and its status
2. Which files are being modified
3. Any blockers or open questions
4. The next steps to complete the work

Format as a structured prompt the next session can use to resume work.
`
    },
  }
}

Когда установлен output.prompt, он полностью заменяет стандартный запрос компактификации. Массив output.context в этом случае игнорируется.

Skills

Custom Tools