@tedbrain/vlink

跨平台 vlink npm 安装包。包本身不包含 Rust 二进制，安装时会像 Claude Code / Codex 一样按当前平台下载对应的 vlink 二进制。推荐统一使用 npx 完成持久化安装 和 TedBrain 初始化：

npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install

该命令会识别平台和架构，始终安装与当前 npm 包版本一致的 vlink，配置用户 PATH，并启动 vlink setup tedbrain。如果 PATH 中已有原生 vlink，会优先更新该位置； 旧文件或目录不可写时，自动回退到用户安装目录（Unix 为 ~/.local/bin，Windows 为 %LOCALAPPDATA%\TedBrain\bin），保留原来的共享安装。显式设置 VLINK_INSTALL_DIR 时始终使用该目录，写入失败会报错，不会再改装到其他位置。

安装目录会优先加入当前安装进程的 PATH，补全和 setup 均使用新二进制的绝对路径。 默认目录还会写入 shell 配置或 Windows 用户 PATH；自定义 Unix 目录需要自行配置 永久 PATH。完成后请打开新终端，让 PATH 和 shell 命令缓存更新，再运行：

vlink --version

安装、更新或执行 vlink setup tedbrain 时，vlink 会根据当前 shell 自动配置 命令与子命令补全，不需要额外执行或 source 补全脚本。自动配置支持 Bash、Zsh、 Fish 和 PowerShell；可用 vlink completion -h 查看手动生成或重新安装选项。

Windows 会在 vlink.exe 旁同时生成 vlink.cmd。安装目录加入用户 PATH 后， 可在 PowerShell 或 cmd 中直接运行 vlink ...，也可显式使用 vlink.cmd ...。

也可以只把 npm 包作为临时 CLI 使用：

npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest --version

安装命令会输出安装目标、权限回退原因及 setup 状态；失败时输出错误并返回非零退出码。

需要排查安装过程时，加上 --verbose：

npx --registry=https://registry.npmmirror.com -y \
  @tedbrain/vlink@latest install --verbose

verbose 会从 npm 包的 JavaScript wrapper 开始输出 Node、包版本、平台选择、PATH 查找、权限检查、二进制缓存或下载、复制、补全和 setup 各阶段。也可以设置 VLINK_VERBOSE=1。日志不会打印完整环境变量、registry 凭据或下载 URL 的查询参数。

如果上面的命令连 [TedBrain:verbose] wrapper entered 都没有输出，使用 npm 的显式 package 形式，绕过 npx 的命令推断：

npm exec --registry=https://registry.npmmirror.com \
  --package=@tedbrain/vlink@latest -- \
  vlink install --verbose

若显式形式可以输出，问题发生在本机 npx 的参数路由或缓存阶段；若仍无 wrapper 输出，可再加 npm 自身的 --loglevel verbose 检查 npm 在执行包之前的行为。

手动配置 Agent 时可以只安装或更新 vlink，并跳过 TedBrain 配置向导：

npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install --no-setup

安装 Web 通道

用于网页接入、终端和协议命令调用时，执行：

npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install --web

该选项复用原生二进制下载、更新、安装路径、PATH 和补全配置，跳过 vlink setup tedbrain，随后使用安装后的二进制绝对路径依次执行：

vlink channel web install-protocol
vlink channel web start

协议注册或服务启动失败时，安装命令返回非零退出码。 --web 可与 --verbose、--no-setup 一起使用；--no-setup 仅控制 TedBrain 向导，不会禁用 Web 初始化。 服务已运行时沿用 channel web start 的幂等复用行为，不强制重启现有终端。 该选项启动当前服务并注册 vlink:// 唤起入口，不配置开机自启动。

下载地址

安装脚本优先从 Gitee Release 解析当前版本对应平台的附件并下载；Gitee 不可用、 release 不存在或校验失败时，自动回退到 d01 下载服务器：

优先: https://gitee.com/ted-team/tedbrain 的 release attachment
回退: http://49.232.144.199/downloads/oss/vlink/<version>/vlink-<platform>

下载器遵循标准代理环境变量，同时支持大写和小写形式：

HTTP_PROXY=http://proxy.example:8080
HTTPS_PROXY=http://proxy.example:8080
NO_PROXY=localhost,127.0.0.1,.internal.example

也支持 http_proxy、https_proxy、no_proxy、ALL_PROXY，以及 npm 注入的 npm_config_proxy、npm_config_https_proxy 和 npm_config_noproxy。小写变量与 大写变量同时存在时优先使用小写。HTTPS 请求通过代理的 CONNECT 隧道传输；每次 重定向都会根据目标地址重新应用代理和 NO_PROXY。verbose 日志仅显示脱敏后的 代理主机，不显示代理用户名、密码或下载 URL 查询参数。

可用环境变量覆盖：

# 跳过 Gitee，直接使用 d01/自定义下载源
VLINK_SKIP_GITEE=1 npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install

# d01 回退源改用开发通道
VLINK_DOWNLOAD_CHANNEL=oss-dev npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install

# 自定义回退下载根路径（会自动拼接 <channel>/vlink/<version>/vlink-<platform>）
VLINK_DOWNLOAD_BASE=https://internal.example/downloads npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install

# 自定义回退下载目录（会自动拼接 vlink-<platform>）
VLINK_DOWNLOAD_URL=https://internal.example/vlink npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install

# 指定不同版本（同时影响 Gitee release tag 与 d01 回退路径）
VLINK_VERSION=0.1.21 npx --registry=https://registry.npmmirror.com -y @tedbrain/vlink@latest install

平台映射

| npm platform/arch | 下载文件 | | --- | --- | | linux/x64, glibc >= 2.17 | vlink-linux-x86_64-glibc2.17 | | linux/x64 | vlink-linux-x86_64 | | linux/arm64 | vlink-linux-aarch64 | | darwin/x64 | vlink-macos-x86_64 | | darwin/arm64 | vlink-macos-aarch64 | | win32/x64 | vlink-windows-x86_64.exe | | win32/arm64 | vlink-windows-aarch64.exe |

二进制存放位置

• 优先写入 npm 包目录 vendor/vlink（或 vlink.exe）。
• 如果包目录不可写，则回退到 ~/.cache/vlink/<version>/。
• 也可以直接指定 VLINK_BINARY_PATH 指向一个已存在的 vlink 二进制。

安装脚本会校验 SHA-256（与 dist/*.manifest 一致），并执行一次 vlink -V 验证可运行。

发布

cd biz/eda/packages/vlink/npm
./scripts/publish.sh --dry-run
./scripts/publish.sh

发布脚本会从 Cargo.toml 读取 version，动态生成 package.json，再以 public 访问级别执行 npm pack/npm publish；仓库不维护静态 package.json。