# miaoa CLI 安装与 skill 配置说明

> 面向 AI agent。请按顺序执行；遇到失败按文末「错误处理」停止并告知用户，不要自行猜测、换源或重试。
> 本文档可重复执行，已有安装会被覆盖更新。
> 本文档中的服务地址固定为 `https://miaoa.mininglamp.com`。

## 0. 强约束

- 只从 `https://miaoa.mininglamp.com/api/cli/` 下载 CLI、install.sh 和 skill.md，不要从其它地址下载。
- 不要自行编译 miaoa，也不要安装其它版本或其它平台的二进制。
- `install.sh` 报 `unsupported platform`：停止，并告知用户当前平台暂无二进制。
- HTTP 401：告知用户重新登录，不要自动重试。
- HTTP 403 / 404：停止并原样返回错误，不要创建占位资源、换接口或重试。
- 不要输出、写入文件或提交任何 token、验证码、Cookie。

## 1. 检查运行环境

```bash
uname -s
uname -m
command -v curl
command -v bash
```

判断：

- 需要 `bash` 和 `curl`。
- 支持：Linux x86_64、macOS ARM64、Windows x86_64。
- Windows 必须在 Git Bash / MSYS2 / Cygwin / WSL 中执行；原生 PowerShell / cmd 无法运行 install.sh，停止并告知用户切换环境。
- 其它 `uname` 组合：停止，告知用户当前平台暂无 miaoa CLI 二进制。

## 2. 安装 miaoa CLI

```bash
curl -fsSL https://miaoa.mininglamp.com/api/cli/install.sh \
  | bash -s -- --host https://miaoa.mininglamp.com
```

install.sh 会：

- 下载对应平台的二进制到 `$HOME/.local/bin/miaoa`（Windows 为 `miaoa.exe`）；
- 写入 `$HOME/.miaoa/config.json`，`base_url` 指向 `https://miaoa.mininglamp.com/api`。

> install.sh 只覆盖 `config.json`，不会清除 `~/.miaoa/credentials.json` 中的登录凭证。

安装完成后，从 install.sh 的输出中确认可执行文件路径，并设置：

```bash
MIAOA="$HOME/.local/bin/miaoa"
# Windows Git Bash / MSYS2 / Cygwin 下二进制为 miaoa.exe：
# MIAOA="$HOME/.local/bin/miaoa.exe"
"$MIAOA" --version
```

> agent 的每条命令可能运行在新的 shell 中，不要依赖 `source ~/.zshrc` / `~/.bashrc` 让 PATH 生效。
> 后续命令统一使用 `"$MIAOA"`；如果确认 PATH 已包含 `$HOME/.local/bin`，也可以直接用 `miaoa`。

## 3. 安装 skill

根据当前 agent 环境选择 skill 目录：

| 运行环境 | skill 文件路径 |
|---|---|
| OpenClaw | `$HOME/.openclaw/skills/miaoa-cli/SKILL.md` |
| Claude Code | `$HOME/.claude/skills/miaoa-cli/SKILL.md` |
| 其它 agent | 询问用户该 agent 的 skill 目录，不要臆造 |

```bash
SKILL_DIR="$HOME/.openclaw/skills/miaoa-cli"   # 按上表替换为实际目录
mkdir -p "$SKILL_DIR"
curl -fsSL https://miaoa.mininglamp.com/api/cli/skill.md -o "$SKILL_DIR/SKILL.md"
```

- 目标文件名必须是 `SKILL.md`（Linux 区分大小写）。
- 已存在时直接覆盖。
- 如果该 agent 需要重启或重新加载才能识别新 skill，完成后提醒用户。

## 4. 验证 CLI

```bash
"$MIAOA" --version
"$MIAOA" version check --json
"$MIAOA" auth status --json
```

- `--version` 能输出版本号，说明安装成功。
- `version check --json` 的 `upToDate` 为 `false` 时，执行 `"$MIAOA" version update --confirm`，然后重新执行第 3 步拉取 skill.md。
- `versionInfoAvailable` 为 `false` 时照常继续，不要重试。
- `auth status` 显示未登录是正常状态，继续下一步。

## 5. 登录

先向用户询问手机号，不要臆造或使用示例号码。用户提供后执行：

```bash
"$MIAOA" auth login --phone <用户手机号>
```

告知用户查收短信，并等待用户把验证码发给你。拿到验证码后执行：

```bash
"$MIAOA" auth login --phone <用户手机号> --code <验证码>
```

- 手机号不是中国大陆号码时，两条命令都加 `--country-code <国家码>`（默认 `+86`）。
- 验证码只用于本次登录，不要写入文件、日志或任何持久化位置。
- 如果 `auth status` 显示已登录，跳过本节。
- 401 或 token 失效：让用户重新登录，不要循环重试。
- 当前环境有浏览器且用户愿意时，也可以走设备流：

```bash
"$MIAOA" auth login --no-wait
# 用户打开返回的 verification_url 并确认后：
"$MIAOA" auth login --device-code <device_code>
```

## 6. 选择租户与项目

```bash
"$MIAOA" tenant list --json
```

让用户选择租户，然后执行：

```bash
"$MIAOA" tenant select <TENANT_ID>
```

用户暂不需要切换时可跳过；执行业务命令前再确认 `auth status` 中的 tenant / project 上下文。

## 7. 收尾

- 再次确认本地 `SKILL.md` 已是最新版本（如果第 4 步执行过 `version update`，必须重新拉取一次）。
- 向用户汇报：CLI 版本、登录状态、当前租户 / 项目。
- 后续操作严格按本地 `SKILL.md` 执行；每个会话开始先运行 `"$MIAOA" version check --json`。

## 8. 错误处理

| 症状 | 处理 |
|---|---|
| `unsupported platform` | 停止，告知用户当前平台暂无二进制 |
| 401 / token 失效 | 让用户重新登录，不自动重试 |
| 403 | 停止，原样返回错误 |
| 404 | 停止，原样返回错误，不创建占位资源 |
| 下载失败 | 停止并返回原始 curl 错误，不要换源 |
| `version update` 失败 | 不要循环重试，把原文告诉用户，继续使用当前版本 |
| skill 拉取失败 | 停止并返回原始错误，不要自己编写 skill 内容 |