Plugins

Écrivez vos propres plugins pour étendre Dropstone.

Les plugins vous permettent d'étendre Dropstone en vous connectant à divers événements et en personnalisant le comportement. Vous pouvez créer des plugins pour ajouter de nouvelles fonctionnalités, intégrer des services externes ou modifier le comportement par défaut de Dropstone.

Utiliser un plugin

Il y a deux façons de charger les plugins.

À partir de fichiers locaux

Placez des fichiers JavaScript ou TypeScript dans le répertoire des plugins.

.dropstone/plugins/ - Plugins au niveau du projet
~/.config/dropstone/plugins/ - Plugins globaux

Les fichiers dans ces répertoires sont automatiquement chargés au démarrage.

À partir de npm

Spécifiez les packages npm dans votre fichier de configuration.

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

Les packages npm réguliers et les packages avec portée sont tous deux pris en charge.

Comment les plugins sont installés

Les plugins npm sont installés automatiquement à l'aide de Bun au démarrage. Les packages et leurs dépendances sont mis en cache dans ~/.cache/dropstone/node_modules/.

Les plugins locaux sont chargés directement à partir du répertoire des plugins. Pour utiliser des packages externes, vous devez créer un package.json dans votre répertoire de configuration (voir Dépendances), ou publier le plugin sur npm et l'ajouter à votre configuration.

Ordre de chargement

Les plugins sont chargés à partir de toutes les sources et tous les hooks s'exécutent en séquence. L'ordre de chargement est :

Configuration globale (~/.config/dropstone/dropstone.json)
Configuration du projet (dropstone.json)
Répertoire des plugins globaux (~/.config/dropstone/plugins/)
Répertoire des plugins du projet (.dropstone/plugins/)

Les packages npm en double avec le même nom et la même version sont chargés une seule fois. Cependant, un plugin local et un plugin npm avec des noms similaires sont tous deux chargés séparément.

Créer un plugin

Un plugin est un module JavaScript/TypeScript qui exporte une ou plusieurs fonctions de plugin. Chaque fonction reçoit un objet de contexte et retourne un objet de hooks.

Dépendances

Les plugins locaux et les outils personnalisés peuvent utiliser des packages npm externes. Ajoutez un package.json à votre répertoire de configuration avec les dépendances dont vous avez besoin.

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

Dropstone exécute bun install au démarrage pour installer ces packages. Vos plugins et outils peuvent ensuite les importer.

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

Structure de base

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

  return {
    // Hook implementations go here
  }
}

La fonction du plugin reçoit :

project : Les informations du projet actuel.
directory : Le répertoire de travail actuel.
worktree : Le chemin du worktree git.
client : Un client SDK Dropstone pour interagir avec l'agent.
$ : L'API shell de Bun pour exécuter des commandes.

Support de TypeScript

Pour les plugins TypeScript, vous pouvez importer les types du package de plugin :

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

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

Événements

Les plugins peuvent s'abonner à des événements comme indiqué ci-dessous dans la section Exemples. Voici une liste des différents événements disponibles.

Événements de commande

command.executed

Événements de fichier

file.edited
file.watcher.updated

Événements d'installation

installation.updated

Événements LSP

lsp.client.diagnostics
lsp.updated

Événements de message

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

Événements de permission

permission.asked
permission.replied

Événements de serveur

server.connected

Événements de session

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

Événements Todo

todo.updated

Événements Shell

shell.env

Événements Tool

tool.execute.after
tool.execute.before

Exemples

Voici quelques exemples de plugins que vous pouvez utiliser pour étendre dropstone.

Envoyer des notifications

Envoyez des notifications lorsque certains événements se produisent :

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"'`
      }
    },
  }
}

Nous utilisons osascript pour exécuter AppleScript sur macOS. Ici, nous l'utilisons pour envoyer des notifications.

Protection .env

Empêchez dropstone de lire les fichiers .env :

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")
      }
    },
  }
}

Injecter des variables d'environnement

Injectez des variables d'environnement dans toute l'exécution shell (outils IA et terminaux utilisateur) :

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

Outils personnalisés

Les plugins peuvent également ajouter des outils personnalisés à 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})`
        },
      }),
    },
  }
}

L'assistant tool crée un outil personnalisé que dropstone peut appeler. Il prend une fonction de schéma Zod et retourne une définition d'outil avec :

description : Ce que fait l'outil
args : Schéma Zod pour les arguments de l'outil
execute : Fonction qui s'exécute lorsque l'outil est appelé

Vos outils personnalisés seront disponibles pour dropstone aux côtés des outils intégrés.

Note:

Si un outil de plugin porte le même nom qu'un outil intégré, l'outil de plugin a la priorité.

Journalisation

Utilisez client.app.log() au lieu de console.log pour la journalisation structurée :

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

Niveaux : debug, info, warn, error. Voir la référence SDK pour plus de détails.

Hooks de compaction

Personnalisez le contexte inclus lors de la compaction d'une session :

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
`)
    },
  }
}

Le hook experimental.session.compacting se déclenche avant que le LLM génère un résumé de continuation. Utilisez-le pour injecter un contexte spécifique au domaine que l'invite de compaction par défaut pourrait manquer.

Vous pouvez également remplacer entièrement l'invite de compaction en définissant 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.
`
    },
  }
}

Lorsque output.prompt est défini, il remplace complètement l'invite de compaction par défaut. Le tableau output.context est ignoré dans ce cas.

Skills

Custom Tools