version: "1.0.1" name: feishu-cli-search description: >- 搜索飞书云文档、消息和应用。当用户请求"搜索文档"、"搜索消息"、"搜索应用"、"找文档"、 "search docs"、"查找飞书文档"、"有没有关于 xxx 的飞书文档"时使用。 也适用于：用户想查找某个主题的飞书文档或 Wiki、按关键词检索消息记录、查找内部应用。 搜索 API 必须使用 User Access Token，本技能包含完整的认证前置检查流程。 argument-hint: docs | messages | apps <query> 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 不做权限申请自动化——引导用户自己去飞书开放平台：

1. 打开飞书开放平台 → 你的应用 → 权限管理页面
2. 搜索并开通缺失的 scope（例如 search:docs:read、search:message），或复制 README 的完整 JSON 一次性导入
3. 等待 tenant 管理员审批（如果需要）
4. 审批通过后再执行 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 "关键词" [选项]

选项

文档类型（小写）

示例

# 基础搜索
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 "关键词" [选项]

选项

`--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 "关键词" [选项]

选项

示例

feishu-cli search apps "审批"
feishu-cli search apps "OKR" --page-size 50

常见问题

完整的认证流程和 Token 管理请参考 `feishu-cli-auth` 技能。

与其他技能的分工

搜索消息与浏览聊天记录的区别：搜索（search messages）用关键词跨会话检索，返回消息 ID 列表；浏览（msg history）获取指定会话的连续消息流。如果用户的意图是"找到包含某关键词的消息"用搜索，"看看某个群最近在聊什么"用浏览。