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/api.md.
  • 简体中文
  • 程序接口 __api__

    byk __api__ 是 byk 面向程序的一面:从不执行别名,从不写磁盘,可以任意频率调用。它不出现在 -h 里——它本来就不是给人看的。

    三条约定,所有请求通用:

    • stdout 只有数据:告警、错误一律写 stderr,所以 $(byk __api__ …) 拿到的永远是干净的值
    • 失败退出码 1:未知请求、缺参数、不支持的 shell、未知的路径名
    • 表外的参数位不存在:多写一个参数是错误,不会被忽略

    请求一览

    请求输出
    __api__ completion <shell>补全注册脚本(zsh / bash / fish)
    __api__ complete [--with-descriptions] <words...>补全候选,一行一个;带 flag 时内置选项、文件命令动词和文件 key(别名文件路径)附带 tab 分隔的描述
    __api__ resolve <key> [args...]别名的解析结果,JSON
    __api__ pathsCLI 目录、工作目录与别名文件清单,JSON
    __api__ paths <name>单个目录的裸路径(root / alias / workdir)
    __api__ file <file-key> / --list单个文件地址或全部文件清单,JSON
    __api__ expand [--no-builtins] <path>展开 JSON 文件中的变量,输出 JSON
    __api__ check扫描诊断,JSON
    __api__(无参)接口清单,JSON

    最后一条建议常备:请求名别背,直接问。清单顶层的 version 是 CLI 版本,与 -v 首行一致,集成方不必再解析版本文本。

    byk __api__
    byk __api__
    {
      "version": "0.8.0",
      "requests": [
        {
          "name": "completion",
          "args": "<shell>",
          "description": "print the shell registration script (zsh|bash|fish)"
        },
        {
          "name": "complete",
          "args": "[--with-descriptions] <words...>",
          "description": "print completion candidates; the flag appends a tab-separated description"
        },
        {
          "name": "resolve",
          "args": "<key> [args...]",
          "description": "resolve an alias to its final command without executing"
        },
        {
          "name": "paths",
          "args": "[name]",
          "description": "print CLI paths and alias file locations as JSON; with <name>, print only that path (root|alias|workdir)"
        },
        {
          "name": "file",
          "args": "<file-key> | --list",
          "description": "resolve an alias file key (@name / @@name) to its path, or list every alias file with --list"
        },
        {
          "name": "expand",
          "args": "[--no-builtins] <path>",
          "description": "expand file-level $var in a JSON file without alias validation; --no-builtins leaves byk_dir/work_dir/file_dir/deps_dir unset"
        },
        {
          "name": "check",
          "args": "",
          "description": "print scan diagnostics as JSON; problems do not change the exit code"
        }
      ]
    }

    completion <shell>

    打印某个 shell 的补全注册脚本,由它在 Tab 时反过来调用 complete。写错 shell 时退出码 1,并列出支持的三个:

    Unsupported shell: pwsh
      Supported: zsh, bash, fish

    这个请求是给安装脚本用的,日常只需要这一行(见补全是怎么接上的)。

    complete [--with-descriptions] <words...>

    把命令行上已经敲下的词原样传进去,返回候选,一行一个。带 @ / @@ 前缀时只返回文件 key,带分组前缀时只返回该组的子项。空输入只列合并别名——文件 key 要等词以 @ / @@ 开头才出现。带 --with-descriptions 时,内置选项、文件命令动词与文件 key 都附带 tab 分隔的描述;文件 key 的描述是别名文件路径,家目录显示为 ~。

    $ byk __api__ complete grp.
    grp.inner

    别名只补第一个词。别名只认点号单 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。

    byk __api__ resolve @run.build --env staging
    字段说明
    key传入的键,原样回显
    source命中的文件 key,如 @run / @@ops
    sourcePath该别名文件的绝对路径;仅少数无来源的场合为 null
    command非交互别名:占位符已按参数解析的最终命令(参数已按 shell 规则引用,可直接交给 sh -c);交互别名:未解析的模板
    cwd执行时的工作目录(绝对路径)
    paths实际前置到 PATH 的目录,见下
    modenormal / interactive / silent
    interactivemode == "interactive" 的派生布尔,保留给只认布尔值的旧版本调用方
    description$description,未设置为 null

    两个字段的语义值得单独说清,插件的正确性基本都压在它们身上:

    • command 在 interactive 时是模板。交互别名的占位符值要问用户,而无终端时 byk 无法代答,所以原样返回 deploy --env {env} 并置 mode: "interactive"。调用方要么自己交互,要么把请求交回终端里的 byk;直接执行这个字符串等于跳过确认。
    • paths 是生效值,不是配置值。它已绝对化(相对条目以别名文件所在目录为基准)、只保留真实存在的目录,并且包含工作目录下的 node_modules/.bin;文件声明了 $deps.pip / $deps.npm 时,依赖目录里的 venv bin / node_modules/.bin 也会包含在内。文件里写了但目录不存在的条目不会出现。
    byk __api__ resolve int
    {
      "key": "int",
      "source": "@i",
      "sourcePath": "/Users/you/proj/i.byk.json",
      "command": "deploy --env {env}",
      "cwd": "/Users/you/proj",
      "paths": ["/Users/you/proj/scripts", "/Users/you/proj/node_modules/.bin"],
      "mode": "interactive",
      "interactive": true,
      "description": null
    }

    paths [name]

    不带名字返回目录与别名文件清单的 JSON,给需要一次拿全的程序:

    byk __api__ paths
    {
      "root": "/Users/you/.byk",
      "alias": "/Users/you/.byk/alias",
      "workdir": "/Users/you/proj",
      "aliasFiles": [
        "/Users/you/.byk/alias/ops.byk.json",
        "/Users/you/proj/run.byk.json"
      ]
    }
    字段说明
    rootCLI 根目录,也就是别名里可用的 ${byk_dir}
    alias全局别名目录
    workdir进程工作目录,也就是本地别名文件的查找目录
    aliasFiles两处目录下的别名文件绝对路径:先全局后本地,各自按 key 排序;同一目录兼作两种作用域时只列一次;没有文件时为空数组。需要 key、scope 或所在目录时用 file --list

    清单只按文件名枚举、不读取内容:JSON 损坏、链接目标缺失或符号链接断链的文件照样列出,能否使用交给 check;文件名非法的文件不会出现。所有值都只回答"在哪",不会顺手创建目录。

    取路径

    shell 脚本用 paths <name>:它只打印那个值的裸字符串,不带引号、不带标签、结尾只有一个换行,正好是 $() 想要的形状。<name> 可取 root、alias、workdir,与 JSON 字段一一对应。

    INSTALL_DIR="$(byk __api__ paths root)/bin"
    ALIAS_DIR="$(byk __api__ paths alias)"
    WORKDIR="$(byk __api__ paths workdir)"

    名字写错时列出可选值,退出码 1:

    __api__ paths: unknown name "bin" (expected one of: root, alias, workdir)

    之所以不给 paths <name> 也套 JSON:它的调用方是 shell 脚本,套一层就得靠 jq 或 sed 剥引号,而 "$(...)" 天然拿到干净的值;需要结构化数据的程序走无参 paths。人读的版本仍然是 byk --paths——带标签和空行,终端里一眼看清;它与无参 paths 共用同一份路径布局和同一份文件名枚举,区别只在展示形状。

    file <file-key> / --list

    file 有两种用法:给一个文件 key,解析成地址;或加 --list,列出全部别名文件。

    单个 key

    把文件 key 解析成地址,不读文件,也不要求文件存在:

    byk __api__ file @run
    byk __api__ file @run
    {
      "key": "@run",
      "scope": "local",
      "path": "/Users/you/proj/run.byk.json",
      "dir": "/Users/you/proj"
    }

    接受与文件命令相同的 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 不同,它保留两种作用域身份,因此同一目录兼作全局与本地时会出现两条。每项与单查的返回体同形。

    byk __api__ file --list
    byk __api__ file --list
    {
      "files": [
        {
          "key": "@@ops",
          "scope": "global",
          "path": "/Users/you/.byk/alias/ops.byk.json",
          "dir": "/Users/you/.byk/alias"
        },
        {
          "key": "@run",
          "scope": "local",
          "path": "/Users/you/proj/run.byk.json",
          "dir": "/Users/you/proj"
        }
      ]
    }

    清单只按文件名枚举、不读取内容:JSON 损坏、链接目标缺失或符号链接断链的文件照样列出,文件名非法的文件不会出现。--list 不能与 key 同时给出,未知选项同样以退出码 1 结束。

    expand [--no-builtins] <path>

    展开一个 JSON 文件里的变量并输出结果。参数是普通文件路径(相对路径按进程工作目录解析),不是 @文件key。选项写在路径前面。

    --no-builtins 只展开文件自己的 $var:不注入 ${byk_dir}、${work_dir}、${file_dir}、${deps_dir},没有声明同名变量时原样保留。

    ./config.json
    {
      "$var": {
        "TOOLS": "${byk_dir}/tools"
      },
      "deploy": "cd ${file_dir} && ${TOOLS}/deploy.sh"
    }
    byk __api__ expand ./config.json
    byk __api__ expand ./config.json
    {
      "deploy": "cd /Users/you/proj && /Users/you/.byk/tools/deploy.sh"
    }

    默认规则与 ..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。

    byk __api__ check
    byk __api__ check
    {
      "scanned": 2,
      "errors": 1,
      "warnings": 1,
      "items": [
        {
          "level": "error",
          "path": "/Users/you/proj/gone.byk.json",
          "message": "cannot load link target /Users/you/proj/missing.byk.json: cannot read file: No such file or directory (os error 2)"
        },
        {
          "level": "warning",
          "path": "/Users/you/proj/env.byk.json",
          "message": "$mode must be one of normal|interactive|silent, got \"activ\" (treated as normal)"
        }
      ]
    }
    字段含义
    scanned遇到的候选 *.byk.json 目录项数量,包括非法文件名与断链符号链接
    errors / warnings条目数量,调用方不必遍历列表就能出徽标
    items[].levelerror(文件或别名不可用)或 warning(仍可用但可疑)
    items[].path问题所属文件的绝对路径
    items[].message与人读报告里完全相同的文本

    发现问题不改变退出码。 只要请求跑完就算成功:stdout 一定是一份完整数据,调用方读 items;只有用法错误(多写参数)才退出 1。这样「有问题」和「请求失败」从一开始就是两件事,上面那条 __api__ 退出码约定不适用于检查结果。

    扫描和正常执行一样不递归:只覆盖进程工作目录与全局别名目录,所以编辑器插件想覆盖哪些目录,就按目录各发一次请求。

    补全是怎么接上的

    install.sh 会往 ~/.zshrc(或 ~/.bashrc)写一行:

    # byk shell completion
    if command -v byk >/dev/null 2>&1; then source <(byk __api__ completion zsh); fi

    这行把 Tab 事件转给 byk __api__ complete,由 byk 实时扫描别名后返回候选。手工写同样的行也完全等价。

    版本与兼容

    请求可能随版本增加——resolve、paths、file、expand 和 check 都是后来才有的。写集成时:

    • 请求名从 byk __api__ 读,不要写死在代码里
    • 解析 JSON 时容忍未知字段,字段只会增加
    • 动手前用 byk -v 确认版本,旧版本上没有你要的请求会直接以退出码 1 失败