飞书卡片免费版

版本: 1.0.0 适用对象: 个人用户、独立开发者、一人公司 核心定位: 飞书富文本卡片消息构建与发送基础工具

概述

飞书卡片免费版是一款帮助个人用户向飞书（Lark）用户或群组发送富交互卡片消息的工具。支持在卡片中渲染 Markdown 内容（代码块、表格、列表）、设置标题与彩色头部、添加底部操作按钮以及嵌入本地图片，让消息展示更加丰富专业。

工具特别解决了命令行环境下特殊字符（如反引号）被 shell 吞掉的常见问题，提供安全发送模式通过临时文件自动处理内容传递，确保 Markdown 代码块等内容完整传递。同时支持多种消息风格（Persona），可按不同场景选择合适的展示样式。免费版聚焦个人用户的卡片消息发送需求，配置简洁、使用便捷。

核心能力

卡片消息发送

目标对象: 支持用户 Open ID（ou_...）与群组 Chat ID（oc_...）
简单文本: 直接发送纯文本内容
文件内容: 从文件读取内容发送（推荐，支持完整 Markdown）

输入: 用户提供卡片消息发送所需的指令和必要参数。处理: 按照skill规范执行卡片消息发送操作,遵循单一意图原则。输出: 返回卡片消息发送的执行结果,包含操作状态和输出数据。

Markdown 渲染

代码块（支持语法高亮）
表格
有序/无序列表
加粗、斜体、行内代码
链接

输入: 用户提供Markdown 渲染所需的指令和必要参数。处理: 按照skill规范执行Markdown 渲染操作,遵循单一意图原则。输出: 返回Markdown 渲染的执行结果,包含操作状态和输出数据。

卡片样式

标题: 自定义卡片头部标题
彩色头部: 蓝/红/橙/绿/紫/灰六种颜色
底部按钮: 文本按钮 + 跳转链接

输入: 用户提供卡片样式所需的指令和必要参数。处理: 按照skill规范执行卡片样式操作,遵循单一意图原则。输出: 返回卡片样式的执行结果,包含操作状态和输出数据。

图片支持

本地图片上传
图片嵌入卡片
自动获取 image_key

输入: 用户提供图片支持所需的指令和必要参数。处理: 按照skill规范执行图片支持操作,遵循单一意图原则。输出: 返回图片支持的执行结果,包含操作状态和输出数据。

安全发送

自动创建临时文件处理特殊字符
自动清理临时文件
避免反引号等字符被 shell 吞掉

输入: 用户提供安全发送所需的指令和必要参数。处理: 按照skill规范执行安全发送操作,遵循单一意图原则。输出: 返回安全发送的执行结果,包含操作状态和输出数据。

人设消息

多种消息风格切换
自动添加主题化头部与格式
不同场景适用不同风格

输入: 用户提供人设消息所需的指令和必要参数。处理: 按照skill规范执行人设消息操作,遵循单一意图原则。输出: 返回人设消息的执行结果,包含操作状态和输出数据。 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：飞书富文本卡片消、息构建工具、与按钮交互、飞书卡片免费版是、一款面向个人用户、的飞书卡片消息构、建与发送工具、支持向飞书用户或、群组发送包含、按钮与图片的富交、互卡片消息、Use、when、需要生成营销文案、写作内容、标题优化、内容创作时使用、不适用于纯技术文、档撰写、适用于独立开发者、企业团队和自动化、工作流场景等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一：发送代码片段通知

向开发群发送包含代码块的技术通知。

# 将内容写入临时文件（避免反引号被吞）
write temp/msg.md "代码审查通知：
\`\`\`js
function greet(name) {
  console.log('Hello, ' + name);
}
\`\`\`
请各位review以上代码。"

# 使用文件发送卡片
node skills/feishu-card-builder/send.js \
  --target "oc_xxxxxxx" \
  --text-file "temp/msg.md" \
  --title "代码审查通知" \
  --color blue

场景二：发送带按钮的引导消息

向用户发送带操作按钮的引导卡片。

# 安全发送带按钮的卡片
node skills/feishu-card-builder/send_safe.js \
  --target "ou_xxxxxxx" \
  --text "您的报告已生成，请点击下方按钮查看。" \
  --title "报告生成完成" \
  --color green \
  --button-text "查看报告" \
  --button-url "https://example.com/report/123"

场景三：发送带图片的展示卡片

上传本地图片并发送带图片的展示卡片。

# 发送带图片的卡片
node skills/feishu-card-builder/send.js \
  --target "oc_xxxxxxx" \
  --text "本周数据图表如下：" \
  --title "周报数据" \
  --color orange \
  --image-path "charts/weekly_chart.png"

快速开始

依赖详情

本工具依赖 feishu-common 模块提供 Token 与 API 认证：

# 确保已安装 feishu-common
# 配置飞书应用凭证（app_id 与 app_secret）

第二步：发送简单文本卡片

# 发送简单文本
node skills/feishu-card-builder/send.js --target "ou_xxxxxxx" --text "Hello World"

第三步：发送 Markdown 卡片（推荐）

对于包含特殊字符的内容，始终使用文件方式发送：

# 写入内容到文件
write temp/msg.md "这里有一些代码：
\`\`\`python
print('hello')
\`\`\`"

# 使用文件发送
node skills/feishu-card-builder/send.js --target "ou_xxxxxxx" --text-file "temp/msg.md"

第四步：使用安全发送模式

# 安全发送（自动处理临时文件）
node skills/feishu-card-builder/send_safe.js \
  --target "ou_xxxxxxx" \
  --text "包含 \`反引号\` 和 *markdown* 的内容" \
  --title "安全消息"

结果处理: 执行完成后,查看输出结果确认操作状态。成功时输出包含处理摘要和结果数据;失败时根据错误信息排查问题,查阅错误处理章节获取恢复步骤。

示例

最佳实践

内容传递安全

核心原则: 包含特殊字符（反引号、星号等）的内容，始终使用文件方式发送。

# 错误做法：直接用 --text 传递含反引号的内容
# node send.js --text "代码: `code`"  # 反引号会被 shell 吞掉

# 正确做法1：写入文件后用 --text-file 发送
write temp/msg.md "代码: \`code\`"
node skills/feishu-card-builder/send.js --target "ou_xxx" --text-file "temp/msg.md"

# 正确做法2：使用 send_safe.js 自动处理
node skills/feishu-card-builder/send_safe.js --target "ou_xxx" --text "代码: \`code\`"

Markdown 内容组织

# 结构化 Markdown 内容
write temp/report.md "## 本周进展

### 已完成
- 功能A开发完成
- Bug修复12个

### 进行中
- 性能优化

\`\`\`bash
# 部署命令
npm run deploy
\`\`\`"

node skills/feishu-card-builder/send.js \
  --target "oc_xxx" \
  --text-file "temp/report.md" \
  --title "周报" \
  --color blue

按钮设计

按钮文本简洁明确（不超过10个字）
链接确保有效可访问
一个卡片建议不超过2个按钮

图片使用

# 确保图片大小合理（建议不超过1MB）
ls -lh chart.png

# 发送带图片的卡片
node skills/feishu-card-builder/send.js \
  --target "oc_xxx" \
  --text "数据图表" \
  --image-path "chart.png" \
  --title "数据展示" \
  --color green

常见问题

问题1：Markdown 反引号被吞掉

发送的代码块显示不完整，反引号丢失

原因: Shell 会解析反引号作为命令替换。

解决: 使用文件方式或安全发送模式：

# 使用文件方式
write temp/msg.md "代码: \`code\`"
node skills/feishu-card-builder/send.js --target "ou_xxx" --text-file "temp/msg.md"

# 或使用安全发送
node skills/feishu-card-builder/send_safe.js --target "ou_xxx" --text "代码: \`code\`"

问题2：图片上传失败

解决: 检查图片路径与格式：

# 确认文件存在
ls -la path/to/image.png

# 确认格式支持（PNG/JPG）
file image.png

问题3：消息发送失败，提示认证错误

解决: 检查 feishu-common 配置：

# 确认 app_id 与 app_secret 配置正确
# 确认应用有发送消息权限
# 确认 target ID 正确（ou_ 开头为用户，oc_ 开头为群组）

问题4：按钮链接无法跳转

解决: 确保链接格式正确且可访问：

# 使用完整 URL
--button-url "https://example.com/page"

# 确认链接可访问
curl -I https://example.com/page

问题5：长内容被截断

解决: 飞书卡片有内容长度限制，超长内容建议拆分发送或使用文件附件：

# 拆分长内容
write temp/part1.md "第一部分内容..."
write temp/part2.md "第二部分内容..."

node send.js --target "oc_xxx" --text-file "temp/part1.md" --title "报告 (1/2)"
node send.js --target "oc_xxx" --text-file "temp/part2.md" --title "报告 (2/2)"

依赖说明

运行环境

Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
操作系统: Windows / macOS / Linux
Node.js版本: 16 及以上
网络环境: 需可访问飞书开放平台 API

第三方依赖

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供
Node.js	运行时	必需	官方网站下载安装
feishu-common	模块	必需	飞书通用认证模块
飞书应用	应用	必需	飞书开放平台创建应用
app_id/app_secret	凭证	必需	飞书应用配置页获取

API Key 配置

本工具通过飞书应用凭证（app_id 与 app_secret）进行认证
凭证由 feishu-common 模块统一管理
无需额外 API Key
应用需在飞书开放平台开通消息发送权限

可用性分类

分类: MD+EXEC（纯Markdown指令，部分功能需要 exec 命令行执行能力）
说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent执行 Node.js 脚本，完成飞书卡片消息的构建与发送

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

已知限制

本地运行，不支持多设备同步
当前为免费版本,如需完整功能请升级到付费版获取全部能力

Feishu Card Builder Free

安装到 Tokeny（自动）

SKILL.md