back
loading skill details...
>-
飞书搜索
搜索飞书云文档、消息和应用。所有搜索命令必须使用 User Access Token。
feishu-cli：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式。
执行流程
每次执行搜索前，按以下流程操作：
1. 预检 scope（推荐 AI Agent 使用）
feishu-cli auth check --scope "search:docs:read"
# 或同时检查多个
feishu-cli auth check --scope "search:docs:read search:message"
根据返回结果判断：
ok=true → 直接执行搜索（步骤 3）
error=not_logged_in 或 error=token_expired → 登录（步骤 2）
missing=[...] 非空 → 先在飞书开放平台为应用开通缺失的 scope（见步骤 2），然后重新登录
2. 登录获取 Token（如需要）
本项目使用 Device Flow（RFC 8628）授权，无需任何 redirect URL 配置。AI Agent 推荐用后台阻塞模式：
# 后台启动（Claude Code 的 run_in_background=true）
feishu-cli auth login --scope "search:docs:read search:message" --json
首行 stdout 输出 {"event":"device_authorization","verification_uri_complete":"...","user_code":"...","expires_in":240,...}。将 verification_uri_complete 展示给用户，等用户在浏览器完成授权后后台进程自动退出，第二行 stdout 输出 {"event":"authorization_complete",...}。
如果 auth check 返回 missing=[...]，说明应用还没开通所需权限。feishu-cli 不做权限申请自动化——引导用户自己去飞书开放平台：
打开飞书开放平台 → 你的应用 → 权限管理页面
搜索并开通缺失的 scope（例如 search:docs:read、search:message），或复制 README 的完整 JSON 一次性导入
等待 tenant 管理员审批（如果需要）
审批通过后再执行 feishu-cli auth login --scope "search:docs:read search:message" --json
详细的 AI Agent 授权约定见 feishu-cli-auth 技能。
3. 执行搜索
登录后所有搜索命令自动从 ~/.feishu-cli/token.json 读取 Token，无需手动传递。
搜索云文档
搜索当前用户有权访问的飞书云文档和 Wiki。scope: search:docs:read
feishu-cli search docs "关键词" [选项]
选项
参数
类型
默认值
说明
--docs-types
string
全部
文档类型过滤（逗号分隔，小写）
--count
int
20
返回数量（0-50）
--offset
int
0
偏移量（offset + count < 200）
--owner-ids
string
—
文件所有者 Open ID（逗号分隔）
--chat-ids
string
—
文件所在群 ID（逗号分隔）
-o json
string
—
JSON 格式输出
文档类型（小写）
类型
说明
类型
说明
doc
旧版文档
docx
新版文档
sheet
电子表格
slides
幻灯片
bitable
多维表格
mindnote
思维笔记
file
文件
wiki
知识库文档
shortcut
快捷方式
示例
# 基础搜索
feishu-cli search docs "产品需求"
# 只搜索新版文档和 Wiki
feishu-cli search docs "技术方案" --docs-types docx,wiki
# 搜索电子表格
feishu-cli search docs "数据报表" --docs-types sheet
# 分页获取更多
feishu-cli search docs "季度报告" --count 50
# 分页查询：获取第一页（20 条）
feishu-cli search docs "季度报告" --count 20 --offset 0
# 分页查询：获取第二页
feishu-cli search docs "季度报告" --count 20 --offset 20
# JSON 格式输出（适合程序解析）
feishu-cli search docs "产品需求" -o json
v1 vs v2：何时用 drive search？
search docs（v1，本节）走 /open-apis/suite/docs-api/search/object，filter 简单（owner_ids / chat_ids / docs_types）。
drive search（v2，详见 feishu-cli-drive 技能 §9）走 /open-apis/search/v2/doc_wiki/search，支持更精细的扁平 filter：
--folder-tokens 限定云盘文件夹（与 --space-ids 互斥）
--space-ids 限定知识库 space
--creator-ids / --sharer-ids 多人扇出
--only-title / --only-comment 维度限定
--sort 排序（edit_time / open_time / create_time / default）
两者都需要 search:docs:read，按需选择：粗筛用 v1，精筛用 v2。
JSON 输出格式
{
"Total": 35367,
"HasMore": true,
"ResUnits": [
{
"DocsToken": "doc_token_xxx",
"DocsType": "docx",
"Title": "产品需求文档 - Q2",
"OwnerID": "ou_xxx",
"URL": "https://feishu.cn/docx/doc_token_xxx"
}
]
}
DocsToken 可以直接用于 feishu-cli doc get、doc export 等文档操作命令。
搜索消息
搜索飞书消息记录。scope: search:message
feishu-cli search messages "关键词" [选项]
选项
参数
类型
说明
--chat-ids
string
限定群聊范围（逗号分隔）
--from-ids
string
限定发送者 ID（逗号分隔）
--at-chatter-ids
string
限定被@的用户 ID（逗号分隔）
--message-type
string
消息类型：file/image/media
--chat-type
string
会话类型：group_chat/p2p_chat
--from-type
string
发送者类型：bot/user
--start-time
string
起始时间（Unix 秒级时间戳）
--end-time
string
结束时间（Unix 秒级时间戳）
--page-size
int
每页数量（默认 20）
--page-token
string
分页 token（上一页返回）
-o json
string
JSON 格式输出
示例
# 搜索消息
feishu-cli search messages "上线"
# 搜索私聊消息（search-chats 无法搜到 p2p 会话，用此方式替代）
feishu-cli search messages "你好" --chat-type p2p_chat
# 搜索群聊中的文件消息
feishu-cli search messages "周报" --chat-type group_chat --message-type file
# 搜索机器人消息
feishu-cli search messages "告警" --from-type bot
# 限定时间范围
feishu-cli search messages "项目" --start-time 1704067200 --end-time 1704153600
# 限定特定群
feishu-cli search messages "会议" --chat-ids oc_xxx,oc_yyy
提示：搜索群聊 API（search-chats）无法搜到 p2p 私聊会话。要查找私聊内容，使用 search messages --chat-type p2p_chat。
JSON 输出格式
{
"MessageIDs": ["om_xxx", "om_yyy"],
"PageToken": "ea9dcb2f...",
"HasMore": true
}
返回的 MessageIDs 可用 feishu-cli msg get <message_id> 获取消息详情。
搜索应用
搜索飞书应用。注意：搜索应用的 scope 需在飞书开发者后台确认是否可用，部分应用可能未开通此权限。
feishu-cli search apps "关键词" [选项]
选项
参数
类型
说明
--page-size
int
每页数量（默认 20）
--page-token
string
分页 token
-o json
string
JSON 格式输出
示例
feishu-cli search apps "审批"
feishu-cli search apps "OKR" --page-size 50
常见问题
问题
原因
解决
"缺少 User Access Token"
从未登录
执行两步式登录流程
"User Access Token 已过期"
access + refresh token 都过期
重新登录
99991679 权限错误提到搜索应用
应用未开通搜索应用权限，或该 scope 在开发者后台不可用
在飞书开发者后台确认是否已开通对应权限
99991679 权限错误提到 search:docs:read
登录时未包含 search:docs:read scope
重新登录，scope 加上 search:docs:read
搜索结果为空
关键词不匹配或无权限文档
尝试更宽泛的关键词，或检查文档权限
offset + count 超过 200
飞书 API 限制
最多翻到第 200 条结果
完整的认证流程和 Token 管理请参考 feishu-cli-auth 技能。
与其他技能的分工
场景
使用技能
按关键词搜索文档/应用
feishu-cli-search（本技能）
按关键词搜索消息（含高级筛选）
feishu-cli-search（本技能）
浏览群聊历史消息、搜索群聊列表
feishu-cli-chat
Reaction/Pin/删除/获取消息详情
feishu-cli-chat
群聊信息管理、成员管理
feishu-cli-chat
搜索消息与浏览聊天记录的区别：搜索（search messages）用关键词跨会话检索，返回消息 ID 列表；浏览（msg history）获取指定会话的连续消息流。如果用户的意图是"找到包含某关键词的消息"用搜索，"看看某个群最近在聊什么"用浏览。don't have the plugin yet? install it then click "run inline in claude" again.