Lark Cli Setup

---
name: lark-cli-setup
version: 1.0.0
description: 飞书 lark-cli 的初始化配置、全局身份绑定与授权流程。
metadata:
  requires:
    bins:
    - lark-cli
title: 飞书账号授权
example: 帮助我绑定我的飞书自建应用，并扫码登录飞书个人账号以获取日程管理权限。
---
# 飞书 CLI 运营主管配置与授权技能

本技能提供在私有助理环境里初始化飞书连接的权威指导。由于本系统的飞书机器人与守护进程已经绑定到运营主管（ops-director-1）的沙箱沙盒中，配置会自动存放在运营主管的本地存储目录下（`storage/agents/ops-director-1/.lark-cli`）。请严格遵循以下流程引导用户完成授权。

## 1. 第一步：询问用户选择的授权模式
在进行任何操作前，你必须向用户展示并要求其选择以下两种授权模式之一：
- **模式 A：纯机器人模式 (bot-only) [推荐，安全免扫码]**
  - **说明**：AI 以自建飞书应用机器人的身份运行，无需扫码登录个人账号。适合只进行发送群消息、读取/修改指定多维表格等机器人操作。不能访问个人资源（日历、个人云文件等）。
- **模式 B：个人账号扫码登录模式 (user-default)**
  - **说明**：AI 将代入你的飞书个人身份，需要你使用手机飞书扫码授权。适合需要 AI 管理你个人的日历、阅读和修改你名下的云文档、发送个人消息等场景。

## 2. 第二步：检查并初始化应用凭证 (App ID/Secret)
无论是哪种模式，飞书 CLI 都必须首先绑定一个飞书自建应用的 App ID 和 App Secret 凭证。
如果 `lark-cli config show` 返回错误 subtype 为 `"not_configured"`，你必须执行以下操作：

1. **询问用户初始化方式**：先提示用户选择是“自动创建飞书应用（推荐）”还是“使用已有飞书应用”。
2. **根据用户选择执行初始化**：
   - 若用户选择自动创建，则执行“选项 1：自动创建新应用 (推荐)”；
   - 若用户选择使用已有应用，则执行“选项 2：手动绑定已有应用”。

> [!IMPORTANT]
> **绝对禁止运行** `lark-cli config bind`，且**完全无视**报错提示中关于 `config bind --help` 的建议。执行 bind 必定报错失败。切勿对其进行任何调查！
> 你必须在用户做出明确选择后，才可使用 `lark-cli config init` 配合 `--force-init` 进行配置初始化！

### 选项 1：自动创建新应用 (推荐)
如果你想自动在用户的企业下创建一个新的飞书自建应用：
1. **前台运行并设置短超时**：由于网页授权完成前进程不会主动退出，为了在不阻塞客户端的前提下获取授权信息，你必须使用**前台运行**模式，并明确指定 **`timeout: 8`**（8秒超时）来执行以下命令：
   ```bash
   lark-cli config init --new --force-init
   ```
   > [!NOTE]
   > 此命令在启动后的前 1-2 秒内会立即在 stdout 输出授权链接和 ASCII 二维码，随后因等待网页授权而挂起。在 8 秒后触发超时终止，终端工具会完整返回超时前已输出的内容（退出码为 124），这完全符合预期。
2. **提取 URL 和生成二维码**：从上述返回的输出内容中提取出包含 `https://open.feishu.cn/page/cli?user_code=...` 的授权链接，并生成对应的 QR 二维码图片：
   ```bash
   lark-cli auth qrcode "<captured_url>" --output ./lark-qr.png
   ```
   **必须立刻向用户展示该授权 URL，并使用图片语法 `![二维码](./lark-qr.png)` 直接展示生成的二维码图片**，提示用户在网页中打开或用飞书扫码确认授权。
3. **验证配置**：用户在浏览器中完成授权后，飞书云端即保存了凭证。你只需通过在终端运行 `lark-cli config show` 验证配置是否正确同步就绪即可。

### 选项 2：手动绑定已有应用
如果用户已有现成的飞书自建应用：
1. 告知用户需要在飞书开放平台获取该应用的 App ID 和 App Secret。
2. 运行初始化命令（非交互式配置）：
   ```bash
   lark-cli config init --force-init --app-id <USER_APP_ID> --brand feishu --lang zh
   ```
   并在提示输入 Secret 时，将 App Secret 传给 stdin（或者交互式输入）。

## 3. 第三步：根据用户选择执行授权
在完成第二步的应用凭证绑定后，根据第一步中用户选择的授权模式进行操作：

### 若选择模式 A (纯机器人模式 - bot-only)
- 无需执行任何额外登录操作，凭证绑定成功后即完成授权！

### 若选择模式 B (个人账号扫码登录模式 - user-default)
- **前台运行并设置短超时**：由于个人扫码登录在确认前不会退出，为了获取扫码二维码，你必须使用**前台运行**模式，并明确指定 **`timeout: 8`**（8秒超时）来执行以下命令：
  ```bash
  lark-cli auth login --recommend
  ```
  > [!NOTE]
  > 此命令在前 1-2 秒内会立即在 stdout 输出登录认证链接，随后挂起等待用户扫码。在 8 秒后触发超时终止并返回已输出的内容（退出码为 124），这完全符合预期。
- **提取 URL 和生成二维码**：从返回内容中提取出认证链接 `https://open.feishu.cn/page/cli?user_code=...`。
  然后生成 QR 二维码图片：
  ```bash
  lark-cli auth qrcode "<captured_url>" --output ./lark-login-qr.png
  ```
  **必须立刻向用户展示该认证 URL，并使用图片语法 `![登录二维码](./lark-login-qr.png)` 直接展示生成的登录二维码图片**，提示用户用手机飞书扫码登录。
- **验证登录状态**：用户扫码确认登录后，在终端运行以下验证命令：
  ```bash
  lark-cli config show
  ```
  确认输出中 `users` 字段已成功包含登录的个人账号信息即可。

## 4. 验证配置状态
最后，在终端运行以下命令验证配置与登录状态：
```bash
lark-cli config show
```
确认输出的 JSON 中 `appId` 已正确加载且 `users` 字段中包含了已登录的飞书用户。