Benutzerdefinierte OpenCode-Tools

Benutzerdefinierte Tools ermöglichen es Ihnen, die Fähigkeiten von OpenCode zu erweitern, sodass das LLM Funktionen aufrufen kann, die Sie während Gesprächen definieren, und dadurch komplexe Vorgänge wie Datenbankabfragen, Skriptausführung und API-Aufrufe implementiert werden.

Diese Tools arbeiten mit integrierten Tools (wie z. B.read、write、bash)

Benutzerdefinierte Tools sind die zentrale Erweiterungsfunktion von OpenCode und befähigen das LLM, nicht nur Code zu generieren, sondern auch Aufgaben auszuführen.

Durch den richtigen Entwurf von Tools können Sie Folgendes erstellen:

  • Automatisierte Entwicklungspipelines
  • Intelligente Code-Assistenten
  • AI-Ops-Systeme
  • Unternehmensinterne KI-Tool-Plattformen

1. Was sind benutzerdefinierte Tools?

Ein benutzerdefiniertes Tool ist im Wesentlichen eine Funktionsschnittstelle, die das LLM während der Ausführung proaktiv aufrufen kann, um das Ergebnis zu erhalten.

Typische Anwendungsfälle:

  • Datenbanken abfragen (SQL / NoSQL)
  • Interne APIs aufrufen
  • Skripte ausführen (Python / Shell)
  • Systemstatus oder Umgebungsinformationen lesen
  • Komplexe Geschäftslogik kapseln

Man kann es sich so vorstellen:Ein Plugin-Mechanismus, der der KI Ausführungsfähigkeiten verleiht。

2. Speicherort für Tools

OpenCode lädt Tools automatisch aus den folgenden Verzeichnissen:

  • Projektebene:.opencode/tools/
  • Globale Ebene:~/.config/opencode/tools/

Der Dateiname ist der Tool-Name (dies ist entscheidend).

3. Grundlegende Tool-Definition (Empfohlen)

Verwenden Sietool()Hilfsfunktionen bieten Typsicherheit und Parametervalidierung.

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) {
    return `Executed query: ${args.query}`
  },
})

Erklärung:

  • description: Tool-Beschreibung, wird vom LLM verwendet, um zu bestimmen, ob aufgerufen werden soll
  • args: Parameterdefinition (basierend auf Zod)
  • execute: Tatsächliche Ausführungslogik

4. Mehrere Tools in einer einzigen Datei

Eine einzelne Datei kann mehrere Tools exportieren, und jedes Tool wird automatisch benannt als:

<文件名>_<导出名>

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

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

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

Die endgültig generierten Tools:

  • math_add
  • math_multiply

5. Konflikte mit integrierten Tools

Wenn der Name Ihres Tools mit einem integrierten Tool identisch ist, wird esdas integrierte Tool überschreiben。 

// 覆盖内置 bash 工具
export default tool({
  description: "Restricted bash wrapper",
  args: {
    command: tool.schema.string(),
  },
  async execute(args) {
    return `blocked: ${args.command}`
  },
})

Empfehlung:

  • Namenskonflikte vermeiden
  • Wenn Sie nur Funktionen einschränken möchten, verwenden Sie vorzugsweisepermissionconfiguration

6. Parameterdefinition (Zod)

Parameter werden mit Zod Schema definiert, wodurch Typvalidierung und Beschreibungen unterstützt werden:

args: {
  query: tool.schema.string().describe("SQL query"),
  limit: tool.schema.number().optional(),
}

Sie können auch direkt Zod verwenden:

import { z } from "zod"

export default {
  description: "Example tool",
  args: {
    name: z.string(),
  },
  async execute(args) {
    return `Hello ${args.name}`
  },
}

7. Kontext

Wenn ein Tool ausgeführt wird, werden Kontextinformationen automatisch eingefügt:

export default tool({
  description: "Get project info",
  args: {},
  async execute(args, context) {
    const { agent, sessionID, directory, worktree } = context
    return `Agent: ${agent}, Dir: ${directory}`
  },
})<

Verfügbare Felder:

  • agent: Aktueller Agent
  • sessionID: Session-ID
  • messageID: Message-ID
  • directory: Aktuelles Arbeitsverzeichnis
  • worktree: Git-Stammverzeichnis

8. Aufruf externer Sprachen (Python-Beispiel)

Sie können die Tool-Logik in jeder Sprache implementieren, z. B. in Python.

1. Python-Skript

# .opencode/tools/add.py
import sys

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

print(a + b)

2. Tool-Kapselung

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

export default tool({
  description: "Add two numbers using Python",
  args: {
    a: tool.schema.number(),
    b: tool.schema.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()
  },
})

Dieser Ansatz eignet sich für:

  • Bestehende Python-Toolchains
  • Aufrufen von Datenanalyse-/KI-Modellen
  • Ausführen komplexer Berechnungsaufgaben

9. Bewährte Vorgehensweisen

  • Werkzeugbeschreibungen sollten klar sein, damit das LLM die richtige Wahl treffen kann
  • Parameter so einfach und klar wie möglich gestalten
  • Seiteneffekte vermeiden (außer wenn eindeutig erforderlich)
  • Riskante Operationen vorzugsweise über Berechtigungen steuern
  • Werkzeuge sollten sich auf eine einzige Verantwortlichkeit konzentrieren
Weitere Erweiterungen