选项与命令
byk 的命令行只有四层:选项、别名、文件命令、程序接口。除了保留字里的几个词,其余任何一个词都会被当作别名去查找——所以想到什么名字都能用。
选项
byk 不带参数与 byk -h 输出完全一致。第一行固定为 byk <版本> (<commit> <构建日期>) [<平台>],可以安全地用 byk -v | head -1 取版本号。
installed at 那行在可执行文件是符号链接时会追加 -> 目标路径,用来确认真正执行的是哪一份。
CLI Home 是 byk 的家目录,Alias 是全局别名文件所在目录,Workdir 是扫描本地文件时使用的当前目录。把 *.byk.json 放进这两处目录,它就会进入查找空间。
--paths 还会列出全局别名目录和当前工作目录顶层的别名文件,每个来源一组。@@ / @ 前缀区分全局与本地。只校验文件名,不解析内容:JSON 损坏的文件、标了 $private 的文件、断链的符号链接也会出现在这里。内容问题用 --check 查。空分组连同分隔线一起不打印。
帮助页里的别名列表只包含合并空间中的别名:标了 $private: true 的别名不出现在这里,因为它们本来就只能通过 @file.key 调用。设了 $cwd 的别名后面会附上生效目录,形如 deploy deploy.sh (/Users/me/proj)。
诊断 --check
扫描别名文件时发现的问题不再在普通执行时直接输出。只要有问题,-h 顶部的 banner 会变成:
用 byk --check 查看按文件分组的明细:
没有任何问题时输出 Scanned N alias files; no problems. 并返回 0;有问题返回 1。Scanned 统计的是遇到的候选 *.byk.json 目录项,包括非法文件名和断链的符号链接。目前覆盖:文件读取、JSON 解析、根类型、别名与元数据字段类型、链接文件、非法文件名、断链符号链接、$mode、$var、$deps 声明(含 base、落点冲突与包条目)等。它只查配置本身——依赖装没装是运行时状态,用 ..deps status 看。--check 不带别名参数,多写会报 check takes no arguments。
执行别名
合并空间由全局目录 ~/.byk/alias/(优先级 0)与当前目录(优先级 1)组成,同名时项目里的覆盖全局的。
精确语法只做文件路由,不做 fallback:
- 文件不存在 →
Alias file not found: @run(全局是@@run) - 文件存在但无法加载 →
Alias file cannot be loaded: @run,附原因并提示byk --check - key 不存在 →
Alias key not found in file @run: build - 路径段以
$开头 →Not an alias (reserved $ field): @run.build.$cmd
以上都以退出码 1 结束。$ 开头的段是保留字段或自定义元数据,永远不会被当作别名执行。
每个别名文件还带一组保留的文件命令:用 @文件..命令 / @@文件..命令 创建、编辑、克隆、安装依赖和查看文件本身。完整列表见 文件命令。
程序接口 __api__
byk __api__ 是给程序和编辑器插件用的只读接口:从不执行别名,从不写磁盘,可以任意频率调用。它不出现在 -h 里。
请求列表、每个字段的语义与调用示例都在 程序接口 里——集成时该读的是那一页。
保留字
byk <word> 里的任何一个词都会被当作别名查找,只有下面这几个例外,别名不能同名:
除此之外都是自由的——连 version、paths 这样的词也能当别名,只要不带前导 -。
匹配顺序
输入 byk <word> ... 时按以下顺序判断,第一个命中即返回:
__api__隐藏接口-h/-v/--paths/--check等选项@file.key/@@file.key精确执行- 合并空间里的别名
文件命令在步骤 3 之前就地处理:含 .. 的 @文件..命令 不会走到别名查找。同时给出多个选项时,-h 优先,其次是 --check、--paths、-v。
全部未命中时,输出 Unrecognized command or alias: <word>,并附上候选建议,退出码 1。