前言¶
在飞书群里让 Agent 执行敏感操作（删文件、跑 shell、改配置）时，纯文本「是否继续」很难审计，也不符合「人在回路」的习惯。自己查飞书开放平台文档、拼 interactive 卡片 JSON、再接按钮回调，步骤多且容易漏字段。下面介绍 SkillHub 上的 feishubutton：把「带按钮的飞书消息卡片」和审批类交互的约定写进 Skill 包，方便 Agent 按同一套结构发卡片、解析回调。
这是什么¶
feishubutton 是社区发布的 Agent Skill（SkillHub 标识 @indiv-zhangwei/feishubutton，页面亦写作 @user_a5827f21/feishubutton），当前最新版本为 v1.0.1，作者为 盛通教育-张维。官方一句话说明为：feishu message button approve（飞书消息按钮审批）。
Skill 归类为 office-efficiency（办公效率），子类为 流程自动化。包内遵循通用 SKILL.md 格式，并附带 Python 源码与示例脚本；说明文档写明面向 Hermes Agent 在飞书侧发送带按钮的交互卡片，完整能力依赖 hermes_feishu_plugin 等飞书适配层。
SkillHub 页面显示 AI 评分约 4.3/5.0，科恩实验室与云鼎实验室安全扫描均为「安全，无风险」；元数据标注 requires_api_key: false。
核心功能¶
以下内容来自已安装的 v1.0.1 包内 SKILL.md 与 scripts/example.py，只列已写明的能力。
交互卡片与按钮¶
- 说明飞书 interactive 卡片的 JSON 结构：
config、header、elements（含markdown与action区块）。 - 归纳按钮类型：
primary（主操作）、default（次要）、danger（破坏性操作）。 - 约定按钮
value在点击后回传，例如审批场景中的hermes_action、approval_id、session_key、chat_id等字段。
审批与卡片工具（Python）¶
SKILL.md 对 src/ 中模块的职责描述如下：
| 模块 | 作用 |
|---|---|
approval.py |
带按钮的审批流：send_exec_approval()、处理回调 handle_card_action()、事后更新 update_approval_card() |
builder.py |
组装流式/完成态卡片、split_reasoning_text() 等 |
cardkit.py |
发送与 PATCH 更新交互卡片 |
scripts/example.py 提供可本地运行的示例函数，包括：
create_confirmation_card()：确认/取消双按钮卡片；create_approval_card()：展示待执行命令，并提供 Allow Once / Allow Session / Allow Always / Deny 四类按钮；parse_button_callback()、create_result_card()：解析回调与展示审批结果卡片。
运行示例（在 Skill 包目录下）：
python3 scripts/example.py
文档要求 Python 3.11+，并列出对 hermes_feishu_plugin 的依赖；未安装适配器时，示例仍以打印卡片 JSON 的方式演示结构。
安装与启用¶
通过 SkillHub CLI（推荐）¶
先确认本机是否已有 skillhub：
command -v skillhub && skillhub --version
未安装时可按 SkillHub 官方安装说明执行（完整安装示例）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安装 Skill 时必须用 --dir 指向当前 Agent 识别的 skills 目录，否则默认落在 ./skills/ 可能不会被加载。常见路径（摘自 SkillHub 安装文档）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下.agents/skills/
安装 feishubutton：
skillhub install feishubutton --namespace indiv-zhangwei --dir ~/.cursor/skills
将 ~/.cursor/skills 换成你实际使用的 Agent 目录即可。CLI 解析到的包名为 @indiv-zhangwei/feishubutton，安装后目录 slug 为 feishubutton。
通过对话让 Agent 安装¶
SkillHub 页面提供的提示词为：请 Agent 根据 SkillHub 安装说明 安装：
@indiv-zhangwei/feishubutton
Hermes 侧额外步骤¶
SKILL.md 中的安装说明还提到：将 Skill 目录放到 Hermes Agent 的 skills/social-media/ 下，并保证 src/ 可被 Hermes 引用；这与 SkillHub 通用 Agent 目录约定并行存在，部署 Hermes 时需按该文档核对路径。
典型用法¶
1. 发送带确认按钮的卡片¶
文档中的模式是构造卡片 dict，再通过飞书适配器以 interactive 消息发出（伪代码层次与 SKILL.md 一致）：
card = {
"config": {"wide_screen_mode": True},
"header": {
"title": {"content": "Confirm Action", "tag": "plain_text"},
"template": "orange"
},
"elements": [
{"tag": "markdown", "content": "Do you want to proceed?"},
{
"tag": "action",
"actions": [
{
"tag": "button",
"text": {"tag": "plain_text", "content": "Confirm"},
"type": "primary",
"value": {"action": "confirm"}
},
{
"tag": "button",
"text": {"tag": "plain_text", "content": "Cancel"},
"type": "danger",
"value": {"action": "cancel"}
}
]
}
]
}
# await adapter.send_card(chat_id, card)
2. 处理按钮回调¶
async def handle_callback(callback_data):
action = callback_data.get("action")
if action == "confirm":
pass # 执行业务确认逻辑
elif action == "cancel":
pass # 取消
审批类按钮则使用 hermes_action 等字段；scripts/example.py 中 create_approval_card() 展示了如何把命令预览与多档授权按钮写入同一张卡片。
3. 本地先看 JSON 结构¶
不连飞书时，可先跑示例脚本核对卡片是否符合预期，再接入真实 chat_id 与回调服务。
适用场景与注意¶
适合谁
- 已在飞书内运行 Agent（尤其是 Hermes + 飞书插件）的团队，需要在群里对危险操作做「点按钮」审批。
- 需要统一卡片 JSON、按钮类型与回调字段约定的开发者，希望 Agent 读 Skill 即可按同一模板生成消息。
限制与注意
- 平台绑定：Skill 明确面向飞书（Lark）；Discord、Telegram、Slack 需各自的消息组件格式，不能照搬 JSON。
- 运行时依赖：完整发送/更新卡片依赖
hermes_feishu_plugin与 Hermes 适配器；仅安装 Skill 到 Cursor 等客户端时，Agent 主要获得文档与示例代码指引，飞书连通性仍需你自行配置应用凭证与回调。 - 源码与 Hermes 集成：
src/approval.py等文件实现的是 Hermes 审批补丁逻辑，与独立脚本示例并存；集成前建议在目标环境验证 import 路径与插件版本。 - 版本：SkillHub 上 v1.0.1 变更说明为「append import py files」；升级后留意与本地 Hermes 目录是否冲突。
结尾¶
feishubutton 把飞书交互卡片、按钮类型和审批回调字段收敛成一份 Skill 说明和 Python 参考实现，适合在飞书群里做「消息按钮审批」类自动化。查阅详情、下载 Zip 或复制安装提示词，可打开 SkillHub 技能页：
- https://www.skillhub.cn/skills/feishubutton
- https://api.skillhub.cn/user_a5827f21/feishubutton（站点 API 入口；浏览器直接访问可能返回 405，技能元数据可通过
https://api.skillhub.cn/api/v1/skills/feishubutton查询）
