#插件系统

byk 通过隔离的 Python 虚拟环境运行插件，不污染系统全局的 pip 包。插件基于 Python 模块或脚本执行，安装后即可作为一级命令使用。

#工作原理

插件系统依赖 ~/.byk/venv/ 下的 Python 虚拟环境。当你运行 byk add <user/repo[/key]> 时：

1. 从远程仓库（或本地文件）拉取插件协议 byk.json
2. 查找匹配的插件 key，按固定顺序执行操作块：pip-keep → pip → downloads → download-to-workdir → download-to-alias → command / commands → alias
3. 在隔离的 venv 中执行 pip install（pip-keep / pip 块）、统一下载/解压资源（downloads / download-to-workdir / download-to-alias 块）
4. 将命令路由直接合并到 ~/.byk/plugins/plugins.cmd.json，包追踪信息持久化到 ~/.byk/plugins/plugins.pkg.json

之后运行 byk <command> 时，byk 根据 type 字段区分执行方式：

• python-m：执行 python -m <entry>
• python：执行 python plugins/<plugin_key>/<entry>
• pip-bin：直接执行 venv/bin/<entry>
• bin：直接执行 plugins/<plugin_key>/<entry>（支持相对路径如 my-tool/bin/my-tool）

#初始化

首次使用插件功能时，venv 不存在则 byk 会自动创建，也可以手动初始化：

byk add <any-plugin>   # 首次 add 时自动创建 venv

#安装插件

#从远程仓库安装

任何 GitHub 仓库只需在根目录放一个 byk.json 即可作为 byk 插件源：

byk add user/repo           # 安装该仓库 byk.json 中的默认 key（$default 指定，或唯一 key）
byk add user/repo/my-key    # 安装指定 key

#指定分支

使用 @ 语法指定分支、tag 或 commit，与 jsDelivr 一致：

byk add user/repo@dev/hello   # 从 dev 分支的 byk.json 拉取
byk add user/repo@v1.0/my-key # 从 v1.0 tag 拉取

#CDN 加速

使用 --cdn 选项将 raw.githubusercontent.com 的 URL 自动转换为 jsDelivr CDN，加速下载：

byk add --cdn user/repo/hello   # 所有 raw.githubusercontent.com URL 加入 CDN 加速

#本地安装

byk add --file ./local.json my-key   # 使用本地 byk.json 文件

#运行插件

安装完成后，插件命令自动注册为 byk 的一级命令，直接使用即可：

byk <command> [args...]

所有命令行参数会原样透传给底层的 Python 模块。

byk lansend --target 192.168.1.10 "hello"
# 等价于 venv/bin/python -m byklansend.main --target 192.168.1.10 "hello"

#查看已安装插件

byk show plugins        # 列出所有已安装插件及其命令和脚本
byk show <command>      # 查询某个命令是否来自插件（含入口点、描述等）

#卸载插件

byk remove <plugin-key>   # 卸载指定插件

卸载流程：删除下载的脚本文件，清除 plugins.cmd.json 和 plugins.pkg.json 中该插件注册的所有命令。

#目录结构

插件相关的数据存储在以下位置：

#状态文件

插件系统使用两个 JSON 文件分别管理命令路由和包追踪，由 byk add / byk remove 自动维护。

#plugins.cmd.json（命令路由）

热路径文件，用于命令解析、路由和帮助渲染：

{
  "commands": {
    "lansend": {
      "type": "python-m",
      "entry": "byklansend.main",
      "desc": "Send messages via LAN"
    },
    "myscript": {
      "type": "python",
      "entry": "myscript/myscript.py",
      "desc": "My custom script"
    }
  }
}

#plugins.pkg.json（包追踪）

冷路径文件，记录每个插件的安装来源和注册命令，用于卸载和信息查询：

{
  "hello": {
    "source": "user/repo",
    "pip": ["byk-hello"],
    "commands": ["hello", "world"]
  },
  "my-tool": {
    "source": "user/tools",
    "pip": ["rich"],
    "assets": ["configs", "my-tool"],
    "commands": ["my-tool"]
  }
}

#编写自己的插件

如果你希望将自己的工具发布为 byk 插件，请参考 插件协议 byk.json。