hermes-feishu 0.2.0__tar.gz

hermes_feishu-0.2.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: hermes-feishu
+Version: 0.2.0
+Summary: Enhanced Feishu/Lark messaging for Hermes Agent with card messages and table rendering
+Author: hermes-feishu contributors
+License: MIT
+Keywords: hermes,feishu,lark,agent,plugin,card,table
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: lark-oapi<2,>=1.5.3
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+
+# 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. 安装插件
+
+```bash
+# 从源码安装（开发模式）
+cd hermes-feishu
+pip install -e .
+
+# 或安装到 Hermes 插件目录
+cp plugin.yaml ~/.hermes/plugins/hermes-feishu/
+cp -r src/hermes_feishu/ ~/.hermes/plugins/hermes-feishu/
+```
+
+### 3. 配置环境变量
+
+```bash
+export FEISHU_APP_ID="cli_xxxxxxxxxxxx"
+export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxx"
+```
+
+或在 Hermes 的 `.env` 文件中添加：
+
+```env
+FEISHU_APP_ID=cli_xxxxxxxxxxxx
+FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### 4. 重启 Hermes
+
+```bash
+hermes
+```
+
+启动后使用 `/plugins` 命令确认插件已加载。
+
+## 使用方式
+
+插件加载后，LLM 在飞书平台上会自动收到格式化指令。当需要展示表格时，LLM 会自动调用 `send_feishu_card` 或 `send_feishu_table` 工具。
+
+### 示例：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` | 读取消息内容 |
+
+## 开发
+
+```bash
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest tests/ -v
+
+# 运行测试（带覆盖率）
+pytest tests/ -v --cov=hermes_feishu
+```
+
+## 许可证
+
+MIT License

hermes_feishu-0.2.0/README.md

@@ -0,0 +1,131 @@
+# 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. 安装插件
+
+```bash
+# 从源码安装（开发模式）
+cd hermes-feishu
+pip install -e .
+
+# 或安装到 Hermes 插件目录
+cp plugin.yaml ~/.hermes/plugins/hermes-feishu/
+cp -r src/hermes_feishu/ ~/.hermes/plugins/hermes-feishu/
+```
+
+### 3. 配置环境变量
+
+```bash
+export FEISHU_APP_ID="cli_xxxxxxxxxxxx"
+export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxx"
+```
+
+或在 Hermes 的 `.env` 文件中添加：
+
+```env
+FEISHU_APP_ID=cli_xxxxxxxxxxxx
+FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### 4. 重启 Hermes
+
+```bash
+hermes
+```
+
+启动后使用 `/plugins` 命令确认插件已加载。
+
+## 使用方式
+
+插件加载后，LLM 在飞书平台上会自动收到格式化指令。当需要展示表格时，LLM 会自动调用 `send_feishu_card` 或 `send_feishu_table` 工具。
+
+### 示例：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` | 读取消息内容 |
+
+## 开发
+
+```bash
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest tests/ -v
+
+# 运行测试（带覆盖率）
+pytest tests/ -v --cov=hermes_feishu
+```
+
+## 许可证
+
+MIT License

hermes_feishu-0.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hermes-feishu"
+version = "0.2.0"
+description = "Enhanced Feishu/Lark messaging for Hermes Agent with card messages and table rendering"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "hermes-feishu contributors"},
+]
+keywords = ["hermes", "feishu", "lark", "agent", "plugin", "card", "table"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Chat",
+]
+dependencies = [
+    "lark-oapi>=1.5.3,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[project.entry-points."hermes_agent.plugins"]
+hermes-feishu = "hermes_feishu"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

hermes_feishu-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hermes_feishu-0.2.0/src/hermes_feishu/__init__.py

@@ -0,0 +1,85 @@
+"""Hermes Feishu Plugin - Enhanced Feishu messaging with card messages and table rendering.
+
+This plugin enhances Hermes Agent's Feishu messaging capabilities by providing:
+- send_feishu_card: Send rich card messages with table support
+- send_feishu_table: Send structured tables as card messages
+- pre_llm_call hook: Auto-inject formatting instructions for Feishu platform
+"""
+
+from .schemas import SEND_FEISHU_CARD_SCHEMA, SEND_FEISHU_TABLE_SCHEMA
+from .sender import _has_credentials
+from .tools import send_feishu_card, send_feishu_table
+
+__version__ = "0.2.0"
+
+# Context injection for Feishu platform
+_FEISHU_CONTEXT_INJECTION = (
+    "\n\n[System: Feishu Platform Formatting]\n"
+    "You are connected via Feishu (Lark). Feishu post messages do NOT support "
+    "Markdown table syntax. When your response contains tabular data, you MUST "
+    "use the `send_feishu_card` or `send_feishu_table` tool to render it properly.\n"
+    "- Use `send_feishu_card` for Markdown content that includes tables.\n"
+    "- Use `send_feishu_table` for structured data (headers + rows).\n"
+    "- Do NOT include Markdown tables in your regular text response.\n"
+    "- Other Markdown (bold, italic, lists, code blocks) works fine in normal messages.\n"
+)
+
+
+def register(ctx):
+    """Register plugin tools and hooks with Hermes Agent.
+
+    Args:
+        ctx: Plugin registration context provided by Hermes.
+    """
+    # Register tools with conditional availability
+    ctx.register_tool(
+        name="send_feishu_card",
+        schema=SEND_FEISHU_CARD_SCHEMA,
+        handler=send_feishu_card,
+        check_fn=_has_credentials,
+    )
+
+    ctx.register_tool(
+        name="send_feishu_table",
+        schema=SEND_FEISHU_TABLE_SCHEMA,
+        handler=send_feishu_table,
+        check_fn=_has_credentials,
+    )
+
+    # Register pre_llm_call hook for Feishu context injection
+    ctx.register_hook("pre_llm_call", _on_pre_llm_call)
+
+
+def _on_pre_llm_call(
+    session_id: str = "",
+    user_message: str = "",
+    conversation_history=None,
+    is_first_turn: bool = False,
+    model: str = "",
+    platform: str = "",
+    **kwargs,
+):
+    """Inject Feishu formatting instructions when platform is Feishu.
+
+    Only injects on the first turn of a session to avoid repetition,
+    and only when the platform is 'feishu'.
+
+    Args:
+        session_id: Current session ID.
+        user_message: The user's message.
+        conversation_history: Conversation history.
+        is_first_turn: Whether this is the first turn.
+        model: Model name.
+        platform: Platform identifier (e.g., 'feishu').
+
+    Returns:
+        Context dict to inject, or None.
+    """
+    if not is_first_turn:
+        return None
+
+    # Normalize platform name (case-insensitive check)
+    if not platform or platform.lower() not in ("feishu", "lark"):
+        return None
+
+    return {"context": _FEISHU_CONTEXT_INJECTION}

hermes_feishu-0.2.0/src/hermes_feishu/card_builder.py

@@ -0,0 +1,241 @@
+"""Feishu card JSON builder for Hermes Feishu plugin.
+
+Builds Feishu interactive card JSON structures from parsed table data
+and markdown content.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from .table_parser import ParsedTable, TableColumn, TableCell, parse_table, split_table_and_text
+
+
+def _build_table_columns(columns: List[TableColumn]) -> List[Dict[str, Any]]:
+    """Build Feishu Table column definitions.
+
+    Args:
+        columns: Parsed table column definitions.
+
+    Returns:
+        List of Feishu column spec dicts.
+    """
+    feishu_cols: List[Dict[str, Any]] = []
+    for col in columns:
+        spec: Dict[str, Any] = {
+            "field_type": col.field_type,
+            "name": col.name,
+        }
+        if col.width:
+            spec["width"] = col.width
+        feishu_cols.append(spec)
+    return feishu_cols
+
+
+def _build_table_rows(
+    rows: List[List[TableCell]],
+    columns: List[TableColumn],
+) -> List[List[Dict[str, Any]]]:
+    """Build Feishu Table row data.
+
+    Args:
+        rows: Parsed table cell data.
+        columns: Column definitions (for type info).
+
+    Returns:
+        List of Feishu row dicts.
+    """
+    feishu_rows: List[List[Dict[str, Any]]] = []
+    for row in rows:
+        feishu_row: List[Dict[str, Any]] = []
+        for idx, cell in enumerate(row):
+            col_type = "text"
+            if idx < len(columns):
+                col_type = columns[idx].field_type
+
+            if col_type == "number":
+                # Try to parse as number for the value field
+                try:
+                    cleaned = cell.text.replace(",", "").replace("%", "").strip()
+                    num = float(cleaned)
+                    if num == int(num):
+                        num = int(num)
+                    feishu_row.append({"text": cell.text, "value": num})
+                except (ValueError, OverflowError):
+                    feishu_row.append({"text": cell.text})
+            else:
+                feishu_row.append({"text": cell.text})
+        feishu_rows.append(feishu_row)
+    return feishu_rows
+
+
+def build_table_card(
+    table: ParsedTable,
+    title: str = "📊 数据表格",
+    template: str = "blue",
+) -> Dict[str, Any]:
+    """Build a Feishu interactive card containing a Table component.
+
+    Args:
+        table: A parsed table from table_parser.
+        title: Card header title.
+        template: Card header color template (blue, wathet, turquoise, green,
+                  yellow, orange, red, carmine, violet, purple, indigo, grey).
+
+    Returns:
+        Complete Feishu card JSON dict.
+    """
+    columns = _build_table_columns(table.headers)
+    rows = _build_table_rows(table.rows, table.headers)
+
+    card: Dict[str, Any] = {
+        "config": {"wide_screen_mode": True},
+        "header": {
+            "title": {"content": title, "tag": "plain_text"},
+            "template": template,
+        },
+        "elements": [
+            {
+                "tag": "table",
+                "columns": columns,
+                "rows": rows,
+            }
+        ],
+    }
+
+    return card
+
+
+def build_content_card(
+    content: str,
+    title: Optional[str] = None,
+    template: str = "blue",
+) -> Dict[str, Any]:
+    """Build a Feishu card with markdown content (no table).
+
+    Used for non-table content that should be sent as a card.
+
+    Args:
+        content: Markdown content for the card body.
+        title: Optional card header title.
+        template: Card header color template.
+
+    Returns:
+        Complete Feishu card JSON dict.
+    """
+    card: Dict[str, Any] = {
+        "config": {"wide_screen_mode": True},
+    }
+
+    if title:
+        card["header"] = {
+            "title": {"content": title, "tag": "plain_text"},
+            "template": template,
+        }
+
+    card["elements"] = [
+        {
+            "tag": "markdown",
+            "content": content,
+        }
+    ]
+
+    return card
+
+
+def build_mixed_card(
+    markdown: str,
+    title: Optional[str] = None,
+    template: str = "blue",
+) -> Optional[Dict[str, Any]]:
+    """Build a Feishu card that handles mixed content (text + tables).
+
+    If the content contains tables, they are rendered as Table components.
+    Non-table text is rendered as markdown elements.
+
+    Args:
+        markdown: Full markdown content that may include tables.
+        title: Optional card header title.
+        template: Card header color template.
+
+    Returns:
+        Complete Feishu card JSON dict, or None if no tables found
+        (in which case use build_content_card or send as post message).
+    """
+    tables = parse_table(markdown)
+    if not tables:
+        return None
+
+    card: Dict[str, Any] = {
+        "config": {"wide_screen_mode": True},
+    }
+
+    if title:
+        card["header"] = {
+            "title": {"content": title, "tag": "plain_text"},
+            "template": template,
+        }
+
+    elements: List[Dict[str, Any]] = []
+    table_blocks, text_segments = split_table_and_text(markdown)
+
+    # Interleave text and table elements in original order
+    table_idx = 0
+    text_idx = 0
+
+    # Walk through the original markdown to maintain order
+    import re
+    _TABLE_BLOCK_RE = re.compile(
+        r"((?:^\|[^\n]+\|\s*\n"
+        r"^\|[\s:|-]+\|\s*\n"
+        r"(?:^\|[^\n]+\|\s*\n?)*)+)",
+        re.MULTILINE,
+    )
+
+    last_end = 0
+    for match in _TABLE_BLOCK_RE.finditer(markdown):
+        # Text before this table
+        before = markdown[last_end:match.start()].strip()
+        if before:
+            elements.append({
+                "tag": "markdown",
+                "content": before,
+            })
+
+        # Table element
+        if table_idx < len(tables):
+            table = tables[table_idx]
+            columns = _build_table_columns(table.headers)
+            rows = _build_table_rows(table.rows, table.headers)
+            elements.append({
+                "tag": "table",
+                "columns": columns,
+                "rows": rows,
+            })
+            table_idx += 1
+
+        last_end = match.end()
+
+    # Remaining text after last table
+    remaining = markdown[last_end:].strip()
+    if remaining:
+        elements.append({
+            "tag": "markdown",
+            "content": remaining,
+        })
+
+    card["elements"] = elements
+    return card
+
+
+def card_to_json(card: Dict[str, Any]) -> str:
+    """Serialize a card dict to JSON string.
+
+    Args:
+        card: Feishu card JSON dict.
+
+    Returns:
+        Compact JSON string (ensure_ascii=False for CJK support).
+    """
+    return json.dumps(card, ensure_ascii=False, separators=(",", ":"))