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/file-commands.md.
  • 简体中文
  • 文件命令

    每个别名文件都自带一组保留命令,用来创建、修改和查看这个文件本身:

    byk @文件..命令 [参数...]     # 当前目录
    byk @@文件..命令 [参数...]    # 全局目录 ~/.byk/alias/

    .. 是保留分隔符。以 @ / @@ 开头且含 .. 的形式不会再被当作别名,所以 byk @@ops..set 永远走文件命令,不会去找一个叫 @@ops..set 的别名。

    byk @@ops..init                            # 创建 ~/.byk/alias/ops.byk.json
    byk @@ops..set build --cmd "pnpm build"    # 写入 build 别名
    byk @@ops..json                            # 查看文件内容
    byk @@ops..help                            # 列出全部文件命令

    寻址

    写法目标文件
    @ops..json当前目录 ./ops.byk.json
    @@ops..json全局目录 ~/.byk/alias/ops.byk.json
    @..json当前目录匿名文件 ./.byk.json
    @@..json全局匿名文件 ~/.byk/alias/.byk.json
    • 文件名不能包含 .、@、/ 或空格;支持字母、数字、-、_ 与中文。
    • .. 取第一个出现的位置;后面的命令名只允许字母、数字、-、_。
    • 改写类命令只写被寻址的这个文件;clone、link、init --link 的来源只读。
    • ..set 与 ..remove 拒绝改写链接文件(单元素数组);要改内容请直接编辑链接目标。..clear 清空的是链接文件自身。
    • 需要文件存在的命令在目标缺失时,如果另一侧(当前目录 / 全局目录)有同名文件,会提示换用 @ 或 @@;..path 不要求文件存在。
    • 修改类命令的提示写 stderr;json、path、help 的数据写 stdout,方便管道和 $(...)。

    命令一览

    命令作用
    ..init创建空别名文件或链接文件
    ..destroy删除别名文件
    ..clear重置为空对象 {}
    ..set创建或修改别名、文件级元数据
    ..remove删除别名或整个分组
    ..json输出文件内容
    ..path输出文件绝对路径
    ..rename重命名别名文件
    ..clone从本地或远程复制一份别名文件
    ..link把当前文件改为指向另一个文件的链接
    ..deps安装、卸载或查看本文件声明的依赖
    ..help查看命令列表、用法与选项

    创建与删除

    ..init

    byk @@ops..init                      # 创建空文件 {}
    byk @ops..init --link @shared        # 创建指向 ./shared.byk.json 的链接
    • 内容固定为 {} 加一个结尾换行;不会覆盖已存在的文件。
    • --link <source> 创建链接文件(单元素数组),保存来源文件的规范化绝对路径。
    • 来源可以是 @name(当前目录)、@@name(全局目录)或路径(~ 展开,相对路径按当前目录解析)。来源必须是已存在的对象别名文件;指向链接文件时会被拒绝,链接只支持一层。
    • 本地裸名先读字面文件,缺失时再补 .byk.json;.、..、结尾 / 与目录名读取目录里的 .byk.json——与 ..clone 的本地规则相同。
    • 创建全局文件时,~/.byk/alias/ 不存在会自动创建。

    ..destroy

    byk @@ops..destroy        # 交互确认
    byk @@ops..destroy --yes  # 跳过确认
    • 删除被寻址的文件。交互确认要求输入文件名;非 TTY 环境必须带 --yes。
    • 符号链接只删除链接本身,不碰目标;目录会被拒绝。
    • 全局文件会连带删除它的依赖目录 ~/.byk/deps/@@<文件名>。

    ..clear

    byk @@ops..clear --yes
    • 把文件重置为 {}。已经为空时只提示 Already empty,不写盘。
    • 链接文件清空的是链接文件自身,目标内容不动。
    • 拒绝清空符号链接,需要删除链接时用 ..destroy。
    • 与 ..destroy 一样,非 TTY 环境需要 --yes。

    编辑别名

    ..set

    byk @@ops..set <key> [选项...]    # 编辑某个别名
    byk @@ops..set [选项...]          # 编辑文件级元数据

    第一个不以 - 开头的参数是别名 key;带点号表示分组路径,不存在的中间分组会自动创建。

    byk @@ops..set build --cmd "pnpm build"
    byk @@ops..set web.deploy --cmd "deploy.sh" --cwd ./web --mode interactive
    byk @@ops..set build --unset mode

    别名级选项:

    选项说明
    --cmd <command>设置命令;新建别名时必填
    --cwd <path>工作目录
    --mode <mode>normal / interactive / silent
    --description <text>帮助页描述
    --recursive / --no-recursive放行 / 取消调用链上的重复进入
    --private / --no-private移出 / 重新放回合并空间
    --unset <fields>删除元数据,可组合 cwd,mode,description,recursive

    文件根选项(不写 key):

    选项说明
    --priority <n>排序优先级;小于 0 按 0 处理
    --paths <dir>前置到 PATH 的目录;可重复,整体覆盖旧的 $paths
    --cwd <path>文件级工作目录
    --mode <mode>文件级执行方式
    --private / --no-private整个文件移出 / 重新放回合并空间
    --unset <fields>删除元数据,可组合 priority,paths,cwd,mode
    byk @@ops..set --priority 10 --paths ./bin --paths ~/tools/bin --private
    • 给字符串别名加元数据时,会转成 { "$cmd": ... } 对象形式;删掉多余的元数据后会自动折叠回字符串。
    • --private 可继承;--no-private 在子级写入 false,用来重新暴露 private 分组里的别名。详见 可见性。
    • key 不能以 $ 开头;元数据字段请用上面的选项,不要直接写进 key。

    ..remove

    byk @@ops..remove build
    byk @@ops..remove web.deploy
    • 按点号路径删除别名或整个子树。
    • 删除后只剩 $ 元数据的空分组会一并剪掉。
    • key 不存在会报错,不会静默成功。
    • 删除单个元数据字段用 ..set <key> --unset <fields>。

    查看

    ..json

    byk @@ops..json               # 校验后原样输出
    byk @@ops..json --no-check    # 不校验,原样输出
    byk @@ops..json --expand      # 展开变量并格式化
    • 默认只校验 JSON,输出精确的原始字节:不重排、不补换行。
    • --no-check 连校验都跳过,非法 JSON 也原样输出。
    • --expand 展开内置变量和文件 $var,删除 $var 后缩进输出;变量问题写 stderr。
    • --expand 与 --no-check 不能同时使用。
    • 链接文件输出数组本身,不跟随目标。

    ..path

    byk @@ops..path
    # /Users/me/.byk/alias/ops.byk.json

    输出绝对路径,不要求文件存在,也不接受参数。

    ..rename

    byk @@ops..rename tools
    • 在同一个作用域内改名(@ 只改当前目录,@@ 只改全局目录)。
    • 新名字遵循同样的文件名规则;目标已存在时拒绝。
    • 链接文件改的是链接文件本身,目标不动。
    • 全局文件的依赖目录 ~/.byk/deps/@@<旧名> 会同步改名为 @@<新名>,别名里的 ${deps_dir} 指向不变。

    ..help

    byk @@ops..help           # 命令列表
    byk @@ops..help set       # set 的用法与选项

    未知命令会列出全部可用命令。

    克隆与链接

    ..clone <source>

    byk @@ops..clone @shared
    byk @@ops..clone ~/src/tool.byk.json
    byk @@ops..clone ~/src/tool               # 自动补成 tool.byk.json
    byk @@ops..clone ./tools/release          # 子目录里的 release.byk.json
    byk @@ops..clone ./tools/                 # tools/.byk.json
    byk @@ops..clone .                        # 当前目录的 .byk.json
    byk @@ops..clone https://example.com/tool.byk.json
    byk @@ops..clone -gh user/repo                     # 仓库根的 .byk.json
    byk @@ops..clone -gh user/repo@main/tools/release.byk.json
    byk @@ops..clone --tap user/repo/build            # 按 byk.tap.json 解析 build
    byk @@ops..clone -t user/repo@v1/build -d
    byk @@ops..clone https://example.com/tool.byk.json -d   # 顺手装好 $deps

    来源可以是:

    来源说明
    @name / @@name当前目录 / 全局目录里的别名文件
    路径支持 ~;相对路径按当前目录解析;裸名字自动补 .byk.json
    http:// / https://通过外部 curl 下载
    -gh / --github从 GitHub 仓库读取
    -ge / --gitee从 Gitee 仓库读取
    -jd / --jsdelivr通过 jsDelivr 读取 GitHub 文件
    -t / --tap从本地或 GitHub 的 byk.tap.json 解析一个键
    -d / --deps克隆后接着装新文件的 $deps

    仓库简写的格式:

    <user>/<repo>[@<ref>][/<path>]
    • @<ref> 可省略,默认 HEAD。
    • <path> 可省略:省略就是仓库根的 .byk.json,所以 user/repo 与 user/repo/ 等价。
    • <path> 指向目录时以 / 结尾,表示读取该目录的 .byk.json。
    • 最后一段是文件名;.byk.json 后缀可写可不写。
    • 「省略 <path>」这一层糖只对整条路径生效:user/repo/ss 仍然读 ss.byk.json,不会被猜成 ss/ 目录。
    • 别带主机名。-gh github.com/user/repo 会被当成 user=github.com 去下载,所以直接报错并提示写成 user/repo。
    简写结果
    -gh user/repo仓库根 .byk.json
    -gh user/repo@v1v1 上的仓库根 .byk.json
    -gh user/repo@v1/tools/releasetools/release.byk.json
    -gh user/repo@v1/tools/tools/.byk.json
    -gh user/repo@v1/仓库根 .byk.json

    本地路径的解析顺序:

    写法读取
    ./tools/release.byk.json原样
    ./tools/release先读字面 release;没有则补 release.byk.json
    ./tools/、.、..该目录的 .byk.json(匿名文件)
    ./config.json、./hello.txt原样;其他扩展名不补
    • 裸名字字面优先:./tool 先读 tool,不存在再回退 tool.byk.json。这样 tool 与 tool.byk.json 同时存在时两个都可达——显式写 ./tool.byk.json 永远能命中后者。

    • 只有能构成合法别名文件名的裸名字才补后缀:hello.txt、my tool 这类保持字面,不会去找 hello.txt.byk.json——它本来就不是合法的别名文件名。

    • 裸名字最后落到一个目录时读该目录的 .byk.json,所以 ./tools、./tools/、. 都能指向匿名文件。

    • ..link 与 ..init --link 的来源解析与这里完全一致。

    • 都找不到时错误会列出尝试过的候选:Source not found: … 与 Also tried: …。

    • 目标文件必须不存在,..clone 不会覆盖。

    • 本地来源会先校验:必须是 JSON 对象;链接文件(数组)会被拒绝。

    • 内容是独立副本,与来源不再有关系。想要实时引用请用 ..link。

    • 标了 $clone: false 的别名和分组不会进入副本;分组里写 $clone: true 的子级仍会保留,标记本身不会出现在结果里。如果剔除后什么都不剩,clone 会在落盘前失败。含标记或发生过剔除的副本会重新序列化(键按字典序)。$private 不影响 clone。

    • 来源顺手把 $deps.base 冻结成绝对地址并打印一行 Recorded $deps.base = …。形态跟着来源走:远程写成绝对 http(s) 目录 URL,本地写成本机绝对目录路径。补的规则一致——没写就按源文件所在目录补上,写了相对形态(.、../、sub/dir)就相对源文件解析,写了绝对地址则原样保留,只补结尾的 /。

    • $deps.base 是程序写入的尽力锚点,不构成可移植性担保:克隆链路(a ← b ← c)每跳都会重新冻结,最初的来源语义可能丢失。不建议手写 base。

    • 两条路互不越界:远程来源遇到本地路径形态的 base(/x、C:/x)直接失败,于是从网上拿到的别名文件读不了本机文件;本地来源遇到绝对 URL 则照搬,那份文档的资产仍然从网上取。

    • clone 时 base 里出现变量会直接失败:那一刻没有变量表,${CDN} 求不出值,猜一个写死只会把意图烧成假地址。补写会让整份文档重新序列化(键按字典序);既没有 $deps 也没有 $clone 的文件仍是字节级副本。

    • 远程来源依赖 curl;缺少时会提示先安装。服务器返回 404 时报 Remote source not found: <url> 并提示检查仓库、ref 与路径——目录路径忘了以 / 结尾也归到这里。

    • 选项可以写在来源前后,-gh user/repo@v1/tool -d 与 -d -gh ... 等价。

    Tap 索引(--tap)

    一个仓库可以发布多个别名文件,而不必都堆在根目录:--tap 读取仓库根目录的 byk.tap.json 作为路由表。

    git clone https://github.com/user/repo ~/.byk/tap/user/repo   # 可选:byk 只读
    byk @@ops..clone --tap user/repo/build
    byk @@ops..clone --tap build                      # 搜索所有本地 tap 索引
    byk @@ops..clone -t user/repo@v1/build -d

    索引是一个扁平 JSON 对象;$ 开头的键保留给元数据,永远不参与匹配:

    {
      "build": "aliases/build.byk.json",
      "release": "https://example.com/other/tool.byk.json"
    }
    • Tap 来源形态:<user>/<repo>[@<ref>]/<key>。<ref> 默认 HEAD;<key> 只能是单个路径段,不能含 /、不能是 . / ..、不能以 $ 开头。
    • --tap 只支持 GitHub,本身就是一个来源形态:不能与 -gh、-ge、-jd 同时使用。
    • 完整写法本地索引优先。 spec 不带 @<ref> 时,先读 ~/.byk/tap/<user>/<repo>/byk.tap.json。这个文件存在就是权威:解析失败、缺键、value 非 string、目标不存在都会直接报错;只有索引文件本身不存在才回退 GitHub。写了 @<ref> 则始终使用远程索引。
    • 单 key 简写。 只写 --tap <key>(不含 /)时,搜索所有合法的 ~/.byk/tap/<user>/<repo>/byk.tap.json,只查本地索引、不联网拉取索引。唯一命中就从该索引克隆(value 是 URL 时仍走远程 clone);多个仓库都有这个 key 时,列出 user/repo/key 完整写法让你自己选;一个都没有则直接失败,不回退远程。
    • 简写只读两层:tap/<user>/<repo>/byk.tap.json。目录名必须是合法的 GitHub 用户名 / 仓库名,非法目录和没有索引的目录跳过。读不了或解析失败的索引会打印警告并跳过,所以「唯一」只对可读索引成立。
    • 简写不支持 @ref;要固定 ref 请用完整写法(走远程索引)。
    • ~/.byk/tap/ 是只读缓存:byk 不会创建、更新或删除它。需要自己准备,例如 git clone https://github.com/user/repo ~/.byk/tap/user/repo。
    • value 是精确指针:不会补 .byk.json,也不会把目录当成目录里的 .byk.json。以 @ / @@ 开头的目标同样按字面文件名处理,绝不解释成别名引用。
      • 本地索引:相对值以索引文件所在目录为基准;绝对路径与 ~ 按本地文件处理;http(s) URL 仍走远程 clone。
      • 远程索引:相对值以仓库根为基准;只允许 http(s) URL 和仓库内相对路径,不能指向本地。
    • 只路由一层。目标必须是别名文件,不能再是 tap 索引:最后一段是 byk.tap.json 的目标会被直接拒绝,解析出来的文件也不会被当成第二条路由。
    • $deps.base 锚在目标的位置上,而不是索引上。目标是本地文件时冻结成缓存里的本机绝对目录;目标是 URL 时保持 http(s) 目录 URL。
    • 索引缺失时报 Tap index not found: … 并提示在仓库根目录补 byk.tap.json;键缺失时列出可用键。
    • byk 会在路由前打印这次用的是哪份索引:Tap index: local <路径> 或 Tap index: remote <URL>,随后是 Tap <key> -> <目标>。

    克隆并安装依赖(-d)

    byk @@hello..clone https://example.com/hello.byk.json -d
    • 克隆落盘后立刻读新文件的 $deps:有就按 ..deps i 的同步语义装好(新建的 key 没有清单,等于首次安装);没有就跳过,不当成错误。
    • -d 对局部文件同样有效:依赖落在当前目录的 .byk/deps/@<文件名>/ 里,和 ..deps i 一致。
    • 安装不二次确认,也不需要 --yes:从 clone 到资产就位是一条命令的事,适合脚本与非交互环境。
    • 装依赖失败不回滚克隆:文件已经落盘且合法,按提示重跑 @@<file>..deps i 即可,已就位的资产不会重复下载。
    byk @@ops..link @shared
    • 把被寻址的文件改写为单元素数组,指向目标文件的规范化绝对路径。
    • 只能作用于空对象 {} 或已经是链接的文件;有内容的普通别名文件会被拒绝。
    • 目标必须是本地的对象别名文件;URL 会被拒绝并提示改用 ..clone。本地名称遵循与 ..clone 相同的规则:先读字面文件,再补 .byk.json,目录名则读取目录里的 .byk.json。
    • 拒绝指向自己,也拒绝改写符号链接。
    • 被寻址文件不存在时,会提示用 ..init --link 创建。
    • 全局文件改指向时,如果它的依赖目录已存在,会提醒先 ..deps uninstall,避免继续用旧目标的资产。
    • 链接后的行为、路径基准与身份归属见 单链接。

    ..deps [install|uninstall|status]

    byk @@tool..deps                       # 查看现状:声明几条、到位几条,哪些缺失、过期、多余或未知
    byk @@tool..deps install               # 同步文件并安装声明的包
    byk @@tool..deps i                     # 同上,取无歧义前缀
    byk @@tool..deps i --force             # 忽略清单,重下文件条目
    byk @@tool..deps uninstall             # 删除整个依赖目录(交互确认)
    byk @@tool..deps u                     # 同上;u / un / uni 都认
    byk @@tool..deps uninstall --yes       # 删除时跳过确认

    子命令取 install / uninstall / status,也接受无歧义前缀;不带子命令等于 status。

    install 是同步,不是追加。 $deps.files 是期望状态,安装让目录收敛到它:

    情形动作
    声明里有、目录里没有add
    声明里有、清单里有、源变了update(重下覆盖,原子替换)
    清单里有、文件被删了repair
    只有 exec 不一致chmod,不重下
    声明里有、清单里没有、文件已存在adopt:接管老文件,不重取
    声明里没有、清单里有remove(连空掉的父目录一起收)
    完全一致keep,跳过
    $ byk @@tool..deps i
    Syncing 2 declared entries in ~/.byk/deps/@@tool:
      update  @@tool/bin/tool <- https://example.com/v2/tool
      keep    @@tool/etc/cfg.json
    Downloaded 1 file into ~/.byk/deps/@@tool

    文件条目都没变、也没有声明包时是空操作,不产生任何请求:

    $ byk @@tool..deps i
    @@tool: 2 declared, 2 present — up to date
    • src 写相对路径时靠 $deps.base 拼成绝对地址;两者缺一就报错,不会去猜。base 落盘后必须是绝对地址——URL 形态对应下载,本机路径形态对应复制(..clone 按来源决定写哪种)。相对写法只在 ..clone 时才有意义。base 由程序写入,是尽力锚点而非可移植性担保,不建议手写。
    • 本地条目按源文件 mtime 判新旧:源比装好的那份新就重装;源不在了就报 cannot read 并给出路径,不安静跳过。
    • 全局与局部都支持:全局落到 ~/.byk/deps/@@<文件名>/,局部落到 <文件所在目录>/.byk/deps/@<文件名>/ 并自带 .gitignore(内容 *)。
    • 已安装清单存在 <专属目录>/.byk-deps.json,记录上次声明的快照与落点。删除它等于重新开始记账,安装会重新「接管」现有文件。
    • 只删自己装过的路径:目录里多出来的文件永远不动,只提示一句。
    • 安装不二次确认,也不需要 --yes;--force 是唯一的选项,用于「文件资产被外部改坏」这类清单看不出的情况。
    • 绝对地址交给系统 curl,本地路径直接 fs::copy(同样先落临时文件再 rename);解压两条路都交给系统 tar,缺失时报错并提示安装。汇总行两种来源都写 Downloaded,其中来自本地复制的条数在括号里交代(Downloaded 3 files into … (1 local)),一条本地都没有时不出现括号——$deps.files 只负责取文件;$deps.pip 与 $deps.npm 交给 pip / npm 自己处理,不记账在文件清单里。
    • $deps.pip 把 Python 包装进专属目录里的 .venv:venv 缺失时用 python3(Windows 为 python)创建,然后执行 pip install。venv 的 bin / Scripts 会前置到 PATH;缺少 Python 时报错并提示安装。
    • $deps.npm 把 npm 包装进专属目录:缺失时写一个最小 package.json(byk-deps、private),然后执行 npm install。node_modules/.bin 会前置到 PATH;缺少 npm 时报错并提示安装。
    • 包每次安装都会执行,且不记进 .byk-deps.json——是否最新由 pip / npm 判断。--force 只影响文件条目;从声明里删掉某个包不会卸载它,想清空整个目录用 ..deps uninstall。files 可以省略,所以声明里可以只有包。
    • 落点都圈在专属目录内(全局 ~/.byk/deps/@@<文件名>/,局部 <文件所在目录>/.byk/deps/@<文件名>/)。字段说明见 依赖。
    • 带 extract 的条目落点是目录,用 (extract) 标注;重装时整目录替换,旧归档里没有的文件不会留下。省略 to 表示解到专属目录根,这种条目必须单独存在(它会换掉整个目录):
    Downloading 2 files into ~/.byk/deps/@@tool:
      add     @@tool/bin/tool <- https://example.com/cli-linux
      add     @@tool/dist <- https://example.com/tool-1.4.tar.gz (extract)
    Downloaded 2 files into ~/.byk/deps/@@tool
    • 中途失败不回滚已完成的条目,错误里列出这次已经落盘的路径;清单也会写成实际状态,重跑接着做。
    • uninstall 删除整个依赖目录;目录不存在时报错。status 只读,文本写 stdout,适合管道:
    @@tool: 6 declared, 2 present, 1 stale
      ok        @@tool/bin/tool
      missing   @@tool/etc/cfg.json
      outdated  @@tool/dist
      stale     @@tool/bin/old-tool
      ok        pip:click>=8.0
      unknown   pip:git+https://example.com/tool.git
      missing   npm:chalk
    Base: https://example.com/releases/v1/
    Deps directory: ~/.byk/deps/@@tool
    Hint: run `byk @@tool..deps i` to install the missing assets

    unknown 表示 pip 的 URL / VCS 直接引用:本地拿不到包名,byk 如实标注而不去猜。这类条目既不算到位,也不算缺失。

    --check 只校验声明本身:能不能解析、落点是否冲突、相对 src 有没有 base、包条目是否非空字符串,不碰装没装。缺哪条、旧没旧是运行时状态,用 ..deps status 看,或者在执行前跑一次 ..deps i。

    补全

    文件命令的补全覆盖:

    • @ / @@ 后的文件名,输入 .. 后补命令名;
    • 命令后的选项(如 ..set --);
    • ..help 后面的命令名;
    • ..remove 后面的已有 key 路径(读目标文件,链接文件不补);
    • ..clone、..link、..init --link 的来源参数(以 @ 开头的别名文件);
    • ..deps 后面的子命令(install / uninstall / status)。