---
name: umeng-cli
description: 友盟命令行工具，支持投放巡检（查询投放进展、监控投放状态）、账号管理等操作。当用户需要查询友盟投放数据、检查投放进展、管理友盟账号时使用。
metadata:
  requires:
    bins: ["umeng-cli"]
  cliHelp: "umeng-cli --help"
  install: "npm install -g @umengfe/umeng-cli"
  homepage: "https://github.com/umeng/umeng-cli"
---

# umeng-cli Agent Skill

友盟命令行工具 - 让人类和 AI Agent 都能在终端中操作友盟平台

## 安装 Skill

本 Skill 仅包含 Agent 平台的描述文档，安装后 AI Agent 可以了解 umeng-cli 的能力和用法。

```bash
npx skills add umeng/umeng-cli -y -g
```

> Skill 安装后，还需要安装 CLI 工具本体才能执行命令。

## 安装 CLI 工具

CLI 工具是实际执行命令的二进制程序，需要单独安装。

```bash
# 方式一：通过 npm 安装（推荐，自动安装 Skill + CLI）
npm install -g @umengfe/umeng-cli

# 方式二：通过安装脚本（仅安装 CLI 二进制 + Skill）
curl -fsSL https://raw.githubusercontent.com/umeng/umeng-cli/main/scripts/install.sh | sh
```

安装完成后，运行 `umeng-cli --version` 验证是否安装成功。

## 前置条件

使用前需要先完成登录：

```bash
umeng-cli login
```

扫码登录后，凭证会加密存储在本地，后续命令自动使用。

## 核心能力

### 1. 投放巡检

查询投放进展、检查投放状态等。

```bash
umeng-cli umengcli-inspection query_delivery_progress '{}'
```

### 2. 账号管理

```bash
# 查看当前登录用户
umeng-cli whoami

# 列出所有已登录账号
umeng-cli account list

# 切换账号（交互式选择）
umeng-cli account switch

# 切换到指定账号
umeng-cli account switch user@example.com
```

### 3. 调用统计

上报 Skill 调用的 trace 数据，用于统计分析。

```bash
# 上报 trace（默认简洁输出）
umeng-cli trace '{"appkey":"xxx","skill_name":"umengcli-inspection"}'

# 打印完整的请求和响应详情
umeng-cli trace -v '{"appkey":"xxx","skill_name":"umengcli-inspection"}'
```

### 4. Skills 管理

```bash
# 列出所有已加载的 Skills
umeng-cli skills list

# 查看某个 Skill 的详细内容
umeng-cli skills show umengcli-inspection

# 查看 Skills 安装目录
umeng-cli skills location
```

## 使用规范

### 方式一：Skill 工具调用（面向人类）

```bash
umeng-cli <skill-name> <tool-name> '<json-args>'
```

- **skill-name**：Skill 名称（如 `umengcli-inspection`）
- **tool-name**：工具名称（如 `query_delivery_progress`）
- **json-args**：JSON 格式的参数（必须用单引号包裹）

### 方式二：通用 API 调用（面向 Agent，推荐）

```bash
umeng-cli call '<tool_schema_json>' '<args_json>'
```

直接传入完整的 tool schema JSON 和参数，无需预注册命令。适合 Agent 动态调用。

- **tool_schema_json**：完整的 ToolSchema JSON（必填），包含以下字段：
  - `name`：工具名称
  - `description`：工具描述
  - `inputSchema`：输入参数的 JSON Schema
  - `api`：API 配置，包含：
    - `method`：HTTP 方法（GET/POST/PUT/DELETE/PATCH）
    - `baseUrl`：API 基础 URL
    - `endpoint`：API 路径
    - `headers`：请求头（可选）
    - `bodyFormat`：请求体格式，`array` 或 `object`（默认 `object`）
    - `timeout`：超时时间（秒，默认 30）
    - `requireAuth`：是否需要鉴权（默认 `true`）
    - `authType`：鉴权方式，`cookie`（默认）/ `aksk` / `signature` / `none`
    - `pathParams`：路径参数列表（可选）
- **args_json**：JSON 格式的调用参数（可选，默认 `{}`）

**调用示例：**

```bash
umeng-cli call '{
  "name": "query_delivery_progress",
  "description": "查询投放进展",
  "inputSchema": {"type": "object", "properties": {}},
  "api": {
    "method": "POST",
    "baseUrl": "https://appwin.umeng.com",
    "endpoint": "/hsf/fagent/inspection/queryDeliveryProgress",
    "headers": {"content-type": "application/json", "accept": "application/json"},
    "timeout": 30,
    "requireAuth": true
  }
}' '{}'
```

### 错误处理

| 错误信息 | 解决方案 |
|---------|---------|
| `未登录，请先运行 'umeng-cli login' 进行登录` | 运行 `umeng-cli login` |
| `登录态已过期，请重新登录` | 运行 `umeng-cli login` 重新登录 |
| `接口返回 401 未授权` | 联系管理员申请权限 |

## 卸载

```bash
# 卸载 CLI 工具（二进制 + Skills + 配置）
umeng-cli uninstall

# 保留配置和凭证
umeng-cli uninstall --keep-config
```

## 更多信息

- GitHub: https://github.com/umeng/umeng-cli
