消息通知 Backend Function 开发指南

本文面向第一次接触 Lovrabet 消息通知能力的开发者。读完后你可以照着步骤，从注册通知通道开始，独立开发、测试、发布一个向固定飞书群发送通知的 Backend Function，并（可选）把它封装成 Skill 交给 AI 调用。全文以生产环境真实在用的 sendFeishuNotification 为例。整个过程以 prompt 驱动：你只需把需求描述给 Agent，每个步骤会补充 Agent 实际调用的 rabetbase / lovrabet 语句。

0、功能描述

在飞书群里通过WebHook根据业务逻辑按需发送消息通知，示例截图：

一、先理解整体链路

一条通知从发起到落地经过四层，开发时只需要写中间那一层：

• 调用方：lovrabet bff exec 命令行、页面里的 SDK client、或其他 Backend Function，传入 title、body 等业务参数。
• Backend Function（要开发的部分）：一个 ENDPOINT 类型脚本，负责校验输入、把通道 configCode 等固定信息写死、组装消息体，然后调用通知扩展。
• notification 扩展：平台内置能力，通过 context.client.extension.execute("notification", "send", ...) 调用，按 configCode 找到对应的通知配置，渲染飞书卡片（标题 + 摘要 + Markdown 详情）并发出。
• 通知通道：在平台「消息通知」配置中预先注册好的飞书群机器人通道，每个通道对应一个 configCode。Endpoint 不直接碰 Webhook 和群 ID。

这样设计的好处：调用方只关心业务参数，换群、换通道只改平台配置，不用改代码。

二、开始前准备

• 准备好开发环境：确保 rabetbase 与 lovrabet CLI 已安装并完成登录（开发态用 rabetbase，运行态验证用 lovrabet）。没配好时直接对 Agent 说「帮我配置好 rabetbase 和 lovrabet 开发环境」，Agent 会完成安装与认证（对应 rabetbase auth login / lovrabet auth login）。
• 配置消息渠道

• 拿到通知配置的 configCode：在平台「消息通知」中注册渠道与通道后，对 Agent 说「查一下消息通知配置列表」，Agent 会调用 rabetbase notification config-list 返回 configCode，形如 ncc_xxxxxxxx。

三、开发步骤

第 1 步：创建 BFF 骨架

在带 .rabetbase 目录的应用仓库里，对 Agent 说：

帮我创建一个 ENDPOINT 类型的 Backend Function，函数名 sendXxxNotification，用于发送消息通知

Agent 会执行 rabetbase bff create --type ENDPOINT --name sendXxxNotification 完成创建。生成的脚本位于 .rabetbase/bff/<appcode>/ENDPOINT/sendXxxNotification.js，这个文件就是源码，直接编辑。

第 2 步：描述通知需求，让 Agent 实现

这一步同样由 Agent 完成，你只需把需求说清楚：

实现 sendXxxNotification：接收 title、body、summary（可选）、atUserIds（可选）四个参数；
校验输入合法性；把目标飞书群的 configCode 写死在脚本里，不允许调用方传渠道参数；
组装 {title, summary, theme, detailMarkdown} 消息体并调用 notification 扩展发送；
返回 {sent, channelType, message, mentionCount}。

Agent 会按以下契约实现，这份清单同时是完成后的 review 核对项：

• 校验输入：title 必填、单行、1–100 字符；body 必填、1–4000 字符、禁止手写 <at> 标签；summary 可选、单行、1–200 字符；atUserIds 可选数组、最多 20 个飞书 Open ID、去重、拒绝 all。所有校验失败抛 INVALID_PARAMS:...。
• 写死固定配置：目标通道的 configCode 作为常量写在脚本里，不允许调用方传入 configCode、Webhook、群 ID 等渠道参数——这是安全边界。
• 组装消息体：{ title, summary, theme, detailMarkdown }。summary 不传时由 body 自动压缩生成；有 @ 人时在 detailMarkdown 头部拼接 <at id="ou_xxx"></at>。
• 调用扩展并返回：context.client.extension.execute("notification", "send", { configCode, message })，返回 { sent, channelType, message, mentionCount }。

核心代码骨架（供 review 参考）：

const FEISHU_CONFIG_CODE = "ncc_xxxxxxxx"; // 固定通道

export default async function sendXxxNotification(params, context) {
  const title = normalizeTitle(params?.title);
  const body = normalizeBody(params?.body);
  const atUserIds = normalizeAtUserIds(params?.atUserIds);
  const summary = normalizeSummary(params?.summary) || buildSummary(body);
  const result = await context.client.extension.execute("notification", "send", {
    configCode: FEISHU_CONFIG_CODE,
    message: { title, summary, theme: "blue", detailMarkdown: buildDetailMarkdown(body, atUserIds) },
  });
  return {
    sent: result?.sent === true,
    channelType: result?.channelType || "FEISHU",
    message: result?.message || "通知发送成功",
    mentionCount: atUserIds.length,
  };
}

第 3 步：推送到平台

对 Agent 说：

把 sendXxxNotification 这个 Backend Function 推送到平台

Agent 会先执行 rabetbase bff push --type ENDPOINT --name sendXxxNotification --dry-run 预览，确认后执行 rabetbase bff push --yes 正式推送（high-risk-write）。

推送成功后平台自动清理运行时脚本缓存，改动即时生效；本地 .rabetbase/bff.lock.json 记录脚本 hash、remoteId 和版本号，后续推送靠它做变更检测。

第 4 步：运行态验证

对 Agent 说：

调用 sendXxxNotification 发一条测试消息，验证能否正常发送

Agent 会执行 lovrabet bff exec --appcode <appcode> --name sendXxxNotification --params '...' 真实发送一条消息；--params 由 Agent 用 JSON 序列化器生成。

只有返回 sent: true 且 channelType: FEISHU 才算成功。验证会真实发到群里，控制次数。

第 5 步（可选）：封装成 Skill 交给 AI 调用

如果希望同事直接对 AI 说「发个飞书通知：……」就能用，对 Agent 说：

把这个通知能力封装成 Skill 并推送到公司空间，让同事可以直接让 AI 向本群发通知。
然后把skill推送到Lovrabet平台

Skill 本质是一个 SKILL.md 文件，写清四件事就够了：

• 调用谁：固定写死 appcode 和 Backend Function 名，调用方不需要知道通道配置。
• 入参契约：每个参数的含义与规则，如 title 单行 1–100 字符、body 支持 Markdown、atUserIds 传飞书 Open ID。
• 发送决策：默认先把文案给用户确认，确认后才发送，避免误发。
• 文案规范：直接讲内容、不寒暄，涉及文档或需求时附链接。

写完后 Agent 会执行 lovrabet skill push --scope company 提交审核；同事安装时对 Agent 说「安装这个 skill」即可（对应 lovrabet skill install --code <skill-code> --appcode <appcode>）。

四、总结

开发一个消息通知 Backend Function 的完整路径：创建 BFF 骨架 → 用自然语言描述需求让 Agent 实现 → 推送到平台 → 运行态验证。四步完成后，通知能力即可在运行态应用中使用；如果希望同事也能通过一句话让 AI 发通知，再额外封装成 Skill 推送到公司空间即可。