docs: Modify the preferred installation method

2026-09-14 19:49:23 +08:00 · 2026-08-14 16:47:30 +08:00
parent 4ec0f6828b
commit 7eedc05b99
3 changed files with 66 additions and 40 deletions
@@ -1,8 +1,38 @@
 # 阿里云百炼CLI 安装说明（供 AI Agent 阅读）

-本文档面向 **AI Agent**：按下列步骤为用户安装并校验 **阿里云百炼CLI**（命令 `bl` / `bailian`）。**优先**使用二进制一键安装（无需 Node）；若环境已有 Node / 需要 Command Pack，再用 npm。不要臆造版本号或路径；以用户环境为准。
+本文档面向 **AI Agent**：按下列步骤为用户安装并校验 **阿里云百炼CLI**（命令 `bl` / `bailian`）。**优先**在已有 Node.js（**≥ 18.17.0**）的环境用 npm 安装；若没有可用 Node / npm，再走二进制一键安装。不要臆造版本号或路径；以用户环境为准。

-## 1. 推荐：二进制安装（无需 Node）
+## 1. 推荐：npm 安装（要求 **≥ 18.17.0**）
+
+1. `node -v` 确认版本 ≥ 18.17.0。
+2. `npm -v` 确认可用（**仅允许 npm** 全局安装，不要用 pnpm/yarn）。
+3. 执行：
+
+```bash
+npm install -g bailian-cli
+```
+
+4. 校验：`bl --version`。
+
+安装 skills（CLI 内置，无需 Git / npx skills）：
+
+```bash
+bl skill init
+```
+
+**Supported：** `bl skill init` 一次装齐 registry 中全部 `bailian-*`（含共享协议 `bailian-protocol`）。
+
+**Advanced / 按需子集：**
+
+```bash
+bl skill add --name bailian-protocol,bailian-gen
+```
+
+安装成功后，用中文简要说明已安装的 skills 及用户可做什么。
+
+## 2. 备选：二进制安装（无需 Node）
+
+当环境没有 Node / npm，或 Node 版本过低无法走 npm 时，使用二进制安装脚本。脚本安装 CLI 成功后会自动执行 `bl skill init`。

 ```bash
 curl -fsSL https://bailian.aliyun.com/cli/install.sh | bash
@@ -37,35 +67,9 @@ bl --version
 which bl   # Windows: where.exe bl
 ```

-> CDN / GitHub Release 未就绪或下载失败时，回退到下方 npm 安装。
+若自动 skill 安装失败，再手动执行：`bl skill init`。

-## 2. 备选：npm 安装（要求 **≥ 18.17.0**）
-
-1. `node -v` 确认版本。
-2. `npm -v` 确认可用（**仅允许 npm** 全局安装，不要用 pnpm/yarn）。
-3. 执行：
-
-```bash
-npm install -g bailian-cli
-```
-
-4. 校验：`bl --version`。
-
-安装 skills（CLI 内置，无需 Git / npx skills）：
-
-```bash
-bl skill init
-```
-
-**Supported：** `bl skill init` 一次装齐 registry 中全部 `bailian-*`（含共享协议 `bailian-protocol`）。
-
-**Advanced / 按需子集：**
-
-```bash
-bl skill add --name bailian-protocol,bailian-gen
-```
-
-安装成功后，用中文简要说明已安装的 skills 及用户可做什么。
+> CDN / GitHub Release 未就绪或下载失败时，若本机已有合格 Node，回退到上方 npm 安装。

 ---

@@ -11,13 +11,33 @@ inspect config keys. Day-to-day command routing lives in the business skills

 ## Install

-```bash
-# Recommended binary install (no Node), or: npm install -g bailian-cli
-curl -fsSL https://bailian.aliyun.com/cli/install.sh | bash
-# Install the full bailian-* skill family (includes bailian-protocol)
-bl skill init
+**prefer npm** (Node.js **≥ 18.17.0**); use the binary installer only when Node/npm is unavailable.

-# Advanced / subset (comma-separated names; include bailian-protocol when needed)
+### 1. Recommended: npm
+
+```bash
+# node -v ≥ 18.17.0; global install via npm only (do not use pnpm/yarn)
+npm install -g bailian-cli
+bl skill init
+```
+
+### 2. Fallback: binary (no Node)
+
+When there is no usable Node/npm, or Node is too old for the npm path:
+
+```bash
+curl -fsSL https://bailian.aliyun.com/cli/install.sh | bash
+# The script runs bl skill init after installing the CLI; if that fails, run it manually
+```
+
+Windows PowerShell: `irm https://bailian.aliyun.com/cli/install.ps1 | iex`
+
+### Skills
+
+- **Supported:** `bl skill init` (installs every `bailian-*`, including `bailian-protocol`)
+- **Advanced / subset** (include protocol when needed):
+
+```bash
 # bl skill add --name bailian-protocol,bailian-gen
 # bl skill add --name bailian-protocol,bailian-finetune
 # bl skill add --name bailian-protocol,bailian-managed-agent
@@ -35,13 +35,15 @@

 ## Missing `bl`

-If `bl --version` fails, install the CLI and skills:
+If `bl --version` fails, install the CLI and skills (same order as [setup.md → Install](setup.md#install) / root `INSTALL.md`: **npm first**):

 ```bash
-# Recommended — no Node required
-curl -fsSL https://bailian.aliyun.com/cli/install.sh | bash
-# Or: npm install -g bailian-cli
+# Recommended — Node.js ≥ 18.17.0; npm only (do not use pnpm/yarn)
+npm install -g bailian-cli
 bl skill init
+
+# Fallback — no usable Node/npm:
+# curl -fsSL https://bailian.aliyun.com/cli/install.sh | bash
 ```

 Do not install a single business skill alone — use `bl skill init` so `bailian-protocol` is present.