Skip to content

Prompt 模板 ​

创建你的第一个模板 ​

提示词模板保存你反复使用的指令,并将其暴露为斜杠命令。可以用它来做统一的审查清单、发布摘要、测试计划,或任何其他不需要自定义程序逻辑的任务。

在你想要使用该命令的项目中创建 .omp/prompts/review-change.md:

---
description: Review one area of this project for correctness
---

Review the code related to $1.

Focus on: $@[2:].

Report concrete findings first, with file and line references. Then list any
remaining risks or missing tests. Do not change files.

在该项目中启动一个新的 omp 会话,然后输入:

/review-change authentication "error handling and tests"

文件名创建了 /review-change 命令。omp 会把 $1 展开为 authentication,把 $@[2:] 展开为 error handling and tests,并把生成的 Markdown 作为你的消息发送。description 会显示在 / 自动补全中该命令的旁边。

与项目共享的提示词放在 .omp/prompts/。若希望命令在每个项目中都可用,则把同样的 Markdown 文件保存到 ~/.omp/agent/prompts/ 下。

传递参数 ​

参数跟在命令名之后。空格和制表符用于分隔参数;匹配的单引号或双引号会把文本连在一起,且引号字符会被移除。

/review-change payments "retry behavior" tests
语法本例中的值
$1、$2、…payments、retry behavior、…
$@ 或 $ARGUMENTSpayments retry behavior tests
$@[2] 或 $@[2:]从第二个起的所有参数:retry behavior tests
$@[2:1]从第二个起取一个参数:retry behavior

索引从 1 开始。缺失的位置参数、超出范围的切片或非正数的切片索引都会展开为空字符串。

参数解析器没有反斜杠转义语法。如果参数包含空格,请改用另一种引号样式把它包起来,而不要试图转义外层引号。空的带引号参数会被丢弃。

如果模板没有任何参数占位符,omp 也不会丢弃你提供的文本。它会在提示词之后加一个空行,然后把拼接后的参数追加到末尾:

Summarize the requested part of this project.

调用 /summarize src/auth 时,会先发送模板,再发送 src/auth。

使用 Handlebars 插值 ​

在替换完 $… 占位符后,omp 会把结果作为 Handlebars 模板渲染。最常用的取值有:

语法含义
{{arg 1}}解析出的第一个参数;arg 从 1 开始
{{arguments}} 或 {{ARGUMENTS}}所有解析出的参数,以空格连接
{{args}}解析出的参数数组,在块和辅助函数中很有用
{{default (arg 1) "current branch"}}第一个参数缺失时的回退值
{{#if args}}…{{else}}…{{/if}}根据是否提供了参数来决定的条件内容

例如:

---
description: Draft a test plan for a feature
---

Draft a test plan for {{default (arg 1) "the current change"}}.
{{#if args}}
Additional context: {{arguments}}
{{/if}}

Shell 风格的替换先进行,Handlebars 渲染后进行。包含 $1、$@ 或 $ARGUMENTS 的参数值不会被递归替换。使用任一种行内参数占位符样式的模板,也不会再接收自动追加的参数后缀。

对于普通的可复用提示词,优先使用 $1 和 $@ 形式:它们更简短,也让调用更容易理解。只有当你需要默认值或条件区块时,才使用 Handlebars。

添加描述 ​

在 omp 提示词模板的 YAML frontmatter 中,只有 description 具有特殊含义:

---
description: Explain a failing test and propose the smallest fix
---

把 frontmatter 放在文件开头。如果没有 description,omp 在自动补全中会使用正文的第一条非空行(截断到 60 个字符)。命令名始终来自 Markdown 文件名;frontmatter 中的 name 字段不会重命名它。

发现与命名 ​

在会话启动时,omp 会递归发现以下位置的 Markdown 文件:

范围目录自动补全来源标签
用户~/.omp/agent/prompts/**/*.md(user) 或 (user:subdirectory)
项目<working-directory>/.omp/prompts/**/*.md(project) 或 (project:subdirectory)

只有最终的文件名会成为命令名。.omp/prompts/frontend/review.md 和 .omp/prompts/backend/review.md 都会定义 /review,而不是带命名空间的命令。即使你按子目录组织文件,也要给每个模板一个独一无二的文件名。

提示词模板是 Markdown 提示词,不是可执行的命令模块。如果某个命令需要运行自定义的程序逻辑或显示自己的 UI,请改用扩展来实现。

优先级 ​

omp 先加载用户模板,再加载项目模板,并采用第一个匹配的名字。因此,~/.omp/agent/prompts/review.md 会胜过 .omp/prompts/review.md。这与许多「项目覆盖用户」的配置系统不同,所以使用独一无二的名字是最稳妥的选择。

其他类型的斜杠命令会在提示词模板之前解析。同名的内置命令、扩展命令、自定义命令、技能命令或基于文件的斜杠命令会胜出;冲突的提示词模板会从自动补全中被省略。

编辑后重新加载 ​

提示词模板在会话开始时才会被读取。omp 不会监听这些文件,/reload-plugins 也不会重新加载它们。创建、重命名或编辑模板之后,请退出,并在目标工作目录中启动一个新的 omp 会话。

故障排查 ​

命令没有出现在自动补全中 ​

  • 确认文件以 .md 结尾,并且位于当前工作目录的 .omp/prompts/ 中,或你的用户级 ~/.omp/agent/prompts/ 中。
  • 修改文件后启动一个新的会话。
  • 检查是否存在另一个同名的模板。用户模板胜过项目模板。
  • 尝试一个更有辨识度的文件名,以防某个内置、技能、扩展、自定义或基于文件的命令已经占用了该名字。
  • 检查会话日志中是否有提示词模板相关的警告。无效的 YAML frontmatter 或无法读取的文件都可能阻止该模板加载。

参数意外展开 ​

  • 对包含空格的参数加引号:/review-change auth "error handling"。
  • 不要依赖带引号参数内的反斜杠转义;它们会被按字面处理,而不是作为转义机制。
  • 请记住,$@ 包含所有参数,包括 $1。只想取剩余参数时,请使用 $@[2:]。
  • 如果需要控制参数出现的位置,请添加显式占位符。没有占位符时,omp 会把它们追加在模板正文之后。

项目模板没有覆盖我的用户模板 ​

这是当前的优先级规则:用户模板先加载。重命名其中一个文件,或删除用户级的重复模板,然后启动一个新的会话。

基于 oh-my-pi 上游文档整理的非官方中文文档。