hermes-feishu

增强 Hermes Agent 飞书消息通道，支持卡片消息和表格渲染。

问题背景

Hermes Agent 内置的飞书通道使用 post 消息类型 + tag: "md" 发送 Markdown 内容。但飞书的 Markdown 组件仅支持语法子集，不支持表格语法 (| col | col |)。这导致 LLM 生成的表格在飞书中无法正常渲染。

解决方案

本插件通过以下方式解决：

1. send_feishu_card 工具 — 发送包含表格的飞书卡片消息。自动检测 Markdown 中的表格语法，转换为飞书卡片 Table 组件。
2. send_feishu_table 工具 — 直接发送结构化表格数据（headers + rows）。
3. pre_llm_call 钩子 — 当平台为飞书时，自动注入格式化指令，引导 LLM 使用卡片工具发送表格。

快速安装

1. 环境准备

• Python 3.10+
• Hermes Agent 已安装并配置飞书平台
• 飞书开放平台应用（需要 App ID 和 App Secret）

2. 安装插件

hermes plugins install arkseek/hermes-feishu

3. 配置环境变量

⚠️ 重要：凭证必须配置在 ~/.hermes/.env 文件中，否则插件工具不会加载。

# 编辑 Hermes 环境变量文件
nano ~/.hermes/.env

# 添加以下内容
FEISHU_APP_ID=cli_xxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx

# 可选：设置默认 chat_id（用于 Hermes 未传递 chat_id 的情况）
# HERMES_FEISHU_CHAT_ID=oc_xxxxxxxxxxxxxxxxxxxxxxxx

关于 HERMES_FEISHU_CHAT_ID

Hermes Agent 目前存在一个已知问题：pre_llm_call 钩子不会传递 chat_id 参数给插件（尽管 Hermes 内部拥有该信息）。这导致插件无法自动确定目标会话。

临时解决方案：

• 在 .env 中设置 HERMES_FEISHU_CHAT_ID，插件会在找不到 chat_id 时使用该默认值
• 适用于单会话场景（例如只在特定群组中使用）
• 多会话场景下，建议向 Hermes 提交 Issue 请求修复

如何获取 chat_id：

1. 在飞书中发送消息给机器人
2. 查看 Hermes gateway 日志，搜索 inbound message 日志
3. 日志中的 chat=oc_xxx 即为 chat_id

4. 重启 Hermes

hermes gateway restart

重启后使用 /plugins 命令确认插件已加载。

使用方式

插件加载后，LLM 在飞书平台上会自动收到格式化指令。当需要展示表格时，LLM 会自动调用 send_feishu_card 或 send_feishu_table 工具。

工具参数

send_feishu_card

发送富文本卡片消息,支持 Markdown 内容和表格。

参数:

• content (必填): Markdown 内容,可包含表格
• title (可选): 卡片标题
• chat_id (可选): 目标会话 ID (通常自动检测)
• template (可选): 卡片配色模板 (默认: blue)
• reaction (可选): 发送后添加的表情反应 (例如: 👍, ✅, 🎉)

示例:

{
  "content": "| 姓名 | 年龄 |\n| --- | --- |\n| 张三 | 25 |\n| 李四 | 30 |",
  "title": "📊 数据表格",
  "template": "blue",
  "reaction": "✅"
}

send_feishu_table

发送结构化表格数据。

参数:

• headers (必填): 列标题数组
• rows (必填): 数据行数组
• title (可选): 卡片标题
• chat_id (可选): 目标会话 ID
• template (可选): 卡片配色模板
• reaction (可选): 发送后添加的表情反应

示例:

{
  "headers": ["姓名", "年龄"],
  "rows": [["张三", "25"], ["李四", "30"]],
  "title": "📊 数据表格",
  "reaction": "👍"
}

示例：Markdown 表格

LLM 生成包含表格的内容时会自动调用：

用户: 帮我对比一下这两个方案

LLM 调用 send_feishu_card:
  content: |
    | 对比项 | 方案A | 方案B |
    | --- | --- | --- |
    | 成本 | ¥1000 | ¥2000 |
    | 周期 | 2周 | 1周 |
    | 风险 | 低 | 中 |

飞书中会渲染为带颜色标题的卡片消息，表格使用飞书 Table 组件。

示例：结构化表格

LLM 可以直接使用结构化数据：

LLM 调用 send_feishu_table:
  headers: ["指标", "当前值", "目标值"]
  rows: [
    ["日活用户", "10,000", "15,000"],
    ["转化率", "3.2%", "5%"],
    ["NPS", "42", "60"]
  ]

插件架构

src/hermes_feishu/
├── __init__.py      # 插件注册：工具 + 钩子
├── schemas.py       # 工具 Schema 定义
├── tools.py         # 工具处理器
├── card_builder.py  # 飞书卡片 JSON 构建
├── table_parser.py  # Markdown 表格解析
└── sender.py        # 飞书 API 发送层

飞书应用权限

插件需要以下飞书应用权限：

权限	权限标识	用途
获取与发送单聊、群组消息	im:message	发送卡片消息
读取消息中的消息体内容	im:message:readonly	读取消息内容

开发

# 克隆仓库
git clone https://github.com/arkseek/hermes-feishu.git
cd hermes-feishu

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v

# 运行测试（带覆盖率）
pytest tests/ -v --cov=hermes_feishu

许可证

MIT License

更新日志

v0.4.0 (2026-04-15)

新功能

• ✨ 添加消息 Reaction 支持：工具支持 reaction 参数，发送成功后自动添加表情反应
• 🔧 添加 HERMES_FEISHU_CHAT_ID 环境变量回退，解决 Hermes 未传递 chat_id 的问题

Bug 修复

• 🐛 修复飞书 Table 组件格式错误，正确使用字典列表格式
• 🐛 修复表格渲染失败问题（"table rows is invalid" 错误）

改进

• 📝 完善 README 文档，添加环境变量配置说明
• 🎨 改进错误消息，提供明确的解决方案

v0.3.6 (之前)

• 初始版本
• 实现基本的卡片消息和表格渲染功能