my-lark

My Lark（飞书全能力技能）

凭证统一存放在 /workspace/.lark_令牌s.json，技能本身不含任何凭证。

一、完整功能索引 # 功能场景 核心工具 凭证要求 1 发消息到群 im_v1_message_创建 应用_id + 应用_secret 2 获取群聊列表 im_v1_chat_列出 应用_id + 应用_secret 3 创建群聊 im_v1_chat_创建 应用_id + 应用_secret 4 搜索云文档 docx_builtin_搜索 user_访问_令牌 5 读取文档内容 docx_v1_document_rawContent user_访问_令牌 6 读写电子表格 sheets_v2_spreadsheets_values_ 应用_id + 应用_secret 7 搜索知识库 wiki_v1_node_搜索 user_访问_令牌 8 查询多维表格 bitable_v1_应用TableRecord_ 应用_id + 应用_secret 9 查日历/建日程 calendar_v4_事件 应用_id + 应用_secret 10 查询通讯录 contact_v3_user_batch获取Id 应用_id + 应用_secret 11 提交/查审批 应用roval_v4_instances_* 应用_id + 应用_secret 12 云盘文件管理 drive_资源管理器_v2_file列出 应用_id + 应用_secret 13 下载画板图片 board/v1/whiteboards/:id/下载_as_image 应用_id + 应用_secret 14 解析 PlantUML/MermAId board/v1/whiteboards/:id/nodes/plantuml 应用_id + 应用_secret 二、前置条件（逐项检查） 依赖 最低要求 检查命令 检查失败怎么做 Python ≥ 3.8（建议 ≥ 3.10） python3 --version 升级 Python：apt 更新 && apt 安装 python3.11 Node.js ≥ 16 node --version 升级 Node.js npm 任意版本 npm --version 随 Node.js 自动安装 lark-mcp 已安装并可用 lark-mcp --help 见安装步骤第三步 飞书应用 已创建并发布 飞书开放平台控制台 见安装步骤第一步 凭证文件 已配置 cat /workspace/.lark_令牌s.json 见安装步骤第二步

一键检查脚本（复制运行）：

python3 --version && node --version && lark-mcp --help && cat /workspace/.lark_令牌s.json | python3 -m json.工具 && echo "✅ 全部就绪"

三、完整安装步骤 第一步：创建飞书应用（账号要求：飞书管理员）

操作路径：

打开 飞书开放平台 → 用管理员账号登录 点击「创建企业自建应用」→ 填写应用名称（如"MyLark 机器人"）→ 点击创建 进入应用 → 左侧「应用功能」→「机器人」→ 点击「开启」 左侧「凭证与基础信息」→ 复制 应用 ID 和 应用 Secret（备用） 左侧「权限管理」→ 按需申请以下权限（见下方权限速查表） 左侧「版本管理与发布」→ 创建版本 → 申请发布 → 管理员审批

必须申请的权限（消息/群组/日历/通讯录/审批/多维表格）：

权限名 用途 im:message 发/查消息 im:chat 群管理 im:chat:read 读取群信息 calendar 日历读写 calendar:calendar:read 读日历 contact 通讯录读写 应用roval 审批读写

知识库/云文档额外权限（需 User 令牌）：

权限名 用途 wiki 知识库读写 docx 云文档读写

💡 权限申请后需重新发布版本才能生效。

第二步：配置凭证文件

在 /workspace/.lark_令牌s.json（注意是 /workspace/ 不是 ~）创建文件：

{ "应用_id": "命令行工具_xxxxxxxxxxxxxxxx", "应用_secret": "your_应用_secret_here", "user_访问_令牌": "your_user_访问_令牌_here" }

如何获取 user_访问_令牌（仅知识库/云文档需要）：

方式 A（简单）：在飞书开放平台 → 应用 → 权限管理 → 开通「以应用身份获取用户授权」

方式 B（标准 OAuth）：

构造授权 URL： https://open.feishu.cn/open-APIs/authen/v1/授权?应用_id=命令行工具_xxx&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback&状态=randomstring

浏览器打开 → 扫码授权 → 回调获取 code 用 code 换取 令牌： curl -X POST 'https://open.feishu.cn/open-APIs/authen/v1/oidc/访问_令牌' \ -H 'Content-Type: 应用/json' \ -H 'Authorization: Bearer USER_访问_令牌' \ -d '{"grant_type": "authorization_code", "code": "获取的code"}'

第三步：安装 lark-mcp 命令行工具 npm 安装 -g @larksuite/lark-mcp

验证安装成功：

lark-mcp --help # 出现帮助信息即表示安装成功

第四步：验证配置（逐项测试） # 1. 确认凭证文件存在且格式正确 cat /workspace/.lark_令牌s.json | python3 -m json.工具 # 应该输出格式化的 JSON，无报错

# 2. 测试 应用 令牌（查询群列表） python3 /workspace/技能s/lark-技能/lark_mcp.py call im_v1_chat_列出 '{"page_size": 5}' # 预期：返回群聊列表 JSON

# 3. 测试发消息（需要先把机器人拉入群） python3 /workspace/技能s/lark-技能/lark_mcp.py 发送 oc_xxxxxxxxxxxxxxxx "机器人连通测试" # 预期：飞书群收到消息

# 4. 测试通讯录查询 python3 /workspace/技能s/lark-技能/lark_mcp.py call contact_v3_user_batch获取Id '{}' # 预期：返回用户信息

全部通过 → 配置完成 ✅

四、调用方式详解 标准格式 python3 /workspace/技能s/lark-技能/lark_mcp.py <命令> [参数]

命令分类 A. 便捷命令（简化操作，无需记工具名） 命令 示例 说明 发送 <消息> 发送 oc_xxx "你好" 发文本消息到群 chats chats 获取群聊列表（返回 chat_id） 搜索 <关键词> 搜索 项目报告 搜索云文档（需 User 令牌） doc doc W7FOdr5aQo9F1 读取云文档全文（需 User 令牌） user user ou_xxx 查询单个用户信息 call <工具名> call im_v1_chat_列出 '{}' 调用任意底层工具 B. 底层工具调用格式 python3 /workspace/技能s/lark-技能/lark_mcp.py call <工具名> ''

⚠️ JSON 参数必须用单引号包裹，外层用双引号，这是 shell 转义要求。

五、每个场景的完整调用示例 场景 1：发文本消息到群 python3 /workspace/技能s/lark-技能/lark_mcp.py 发送 oc_xxxxxxxxxxxxxxxx "各位同事，明天上午10点开会，请准时参加。"

前置：机器人已在群里（未被禁言）

场景 2：获取群聊列表（找到 chat_id） python3 /workspace/技能s/lark-技能/lark_mcp.py call im_v1_chat_列出 '{"page_size": 20}'

返回示例：

{ "data": { "items": [ {"chat_id": "oc_xxx", "name": "技术部群"}, {"chat_id": "oc_yyy", "name": "项目协同群"} ] } }

取 chat_id 填入 发送 命令即可发消息。

场景 3：发送富文本消息 python3 /workspace/技能s/lark-技能/lark_mcp.py call im_v1_message_创建 '{ "接收_id": "oc_xxxxxxxxxxxxxxxx", "msg_type": "post", "content": "{\"zh_cn\":{\"title\":\"会议通知\",\"content\":[[{\"tag\":\"text\",\"text\":\"时间：明天上午10点\"},{\"tag\":\"text\",\"text\":\"地点：会议室A\"}]]}}" }'

场景 4：搜索云文档 python3 /workspace/技能s/lark-技能/lark_mcp.py 搜索 项目报告

返回文档名称、令牌、链接等列表。

场景 5：读取云文档内容 # 先用 搜索 拿到 document_id，再读取内容 python3 /workspace/技能s/lark-技能/lark_mcp.py doc W7FOdr5aQo9F1OxapR8cQkPpnNg

⚠️ 需要 user_访问_令牌 配置正确。

场景 6：读写电子表格 # 读取单元格（A1:D5） python3 /workspace/技能s/lark-技能/lark_mcp.py call sheets_v2_spreadsheets_values_获取 '{ "spreadsheet令牌": "Shtxxxxxx", "range": "Sheet1!A1:D5" }'

# 写入单元格 python3 /workspace/技能s/lark-技能/lark_mcp.py call sheets_v2_spreadsheets_values_put '{ "spreadsheet令牌": "Shtxxxxxx", "range": "Sheet1!A1", "values": [["姓名", "部门", "状态"],