Brugerdefinerede værktøjer

Opret værktøjer, som LLM kan kalde opencode ind.

Brugerdefinerede værktøjer er funktioner, du opretter, som LLM kan kalde under samtaler. De arbejder sammen med opencodes built-in tools som read, write og bash.

Oprettelse af et værktøj

Værktøjer er defineret som TypeScript- eller JavaScript-filer. Værktøjsdefinitionen kan dog kalde scripts skrevet på alle sprog - TypeScript eller JavaScript bruges kun til selve værktøjsdefinitionen.

Placering

De kan definere:

Lokalt ved at placere dem i biblioteket .opencode/tools/ i dit projekt.
Eller globalt ved at placere dem i ~/.config/opencode/tools/.

Struktur

Den nemmeste måde at oprette værktøjer på er at bruge tool()-hjælperen, som giver typesikkerhed 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 bliver værktøjsnavnet. Ovenstående opretter et database værktøj.

Flere værktøjer pr. fil

Du kan også eksportere flere værktøjer fra en enkelt fil. Hver eksport bliver et separat værktøj 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 skaber værktøjer: math_add og math_multiply.

Argumenter

Du kan bruge tool.schema, som kun er Zod, til at definere argumenttyper.

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

Du kan også importere Zod direkte og returnere et almindeligt 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

Værktøjer modtager kontekst om den aktuelle session:

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

Brug context.directory til sessionens arbejdsmappe. Brug context.worktree til git-arbejdstræets rod.

Eksempler

Skriv et værktøj i Python

Du kan skrive dine værktøjer på et hvilket som helst sprog, du ønsker. Her er et eksempel, der tilføjer til tal ved hjælp af Python.

Først skal du oprette værktøjet som et Python-script:

import sys

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

Opret derefter værktøjsdefinitionen, der kalder 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 bruger vi Bun.$-værktøjet til at køre Python-scriptet.