Lark MCP Bot

Lark MCP AI代理机器人

是在Lark（Feishu）的租户内经由MCP（Model Context Protocol）自由操纵的AI代理机器人。使用GLM-4.7作为LLM。

🎯 特徴

• Lark API统合: @larksuiteoapi/node-sdk对较大场景进行渲染期间已观察到该故障
• MCP工具集成: @larksuiteoapi/lark-mcp将27个Lark API工具转换为GLM-4.7的Function Calling
• MCP工具过滤：仅启用所需工具以优化上下文性能
• GLM-4.7连携：通过Zhipu AI的GLM-4.7模型进行高精度的响应生成和自动的工具选择
• 会話履歴管理：每个聊天保持上下文（最多30条消息），长期对话自动汇总
• 增强的错误处理：自定义错误类、API速率限制时的自动重试（指数退避）、工具错误详细信息输出到聊天
• 结构化记录：JSON格式的日志、日志级别设置、性能度量
• 提示管理: src/bot/prompts.ts 一元管理提示常数，按用途有条件注入

📋 能做的事

发送消息｜向聊天发送文本消息｜ 邮件搜索｜获取聊天中的邮件列表｜ 聊天管理｜创建组聊天并获取成员｜ ｜用户信息｜获取用户信息｜ 文档操作：读取、搜索和导入Lark文档 ｜维客操作｜搜索和检索维客节点｜ 基于/表/字段/记录的创建、搜索和更新 日历｜创建、获取、编辑事件、确认空闲时间｜ 任务｜创建、更新任务、添加成员、提醒设置｜

🏗️ 体系结构

当前实施（src/bot/index.ts, src/bot/message-processor.ts, src/bot/tool-executor.ts, api/webhook.ts）的配置。

全体构成（実装准据）

graph TB
    subgraph "Entry Points"
        Local["Local HTTP Server
src/index.ts"]
        Vercel["Vercel Function
api/webhook.ts"]
    end

    subgraph "Runtime"
        Dispatcher["Lark EventDispatcher
im.message.receive_v1"]
        Bot["LarkMCPBot"]
        Processor["MessageProcessor"]
        Planner["IntentPlanner"]
        Prompts["prompts.ts"]
        LLM["LLMService"]
        Exec["ToolExecutor"]
        Storage["ConversationStorage"]
    end

    subgraph "External"
        LarkAPI["Lark Open Platform"]
        GLM["GLM API (OpenAI互換)"]
        MCP["LarkMcpTool / larkOapiHandler"]
        Redis["Upstash Redis"]
    end

    LarkAPI --> Local
    LarkAPI --> Vercel
    Local --> Dispatcher
    Vercel --> Dispatcher
    Dispatcher --> Bot
    Bot --> Processor
    Processor --> Planner
    Processor --> Prompts
    Processor --> LLM
    Processor --> Exec
    Exec --> MCP
    MCP --> LarkAPI
    Processor --> Storage
    Storage --> Redis
    LLM --> GLM
    Bot --> LarkAPI

组件责任

• LarkMCPBot

- 负责事件接收、重复排除、异步处理控制、回复重试 - 在Vercel运行时，将超时50秒，直到处理完成为止 await

• MessageProcessor

- 负责成员判定、履历读写、Function Calling循环 - 即使在工具运行后的follow-up调用中 tools 递归处理tool call - 在最终响应中添加工具错误详细信息

• prompts.ts

- 集中管理系统提示摘要提示错误提示常量 - 按域提示（Bitable等）根据用户消息的内容有条件地注入

• LLMService

- GLM API调用、API速率限制（1302/1303/1305）时的指数退避重试 - 超时时间为120秒（不重试超时错误）

• ToolExecutor

- 将MCP工具转换为Function定义，在调用时实施验证和执行 - 双精度工具的path参数规格化（app_token/table_id 等等 path 到子对象） - 字段中的JSON字符串自动透视data.table 集成到

• ConversationStorage

- KV_REST_API_URL / KV_REST_API_READ_ONLY_TOKEN 设置为Redis，未设置则使用Memory

消息处理序列

sequenceDiagram
    participant U as User
    participant L as Lark API
    participant W as Webhook (Local/Vercel)
    participant B as LarkMCPBot
    participant P as MessageProcessor
    participant S as Storage
    participant G as GLM
    participant T as ToolExecutor
    participant M as MCP/Lark API

    U->>L: メッセージ送信
    L->>W: im.message.receive_v1
    W->>B: dispatch
    B->>B: 重複排除(event_id/message_id)
    B->>P: process()
    P->>S: getHistory(chatId)
    P->>G: createCompletion(messages, tools)

    loop tool call が返る限り（最大3回）
        G-->>P: assistant + tool_calls
        P->>T: executeToolCall(name, args)
        T->>M: larkOapiHandler(...)
        M-->>T: tool result
        T-->>P: tool result text
        P->>G: createCompletion(history+tool, tools)
    end

    G-->>P: final text
    P->>S: setHistory(chatId, ...)
    P-->>B: response text（ツールエラー詳細を付記）
    B->>L: reply (retry付き)

27个有效的MCP工具

分类工具 |---------|--------| 邮件 im.v1.message.create, im.v1.message.list | 聊天 im.v1.chat.create, im.v1.chat.list, im.v1.chatMembers.get | |Bitable| bitable.v1.app.create, bitable.v1.appTable.create, bitable.v1.appTable.list, bitable.v1.appTableField.create, bitable.v1.appTableField.list, bitable.v1.appTableRecord.create, bitable.v1.appTableRecord.search, bitable.v1.appTableRecord.update | 文档 docx.v1.document.rawContent, docx.builtin.import, docx.builtin.search | |Wiki| wiki.v2.space.getNode, wiki.v1.node.search | 兜风 drive.v1.permissionMember.create | 用户 contact.v3.user.batchGetId | 日历 calendar.v4.calendarEvent.create, calendar.v4.calendarEvent.patch, calendar.v4.calendarEvent.get, calendar.v4.freebusy.list, calendar.v4.calendar.primary | 任务 task.v2.task.create, task.v2.task.patch, task.v2.task.addMembers, task.v2.task.addReminders |

错误类

• LarkBotError（基底）
• LLMError
• ToolExecutionError
• LarkAPIError
• ResourcePackageError
• APIRateLimitError
• ValidationError

🚀 部署

本番环境（Vercel + Upstash Redis）推奨⭐

如果要作为交互式机器人进行生产，建议使用Vercel部署：

📖 详细: Vercel部署指南

已安装功能:

• ✅ 保持对话上下文：Upstash Redis统合
• ✅ 自动存储切换：本地=内存，生产=刷新
• ✅ Vercel API Routes対応: api/webhook.ts
• ✅ 300秒実行时间：启用流计算最多800秒

优点:

• ✅ 固定URL（変更不要）
• ✅ 对话型机器人（记得之前的对话）
• ✅ 自动缩放
• ✅ 通过GitHub推送自动部署CI/CD集成
• ✅ 全局CDN

5分钟部署:

# 1. Vercel CLIでデプロイ
vercel --prod

# 2. 環境変数を設定（Vercel Dashboard）
KV_REST_API_URL=https://...
KV_REST_API_READ_ONLY_TOKEN=...

🚀 安装，安装

1.安装相关性

npm install

2.设置环境变量

.env编辑文件：

# Lark App Credentials
LARK_APP_ID=your_app_id_here
LARK_APP_SECRET=your_app_secret_here

# GLM-4.7 API Key (Zhipu AI)
GLM_API_KEY=your_glm_api_key_here
# Coding Plan endpoint:
# - Claude Code / Goose: https://api.z.ai/api/anthropic
# - Other tools: https://api.z.ai/api/coding/paas/v4
GLM_API_BASE_URL=https://api.z.ai/api/coding/paas/v4
GLM_MODEL=glm-4.7

# Server Configuration
PORT=3000
WEBHOOK_PATH=/webhook/event

# OAuth Configuration (Required for document/wiki search, calendar, and tasks)
LARK_OAUTH_REDIRECT_URI=http://localhost:3000/auth/callback
# For production (Vercel):
# LARK_OAUTH_REDIRECT_URI=https://your-app.vercel.app/auth/callback

# Logging Configuration (オプション)
LOG_LEVEL=info                          # debug/info/warn/error
ENABLE_PERFORMANCE_METRICS=true         # true/false

# MCP Tool Filtering (オプション)
DISABLED_TOOLS=                         # 明示的に無効化するツール（カンマ区切り）

3.Lark应用程序的设置

1. 飞书开放平台 创建应用程序
2. APP_ID 和 APP_SECRET 获得
3. 授予所需权限：

- im:message （消息发送、接收） - im:chat （聊天信息取得） - contact:user.base:readonly （用户信息取得） - docx:document （读取文档） - bitable:app （Base操作） - calendar:calendar （日历操作） - task:task （任务操作）

1. OAuth设定（文档搜索、维客搜索、日历任务所必需）：

- 在应用程序设置中启用“OAuth” - 设置重定向URI： - 开発环境： http://localhost:3000/auth/callback - 本番环境（Vercel）： https://your-app.vercel.app/auth/callback - 添加范围： - drive:drive:readonly （搜索文档维客所需） - drive:drive:write （导入文档所需） - wiki:wiki:readonly （Wiki检索所需） - calendar:calendar （日历操作） - task:task:read, task:task:write （任务操作） - offline_access （令牌自动更新）

🏃 実行

开发模式

npm run dev

构建

npm run build

本番実行

npm start

📁 项目结构

lark-mcp-bot/
├── src/
│   ├── bot/
│   │   ├── index.ts            # メインボットロジック（イベント処理・リトライ）
│   │   ├── message-processor.ts # メッセージ処理・Function Callingループ
│   │   ├── tool-executor.ts    # MCPツール実行・パラメータ正規化
│   │   ├── llm-service.ts      # GLM API呼び出し・リトライ制御
│   │   ├── intent-planner.ts   # インテント解析・スロット抽出
│   │   └── prompts.ts          # プロンプト定数の一元管理
│   ├── storage/                # 会話履歴ストレージ（Redis/Memory）
│   ├── utils/                  # ロガー等ユーティリティ
│   ├── config.ts               # 設定管理
│   ├── types.ts                # 型定義
│   └── index.ts                # HTTPサーバー・Webhookエンドポイント
├── api/
│   └── webhook.ts              # Vercel Serverless Function エントリポイント
├── tests/
│   ├── bot.test.ts             # ユニットテスト
│   ├── integration.test.ts     # 統合テスト
│   ├── tool-executor.test.ts   # ToolExecutorテスト
│   └── setup.ts                # テスト共通設定
├── vercel.json                 # Vercel設定（maxDuration: 300s）
├── package.json
├── tsconfig.json
└── vitest.config.ts

💬 使用例

用Lark聊天跟机器人搭话

在Lark上和机器人聊天。博特将在GLM-4.7中解析您的请求，并自动运行适当的Lark API。

ユーザー: @bot こんにちは！
ボット: こんにちは！私はLarkのAIアシスタントボットです。メッセージ検索、ドキュメント読み取り、Base操作などができます。

ユーザー: @bot 最近のメッセージを要約して
ボット: [最近のメッセージの要約を表示]

ユーザー: @bot 自動車整備工場用のBaseを作成して
ボット: Baseを作成しました。続いてテーブルとフィールドを追加します...

ユーザー: @bot 来週の空き時間を教えて
ボット: [カレンダーの空き時間を表示]

🧪 测试

# 全テスト実行
npm test

# 統合テストのみ
npm test -- tests/integration.test.ts

# カバレッジレポート（目標: 80%以上）
npm run test:coverage

🔧 故障排除

GLM API超时

GLM API响应超过120秒时失败。请确认：

1. 缩小工具数量（DISABLED_TOOLS 禁用不需要的工具）
2. 如果对话历史很长，请尝试新的聊天
3. 缩短·具体要求

GLM API速率限制（1302错误）

已达到并发请求数限制。机器人会自动重试（最多3次，指数回调），但如果频繁发生，请查看API计划。

双精度工具错误

错误详细信息在聊天响应中 ツールエラー詳細: 中所述修改相应参数的值。常见错误：

• field validation failed：字段类型值无效（src/bot/prompts.ts 的，之 BITABLE_HINTS ），模板名称将采用不同的格式
• request miss app_token path argument未指定：app_token

授权错误

如果文档搜索维客搜索日历任务操作出错：

• 错误99991663（权限不足）：未设置审计。请按照以下步骤设置：

1. .env 的 LARK_OAUTH_REDIRECT_URI 的规格化距离的幂函数 1. 在Lark Open Platform中启用OAuth并设置重定向URI和作用域 1. 在Lark聊天中再次登录到bot，点击认证链接

• 错误99991679（范围不足）：缺少外部作用域。请检查以下范围：

- 文档搜索： drive:drive:readonly - 获取文档内容： drive:drive:readonly - 文档导入： drive:drive:write - Wiki検索: wiki:wiki:readonly - 添加驱动器权限： drive:drive:write - 日历操作： calendar:calendar, calendar:calendar:readonly, calendar:calendar:update, calendar:calendar:create - 任务操作： task:task:read, task:task:write, task:tasklist:read, task:tasklist:write

调整日志级别

LOG_LEVEL=debug   # デバッグ時
LOG_LEVEL=warn    # 本番でログ削減

性能问题

ENABLE_PERFORMANCE_METRICS=true
LOG_LEVEL=info

日志 duration_ms 对较大场景进行渲染期间已观察到该故障。

📄 许可证

MIT许可证

🙏 参考链接

• 飞书开放平台
• 智普AI GLM-4.7
• 模型上下文协议
• 比特字段指南