My Lark（飞书全能力技能）
凭证统一存放在 /workspace/.lark_tokens.json，技能本身不含任何凭证。
一、完整功能索引
| # | 功能场景 | 核心工具 | 凭证要求 |
|---|
| 1 | 发消息到群 | INLINECODE1 | appid + appsecret |
| 2 |
获取群聊列表 |
im_v1_chat_list | app
id + appsecret |
| 3 | 创建群聊 |
im_v1_chat_create | app
id + appsecret |
| 4 | 搜索云文档 |
docx_builtin_search | user
accesstoken |
| 5 | 读取文档内容 |
docx_v1_document_rawContent | user
accesstoken |
| 6 | 读写电子表格 |
sheets_v2_spreadsheets_values_* | app
id + appsecret |
| 7 | 搜索知识库 |
wiki_v1_node_search | user
accesstoken |
| 8 | 查询多维表格 |
bitable_v1_appTableRecord_* | app
id + appsecret |
| 9 | 查日历/建日程 |
calendar_v4_events | app
id + appsecret |
| 10 | 查询通讯录 |
contact_v3_user_batchGetId | app
id + appsecret |
| 11 | 提交/查审批 |
approval_v4_instances_* | app
id + appsecret |
| 12 | 云盘文件管理 |
drive_explorer_v2_fileList | app
id + appsecret |
| 13 | 下载画板图片 |
board/v1/whiteboards/:id/download_as_image | app
id + appsecret |
| 14 | 解析 PlantUML/Mermaid |
board/v1/whiteboards/:id/nodes/plantuml | app
id + appsecret |
二、前置条件（逐项检查）
| 依赖 | 最低要求 | 检查命令 | 检查失败怎么做 |
|---|
| Python | ≥ 3.8（建议 ≥ 3.10） | INLINECODE15 | 升级 Python： INLINECODE16 |
| Node.js |
≥ 16 |
node --version | 升级 Node.js |
| npm | 任意版本 |
npm --version | 随 Node.js 自动安装 |
| lark-mcp | 已安装并可用 |
lark-mcp --help | 见安装步骤第三步 |
| 飞书应用 | 已创建并发布 | 飞书开放平台控制台 | 见安装步骤第一步 |
| 凭证文件 | 已配置 |
cat /workspace/.lark_tokens.json | 见安装步骤第二步 |
一键检查脚本（复制运行）：
python3 --version && node --version && lark-mcp --help && cat /workspace/.lark_tokens.json | python3 -m json.tool && echo "✅ 全部就绪"
三、完整安装步骤
第一步：创建飞书应用（账号要求：飞书管理员）
操作路径：
- 1. 打开 飞书开放平台 → 用管理员账号登录
- 点击「创建企业自建应用」→ 填写应用名称（如"MyLark Bot"）→ 点击创建
- 进入应用 → 左侧「应用功能」→「机器人」→ 点击「开启」
- 左侧「凭证与基础信息」→ 复制 App ID 和 App Secret（备用）
- 左侧「权限管理」→ 按需申请以下权限（见下方权限速查表）
- 左侧「版本管理与发布」→ 创建版本 → 申请发布 → 管理员审批
必须申请的权限（消息/群组/日历/通讯录/审批/多维表格）：
| 权限名 | 用途 |
|---|
| INLINECODE21 | 发/查消息 |
| INLINECODE22 |
群管理 |
|
im:chat:read | 读取群信息 |
|
calendar | 日历读写 |
|
calendar:calendar:read | 读日历 |
|
contact | 通讯录读写 |
|
approval | 审批读写 |
知识库/云文档额外权限（需 User Token）：
| 权限名 | 用途 |
|---|
| INLINECODE28 | 知识库读写 |
| INLINECODE29 |
云文档读写 |
💡 权限申请后需重新发布版本才能生效。
第二步：配置凭证文件
在 /workspace/.lark_tokens.json（注意是 /workspace/ 不是 ~）创建文件：
CODEBLOCK1
如何获取 useraccesstoken（仅知识库/云文档需要）：
方式 A（简单）：在飞书开放平台 → 应用 → 权限管理 → 开通「以应用身份获取用户授权」
方式 B（标准 OAuth）：
- 1. 构造授权 URL：
https://open.feishu.cn/open-apis/authen/v1/authorize?app_id=cli_xxx&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback&state=randomstring
- 2. 浏览器打开 → 扫码授权 → 回调获取 INLINECODE33
- 用 code 换取 token：
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
CODEBLOCK4
验证安装成功：
lark-mcp --help
# 出现帮助信息即表示安装成功
第四步：验证配置（逐项测试）
CODEBLOCK6
全部通过 → 配置完成 ✅
四、调用方式详解
标准格式
CODEBLOCK7
命令分类
A. 便捷命令（简化操作，无需记工具名）
| 命令 | 示例 | 说明 |
|---|
| INLINECODE34 | INLINECODE35 | 发文本消息到群 |
| INLINECODE36 |
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. 底层工具调用格式
CODEBLOCK8
⚠️ JSON 参数必须用单引号包裹，外层用双引号，这是 shell 转义要求。
五、每个场景的完整调用示例
场景 1：发文本消息到群
CODEBLOCK9
前置：机器人已在群里（未被禁言）
场景 2：获取群聊列表（找到 chat_id）
CODEBLOCK10
返回示例：
{
"data": {
"items": [
{"chat_id": "oc_xxx", "name": "技术部群"},
{"chat_id": "oc_yyy", "name": "项目协同群"}
]
}
}
取
chat_id 填入
send 命令即可发消息。
场景 3：发送富文本消息
CODEBLOCK12
场景 4：搜索云文档
CODEBLOCK13
返回文档名称、token、链接等列表。
场景 5：读取云文档内容
CODEBLOCK14
⚠️ 需要 user_access_token 配置正确。
场景 6：读写电子表格
CODEBLOCK15
场景 7：操作多维表格（增删改查记录）
CODEBLOCK16
场景 8：日历管理
CODEBLOCK17
场景 9：通讯录查询
CODEBLOCK18
场景 10：提交审批
CODEBLOCK19
场景 11：知识库操作
CODEBLOCK20
⚠️ 知识库相关接口需要 user_access_token。
场景 12：云盘文件管理
CODEBLOCK21
场景 13：下载画板为图片
CODEBLOCK22
场景 14：解析 PlantUML / Mermaid 语法
CODEBLOCK23
六、异常处理（完整版）
运行时错误速查
| 错误现象 | 第一步排查 | 解决方案 |
|---|
| 报 INLINECODE50 | INLINECODE51 | 创建凭证文件，见第二步 |
| 报 INLINECODE52 |
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 正确 |
网络与连接错误
| 错误信息 | 原因 | 解决方法 |
|---|
| INLINECODE70 | 网络超时 | 确认服务器可访问 INLINECODE71 |
| INLINECODE72 |
IP 白名单限制 | 飞书后台 → 安全设置 → 关闭 IP 白名单 |
|
HTTP 429 | 请求过快被限流 | 添加延时：
sleep 1 后重试 |
|
SSL error | 证书问题 | 确认服务器时间正确：
date |
七、凭证与权限体系详解
凭证种类
| 凭证 | 有效期 | 获取方式 | 用途 |
|---|
| App Token（tenantaccesstoken） | 2小时，自动续期 | appid + appsecret 自动换取 | 消息/日历/通讯录/审批/多维表格/云盘 |
| User Access Token |
2小时 | OAuth 用户授权 | 知识库/云文档搜索和读取 |
权限申请自查表（按功能）
| 需要的功能 | 必须申请的权限 | 是否需重新发版 |
|---|
| 发消息到群 | INLINECODE77 | ✅ |
| 获取群列表 |
im:chat:read | ✅ |
| 创建群聊 |
im:chat | ✅ |
| 日历读写 |
calendar | ✅ |
| 通讯录查询 |
contact | ✅ |
| 提交审批 |
approval | ✅ |
| 多维表格读写 |
bitable:app | ✅ |
| 电子表格读写 |
sheets | ✅ |
| 云盘文件管理 |
drive | ✅ |
| 知识库搜索/读取 |
wiki | ✅ + User Token |
| 云文档搜索/读取 |
docx | ✅ + User Token |
| 获取用户信息 |
contact:user.id:readonly | ✅ |
八、调试与排障流程图
CODEBLOCK24
九、频率限制参考
| 接口类型 | 限制 | 超过后 |
|---|
| 大多数 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 详解 |
My Lark（飞书全能力技能）
凭证统一存放在 /workspace/.lark_tokens.json，技能本身不含任何凭证。
一、完整功能索引
| # | 功能场景 | 核心工具 | 凭证要求 |
|---|
| 1 | 发消息到群 | imv1messagecreate | appid + appsecret |
| 2 |
获取群聊列表 | imv1
chatlist | app
id + appsecret |
| 3 | 创建群聊 | im
v1chat
create | appid + app_secret |
| 4 | 搜索云文档 | docx
builtinsearch | user
accesstoken |
| 5 | 读取文档内容 | docx
v1document
rawContent | useraccess_token |
| 6 | 读写电子表格 | sheets
v2spreadsheets
values* | app
id + appsecret |
| 7 | 搜索知识库 | wiki
v1node
search | useraccess_token |
| 8 | 查询多维表格 | bitable
v1appTableRecord
* | appid + app_secret |
| 9 | 查日历/建日程 | calendar
v4events | app
id + appsecret |
| 10 | 查询通讯录 | contact
v3user
batchGetId | appid + app_secret |
| 11 | 提交/查审批 | approval
v4instances
* | appid + app_secret |
| 12 | 云盘文件管理 | drive
explorerv2
fileList | appid + app_secret |
| 13 | 下载画板图片 | board/v1/whiteboards/:id/download
asimage | app
id + appsecret |
| 14 | 解析 PlantUML/Mermaid | board/v1/whiteboards/:id/nodes/plantuml | app
id + appsecret |
二、前置条件（逐项检查）
| 依赖 | 最低要求 | 检查命令 | 检查失败怎么做 |
|---|
| 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. 打开 飞书开放平台 → 用管理员账号登录
- 点击「创建企业自建应用」→ 填写应用名称（如MyLark Bot）→ 点击创建
- 进入应用 → 左侧「应用功能」→「机器人」→ 点击「开启」
- 左侧「凭证与基础信息」→ 复制 App ID 和 App Secret（备用）
- 左侧「权限管理」→ 按需申请以下权限（见下方权限速查表）
- 左侧「版本管理与发布」→ 创建版本 → 申请发布 → 管理员审批
必须申请的权限（消息/群组/日历/通讯录/审批/多维表格）：
| 权限名 | 用途 |
|---|
| im:message | 发/查消息 |
| im:chat |
群管理 |
| im:chat:read | 读取群信息 |
| calendar | 日历读写 |
| calendar:calendar:read | 读日历 |
| contact | 通讯录读写 |
| approval | 审批读写 |
知识库/云文档额外权限（需 User Token）：
云文档读写 |
💡 权限申请后需重新发布版本才能生效。
第二步：配置凭证文件
在 /workspace/.lark_tokens.json（注意是 /workspace/ 不是 ~）创建文件：
json
{
appid: clixxxxxxxxxxxxxxxx,
appsecret: yourappsecrethere,
useraccesstoken: youruseraccesstokenhere
}
如何获取 useraccesstoken（仅知识库/云文档需要）：
方式 A（简单）：在飞书开放平台 → 应用 → 权限管理 → 开通「以应用身份获取用户授权」
方式 B（标准 OAuth）：
- 1. 构造授权 URL：
https://open.feishu.cn/open-apis/authen/v1/authorize?appid=clixxx&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback&state=randomstring
- 2. 浏览器打开 → 扫码授权 → 回调获取 code
- 用 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
ACCESSTOKEN \
-d {grant
type: authorizationcode, 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 imv1
chatlist {page_size: 5}
预期：返回群聊列表 JSON
3. 测试发消息（需要先把机器人拉入群）
python3 /workspace/skills/lark-skill/lark
mcp.py send ocxxxxxxxxxxxxxxxx 机器人连通测试
预期：飞书群收到消息
4. 测试通讯录查询
python3 /workspace/skills/lark-skill/lark
mcp.py call contactv3
userbatchGetId {}
预期：返回用户信息
全部通过 → 配置完成 ✅
四、调用方式详解
标准格式
bash
python3 /workspace/skills/lark-skill/lark_mcp.py <命令> [参数]
命令分类
A. 便捷命令（简化操作，无需记工具名）
| 命令 | 示例 | 说明 |
|---|
| send <chatid> <消息> | send ocxxx 你好 | 发文本消息到群 |
| chats |
chats | 获取群聊列表（返回 chat_id） |
| search <关键词> | search 项目报告 | 搜索云文档（需 User Token）|
| doc
| doc W7FOdr5aQo9F1 | 读取云文档全文（需 User Token）|
| user id> | user ouxxx | 查询单个用户信息 |
| call <工具名> | call imv1chat_list {} | 调用任意底层工具 |
B. 底层工具调用格式
bash
python3 /workspace/skills/lark-skill/lark_mcp.py call <工具名>
⚠️ JSON 参数必须用单引号包裹，外层用双引号，这是 shell 转义要求。
五、每个场景的完整调用示例
场景 1：发文本消息到群
bash
python3 /workspace/skills/lark-skill/larkmcp.py send ocxxxxxxxxxxxxxxxx 各位同事，明天上午10点开会，请准时参加
