程序接口 __api__
byk __api__ 是 byk 面向程序的一面:从不执行别名,从不写磁盘,可以任意频率调用。它不出现在 -h 里——它本来就不是给人看的。
三条约定,所有请求通用:
- stdout 只有数据:告警、错误一律写 stderr,所以
$(byk __api__ …)拿到的永远是干净的值 - 失败退出码 1:未知请求、缺参数、不支持的 shell、未知的路径名
- 表外的参数位不存在:多写一个参数是错误,不会被忽略
请求一览
最后一条建议常备:请求名别背,直接问。清单顶层的 version 是 CLI 版本,与 -v 首行一致,集成方不必再解析版本文本。
completion <shell>
打印某个 shell 的补全注册脚本,由它在 Tab 时反过来调用 complete。写错 shell 时退出码 1,并列出支持的三个:
这个请求是给安装脚本用的,日常只需要这一行(见补全是怎么接上的)。
complete [--with-descriptions] <words...>
把命令行上已经敲下的词原样传进去,返回候选,一行一个。带 @ / @@ 前缀时只返回文件 key,带分组前缀时只返回该组的子项。空输入只列合并别名——文件 key 要等词以 @ / @@ 开头才出现。带 --with-descriptions 时,内置选项、文件命令动词与文件 key 都附带 tab 分隔的描述;文件 key 的描述是别名文件路径,家目录显示为 ~。
别名只补第一个词。别名只认点号单 token(grp.inner),词一旦被空格终结,后面敲的都是原样传给目标命令的参数,byk 无从得知它们该是什么——所以 complete grp ''(byk grp 后按 Tab)返回空,不会像子命令那样列出 inner。光标在空格后时 shell 传一个空词,正是靠它区分「还在敲第一个词」和「第一个词已经敲完」。
文件命令是这条规则的例外:它的参数由 byk 自己解释,所以 ..help 后补命令名、..remove 后补文件里已有的 key、..clone / ..link / ..init --link 后补来源文件、命令后补该命令的选项。清单见文件命令 - 补全。
它做的是一次只读扫描,扫描期对别名文件的告警(例如非法变量名)仍然走 stderr——stdout 上只有候选,补全脚本因此可以直接 $(...)。
resolve <key> [args...]
解析一个别名但不执行:返回最终命令、工作目录、PATH 前缀和执行方式。键支持两种写法——合并空间里的名字(dep),或精确语法(@run.build、@@ops.deploy)。文件命令不是别名,@文件..命令 会被拒绝并以退出码 1 结束;路径段以 $ 开头的保留字段或自定义元数据同样不是别名。
file.key
run.build 是点号路径,会在合并空间里当成分组名查找,通常找不到。文件 key 必须带前缀:@run.build。
两个字段的语义值得单独说清,插件的正确性基本都压在它们身上:
command在interactive时是模板。交互别名的占位符值要问用户,而无终端时 byk 无法代答,所以原样返回deploy --env {env}并置mode: "interactive"。调用方要么自己交互,要么把请求交回终端里的 byk;直接执行这个字符串等于跳过确认。paths是生效值,不是配置值。它已绝对化(相对条目以别名文件所在目录为基准)、只保留真实存在的目录,并且包含工作目录下的node_modules/.bin;文件声明了$deps.pip/$deps.npm时,依赖目录里的 venv bin /node_modules/.bin也会包含在内。文件里写了但目录不存在的条目不会出现。
paths [name]
不带名字返回目录与别名文件清单的 JSON,给需要一次拿全的程序:
清单只按文件名枚举、不读取内容:JSON 损坏、链接目标缺失或符号链接断链的文件照样列出,能否使用交给 check;文件名非法的文件不会出现。所有值都只回答"在哪",不会顺手创建目录。
取路径
shell 脚本用 paths <name>:它只打印那个值的裸字符串,不带引号、不带标签、结尾只有一个换行,正好是 $() 想要的形状。<name> 可取 root、alias、workdir,与 JSON 字段一一对应。
名字写错时列出可选值,退出码 1:
之所以不给 paths <name> 也套 JSON:它的调用方是 shell 脚本,套一层就得靠 jq 或 sed 剥引号,而 "$(...)" 天然拿到干净的值;需要结构化数据的程序走无参 paths。人读的版本仍然是 byk --paths——带标签和空行,终端里一眼看清;它与无参 paths 共用同一份路径布局和同一份文件名枚举,区别只在展示形状。
file <file-key> / --list
file 有两种用法:给一个文件 key,解析成地址;或加 --list,列出全部别名文件。
单个 key
把文件 key 解析成地址,不读文件,也不要求文件存在:
接受与文件命令相同的 key 形式:@name(工作目录)、@@name(全局别名目录)、@ / @@(匿名文件 .byk.json)。path 与 paths.aliasFiles 中的一项相同,另外附带 key、scope 与 dir。
- 不要求文件存在:它回答的是"按 byk 的规则会落在哪里",与
@run..path的输出路径相同,另外附带scope与dir。 - 只解析地址,不解析内容:想知道某个别名来自哪个文件、最终命令是什么,用
resolve。 - 不跟随链接:返回的是链接文件本身的位置,不是它指向的目标。
- 别名 key 会被拒绝:
@run.build里的点让它成为非法文件名,退出码 1。
--list
不带 key、只给 --list 时返回全部别名文件,排序与 paths.aliasFiles 相同:先全局后本地,各自按 key 排序。与 aliasFiles 不同,它保留两种作用域身份,因此同一目录兼作全局与本地时会出现两条。每项与单查的返回体同形。
清单只按文件名枚举、不读取内容:JSON 损坏、链接目标缺失或符号链接断链的文件照样列出,文件名非法的文件不会出现。--list 不能与 key 同时给出,未知选项同样以退出码 1 结束。
expand [--no-builtins] <path>
展开一个 JSON 文件里的变量并输出结果。参数是普通文件路径(相对路径按进程工作目录解析),不是 @文件key。选项写在路径前面。
--no-builtins 只展开文件自己的 $var:不注入 ${byk_dir}、${work_dir}、${file_dir}、${deps_dir},没有声明同名变量时原样保留。
默认规则与 ..json --expand 相同:
- 展开
${byk_dir}、${work_dir}、${file_dir}以及顶层$var;$var可以覆盖内置名;目标在全局别名目录内时另注入${deps_dir} - 展开后移除顶层
$var - 未识别的
${name}、裸$HOME、\${...}原样保留;${args}是别名占位符,不展开 - 不做别名结构校验:没有
$var、没有$cmd、甚至根不是对象都可以,只要是合法 JSON 就处理;除非传了--no-builtins,内置变量照样展开 - 不跟随 link 数组、不做继承、不执行任何内容
--no-builtins 只属于 __api__ 请求(..json --expand 没有):四个内置变量不注入,除此以外 $var 的移除、名字检查与告警都和上面一致。$var 里显式声明同名变量时,它就是普通自定义变量。
$var 声明的问题(非法名字、自引用等)只写 stderr 告警,请求仍然成功,stdout 是一份完整 JSON;只有文件读不到、目标是目录、非法 UTF-8/JSON 才退出 1,stdout 为空。
check
byk --check 的机器版本:扫描工作目录与全局别名目录——和正常执行读的是同两处——把发现的问题返回为 JSON。
发现问题不改变退出码。 只要请求跑完就算成功:stdout 一定是一份完整数据,调用方读 items;只有用法错误(多写参数)才退出 1。这样「有问题」和「请求失败」从一开始就是两件事,上面那条 __api__ 退出码约定不适用于检查结果。
扫描和正常执行一样不递归:只覆盖进程工作目录与全局别名目录,所以编辑器插件想覆盖哪些目录,就按目录各发一次请求。
补全是怎么接上的
install.sh 会往 ~/.zshrc(或 ~/.bashrc)写一行:
这行把 Tab 事件转给 byk __api__ complete,由 byk 实时扫描别名后返回候选。手工写同样的行也完全等价。
版本与兼容
请求可能随版本增加——resolve、paths、file、expand 和 check 都是后来才有的。写集成时:
- 请求名从
byk __api__读,不要写死在代码里 - 解析 JSON 时容忍未知字段,字段只会增加
- 动手前用
byk -v确认版本,旧版本上没有你要的请求会直接以退出码 1 失败