lark-cli

# lark-cli 插件

飞书(Lark)机器人 CLI 集成插件，支持发送消息、**AI Agent 自动回复**、监听事件、管理多租户配置。

## 前置依赖

### 基础依赖

- [uv](https://docs.astral.sh/uv/) - Python 包管理器
- Python >= 3.10

插件包含完整的 lark-cli 源码，无需额外安装。

### AI Agent 额外依赖

使用 `lark-cli agent` 命令启动 AI Agent 功能需要以下额外条件：

1. **Claude Code CLI** - AI Agent 使用 `claude-agent-sdk` 与 Claude 交互
   - SDK 已自动包含在插件依赖中（无需手动安装）
   - SDK 内部会自动管理 Claude Code CLI 进程

2. **Anthropic API 密钥** - Claude Code 需要有效的 API 访问权限
   - 确保已完成 `claude` 命令的初始设置
   - 或设置 `ANTHROPIC_API_KEY` 环境变量

3. **飞书机器人配置** - 需要配置 `~/.lark_cli/config.yaml`
   - 参见下方「配置」章节

**验证方法**：
```bash
# 检查 Claude Code 是否可用
claude --version

# 检查飞书配置是否正确
lark-cli config show
```

## 功能

- **AI Agent 自动回复**（使用 Claude 自动回复飞书消息）
- 发送飞书消息（文本、富文本、卡片等）
- @ 人功能（支持 @某人 和 @所有人）
- 发送到群聊（支持通过群名称发送）
- 群聊管理（同步群列表、按名称查找）
- 回复消息
- 表情回复（给消息点赞、添加表情）
- 卡片消息模板（通知、告警、成功、任务、报告）
- 监听飞书事件（WebSocket）
- 管理多租户配置

## 安装

首先添加 marketplace：

```bash
claude plugin marketplace add https://github.com/vincentor/claude-code-plugins
```

然后安装插件：

```bash
claude plugin install lark-cli
```

> **注意**：如果遇到 marketplace 路径问题，也可以尝试：
> ```bash
> claude plugin marketplace add github:vincentor/claude-code-plugins
> ```

## 使用

安装后，可以通过以下方式使用：
- 对 Claude 说 "启动飞书 AI Agent"
- 对 Claude 说 "让机器人自动回复消息"
- 对 Claude 说 "发消息给xxx"
- 对 Claude 说 "@ 某人发消息"
- 对 Claude 说 "发送卡片消息"
- 对 Claude 说 "发消息到某某群"
- 对 Claude 说 "查看群列表"
- 对 Claude 说 "给消息点赞"
- 对 Claude 说 "监听飞书事件"
- 对 Claude 说 "查看飞书配置"
- 使用 `/lark` 命令直接调用

### AI Agent 自动回复

AI Agent 采用**双层 LLM 架构**，实现快速响应：

1. **快速 LLM**（如豆包 Flash）：意图路由和简单闲聊（~1-2s）
2. **Claude Code**：复杂任务执行（~10-30s）

```bash
# 启动 AI Agent（自动回复 @ 机器人的消息）
lark-cli agent

# 监听所有消息
lark-cli agent --filter all

# 仅监听私聊
lark-cli agent --filter p2p

# 禁用快速 LLM（仅使用 Claude Code）
lark-cli agent --no-fast-llm

# 启用群聊自主回复（根据话题相关性自动回复）
lark-cli agent --group-auto-reply

# 自定义 persona
lark-cli agent --persona "你是一个专业的技术助手"
```

**Agent 性能指标**：

| 场景 | 响应时间 | 说明 |
|------|---------|------|
| 简单闲聊 | ~1-2s | 由快速 LLM 直接回复 |
| 复杂任务 | ~10-30s | 由 Claude Code 执行 |

**快速 LLM 配置**：

需要在配置文件中添加 `fast_llm` 配置，并设置相应的 API Key 环境变量。参见下方「AI Agent 专用配置」章节。

### 常用命令示例

```bash
# 发送文本消息
lark-cli message send "消息内容"

# 发送到群聊（通过群名称，需要先 sync）
lark-cli chat sync                              # 同步群列表
lark-cli message send --chat "群名称" "消息内容"

# 发送到群聊（通过 chat_id）
lark-cli message send -r "oc_xxx" --receiver-type chat_id "消息内容"

# 发送消息并 @ 某人
lark-cli message send --at ou_xxx "请审核"

# 群聊中 @所有人
lark-cli message send --chat "群名称" --at-all "全体通知"

# 发送富文本消息
lark-cli message post --title "通知" "富文本内容"

# 发送卡片消息
lark-cli card template notify --title "通知" --content "内容" -o send

# 卡片消息 @ 某人
lark-cli card template alert --title "告警" --content "请处理" --at ou_xxx -o send

# 群聊管理
lark-cli chat sync     # 同步群列表到本地
lark-cli chat list     # 列出缓存的群聊
lark-cli chat find "关键词"  # 按名称搜索群聊

# 获取最近消息（用于获取 message_id）
lark-cli message list --chat "群名称" --limit 10  # 按群名称
lark-cli message list --chat oc_xxx --limit 5     # 按 chat_id
lark-cli message list --user ou_xxx --limit 5     # 私聊消息（需要先 listen）
lark-cli message list --user [email protected] --limit 5  # 私聊消息（通过邮箱）

# 私聊管理（需要先 listen 获取缓存）
lark-cli chat private       # 查看已缓存的私聊映射
lark-cli chat private-id ou_xxx  # 获取用户的私聊 chat_id
lark-cli chat private-id [email protected]  # 通过邮箱获取

# 表情回复
lark-cli message react om_xxx THUMBSUP   # 给消息点赞
lark-cli message reactions om_xxx        # 查看消息的表情回复
lark-cli message emoji-list              # 查看支持的表情类型

# 监听事件
lark-cli listen
```

## 配置

安装插件后，需要配置飞书机器人租户信息。配置文件位于 `~/.lark_cli/config.yaml`。

### 添加租户

```bash
# 使用命令添加租户
lark-cli config add-tenant my_bot \
  --app-id "cli_xxx" \
  --app-secret "your_app_secret" \
  --receiver-id "ou_xxx" \
  --description "我的飞书机器人"

# 设置为默认租户
lark-cli config set-default my_bot
```

或者手动创建配置文件 (`~/.lark_cli/config.yaml`)：

```yaml
cli:
  default_tenant: my_bot
  log_level: INFO

tenants:
  my_bot:
    name: my_bot
    app_id: "cli_xxx"
    app_secret: "your_app_secret"
    default_receiver_id: "ou_xxx"
    default_receiver_type: "open_id"
    description: "我的飞书机器人"
```

### 获取配置信息

1. 登录[飞书开放平台](https://open.feishu.cn/)
2. 创建或选择一个应用
3. 获取 App ID 和 App Secret
4. 在「权限管理」中开启相关权限：
   - `im:message` - 发送消息
   - `im:message.group_at_msg` - 群聊 @所有人
   - `im:message:send_as_bot` - 以机器人身份发送消息
   - `im:chat:readonly` - 获取群组信息（群列表功能）
   - `im:message.reactions:write` - 添加/删除表情回复
   - `contact:user.email:readonly` - 通过邮箱查询用户（可选）
5. 获取接收者 ID（用户 Open ID 或群聊 ID）

### AI Agent 专用配置

为 AI Agent 配置机器人个性和双层 LLM：

```yaml
tenants:
  my_bot:
    name: my_bot
    app_id: "cli_xxx"
    app_secret: "your_app_secret"
    default_receiver_id: "ou_xxx"
    description: "我的 AI 助手"

    # AI Agent 基础配置
    bot_name: "Kira"
    bot_identity: "你是 Kira，一个友好、专业的 AI 助手"
    bot_capabilities: "回答问题、编程辅助、文档编写、代码审查"
    persona: |
      - 用友好的语气回复
      - 回复要简洁但完整
      - 适当使用 emoji
    model: sonnet  # Claude 模型: haiku, sonnet, opus

    # 群聊自主回复（可选）
    group_auto_reply: false
```

### 快速 LLM 配置（可选但推荐）

快速 LLM 用于双层架构，可以显著提升简单对话的响应速度（~10s → ~1-2s）。

**不配置快速 LLM**：所有消息都由 Claude Code 处理（约 10 秒响应）

**配置快速 LLM 后**：
- 简单闲聊由快速 LLM 直接回复（约 1-2 秒）
- 复杂任务仍由 Claude Code 处理（约 10-30 秒）

#### 方式一：使用豆包（火山引擎 Ark）

1. 访问 [火山引擎控制台](https://console.volcengine.com/ark) 创建推理接入点
2. 设置环境变量：`export ARK_API_KEY=your_api_key`
3. 配置：

```yaml
    fast_llm:
      enabled: true
      provider: "ark"
      base_url: "https://ark.cn-beijing.volces.com/api/v3"
      model: "ep-your-endpoint-id"  # 推理接入点 ID
      api_key_env: "ARK_API_KEY"
```

#### 方式二：使用 OpenAI

```bash
export OPENAI_API_KEY=your_api_key
```

```yaml
    fast_llm:
      enabled: true
      provider: "openai"
      base_url: "https://api.openai.com/v1"
      model: "gpt-4o-mini"
      api_key_env: "OPENAI_API_KEY"
```

#### 方式三：使用 DeepSeek

```bash
export DEEPSEEK_API_KEY=your_api_key
```

```yaml
    fast_llm:
      enabled: true
      provider: "deepseek"
      base_url: "https://api.deepseek.com/v1"
      model: "deepseek-chat"
      api_key_env: "DEEPSEEK_API_KEY"
```

> **提示**：快速 LLM 是可选的。如果不配置，Agent 仍然可以正常工作，只是响应速度会稍慢。

## 群通知（group-notify）

`message group-notify` 命令用于让 Claude Code 在任务完成或需要用户输入时，自动发送结构化通知到飞书群聊并 @ 指定用户。

### 配置

在 `~/.lark_cli/config.yaml` 的租户配置中添加 `notification` 段：

```yaml
tenants:
  my_bot:
    name: my_bot
    app_id: "cli_xxx"
    app_secret: "your_app_secret"
    # ... 其他配置 ...

    notification:
      chat: "群聊名称"    # 目标群聊名称（需先 lark-cli chat sync）
      at: "张三"          # @ 的群成员姓名
```

### 手动使用

```bash
# 发送群通知（群聊和 @ 从 config.yaml 读取）
lark-cli message group-notify --title "标题" "正文内容"
```

### 配合 Claude Code Stop Hook 自动触发

通过 Claude Code 的 [Stop Hook](https://docs.anthropic.com/en/docs/claude-code/hooks) 机制，可以**强制** Claude 在每次停下来前发送通知，避免遗漏。

#### 1. 创建 Hook 脚本

将以下脚本保存到 `~/.claude/hooks/require-notification.sh`：

```bash
#!/bin/bash
# Stop hook: 强制 Claude 在停下来前发送飞书通知
# 检查 transcript 中是否已调用过 group-notify，没有则阻止停止

INPUT=$(cat)

# 防止死循环：如果已经因为 hook block 继续过一次，直接放行
STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
  exit 0
fi

# 从 transcript 检查是否已经发过通知
TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty')
if [ -n "$TRANSCRIPT" ] && [ -f "$TRANSCRIPT" ]; then
  if grep -qE 'lark-notify-group|group-notify' "$TRANSCRIPT" 2>/dev/null; then
    exit 0
  fi
fi

# 没发通知，阻止停止并提醒
jq -n '{
  "decision": "block",
  "reason": "停下来前必须调用 /lark-cli:lark-notify-group 发送群通知。它会自动读取配置并发到群聊。用法：/lark-cli:lark-notify-group 总结做了什么、为什么停下来"
}'
```

```bash
chmod +x ~/.claude/hooks/require-notification.sh
```

#### 2. 注册到 Claude Code settings

在 `~/.claude/settings.json` 的 `hooks.Stop` 数组中添加：

```json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/你的用户名/.claude/hooks/require-notification.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}
```

#### 3. 工作原理

```
Claude 完成任务想停下来
        │
        ▼
  Stop Hook 触发
        │
        ▼
  检查 transcript 中是否调用过 group-notify
        │
   ┌────┴────┐
   │ 已调用   │ 未调用
   │         │
   ▼         ▼
 放行     阻止停止，返回提醒
          Claude 自动调用
          /lark-cli:lark-notify-group
          然后再次尝试停止 → 放行
```

**防死循环机制**：如果 Claude 因 hook block 继续执行后再次触发 Stop，`stop_hook_active` 标志会被设为 `true`，hook 直接放行。

## 安全说明

- 配置文件 (`~/.lark_cli/config.yaml`) 包含敏感的 App Secret，请妥善保管
- 建议设置文件权限为 600：`chmod 600 ~/.lark_cli/config.yaml`
- 插件源码不包含任何私钥信息