# 程序接口 `__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__ paths` | CLI 目录、工作目录与别名文件清单，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` 首行一致，集成方不必再解析版本文本。

```bash
byk __api__
```

```json title="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，并列出支持的三个：

```text
Unsupported shell: pwsh
  Supported: zsh, bash, fish
```

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

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

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

```bash
$ 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` 后补来源文件、命令后补该命令的选项。清单见[文件命令 - 补全](/zh/cli/file-commands.md#补全)。

它做的是一次只读扫描，扫描期对别名文件的告警（例如非法变量名）仍然走 stderr——stdout 上只有候选，补全脚本因此可以直接 `$(...)`。

## resolve `<key> [args...]`

解析一个别名但不执行：返回最终命令、工作目录、PATH 前缀和执行方式。键支持两种写法——合并空间里的名字（`dep`），或精确语法（`@run.build`、`@@ops.deploy`）。文件命令不是别名，`@文件..命令` 会被拒绝并以退出码 1 结束；路径段以 `$` 开头的保留字段或自定义元数据同样不是别名。

:::warning 不是 `file.key`
`run.build` 是**点号路径**，会在合并空间里当成分组名查找，通常找不到。文件 key 必须带前缀：`@run.build`。
:::

```bash
byk __api__ resolve @run.build --env staging
```

| 字段 | 说明 |
|------|------|
| `key` | 传入的键，原样回显 |
| `source` | 命中的文件 key，如 `@run` / `@@ops` |
| `sourcePath` | 该别名文件的绝对路径；仅少数无来源的场合为 `null` |
| `command` | 非交互别名：占位符已按参数解析的最终命令（参数已按 shell 规则引用，可直接交给 `sh -c`）；交互别名：**未解析的模板** |
| `cwd` | 执行时的工作目录（绝对路径） |
| `paths` | 实际前置到 `PATH` 的目录，见下 |
| `mode` | `normal` / `interactive` / `silent` |
| `interactive` | `mode == "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` 也会包含在内。文件里写了但目录不存在的条目不会出现。

```json title="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，给需要一次拿全的程序：

```json title="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"
  ]
}
```

| 字段 | 说明 |
|------|------|
| `root` | CLI 根目录，也就是别名里可用的 `${byk_dir}` |
| `alias` | 全局别名目录 |
| `workdir` | 进程工作目录，也就是本地别名文件的查找目录 |
| `aliasFiles` | 两处目录下的别名文件绝对路径：先全局后本地，各自按 key 排序；同一目录兼作两种作用域时只列一次；没有文件时为空数组。需要 key、scope 或所在目录时用 `file --list` |

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

### 取路径

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

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

名字写错时列出可选值，退出码 1：

```text
__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 解析成地址，不读文件，也不要求文件存在：

```bash
byk __api__ file @run
```

```json title="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` 不同，它保留两种作用域身份，因此同一目录兼作全局与本地时会出现两条。每项与单查的返回体同形。

```bash
byk __api__ file --list
```

```json title="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}`，没有声明同名变量时原样保留。

```json title="./config.json"
{
  "$var": {
    "TOOLS": "${byk_dir}/tools"
  },
  "deploy": "cd ${file_dir} && ${TOOLS}/deploy.sh"
}
```

```bash
byk __api__ expand ./config.json
```

```json title="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。

```bash
byk __api__ check
```

```json title="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[].level` | `error`（文件或别名不可用）或 `warning`（仍可用但可疑） |
| `items[].path` | 问题所属文件的绝对路径 |
| `items[].message` | 与人读报告里完全相同的文本 |

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

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

## 补全是怎么接上的

`install.sh` 会往 `~/.zshrc`（或 `~/.bashrc`）写一行：

```bash
# 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 失败

***

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