Skill: longsasasasasa/my-lark (version 3.0.0)

--- name: my-lark version: 3.0.0 description: 飞书全能力技能。基于飞书官方工具服务，支持消息、群组、云文档、云盘、知识库、日历、审批、多维表格、电子表格、画板、通讯录全部模块。面向小白：安装即用，每一步都有操作指引；面向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. 打开 [飞书开放平台](https://open.feishu.cn/app) → 用管理员账号登录 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： ``` 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 '[REDACTED_SECRET]' \ -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": [[REDACTED_SECRET]] }' # 查询部门下所有用户 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](https://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` | ✅ | --- ## 八、调试与排障流程图 ``` 工具调用报错 │ ├─ 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 详解 |


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)