lark

飞书 CLI Skill

使用 lark-cli 工具与飞书机器人交互，支持多租户管理。

命令前缀

所有命令使用 uv run 执行：

cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli <command>

当前配置

• 配置文件: !cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli config path 2>/dev/null
• 默认租户: !cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli config get cli.default_tenant 2>/dev/null

群聊操作说明

直接发送即可，缓存过期或找不到时会自动同步：

# 直接发送消息到群（自动处理缓存和同步）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send --chat "群名称" "消息内容"

# 发送消息并 @ 人（通过姓名，推荐方式）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send --chat "群名称" --at "姓名" "消息内容"

# ⚠️ 群聊中 @ 人请直接用中文姓名，不要猜测邮箱前缀（很多人邮箱前缀和姓名拼音不一致）
# 邮箱方式仅在确切知道邮箱地址时使用

自动同步机制：

• 群列表缓存过期（默认 3 天）或找不到群时，自动从 API 同步
• @ 成员时，群成员缓存过期或找不到时，自动同步群成员
• 无需手动执行 chat sync 或 chat members --sync

@ 功能优先级：

1. 群聊中优先从群成员列表查找（通过姓名）
2. 如果找不到，自动同步群成员后重试
3. 如果是邮箱，先通过 API 解析，失败则用邮箱前缀匹配群成员姓名

命令参考

发送消息

# 发送文本消息（使用默认租户和接收者）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send "消息内容"

# 发送到指定用户（通过 open_id）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send -r "ou_xxx" "消息内容"

# 通过邮箱发送消息（自动解析为 open_id）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send -e "[email protected]" "消息内容"

# 发送到群聊
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send -r "oc_xxx" --receiver-type chat_id "消息内容"

# 使用指定租户发送
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send -t tenant_name "消息内容"

# 发送消息并 @ 某人（通过 open_id）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send --at ou_xxx "请查阅这份文档"

# 发送消息并 @ 某人（通过邮箱，仅在确切知道邮箱时使用）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send --at [email protected] "请审核"

# 在群聊中 @所有人
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send -r "oc_xxx" --receiver-type chat_id --at-all "全体会议通知"

# @ 多个人
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send --at ou_xxx --at ou_yyy "请两位审核"

# 群聊中 @ 某人（推荐用姓名）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send --chat "群名称" --at "张三" "请审核这份文档"

# 群聊中 @ 多人
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send --chat "群名称" --at "张三" --at "李四" "请两位审核"

发送富文本消息 (Post)

# 发送带标题的富文本消息
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message post --title "通知" "这是一条富文本消息"

# 富文本消息带 @ 功能
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message post --at ou_xxx "请审核这份文档"

# 富文本消息 @所有人（群聊）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message post -r "oc_xxx" --receiver-type chat_id --at-all "全体通知"

# 富文本消息在群聊中 @ 某人
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message post -r "oc_xxx" --receiver-type chat_id --at ou_xxx --title "审核通知" "请审核这份文档"

回复消息

# 简单回复
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message reply <message_id> "回复内容"

# 在话题中回复（话题群）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message reply --in-thread <message_id> "话题内回复"

# 回复并 @ 某人
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message reply --at ou_xxx <message_id> "回复并 @ 某人"

# 话题中回复并 @ 某人（用姓名）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message reply --in-thread --at "张三" <message_id> "回复内容"

查看消息

# 按群名称列出最近消息（缓存过期时自动同步）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message list --chat "群名称" --limit 10

# 按 chat_id 列出消息
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message list --chat oc_xxx --limit 20

# 列出话题中的消息
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message list --thread om_xxx --limit 10

# 列出与某用户的私聊消息（需要先 listen 获取 chat_id 缓存）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message list --user ou_xxx --limit 10

# 通过邮箱查看私聊消息
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message list --user [email protected] --limit 10

# 输出 JSON 格式（便于获取 message_id）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message list --chat "群名称" --json

# 获取特定消息详情
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message get <message_id>

提示： 获取消息列表后，可以使用返回的 message_id 进行回复（message reply）或表情回复（message react）。

私聊消息

要查看与某用户的私聊消息，需要先获取私聊的 chat_id：

# 1. 启动监听，让用户给机器人发一条消息
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli listen

# 2. 收到消息后会自动缓存私聊映射，可以查看已缓存的映射
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat private

# 3. 然后就可以用 --user 参数查看私聊消息
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message list --user ou_xxx --limit 10

# 或者直接用 chat_id
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message list --chat oc_xxx --limit 10

监听事件 (WebSocket)

# 监听所有租户事件
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli listen

# 监听指定租户
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli listen -t tenant_name

# 详细输出模式
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli listen -v

# 记录事件日志
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli listen --log --log-dir ./events

配置管理

# 查看配置
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli config show

# 查看配置（含密钥）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli config show --secrets

# JSON 格式输出
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli config show --json

# 添加新租户
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli config add-tenant <name> \
  --app-id "cli_xxx" \
  --app-secret "xxx" \
  --receiver-id "ou_xxx" \
  --description "描述"

# 更新租户
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli config update-tenant <name> --description "新描述"

# 删除租户
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli config remove-tenant <name>

# 设置默认租户
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli config set-default <name>

# 设置配置项
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli config set cli.log_level DEBUG

租户管理（快捷命令）

# 列出所有租户
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli tenant list

# 添加租户
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli tenant add <name> --app-id xxx --app-secret yyy

群聊管理

# 同步群列表到本地缓存
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat sync

# 列出缓存的群聊
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat list

# 刷新并列出群聊
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat list --refresh

# 模糊搜索群聊（推荐）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat search "关键词"

# 模糊搜索并只输出 ID（用于脚本）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat search "关键词" --id-only

# 按名称精确查找群聊
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat find "群名称"

# 获取群聊 ID（用于脚本，需要精确匹配）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat get-id "群名称"

# 通过群名称发送消息（缓存过期时自动同步）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send --chat "群名称" "消息内容"

# 通过群名称发送消息并 @所有人
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send --chat "群名称" --at-all "全体通知"

群成员管理

# 同步并显示群成员列表
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat members "群名称" --sync

# 使用缓存显示群成员（更快）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat members "群名称"

# 通过 chat_id 查看群成员
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat members oc_xxx --sync

# 在群成员中查找某人（返回第一个匹配）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat find-member "群名称" "姓名"

# 模糊搜索群成员（返回所有匹配，适合让用户选择）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat search-member "群名称" "关键词"

# 模糊搜索并获取邮箱（需要 contact:contact:readonly 权限）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat search-member "群名称" "关键词" --with-email

# 获取群成员 ID（用于脚本）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat find-member "群名称" "姓名" --id-only

# JSON 格式输出（适合 AI 解析）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli chat search-member "群名称" "关键词" --json

AI Agent 推荐流程：当需要 @ 某人但不确定准确姓名时：

1. 使用 chat search-member 模糊搜索
2. 如果有多个匹配，提示用户选择
3. 使用确定的姓名发送消息

话题群操作

话题群（Thread Group）是飞书的特殊群聊模式，所有消息都在话题下发送。

# 1. 发送消息到话题群（创建新话题）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message send --chat "话题群名称" "话题标题/内容"
# 返回 message_id (如 om_xxx)，这就是话题的根消息

# 2. 在话题中回复（使用 --in-thread）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message reply --in-thread <message_id> "话题内回复"

# 3. 在话题中回复并 @ 某人（用姓名）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message reply --in-thread --at "张三" <message_id> "请审阅"

# 4. 在话题中回复并 @ 多人
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message reply --in-thread --at "张三" --at "李四" <message_id> "请两位审阅"

# 5. 在话题中 @所有人
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message reply --in-thread --at-all <message_id> "全体注意"

# 6. 同时 @ 某人和 @所有人
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message reply --in-thread --at "张三" --at-all <message_id> "请注意"

话题群工作流程示例：

# Step 1: 同步群列表
lark-cli chat sync

# Step 2: 搜索话题群
lark-cli chat search "火山"

# Step 3: 发送消息创建话题
lark-cli message send --chat "火山方舟成本优化" "新话题：讨论本周成本报告"
# 输出: Message ID: om_xxx

# Step 4: 在话题中回复并 @ 相关人员
lark-cli message reply --in-thread --at "张三" om_xxx "请查看附件中的详细数据"

表情回复 (Reaction)

给消息添加表情回应，类似于点赞、确认等操作。

# 给消息点赞（添加 THUMBSUP 表情）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message react <message_id> THUMBSUP

# 添加笑脸表情
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message react <message_id> SMILE

# 添加 OK 表情
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message react <message_id> OK

# 添加 DONE 表情（表示已完成）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message react <message_id> DONE

# 添加爱心表情
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message react <message_id> LOVE

# 添加鼓掌表情
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message react <message_id> APPLAUSE

# 查看消息的表情回复
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message reactions <message_id>

# 按类型过滤表情回复
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message reactions <message_id> --type THUMBSUP

# JSON 格式输出
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message reactions <message_id> --json

# 删除表情回复（需要 reaction_id）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message unreact <message_id> <reaction_id>

# 查看常用表情类型列表
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli message emoji-list

常用 emoji_type：

类别	emoji_type
认可	THUMBSUP, OK, THANKS, DONE, MUSCLE, APPLAUSE, FISTBUMP, CLAP, CHECKMARK
表情	SMILE, LAUGH, BLUSH, WINK, LOL, PROUD, JOYFUL, WOW, YEAH
爱心	HEART, HEARTBROKEN, FINGERHEART, KISS, ROSE
庆祝	PARTY, FIRE, TROPHY, FIREWORKS, GIFT, CAKE
状态	TYPING, THINKING, WORKING, ONIT, ONESECOND
否定	CROSSMARK, THUMBSDOWN, MINUSONE, FACEPALM
其他	WAVE, COFFEE, BEER, LGTM, HUNDRED, PIN, ALARM

完整 emoji_type 参考（按类别）：

# 面部表情
SMILE, BLUSH, LAUGH, SMIRK, LOL, FACEPALM, WINK, PROUD, WITTY, SMART,
SCOWL, THINKING, SOB, CRY, INNOCENT, JOYFUL, WOW, TRICK, YEAH, EMBARRASSED,
KISS, SMOOCH, DROOL, OBSESSED, TEASE, SHOWOFF, SILENT, WAVE, WHAT, FROWN,
SHY, DIZZY, CHUCKLE, WAIL, CRAZY, WHIMPER, BLUBBER, WRONGED, HUSKY, SHHH,
SMUG, ANGRY, SHOCKED, TERROR, PETRIFIED, SKULL, SWEAT, SPEECHLESS, SLEEP,
DROWSY, YAWN, SICK, PUKE, BETRAYED

# 手势和动作
OK, THUMBSUP, THANKS, MUSCLE, FINGERHEART, APPLAUSE, FISTBUMP, JIAYI, DONE,
SALUTE, SHAKE, HIGHFIVE, CLAP, PRAISE, STRIVE, HUG, HEADSET, THUMBSDOWN

# 物品和符号
HEART, HEARTBROKEN, ROSE, FIRE, BOMB, PARTY, LIPS, BEER, CAKE, GIFT, TROPHY,
MUSIC, LGTM, LEMON, GET, CHECKMARK, CROSSMARK, MINUSONE, HUNDRED, PIN, ALARM,
LOUDSPEAKER, XMASTREE, SNOWMAN, XMASHAT, FIREWORKS, REDPACKET, POOP, COFFEE

# 状态和活动
WORKING, ONIT, ONESECOND, TYPING, VRHEADSET, YOUARETHEBEST, ROARFORYOU,
CALF, BEAR, BULL, RAINBOWPUKE, EATINGFOOD, SIGH

AI Agent 表情状态机推荐用法：

• OK - 收到消息确认
• TYPING - 正在处理/思考中
• DONE/CHECKMARK - 任务完成
• CROSSMARK - 处理失败/错误
• THUMBSUP - 同意/确认
• THINKING - 分析/思考
• FIRE - 紧急/重要
• PARTY - 庆祝/成功

使用说明

群聊操作流程

直接使用 --chat "群名称" 发送即可，系统自动处理缓存同步：

• 缓存有效（3 天内）：直接使用缓存数据发送
• 缓存过期或为空：自动同步后发送
• 可选：用 chat search "关键词" 手动确认群名

请求映射

当用户请求时：

1. "发消息给xxx" → 使用 message send 命令
2. "发个飞书消息" → 使用 message send 命令
3. "发消息给 [email protected]" → 使用 message send -e "[email protected]" 命令
4. "发卡片消息" → 使用 card template 或 card send 命令
5. "监听飞书事件" → 使用 listen 命令
6. "查看飞书配置" → 使用 config show 命令
7. "添加飞书机器人" → 使用 config add-tenant 命令
8. "切换飞书租户" → 使用 config set-default 命令
9. "@ 某人发消息" → 使用 message send --at 或 message post --at 命令
10. "在群里 @所有人" → 直接使用 --at-all 参数（自动同步群列表）
11. "发送到群聊" → 直接使用 --chat "群名称" 参数（自动同步群列表）
12. "查看群列表" → chat list（需要手动刷新用 --refresh）
13. "发消息到某某群" → 直接使用 --chat "群名称" 参数（自动同步群列表）
14. "发消息到群并 @ 某人" → 直接 message send --chat "群名称" --at "姓名" "消息"（自动同步，群聊中用中文姓名）
15. "回复消息" → 使用 message reply <message_id> 命令
16. "在话题中回复" → 使用 message reply --in-thread <message_id> 命令
17. "查找群 ID" → 使用 chat get-id "群名称" 或 chat search "关键词" 命令
18. "搜索群" → 使用 chat search "关键词" 命令（模糊搜索）
19. "话题群发消息" → 先 message send --chat "群名" 创建话题，再 message reply --in-thread 回复
20. "在话题里 @ 某人" → 使用 message reply --in-thread --at "姓名"
21. "给消息点赞" → 使用 message react <message_id> THUMBSUP
22. "表情回复" → 使用 message react <message_id> <EMOJI_TYPE>
23. "查看表情" → 使用 message reactions <message_id>
24. "查看表情类型" → 使用 message emoji-list
25. "获取最近消息" → 使用 message list --chat "群名称" --limit N
26. "查看群里的消息" → 使用 message list --chat "群名称"
27. "查看私聊消息" → 使用 message list --user ou_xxx 或 --user email（需要先 listen）
28. "查看私聊缓存" → 使用 chat private
29. "启动 AI Agent" → 使用 agent 命令启动自动回复机器人
30. "让机器人自动回复" → 使用 agent 命令
31. "启动聊天机器人" → 使用 agent 命令
32. "agent 监听所有消息" → 使用 agent --filter all
33. "agent 只回复私聊" → 使用 agent --filter p2p

$ARGUMENTS 包含用户的具体请求，解析后决定运行哪个命令。

接收者类型

• open_id: 用户的 Open ID (ou_xxx)
• user_id: 用户 ID
• union_id: Union ID
• chat_id: 群聊 ID (oc_xxx)
• email: 用户邮箱

消息类型

• text: 纯文本消息
• post: 富文本消息
• image: 图片消息
• file: 文件消息

发送卡片消息

卡片消息推荐使用以下两种方式发送：

方式1：使用预设模板（推荐）

# 通知卡片
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli card template notify \
  --title "标题" --content "内容" -o send [-e email]

# 告警卡片（level: info/warning/error/critical）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli card template alert \
  --title "告警" --content "消息" --level error -o send [-e email]

# 成功卡片
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli card template success \
  --title "成功" --content "操作成功" -o send [-e email]

# 任务卡片
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli card template task \
  --title "任务" --content "描述" --status "待处理" --assignee "张三" -o send [-e email]

# 报告卡片
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli card template report \
  --title "周报" --fields '{"完成": "10", "进行中": "5"}' -o send [-e email]

# 卡片中 @ 某人
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli card template notify \
  --title "审核通知" --content "请审核文档" --at ou_xxx -o send

# 卡片中 @所有人（群聊）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli card template alert \
  --title "紧急通知" --content "服务器故障" --at-all -o send -r oc_xxx

方式2：直接发送卡片 JSON

# 发送卡片（带校验）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli card send '<card_json>' [-e email]

# 从文件发送
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli card send -f card.json [-e email]

校验卡片 JSON

cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli card validate '<card_json>'

列出可用模板

cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli card list-templates

卡片 JSON 结构

{
  "config": {
    "wide_screen_mode": true,
    "enable_forward": true
  },
  "header": {
    "title": {
      "content": "卡片标题",
      "tag": "plain_text"
    },
    "template": "blue"
  },
  "elements": [
    // 卡片元素列表
  ]
}

结构说明

字段	必填	说明
config.wide_screen_mode	否	宽屏模式，推荐设为 true
config.enable_forward	否	允许转发，默认 true
header.title.content	是	标题文本
header.template	否	标题颜色
elements	是	卡片内容元素数组

标题颜色模板

可选值：blue、turquoise、green、yellow、orange、red、purple、grey、default

• 通知/信息 → blue
• 成功 → green
• 警告 → orange 或 yellow
• 错误/告警 → red
• 中性 → grey

卡片元素类型

1. 文本块 (div)

{
  "tag": "div",
  "text": {
    "content": "**粗体** 和 *斜体* 文本",
    "tag": "lark_md"
  }
}

2. 多列字段 (div + fields)

{
  "tag": "div",
  "fields": [
    {
      "is_short": true,
      "text": {"content": "**状态**\n已完成", "tag": "lark_md"}
    },
    {
      "is_short": true,
      "text": {"content": "**负责人**\n张三", "tag": "lark_md"}
    }
  ]
}

3. 分割线 (hr)

{"tag": "hr"}

4. 备注 (note)

{
  "tag": "note",
  "elements": [
    {"tag": "plain_text", "content": "这是备注文字"}
  ]
}

5. 按钮组 (action)

{
  "tag": "action",
  "actions": [
    {
      "tag": "button",
      "type": "primary",
      "text": {"content": "主要按钮", "tag": "plain_text"},
      "url": "https://example.com"
    },
    {
      "tag": "button",
      "type": "default",
      "text": {"content": "次要按钮", "tag": "plain_text"},
      "url": "https://example.com/cancel"
    }
  ],
  "layout": "bisected"
}

按钮属性：

• type: primary（蓝色主按钮）或 default（灰色次按钮）
• url: 点击跳转链接
• layout: bisected（并排）或 vertical（垂直）

Markdown 语法支持

在 "tag": "lark_md" 的文本中支持：

语法	效果
**文本**	粗体
*文本*	斜体
~~文本~~	删除线
[链接](url)	超链接
`代码`	行内代码
<at id=ou_xxx></at>	@用户
\n	换行

卡片限制

重要：请遵守以下限制，避免卡片显示异常

限制项	限制值	说明
卡片总大小	≤ 30KB	整个 JSON 字符串大小
标题长度	≤ 100 字符	header.title.content
单个文本块	≤ 2000 字符	div.text.content
elements 数量	≤ 50 个	单张卡片元素数量
按钮数量	≤ 5 个/组	单个 action 中的按钮
字段数量	≤ 8 个	单个 div.fields 中的字段
嵌套层级	≤ 3 层	元素嵌套深度

最佳实践：

• 卡片内容精简，突出重点信息
• 长文本分段，每段不超过 500 字符
• 使用 Markdown 格式化，提高可读性
• 按钮文字简短（2-6字），链接有效

完整示例

示例1：简单通知卡片

{
  "config": {"wide_screen_mode": true},
  "header": {
    "title": {"content": "✅ 任务完成", "tag": "plain_text"},
    "template": "green"
  },
  "elements": [
    {
      "tag": "div",
      "text": {"content": "您的构建任务已成功完成。", "tag": "lark_md"}
    }
  ]
}

示例2：带字段的信息卡片

{
  "config": {"wide_screen_mode": true},
  "header": {
    "title": {"content": "📊 部署报告", "tag": "plain_text"},
    "template": "blue"
  },
  "elements": [
    {
      "tag": "div",
      "fields": [
        {"is_short": true, "text": {"content": "**环境**\n生产环境", "tag": "lark_md"}},
        {"is_short": true, "text": {"content": "**版本**\nv1.2.3", "tag": "lark_md"}},
        {"is_short": true, "text": {"content": "**状态**\n成功", "tag": "lark_md"}},
        {"is_short": true, "text": {"content": "**耗时**\n2分30秒", "tag": "lark_md"}}
      ]
    },
    {"tag": "hr"},
    {
      "tag": "div",
      "text": {"content": "部署详情请查看 [Jenkins](https://jenkins.example.com/job/123)", "tag": "lark_md"}
    }
  ]
}

示例3：告警卡片（带按钮）

{
  "config": {"wide_screen_mode": true},
  "header": {
    "title": {"content": "⚠️ 服务告警", "tag": "plain_text"},
    "template": "red"
  },
  "elements": [
    {
      "tag": "div",
      "text": {"content": "**告警内容**\nCPU 使用率超过 90%，持续 5 分钟", "tag": "lark_md"}
    },
    {
      "tag": "div",
      "fields": [
        {"is_short": true, "text": {"content": "**服务**\napi-server", "tag": "lark_md"}},
        {"is_short": true, "text": {"content": "**级别**\n严重", "tag": "lark_md"}}
      ]
    },
    {"tag": "hr"},
    {
      "tag": "action",
      "actions": [
        {
          "tag": "button",
          "type": "primary",
          "text": {"content": "查看详情", "tag": "plain_text"},
          "url": "https://monitor.example.com/alert/123"
        },
        {
          "tag": "button",
          "type": "default",
          "text": {"content": "忽略", "tag": "plain_text"},
          "url": "https://monitor.example.com/alert/123/ignore"
        }
      ],
      "layout": "bisected"
    },
    {
      "tag": "note",
      "elements": [{"tag": "plain_text", "content": "来自监控系统 · 2024-01-15 10:30:00"}]
    }
  ]
}

构建卡片的建议

当需要发送卡片时：

1. 根据信息类型选择合适的标题颜色
2. 使用 div + fields 展示结构化数据
3. 重要操作使用按钮，提供跳转链接
4. 使用 note 添加来源或时间信息
5. 保持卡片简洁，避免信息过载

MCP Server（AI Agent 实时消息集成）

lark-cli 提供了 MCP (Model Context Protocol) Server，允许 AI Agent 实时监听和响应飞书消息。

可用的 MCP Tools

Tool	描述
get_bot_info	获取机器人配置信息（名称、描述、persona 等）
list_chats	列出机器人所在的群聊
list_chat_members	列出群聊成员
send_message	发送消息到用户或群聊
reply_message	回复指定消息
add_reaction	给消息添加表情回复
get_recent_messages	获取群聊的最近消息
search_member	在群聊中搜索成员
start_message_listener	启动消息监听器
get_pending_messages	获取待处理的消息队列
stop_message_listener	停止消息监听器

消息监听过滤类型

start_message_listener 支持以下过滤类型：

filter_type	描述
all	监听所有消息
p2p	仅监听私聊消息
group	仅监听群聊消息
at	仅监听 @ 机器人的消息

AI Agent 工作流示例

# 1. 获取机器人信息
bot_info = get_bot_info()
# 了解机器人的 persona 设定

# 2. 启动监听器（仅监听 @ 机器人的消息）
start_message_listener(filter_type="at")

# 3. 轮询获取新消息
while True:
    pending = get_pending_messages(max_messages=5)
    for msg in pending["messages"]:
        # 处理消息
        chat_id = msg["chat_id"]
        message_id = msg["message_id"]
        content = msg["content"]["text"]

        # 根据内容生成回复
        response = generate_response(content)

        # 回复消息
        reply_message(message_id, response)

# 4. 停止监听
stop_message_listener()

机器人 Persona 配置

在 lark-cli 配置文件中可以为租户添加自定义字段：

tenants:
  my-bot:
    app_id: cli_xxx
    app_secret: xxx
    description: "我的飞书机器人"
    # 自定义字段（AI Agent 可通过 get_bot_info 获取）
    bot_name: "小助手"
    persona: |
      你是一个友好的助手，负责回答技术问题。
      回复要简洁专业。

AI Agent 自动回复

lark-cli 提供了完整的 AI Agent 功能，可以让机器人自动监听飞书消息并使用 Claude 生成回复。

前置依赖

使用 AI Agent 功能需要以下条件：

1. Claude Code CLI

   • Agent 使用 claude-agent-sdk 与 Claude 交互
   • SDK 已包含在插件依赖中（自动安装）
   • SDK 内部自动管理 Claude Code CLI 进程

2. Anthropic API 访问

   • 确保已完成 claude 命令的初始设置
   • 或设置 ANTHROPIC_API_KEY 环境变量

3. 飞书机器人配置

   • 配置 ~/.lark_cli/config.yaml 中的租户信息
   • 需要有效的 App ID 和 App Secret

验证依赖：

# 检查 Claude Code
claude --version

# 检查飞书配置
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli config show

启动 AI Agent

# 启动 AI Agent（默认只回复 @ 机器人的消息）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli agent

# 监听所有消息（包括群聊中的所有消息）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli agent --filter all

# 仅监听私聊消息
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli agent --filter p2p

# 仅监听群聊消息
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli agent --filter group

# 使用特定模型
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli agent --model haiku    # 快速响应
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli agent --model sonnet   # 平衡（默认）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli agent --model opus     # 高质量

# 自定义 persona
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli agent --persona "你是一个专业的技术助手，用简洁的语言回答问题"

# 详细日志模式
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run lark-cli agent --verbose

Agent 命令选项

选项	说明
-t, --tenant	指定租户名称
-f, --filter	消息过滤：all、p2p、group、at（默认）
-m, --model	模型选择：haiku、sonnet、opus
-p, --persona	自定义 AI persona
-d, --debounce	消息聚合延迟（秒，默认 0.5）
--no-fast-llm	禁用快速 LLM，仅使用 Claude Code
--group-auto-reply	启用群聊自主回复（根据话题相关性）
-v, --verbose	详细日志输出

双层 LLM 架构

AI Agent 采用双层 LLM 架构以优化响应速度：

层级	用途	响应时间
快速 LLM（可选）	意图分类、简单闲聊	~1-2 秒
Claude Code	复杂任务、代码执行	~10-30 秒

工作流程：

1. 收到消息后，快速 LLM 判断意图（CHAT 或 TASK）
2. 简单闲聊由快速 LLM 直接回复
3. 复杂任务转发给 Claude Code 处理

不配置快速 LLM：所有消息由 Claude Code 处理（功能正常，但响应稍慢）

快速 LLM 配置

在 ~/.lark_cli/config.yaml 中添加 fast_llm 配置：

tenants:
  my_bot:
    # ... 基础配置 ...

    # 方式一：豆包（火山引擎 Ark）
    # 需要设置: export ARK_API_KEY=your_api_key
    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
    # 需要设置: export OPENAI_API_KEY=your_api_key
    # fast_llm:
    #   enabled: true
    #   provider: "openai"
    #   base_url: "https://api.openai.com/v1"
    #   model: "gpt-4o-mini"
    #   api_key_env: "OPENAI_API_KEY"

    # 方式三：DeepSeek
    # 需要设置: export DEEPSEEK_API_KEY=your_api_key
    # fast_llm:
    #   enabled: true
    #   provider: "deepseek"
    #   base_url: "https://api.deepseek.com/v1"
    #   model: "deepseek-chat"
    #   api_key_env: "DEEPSEEK_API_KEY"

Agent 架构特点

1. 双层 LLM：快速响应简单对话，复杂任务交给 Claude Code
2. 持久 Claude 连接：每个聊天保持独立的 Claude session，支持多轮对话
3. Session 自动恢复：重启 agent 后自动恢复之前的对话上下文
4. 实时状态反馈：
   • 收到消息时添加 ✓ 表情
   • 处理中显示 THINKING 表情
   • 处理失败显示 ERROR 表情
   • 处理成功后移除状态表情
5. WebSocket 连接监控：自动重连，断线重连后继续处理新消息
6. 消息聚合：短时间内的多条消息会被聚合处理

性能指标

指标	数值
平均响应时间	~9.5 秒
平均成本	~$0.012/消息
首次响应	~11 秒
后续响应	~8 秒（利用缓存）

机器人 Persona 配置

在配置文件 (~/.lark_cli/config.yaml) 中为机器人设置个性化行为：

tenants:
  my-bot:
    app_id: cli_xxx
    app_secret: xxx
    description: "我的 AI 助手"
    # AI Agent 专用配置
    bot_name: "Kira"
    bot_identity: "你是 Kira，一个友好、专业的 AI 助手"
    bot_capabilities: "回答问题、提供建议、协助文档编写、解释代码"
    persona: |
      ## 行为准则
      - 用友好的语气回复，适当使用 emoji
      - 回复要简洁但完整
      - 技术问题要准确专业
      - 不确定时诚实说明
    model: sonnet  # 默认使用的模型

Session 管理

Agent 会自动管理每个聊天的 session：

# Session 缓存位置
~/.lark_cli/agent_sessions.yaml

# 清除特定聊天的 session（重置对话）
# 直接编辑 agent_sessions.yaml 删除对应条目

使用场景

1. 客服机器人：自动回答常见问题
2. 技术支持：解答技术问题，提供代码示例
3. 团队助手：在群聊中回答 @ 机器人的问题
4. 通知助手：接收通知后智能回复确认