1. 从“能用”到“好用”：为什么说飞书 CLI 是 Hermes 集成的关键一步

最近在折腾团队内部的效率工具链，把 Hermes 接入了飞书。说实话，这事儿本身不难，官方文档写得挺清楚，配置一下 Webhook，消息就能从 Hermes 推到飞书群里。但搞完之后，我总觉得差点意思。消息是能发了，可每次想查个机器人状态、临时发个测试消息，或者批量处理点啥，都得打开浏览器，登录飞书开放平台，在一堆菜单里点来点去。这感觉就像你买了辆跑车，但每次启动都得用钥匙手动去拧发动机，而不是按一下无钥匙启动按钮。

这就是为什么我说， “Hermes 接上飞书”只是完成了从 0 到 1，而“飞书 CLI”才是实现从 1 到 10，乃至 100 的关键一步。 CLI，也就是命令行工具，它把那些零散、手动、需要界面的操作，变成了可脚本化、可自动化、可集成到现有工作流中的原子操作。对于开发者、运维或者任何需要与飞书机器人/应用高频交互的团队来说，这带来的效率提升和可能性拓展是颠覆性的。想象一下，你可以在 CI/CD 流水线里直接用一条命令发送构建通知，在服务器上用脚本定时拉取群聊文件，或者写个简单的自动化脚本处理审批流——所有这些，都不需要你离开终端或者打开任何图形界面。

2. 飞书 CLI 的核心价值：不止于发送消息

很多人对飞书机器人的理解还停留在“发消息”上，认为 CLI 无非是把 curl 命令封装了一下。这个认知太浅了。飞书 CLI（这里主要指基于飞书开放平台 API 封装的命令行工具，官方或社区均有提供）的真正威力，在于它让你能以程序化的方式，全面、深入地管理和使用飞书生态的能力。

2.1 超越 Webhook：双向交互与主动查询

Webhook 是单向的，是“推送”。而 CLI 开启的是“拉取”和“命令”模式。

• 状态查询与监控 ：你的 Hermes 服务挂了，飞书机器人还活着吗？它的发送频率限制用了多少？通过 CLI，你可以随时执行 feishu-cli bot info 这样的命令来获取机器人的实时状态，而无需登录管理后台。
• 数据获取 ：需要备份某个群聊过去一周的所有文件？或者统计某个话题下的消息数量？CLI 可以让你用 feishu-cli message list --chat_id=xxx --date=last_week 配合 feishu-cli file list 来轻松实现，然后通过管道 ( | ) 传递给其他命令行工具（如 grep , jq , awk ) 进行处理，这是图形界面难以企及的效率。
• 主动管理 ：创建新的群聊、更新机器人头像、管理应用权限范围……这些管理操作通过 CLI 可以轻易地写入你的基础设施即代码 (IaC) 流程中，确保环境的一致性。

2.2 自动化与脚本集成：将飞书融入工作流血脉

这是 CLI 最大的用武之地。你的所有终端操作都可以和飞书联动。

• CI/CD 集成 ：在 Jenkins、GitLab CI 或 GitHub Actions 的 pipeline 中，在构建成功、失败、或部署完成时，直接调用 CLI 发送富文本消息到指定群，附上构建日志链接或关键指标。

  # 一个简单的GitHub Actions步骤示例
  - name: Notify Feishu on Failure
    if: failure()
    run: |
      feishu-cli message send \
        --chat_id=${{ secrets.FEISHU_CHAT_ID }} \
        --msg_type=post \
        --content='{"zh_cn": {"title": "🚨 构建失败", "content": [[{"tag": "text", "text": "仓库: ${{ github.repository }}\n分支: ${{ github.ref }}\n详情: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"}]]}}'
  

• 服务器监控与告警 ：传统的监控告警可能发邮件或走其他通道。现在，你可以在服务器上的监控脚本（如检查磁盘、内存的 cron job）中，直接集成飞书 CLI，让告警以更及时、更易被关注的形式（如@特定人）到达飞书群。
• 本地开发助手 ：写一个脚本，将 git commit 的信息自动格式化并发送到团队开发日志群。或者，当你本地单元测试通过后，自动发送一条“绿灯”消息。这些看似微小的自动化，能极大地提升团队的协同感和信息透明度。

2.3 提升操作安全性与可审计性

在服务器或无头环境中，使用 CLI 配合配置好的访问令牌，比在某个公共电脑上登录飞书管理后台要安全得多。令牌权限可以精细控制，并且可以按需轮换。所有通过 CLI 执行的操作，本质上都是一条条明确的命令，非常容易记录到操作日志中，便于后续审计和回溯。谁在什么时间执行了什么操作，一目了然。

3. 实战：为你的 Hermes + 飞书环境配置 CLI 工具

市面上有几种选择：飞书官方提供的开发者工具套件（通常包含 CLI 组件），以及社区维护的第三方 CLI 工具（如 lark-cli ）。这里我以社区一个较为流行的工具为例，讲解从零开始的配置和使用流程。选择社区工具的原因往往是其更贴近开发者习惯，命令设计更灵活。

3.1 环境准备与工具安装

首先，你需要在你的工作环境（可以是本地开发机，也可以是服务器）上安装这个 CLI 工具。通常，它们通过 npm 或 pip 等包管理器分发。

# 假设是一个Node.js工具
npm install -g lark-cli

# 或者是一个Python工具
pip install feishu-cli

安装完成后，运行 feishu-cli --version 或 lark-cli --help 验证安装是否成功。

3.2 获取并配置必要的凭证

这是最关键的一步。CLI 需要凭证来代表你的应用与飞书 API 对话。你需要从飞书开放平台获取以下信息：

1. App ID 和 App Secret ：这是应用的身份标识。进入你的应用后台（就是你配置 Hermes Webhook 的地方），在“凭证与基础信息”页面可以找到。
2. 访问令牌 ：大部分 API 调用需要 Token。飞书 API 主要使用两种：
   • Tenant Access Token ：代表整个企业自建应用，权限范围大。获取它需要 App ID 和 App Secret。
   • User Access Token ：代表某个具体的用户，需要经过 OAuth 授权，适用于需要以用户身份操作（如读取该用户的日历）的场景。

对于 Hermes 相关的自动化操作，我们通常使用 Tenant Access Token 。CLI 工具一般提供了便捷的命令来帮助获取和缓存这个 Token。

# 使用CLI命令配置凭证并获取Token
feishu-cli config set --app_id=cli_xxxxxx --app_secret=xxxxxx
# 该命令通常会自动帮你获取并缓存Tenant Access Token

注意 ： App Secret 是最高机密，绝不能泄露或提交到代码仓库。在 CI/CD 环境中，应将其存储在环境变量或 Secrets Manager 中。CLI 命令也支持从环境变量读取，如 FEISHU_APP_ID 和 FEISHU_APP_SECRET ，这是更安全的生产环境实践。

3.3 验证与基础命令测试

配置好后，进行一个简单的测试，验证一切是否正常。

# 测试1：发送一条文本消息到群聊
# 首先，你需要知道目标群聊的 chat_id。获取方式之一是通过CLI工具本身（如果你有权限）：
# feishu-cli chat list # 列出可访问的群聊
# 或者，在飞书群中添加机器人后，通常可以通过事件回调获得chat_id。

feishu-cli message send \
  --chat_id=oc_xxxxxxxxxxxxxx \
  --msg_type=text \
  --content='{"text": "CLI 消息测试，Hello from Terminal!"}'

# 测试2：获取机器人的基本信息
feishu-cli bot info

如果群聊里收到了消息，并且 bot info 正确返回了机器人名称、头像等信息，那么恭喜你，CLI 环境已经搭建成功。

4. 进阶场景：用 CLI 解锁 Hermes 的深层用法

现在，让我们把 CLI 和 Hermes 结合起来，看看能玩出什么花样。

4.1 场景一：动态管理 Hermes 的 Webhook 地址

在微服务架构或动态环境中，你的 Hermes 服务地址可能会变（例如，在测试、预发布、生产环境有不同的域名）。每次变更都手动去开放平台修改 Webhook URL 非常麻烦。你可以写一个部署后脚本，用 CLI 自动更新。

#!/bin/bash
# deploy_hook_update.sh
# 假设 HERMES_NEW_URL 由部署脚本传入，FEISHU_APP_TOKEN 已存在环境变量中

NEW_WEBHOOK_URL="${HERMES_NEW_URL}/webhook/feishu"
APP_ID="your_app_id"

# 使用CLI更新事件订阅的请求地址
# 注意：飞书API中更新Webhook可能需要调用特定接口，这里是一个概念性示例
# 实际命令可能需要根据CLI工具的具体功能进行调整，例如调用内部封装的API
feishu-cli api PATCH /open-apis/event/v1/app/event_subscription \
  --data="{
    \"endpoint\": \"$NEW_WEBHOOK_URL\",
    \"events\": [\"im.message.receive_v1\"] # 根据实际需要的事件类型填写
  }"

if [ $? -eq 0 ]; then
  echo "✅ Feishu webhook endpoint updated to $NEW_WEBHOOK_URL"
  # 可以顺便发个飞书消息通知团队
  feishu-cli message send --chat_id=oc_xxx --msg_type=text --content='{"text":"Hermes服务地址已更新至新环境。"}'
else
  echo "❌ Failed to update webhook endpoint"
  exit 1
fi

4.2 场景二：构建 Hermes 消息发送的本地调试工具

开发 Hermes 消息处理逻辑时，经常需要模拟飞书服务器发来的不同事件。与其等待真实用户交互，不如用 CLI 创造一个“虚拟飞书服务器”。

1. 模拟消息事件 ：飞书的消息事件有固定的 JSON 结构。你可以先写一个示例 event_sample.json 文件。

   {
     "schema": "2.0",
     "header": {
       "event_id": "xxx",
       "event_type": "im.message.receive_v1",
       "create_time": "1670000000000",
       "token": "xxx",
       "app_id": "cli_xxx",
       "tenant_key": "xxx"
     },
     "event": {
       "sender": {
         "sender_id": {
           "union_id": "on_xxx",
           "user_id": "ou_xxx",
           "open_id": "ou_xxx"
         },
         "sender_type": "user",
         "tenant_key": "xxx"
       },
       "message": {
         "message_id": "om_xxx",
         "root_id": "om_xxx",
         "parent_id": "om_xxx",
         "create_time": "1670000000000",
         "chat_id": "oc_xxx",
         "chat_type": "group",
         "message_type": "text",
         "content": "{\"text\":\"@_user_1 测试一下Hermes的回复功能\"}",
         "mentions": [{"key": "@_user_1", "id": {"user_id": "ou_xxx"}}]
       }
     }
   }
   

2. 使用 CLI 快速发送测试请求到本地 Hermes ：结合 curl 和 CLI 获取的 Token，你可以轻松构造请求。

   # 获取有效的Tenant Access Token (如果CLI工具没有缓存)
   TOKEN=$(feishu-cli token get --type=tenant)
   # 向本地运行的Hermes服务发送模拟事件
   curl -X POST http://localhost:8080/webhook/feishu \
        -H "Content-Type: application/json" \
        -H "X-Lark-Request-Timestamp: 1670000000" \
        -H "X-Lark-Request-Nonce: some_nonce" \
        -H "X-Lark-Signature: xxx" \ # 注意：签名需要根据飞书规则计算，调试初期可以先在Hermes端关闭验签
        -H "Authorization: Bearer $TOKEN" \
        -d @event_sample.json
   

   通过这种方式，你可以反复测试 Hermes 的解析逻辑、业务处理流程，而无需在飞书上真实操作，极大提升开发调试效率。

4.3 场景三：消息日志的备份与分析

Hermes 可能处理了大量消息，但自身未必存储历史记录。你可以定期使用 CLI 拉取群聊消息，进行备份或分析。

#!/bin/bash
# backup_group_messages.sh
CHAT_ID="oc_xxxxxxxxxxxxxx"
BACKUP_DIR="./feishu_backup/$(date +%Y%m)"
mkdir -p $BACKUP_DIR

# 获取最近24小时的消息（飞书API可能支持分页和时间范围参数）
# 这里假设CLI工具支持`--page_size`和`--page_token`进行分页
feishu-cli message list --chat_id=$CHAT_ID --page_size=50 > "$BACKUP_DIR/messages_$(date +%Y%m%d).json"

# 使用jq工具进行简单分析，例如：统计今日发言最活跃的前3个用户
cat "$BACKUP_DIR/messages_$(date +%Y%m%d).json" | jq -r '.data.items[] | select(.sender.sender_id.user_id) | .sender.sender_id.user_id' | sort | uniq -c | sort -nr | head -3 > "$BACKUP_DIR/top_speakers_$(date +%Y%m%d).txt"

这个脚本可以放到 crontab 里每天执行，自动备份和分析数据。

5. 避坑指南与最佳实践

在实际操作中，我踩过一些坑，也总结出一些让这套流程更稳健的经验。

5.1 权限管理与 Token 安全

• 最小权限原则 ：在飞书开放平台为你的应用申请权限时，只勾选 Hermes 和 CLI 脚本实际需要的权限。比如，如果只是发送消息和读取指定群聊，就不要申请“读取所有群聊信息”的权限。
• Token 生命周期管理 ：Tenant Access Token 默认有效期为2小时。你的 CLI 脚本或自动化任务必须处理 Token 过期的情况。好的 CLI 工具会自动在本地缓存 Token 并在过期前刷新。如果你是自己封装 API 调用，务必实现 Token 的缓存和刷新逻辑，避免在关键任务（如凌晨的监控告警）中因 Token 过期而失败。
• 秘密信息零落地 ：绝对不要将 App Secret 或 Token 硬编码在脚本里或提交到版本控制系统。务必使用环境变量、云服务商提供的密钥管理服务（如 AWS Secrets Manager, Azure Key Vault）或 CI/CD 系统的 Secret 功能来存储和传递。

5.2 速率限制与错误处理

飞书 API 有严格的调用频率限制。CLI 工具在封装时可能不会帮你处理所有限流情况，在编写自动化脚本时需要注意。

• 识别限流错误 ：API 返回 code=99991400 通常意味着速率限制。你的脚本在接收到这类错误时，应该实现指数退避重试逻辑，而不是无限循环快速重试，这会导致情况更糟。
• 批量操作要谨慎 ：如果需要给大量用户发送消息或处理大量数据，务必在循环中增加延迟（例如 sleep 1 ），或者使用飞书 API 提供的批量接口。
• 完善的日志与告警 ：你的 CLI 自动化脚本本身也应该有日志记录，并在失败时通过另一条通道（或者另一个飞书机器人）发送告警，避免“送信人自己失踪了”的情况。

5.3 CLI 工具的选择与封装

• 评估可用性 ：选择 CLI 工具前，先看其文档是否清晰，是否支持你最需要的几个核心 API（发送消息、获取群聊列表、处理事件等）。可以用 --help 看看命令设计是否符合直觉。
• 考虑封装一层 ：如果团队内有多人需要使用，或者希望统一某些操作逻辑（如固定的消息格式、默认的 chat_id ），可以考虑在官方或社区 CLI 工具之上，再封装一层自己的 Shell 脚本或 Python 脚本。这能降低团队成员的使用门槛，并保证操作的一致性。
• 版本化你的自动化脚本 ：将这些 CLI 脚本像管理代码一样管理起来，使用 Git 进行版本控制。这样，脚本的变更历史、回滚、协作都会变得非常方便。

走到这一步，Hermes 与飞书的结合就不再是一个简单的“消息转发器”，而是进化成了团队自动化基础设施中的一个智能枢纽。CLI 所提供的程序化能力，让这个枢纽可以被精准地控制、灵活地编排，并深度嵌入到研发、运维、协作的每一个环节中。它解决的不仅仅是“通知”问题，更是“效率”和“可能性”的问题。当你习惯了在终端里敲几个字就能操控远端的协作空间时，那种流畅感和掌控感，会让你再也回不去那个只能点点点的时代。