飞书卡片消息

提供专业级飞书interactive卡片消息发送，支持多模板、自动Token管理、错误处理及群组和单聊推送功能。

Security Scan

代码和运行说明主要匹配“飞书卡片发送”功能, 但包元数据没有声明所需的敏感环境变量（FEISHU_APP_ID/FEISHU_APP_SECRET）且文档包含“绕过OpenClaw内置限制”的措辞，存在不一致和可疑点，建议在信任前进一步审计与限制凭证权限并检查安装脚本与周期任务实现。

Purpose & Capability

包名、描述和大多数源文件确实实现了飞书(Lark) interactive 卡片构建与发送功能 — Python 实现直接调用 open.feishu.cn 的 OpenAPI，JS 部分也提供发送/统计等模块。总体功能与声明一致。异常点：注册表元数据声明“Required env vars: none / Primary credential: none”，但代码和 SKILL.md 明确要求 FEISHU_APP_ID 与 FEISHU_APP_SECRET（或通过构造函数传入），这与元数据不符，降低对包来源与意图的信任度。

Instruction Scope

SKILL.md 与示例代码限定在构建卡片、验证大小、获取 tenant_access_token 并调用飞书 API；没有看到指示读取系统中其它敏感文件或任意文件路径。需要注意的地方：SKILL.md 中多次强调“绕过OpenClaw内置限制”，为模糊措辞，可能意味着尝试规避平台策略（需要额外核实）。此外文档建议运行 ./scripts/install.sh（存在于包内）——应检查该脚本实际行为。

Install Mechanism

注册表没有声明安装规范（instruction-only），降低了直接写盘的风险；源码附带 scripts/install.sh、package.json（含 axios、crypto-js）与示例。没有发现从不可信 URL 下载或可疑短链接。建议在安装前审阅 scripts/install.sh 与 package.json 脚本以确认不会执行额外网络/系统更改。

Credentials

现实需要的凭据（FEISHU_APP_ID、FEISHU_APP_SECRET）在 SKILL.md 与代码中明确被使用，但注册表要求部分没有列出这些环境变量或任何主凭证。这是明显不一致：技能需要对云服务的应用密钥（高价值凭证），但元数据未声明，用户在安装或授权前不会被充分告知。

Persistence & Privilege

技能没有声明 always:true，默认不会被强制常驻。StatsTracker 类启动周期性任务（startPeriodicTasks），源码被截断但表明在内存中收集统计并可能有周期任务；需要审查这些周期任务是否会把统计或凭证上报到外部端点或写入磁盘。总体没有证据表明修改其他技能或系统级配置，但周期任务和日志上报应被检查。

What to consider before installing

要点与建议： 1) 不一致性告警：此技能的元数据没有声明需要的环境变量，但 SKILL.md 和代码明确需要 FEISHU_APP_ID 和 FEISHU_APP_SECRET。不要在未核实前把有效生产凭证放入环境。使用前假设该技能会使用这些密钥与飞书 API 交互。 2) 检查安装脚本和周期任务：在运行 ./scripts/install.sh 或任何示例前，打开并人工审阅该脚本内容；审查 StatsTracker.startPeriodicTasks 或其它定时任务（源码被截断）以确认不会把统计或凭证发到未预期的外部服务。 3) 最小权限与隔离测试：若要试用，请在受限/沙箱环境中进行（使用测试账号/最小权限的 App 凭证），并在验证无异常行为后再用于生产。尽量对 App 只授予 im:message:send_as_bot 所需的最小范围，并确保凭证可随时撤销/轮换。 4) 源与完整性验证：技能来源显示为 unknown 且 homepage 为 none。优先选择有可追溯仓库/维护者的包；如果可能，从公开仓库（如 README 中提到的 GitHub 链接）拉取并核对提交历史与维护者信息。 5) 若你希望我继续：我可以（a）审阅 scripts/install.sh 与被截断的周期任务函数（提供剩余文件），或（b）帮助生成安全审计清单与沙箱测试步骤，或（c）指引如何在部署前检查并有限制地注入凭证。

Feishu Card Sender Skill

飞书卡片消息发送技能包 - 专业级interactive卡片发送解决方案

🎯 功能概述

本技能包提供完整的飞书interactive卡片发送能力，绕过OpenClaw内置限制，直接调用飞书OpenAPI实现专业级卡片消息发送。

✨ 核心特性

• 完整API支持: 直接调用飞书OpenAPI，支持所有卡片类型
• Schema 2.0标准: 严格遵循飞书interactive卡片规范
• 多种卡片模板: 新闻简报、机票特价、任务管理、基础信息等
• 智能错误处理: 完整的异常捕获和错误码处理机制
• 大小自动验证: 30KB限制自动检测，避免发送失败
• Token自动管理: tenant_access_token自动获取和缓存
• 群组/单聊支持: 同时支持群组和一对一私人消息

🛠️ 核心工具

1. 高级卡片发送器 (feishu_card_sender_advanced.py)

from feishu_card_sender_advanced import AdvancedFeishuCardSender

sender = AdvancedFeishuCardSender(app_id, app_secret)
result = sender.send_simple_card(
    receive_id="ou_xxx",
    receive_id_type="open_id", 
    title="🎯 测试卡片",
    content="**精彩内容**展示"
)

2. 基础发送器 (direct_feishu_card_sender.py)

from direct_feishu_card_sender import FeishuCardSender

sender = FeishuCardSender(app_id, app_secret)
card = sender.build_interactive_card("标题", "内容")
result = sender.send_interactive_card("ou_xxx", "open_id", card)

3. 卡片模板库 (feishu_card_templates.py)

from feishu_card_templates import (
    build_news_card,
    build_flight_deal_card,
    build_task_management_card
)

# 新闻简报卡片
news_card = build_news_card([
    {"category": "国际新闻", "title": "重大事件", "source": "路透社", "time": "2024-02-28 15:30"}
])

# 机票特价卡片
flight_card = build_flight_deal_card({
    "route": "上海 → 东京",
    "price": 899,
    "original_price": 2500,
    "date": "2024-03-15",
    "discount": "3.6折"
})

📋 支持的卡片类型

📰 新闻简报卡片

• 多段落布局
• 时间线展示
• 来源标注
• 分隔线组织

✈️ 机票特价卡片

• 双列字段布局
• 价格对比显示
• 折扣信息突出
• 预订按钮集成

📊 任务管理卡片

• 进度状态指示
• 多字段信息展示
• 优先级颜色标识
• 操作按钮支持

🎯 基础信息卡片

• 简洁标题+内容
• 主题颜色选择
• 图标装饰支持
• 灵活内容布局

🔧 使用方法

环境配置

export FEISHU_APP_ID="your_app_id"
export FEISHU_APP_SECRET="your_app_secret"

快速开始

# 导入发送器
from feishu_card_sender_advanced import AdvancedFeishuCardSender

# 初始化发送器
sender = AdvancedFeishuCardSender(
    app_id="cli_xxx",
    app_secret="your_secret"
)

# 发送基础卡片
result = sender.send_simple_card(
    receive_id="ou_xxx",
    receive_id_type="open_id",
    title="🎉 欢迎使用",
    content="**飞书卡片**发送成功！"
)

print(f"消息ID: {result['message_id']}")

高级用法

# 构建复杂卡片
card = sender.build_news_card([
    {
        "category": "科技新闻",
        "title": "AI技术突破",
        "source": "TechNews",
        "time": "2024-02-28 16:00"
    },
    {
        "category": "财经动态",
        "title": "市场分析",
        "source": "财经网",
        "time": "2024-02-28 15:30"
    }
])

# 发送到群组
result = sender.send_interactive_card(
    receive_id="oc_xxx",
    receive_id_type="chat_id",
    card=card
)

🎨 卡片设计指南

颜色主题

• blue: 蓝色主题（信息类）
• green: 绿色主题（成功类）
• red: 红色主题（警告类）
• yellow: 黄色主题（提醒类）
• grey: 灰色主题（中性类）

内容格式

• 支持Markdown语法
• 支持@用户功能
• 支持超链接
• 支持emoji图标
• 支持代码块

布局建议

• 标题简洁明了
• 内容层次清晰
• 重要信息突出
• 按钮操作明确

⚠️ 注意事项

1. 权限要求: 需要im:message:send_as_bot权限
2. 大小限制: 卡片内容不超过30KB
3. 频率限制: 5 QPS（每秒5次）
4. 用户范围: 接收者必须在应用可用范围内
5. 群组要求: 机器人必须在目标群组中

🔍 错误处理

常见错误码及解决方案：

• 230013: 用户不在应用可用范围内 → 检查应用权限设置
• 230002: 机器人不在群组中 → 将机器人添加到群组
• 230099: JSON格式错误 → 检查卡片结构是否正确
• 230020: 频率限制 → 降低发送频率
• 230025: 内容超出大小限制 → 简化卡片内容

📚 相关资源

• 飞书API文档
• Interactive卡片格式
• OpenClaw飞书扩展源码

🚀 更新日志

v1.0.0 (2026-02-28)

• ✅ 基础卡片发送功能
• ✅ 多种卡片模板支持
• ✅ 错误处理机制
• ✅ 大小验证功能
• ✅ 群组和单聊支持
• ✅ 完整文档和使用指南

---

技能状态: 生产就绪 ✅
维护状态: 活跃维护 🔄
最后更新: 2026-02-28