Feishu Card Sender

通过飞书 OpenAPI 发送卡片消息（interactive card），支持模板化 JSON 卡片与变量替换。用于用户要求“发送飞书卡片/模板消息/互动卡片”时，或需要把结构化通知发到指定 open_id/chat_id 时。该技能只走 OpenAPI（appid/appsecret + tenant_acc...

Security Scan

The skill is mostly what it claims (send Feishu interactive cards and handle callbacks) but its code reads local OpenClaw config, spawns an HTTP callback server, uses un-declared binaries/env/config paths, and persists snapshots — the declared metadata and instructions don’t fully describe these behaviors.

Purpose & Capability

The skill's name/description (send Feishu cards) matches the code and templates. However the code expects to load app credentials from /root/.openclaw/openclaw.json and to operate as a callback-handling service; these config-access and callback behaviors are not reflected in the registry metadata (which lists no required config paths or primary credential). That mismatch is notable but could be legitimate for an OpenClaw-hosted skill.

Instruction Scope

SKILL.md focuses on running scripts/send_feishu_card.py and template usage, but the package includes multiple server/worker scripts: an HTTP callback worker (binds 0.0.0.0:18081), enqueue/queue workers, sqlite snapshot storage, and a finalize/router that reads openclaw.json and patches messages. Those runtime behaviors (listening on network, persistent queue/db, reading host config) are not fully described as required runtime actions in the metadata and grant broader access than a simple send-only tool.

Install Mechanism

There is no install spec (instruction-only), which is low-risk. However the code invokes external commands (openssl via subprocess) and expects system binaries (python3, openssl) without declaring them. That dependency-on-external-binaries is not documented in the registry metadata.

Credentials

The skill will use Feishu app id/secret (described in SKILL.md) but also un-declared environment variables (FEISHU_CALLBACK_ENCRYPT_KEY, FEISHU_CALLBACK_USER_FALLBACK, FEISHU_CALLBACK_ACCOUNT_ID, MAX_SKEW_SECONDS) and reads /root/.openclaw/openclaw.json for accounts. The registry declares no required env or config paths — yet the code reads host config (which may contain multiple channel credentials). Access to that file and stored secrets is higher privilege than the metadata indicates.

Persistence & Privilege

The skill writes persistent state (tmp queue files, sqlite DB under /root/.openclaw/workspace-dev/..., metric logs) and includes a network listener (callback worker binding 0.0.0.0:18081). It is not marked always:true, but it does request ongoing presence and ability to accept inbound callbacks and to read host config — this is more persistent and privileged than a one-shot sender.

What to consider before installing

This package appears to implement the advertised Feishu card sending and callback-handling features, but it makes several assumptions and performs host-level actions that the registry metadata does not declare. Before installing or running it, consider: - Credentials and config: the code reads /root/.openclaw/openclaw.json to obtain appId/appSecret (and will fall back to FEISHU_APP_ID/FEISHU_APP_SECRET). Ensure you are comfortable with the skill reading that file (it may contain other channel credentials). - Persistent services & data: the package can run a callback HTTP server (0.0.0.0:18081), enqueue worker, and a sqlite DB storing raw card JSON and message_id. If you only need sending, avoid running the callback worker and queue processes. - Undeclared binaries/env: the code calls openssl via subprocess for decryption and relies on environment variables (e.g., FEISHU_CALLBACK_ENCRYPT_KEY). The registry metadata does not list these requirements — verify that your runtime has these binaries and that you supply or withhold env vars intentionally. - Network reachability: the callback worker expects to be reachable by Feishu (DNS/HTTPS/reverse proxy). Exposing a listener increases attack surface; run it in a controlled network or container and restrict inbound access if possible. - External integrations: callback handlers mention MoviePilot APIs; inspect subscribe_callback_handler.py to confirm what external endpoints it calls and whether those calls are appropriate for your deployment. If you trust the code and intend to use callbacks, run it in an isolated environment (container or restricted host) and provide only the explicit Feishu credentials you want used (or audit /root/.openclaw/openclaw.json first). If you only need one-off sends, prefer running scripts/send_feishu_card.py manually with explicit credentials and do not start the callback worker or background queue processes.

概览

用统一方式通过飞书 OpenAPI 发送卡片消息，避免每次手写 curl。 本技能固定使用 scripts/send_feishu_card.py（appid/appsecret 鉴权），不走 message 通道。

快速决策

1. 发送到当前会话用户 → 使用当前会话 sender_id 作为 --receive-id（open_id）
2. 发送到指定用户/群 → 显式传 --receive-id + --receive-id-type
3. 需要复用模板 → 把模板放到 assets/templates/*.json，再用 --template + 变量替换

发送方式：脚本发送（OpenAPI，唯一方式）

脚本：scripts/send_feishu_card.py

凭证

按以下优先级自动获取（从高到低）：

1. 命令参数：--app-id / --app-secret
2. 环境变量：FEISHU_APP_ID / FEISHU_APP_SECRET
3. OpenClaw 配置：/root/.openclaw/openclaw.json 的 channels.feishu.accounts
   • 可用 --account-id 指定账户（不传则取第一个）
   • 可用 --account-id current 自动读取会话上下文 account_id（从运行时环境变量 best-effort 获取）

常用命令

# 1) 列出内置模板
python3 scripts/send_feishu_card.py --list-templates

# 2) 用 movie 模板发送到 open_id（变量文件）
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"
python3 scripts/send_feishu_card.py \
  --template movie \
  --receive-id ou_xxx \
  --receive-id-type open_id \
  --vars-file references/vars.example.env

# 3) 直接指定模板文件 + 行内变量
python3 scripts/send_feishu_card.py \
  --template-file assets/templates/movie.json \
  --receive-id ou_xxx \
  --var title='星际穿越' \
  --var rating='8.7'

# 4) 只有海报 URL 时，自动上传飞书并注入 poster_img_key
python3 scripts/send_feishu_card.py \
  --template movie-custom \
  --receive-id ou_xxx \
  --receive-id-type open_id \
  --poster-url 'https://image.tmdb.org/t/p/original/xxx.jpg' \
  --var title='星际穿越' \
  --var overview='...'

变量替换规则

• 模板中占位符写法：${key}
• 变量来源（后者覆盖前者）：
  1. --vars-file（KEY=VALUE）
  2. 多次 --var key=value
• 未提供的变量保持原样，不报错（便于渐进调试）

参数规范（必读）

发送前先读：

• references/template-params.md（movie-custom）

• references/template-params-tv.md（tv-custom）

• 文档定义了每个模板的必填参数、字段含义、示例命令。

• cast（演员）字段必须按 Markdown 多行列表字符串传递。

文件结构

• scripts/send_feishu_card.py：获取 token、渲染模板、发送消息
• scripts/format_cast.py：把演员 JSON 自动转为 cast 字段字符串
• scripts/card_callback_router.py：卡片回调统一路由入口
• scripts/subscribe_callback_handler.py：处理“立即订阅”回调并写入 MoviePilot（含幂等）
• assets/templates/movie-custom.json：电影详情模板（movie）
• assets/templates/tv-custom.json：剧集详情模板（tv）
• assets/rules/*.rules.json：通用规则（支持 require_non_empty / default_value / 条件删减区块）
• references/vars.example.env：变量文件示例
• references/template-params.md：模板参数与传参格式规范

Card-Action 自动处理规则（方案 B）

当收到 Feishu 卡片回调消息时（message_id 形如 card-action-c-...，内容含 {"action":"subscribe"...}）：

1. 自动提取 callback_token（从 message_id 去掉 card-action- 前缀）
2. 自动执行：
   • 先延时更新卡片为“处理中...”并禁用
   • 执行 MoviePilot 订阅（幂等）
   • 再延时更新卡片为“✅ 已订阅”或“❌ 订阅失败，请重试”
3. 无需用户手动提供 token/account 参数

发送后回复约束

• 卡片发送成功后，默认不要再发“已发送 + message_id”的额外文本。
• 仅在用户明确要求回执时，才返回 message_id。

安全与约束

• 不在脚本里硬编码 App Secret
• 日志默认不打印密钥
• 失败时返回飞书原始错误码与错误信息，便于排障