SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场lark-event

lark-event

办公与效率

查看项目

更新于 10-13 21:32

技能介绍

用途

lark-event 用于让 AI 智能体通过命令行工具 lark-cli 消费飞书（Lark）事件。它把可订阅的事件以 EventKey 形式暴露出来，消费时事件以 NDJSON 格式输出到标准输出，方便上层程序读取和处理。

前置条件

使用前需先阅读 ../lark-shared/SKILL.md，了解认证方式、--as user/bot 身份切换、Permission denied 处理以及安全规则。

主要命令

  • lark-cli event list [--json]：列出所有可订阅的 EventKey，可用 --domain 限定领域，领域包括 application、approval、board、card、im、minutes、task、vc。
  • lark-cli event schema <EventKey> [--json]：查看某个 EventKey 的参数与输出结构。
  • lark-cli event consume <EventKey> [flags]：阻塞式消费，事件写入标准输出 NDJSON。
  • lark-cli event status [--json] [--fail-on-orphan]：检查本地总线守护进程状态。
  • lark-cli event stop [--all] [--force]：停止总线守护进程。

常用参数

  • --param key=value / -p：业务参数，可重复使用，多值用逗号分隔；未知键会报错并列出合法名称。
  • --jq <expr>：用 jq 表达式过滤或转换每条事件，输出为空则跳过该事件。
  • --max-events N：接收 N 条事件后退出，默认 0 表示不限制。
  • --timeout D：经过时长 D 后退出（如 30s、2m），默认 0 表示不超时。--max-events 与 --timeout 谁先触发就以谁为准。
  • --output-dir <dir>：把每条事件写入文件（仅支持相对路径，防止路径穿越）。
  • --quiet：抑制 ready/exit 标记与每条事件的 stderr 诊断信息（包括丢弃警告），可能隐藏事件丢失，AI 不应使用。
  • --as user|bot|auto：会话身份（见 lark-shared）。

调用流程

  1. lark-cli event list --json 选择一个合法 EventKey。
  2. lark-cli event schema <key> --json 阅读 resolved_output_schema 与 jq_root_path 确定字段路径。
  3. lark-cli event consume <key> [--jq '<expr>'] 进行消费。

子进程约定

  • 就绪标记：consume 的 stderr 会输出固定行 [event] ready event_key=<key>，父进程应阻塞等待该行出现后再读取 stdout，不要用 sleep 代替。
  • stdin EOF 即优雅退出：对有界运行（--max-events 或 --timeout 大于 0）会忽略 stdin EOF；对无界运行，< /dev/null / nohup / systemd 默认 StandardInput=null 会导致立即优雅退出（stderr 原因为 signal）。要保持无界运行，可用 < <(tail -f /dev/null) 或改用有界运行。
  • 退出码与原因：最后一行 stderr 为 [event] exited — received N event(s) in Xs (reason: ...)。limit/timeout/signal 均退出码 0；1 为消费前准备阶段飞书 API 业务失败；2 为校验失败（未知 EventKey、错误的 --param/--jq、已有总线连接）；3 为认证失败；4/5 为网络或内部失败。启动与运行时失败会输出结构化 JSON：{"ok":false,"error":{"type","subtype","param","message","hint",...}}，应按 error.type/error.subtype 分支，根据 error.param 与 error.hint 处理，不要用正则匹配 message 文本。
  • 不要 kill -9：对在退出时会注销服务端订阅的 EventKey（minutes、vc、board），kill -9 会跳过注销并泄漏服务端订阅，导致重启时提示 subscription already exists 或重复投递。

一次消费一个 EventKey

命令只接受一个位置参数，不支持 k1,k2 和通配符。监听 N 个 key 需要 N 个子进程，这是有意设计：每个进程一种输出结构、故障隔离、每个 key 独立配置 --as/--jq/--max-events/--timeout，且所有消费者共享同一个总线守护进程（UDS 本地 IPC），开销较小。

通过 schema 编写 jq

event schema <key> --json 是编写 --jq 的事实来源，需关注四点：字段起始位置（jq_root_path，"." 表示顶层，".event" 表示 V2 信封内）；字段列表与类型（resolved_output_schema.properties.<name>，含 type/description/format）；字段语义（飞书自定义 format 标签，如 open_id / chat_id / message_id / timestamp_ms / email）；是否已被解码（consume 的 Process 钩子可能预先解码部分字段，如展平 V2 信封、把 .content 渲染为纯文本）。对已解码的文本字段盲目使用 fromjson 会导致每条事件 jq 报错并被静默跳过，消费者看似存活却无输出。--param 的合法参数同样在 schema 的 params 段落中。

适用场景与主题索引

覆盖以下主题（详见各自 reference）：应用（application.bot.menu_v6 等）、审批（approval.instance.status_changed_v4、approval.task.status_changed_v4）、IM（12 个 EventKey，含 im.message.receive_v1 等）、任务（task.task.update_user_access_v2）、音视频会议（7 个 VC EventKey）、妙记（minutes.minute.generated_v1）、白板（board.whiteboard.updated_v1，需 -p whiteboard_id=<token>）。

限制

一次只能消费一个 EventKey；不支持通配符或多 key；--quiet 会移除就绪与完整性信号；--output-dir 仅支持相对路径。认证、费用、价格、平台支持范围等其他信息资料中暂未提供。