Complementos

Escribe tus propios complementos para extender Dropstone.

Los complementos te permiten extender Dropstone enganchándote en varios eventos y personalizando el comportamiento. Puedes crear complementos para agregar nuevas características, integrar con servicios externos o modificar el comportamiento predeterminado de Dropstone.

Usar un complemento

Hay dos formas de cargar complementos.

Desde archivos locales

Coloca archivos JavaScript o TypeScript en el directorio de complementos.

.dropstone/plugins/ - Complementos a nivel de proyecto
~/.config/dropstone/plugins/ - Complementos globales

Los archivos en estos directorios se cargan automáticamente al iniciar.

Desde npm

Especifica paquetes npm en tu archivo de configuración.

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

Se admiten tanto paquetes npm regulares como paquetes con alcance.

Cómo se instalan los complementos

Los complementos npm se instalan automáticamente usando Bun al iniciar. Los paquetes y sus dependencias se almacenan en caché en ~/.cache/dropstone/node_modules/.

Los complementos locales se cargan directamente desde el directorio de complementos. Para usar paquetes externos, debes crear un package.json dentro de tu directorio de configuración (consulta Dependencias), o publicar el complemento en npm y añadirlo a tu configuración.

Orden de carga

Los complementos se cargan desde todas las fuentes y todos los hooks se ejecutan en secuencia. El orden de carga es:

Configuración global (~/.config/dropstone/dropstone.json)
Configuración del proyecto (dropstone.json)
Directorio de complementos global (~/.config/dropstone/plugins/)
Directorio de complementos del proyecto (.dropstone/plugins/)

Los paquetes npm duplicados con el mismo nombre y versión se cargan una sola vez. Sin embargo, un complemento local y un complemento npm con nombres similares se cargan por separado.

Crear un complemento

Un complemento es un módulo JavaScript/TypeScript que exporta una o más funciones de complemento. Cada función recibe un objeto de contexto y devuelve un objeto de hooks.

Dependencias

Los complementos locales y las herramientas personalizadas pueden usar paquetes npm externos. Añade un package.json a tu directorio de configuración con las dependencias que necesites.

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

Dropstone ejecuta bun install al iniciar para instalar estas. Tus complementos y herramientas pueden entonces importarlas.

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

Estructura básica

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

  return {
    // Hook implementations go here
  }
}

La función del complemento recibe:

project: La información del proyecto actual.
directory: El directorio de trabajo actual.
worktree: La ruta del árbol de trabajo de git.
client: Un cliente SDK de Dropstone para interactuar con el agente.
$: La API shell de Bun para ejecutar comandos.

Soporte de TypeScript

Para complementos de TypeScript, puedes importar tipos del paquete de complementos:

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

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

Eventos

Los complementos pueden suscribirse a eventos como se ve a continuación en la sección de Ejemplos. Aquí hay una lista de los diferentes eventos disponibles.

Eventos de comando

command.executed

Eventos de archivo

file.edited
file.watcher.updated

Eventos de instalación

installation.updated

Eventos de LSP

lsp.client.diagnostics
lsp.updated

Eventos de mensaje

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

Eventos de permiso

permission.asked
permission.replied

Eventos de servidor

server.connected

Eventos de sesión

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

Eventos de tareas pendientes

todo.updated

Eventos de shell

shell.env

Eventos de herramienta

tool.execute.after
tool.execute.before

Ejemplos

Aquí hay algunos ejemplos de complementos que puedes usar para extender dropstone.

Enviar notificaciones

Envía notificaciones cuando ocurren ciertos eventos:

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

Estamos usando osascript para ejecutar AppleScript en macOS. Aquí lo estamos usando para enviar notificaciones.

Protección de .env

Evita que dropstone lea archivos .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")
      }
    },
  }
}

Inyectar variables de entorno

Inyecta variables de entorno en toda la ejecución de shell (herramientas de IA y terminales de usuario):

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

Herramientas personalizadas

Los complementos también pueden agregar herramientas personalizadas a 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})`
        },
      }),
    },
  }
}

El ayudante tool crea una herramienta personalizada que dropstone puede llamar. Toma una función de esquema Zod y devuelve una definición de herramienta con:

description: Lo que hace la herramienta
args: Esquema Zod para los argumentos de la herramienta
execute: Función que se ejecuta cuando se llama a la herramienta

Tus herramientas personalizadas estarán disponibles para dropstone junto con las herramientas integradas.

Note:

Si una herramienta de complemento usa el mismo nombre que una herramienta integrada, la herramienta de complemento tiene prioridad.

Registro

Usa client.app.log() en lugar de console.log para registro estructurado:

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

Niveles: debug, info, warn, error. Consulta la referencia del SDK para más detalles.

Hooks de compactación

Personaliza el contexto incluido cuando se compacta una sesión:

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

El hook experimental.session.compacting se dispara antes de que el LLM genere un resumen de continuación. Úsalo para inyectar contexto específico del dominio que el mensaje de compactación predeterminado podría perder.

También puedes reemplazar completamente el mensaje de compactación estableciendo 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.
`
    },
  }
}

Cuando se establece output.prompt, reemplaza completamente el mensaje de compactación predeterminado. El array output.context se ignora en este caso.

Skills

Custom Tools