@larksuite/openclaw-lark v2026.4.8 → v2026.5.13 更新分析

> 2026-05-14 · 基于 npm 包 + GitHub commit 对比

版本路径

npm 序列：2026.4.8 → 2026.4.9 → 2026.4.10 → 2026.5.7 → 2026.5.12 → 2026.5.13

无 CHANGELOG 文件，GitHub tag 未维护。分析基于各版本 npm tarball 源码对比 + GitHub git log。

核心变化摘要

类别	变化
🔐 密钥管理	SecretRef contract 注册，运行时自动解析 secrets
🛠️ 工具合约	40+ Feishu 工具在 plugin manifest 中声明
📞 VC 会议邀请	支持 `vc.bot.meeting_invited_v1` 事件处理
👤 @提及规范化	outbound `` 标签重写 + @Name 解析
📋 任务 Agent	飞书任务 Agent 注册与管理
⚠️ 空消息防护	空消息防护 & 媒体下载重试
🤖 Bot-to-Bot @提及	支持 bot 之间互 @
🏗️ 卡片交互重构	重构为统一交互分发管道
🔄 兼容性修复	`zalouser` → `command-auth`；peerDep 升至 `>=2026.5.4`

一、密钥管理：SecretRef Contract（PR #507）

新增文件：secret-contract-api.js + .d.ts


const SECRET_FIELDS = ['appSecret', 'encryptKey', 'verificationToken'];

在 openclaw.json 中标记以下字段为 SecretRef 类型：

账号级：channels.feishu.accounts.*.{appSecret, encryptKey, verificationToken}
顶级：channels.feishu.{appSecret, encryptKey, verificationToken}

其中 encryptKey 和 verificationToken 仅在 webhook 模式下使用。

效果：OpenClaw 运行时在启动时自动解析这些 secrets，支持 secret:// 引用，不再需要明文存储敏感信息。通过 collectRuntimeConfigAssignments() 收集实际赋值注入运行时。

同时，index.js 入口注册了 secretTargetRegistryEntries 和 collectRuntimeConfigAssignments。

二、工具合约配置（PR #470）

openclaw.plugin.json 新增 contracts.tools 字段，声明了 40 个 Feishu 工具合约：

类别	工具
多维表格	feishu_bitable_app / table / table_field / table_record / table_view
日历	feishu_calendar_calendar / event / event_attendee / freebusy
聊天	feishu_chat / chat_members
文档	feishu_create_doc / doc_comments / doc_media / fetch_doc / update_doc
云盘	feishu_drive_file
IM	feishu_im_bot_image / im_user_fetch_resource / im_user_get_messages / im_user_get_thread_messages / im_user_message / im_user_search_messages
鉴权	feishu_oauth / oauth_batch_auth
搜索	feishu_search_doc_wiki / search_user
表格	feishu_sheet
任务	feishu_task_comment / task_subtask / task_task / task_agent / task_attachment / task_tasklist / task_section
知识库	feishu_wiki_space / wiki_space_node
其他	feishu_get_user / feishu_ask_user_question

新增工具（相对 v2026.4.8）：

feishu_task_agent — 任务 Agent 注册
feishu_task_attachment — 任务附件
feishu_ask_user_question — 向用户提问

影响：工具合约是 OpenClaw runtime 的 tool gateway 机制——gateway 按需将这些工具暴露给 agent，实现 Feishu API 与 agent 的解耦调用。

三、VC 会议邀请处理（PR #449 / #475）

新增文件：

src/messaging/inbound/vc-meeting-invited-handler.js
src/messaging/inbound/vc-sender.js
src/core/synthetic-target.js

处理 vc.bot.meeting_invited_v1 事件。当飞书机器人被邀请进视频会议时，将该事件转换为合成自然语言消息，通过标准 agent 管道分发。

Synthetic Target 模式


会议邀请事件 → 解析 inviter 身份 → 创建合成 inbound 消息 → dispatchToAgent → agent 回复

关键设计：

使用 "synthetic:vc-invited" 作为 sentinel chatId，outbound deliverer 遇到此前缀时短路，不尝试发送 IM 消息
resolveVcSender() 提供确定的 sender 解析链：inviter.id.open_id → user_id → union_id，缺失时跳过事件

交互优化

PR #475 将会议加入提示改为 tool-agnostic（不绑定特定 tool 的实现），在 PR #449 的基础上做了通用化改造。

四、@提及规范化（PR #486 / #477）

新增文件：src/messaging/outbound/normalize-mentions.js

Outbound @提及标签重写


<!-- 输入：多种变体 -->
<at id="ou_xxx">
<at open_id="ou_xxx">
<at user_id="ou_xxx">

<!-- 输出：统一规范格式 -->
<at user_id="ou_xxx">Name</at>

id=all → Everyone
选择器标签保持不变

@Name 解析

出站文本中的裸 @Name（如 @张三）通过用户名缓存查找，链路：

1. 查本地 UserNameCache → 匹配成功直接替换

2. 缓存 miss → 拉取 chat member list → 重试

3. 匹配多个 → 记录 ambiguous sentinel → 下次 inbound 时让 agent 做消歧

Bot-to-Bot @提及（PR #477）

支持 bot 之间用 @ 互相提及，bot 名称从 chat member list 的 bot 列表中解析。

Sentinel Store

新增文件：src/messaging/inbound/sentinel-store.js

独立的 per-thread store，用于暂存未解析的 @Name（10 分钟 TTL），与 UserNameCache 生命周期解耦：


outbound 遇到无法解析的 @Name → 记录 sentinelEntry
next inbound 同一 thread → consume sentinelEntry → buildMentionAnnotation → 系统提示 → agent 消歧

五、Task Agent 工具（PR #451）

新增文件：src/tools/oapi/task/task_agent.js

支持飞书任务 Agent 注册管理：

Action	功能
`register`	注册任务 Agent（tenant 身份）
`update_profile`	更新 Agent 资料

配套新增 src/tools/oapi/task/attachment.js（任务附件操作）。

六、卡片交互重构（PR #395）

合并自 chenxiaoyufisher-hash/feat/add_card_action：

重构卡片交互处理逻辑，使用标准交互分发管道
统一代码引号格式
更新 openclaw 依赖

此前卡片交互处理是分散在不同模块里的，重构后通过集中管道路由，为后续新增交互类型提供了基础。

七、兼容性 & 依赖变化

zalouser → command-auth（commit 78231a7）


// before
import { ... } from "openclaw/plugin-sdk/zalouser";
// after
import { ... } from "openclaw/plugin-sdk/command-auth";

原因：OpenClaw 2026.4.27 移除了 plugin-sdk/zalouser 导出路径。

依赖变化

依赖	v2026.4.8	v2026.5.13
openclaw (peer)	`>=2026.3.22`	`>=2026.5.4`
undici-types	❌ 无	✅ `^8.1.0`
其他 deps	`@larksuiteoapi/node-sdk ^1.60.0`、`@sinclair/typebox 0.34.48`、`image-size ^2.0.2`、`zod ^4.3.6`	不变

ask-user-question 修复（commit 73ca0c6）

为 ask-user-question 提交按钮添加 value 字段，解决 Feishu 端报 200340 错误的问题。

空消息防护 & 媒体重试（PR #495）

空消息防护（empty message guard）：防止处理空消息导致异常
媒体下载重试（media download retry）：媒体资源下载失败时自动重试

Footer Metrics（PR #504）

修复 routed agent 场景下的 footer metrics session store 解析——正确传递 agentId。

八、构建 & 发布

项目	v2026.4.8	v2026.5.13
构建工具	tsdown	tsdown
打包管理	[email protected]	[email protected]
构建输出	dist/ (ESM)	dist/ (ESM)，新增 secret-contract-api.js
发布流程	`node scripts/release.mjs`	`node scripts/release.mjs`

版本演进脉络

版本	主要变化
2026.4.9	添加 `undici-types` 依赖
2026.4.10	card action 重构 + zalouser → command-auth 兼容性修复 + ask-user-question 修复
2026.5.7	VC meeting invite 处理 + synthetic target + 任务 Agent 工具
2026.5.12	Bot-to-bot @提及 + outbound mention 规范化 + sentinel store
2026.5.13	SecretRef contract（密钥安全） + 空消息防护 & 媒体重试 + tool gateway 合约配置 + peerDep 升至 `>=2026.5.4` + footer metrics 修复

质量问题

1. 无 CHANGELOG：GitHub 仓库没有维护 CHANGELOG.md，所有版本变化靠 git log + npm tarball 反推

2. Git tag 缺失：npm 已发布到 v2026.5.13，但 GitHub 仓库无对应 tag

3. 旧版本兼容中断：zalouser import 移除意味着 v2026.4.10+ 不再兼容 OpenClaw < 2026.4.27；peerDep 升至 >=2026.5.4 进一步缩小兼容范围