# lark-cli 使用指南

## 安装

环境要求：Node.js >= 16，npm 或 yarn。

先检查是否已安装：

```bash
lark-cli --version
```

- 如果输出版本号 → **已安装，跳过安装步骤**，直接进入 Preflight
- 如果 command not found → 执行安装：

```bash
npm install -g @larksuite/cli
npx skills add larksuite/cli -y -g
```

## Preflight（每次操作前必须检查）

### 1. 检查应用配置

```bash
lark-cli config show
```

如果报错或无 appId，先通过 Gateway 接口获取飞书应用凭证，然后执行初始化：

```bash
# 获取飞书应用凭证（PIE_TOKEN 和 PIE_BASE_URL 由 PieBox 自动注入）
CREDS=$(curl -s -H "Authorization: Bearer $PIE_TOKEN" "$PIE_BASE_URL/api/feishu/credentials")
APP_ID=$(echo "$CREDS" | jq -r '.app_id')
APP_SECRET=$(echo "$CREDS" | jq -r '.app_secret')

# 初始化 lark-cli 配置
echo "$APP_SECRET" | lark-cli config init --app-id "$APP_ID" --app-secret-stdin
```

### 2. 检查用户登录状态

```bash
lark-cli auth status
```

如果未登录或 token 已过期，**一次性全量授权**：

```bash
lark-cli auth login --domain all
```

使用 background 方式执行，从输出中提取授权链接发给用户。用户浏览器确认一次后，后台已开通的所有用户权限全部授权完成，后续任何操作都不需要再次授权。

### 3. 确认就绪后开始操作

配置和登录都就绪后，直接执行用户请求的操作。

## 认证

默认使用 user 身份（`--as user`），通过 `lark-cli auth login` 授权后访问用户资源。bot 身份（`--as bot`）仅用于应用级操作，无需 `auth login`。

### Agent 代理认证

检测到未登录时，**必须使用 `--domain all` 一次性全量授权**：

```bash
# 正确
lark-cli auth login --domain all

# 错误：不完整，后续可能再弹授权
# lark-cli auth login --recommend

# 错误：按域分次授权
# lark-cli auth login --domain contact
```

### Token 生命周期

- `user_access_token` 有效期约 **2 小时**
- 含 `offline_access` 后，CLI 获得 `refresh_token`（约 **7 天**）
- CLI 在 token 过期时**自动续期**，用户无感知
- refresh_token 过期（7 天未使用）才需重新 `auth login`

错误响应中包含：`permission_violations`（缺失 scope）、`console_url`（后台链接）、`hint`（修复命令）。

补授权：`lark-cli auth login --scope "<missing_scope>"`

## 命令体系

### 1. Shortcuts（推荐优先）

`+` 前缀，带智能默认值：

```bash
lark-cli calendar +agenda
lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
lark-cli doc +create --title "周报" --markdown "# 进展\n- 完成功能 X"
lark-cli contact +search-user --query "张三"
```

### 2. API Commands（原生 API）

调用前**必须先查 schema**：

```bash
lark-cli schema calendar.events.instance_view
lark-cli calendar events instance_view --params '{"calendar_id":"primary","start_time":"1700000000","end_time":"1700086400"}'
```

### 3. Raw API（任意端点）

覆盖 2500+ 飞书开放平台 API：

```bash
lark-cli api GET /open-apis/calendar/v4/calendars
lark-cli api POST /open-apis/im/v1/messages \
  --params '{"receive_id_type":"chat_id"}' \
  --data '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"Hello\"}"}'
```

## 核心能力

| 业务域 | 核心能力 |
|--------|---------|
| 消息与群组 | 搜索消息和群聊、发送消息、回复话题、管理群聊成员 |
| 云文档 | 创建文档、读取内容、更新正文、评论协作 |
| 云空间 | 上传下载文件、管理权限 |
| 电子表格 | 创建表格、读写单元格、批量更新 |
| 多维表格 | 管理数据表、字段、记录、视图、仪表盘 |
| 日历 | 查询日程、创建会议、查询忙闲、预定会议室 |
| 视频会议 | 搜索会议、获取纪要和逐字稿 |
| 邮箱 | 搜索、读取、起草、发送、回复邮件 |
| 任务 | 创建任务、更新状态、管理清单 |
| 知识库 | 查询空间、管理节点和文档层级 |
| 通讯录 | 查询用户、搜索同事、查看部门 |
| 幻灯片 | 创建演示文稿、读取内容 |
| 审批 | 查询任务、同意/拒绝/转交 |

## 通用选项

| Flag | 说明 |
|------|------|
| `--format json` | JSON 输出（默认） |
| `--format pretty` | 人类可读格式 |
| `--format table` | 表格输出 |
| `--as user` | 强制用户身份 |
| `--as bot` | 强制应用身份 |
| `--dry-run` | 预览请求，不实际执行 |
| `--page-all` | 自动翻页获取所有结果 |

## 命令探索

不确定用什么命令或参数时，用以下方式自助查询：

- **查看所有可用服务**：`lark-cli --help`
- **查看某个服务的可用命令**：`lark-cli <service> --help`（如 `lark-cli im --help`）
- **查看 API 参数结构**：`lark-cli schema <service>.<resource>.<method>`（调用原生 API 前**必须先查**，不要猜测字段格式）

```bash
lark-cli --help                                 # 所有服务总览
lark-cli im --help                              # im 域的所有命令
lark-cli schema calendar.events.instance_view   # 查看接口参数、请求体、响应结构
```

## 更新检查

命令执行后如果输出包含 `_notice.update`，完成当前请求后主动提议更新：

```bash
npm update -g @larksuite/cli && npx skills add larksuite/cli -g -y
```

## 安全规则

- **禁止输出密钥**（appSecret、accessToken）到终端明文
- **写入/删除操作前必须确认用户意图**
- 用 `--dry-run` 预览危险请求
- **消息发送**：发送前必须确认收件人和内容