docs: add INSTALL.md for AI Agent-driven installation

Author: XXPermanentXX

INSTALL.md

@@ -0,0 +1,111 @@
+# 阿里云百炼CLI 安装说明（供 AI Agent 阅读）
+
+本文档面向 **AI Agent**：按下列步骤为用户安装并校验 **阿里云百炼CLI**（npm 包名 `bailian-cli`，命令 `bl` / `bailian`）。用户通常通过 **npm 全局安装** 使用，**无需**访问本仓库源码。不要臆造版本号或路径；以用户环境为准。
+
+## 1. 安装前检查
+
+**原则**：先执行检查；若 **Node / 包管理器 / 网络** 任一不满足下文要求，Agent 应 **在本机终端内主动完成安装或配置**（例如升级 Node、切换镜像、配置 `npm` 代理等），再继续 `bailian-cli` 安装。仅在无权限或环境无法自动化时，再向用户说明原因并请其配合。
+
+1. **Node.js**  
+   - 要求 **≥ 22.12.0**，执行 `node -v` 确认。  
+   - 未安装或版本不足：由 Agent 自行安装或升级 Node。
+
+2. **npm**（**唯一**允许的包管理器）  
+   - 执行 `npm -v` 确认可用。  
+   - 未安装或不可用：由 Agent **安装或修复 npm**（不要改用 pnpm/yarn 装 `bailian-cli`），再执行 `npm install -g bailian-cli`。  
+   - 即使本机已安装 `pnpm`、`yarn` 等，**也仅用于其它项目**；装 `bailian-cli` 时仍必须用 `npm`。
+
+3. **网络**  
+   - 需能访问 npm registry（默认 **registry.npmjs.org**）。  
+   - 不可达：由 Agent 自行配置镜像或代理后重试。
+
+---
+
+## 2. 安装 CLI 与 Skills
+
+**仅允许以下命令**（不要用 `pnpm add -g`、`yarn global add` 等）。按顺序执行，上一步通过后再进行下一步。
+
+**2.1 安装 CLI**
+
+```bash
+npm install -g bailian-cli
+```
+
+安装成功后，应能在 PATH 中找到：
+
+- `bl`（短别名）
+- `bailian`（全名）
+
+**校验**（Agent 应执行并检查退出码与输出）：
+
+```bash
+bl --version
+which bl   # Windows 可用 where bl
+```
+
+若 `command not found`：检查全局 bin 是否在 PATH（`npm config get prefix`，其下 `bin` 目录应加入 PATH）。
+
+**2.2 安装 Skills**
+
+CLI 校验通过后，在本机终端执行：
+
+```bash
+npx skills add modelstudioai/skills --all -g
+```
+
+完整说明见 [百炼Skills](https://github.com/modelstudioai/skills)。安装成功后，用中文简要说明已安装的 skills 及用户可做什么。
+
+---
+
+## 3. 鉴权（安装后必做才能调 API）
+
+用户需具备阿里云百炼 **API Key**。
+
+- 获取入口：[百炼控制台 API Key](https://bailian.console.aliyun.com/cn-beijing/?tab=app#/api-key)
+
+### 推荐：由 Agent 引导用户输入后登录
+
+适用于对话式安装（Cursor、Claude 等）：
+
+1. 执行 `bl auth status --output json`，判断是否已配置。  
+2. 若未配置或后续 API 校验失败，**请用户粘贴 API Key**（可说明从上述控制台复制；勿要求用户发到公开渠道）。  
+3. 用户提供了 Key 之后，在**用户本机终端**执行（Agent 用终端工具跑，勿把 Key 写进回复正文）：`bl auth login --api-key <用户提供的_Key>`
+
+4. 登录成功后执行 `bl auth status --output json` 确认；汇报时只使用 masked 字段，**禁止**回显完整 Key。
+
+### 其他方式
+
+- **环境变量**（不落盘到配置文件）：在 shell 中配置 API Key 环境变量；变量名见 `bl auth status --help`，勿在对话中向用户解释底层命名。  
+- **写入配置文件**（持久化，与 `auth login` 落盘相同）：`bl config set --key api_key --value <key>`（`--key api-key` 亦可）。**不会**像 `bl auth login --api-key` 那样先校验 Key 是否可用；Agent 引导安装时仍**优先**用 `auth login`。  
+- **命令行临时传入**：需要 API Key 的 `bl` 子命令可在**当次**执行附加全局 `--api-key <key>`，仅本次生效、不落盘（例：`bl text chat --api-key sk-xxx --message "你好"`）。与上文持久化方式不是同一用途。  
+- **浏览器登录（控制台会话）**：`bl auth login --console`，用于 `app list`、`usage free` 等控制台能力；与 API Key 登录可并存，详见 `bl auth login --help`
+
+### Agent 安全约束
+
+- **禁止**把真实 API Key 写入仓库、日志、Skill、聊天记录的可公开部分。  
+- CI / 非交互环境：使用 `bl ... --non-interactive`；通过密钥管理或环境变量注入，勿在脚本中硬编码 Key。
+
+---
+
+## 4. 最小功能验证
+
+在鉴权配置完成后执行：
+
+```bash
+bl auth status --output json
+bl text chat --message "ping" --non-interactive --output json
+```
+
+若失败：根据 stderr / JSON 中的 `hint` 或 `message` 排查（网络、Key 无效、region 等）。全局 region：`--region cn|us|intl`，默认 `cn`。
+
+---
+
+## 5. 常见问题（Agent 排障清单）
+
+| 现象 | 可能原因 | 建议动作 |
+|------|----------|----------|
+| `bl: command not found` | 全局 bin 不在 PATH | 检查 `npm prefix -g` 与 PATH |
+| 安装报错 engines | Node 版本过低 | 升级到 ≥ 22.12 |
+| 401 / 鉴权失败 | 未 login 或 Key 无效 | 引导用户更新 Key 并 `bl auth login --api-key` |
+| 企业网络无法访问 npm | 代理 / 镜像 | 配置 registry 或代理后再装 |
+| 本机只有 pnpm、没有 npm | Agent 误用 pnpm 安装 | 先装/修好 **npm**，再用 `npm install -g bailian-cli`；勿用 pnpm |