feishu-ops

name	feishu_ops
description	飞书操作：向用户/群组发送消息（文字/富文本/图片/文件）、读写云文档/电子表格/多维表格、查询群成员、管理日历事件。适合推送通知、发送处理结果文件、读取共享文档、批量发送报告等场景。
type	task
version	3.1
metadata	{"requires":{"bins":["lark-cli","python3"]}}

feishu_ops Skill

⚠️ 安全约束（CRITICAL）：所有飞书操作必须通过本目录下的 scripts/ 脚本执行。
禁止直接调用：lark-cli 命令、全局 lark-* skills、飞书 OpenAPI。

脚本自动从 feishu.json 读取凭证和 lark-cli profile，无需手动处理鉴权。

调用方式：python {_skill_base}/scripts/<脚本名>.py [参数]

---

一、发送消息

send_text.py — 发送纯文字消息

python {_skill_base}/scripts/send_text.py \
    --routing_key <routing_key> \
    --text "消息内容"

参数	必填	说明
--routing_key	✅	p2p:ou_xxx（私聊）或 group:oc_xxx（群组）
--text	✅	纯文本消息内容

---

send_post.py — 发送富文本消息（带标题 + 多段落）

python {_skill_base}/scripts/send_post.py \
    --routing_key <routing_key> \
    --title "消息标题" \
    --paragraphs '["第一段内容", "第二段，含[链接](https://example.com)"]'

参数	必填	说明
--routing_key	✅	同上
--title	否	消息标题，可为空
--paragraphs	✅	JSON 字符串数组；支持 [文字](URL) 格式内嵌链接

---

send_image.py — 发送图片

python {_skill_base}/scripts/send_image.py \
    --routing_key <routing_key> \
    --image_path /workspace/sessions/{session_id}/outputs/chart.png

参数	必填	说明
--routing_key	✅	同上
--image_path	✅	图片绝对路径（jpg/png/gif/webp，≤30MB）

---

send_file.py — 发送文件

python {_skill_base}/scripts/send_file.py \
    --routing_key <routing_key> \
    --file_path /workspace/sessions/{session_id}/outputs/report.pdf

参数	必填	说明
--routing_key	✅	同上
--file_path	✅	文件绝对路径（pdf/doc/xls/ppt/mp4 等，≤30MB）

---

二、读取飞书云文档

read_doc.py — 读取飞书文档内容（带本地缓存）

python {_skill_base}/scripts/read_doc.py \
    --doc "https://xxx.feishu.cn/docx/doccnXXXXXX" [--no-cache] [--verify-remote]

参数	必填	说明
--doc	✅	飞书文档 URL 或 doc_token
--no-cache	否	跳过本地缓存，强制远程拉取
--verify-remote	否	命中本地后顺手校验远程 revision 是否变化（变化只 warning，仍返回本地快照）

缓存逻辑：若该飞书文档由本工作区通过 create_doc.py 上传过，且本地源 md 文件仍存在、内容未变，则直接读本地文件返回（data.source == "local_cache"），不再下载。否则走远程（data.source == "remote"）。

read_sheet.py — 读取飞书电子表格数据

python {_skill_base}/scripts/read_sheet.py \
    --sheet "https://xxx.feishu.cn/sheets/shtcnXXXXXX" \
    --sheet_id Sheet1 \
    --range A1:D10

---

三、查询群成员

get_chat_members.py — 获取群组成员列表

python {_skill_base}/scripts/get_chat_members.py --chat_id oc_xxxxx

---

四、日历操作

list_events.py — 查询日历事件

python {_skill_base}/scripts/list_events.py \
    --calendar_id primary \
    --start_time 2026-03-01T00:00:00+08:00 \
    --end_time 2026-03-31T23:59:59+08:00

create_event.py — 创建日历事件

python {_skill_base}/scripts/create_event.py \
    --summary "周例会" \
    --start_time 2026-04-09T10:00:00+08:00 \
    --end_time 2026-04-09T11:00:00+08:00 \
    --description "本周进度同步" \
    --attendees '["ou_aaa", "ou_bbb"]'

---

五、创建文档 / 表格

create_doc.py — 把本地 Markdown 文件上传为飞书文档（带去重缓存）

⚠️ 只接受本地 .md 文件路径。--content / --content_file 已废弃，传了会报 errcode: 2。 上传前若同内容（按 sha256）已上传过，直接复用旧链接（data.cached == true），不重复上传。

python {_skill_base}/scripts/create_doc.py \
    --file_path "$WORKSPACE_DIR/outputs/report.md" \
    --title "AI PM 前期沟通报告" [--folder_token <token>] [--no-cache]

参数	必填	说明
--file_path	✅	本地 .md 文件绝对路径，必须在当前 workspace 内，≤10MB
--title	否	文档标题（默认取文件名去后缀）
--folder_token	否	目标飞书文件夹 token（留空放根目录）
--no-cache	否	跳过缓存命中，强制重新上传

返回 data：{url, document_id, cached(bool), sha256, record_id}。

上传前要先生成/保存 md 文件时：见下方「八、文件存放规范」——优先放到项目内合适位置，没有归属时才放 $WORKSPACE_DIR/tmp_file/，禁止放 /tmp、CWD、skill 目录内。

dump_index.py — 查看上传索引

python {_skill_base}/scripts/dump_index.py [--status active|deleted|remote_missing|all]

create_sheet.py — 创建电子表格

python {_skill_base}/scripts/create_sheet.py --title "销售数据"

upload_sheet.py — 导入本地 Excel 为飞书表格

python {_skill_base}/scripts/upload_sheet.py \
    --file_path /workspace/outputs/report.xlsx \
    --title "销售报告"

write_sheet.py — 向表格写入数据

python {_skill_base}/scripts/write_sheet.py \
    --sheet "https://xxx.feishu.cn/sheets/shtcnXXXX" \
    --values '[["姓名","年龄"],["Alice",30]]'

---

六、多维表格（Bitable）

create_bitable.py — 创建多维表格应用

python {_skill_base}/scripts/create_bitable.py --name "项目管理"

create_bitable_table.py — 创建数据表

python {_skill_base}/scripts/create_bitable_table.py \
    --app "https://xxx.feishu.cn/base/BxxXXXX" \
    --name "任务清单" \
    --fields '[{"name":"任务名称","type":"text"},{"name":"优先级","type":"select","options":["高","中","低"]}]'

write_bitable_records.py — 批量写入记录

python {_skill_base}/scripts/write_bitable_records.py \
    --app "https://xxx.feishu.cn/base/BxxXXXX" \
    --table_id tblXXXXXX \
    --records '[{"任务名称":"完成API文档","优先级":"高"}]'

---

七、文件存放规范（上传飞书文档前必读）

调用 create_doc.py 前若需要先生成或保存 .md 文件，存放位置遵循以下优先级：

1. 项目内合适位置（首选）：md 文档若属于工作产物（课程稿、报告、设计文档），放到对应业务目录： ai-pm/、multi-agent/、企业培训/<客户>/、.claude/skills/<skill>/docs/ 等。
2. $WORKSPACE_DIR/tmp_file/（次选）：纯过渡性、无明确归属的 md，放这里（可建子目录）。
3. 禁止放到 /tmp、/var/tmp、当前工作目录（CWD）、skill 目录根目录或 scripts/ 下。

create_doc.py 会拒绝当前 workspace 之外的文件路径，并提示重新放置。

---

八、文档缓存与索引（内部机制）

• 索引库：{_skill_base}/index/doc_cache.db（SQLite，自动创建）。
• 记录每次上传的 (sha256, 飞书 doc_token/url, 本地源路径, 标题, ...) 映射。
• create_doc.py 上传前查 sha256；read_doc.py 读取前查 doc_token。命中即走本地，省去重复上传/下载。
• 索引写入失败不会让上传失败（上传是不可逆操作，索引只是优化层）。
• 用 dump_index.py 查看，无需手工编辑 db 文件。

---

输出格式

所有脚本统一输出 JSON 到 stdout：

{"errcode": 0, "errmsg": "success", "data": {...}}
{"errcode": 1, "errmsg": "错误说明\n建议：...", "data": {}}