飞书集成

8 模块 60+ 命令操作飞书全量 API

统一 CLI 覆盖文档(含全文搜索+导出含图)、任务 v2、Wiki(搜索+导出)、多维表格(条件筛选)、消息(文本/卡片/富文本)、审批(完整生命周期)、成员目录。OAuth2 全自动。仅依赖 Python 3 标准库。

命令

说明

示例

list

列出云空间文件

./feishu doc list

tree

递归目录树

./feishu doc tree --token "xxx"

read-raw

按名称搜索并读取

./feishu doc read-raw --name "需求文档"

search-content

全文搜索

./feishu doc search-content --query "退款" --read

create-from-markdown

从 MD 创建

./feishu doc create-from-markdown --file plan.md

append-markdown

追加 Markdown

./feishu doc append-markdown --document-id "xxx" --file spec.md

export

导出为 Markdown

./feishu doc export --document-id TOKEN --images --output path.md

shared-add

添加共享文件夹

./feishu doc shared-add --url "https://..."

trash

移入回收站

./feishu doc trash --token "xxx"

命令

说明

示例

send --text

发文本到群

./feishu msg send --chat-id oc_xxx --text "消息内容"

send --user

发消息给个人

./feishu msg send --user "张三" --text "已确认"

send --card

发卡片消息

./feishu msg send --chat-id oc_xxx --card card.json

send --post

发富文本消息

./feishu msg send --chat-id oc_xxx --post "内容" --title "标题"

chats

查看群列表

./feishu msg chats [--name "产品"]

chat-info

群详情

./feishu msg chat-info --chat-id oc_xxx

history

消息记录

./feishu msg history --chat-id oc_xxx --count 20

命令

说明

示例

list-definitions

查看审批模板

./feishu approval list-definitions

get-definition

模板详情

./feishu approval get-definition --code CODE

create

创建审批

./feishu approval create --code CODE --form '{...}'

get

查看审批详情

./feishu approval get --instance-id ID

list

列出审批实例

./feishu approval list --code CODE --status PENDING

approve

同意审批

./feishu approval approve --instance-id ID --task-id TID

reject

拒绝审批

./feishu approval reject --instance-id ID --task-id TID --comment "理由"

cancel

撤销审批

./feishu approval cancel --instance-id ID

命令

说明

示例

create

创建任务

./feishu task create --summary "审计" --due "2026-03-01"

list

列出任务

./feishu task list --keyword "重构" --completed false

update

更新任务

./feishu task update --task-id "xxx" --summary "新标题"

complete

标记完成

./feishu task complete --task-id "xxx"

comment

添加评论

./feishu task comment --task-id "xxx" --content "已完成"

tasklist-create

创建清单/Sprint

./feishu task tasklist-create --name "Sprint-1"

batch-create

批量创建

./feishu task batch-create --file tasks.json --tasklist-id "xxx"

命令

说明

示例

list-tables

列出数据表

./feishu bitable list-tables --app-token "basXXX"

list-fields

列出字段

./feishu bitable list-fields --app-token "xxx" --table-id "yyy"

list-records

列出记录

./feishu bitable list-records --app-token "xxx" --table-id "yyy"

--filter

条件筛选

./feishu bitable list-records --filter 'CurrentValue.[status]="active"'

create-record

创建记录

./feishu bitable create-record --fields '{"Name":"test"}'

batch-create

批量创建 (500自动分批)

./feishu bitable batch-create --file records.json

export

导出 CSV/JSON

./feishu bitable export --format csv --output data.csv

命令

说明

示例

space-list

列出空间

./feishu wiki space-list

tree

递归目录树

./feishu wiki tree --space-id "xxx" --depth 3

node-read

读取节点

./feishu wiki node-read --token "xxx"

search

搜索知识库

./feishu wiki search --query "退款" --read

create-from-markdown

从 MD 创建

./feishu wiki create-from-markdown --space-id "xxx" --file spec.md

export

导出含图片

./feishu wiki export --url "https://xxx.feishu.cn/wiki/TOKEN"

命令

说明

示例

scan

扫描并缓存 (7天TTL)

./feishu member scan

find

子串匹配查找

./feishu member find --name "张三"

whoami

当前用户

./feishu member whoami

首次配置

首次使用需要 4 步配置，之后 Agent 全自动管理认证。

1. 创建飞书自建应用

打开飞书开放平台，创建一个自建应用。

2. 开通权限

进入应用的 权限管理 页面，全选开通所有用户权限。OAuth2 登录时会按需请求实际所需的 scope。

3. 配置安全设置 & 发布

安全设置 → 重定向 URL → 添加 http://localhost:9876/callback
版本管理 → 创建版本 → 发布上线

4. 设置凭据 & 登录

复制应用凭证页面的 App ID 和 App Secret，直接告诉 Agent 即可完成登录。

Agent 会自动设置环境变量并执行 ./feishu auth login 完成 OAuth2 授权。

使用场景

Sprint Planning — 批量创建任务

> "把这些需求拆成任务放到 Sprint-1 里"

Agent 执行:
1. ./feishu task tasklist-create --name "Sprint-1"
2. ./feishu task batch-create --file tasks.json --tasklist-id "$TASKLIST"

全文搜索 + 自动读取

> "帮我找一下关于退款的文档"

Agent 执行:
./feishu doc search-content --query "退款" --read
# 搜索到 3 个文档，自动读取内容

也支持按类型过滤：doc search-content --query "数据" --type docx,wiki

发消息到群

> "告诉产品群审批已通过"

Agent 执行:
1. ./feishu msg chats --name "产品"  → oc_xxx
2. ./feishu msg send --chat-id oc_xxx --text "审批已通过"

也可以发给个人：./feishu msg send --user "张三" --text "已确认"

审批管理

> "帮我提交一个出差审批"

Agent 执行:
1. ./feishu approval list-definitions  → 找到出差审批模板
2. ./feishu approval get-definition --code TRAVEL  → 查看表单字段
3. ./feishu approval create --code TRAVEL --form '{"destination":"..."}'

文档导出 (含图片)

bash

# 导出文档为 Markdown，图片下载到本地
./feishu doc export --document-id TOKEN --images --output path.md

# 按名称导出
./feishu doc export --name "方案"

# Wiki 导出
./feishu wiki export --url "https://xxx.feishu.cn/wiki/TOKEN"

Wiki 知识库搜索

bash

# 搜索知识库并自动读取
./feishu wiki search --query "退款" --read

# 限定空间搜索
./feishu wiki search --query "退款" --space-id ID

技术方案发布到 Wiki

bash

./feishu wiki create-from-markdown --space-id "$SPACE" --title "支付方案 v2" --file plan.md

多维表格条件筛选

bash

# 按条件筛选记录
./feishu bitable list-records --filter 'CurrentValue.[status]="active"'

# 导出
./feishu bitable export --app-token "basXXX" --table-id "tblXXX" --format csv

认证说明

首次配置完成后，认证由 Agent 全自动处理：

Token 2h 过期后自动刷新，无需手动操作
使用 member 模块时自动增量授权 contact:user.base:readonly scope
仅使用 user_access_token（用户身份），不降级到应用身份

错误恢复

错误码	含义	处理
99991663	Token 过期	引擎自动处理。持续出现：`auth refresh`
99991679	Scope 不足	自动增量授权。持续出现：`auth relogin`
100003	权限不足	用户去控制台启用 scope → `auth relogin`
1470400	参数错误	检查格式（URL 需 `http://`/`https://`）
Member not found	—	`member scan` 刷新缓存，缩短关键词重试

模块架构

feishu (Bash CLI 入口)
│
├── doc      → docx.py      文档 & 云空间（CRUD + 全文搜索 + Markdown↔Block + 导出含图）
├── task     → task.py      任务 v2（CRUD + tasklist + batch + comment + 时间管理）
├── wiki     → wiki.py      知识库（空间/节点/递归 tree + 搜索 + create + 导出含图）
├── bitable  → bitable.py   多维表格（CRUD + 条件筛选 + 500条自动分批 + JSON/CSV 导出）
├── msg      → msg.py       消息（send 文本/卡片/富文本 + chats + chat-info + history）
├── approval → approval.py  审批（list-definitions + create + get + list + approve + reject + cancel）
├── member   → members.py   成员目录（扫描 + 7天缓存 + 子串匹配 + 反向解析）
└── auth     → auth.py      OAuth2（login / refresh / relogin + 增量授权）
               ↓
            feishu_api.py    核心引擎 (HTTP + 429/5xx 自动重试 + 分页 + token 解析 + 媒体下载)
               ↓
         ~/.feishu/credentials.json

飞书集成

核心能力

文档 + 全文搜索 + 导出

消息 (msg)

审批 (approval)

任务管理 v2

多维表格

Wiki + 搜索 + 导出

CJK 智能列宽

OAuth2 全自动

命令参考

文档 (doc)

消息 (msg)

审批 (approval)

任务 (task)

多维表格 (bitable)

知识库 (wiki)

成员 (member)

首次配置

1. 创建飞书自建应用

2. 开通权限

3. 配置安全设置 & 发布

4. 设置凭据 & 登录

使用场景

Sprint Planning — 批量创建任务

全文搜索 + 自动读取

发消息到群

审批管理

文档导出 (含图片)

Wiki 知识库搜索

技术方案发布到 Wiki

多维表格条件筛选

认证说明

错误恢复

模块架构

快速开始

飞书集成

核心能力

文档 + 全文搜索 + 导出

消息 (msg)

审批 (approval)

任务管理 v2

多维表格

Wiki + 搜索 + 导出

CJK 智能列宽

OAuth2 全自动

命令参考

文档 (doc)

消息 (msg)

审批 (approval)

任务 (task)

多维表格 (bitable)

知识库 (wiki)

成员 (member)

首次配置 ​

1. 创建飞书自建应用 ​

2. 开通权限 ​

3. 配置安全设置 & 发布 ​

4. 设置凭据 & 登录 ​

使用场景 ​

Sprint Planning — 批量创建任务 ​

全文搜索 + 自动读取 ​

发消息到群 ​

审批管理 ​

文档导出 (含图片) ​

Wiki 知识库搜索 ​

技术方案发布到 Wiki ​

多维表格条件筛选 ​

认证说明 ​

错误恢复 ​

模块架构 ​

快速开始

首次配置

1. 创建飞书自建应用

2. 开通权限

3. 配置安全设置 & 发布

4. 设置凭据 & 登录

使用场景

Sprint Planning — 批量创建任务

全文搜索 + 自动读取

发消息到群

审批管理

文档导出 (含图片)

Wiki 知识库搜索

技术方案发布到 Wiki

多维表格条件筛选

认证说明

错误恢复

模块架构