🍤 claw-fry-cards — 虾条卡片

OpenClaw 飞书 / Lark 通道插件：CardKit v2.0 流式消息 · 派发即建卡 · 打字机效果 · 统一指标面板 · 峰谷价标识

特性 · 安装 · 配置 · 面板功能 · 开发 · 相关项目 · 许可证

这是什么：一个飞书通道插件（替代官方 @larksuite/openclaw-lark / 内置 @openclaw/feishu），负责 OpenClaw Agent 的飞书消息收发，并用 CardKit v2.0 流式卡片呈现每一轮回复。
为什么存在：官方通道插件停更于 2026-07-16，未适配 OpenClaw 2.0（SDK 导出重构、会话存储迁移 SQLite），在新版网关上无法加载。本项目完成了 2.0 适配，并将流式卡片体验升级到 fry-cards 系列风格。

⚠️ 1.0 与 2.0 架构不同，切勿同时启用（两套卡片会互相冲突）。
2.0 前身 claw-lark-cards 已合并入本仓库并废弃，后续仅在此维护。

openclaw plugins uninstall openclaw-lark --force   # 按其实际目录名卸载

配置迁移：插件 ID 已更名为 claw-fry-cards，channels.feishu 配置不变，仅需将 plugins.entries.openclaw-lark 改为 plugins.entries.claw-fry-cards。

2.0 为通道插件，会替换官方通道。先卸载官方飞书通道（openclaw plugins uninstall feishu --force，注意该命令会删除 channels.feishu 配置，请备份后恢复），再安装本插件；1.0 的 hooks.allowConversationAccess 在 2.0 下不再需要。

• 💬 消息全覆盖：群聊 / 单聊收发、话题回复、消息搜索、图片 / 文件上传下载。
• 📄 云文档交互：云文档创建、更新、读取。
• 📊 多维表格：数据表 / 字段 / 记录 CRUD、批量操作、高级筛选、视图。
• 📈 电子表格：在线电子表格创建、编辑、查看。
• 📅 日历与任务：日程管理、参会人忙闲查询；任务 / 清单 / 评论全周期追踪。

• ⚡ 派发即建卡：用户消息到达 1 秒内建立“处理中”卡片，杜绝空白等待焦虑。
• ✍️ 打字机输出：基于 CardKit streaming_mode 客户端动画，回复文字流畅逐字上屏。
• 🎯 统一指标面板：完成态底部收归单一折叠面板，一行带全关键指标：🍤 ⇲模型 · 💭N · 🔧N · 上下文 (x%) · 🎫 输出 · ⏱️耗时。
• 🎨 状态感知边框：边框颜色随终态反馈变化（绿=完成 · 红=出错 · 黄=中断）；展开后清晰呈现思考过程与工具调用明细。
• ⏱️ 峰谷计费标识：按时间窗口自动切换 DeepSeek 等模型的显示名（如工作日高峰显示梁文锋⚡️、谷段显示梁文谷⚡️）。
• 🏷️ 灵活别名映射：大小写不敏感匹配，支持按星期、时段自动切换模型名称展示。
• 📊 原生会话指标：实时读取 OpenClaw agent transcript SQLite，准确统计 token 与上下文水位。

• 全面迁移 SDK 导入路径（openclaw/plugin-sdk → plugin-sdk/core 等 100+ 处）。
• 升级类型定义（ClawdbotConfig → OpenClawConfig），对齐运行时配置 API。
• 会话指标源自 SQLite 数据库提取，不再依赖已废弃的 sessions.json。
• 保留官方 TypeScript 构建链路，规范产出标准 ESM 产物。

环境要求：

• OpenClaw ≥ 2026.5.4（推荐 2026.9.4+，已在 Docker + 飞牛 fnOS 验证）
• Node.js ≥ 22

curl -fsSL https://raw.githubusercontent.com/techysy/claw-fry-cards/main/install.sh | bash

脚本将自动定位 OpenClaw CLI 并从 npm 拉取注册（可通过 FRY_VERSION=2.0.5 指定版本）。安装完成后需手动重启网关：

openclaw gateway restart

openclaw plugins install claw-fry-cards --force --accept-capabilities
openclaw gateway restart

git clone https://github.com/techysy/claw-fry-cards.git
cd claw-fry-cards
npm install --legacy-peer-deps
npm run build        # 产物输出至 dist/

openclaw plugins install . --force --accept-capabilities
openclaw gateway restart

⚠️ 若之前使用过官方通道，请先执行清理：openclaw plugins uninstall feishu --force 并移除 plugins.entries.feishu 配置项，防止宿主收敛机制自动回装旧版本。

在 ~/.openclaw/openclaw.json 中配置：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "feishu",
      "connectionMode": "websocket",
      "appId": "cli_xxxxxxxx",
      "appSecret": "xxxxxxxx",
      "dmPolicy": "open",
      "allowFrom": ["*"],
      "groupPolicy": "open",
      "groupAllowFrom": ["*"],
      "requireMention": true,
      "streaming": { "mode": "partial" }
    }
  },
  "plugins": {
    "entries": {
      "claw-fry-cards": {
        "enabled": true,
        "config": {
          "panel": {
            "unifiedPanelMinDuration": 5,
            "contextDisplayMode": "text",
            "peakValley": { "deepseek": { "peakName": "梁文锋⚡️", "valleyName": "梁文谷⚡️", "schedule": "deepseek" } },
            "modelAliases": { "mimo/mimo-v2.5": "小虾米" }
          }
        }
      }
    }
  }
}

⚠️ 注意：飞牛/本地部署请将凭据配置在 channels.feishu.* 下，勿混写至插件配置中。
飞牛 / 飞书开放平台应用须开通：im:message（消息收发）与 cardkit:card（卡片操作权限）。推荐采用 websocket 模式直连。

当 Agent 回复生成完成时，底部会自动注入统计面板。面板支持在 Control UI → 设置 → Claw Fry Cards 界面进行全中文可视化配置。

fields 面板字段（有序数组——数组顺序即标题从左到右的顺序，未列出的段不显示；删除整个字段则回落默认全字段顺序）：

// 只显示 模型名 · 缓存命中 · 输出 · 耗时，并按此顺序排列
"panel": { "fields": ["model", "cache", "output", "elapsed"] }

• 缺省（不配 fields）：等价于全字段，顺序 model → reasoning → tools → context → cache → output → speed → elapsed
• 空数组 []：标题只留 🍤，不显示任何指标段
• 无论是否列出，该段数据缺失时仍会自动省略（如无缓存计量则不显示 💾）

面板设置：在 Control UI → 设置 → Claw Fry Cards → 配置页 可视化编辑（全中文字段说明），存储于插件自有配置 plugins.entries.claw-fry-cards.config.panel——随插件版本化，不受宿主 schema 演化影响（旧位置 channels.feishu.panel 仍兼容读取）：

🔥 全部热更新：保存后网关自动检测并应用（agent 正忙时重载排队，干完自动生效），无需重启网关；正在生成的回复不受影响，下一条消息即用新值。

"panel": {
  "unifiedPanelMinDuration": 5,
  "contextDisplayMode": "text",
  "truncateModelName": true,
  "modelAliasesEnabled": true,
  "fields": ["model", "reasoning", "tools", "context", "cache", "output", "speed", "elapsed"]
}

面板模型名支持按时间窗自动切换显示——典型用途是 DeepSeek 的峰谷价标识（峰段梁文锋⚡️ / 谷段梁文谷⚡️，一眼看出当前计费档位），也适用于任何时段人设。

配置入口：Control UI → 设置 → Claw Fry Cards → 配置页，全部可视化编辑，无需手写 JSON：

• 匹配：键对完整模型名做大小写不敏感子串匹配，按插入顺序第一条命中即生效（mimo 命中 mimo/mimo-v2.5）
• 时间表（峰谷价专用预置）：deepseek（工作日 9:00–12:00 & 14:00–18:00 峰段）/ workday-918 / everyday-day / always-peak / custom
• 时段规则里 days 星期逐项选择（0=周日），start/end 为北京时间 HH:MM，支持跨午夜；规则都不命中时回落默认名称（即"其他时间"）
• 两种写法可共存：peakValley 运行时展开为等价时段规则，同键时 Model Aliases 手写条目优先；别名命中优先于 ⇲ 截断；Model Aliases Enabled 开关可整体关闭别名

"panel": {
  "peakValley": {
    "deepseek": { "peakName": "梁文锋⚡️", "valleyName": "梁文谷⚡️", "schedule": "deepseek" },
    "gemini":   { "peakName": "Gemini☀️",  "valleyName": "Gemini🌙",  "schedule": "workday-918" }
  },
  "modelAliases": {
    "deepseek": {
      "name": "梁文谷⚡️",
      "timeAliases": [
        { "days": [1, 2, 3, 4, 5], "start": "09:00", "end": "12:00", "name": "梁文锋⚡️" },
        { "days": [1, 2, 3, 4, 5], "start": "14:00", "end": "18:00", "name": "梁文锋⚡️" }
      ]
    },
    "mimo": "小虾米"
  }
}

指标来源是 agent transcript SQLite（~/.openclaw/agents/<agent>/agent/openclaw-agent.sqlite），模型名/token/上下文窗口由最近一轮 usage 事件解析；💾 缓存命中率 = 本轮 cacheRead/(input+read+write)，⚡ 速度 = 本轮 output ÷ 生成耗时（本轮 assistant 事件与前一条事件的时间戳差，不含工具执行段，>30 分钟视为异常省略）。显示哪些段与顺序由 panel.fields 有序数组决定；无论是否列出，该段数据缺失时都自动省略。老版本宿主无此库时统一面板自动省略指标段（详见 docs/compat-test-report.md）。

# 安装依赖
npm install --legacy-peer-deps

# 编译 ESM 产物 (dist/)
npm run build

# 运行自动化测试
npm test

# 类型安全检查
npm run typecheck

• 🍟 hermes-fry-cards — Hermes Gateway 飞书流式卡片插件
• 🕊️ feige-fry-cards — 跨 Agent 战报结果汇报插件
• 🌉 zcode-feishu-bridge — ZCode 会话转飞书流式卡片桥接器

• 上游归属：基于 larksuite/openclaw-lark（MIT），OpenClaw 2.0 基础适配归功于 @Mirr0ch1。
• 安全声明：OpenClaw 具备本地命令执行及自动化能力，飞书应用凭据切勿泄漏。建议将机器人作为私聊办公助手使用，加入公开群聊时需谨慎配置访问与审批策略。

MIT