Пользовательские команды OpenCode

Пользовательские команды позволяют инкапсулировать часто используемые запросы в короткую команду. В TUI,/command nameвы можете выполнить её одним нажатием клавиши, избегая повторного ввода одного и того же запроса.

Например, можно инкапсулировать сложный запрос "запусти тесты и проанализируй причины сбоев" как/testКаждый раз достаточно ввести два символа, чтобы вызвать её.

Пользовательские команды — это/init、/undo、/redo、/share、/helpрасширения помимо встроенных команд и т. д.

Если ваша пользовательская команда имеет то же имя, что и встроенная команда,пользовательская команда переопределит встроенную команду.Пожалуйста, избегайте использованияinit、undo、redo、share、helpв качестве имени пользовательской команды, если только вам явно не нужно заменить встроенное поведение.

Два способа определения

Пользовательские команды поддерживают два способа определения с абсолютно одинаковым результатом. Вы можете выбрать по своему усмотрению:

Метод 1: Конфигурация JSON

Вopencode.jsonизcommandОпределите его в поле; имя ключа — это имя команды:

После завершения настройки введите в поле ввода TUI/testи нажмите Enter, чтобы выполнить команду.

Способ 2: файлы Markdown

Вcommands/Создайте в каталоге.mdфайл для определения команды.Имя файла — это имя команды.Содержимое файла делится на две части:

• Frontmatter（---раздел YAML, заключённый в ---): определяет атрибуты команды
• Тело(содержимое ниже Frontmatter): становится шаблоном промпта, отправляемым в LLM

Файлы Markdown поддерживают два места хранения:

• Уровень проекта:.opencode/commands/命令名.md(действует только для текущего проекта)
• Глобально:~/.config/opencode/commands/命令名.md(действует для всех проектов)

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

Имя файла —test.md, поэтому имя команды —test, а в TUI она вызывается через/test.

Синтаксис шаблона промпта

Промпт команды (templateполе или тело Markdown) поддерживает следующий специальный синтаксис, позволяющий промпту динамически реагировать на аргументы, вставлять вывод команды в реальном времени или ссылаться на содержимое файлов.

1. Передача аргументов ($ARGUMENTS)

Используйте$ARGUMENTSплейсхолдер для приёма аргументов, переданных при вызове команды, вставляемых как единая строка:

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

При вызове добавьте аргументы после имени команды:

/component Button

$ARGUMENTSбудет заменён наButtonФактически выполняемый промпт становится:

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

2. Позиционные параметры ($1, $2, $3...)

Когда нужно передать несколько независимых аргументов, можно использовать позиционные параметры$1、$2、$3чтобы ссылаться на каждый аргумент отдельно, разделяя их пробелами; аргументы, содержащие пробелы, заключайте в кавычки:

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

Пример вызова (аргументы, содержащие пробелы, заключаются в кавычки):

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

Результаты замены для каждого заполнителя:

3. Внедрение вывода команды Shell (!`command`)

Используя!`shell命令`синтаксис, можно выполнить команду Shell при выполнении команды и вставить её вывод непосредственно в промпт. Команда Shell выполняется вкорневом каталоге проекта. Это очень полезно, когда вам нужно, чтобы LLM проанализировала данные в реальном времени (например, результаты тестов, логи git и т. д.):

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

При выполнении команды,!`git log --oneline -10`он будет заменён фактическим выводом git log, а затем отправлен в LLM вместе с промптом.

4. Ссылка на содержимое файла (@file_path)

Используя@file pathсинтаксис, содержимое указанного файла может быть автоматически включено в промпт без ручного копирования и вставки:

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

При выполнении команды,@src/components/Button.tsxон будет заменён полным содержимым файла, что позволит LLM напрямую анализировать код файла.

Подробные параметры конфигурации

Ниже приведены все параметры конфигурации, поддерживаемые пользовательскими командами. В файлах Markdown записывайте их во frontmatter; в конфигурации JSON записывайте их в объекте команды:

Связь между agent и subtask

agentиsubtaskОни совместно управляют тем, как выполняется команда:

• ifagentЕсли указанный agent — subagent (mode равен subagent), командапо умолчанию вызывает subagentи выполняется в независимом контексте, не влияя на основную сессию.
• Если вы не хотите такого поведения, установитеsubtaskвfalseчтобы принудительно выполнить в основной сессии.
• Если задатьsubtaskвtrue, независимо отmodeнастроек agent, команда всегда выполняется как subagent, подходит для сценариев, требующих полной изоляции контекста.

Комплексные примеры использования

Пример 1: Команда генерации кода с несколькими параметрами

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

Пример 2: Команда проверки кода, объединяющая вывод Shell и ссылки на файлы

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

Пример 3: Команда запланированного снимка данных (метод 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
    }
  }
}