Comandos personalizados de OpenCode

Los comandos personalizados te permiten encapsular los prompts de uso frecuente en un comando corto, que en la TUI se ejecuta mediante/nombre del comandouna sola tecla, evitando repetir la entrada del mismo prompt.

Por ejemplo, encapsular el prompt complejo "ejecutar pruebas y analizar las causas de los fallos" como/test, cada vez solo necesitas escribir dos caracteres para activarlo.

Los comandos personalizados son/init、/undo、/redo、/share、/helpuna extensión más allá de los comandos integrados, etc.

Si defines un comando personalizado con el mismo nombre que un comando integrado,el comando personalizado sobrescribirá al comando integrado. Evita usarinit、undo、redo、share、helpcomo nombre de comando personalizado, a menos que realmente necesites reemplazar el comportamiento integrado.

Dos formas de definición

Los comandos personalizados admiten dos formas de definición, con exactamente el mismo efecto; puedes elegir según tus hábitos:

Forma 1: Configuración JSON

Enopencode.jsondecommandSe define en el campo; el nombre de la clave es el nombre del comando:

Una vez completada la configuración, escribe en el campo de entrada de la TUI/testy presiona Enter para ejecutar el comando.

Forma 2: Archivo Markdown

Encommands/Crea en el directorio.mdun archivo para definir el comando,el nombre del archivo es el nombre del comando, y el contenido del archivo se divide en dos partes:

• Frontmatter（---la parte YAML envuelta): define las propiedades del comando
• Cuerpo(contenido debajo del Frontmatter): se convierte en la plantilla de prompt enviada al LLM

Los archivos Markdown admiten dos ubicaciones de almacenamiento:

• A nivel de proyecto:.opencode/commands/命令名.md(solo válido para el proyecto actual)
• Global:~/.config/opencode/commands/命令名.md(válido para todos los proyectos)

<!-- 文件路径：.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.

El archivo se llamatest.md, por lo tanto el nombre del comando estest, en la TUI mediante/testse invoca.

Sintaxis de la plantilla de prompt

El prompt del comando (templatecampo o cuerpo del Markdown) admite la siguiente sintaxis especial, que permite que el prompt responda dinámicamente a los parámetros, inyecte la salida de comandos en tiempo real o haga referencia al contenido de archivos.

1. Parámetros de entrada ($ARGUMENTS)

Usa$ARGUMENTSel marcador de posición para recibir los parámetros pasados al invocar el comando, insertándolos en su conjunto como una cadena:

<!-- 文件路径：.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.

Al invocar, agrega los parámetros después del nombre del comando:

/component Button

$ARGUMENTSserá reemplazado porButton, y el prompt realmente ejecutado se convierte en:

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

2. Parámetros posicionales ($1, $2, $3...)

Cuando necesites pasar varios parámetros independientes, puedes usar los parámetros posicionales$1、$2、$3para referenciar cada parámetro por separado, separados por espacios; los parámetros que contengan espacios deben ir entre comillas:

<!-- 文件路径：.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

Ejemplo de invocación (los parámetros que contienen espacios van entre comillas):

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

Resultado del reemplazo de cada marcador de posición:

3. Inyección de salida de comandos Shell (!`command`)

Usa!`shell命令`la sintaxis permite ejecutar un comando Shell al ejecutar el comando e insertar su salida directamente en el prompt. El comando Shell se ejecuta en eldirectorio raíz del proyecto. Esto es muy útil cuando se necesita que el LLM analice datos en tiempo real (como resultados de pruebas, registros de git, etc.):

<!-- 文件路径：.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.

Al ejecutar el comando,!`git log --oneline -10`será reemplazado por la salida real del registro de git y luego se enviará al LLM junto con el prompt.

4. Referencia al contenido de un archivo (@ruta_del_archivo)

Usa@ruta del archivola sintaxis permite incluir automáticamente el contenido del archivo especificado en el prompt, sin necesidad de copiar y pegar manualmente:

<!-- 文件路径：.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.

Al ejecutar el comando,@src/components/Button.tsxserá reemplazado por el contenido completo del archivo, y el LLM puede analizar directamente el código del archivo.

Explicación detallada de las opciones de configuración

A continuación se muestran todas las opciones de configuración compatibles con los comandos personalizados. En los archivos Markdown se escriben en el frontmatter, y en la configuración JSON, dentro del objeto del comando:

Relación entre agent y subtask

agentysubtaskControlan conjuntamente la forma de ejecución del comando:

• siagentSi el agente especificado es un subagente (mode es subagent), el comandoactiva por defecto la invocación del subagente, se ejecuta en un contexto independiente y no afecta a la sesión principal
• Si no deseas este comportamiento, establecesubtaskenfalsepara forzar la ejecución en la sesión principal
• Si se establecesubtaskentrue, independientemente de lamodeconfiguración del agente, el comando siempre se ejecuta como subagente, adecuado para escenarios que requieren un aislamiento completo del contexto

Ejemplos de uso integral

Ejemplo 1: Comando de generación de código con múltiples parámetros

<!-- 文件路径：.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 -->

Ejemplo 2: Comando de revisión de código que combina la salida de Shell y la referencia a archivos

<!-- 文件路径：.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).

Ejemplo 3: Comando de instantánea de datos programada (forma JSON)

{
  "$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
    }
  }
}