Dropstone Docs

Strumenti personalizzati

Crea strumenti che l'LLM può chiamare in dropstone.

Gli strumenti personalizzati sono funzioni che crei e che l'LLM può chiamare durante le conversazioni. Funzionano insieme agli strumenti integrati di Dropstone come read, write e bash.

Creazione di uno strumento

Gli strumenti sono definiti come file TypeScript o JavaScript. La definizione dello strumento stesso è TS/JS, ma il lavoro che svolge può essere implementato in qualsiasi linguaggio: script shell, Python, Go, qualsiasi cosa tu possa eseguire dagli helper shell di Bun.

Posizione

Possono essere definiti:

  • Localmente posizionandoli nella directory .dropstone/tools/ del tuo progetto.
  • O globalmente, posizionandoli in ~/.config/dropstone/tools/.

Struttura

Il modo più semplice per creare strumenti è utilizzare l'helper tool() che fornisce type-safety e validazione.

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

export default tool({
  description: "Query the project database",
  args: {
    query: tool.schema.string().describe("SQL query to execute"),
  },
  async execute(args) {
    // Your database logic here
    return `Executed query: ${args.query}`
  },
})

Il nome del file diventa il nome dello strumento. Il codice precedente crea uno strumento database.

Più strumenti per file

Puoi anche esportare più strumenti da un singolo file. Ogni esportazione diventa uno strumento separato con il nome <filename>_<exportname>:

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

export const add = tool({
  description: "Add two numbers",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args) {
    return args.a + args.b
  },
})

export const multiply = tool({
  description: "Multiply two numbers",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args) {
    return args.a * args.b
  },
})

Questo crea due strumenti: math_add e math_multiply.

Collisioni di nomi con strumenti integrati

Gli strumenti personalizzati sono identificati dal nome dello strumento. Se uno strumento personalizzato utilizza lo stesso nome di uno strumento integrato, lo strumento personalizzato ha la precedenza.

Ad esempio, questo file sostituisce lo strumento integrato bash:

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

export default tool({
  description: "Restricted bash wrapper",
  args: {
    command: tool.schema.string(),
  },
  async execute(args) {
    return `blocked: ${args.command}`
  },
})

Note:

Preferisci nomi univoci a meno che tu non voglia intenzionalmente sostituire uno strumento integrato. Se vuoi disabilitare uno strumento integrato ma non sostituirlo, utilizza permissions.

Argomenti

Puoi utilizzare tool.schema, che è semplicemente Zod, per definire i tipi di argomenti.

args: {
  query: tool.schema.string().describe("SQL query to execute")
}

Puoi anche importare Zod direttamente e restituire un oggetto semplice:

import { z } from "zod"

export default {
  description: "Tool description",
  args: {
    param: z.string().describe("Parameter description"),
  },
  async execute(args, context) {
    // Tool implementation
    return "result"
  },
}

Contesto

Gli strumenti ricevono il contesto della sessione corrente:

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

export default tool({
  description: "Get project information",
  args: {},
  async execute(args, context) {
    // Access context information
    const { agent, sessionID, messageID, directory, worktree } = context
    return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}, Directory: ${directory}, Worktree: ${worktree}`
  },
})

Utilizza context.directory per la directory di lavoro della sessione. Utilizza context.worktree per la radice del worktree git.

Esempi

Scrivi uno strumento in Python

Puoi scrivere i tuoi strumenti in qualsiasi linguaggio desideri. Ecco un esempio che aggiunge due numeri utilizzando Python.

Per prima cosa, crea lo strumento come script Python:

import sys

a = int(sys.argv[1])
b = int(sys.argv[2])
print(a + b)

Quindi crea la definizione dello strumento che lo invoca:

import { tool } from "@blankline/dropstone-plugin"
import path from "path"

export default tool({
  description: "Add two numbers using Python",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args, context) {
    const script = path.join(context.worktree, ".dropstone/tools/add.py")
    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
    return result.trim()
  },
})

Qui stiamo utilizzando l'utilità Bun.$ per eseguire lo script Python.

Ctrl+I