文档同步

本页由 plugins/adapters/lark/README.md 自动生成。请修改包内 README 后运行 pnpm sync:adapter-docs。

@zhin.js/adapter-lark

Zhin.js 飞书 / Lark 适配器（Plugin Runtime），通过 Runtime Host HTTP Webhook 收发消息。

功能

• Webhook 事件接收（httpHostToken POST + 可选 verificationToken / encryptKey 签名）
• URL 验证挑战（url_verification）
• Tenant Access Token 自动刷新
• 支持飞书与 Lark 国际版 API 基址
• canonical markdown 段编码为 interactive 卡片中的 lark_md
• 约定式 defineAdapter / definePlugin（无需 usePlugin）

安装

pnpm add @zhin.js/adapter-lark

Plugin Runtime

• @zhin.js/adapter — 约定式 adapters/lark/index.ts（defineAdapter）
• @zhin.js/core — Endpoint.emit(...) 入站、outboundMessageToken 出站
• @zhin.js/host-http — httpHostToken 注册 Webhook 路由（非 legacy host-router/Koa）
• zhin.js — plugin.ts（definePlugin）
• 配置经插件 schema.json 落到 plugins.<instanceKey>

入站：gateway.receive({ conversation, message: { conversation, id }, content: text, sender, metadata })
出站：send({ conversation, payload }) → im/v1/messages

入站 metadata.mentioned：未接线。消息事件的 mentions[] 元素含 id.open_id，但本适配器拿不到 bot 自身的 open_id——配置（appId / appSecret / id 等）不含 bot open_id，代码也未调用 bot/v3/info 获取应用信息，故无可靠判据比对 mentions。

前置条件

1. 在 飞书开放平台（或 Lark）创建企业自建应用
2. 获取 App ID、App Secret
3. 启用机器人能力并配置事件订阅 URL：https://your-domain/lark/webhook
4. Runtime Host（http）须已 listen，Webhook 才可达

必填字段（endpoints[i]）：id、appId、appSecret。

最小配置

# zhin.config.yml（Plugin Runtime）
plugins:
  lark:
    webhookPath: /lark/webhook          # 可选，默认 /lark/webhook
    isFeishu: true                      # 可选，默认 true
    # apiBaseUrl: https://open.feishu.cn/open-apis
    endpoints:
      - id: my-lark-bot
        appId: ${LARK_APP_ID}
        appSecret: ${LARK_APP_SECRET}
        # encryptKey: ${LARK_ENCRYPT_KEY}          # 可选
        # verificationToken: ${LARK_VERIFY_TOKEN}  # 可选

根插件 zhin.plugins（或项目图）需引用 @zhin.js/adapter-lark（instanceKey: lark）。

环境变量

变量	说明
LARK_APP_ID	示例中由 YAML ${LARK_APP_ID} 引用的 App ID；变量名可自行定义
LARK_APP_SECRET	示例中由 YAML ${LARK_APP_SECRET} 引用的 App Secret；变量名可自行定义

消息类型映射

飞书类型	入站 content（文本摘要）	出站 wire
text	原文	text
markdown	原文	interactive（lark_md）
image	[image]	image（需 file_key）
file	[file: name]	file
audio / video / sticker	[audio] / [video] / [sticker]	—
card	—	interactive

Agent 工具

tools/ 目录提供 get_user、群聊、管理员、上传文件等 Tool。工具声明 adapter: 'lark' 后，通过惰性的 context.$client 自动取得当前操作的 LarkClient；无需把 Endpoint id 暴露给模型。

平台权限（platform permit）

plugin.ts 在 generation setup 注册 src/platform-permit.ts checker，并在 dispose 注销；CapabilityIngress 与 ToolSystem 统一经 Core canAccessTool() 消费工具权限。

测试

pnpm --filter @zhin.js/adapter-lark build
pnpm --filter @zhin.js/adapter-lark test

故障排查

现象	排查
URL 验证失败	检查公网 HTTPS、webhookPath、verification token 与 encrypt key
Tenant Token 获取失败	检查 appId、appSecret 与应用版本是否已发布
群里 @机器人不触发 AI	当前无法可靠判定 bot open_id；使用显式 AI 前缀
能收不能发	检查机器人消息权限、可见范围与应用是否已加入群聊