OpenCode-Benutzerdefinierte Befehle

Benutzerdefinierte Befehle ermöglichen es, häufig verwendete Prompts in einen kurzen Befehl zu fassen. In der TUI,/command namekannst du ihn mit einem Tastendruck ausführen, wodurch die wiederholte Eingabe desselben Prompts vermieden wird.

Zum Beispiel lässt sich der komplexe Prompt "Tests ausführen und Fehlerursachen analysieren" als/testJedes Mal musst du nur zwei Zeichen eingeben, um ihn auszulösen.

Benutzerdefinierte Befehle sind/init、/undo、/redo、/share、/helpErweiterungen über integrierte Befehle hinaus usw.

Wenn dein benutzerdefinierter Befehl denselben Namen wie ein integrierter Befehl hat,überschreibt der benutzerdefinierte Befehl den integrierten Befehl.Bitte vermeide die Verwendung voninit、undo、redo、share、helpals Namen für einen benutzerdefinierten Befehl, es sei denn, du musst das integrierte Verhalten ausdrücklich ersetzen.

Zwei Definitionsmethoden

Benutzerdefinierte Befehle unterstützen zwei Definitionsmethoden mit exakt derselben Wirkung. Du kannst sie nach deinen persönlichen Vorlieben auswählen:

Methode 1: JSON-Konfiguration

Inopencode.jsonvoncommandDefiniere es im Feld; der Schlüsselname ist der Befehlsname:

Nach Abschluss der Konfiguration im TUI-Eingabefeld eingeben/testund Enter drücken, um den Befehl auszuführen.

Methode 2: Markdown-Dateien

Incommands/Erstellen Sie im Verzeichnis.mdeine Datei, um den Befehl zu definieren.Der Dateiname ist der Befehlsname.Der Dateiinhalt ist in zwei Teile unterteilt:

• Frontmatter（---der von --- umschlossene YAML-Abschnitt): definiert die Attribute des Befehls
• Body(Inhalt unterhalb des Frontmatter): wird zur Prompt-Vorlage, die an das LLM gesendet wird

Markdown-Dateien unterstützen zwei Speicherorte:

• Projektebene:.opencode/commands/命令名.md(nur für das aktuelle Projekt gültig)
• Global:~/.config/opencode/commands/命令名.md(für alle Projekte gültig)

<!-- 文件路径：.opencode/commands/test.md -->
---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

Der Dateiname isttest.md, daher lautet der Befehlsnametest, und in der TUI wird er über/test.

Prompt-Template-Syntax

Der Prompt des Befehls (templateFeld oder Markdown-Body) unterstützt die folgende spezielle Syntax, sodass der Prompt dynamisch auf Argumente reagieren, Befehlsausgabe in Echtzeit einfügen oder auf Dateiinhalte verweisen kann.

1. Übergeben von Argumenten ($ARGUMENTS)

Verwenden Sie die$ARGUMENTSPlatzhalter zum Empfangen der beim Aufruf des Befehls übergebenen Argumente, der als ganze Zeichenkette eingefügt wird:

<!-- 文件路径：.opencode/commands/component.md -->
---
description: Create a new React component
---

Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.

Beim Aufruf die Argumente nach dem Befehlsnamen anhängen:

/component Button

$ARGUMENTSwird ersetzt durchButtonDer tatsächlich ausgeführte Prompt wird zu:

Create a new React component named Button with TypeScript support.
Include proper typing and basic structure.

2. Positionsparameter ($1, $2, $3...)

Wenn Sie mehrere unabhängige Argumente übergeben müssen, können Sie Positionsparameter verwenden$1、$2、$3um jedes Argument separat zu referenzieren, getrennt durch Leerzeichen; Argumente, die Leerzeichen enthalten, in Anführungszeichen setzen:

<!-- 文件路径：.opencode/commands/create-file.md -->
---
description: Create a new file with content
---

Create a file named $1 in the directory $2
with the following content: $3

Aufrufbeispiel (Argumente, die Leerzeichen enthalten, werden in Anführungszeichen gesetzt):

/create-file config.json src "{ \"key\": \"value\" }"

Ersetzungsergebnisse für jeden Platzhalter:

3. Einfügen der Shell-Befehlsausgabe (!`command`)

Mit der!`shell命令`Syntax können Sie beim Ausführen des Befehls einen Shell-Befehl ausführen und seine Ausgabe direkt in den Prompt einfügen. Der Shell-Befehl läuft imProjektstammverzeichnis. Dies ist sehr nützlich, wenn Sie möchten, dass das LLM Echtzeitdaten analysiert (z. B. Testergebnisse, Git-Logs usw.):

<!-- 文件路径：.opencode/commands/analyze-coverage.md -->
---
description: Analyze test coverage
---

Here are the current test results:
!`npm test`

Based on these results, suggest improvements to increase coverage.

<!-- 文件路径：.opencode/commands/review-changes.md -->
---
description: Review recent git changes
---

Recent git commits:
!`git log --oneline -10`

Review these changes and suggest any improvements or potential issues.

Wenn der Befehl ausgeführt wird,!`git log --oneline -10`es wird durch die tatsächliche Ausgabe von git log ersetzt und dann zusammen mit dem Prompt an das LLM gesendet.

4. Referenzieren von Dateiinhalten (@file_path)

Mit der@file pathMit der Syntax kann der Inhalt der angegebenen Datei automatisch in den Prompt eingefügt werden, ohne manuelles Kopieren und Einfügen:

<!-- 文件路径：.opencode/commands/review-component.md -->
---
description: Review a component for performance issues
---

Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.

Wenn der Befehl ausgeführt wird,@src/components/Button.tsxes wird durch den vollständigen Inhalt der Datei ersetzt, sodass das LLM den Dateicode direkt analysieren kann.

Detaillierte Konfigurationsoptionen

Im Folgenden sind alle von benutzerdefinierten Befehlen unterstützten Konfigurationsoptionen aufgeführt. In Markdown-Dateien schreiben Sie sie in das Frontmatter; in der JSON-Konfiguration schreiben Sie sie unter das command-Objekt:

Die Beziehung zwischen agent und subtask

agentundsubtaskSie steuern gemeinsam, wie der Befehl ausgeführt wird:

• ifagentWenn der angegebene Agent ein Subagent ist (Modus ist subagent), löst der Befehleinen Subagenten-Aufruf durchaus und wird in einem unabhängigen Kontext ausgeführt, ohne die Hauptsitzung zu beeinträchtigen.
• Wenn Sie dieses Verhalten nicht wünschen,subtaskauffalsezur Ausführung in der Hauptsitzung.
• Wenn Siesubtaskauftrue, unabhängig von denmodeEinstellungen des Agenten, wird der Befehl immer als Subagent ausgeführt, geeignet für Szenarien, die einen vollständigen Kontext erfordern.

Umfassende Anwendungsbeispiele

Beispiel 1: Befehl zur Codegenerierung mit mehreren Parametern

<!-- 文件路径：.opencode/commands/gen-api.md -->
---
description: Generate a REST API endpoint
agent: build
---

Generate a $1 REST API endpoint for the resource "$2".
Place the file in the $3 directory.
Include input validation, error handling, and JSDoc comments.

<!-- 调用示例：/gen-api POST user src/api -->
<!-- $1 = POST，$2 = user，$3 = src/api -->

Beispiel 2: Code-Review-Befehl, der Shell-Ausgabe und Dateireferenzen kombiniert

<!-- 文件路径：.opencode/commands/pr-review.md -->
---
description: Review changes in current branch against main
agent: plan
subtask: true
---

Please review the following changes for code quality, potential bugs, and security issues.

## Recent commits
!`git log main..HEAD --oneline`

## Changed files
!`git diff main --name-only`

## Diff content
!`git diff main`

## Project coding guidelines
@.opencode/AGENTS.md

Provide structured feedback with severity levels (critical / warning / suggestion).

Beispiel 3: Geplanter Daten-Snapshot-Befehl (JSON-Methode)

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "healthcheck": {
      "description": "Check project health status",
      "template": "Analyze the project health based on the following data:\n\nDependency vulnerabilities:\n!`npm audit --json`\n\nOutdated packages:\n!`npm outdated`\n\nTest results:\n!`npm test -- --passWithNoTests 2>&1 | tail -20`\n\nSummarize the issues by severity and suggest a prioritized action plan.",
      "model": "anthropic/claude-3-5-sonnet-20241022",
      "subtask": true
    }
  }
}