For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/cli/alias/placeholders.md.
  • 简体中文
  • 参数处理

    占位符命名空间

    三个命名空间完全隔离:

    命名空间语法说明
    具名占位符{xxx}匹配输入中 xxx 后面紧跟的值
    可选透传{{xxx}}有 xxx 则原样渲染,无则消失
    系统占位符${...}固定语义,由系统提供
    变量(先行展开)

    ${byk_dir} / ${file_dir} / ${deps_dir} 以及 $var 声明的变量,在占位符解析之前由 byk 替换为字面量,不属于上述参数命名空间——它们不消耗任何参数位置,也不接受输入值。${args} / ${N} / ${...args} 仍由参数层处理。详见 变量。

    占位符一览

    占位符说明消耗位置数
    {xxx}匹配输入中 xxx 后面紧跟的值2(xxx + 值)
    {{xxx}}可选透传,有则渲染为 xxx value,无则消失2(有值时)
    {xxx?}条件渲染(最简),有 xxx 则渲染为 xxx,无则消失1
    {xxx?渲染1:渲染2}条件渲染(三元)1
    ${N}原始参数第 N 个(从 0 开始)1(位置 N)
    ${args}所有原始参数不消耗
    ${...args}剩余参数(去除已被其他占位符消耗的)不消耗

    消耗规则

    • {xxx} / {{xxx}} 消耗 xxx 及其紧跟的值(共 2 个位置)
    • {xxx?} / {xxx?渲染1} / {xxx?渲染1:渲染2} 只消耗 xxx 本身(1 个位置)
    • ${N} 消耗位置 N
    • 同一占位符多次出现,只消耗一次,值复用
    • ${...args} 的剩余 = 所有原始参数 - 已被消耗的位置,按原始顺序拼接

    无值 / 无占位符行为

    无占位符行为

    别名中不含任何占位符时,自动追加所有原始参数,等价于末尾隐式追加 ${args}。兼容 find 命令中的裸 {}(如 find . -exec ... {} +),不会被解析或替换。

    无值行为

    任何占位符取不到对应的值时,静默消失,不报错。参数缺失导致的错误由底层命令的运行时处理。

    参数保真

    命令最终交给 sh -c 解释,所以每个参数在拼进命令时都会被单引号包裹——边界由引号守住,不再交给 shell 重新切分:

    你输入命令收到
    byk probe "my file.json"1 个参数 my file.json
    byk probe ""1 个参数(空)
    byk probe 'a; echo INJECTED'1 个参数 a; echo INJECTED,echo 不会执行
    byk probe "*.json"1 个参数 *.json,不做通配展开
    byk probe 'C:\tmp\x'1 个参数 C:\tmp\x,反斜杠保留

    只有纯字母数字(外加 - _ . / : = @ + ,)的值不加引号,所以提示行里 cp src dst 依然是原样;需要引号时才会看到 cp 'my file.json' dst。

    参数不会再被 shell 展开

    *、~、$VAR 都在你敲命令时由你自己的 shell 处理过一次了——byk probe *.json 里的 * 在 byk 拿到之前就已经展开成文件列表。所以 byk 侧按字面传,是保真而不是丢失。

    Windows

    cmd 侧用双引号包裹,已知不保真的只剩 %VAR%:cmd 在引号内照样展开环境变量,命令行上也没有可靠的转义写法(%% 只在批处理文件里有效)。

    具名占位符示例

    长选项
    短选项
    # "copy": "cp {--src} {--dest}"
    byk copy --src foo.txt --dest bar.txt
    # 执行:cp foo.txt bar.txt

    可选透传示例

    # "build": "vite build {{--mode}}"
    byk build --mode production
    # 执行:vite build --mode production
    
    byk build
    # 执行:vite build

    条件渲染示例

    最简形式
    三元形式
    # "dev": "vite {--open?--open}"
    byk dev --open
    # 执行:vite --open
    
    byk dev
    # 执行:vite

    位置参数示例

    绝对位置
    重复使用
    剩余参数
    # "echo": "echo ${0} ${2}"
    byk echo aaa bbb ccc
    # 执行:echo aaa ccc