.goat 脚本中的参数和变量

.goat 脚本可以使用运行时传递的参数、本地变量以及环境变量。

提供四种基本机制：

  • {{args}} — 传递给脚本的所有参数，
  • {{args.nazwa}} — 指定的命名参数，
  • {{zmienna}} — 由 set 定义的本地变量，
  • {{env.NAZWA}} — 环境变量。

参数和本地变量属于当前脚本。子脚本只有在显式传递给它们时才能获得这些值。

向脚本传递参数

脚本参数在分隔符 -- 后传递。

goat run:script --path=herd/translate.goat -- --force

在此示例中：

--path=herd/translate.goat

是 run:script 选项，而：

--force

是 translate.goat 脚本的参数。

可以传递任意数量的参数：

goat run:script --path=herd/example.goat -- --force --model=gpt-5 --verbose

如果没有分隔符 --，参数会被解释为 run:script 命令的选项。

所有参数 — {{args}}

{{args}} 会展开为传递给当前脚本的所有参数。

示例：

translate:sync --catalog="catalog.json" {{args}}

运行：

goat run:script --path=herd/translate.goat -- --force --model=gpt-5

在这种情况下等同于向 translate:sync 传递：

--force --model=gpt-5

参数顺序会被保留。

如果未向脚本传递任何参数，{{args}} 会展开为空列表。这不会导致错误。

因此，可以安全地编写：

translate:sync --catalog="catalog.json" {{args}}

并将同一脚本既用于不带额外选项的情况：

goat run:script --path=herd/translate.goat

也用于带额外选项的情况：

goat run:script --path=herd/translate.goat -- --force

{{args}} 作为独立令牌

{{args}} 只能作为独立令牌出现。

正确：

command {{args}}

错误：

command --options={{args}}

这是必要的，因为 {{args}} 可以展开为零个、一个或多个参数。

命名参数 — {{args.nazwa}}

可以通过以下方式引用特定参数：

{{args.nazwa}}

例如：

command {{args.model}}

支持以下形式的长参数：

--model
--model=gpt-5
--model gpt-5

保留原始形式

参数会以传入时的相同形式传递。

对于：

--model=gpt-5

表达式：

{{args.model}}

会传递：

--model=gpt-5

而对于：

--model gpt-5

则会传递两个令牌：

--model
gpt-5

多次出现

如果同一参数出现多次，其所有出现位置都会按原始顺序保留。

示例：

--tag=a --tag b --tag=c

引用：

{{args.tag}}

将传递全部三次出现的参数。

缺少参数

引用未传递的参数会以错误终止脚本执行。

示例：

command {{args.model}}

要求存在参数 --model。

如果参数是可选的，通常更方便通过以下方式传递所有可选参数：

{{args}}

独立令牌

与 {{args}} 一样，{{args.nazwa}} 也只能作为独立令牌出现。

正确：

command {{args.model}}

错误：

command --model={{args.model}}

本地变量 — set

可以通过以下方式定义本地变量：

set model = "gpt-5"

随后可以在后续命令中使用它：

command --model={{model}}

或作为单独的参数：

command {{model}}

变量从其声明位置起可用，并且仅属于当前脚本。

示例：

set catalog = "catalog.json"
set model = "gpt-5"

translate:sync --catalog={{catalog}} --model={{model}}

变量值不会再次拆分

局部变量的值始终被视为单个值。

示例：

set options = "--foo --bar"

command {{options}}

会传递一个参数：

--foo --bar

而不是两个独立的参数：

--foo
--bar

如果需要传递多个参数，请使用 {{args}}，或直接将它们写入命令中。

环境变量 — {{env.NAZWA}}

可以通过以下方式引用环境变量：

{{env.NAZWA}}

示例：

translate:sync --model={{env.GOAT_OPENAI_MODEL}}

也可以在 token 内部使用它们：

command --endpoint={{env.API_ENDPOINT}}

环境变量的值会被视为单个值，不会再次拆分为参数。

如果指定的环境变量不存在，脚本执行将以错误结束。

在引用值中使用变量

局部变量和环境变量也可以在引用值内部使用。

set model = "gpt-5"

translate:sync --model="{{model}}"

以及：

translate:sync --model="{{env.GOAT_OPENAI_MODEL}}"

还可以将它们与固定文本组合：

set locale = "pl"

command --catalog="catalog-{{locale}}.json"

参数和变量的作用域

每个 .goat 脚本都有自己的：

  • 参数，
  • 由 set 定义的局部变量。

它们不会自动在所启动的子脚本中可用。

示例：

run:script --path=herd/child.goat

child.goat 启动时不带父脚本的参数和局部变量。

环境变量仍可通过以下方式访问：

{{env.NAZWA}}

向子脚本传递参数

如果子脚本需要接收父脚本的参数，必须显式传递它们。

run:script --path=herd/child.goat -- {{args}}

这样，child.goat 将接收当前脚本的所有参数。

也可以只传递选定的参数：

run:script --path=herd/child.goat -- {{args.model}}

或者基于局部变量构建参数：

set model = "gpt-5"

run:script --path=herd/child.goat -- --model={{model}}

因此，每个脚本只会接收明确传递给它的数据。

可用的插值形式

语法含义可返回多个参数可作为 token 的一部分
{{args}}脚本的所有参数可以不可以
{{args.nazwa}}指定的命名参数可以不可以
{{zmienna}}本地变量不可以可以
{{env.NAZWA}}环境变量不可以可以

正确用法示例：

command {{args}}
command {{args.model}}
command {{model}}
command --model={{model}}
command --model={{env.GOAT_OPENAI_MODEL}}

不正确：

command prefix-{{args}}
command --model={{args.model}}

示例：向 translate:sync 传递选项

脚本可以将所有接收到的参数直接传递给 translate:sync：

translate:sync --catalog="catalog.json" {{args}}

标准运行方式：

goat run:script --path=herd/translate.goat

不会传递任何额外选项。

运行：

goat run:script --path=herd/translate.goat -- --force

会将 --force 传递给 translate:sync。

类似地：

goat run:script --path=herd/translate.goat -- --force --model=gpt-5

会按相同顺序传递两个选项。

完整脚本示例

set catalog = "catalog.json"
set defaultModel = "gpt-5"

translate:prepare --catalog={{catalog}}
translate:sync --catalog={{catalog}} --fallback-model={{defaultModel}} {{args}}

脚本可以不带额外参数运行：

goat run:script --path=herd/example.goat

或传递额外选项：

goat run:script --path=herd/example.goat -- --force --model=gpt-5

错误

脚本执行会在以下情况中断：

  • 使用了未定义的本地变量，
  • 指定的环境变量不存在，
  • {{args.nazwa}} 引用了未传递的参数，
  • {{args}} 或 {{args.nazwa}} 在另一个 token 内部使用。

错误消息会指出脚本中出现问题的位置，从而可以识别错误的引用。