command-creator

命令创建器

在 OpenCode 中为重复性任务创建自定义斜杠命令。

<core_approach>

创建命令是对话式的，而非事务式的。

• MUST NOT 臆测用户的需求——应主动询问
• SHOULD 从简单开始，仅在需要时增加复杂度
• MUST 展示草稿，并根据反馈迭代

</core_approach>

<question_tool>

批量提问： 使用 question 工具一次提出 2 个或更多相关问题。单个问题 → 直接用纯文本提问。

语法： header ≤12 个字符，label 为 1-5 个词，默认选项后添加“(Recommended)”。

何时提问：需求含糊（“创建一个命令”），或存在多种实现方式时。

</question_tool>

命令位置

范围	路径
项目	.opencode/command/<name>.md
全局	~/.config/opencode/command/<name>.md

模板占位符（重要）

• 单次插入： 每个占位符（$ARGUMENTS、$1、@filename 等）在命令正文中只能插入一次。
• 专用区块： 使用专用 XML 区块存放用户输入和文件内容，使目标和指令保持清晰。
• 优先选择： 除非确有必要，否则优先使用单个参数（$ARGUMENTS），而非复杂的位置参数。

错误：“执行 $ARGUMENTS，然后检查 $ARGUMENTS 是否存在错误。”

正确：

<user_guidelines>
$ARGUMENTS
</user_guidelines>

<context>
@src/schema.ts
</context>

<objective>
Analyze findings based on user guidelines and the provided schema.
</objective>

占位符	说明	示例
$ARGUMENTS	传入的所有参数	/cmd foo bar → "foo bar"
$1、$2、$3	位置参数	/cmd foo bar → $1="foo"，$2="bar"
!command	Shell 输出注入	!ls -F
@filename	包含文件内容	@src/index.ts

术语规范

• 直接称呼： 必须使用“you”（指执行命令的 Agent），而不是“the agent”或“opencode”。

命令文件格式

---
description: 3-word command summary
agent: build # Optional: build, plan, or custom agent
model: provider/model-id # Optional: override model
subtask: true # Optional: run as subagent
---

<summary>
Line 1: You MUST [purpose].
Line 2: You SHOULD [inputs].
Line 3: You MUST [outcome].
</summary>

<user_guidelines>
$ARGUMENTS
</user_guidelines>

Template body goes here.

Frontmatter 选项

字段	用途	必需
description	显示在命令列表中	建议
agent	路由到指定的 Agent	否
model	覆盖模型	否
subtask	强制调用子 Agent	否

概念边界（重要）

• 命令面向用户： 命令是高级快捷方式，供人类触发带有特定上下文的 Agent。
• Agent 不能使用命令： Agent 没有终端界面来“输入”命令。它们执行的是命令提供的模板正文。
• 单向流程： 用户 -> 命令 -> Agent。
• 绝不可告诉 Agent 主动使用命令——它们确实无法做到。
• 如果逻辑需要共享，应将其放入 Skill（脚本/指令），而不是命令中。

模板中的 Shell 命令

使用 !command`` 语法将 bash 输出注入提示词。Shell 执行由感叹号触发，后跟用反引号括起的命令：

Review recent changes:

!`git log --oneline -10`

Suggest improvements.

文件引用

使用 @ 包含文件内容：

Given the schema in @prisma/schema.prisma, generate a migration for $ARGUMENTS.

阶段 1：了解任务

1. “你想自动化什么任务？”

   • 了解重复执行的提示词/工作流
   • 示例：“运行测试”“审查此文件”“创建一个组件”

2. “你能展示一下平时会如何提出这个请求吗？”

   • 获取用户实际会输入的提示词
   • 这将成为模板正文

阶段 2：输入与路由

3. “是否需要参数？”

   • 如果用户提到“这个文件”“某个名称”或“这个函数” → 是
   • 说明：/command foo bar → $ARGUMENTS = "foo bar"，$1 = "foo"，$2 = "bar"

4. “需要进行修改，还是只做分析？”

   • 修改 → 默认 Agent（build）
   • 仅分析 → 设置 agent: plan

5. “是否应作为后台子任务运行？”

   • 长时间运行或并行工作 → 设置 subtask: true
   • 交互式或快速任务 → 不设置

6. “仅用于当前项目，还是随处可用？”

   • 当前项目 → .opencode/command/
   • 全局 → ~/.config/opencode/command/

阶段 3：审阅与优化

7. 展示命令草稿并征求反馈
   • “这是我创建的内容。你想调整什么吗？”
   • 持续迭代，直到用户满意

**灵活应对：**如果用户一开始就提供了大量信息，请灵活调整——绝不能僵化地逐一提问。

/test - 运行并修复测试

---
description: Run tests and fix failures
---

<summary>
You MUST run the full test suite.
You SHOULD identify and fix failures.
You MUST re-verify fixes.
</summary>

<objective>
You MUST run the full test suite, find the root cause of any failures, and fix the issue.
</objective>

1. Show the failing test
2. Identify the root cause
3. Fix the issue
4. Re-run to verify

/review - 代码审查（只读）

---
description: Review code for issues
agent: plan
---

<summary>
You MUST review $ARGUMENTS for issues.
You SHOULD check for bugs, security, and performance.
You MUST provide actionable feedback.
</summary>

<objective>
You MUST review $ARGUMENTS for bugs, security, and performance issues and provide actionable feedback without making changes.
</objective>

- Bugs and edge cases
- Security issues
- Performance problems

/commit - 使用前缀智能提交

---
description: Stage and commit with conventional prefix
---

<summary>
You MUST analyze changes and stage files.
You SHOULD choose a conventional commit prefix.
You MUST commit with a concise message.
</summary>

<context>
!`git status`
!`git diff`
</context>

<objective>
You MUST analyze changes, stage relevant files, and commit with a concise message.
</objective>

1. Analyze all changes
2. Choose appropriate prefix: docs:, feat:, fix:, refactor:, test:, ci:
3. Write concise commit message (imperative mood)
4. Stage relevant files and commit

/spellcheck - 检查拼写

---
description: Check spelling in markdown files
subtask: true
---

<summary>
You MUST find unstaged markdown files.
You SHOULD check them for spelling errors.
You MUST report any found errors.
</summary>

Check spelling in all unstaged markdown files:

<context>
!`git diff --name-only | grep -E '\.md$'`
</context>

<objective>
You MUST check for and report any spelling errors found in unstaged markdown files.
</objective>

/issues - 搜索 GitHub Issues

---
description: Search GitHub issues
model: anthropic/claude-3-5-haiku-20241022
subtask: true
---

<summary>
You MUST search GitHub issues for $ARGUMENTS.
You SHOULD limit results to the top 10.
You MUST summarize the relevant issues.
</summary>

Search GitHub issues matching: $ARGUMENTS

<context>
!`gh issue list --search "$ARGUMENTS" --limit 10`
</context>

<objective>
You MUST summarize the top 10 relevant GitHub issues found for $ARGUMENTS.
</objective>

/component - 创建组件

---
description: Create a new React component
---

<summary>
You MUST create a React component named $1.
You SHOULD include TypeScript props and basic styling.
You MUST provide a unit test file.
</summary>

Create a React component named $1 in $2 with:

<objective>
You MUST create a React component with TypeScript props and basic styling, and provide a corresponding unit test file.
</objective>

- TypeScript props interface
- Basic styling
- Unit test file

用法：/component UserProfile src/components

/migrate - 数据库迁移

---
description: Generate database migration
---

<summary>
You MUST read the Prisma schema.
You SHOULD generate a migration for $ARGUMENTS.
You MUST ensure the migration matches the schema.
</summary>

Given the schema in @prisma/schema.prisma:

<context>
@prisma/schema.prisma
</context>

<objective>
You MUST generate a Prisma migration for $ARGUMENTS that matches the provided schema.
</objective>

<quality_checklist>

交付前：

• 询问要自动化的任务
• 获取用户通常如何提示该任务的示例
• 确定是否需要参数（$ARGUMENTS 还是 $1、$2）
• 设置合适的 Agent（只读任务使用 plan）
• 考虑是否为长时间运行的工作设置子任务
• 选择项目范围还是全局范围
• 展示草稿并征求反馈

</quality_checklist>

<best_practices>

应做	不应做
保持模板专注	将多个任务塞进一个模板
使用 $1、$2 表示结构化参数	处理多个参数时只依赖 $ARGUMENTS
使用 !cmd 收集上下文	将动态值硬编码
使用 @file 引用配置/架构文件	复制粘贴文件内容
只读任务设置 agent: plan	忘记为审查任务设置 Agent
并行工作设置 subtask: true	无谓地阻塞主会话

</best_practices>