My Lark（飞书全能力技能）

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

一、完整功能索引

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

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

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. 左侧「版本管理与发布」→ 创建版本 → 申请发布 → 管理员审批

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

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

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

第二步：配置凭证文件

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

{
  "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：

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：

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

npm install -g @larksuite/lark-mcp

验证安装成功：

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

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

# 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 '{}'
# 预期：返回用户信息

全部通过 → 配置完成 ✅

四、调用方式详解

标准格式

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

命令分类

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

B. 底层工具调用格式

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

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

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

场景 1：发文本消息到群

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

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

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

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

返回示例：

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

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

场景 3：发送富文本消息

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：搜索云文档

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

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

场景 5：读取云文档内容

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

⚠️ 需要 user_access_token 配置正确。

场景 6：读写电子表格

# 读取单元格（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：操作多维表格（增删改查记录）

# 列出所有多维表格
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：日历管理

# 查询日历列表
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：通讯录查询

# 查询已知用户的信息
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：提交审批

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：知识库操作

# 搜索知识库
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：云盘文件管理

# 获取云盘根目录
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：下载画板为图片

# 获取画板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 语法

# 解析 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
}'

六、异常处理（完整版）

运行时错误速查

99991403 权限不足——分类诊断

网络与连接错误

七、凭证与权限体系详解

凭证种类

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

八、调试与排障流程图

工具调用报错
  │
  ├─ 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 确认可用性，重试

九、频率限制参考

十、参考文件索引