import { Tab, Tabs } from '@rspress/core/theme';

# 别名配置

## 类型定义

```ts title="alias.types.ts"
// 别名对象（带元数据的形式）
type AliasObject = {
  $cmd?: string;
  $cwd?: string;
  $mode?: 'normal' | 'interactive' | 'silent';
  $description?: string;
  $recursive?: boolean;
  $private?: boolean;
  $clone?: boolean;
  [key: string]: string | AliasObject | boolean | undefined;
}

// 文件级依赖声明：资产文件、pip 包、npm 包
type Deps = {
  base?: string;
  files?: Array<string | { src: string; to?: string; name?: string; extract?: boolean; exec?: boolean }>;
  pip?: string[];
  npm?: string[];
};

// 一个 *.byk.json 文件：别名对象，或单链接数组
type AliasFileJSON =
  | {
      $priority?: number;      // 排序优先级，默认当前目录 = 1、全局 = 0；小于 0 按 0 处理
      $cwd?: string;           // 文件级 / 分组级工作目录，子别名自动继承
      $mode?: 'normal' | 'interactive' | 'silent';  // 文件级 / 分组级执行方式，子别名自动继承
      $private?: boolean;      // 文件级 / 分组级私有，子别名自动继承；私有别名不进合并空间
      $clone?: boolean;        // 文件级 / 分组级复制标记，子别名自动继承；false 不进 ..clone 的副本
      $paths?: string[];       // 文件级 PATH 目录列表，子别名自动继承
      $deps?: Deps;            // 文件级依赖：资产文件、pip 包、npm 包
      $var?: Record<string, string | Record<string, string>>;  // 文件级变量
      [key: string]: string | AliasObject | Deps | number | boolean | undefined;
    }
  | [string];  // 单链接：只含一个路径的数组
```

文件级只解释这八个 `$` 开头的键；其余 `$xxx` 不会被当作别名，也不参与合并，保留给其他工具存放配置。字符串里的 `${xxx}` 由[变量](#变量)机制展开，未声明的名字原样留给 shell。

## 别名对象

### Key 命名规则

* key **不能包含** `@` 或 `.`，违规则该条目被静默忽略
* 支持中文 key 名
* 支持嵌套分组（object），通过 `.` 分隔符访问

### 系统字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `$cmd` | string | 执行命令 |
| `$cwd` | string | 工作目录（可继承） |
| `$mode` | `'normal'` | `'interactive'` | `'silent'` | 执行方式（可继承），默认 `normal` |
| `$description` | string | 帮助页描述文本（不可继承） |
| `$recursive` | boolean | 放行调用链上的重复进入（不可继承），默认 `false`，见[递归保护](#递归保护) |
| `$private` | boolean | 不进入合并空间，只能精确调用（可继承），默认 `false`，见[可见性](#可见性) |
| `$clone` | boolean | 不进入 `..clone` 的副本（可继承），默认 `true`，见[克隆](#克隆) |

:::note
含 `$cmd` 的 object 是别名叶子节点。只有 `$cwd` / `$mode` / `$private` / `$clone` 而没有 `$cmd` 的 object 是**带继承属性的分组**，本身不可执行。
:::

### 工作目录 cwd

三级继承：文件级 → 分组级 → 别名级，越靠近别名优先级越高。支持 `~`；**相对路径以别名文件所在目录为基准**解析，与你在哪个目录敲 `byk` 无关。不写 `$cwd` 时用调用时的工作目录。

<Tabs>
  <Tab label="别名级指定">
    ```json
    {
      "install": {
        "$cmd": "npm i",
        "$cwd": "/project/web"
      }
    }
    ```
  </Tab>

  <Tab label="分组级继承">
    ```json
    {
      "services": {
        "$cwd": "/project",
        "install": "npm i",
        "web": {
          "$cwd": "/project/web",
          "dev": "pnpm dev",
          "build": "pnpm build"
        }
      }
    }
    ```

    `install` 继承 `services` 的 `/project`，`web.dev` 与 `web.build` 使用 `web` 分组覆盖的 `/project/web`。
  </Tab>

  <Tab label="文件级继承">
    ```json
    {
      "$cwd": "/project/web",
      "install": "npm i",
      "start": {
        "$cmd": "pnpm dev",
        "$cwd": "/project/web/frontend"
      }
    }
    ```

    `install` 继承文件级的 `/project/web`，`start` 使用自己的 `/project/web/frontend`。
  </Tab>
</Tabs>

文件级 `$cwd` 会被所有子别名继承。若某个别名需要回到“敲下 byk 时”的目录，把它的 `$cwd` 写成 `"${work_dir}"`：

```json
{
  "$cwd": "/project/web",
  "here": { "$cmd": "pwd", "$cwd": "${work_dir}" }
}
```

`${work_dir}` 在扫描期就展开为绝对路径，写它等同于在配置里直接写绝对路径，因此不再参与相对路径解析。它指当前这次 byk 进程启动时的目录：别名 A 在自己的 `$cwd` 里调用 `byk B` 时，B 看到的 `${work_dir}` 是 A 的工作目录。

### 执行方式

`$mode` 决定别名怎么跑，三态互斥，默认 `normal`。

| 值 | 行为 |
|---|---|
| `normal` | 打印提示行，然后直接执行 |
| `interactive` | 打印提示行，逐项询问占位符，回车确认后才执行 |
| `silent` | 连终端上也不打提示（管道场景本来就不打） |

执行前 byk 会往 **stderr** 打两行提示：来源（`文件.key` 与落地目录）和解析后的最终命令。
走 stderr 而不是 stdout，是因为这两行是给人看的旁白，不该混进可以被管道消费的数据：

* `byk build > log.txt`、`byk build | grep error` 拿到的只有命令自己的输出；
* stderr 不是终端时（被 `2>` 重定向、CI、编辑器任务）这两行干脆不打；
* 想连终端上也保持安静，才写 `$mode: "silent"`。

```bash
byk build
# > @.build /project
#
# > pnpm build
#
# ...（pnpm 的输出）

# "$mode": "silent" 时
byk build
# ...（只剩 pnpm 的输出）
```

`interactive` 适合有副作用的命令：

```bash
byk deploy
# ~ deploy --env {env} --tag {version}
#   env: staging
#   version: v2.0
# ~ deploy --env staging --tag v2.0     ← 绿色粗体
#    Press Enter to execute...
```

`$mode` 支持三级继承：文件级 → 分组级 → 别名级，越靠近别名优先级越高。

<Tabs>
  <Tab label="别名级指定">
    ```json
    {
      "deploy": {
        "$cmd": "deploy --env {env} --tag {version}",
        "$mode": "interactive"
      }
    }
    ```
  </Tab>

  <Tab label="分组级继承">
    ```json
    {
      "danger": {
        "$mode": "interactive",
        "drop": "rm -rf {path}",
        "backup": {
          "$cmd": "rsync -a ./ {dest}",
          "$mode": "silent"
        }
      }
    }
    ```

    `drop` 继承 `danger` 的 `interactive`；`backup` 写一个 `silent` 就够，不需要再把交互关一次。
  </Tab>

  <Tab label="文件级继承">
    ```json
    {
      "$mode": "silent",
      "build": "pnpm build",
      "deploy": {
        "$cmd": "deploy --env {env}",
        "$mode": "interactive"
      }
    }
    ```

    整个文件安静，只有 `deploy` 需要确认。
  </Tab>
</Tabs>

:::note
交互和静默是互斥的两种形态：交互必须让用户看清要确认什么，所以 `silent` 只是让 byk 闭嘴，
不会跳过任何确认步骤——需要确认就写 `interactive`。
:::

### 递归保护

`$cmd` 是任意 shell 字符串，它完全可以再调用 byk —— 包括解析回自己。把 `add` 的 `$cmd` 写成
`byk add`，每一层都会再展开同一个别名；每层都是独立进程，没有栈溢出这种天然上限，
只有进程数一路往上涨，直到机器吃不下为止。

byk 为此给调用链留了标记：执行别名前把 `文件.key` 压进环境变量 `BYK_ALIAS_STACK`
（逗号分隔）交给子进程。下一层发现自己已经在链路上，就报错退出：

```text
Error: alias recursion detected: @dev.build -> @dev.release -> @dev.build
```

报的是**完整链路**而不只是首尾两个名字，因为「谁绕回来的」才是要定位的东西。
链路超过 32 层同样拦住：这一层兜底是给标记被清空的场景准备的（`env -i byk build`、
外部包装器），标记传不下去，只能靠深度止损。

刻意自调用（`FOO=1 byk build`、`sudo byk serve`）需要显式放行，两种写法等价：

```json
{
  "build": {
    "$cmd": "FOO=1 byk build",
    "$recursive": true
  }
}
```

```bash
BYK_ALLOW_RECURSION=1 byk build   # 临时全局放行
```

放行只取消「同一别名重入」这一项检查，深度上限照样生效。

:::note
`$recursive` 只对当前别名生效、不继承。`$mode: "silent"` 也压不住这条错误——
它本来就是用来说明「命令为什么卡住」的。
:::

### 描述文本

`$description` 替代帮助页里默认显示的命令文本，仅对当前别名生效、不继承。

```json
{
  "更新版本号": {
    "$mode": "interactive",
    "$cmd": "cz bump {version}",
    "$description": "交互式更新版本号"
  }
}
```

```text title="byk -h 片段"
Aliases:
  发布.更新版本号    交互式更新版本号
```

未设置时显示命令本身：

```text
Aliases:
  发布.更新版本号    cz bump {version}
```

只有在没有描述时，解析后的 `$cwd` 才会以括号追加在命令后面；有描述时只保留这一行摘要，不再显示工作目录。

### PATH 目录

`$paths` 在执行别名前把目录前置到 `PATH`，让别名可以直接调用这些目录下的可执行文件。

**仅支持文件级**，所有子别名自动继承；写在分组里会被忽略。

```json title="run.byk.json"
{
  "$paths": ["./scripts", "~/tools/bin"],
  "deploy": "deploy.sh",
  "check": "lint.sh"
}
```

* 相对路径以配置文件所在目录为基准解析，`~` 会展开
* **不存在的目录静默跳过**，不会出现在子进程的 `PATH` 里
* 另外，别名运行时 byk 会自动把工作目录下的 `node_modules/.bin` 追加到 `PATH` 前面；声明了 `$deps.pip` / `$deps.npm` 时，依赖目录里的 venv bin / `node_modules/.bin` 也会一并前置——这些都不需要自己写进 `$paths`
* `$paths` 的顺序就是 `PATH` 里的优先级顺序，越靠前越优先

### 依赖

`$deps` 声明一个别名文件需要的东西——资产文件，以及可选的 pip 包与 npm 包——byk 负责把它们装到这个文件的专属目录：

| 文件 | 专属目录 |
|------|----------|
| 全局 `~/.byk/alias/hello.byk.json` | `~/.byk/deps/@@hello/` |
| 局部 `./hello.byk.json` | `./.byk/deps/@hello/` |

两种作用域同一套规则，只是根不同：全局的依赖留在 `~/.byk`，局部的依赖跟着项目走（删项目即删依赖，不占全局空间）。局部安装时会自动写一个 `.byk/deps/.gitignore`（内容 `*`），所以下载产物不会出现在 `git status` 里。

声明本身不触发任何网络行为，安装是显式动词：

```bash
byk @@tool..deps install      # 取回文件并安装声明的包
byk @@tool..deps status       # 声明、到位、缺失、过期
byk @@tool..deps uninstall    # 删除整个专属目录
byk @@tool..clone <source> -d # 或者在克隆时顺手装好
```

```json title="~/.byk/alias/tool.byk.json"
{
  "$deps": {
    "base": "https://example.com/releases/v1/",
    "files": [
      "tool-1.4.tar.gz",
      { "src": "cli-linux", "to": "bin", "exec": true },
      { "src": "../shared/config.json", "name": "tool.cfg", "to": "etc" },
      "https://cdn.example.com/elsewhere.bin"
    ],
    "pip": ["requests", "click>=8.0"],
    "npm": ["chalk", "@scope/pkg@^1.2"]
  },
  "$paths": ["${deps_dir}/bin"],
  "run": { "$cmd": "tool --version" }
}
```

| 规则 | 说明 |
|------|------|
| 字符串简写 | 等于 `{ "src": "..." }`，文件名从地址末段推导 |
| `base` | 相对 `src` 的解析基准，**目录**。落盘后必须是绝对地址：远程 clone 写绝对 http(s) URL，本地 clone 写本机绝对路径。**这个字段通常不用手写**，`..clone` 会替你写入。手写只认字面量——绝对 URL、绝对路径，或 clone 时会被解释的相对写法（`.`、`../`、`sub/dir`）；不支持变量 |
| `src` | 绝对 http(s) URL，或相对 `base` 的路径（`./x`、`../x`、`bin/tool`）；变量先展开再校验，所以可以写 `${url}` 这类以变量开头的地址。绝对地址交给系统 `curl`，本地路径直接复制，`curl` 缺失时报错并提示安装 |
| `to` | 相对专属目录的子目录（默认根），只认 `/` 分隔，拒绝 `..`、绝对路径与反斜杠 |
| `name` | 保存的文件名，覆盖 URL 推导值；与 `extract` 互斥 |
| `extract` | 按 tar 系压缩包解压（`tar.gz` / `tar.xz` / `tar.bz2` 自动检测），交给系统 `tar`；`to` 即解压目标目录，日志用 `(extract)` 标注。省略 `to` 表示解到专属目录根，此时**必须是唯一条目**（重装整目录替换）。归档条目路径越界直接拒绝安装。与 `exec` 互斥 |
| `exec` | 给下载的文件补可执行位（Windows 无此概念，忽略） |
| `pip` | Python 包规格（PEP 508，如 `requests`、`click>=8.0`）；装进专属目录里的 `.venv`，缺失时用 `python3`（Windows 为 `python`）创建，然后执行 `pip install`。venv 的 `bin` / `Scripts` 会前置到 `PATH`。需要 Python 3 |
| `npm` | npm 包规格（`chalk`、`commander@^12`、`@scope/pkg`）；装进专属目录的 `node_modules`，缺失时写一个最小 `package.json`（`byk-deps`、`private`）。`node_modules/.bin` 会前置到 `PATH`。需要 Node.js / npm |
| 同步（`files`） | 声明是期望状态：缺的装、变的重下、移除的删；已安装清单在 `.byk-deps.json`，没变的不重下 |
| 不越权 | 只删清单里记过、且声明里已移除的路径；目录里其他文件不动，只提示 |
| 确认 | install 不再二次确认：先打印每条文件 / pip / npm 动作，然后直接执行；`uninstall` 仍要确认 |
| 联动 | `..rename` 同步改名专属目录，`..destroy` 连带删除，`..link` 改指向时会提醒旧的依赖目录 |

**包与文件条目一起安装。** `$deps.pip` 与 `$deps.npm` 每次 `..deps install` 都会执行——由 pip / npm 自己判断是否最新——所以 `--force` 只影响文件条目。它们不记进 `.byk-deps.json`：从声明里删掉某个包不会卸载它，想清空整个目录用 `..deps uninstall`。`..deps status` 把每个包列为 `pip:<规格>` / `npm:<规格>`；pip 的 URL / VCS 直接引用显示为 `unknown`，因为本地拿不到包名来比对。`files` 可以省略，所以声明里可以只有包。

**`base` 是 clone 唯一会改写的字段。** 落盘的别名文件住在 `~/.byk/alias/`，它没有自己的位置信息，所以相对路径只有在 `..clone` 那一刻才能解释。写成什么形态取决于来源，而形态本身就决定了资产怎么取：

| clone 来源 | 落盘的 `base` | 资产怎么取 |
|---|---|---|
| 远程（URL、`-gh` / `-ge` / `-jd`） | 绝对 http(s) 目录 URL | `curl` 下载 |
| 本地（`@@name`、`@name`、路径） | 本机绝对目录路径 | 直接复制 |

两条路互不越界：**远程 clone 只会写出 URL 形态，所以从网上拿到的别名文件读不了本机文件**。这不是靠检查挡住的，而是它根本拿不到本地路径这种写法。

补 `base` 的规则两边一致，只是基准和产物不同：没写就按源文件所在目录补上，写了相对形态（`.`、`../`、`sub/dir`）就相对源文件解析，写了绝对地址（URL 或路径）就原样保留，只补结尾的 `/`。基准一律是**源文件**所在目录，不是落盘的目标目录——`files` 里的相对路径是作者照着源文档写的，`~/.byk/alias/` 旁边没有那些文件。

补写 `base` 会让 clone 重新序列化整份文档（键按字典序重排）。既没有 `$deps` 也没有 `$clone` 的文件不受影响，仍是字节级副本；`base` 已经等于将要写入的值时也不改写，重复 clone 不会产生 diff。**clone 不接受 `base` 里的变量。** clone 期没有变量表，`"base": "${CDN}"` 求不出值，猜一个写死只会把作者意图烧成假地址，见到它会直接失败并提示改源文件。（读取期更宽：`..deps i` 会先展开变量，所以手写的 `${CDN}` 只要展开成绝对地址仍然能装。这条限制只针对 clone，编辑器里的 schema 按 clone 的口径提示。）base 定位就是"程序写的字面量"：clone 冻结一次，之后谁读都一样。

本地 base 是不可移植的：它写的是这台机器上的绝对路径，换机器就失效。本地依赖的定位就是"本机开发工具"，别指望把它分享出去还能用。

Windows 上还有一条：`/sub` 这种没有盘符的根路径挂在"当前盘"上，换个工作目录就指向别处，所以只认相对路径和盘符开头的绝对路径（`C:/share/`），`/sub` 直接报错。

**本地条目按源文件的 mtime 判新旧**：源比装好的那份新就重装，所以改完本地产物再跑一次 `..deps i` 就生效（想无条件重来用 `--force`）。URL 条目没有这个概念——同一个地址就是同一份内容，`keep` 永远安全。源文件不存在时报错并给出路径，不会安静地报 up to date。

别名里用 `${deps_dir}` 引用专属目录。这个目录由 byk 托管：安装时按声明同步文件条目，别往里手放需要长期保存的东西。

`--check` 只校验这份声明本身（能不能解析、落点是否冲突、相对 `src` 有没有 `base`、包条目是否非空字符串）；缺哪条、旧没旧要看 `..deps status`。

`$var`、`$paths` 与 `$deps` 自身都会先经过变量替换，可以用 `${version}` 之类的自定义变量拼 URL。

链接文件的依赖：声明跟着目标文件走，安装位置跟链接文件的 key 走——全局链接落到 `~/.byk/deps/@@<链接文件名>/`，局部链接落到它所在项目的 `.byk/deps/@<链接文件名>/`。详见 [单链接](#单链接)。

### 变量

变量来自两处，合并成**一张表**，扫描期一次性替换完成。内置变量只有目录这一类，名字一律以 `_dir` 结尾、值都是绝对路径：

| 来源 | 说明 |
|------|------|
| 内置 | `${byk_dir}` → `~/.byk`（资源根，不是二进制目录）；`${work_dir}` → 调用 byk 时的目录（不受 `$cwd` 影响）；`${file_dir}` → 当前别名文件所在目录；`${deps_dir}` → 该文件的依赖目录，全局是 `~/.byk/deps/@@<文件名>`、局部是 `<文件所在目录>/.byk/deps/@<文件名>` |
| `$var` 声明 | 文件级自定义变量 |

同名时**文件声明覆盖内置**——显式写下的值，就是你预期的那个值。

语法统一为 `${name}`，`name` 为 `[A-Za-z_][A-Za-z0-9_]*`（与 shell 标识符一致）：

```json title="run.byk.json"
{
  "$var": {
    "BASE": "https://github.com/owner/repo/releases/download",
    "VER": {
      "darwin-arm64": "tool-mac",
      "linux-x86_64": "tool-linux"
    }
  },
  "fetch": "curl -fsSL ${BASE}/${VER} -o /tmp/tool",
  "log": "tail -f ${byk_dir}/logs/app.log"
}
```

| 规则 | 说明 |
|------|------|
| 语法 | `${name}`，花括号是定界符，必须写 |
| 裸 `$xx` | 不识别，原样交给 shell（`$HOME`、`$PATH` 照常由 shell 展开） |
| 作用域 | 文件级，替换 `$cmd` / `$cwd` / `$paths` 等所有字符串值；JSON key 不动 |
| 展开结果 | 内置变量都会展开为绝对路径，等价于你在配置里直接写绝对路径；因此 `${work_dir}` 可以直接放进 `$cwd` 覆盖继承值 |
| 覆盖 | `$var` 与内置同名时取 `$var` 的值 |
| 自引用 | `"byk_dir": "${byk_dir}/tools"` 等号右边取内置原值，结果为 `~/.byk/tools` |
| 转义 | `\${byk_dir}` 原样交给 shell，最终打印字面量 `${byk_dir}` |
| 平台映射 | 值可为平台映射（`linux-x86_64` / `linux-arm64` / `darwin-x86_64` / `darwin-arm64` / `windows-x64`），取当前平台的值 |
| 交叉引用 | 变量值之间可互相引用，与书写顺序无关，最多展开 8 轮 |
| 未定义 | `${XXX}` 原样保留；`args` 是参数占位符保留名，声明会被忽略 |
| 非法名 | 不符合标识符规则的名字被忽略，并在 stderr 提示 |

:::tip 为什么必须写花括号
裸 `$byk_dir` 没有结束符，`$byk_dirfoo` 到底是变量 `byk_dirfoo` 还是 `byk_dir` 接上 `foo`，无法判断。`${byk_dir}foo` 没有这个歧义——这也是它和 shell 写法一致的原因。
:::

**引号自己负责**：值里含空格时按 shell 规则自己包引号，byk 不会替你加。

```json title="run.byk.json"
{
  "log": "tail -f \"${byk_dir}/my logs/app.log\"",
  "where": "echo ${file_dir}"
}
```

三个目录别混淆：

| 变量 | 指向 |
|------|------|
| `${file_dir}` | 别名文件所在目录 |
| `${work_dir}` | 调用 byk 时的目录，不受任何 `$cwd` 继承影响 |
| `$cwd` / `$PWD` | 命令实际执行目录 |

不要用 shell 的 `$PWD` 找调用目录：byk 用 `$cwd` 作为子进程的工作目录启动 shell，`$PWD` 会被重置成 `$cwd`，永远拿不到调用时的目录；Windows 的 `%CD%` 同理。需要调用目录时用 `${work_dir}`。

### 调用示例

<Tabs>
  <Tab label="系统字段">
    ```json
    {
      "dev": "vite",

      "install": {
        "$cmd": "npm i",
        "$cwd": "/Users/me/project/web"
      },

      "deploy": {
        "$cmd": "deploy --env {env}",
        "$mode": "interactive"
      }
    }
    ```

    ```bash
    byk install          # 在 /Users/me/project/web 下运行 npm i
    ```
  </Tab>

  <Tab label="嵌套分组">
    ```json
    {
      "开发": {
        "测试": "pytest -q",
        "构建": {
          "$cmd": "pnpm run build",
          "前端": "pnpm run build:web",
          "后端": "python -m build"
        }
      },
      "清理": "find . -type d -name __pycache__ -exec rm -rf {} +"
    }
    ```

    ```bash
    byk 开发.测试          # pytest -q
    byk 开发.构建          # pnpm run build
    byk 开发.构建.前端     # pnpm run build:web
    byk 清理               # find ...
    ```
  </Tab>
</Tabs>

## 别名文件

byk 读取两个位置：**全局目录** `~/.byk/alias/` 与**当前工作目录**（不递归）。

### 文件命名规范

| 格式 | 示例 | 说明 |
|------|------|------|
| `[name].byk.json` | `run.byk.json` | 推荐形式，名字即文件 key |
| `.byk.json` | `.byk.json` | 匿名形式，key 为空串 |

:::warning
**合法字符**：字母、数字、`-`、`_`、中文。

**禁止字符**：`.`、`@`、`/`、空格。

非法命名的文件（如 `aaa.bbb.byk.json`）会被**静默跳过**，不报错。
:::

### 目录结构

```tree
# 全局
~/.byk/alias/
├── alias.byk.json
├── work.byk.json
└── .byk.json
```

```tree
# 当前目录
./
├── run.byk.json
├── release.byk.json
└── .byk.json
```

### 单链接

根是**只含一个路径的数组**时，这个文件是链接文件：指向另一个别名文件的指针：

```json title="~/.byk/alias/ops.byk.json"
["~/proj/web/run.byk.json"]
```

含义是「放弃自己的身份」：`@`/`@@` 前缀、key、默认优先级留在链接文件上，别名内容与一切声明都来自目标文件，相对路径也以**目标文件所在目录**为基准。所以同一份 bundle，直接扫描和通过链接，行为完全一致。

```json title="~/proj/web/run.byk.json"
{
  "$cwd": ".",
  "build": "node build.js",
  "deploy": "node deploy.js"
}
```

```bash
byk build           # 在 ~/proj/web 里执行 node build.js
byk @@ops.build     # 精确调用走链接的 key
```

| 规则 | 说明 |
|---|---|
| 只能一项 | 数组写多项时只用第一项，并在 stderr 提示 |
| 路径基准 | 相对**链接文件所在目录**解析，支持 `~` 和 `${...}` 变量 |
| 只允许一层 | 目标文件本身不能也是数组，否则报错并跳过该文件 |
| 身份 | key、`@`/`@@` 前缀、默认优先级来自链接；其余全部来自目标 |
| `$private` | 照常生效：目标写 `true` 会让链接一起退出合并命名空间，只剩精确调用 |
| 依赖 | 目标文件里的 `$deps` 照常可用，安装位置跟链接文件的 key 走：全局链接落到 `~/.byk/deps/@@<链接文件名>`，局部链接落到它所在项目的 `.byk/deps/@<链接文件名>` |

:::note
目标缺失、JSON 损坏、数组为空时，只跳过该文件，其他别名照常可用。
:::

### 优先级

所有参与合并的文件共享一个 key 空间，优先级高的覆盖低的。

#### 默认值

| 文件位置 | 默认优先级 |
|---------|-----------|
| 当前目录 `[name].byk.json` | 1 |
| 当前目录 `.byk.json` | 1（同级最后加载） |
| 全局 `[name].byk.json` | 0 |
| 全局 `.byk.json` | 0（同级最后加载） |

所以「就近优先」：项目里的文件自动覆盖全局同名别名，进目录就能 `byk <key>`，不用写任何声明。

同优先级文件按文件名字母序加载，匿名文件 `.byk.json` 排在同级最后，**后加载的覆盖先加载的**。所以同一目录里若 `a.byk.json` 与 `.byk.json` 都有 `build`，生效的是 `.byk.json` 那份。

:::note 在全局目录里运行
当 cwd 恰好是 `~/.byk/alias/` 时，那里的文件同时属于「当前目录」和「全局目录」。它会以两个身份被扫描（`@f` 与 `@@f` 都能精确调用），但**只按全局身份参与一次合并**，不会被合并两遍。
:::

#### 自定义顺序

需要压过同目录的其他文件时，才需要写数字：

```json title="任意 .byk.json"
{
  "$priority": 20,
  "build": "vite build"
}
```

`$priority` 只负责同名冲突时的排序；小于 0 的值按 0 处理。是否进入合并空间由 `$private` 决定。

:::note
`$priority` 是保留字段，不会被当成别名 key。不写时当前目录为 1、全局为 0。
:::

### 可见性

`$private: true` 让一段别名**不进入合并空间**，只能通过精确语法 `@文件.key` / `@@文件.key` 调用。

它和 `$cwd` / `$mode` 一样支持三级继承：文件级 → 分组级 → 别名级，越靠近别名优先级越高；子级写 `false` 可以重新暴露。

```json title="run.byk.json"
{
  "shared": "echo everyone-can-run-this",
  "scratch": {
    "$private": true,
    "deploy": "deploy --env {env}"
  }
}
```

`byk shared` 照常可用；`byk scratch.deploy` 找不到，只能 `byk @run.scratch.deploy`。

整个文件都不进合并空间时，把 `$private` 写在文件根：

```json title="local.byk.json"
{
  "$private": true,
  "deploy": "deploy --env {env}"
}
```

:::note
`$private` 只影响合并空间；精确调用始终可用，包括 private 分组里的别名。
:::

### 克隆

`$clone: false` 把一段别名标成"自己的"：`..clone` 永远不复制它。它只是复制期的标签，不影响合并空间、执行、补全或任何其他查找。

和 `$private` 一样支持三级继承：文件级 → 分组级 → 别名级，越靠近别名优先级越高；子级写 `true` 可以重新暴露。

```json title="run.byk.json"
{
  "$clone": false,
  "shared": { "$clone": true, "whoami": "whoami" },
  "deploy": "deploy --prod"
}
```

clone 这个文件只会得到 `shared.whoami`，`deploy` 被剔除。如果剔除后什么都不剩，`..clone` 会直接拒绝、不落盘。这个标记本身也不会出现在副本里。

`$private` 和 `$clone` 相互独立：既要避开合并空间、又要避开 clone 副本时，两个都写。

:::note
`$clone` 只约束 `byk ..clone`。`cp`、git、用其他方式拉取文件仍然能看到原始字节——它是声明式约定，不是加密。
:::

### 精确执行语法

| 语法 | 说明 |
|------|------|
| `byk @release.build` | 当前目录 `release.byk.json` 的 `build` |
| `byk @@release.build` | 全局 `~/.byk/alias/release.byk.json` 的 `build` |
| `byk @.build` | 当前目录匿名文件 `.byk.json` 的 `build` |
| `byk @@.build` | 全局匿名文件 `.byk.json` 的 `build` |

约定：

* 只做文件路由，不做 fallback
* 文件不存在 → `Alias file not found: @release`（全局报 `@@release`）
* 文件存在但无法加载 → `Alias file cannot be loaded: @release`，附原因并提示 `byk --check`
* 文件存在但 key 不存在 → `Alias key not found in file @release: build`
* 路径段以 `$` 开头 → `Not an alias (reserved $ field)`；`$` 字段是保留字段或自定义元数据，不是别名
* 以上都以退出码 1 结束

***

byk v0.8.2 · 本页可能落后于 HEAD，以 `byk __api__` 与 `byk -v` 为准。
