Egendefinerte verktøy - Opencode

Egendefinerte verktøy er funksjoner du oppretter som LLM kan kalle under samtaler. De fungerer sammen med OpenCode sine innebygde verktøy som read, write og bash.

Opprette et verktøy

Verktøy er definert som TypeScript- eller JavaScript-filer. Verktøydefinisjonen kan imidlertid påkalle skript skrevet på alle språk - TypeScript eller JavaScript brukes bare for selve verktøydefinisjonen.

Plassering

De kan defineres:

Lokalt ved å plassere dem i .opencode/tools/-katalogen til prosjektet ditt.
Eller globalt, ved å plassere dem i ~/.config/opencode/tools/.

Struktur

Den enkleste måten å lage verktøy på er å bruke tool()-hjelperen som gir typesikkerhet og validering.

import { tool } from "@opencode-ai/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}`
  },
})

filnavnet blir verktøynavnet. Ovennevnte oppretter et database-verktøy.

Flere verktøy per fil

Du kan også eksportere flere verktøy fra en enkelt fil. Hver eksport blir et separat verktøy med navnet <filename>_<exportname>:

import { tool } from "@opencode-ai/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
  },
})

Dette lager to verktøy: math_add og math_multiply.

Navnekollisjoner med innebygde verktøy

Egendefinerte verktøy er nøklet etter verktøynavn. Hvis et egendefinert verktøy bruker samme navn som et innebygd verktøy, vil det egendefinerte verktøyet ha forrang.

For eksempel erstatter denne filen det innebygde bash-verktøyet:

import { tool } from "@opencode-ai/plugin"

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

:::note Foretrekk unike navn med mindre du med vilje ønsker å erstatte et innebygd verktøy. Hvis du vil deaktivere et innebygd verktøy, men ikke overstyre det, bruk tillatelser. :::

Argumenter

Du kan bruke tool.schema, som bare er Zod, for å definere argumenttyper.

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

Du kan også importere Zod direkte og returnere et vanlig objekt:

import { z } from "zod"

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

Kontekst

Verktøy mottar kontekst om gjeldende økt:

import { tool } from "@opencode-ai/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}`
  },
})

Bruk context.directory for øktens arbeidskatalog. Bruk context.worktree for git-arbeidstreet.

Eksempler

Skrive et verktøy i Python

Du kan skrive verktøyene dine på hvilket som helst språk du vil. Her er et eksempel som legger til to tall ved hjelp av Python.

Først lager du verktøyet som et Python-skript:

python

import sys

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

Lag deretter verktøydefinisjonen som påkaller den:

import { tool } from "@opencode-ai/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, ".opencode/tools/add.py")
    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
    return result.trim()
  },
})

Her bruker vi Bun.$-verktøyet for å kjøre Python-skriptet.