my-lark

飞书全能力技能。基于飞书官方工具服务，支持消息、群组、云文档、云盘、知识库、日历、审批、多维表格、电子表格、画板、通讯录全部模块。面向小白：安装即用，每一步都有操作指引；面向AI：每个接口均有调用示例、参数说明、权限要求和异常处理。触发词：发消息、搜索文档、查日历、查审批、建日程、拉群列表等。

My Lark（飞书全能力技能）

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

---

一、完整功能索引

#	功能场景	核心工具	凭证要求
1	发消息到群	im_v1_message_create	app_id + app_secret
2	获取群聊列表	im_v1_chat_list	app_id + app_secret
3	创建群聊	im_v1_chat_create	app_id + app_secret
4	搜索云文档	docx_builtin_search	user_access_token
5	读取文档内容	docx_v1_document_rawContent	user_access_token
6	读写电子表格	sheets_v2_spreadsheets_values_*	app_id + app_secret
7	搜索知识库	wiki_v1_node_search	user_access_token
8	查询多维表格	bitable_v1_appTableRecord_*	app_id + app_secret
9	查日历/建日程	calendar_v4_events	app_id + app_secret
10	查询通讯录	contact_v3_user_batchGetId	app_id + app_secret
11	提交/查审批	approval_v4_instances_*	app_id + app_secret
12	云盘文件管理	drive_explorer_v2_fileList	app_id + app_secret
13	下载画板图片	board/v1/whiteboards/:id/download_as_image	app_id + app_secret
14	解析 PlantUML/Mermaid	board/v1/whiteboards/:id/nodes/plantuml	app_id + app_secret

---

二、前置条件（逐项检查）

依赖	最低要求	检查命令	检查失败怎么做
Python	≥ 3.8（建议 ≥ 3.10）	python3 --version	升级 Python：apt update && apt install python3.11
Node.js	≥ 16	node --version	升级 Node.js
npm	任意版本	npm --version	随 Node.js 自动安装
lark-mcp	已安装并可用	lark-mcp --help	见安装步骤第三步
飞书应用	已创建并发布	飞书开放平台控制台	见安装步骤第一步
凭证文件	已配置	cat /workspace/.lark_tokens.json	见安装步骤第二步

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

bash

python3 --version && node --version && lark-mcp --help && cat /workspace/.lark_tokens.json | python3 -m json.tool && echo "✅ 全部就绪"

---

三、完整安装步骤

第一步：创建飞书应用（账号要求：飞书管理员）

操作路径：

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

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

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

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

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

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

---

第二步：配置凭证文件

在 /workspace/.lark_tokens.json（注意是 /workspace/ 不是 ~）创建文件：

json

{
  "app_id": "cli_xxxxxxxxxxxxxxxx",
  "app_secret": "your_app_secret_here",
  "user_access_token": "your_user_access_token_here"
}

如何获取 user_access_token（仅知识库/云文档需要）：

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

方式 B（标准 OAuth）：

1. 构造授权 URL：

text

https://open.feishu.cn/open-apis/authen/v1/authorize?app_id=cli_xxx&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback&state=randomstring

2. 浏览器打开 → 扫码授权 → 回调获取 code
3. 用 code 换取 token：

bash

curl -X POST 'https://open.feishu.cn/open-apis/authen/v1/oidc/access_token' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer USER_ACCESS_TOKEN' \
  -d '{"grant_type": "authorization_code", "code": "获取的code"}'

---

第三步：安装 lark-mcp CLI

bash

npm install -g @larksuite/lark-mcp

验证安装成功：

bash

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

---

第四步：验证配置（逐项测试）

bash

# 1. 确认凭证文件存在且格式正确
cat /workspace/.lark_tokens.json | python3 -m json.tool
# 应该输出格式化的 JSON，无报错

# 2. 测试 App Token（查询群列表）
python3 /workspace/skills/lark-skill/lark_mcp.py call im_v1_chat_list '{"page_size": 5}'
# 预期：返回群聊列表 JSON

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

# 4. 测试通讯录查询
python3 /workspace/skills/lark-skill/lark_mcp.py call contact_v3_user_batchGetId '{}'
# 预期：返回用户信息

全部通过 → 配置完成 ✅

---

四、调用方式详解

标准格式

bash

python3 /workspace/skills/lark-skill/lark_mcp.py <命令> [参数]

命令分类

A. 便捷命令（简化操作，无需记工具名）

命令	示例	说明
send <chat_id> <消息>	send oc_xxx "你好"	发文本消息到群
chats	chats	获取群聊列表（返回 chat_id）
search <关键词>	search 项目报告	搜索云文档（需 User Token）
doc <doc_token>	doc W7FOdr5aQo9F1	读取云文档全文（需 User Token）
user <open_id>	user ou_xxx	查询单个用户信息
call <工具名> <json>	call im_v1_chat_list '{}'	调用任意底层工具

B. 底层工具调用格式

bash

python3 /workspace/skills/lark-skill/lark_mcp.py call <工具名> '<JSON参数>'

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

---

五、每个场景的完整调用示例

场景 1：发文本消息到群

bash

python3 /workspace/skills/lark-skill/lark_mcp.py send oc_xxxxxxxxxxxxxxxx "各位同事，明天上午10点开会，请准时参加。"

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

---

场景 2：获取群聊列表（找到 chat_id）

bash

python3 /workspace/skills/lark-skill/lark_mcp.py call im_v1_chat_list '{"page_size": 20}'

返回示例：

json

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

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

---

场景 3：发送富文本消息

bash

python3 /workspace/skills/lark-skill/lark_mcp.py call im_v1_message_create '{
  "receive_id": "oc_xxxxxxxxxxxxxxxx",
  "msg_type": "post",
  "content": "{\"zh_cn\":{\"title\":\"会议通知\",\"content\":[[{\"tag\":\"text\",\"text\":\"时间：明天上午10点\"},{\"tag\":\"text\",\"text\":\"地点：会议室A\"}]]}}"
}'

---

场景 4：搜索云文档

bash

python3 /workspace/skills/lark-skill/lark_mcp.py search 项目报告

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

---

场景 5：读取云文档内容

bash

# 先用 search 拿到 document_id，再读取内容
python3 /workspace/skills/lark-skill/lark_mcp.py doc W7FOdr5aQo9F1OxapR8cQkPpnNg

⚠️ 需要 user_access_token 配置正确。

---

场景 6：读写电子表格

bash

# 读取单元格（A1:D5）
python3 /workspace/skills/lark-skill/lark_mcp.py call sheets_v2_spreadsheets_values_get '{
  "spreadsheetToken": "Shtxxxxxx",
  "range": "Sheet1!A1:D5"
}'

# 写入单元格
python3 /workspace/skills/lark-skill/lark_mcp.py call sheets_v2_spreadsheets_values_put '{
  "spreadsheetToken": "Shtxxxxxx",
  "range": "Sheet1!A1",
  "values": [["姓名", "部门", "状态"], ["张三", "技术部", "在职"]]
}'

---

场景 7：操作多维表格（增删改查记录）

bash

# 列出所有多维表格
python3 /workspace/skills/lark-skill/lark_mcp.py call bitable_v1_app_list '{}'

# 列出某个多维表格的所有记录
python3 /workspace/skills/lark-skill/lark_mcp.py call bitable_v1_appTableRecord_list '{
  "table_id": "tblxxxxxx",
  "page_size": 100
}'

# 新增一条记录
python3 /workspace/skills/lark-skill/lark_mcp.py call bitable_v1_appTableRecord_create '{
  "table_id": "tblxxxxxx",
  "fields": {"姓名": "李四", "部门": "产品部"}
}'

---

场景 8：日历管理

bash

# 查询日历列表
python3 /workspace/skills/lark-skill/lark_mcp.py call calendar_v4_calendars '{}'

# 创建日程
python3 /workspace/skills/lark-skill/lark_mcp.py call calendar_v4_events '{
  "summary": "产品评审会",
  "start_time": {"timestamp": "1743225600", "timezone": "Asia/Shanghai"},
  "end_time": {"timestamp": "1743229200", "timezone": "Asia/Shanghai"},
  "description": "Q2产品评审，需要各位负责人参加"
}'

# 查询某人在某时段的忙闲
python3 /workspace/skills/lark-skill/lark_mcp.py call calendar_v4_freebusy_query '{
  "time_min": "2026-03-30T00:00:00+08:00",
  "time_max": "2026-03-31T00:00:00+08:00",
  "user_ids": ["ou_xxxxxxxxxxxxxxxx"]
}'

---

场景 9：通讯录查询

bash

# 查询已知用户的信息
python3 /workspace/skills/lark-skill/lark_mcp.py call contact_v3_user_batchGetId '{
  "user_id_type": "open_id",
  "open_ids": ["ou_032ca29de8829b1a71272844465a4df3"]
}'

# 查询部门下所有用户
python3 /workspace/skills/lark-skill/lark_mcp.py call contact_v3_users '{
  "user_id_type": "open_id",
  "department_id_type": "open_department_id",
  "department_ids": ["od_xxxxxxxxxxxxxxxx"]
}'

---

场景 10：提交审批

bash

python3 /workspace/skills/lark-skill/lark_mcp.py call approval_v4_instances_create '{
  "approval_code": "APPROVAL_CODE_xxx",
  "form": [
    {"id": "field1", "value": ["张三的报销申请"]},
    {"id": "field2", "value": ["998.50"]}
  ]
}'

---

场景 11：知识库操作

bash

# 搜索知识库
python3 /workspace/skills/lark-skill/lark_mcp.py call wiki_v1_node_search '{
  "query": "技术文档",
  "count": 10
}'

# 获取知识库节点详情（需要 space_id 和 node_token）
python3 /workspace/skills/lark-skill/lark_mcp.py call wiki_v2_space_getNode '{
  "space_id": "7241909889038073859",
  "node_token": "xxxxxxxxxx"
}'

⚠️ 知识库相关接口需要 user_access_token。

---

场景 12：云盘文件管理

bash

# 获取云盘根目录
python3 /workspace/skills/lark-skill/lark_mcp.py call drive_explorer_v2_root_folder_meta '{}'

# 列出文件夹内容
python3 /workspace/skills/lark-skill/lark_mcp.py call drive_explorer_v2_fileList '{
  "order_by": 3,
  "direction": "DESC"
}'

# 创建文件夹
python3 /workspace/skills/lark-skill/lark_mcp.py call drive_v1_files_create_folder '{
  "name": "新文件夹",
  "folder_token": "根目录token"
}'

---

场景 13：下载画板为图片

bash

# 获取画板ID（从文档块中提取 white_board_token）
python3 /workspace/skills/lark-skill/lark_mcp.py call board/v1/whiteboards/{whiteboard_id}/download_as_image '{
  "format": "png",
  "quality": "high"
}'

---

场景 14：解析 PlantUML / Mermaid 语法

bash

# 解析 PlantUML
python3 /workspace/skills/lark-skill/lark_mcp.py call board/v1/whiteboards/{whiteboard_id}/nodes/plantuml '{
  "plant_uml_code": "@startuml\nAlice -> Bob: 你好\nBob --> Alice: 你好！\n@enduml",
  "syntax_type": 1
}'

# 解析 Mermaid
python3 /workspace/skills/lark-skill/lark_mcp.py call board/v1/whiteboards/{whiteboard_id}/nodes/plantuml '{
  "mermaid_code": "graph TD;\n    A[开始] --> B{判断}\n    B -->|是| C[执行]\n    B -->|否| D[退出}",
  "syntax_type": 2
}'

---

六、异常处理（完整版）

运行时错误速查

错误现象	第一步排查	解决方案
报 FileNotFoundError	ls /workspace/.lark_tokens.json	创建凭证文件，见第二步
报 JSONDecodeError	cat /workspace/.lark_tokens.json | python3 -m json.tool	JSON 格式错误，用 json.cn 校验
报 app_id 或 app_secret 错误	飞书开放平台 → 凭证与基础信息	重新复制 App ID / App Secret
报 permission denied	飞书开放平台 → 权限管理	申请对应权限 → 重新发布版本
报 99991403	「权限不足」含义广	见下方分类排查
报 99991700	机器人不在群里	手动把机器人拉入群聊
报 99991140	接口频率超限	等 1-2 秒再试，勿频繁轮询
报 99991663	Token 无效或过期	App Secret 可能变更，重新获取
报 lark-mcp: command not found	npm list -g @larksuite/lark-mcp	重新安装：npm install -g @larksuite/lark-mcp
工具调用后无输出/超时报错	lark-mcp --help 确认可用	重启终端或重新安装 lark-mcp
知识库/云文档报权限错误	user_access_token 是否配置	确认凭证中有 user_access_token 字段

99991403 权限不足——分类诊断

伴随信息	真正原因	解决方法
"无 im:message 权限"	应用未申请消息权限	飞书后台 → 权限管理 → 申请 im:message → 重新发版
"无 calendar 权限"	日历权限未开	同上，申请 calendar → 重新发版
"无 docx 权限"	云文档权限未开	同上，申请 docx → 重新发版
"文档不存在"	文档 token 错误或应用无访问权	文档 → 右上角「分享」→ 添加应用
"节点不存在"	知识库节点 token 错误	确认 node_token 正确

网络与连接错误

错误信息	原因	解决方法
Connection timeout	网络超时	确认服务器可访问 open.feishu.cn
HTTP 403	IP 白名单限制	飞书后台 → 安全设置 → 关闭 IP 白名单
HTTP 429	请求过快被限流	添加延时：sleep 1 后重试
SSL error	证书问题	确认服务器时间正确：date

---

七、凭证与权限体系详解

凭证种类

凭证	有效期	获取方式	用途
App Token（tenant_access_token）	2小时，自动续期	app_id + app_secret 自动换取	消息/日历/通讯录/审批/多维表格/云盘
User Access Token	2小时	OAuth 用户授权	知识库/云文档搜索和读取

权限申请自查表（按功能）

需要的功能	必须申请的权限	是否需重新发版
发消息到群	im:message	✅
获取群列表	im:chat:read	✅
创建群聊	im:chat	✅
日历读写	calendar	✅
通讯录查询	contact	✅
提交审批	approval	✅
多维表格读写	bitable:app	✅
电子表格读写	sheets	✅
云盘文件管理	drive	✅
知识库搜索/读取	wiki	✅ + User Token
云文档搜索/读取	docx	✅ + User Token
获取用户信息	contact:user.id:readonly	✅

---

八、调试与排障流程图

text

工具调用报错
  │
  ├─ FileNotFoundError / JSONDecodeError
  │     → 检查 /workspace/.lark_tokens.json 是否存在、格式是否正确
  │
  ├─ lark-mcp: command not found
  │     → npm install -g @larksuite/lark-mcp
  │
  ├─ 99991663（Token 无效）
  │     → 重新确认 app_id 和 app_secret 是否正确
  │
  ├─ 99991403（权限不足）
  │     ├─ 应用权限未申请 → 飞书后台申请 + 发版
  │     └─ 文档未分享给应用 → 文档右上角「分享」添加应用
  │
  ├─ 99991700（不在群里）
  │     → 手动把机器人拉入目标群
  │
  ├─ 99991140（频率超限）
  │     → 降低调用频率
  │
  └─ 无输出 / 超时
        → lark-mcp --help 确认可用性，重试

---

九、频率限制参考

接口类型	限制	超过后
大多数 API	50次/秒	收到 99991140，等待后重试
知识库搜索	5次/秒	等待 1 秒再试
发送消息	50次/秒	加 sleep(0.1) 控制频率
创建日程	10次/秒	降低频率
创建电子表格	5次/分	控制调用节奏
批量发消息	受单发限制叠加	建议间隔发送

---

十、参考文件索引

文件	内容
references/start-here.md	快速入门，三分钟上手
references/tools-index.md	全部工具完整索引（60+ 接口）
references/auth.md	认证体系、双层权限模型详解
references/errors.md	完整错误码速查
references/im.md	消息与群组 API 详解
references/drive.md	云盘与文件 API 详解
references/wiki.md	知识库 API 详解
references/docx.md	云文档 API 详解
references/sheets.md	电子表格 API 详解
references/bitable.md	多维表格 API 详解
references/board.md	画板 API 详解
references/contact.md	通讯录 API 详解
references/calendar.md	日历 API 详解
references/approval.md	审批 API 详解