|
1 | 1 | # 阿里云百炼CLI 安装说明（供 AI Agent 阅读） |
2 | 2 |
|
3 | | -本文档面向 **AI Agent**：按下列步骤为用户安装并校验 **阿里云百炼CLI**（npm 包名 `bailian-cli`，命令 `bl` / `bailian`）。用户通常通过 **npm 全局安装** 使用，**无需**访问本仓库源码。不要臆造版本号或路径；以用户环境为准。 |
| 3 | +本文档面向 **AI Agent**：按下列步骤为用户安装并校验 **阿里云百炼CLI**（命令 `bl` / `bailian`）。**优先**使用二进制一键安装（无需 Node）；若环境已有 Node / 需要 Command Pack，再用 npm。不要臆造版本号或路径；以用户环境为准。 |
4 | 4 |
|
5 | | -## 1. 安装前检查 |
| 5 | +## 1. 推荐：二进制安装（无需 Node） |
6 | 6 |
|
7 | | -**原则**：先执行检查；若 **Node / 包管理器 / 网络** 任一不满足下文要求，Agent 应 **在本机终端内主动完成安装或配置**（例如升级 Node、切换镜像、配置 `npm` 代理等），再继续 `bailian-cli` 安装。仅在无权限或环境无法自动化时，再向用户说明原因并请其配合。 |
8 | | - |
9 | | -1. **Node.js** |
10 | | - - 要求 **≥ 18.17.0**，执行 `node -v` 确认。 |
11 | | - - 未安装或版本不足：由 Agent 自行安装或升级 Node。 |
12 | | - |
13 | | -2. **npm**（**唯一**允许的包管理器） |
14 | | - - 执行 `npm -v` 确认可用。 |
15 | | - - 未安装或不可用：由 Agent **安装或修复 npm**（不要改用 pnpm/yarn 装 `bailian-cli`），再执行 `npm install -g bailian-cli`。 |
16 | | - - 即使本机已安装 `pnpm`、`yarn` 等，**也仅用于其它项目**；装 `bailian-cli` 时仍必须用 `npm`。 |
17 | | - |
18 | | -3. **网络** |
19 | | - - 需能访问 npm registry（默认 **registry.npmjs.org**）。 |
20 | | - - 不可达：由 Agent 自行配置镜像或代理后重试。 |
21 | | - |
22 | | ---- |
| 7 | +```bash |
| 8 | +curl -fsSL https://bailian-cli.oss-cn-hangzhou.aliyuncs.com/bailian-cli/install.sh | bash |
| 9 | +``` |
23 | 10 |
|
24 | | -## 2. 安装 CLI 与 Skills |
| 11 | +Windows PowerShell： |
25 | 12 |
|
26 | | -**仅允许以下命令**（不要用 `pnpm add -g`、`yarn global add` 等）。按顺序执行，上一步通过后再进行下一步。 |
| 13 | +```powershell |
| 14 | +irm https://bailian-cli.oss-cn-hangzhou.aliyuncs.com/bailian-cli/install.ps1 | iex |
| 15 | +``` |
27 | 16 |
|
28 | | -**2.1 安装 CLI** |
| 17 | +校验： |
29 | 18 |
|
30 | 19 | ```bash |
31 | | -npm install -g bailian-cli |
| 20 | +bl --version |
| 21 | +which bl # Windows: where.exe bl |
32 | 22 | ``` |
33 | 23 |
|
34 | | -安装成功后，应能在 PATH 中找到： |
| 24 | +若 `command not found`：把 `~/.local/bin`（Windows 为 `%LOCALAPPDATA%\bailian-cli\bin`）加入 PATH 后开新终端。 |
| 25 | + |
| 26 | +> CDN / GitHub Release 未就绪或下载失败时，回退到下方 npm 安装。 |
35 | 27 |
|
36 | | -- `bl`（短别名） |
37 | | -- `bailian`（全名） |
| 28 | +## 2. 备选：npm 安装（需要 Node.js >= 18.17） |
38 | 29 |
|
39 | | -**校验**（Agent 应执行并检查退出码与输出）： |
| 30 | +1. `node -v` 确认版本。 |
| 31 | +2. `npm -v` 确认可用（**仅允许 npm** 全局安装，不要用 pnpm/yarn）。 |
| 32 | +3. 执行： |
40 | 33 |
|
41 | 34 | ```bash |
42 | | -bl --version |
43 | | -which bl # Windows 可用 where bl |
| 35 | +npm install -g bailian-cli |
44 | 36 | ``` |
45 | 37 |
|
46 | | -若 `command not found`：检查全局 bin 是否在 PATH（`npm config get prefix`，其下 `bin` 目录应加入 PATH）。 |
| 38 | +4. 校验：`bl --version`。 |
47 | 39 |
|
48 | | -**2.2 安装 Skills** |
49 | | - |
50 | | -CLI 校验通过后，在本机终端执行： |
| 40 | +可选 skills（与 CLI 本体无关，按需）： |
51 | 41 |
|
52 | 42 | ```bash |
53 | 43 | npx skills add modelstudioai/cli --all -g |
54 | 44 | ``` |
55 | 45 |
|
56 | | -安装成功后，用中文简要说明已安装的 skills 及用户可做什么。 |
57 | | - |
58 | | ---- |
59 | | - |
60 | 46 | ## 3. 鉴权（安装后必做才能调 API） |
61 | 47 |
|
62 | 48 | ### 推荐：浏览器登录（控制台会话） |
63 | 49 |
|
64 | | -适用于本机交互式安装，无需用户手动复制 API Key： |
65 | | - |
66 | 50 | 1. 执行 `bl auth status --output json`，判断是否已配置。 |
67 | | -2. 若未配置，在**用户本机终端**执行 `bl auth login --console`；命令会拉起浏览器完成阿里云控制台登录授权。 |
| 51 | +2. 若未配置，在**用户本机终端**执行 `bl auth login --console`。 |
68 | 52 | 3. 登录成功后执行 `bl auth status --output json` 确认；汇报时只使用 masked 字段，**禁止**回显完整凭据。 |
69 | 53 |
|
70 | | -> 此方式同时打通 `app list`、`usage free` 等控制台能力，并自动配置 API Key 调用所需的鉴权信息。 |
71 | | -
|
72 | | -### 备选一：由 Agent 引导用户输入普通 API Key 后登录 |
73 | | - |
74 | | -适用于无法拉起浏览器的对话式安装（远程 SSH、CI 调试、纯终端环境等）： |
75 | | - |
76 | | -- 获取入口：[百炼控制台 API Key](https://bailian.console.aliyun.com/cn-beijing/?tab=app#/api-key) |
77 | | - |
78 | | -1. 执行 `bl auth status --output json`，判断是否已配置。 |
79 | | -2. 若未配置或后续 API 校验失败，**请用户粘贴 API Key**（可说明从上述控制台复制；勿要求用户发到公开渠道）。 |
80 | | -3. 用户提供了 Key 之后，在**用户本机终端**执行（Agent 用终端工具跑，勿把 Key 写进回复正文）：`bl auth login --api-key <用户提供的_Key>` |
81 | | -4. 登录成功后执行 `bl auth status --output json` 确认；汇报时只使用 masked 字段，**禁止**回显完整 Key。 |
82 | | - |
83 | | -### 备选二：使用 Token Plan API Key |
| 54 | +### 备选：API Key / Token Plan |
84 | 55 |
|
85 | | -- 获取入口：[Token Plan 订阅详情](https://bailian.console.aliyun.com/cn-beijing?tab=plan#/efm/subscription/overview) |
86 | | - |
87 | | -1. 请用户从订阅详情页获取或复制 Token Plan API Key，勿要求用户发到公开渠道。 |
88 | | -2. 在用户本机终端执行：`bl auth login --config token-plan --api-key <用户提供的_Key>`。 |
89 | | -3. `token-plan` Profile 已内置默认 Base URL；登录命令会先测试 Key，通过后才保存并激活该 Profile，无需另行配置或重复测试。 |
90 | | -4. 执行 `bl auth status --config token-plan --output json` 确认；汇报时只使用 masked 字段。 |
91 | | - |
92 | | -### 其他方式 |
93 | | - |
94 | | -- **环境变量**（不落盘到配置文件）：在 shell 中配置 API Key 环境变量；变量名见 `bl auth status --help`，勿在对话中向用户解释底层命名。 |
95 | | -- **写入配置文件**（持久化，与 `auth login` 落盘相同）：`bl config set --key api_key --value <key>`（`--key api-key` 亦可）。**不会**像 `bl auth login --api-key` 那样先校验 Key 是否可用；Agent 引导安装时仍**优先**用 `auth login`。 |
96 | | -- **命令行临时传入**：需要 API Key 的 `bl` 子命令可在**当次**执行附加全局 `--api-key <key>`，仅本次生效、不落盘（例：`bl text chat --api-key sk-xxx --message "你好"`）。与上文持久化方式不是同一用途。 |
| 56 | +- 普通 Key：`bl auth login --api-key <Key>` |
| 57 | +- Token Plan：`bl auth login --config token-plan --api-key <Key>` |
97 | 58 |
|
98 | 59 | ### Agent 安全约束 |
99 | 60 |
|
100 | 61 | - **禁止**把真实 API Key 写入仓库、日志、Skill、聊天记录的可公开部分。 |
101 | | -- CI / 非交互环境：使用 `bl ... --non-interactive`；通过密钥管理或环境变量注入，勿在脚本中硬编码 Key。 |
102 | | - |
103 | | ---- |
| 62 | +- CI / 非交互环境：使用 `bl ... --non-interactive`；通过密钥管理或环境变量注入。 |
104 | 63 |
|
105 | 64 | ## 4. 配置验证 |
106 | 65 |
|
107 | | -API Key 登录命令本身已经完成可用性测试，通过后只需确认配置状态： |
108 | | - |
109 | 66 | ```bash |
110 | 67 | bl auth status --output json |
111 | 68 | ``` |
112 | 69 |
|
113 | | -无需再执行重复的模型调用测试。若登录失败，根据 stderr / JSON 中的 `hint` 或 `message` 排查（网络、Key 无效、`base_url` 等）。DashScope 端点：使用 `--base-url` / `bl config set --key base_url` / `DASHSCOPE_BASE_URL`，默认中国大陆 `https://dashscope.aliyuncs.com`。 |
114 | | - |
115 | | ---- |
116 | | - |
117 | | -## 5. 常见问题（Agent 排障清单） |
| 70 | +## 5. 常见问题 |
118 | 71 |
|
119 | | -| 现象 | 可能原因 | 建议动作 | |
120 | | -| ----------------------- | -------------------- | --------------------------------------------------------------- | |
121 | | -| `bl: command not found` | 全局 bin 不在 PATH | 检查 `npm prefix -g` 与 PATH | |
122 | | -| 安装报错 engines | Node 版本过低 | 升级到 ≥ 18.17 | |
123 | | -| 401 / 鉴权失败 | 未 login 或 Key 无效 | 按 Key 类型重新执行普通或 Token Plan 登录命令 | |
124 | | -| 企业网络无法访问 npm | 代理 / 镜像 | 配置 registry 或代理后再装 | |
125 | | -| 本机只有 pnpm、没有 npm | Agent 误用 pnpm 安装 | 先装/修好 **npm**，再用 `npm install -g bailian-cli`；勿用 pnpm | |
| 72 | +| 现象 | 可能原因 | 建议动作 | |
| 73 | +| ----------------------- | ---------------------------- | -------------------------------------- | |
| 74 | +| `bl: command not found` | bin 不在 PATH | 检查 `~/.local/bin` 或 `npm prefix -g` | |
| 75 | +| curl 安装 404 | GitHub Release 资产未上传 | 改用 `npm install -g bailian-cli` | |
| 76 | +| `plugin` 需要 npm | 二进制安装无本机 npm | 安装 Node，或改用 npm 版 CLI | |
| 77 | +| 安装报错 engines | Node 版本过低（仅 npm 路径） | 升级到 ≥ 18.17 | |
0 commit comments