feishu-cli-search

name: feishu-cli-search description: >- 搜索飞书云文档、消息和应用。当用户请求"搜索文档"、"搜索消息"、"搜索应用"、"找文档"、 "search docs"、"查找飞书文档"、"有没有关于 xxx 的飞书文档"时使用。也适用于：用户想查找某个主题的飞书文档或 Wiki、按关键词检索消息记录、查找内部应用。搜索 API 必须使用 User Access Token，本技能包含完整的认证前置检查流程。 argument-hint: docs | messages | apps user-invocable: true allowed-tools: Bash(feishu-cli search:), Bash(feishu-cli auth:), Read

飞书搜索

搜索飞书云文档、消息和应用。所有搜索命令必须使用 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 search:app"

根据返回结果判断：

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（上一页返回）
`--page-all`	bool	自动翻页拉取全部（受 `--page-limit` 限制）
`--page-limit`	int	自动翻页最大页数，`0`=不限（默认 0）；配合 `--page-all` 防失控
`--enrich`	bool	补全内容/发送者/群名/时间（opt-in，额外 API 调用）
`--card-content-type`	string	interactive 卡片富化格式：`user`（默认，提取 `card_texts`）/ `raw`（平台内部完整 cardDSL）/ `rendered`（OAPI 渲染版/降级版）。仅在 `--enrich` 时生效，非 enrich 路径忽略
`--format`	string	结构化输出：`json`/`pretty`/`table`/`ndjson`/`csv`
`--jq`	string	用 jq 表达式过滤结构化输出
`--user-id-type`	string	用户 ID 类型：`open_id`（默认）/`union_id`/`user_id`
`-o json`	string	JSON 格式输出（等价 `--format json`）

--page-all 截断无提示：仅非翻页模式（!--page-all 且 HasMore=true）会打印"还有更多结果"。当 --page-all 因达到 --page-limit 提前停止（而非真正耗尽）时，CLI 不会提示结果被截断——需要拉全量时把 --page-limit 设为 0，或结合 JSON 输出的 HasMore 自行判断。

默认 vs --enrich：默认仅返回消息 ID（-o json 输出 {MessageIDs,HasMore,PageToken}），与历史行为一致、向后兼容。加 --enrich 才会多发 BatchGetMessages 等 API 补全内容/发送者/群名/时间，-o json 此时返回富化后的数组。

示例

# 搜索消息（默认返回消息 ID）
feishu-cli search messages "上线"

# 富化：补全内容/发送者/群名/时间
feishu-cli search messages "上线" --enrich
feishu-cli search messages "上线" --enrich --format table

# 富化 + 控制卡片消息格式（仅 --enrich 生效）
feishu-cli search messages "告警" --enrich --card-content-type raw

# 富化 + 自动翻页（最多 5 页，防失控）
feishu-cli search messages "项目" --enrich --page-all --page-limit 5 --format csv

# 搜索私聊消息（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 输出格式

默认（无 --enrich）：

{
  "MessageIDs": ["om_xxx", "om_yyy"],
  "PageToken": "ea9dcb2f...",
  "HasMore": true
}

返回的 MessageIDs 可用 feishu-cli msg get <message_id> 获取消息详情。

加 --enrich 时返回富化后的数组：

[
  {
    "message_id": "om_xxx",
    "msg_type": "text",
    "chat_id": "oc_xxx",
    "chat_name": "项目群",
    "sender_id": "ou_xxx",
    "sender_name": "张三",
    "create_time": "1704067200000",
    "time": "2024-01-01 08:00:00",
    "text": "今天上线"
  }
]

搜索应用

搜索飞书应用。scope: search:app（飞书官方注册表名，可在飞书开放平台 → 应用 → 权限管理搜索开通；该 scope recommend=false，默认不会被 auth login --recommend 自动包含，需要 auth login --scope "search:app" 显式申请。若飞书侧已重命名，以 feishu-cli auth check --scope "search:app" 报错信息为准。）

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 未包含 `search:app`，或飞书开放平台未开通该权限	`feishu-cli auth login --scope "search:app"`；如仍报错，去飞书开放平台权限管理页搜索 `search:app` 并开通（必要时联系 tenant 管理员审批）
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）获取指定会话的连续消息流。如果用户的意图是"找到包含某关键词的消息"用搜索，"看看某个群最近在聊什么"用浏览。

飞书搜索

执行流程

1. 预检 scope（推荐 AI Agent 使用）

2. 登录获取 Token（如需要）

3. 执行搜索

搜索云文档

选项

文档类型（小写）

示例

v1 vs v2：何时用 drive search？

JSON 输出格式

搜索消息

选项

示例

JSON 输出格式

搜索应用

选项

示例

常见问题

与其他技能的分工

v1 vs v2：何时用 `drive search`？