飞书搜索技能

搜索飞书消息和应用。

重要说明：需要 User Access Token

此功能需要 User Access Token（用户授权令牌），而非应用的 Access Token。

获取 User Access Token 的方式

1. 在飞书开放平台创建应用并配置重定向 URL
2. 引导用户访问授权页面进行登录授权
3. 使用授权码换取 User Access Token

详细文档：用户授权

Token 提供方式

方式一：命令行参数

feishu-cli search messages "关键词" --user-access-token "u-xxx"

方式二：环境变量（推荐）

export FEISHU_USER_ACCESS_TOKEN="u-xxx"
feishu-cli search messages "关键词"

使用方法

/feishu-search messages "关键词"    # 搜索消息
/feishu-search apps "应用名"        # 搜索应用

CLI 命令详解

1. 搜索消息

# 基本搜索
feishu-cli search messages "会议" --user-access-token <token>

# 使用环境变量
export FEISHU_USER_ACCESS_TOKEN="u-xxx"
feishu-cli search messages "会议"

# 搜索指定会话中的消息
feishu-cli search messages "会议" --chat-ids oc_xxx,oc_yyy

# 搜索图片类型的消息
feishu-cli search messages "图片" --message-type image

# 搜索指定时间范围内的消息
feishu-cli search messages "项目" \
  --start-time 1704067200 \
  --end-time 1704153600

# 搜索群聊消息
feishu-cli search messages "周报" --chat-type group_chat

# 搜索单聊消息
feishu-cli search messages "反馈" --chat-type p2p_chat

# 搜索用户发送的消息（排除机器人）
feishu-cli search messages "通知" --from-type user

# JSON 格式输出
feishu-cli search messages "会议" --output json

参数说明：

参数	说明	示例值
--user-access-token	User Access Token	u-xxx
--chat-ids	会话 ID 列表（逗号分隔）	oc_xxx,oc_yyy
--from-ids	发送者用户 ID 列表（逗号分隔）	ou_xxx,ou_yyy
--at-chatter-ids	@的用户 ID 列表（逗号分隔）	ou_xxx
--message-type	消息类型	file, image, media
--chat-type	会话类型	group_chat, p2p_chat
--from-type	发送者类型	bot, user
--start-time	起始时间（Unix 时间戳，秒）	1704067200
--end-time	结束时间（Unix 时间戳，秒）	1704153600
--page-size	每页数量（默认 20）	50
--page-token	分页 token
--user-id-type	用户 ID 类型	open_id, union_id, user_id
--output, -o	输出格式	json

消息类型说明：

类型	说明
file	文件消息
image	图片消息
media	媒体消息（视频、音频）

会话类型说明：

类型	说明
group_chat	群聊
p2p_chat	单聊

2. 搜索应用

# 基本搜索
feishu-cli search apps "审批" --user-access-token <token>

# 使用环境变量
export FEISHU_USER_ACCESS_TOKEN="u-xxx"
feishu-cli search apps "审批"

# 分页获取更多结果
feishu-cli search apps "审批" --page-size 50

# JSON 格式输出
feishu-cli search apps "审批" --output json

参数说明：

参数	说明	默认值
--user-access-token	User Access Token	无
--page-size	每页数量	20
--page-token	分页 token	无
--user-id-type	用户 ID 类型	open_id
--output, -o	输出格式	文本

时间戳转换

搜索消息时使用 Unix 时间戳（秒）。常用转换：

获取当前时间戳：

date +%s

指定时间转时间戳：

# macOS
date -j -f "%Y-%m-%d %H:%M:%S" "2024-01-21 00:00:00" +%s

# Linux
date -d "2024-01-21 00:00:00" +%s

时间戳转日期：

# macOS
date -r 1704067200

# Linux
date -d @1704067200

典型工作流

搜索近 7 天的消息

# 计算 7 天前的时间戳
START_TIME=$(date -d "7 days ago" +%s)
END_TIME=$(date +%s)

# 搜索消息
feishu-cli search messages "项目进度" \
  --start-time $START_TIME \
  --end-time $END_TIME

搜索特定群聊中的文件

feishu-cli search messages "文档" \
  --chat-ids oc_xxx \
  --message-type file

搜索并导出结果

# 搜索并保存为 JSON
feishu-cli search messages "周报" --output json > search_results.json

# 使用 jq 处理结果
feishu-cli search messages "周报" --output json | jq '.items[].content'

搜索应用并获取详情

# 搜索应用
feishu-cli search apps "OKR"

# 获取更多结果
feishu-cli search apps "OKR" --page-size 50

注意事项

1. Token 必需：搜索功能必须提供 User Access Token
2. Token 有效期：User Access Token 有过期时间，需要及时刷新
3. 时间戳格式：使用 Unix 时间戳（秒），不是毫秒
4. 权限范围：只能搜索用户有权限访问的消息和应用
5. 环境变量优先：推荐使用 FEISHU_USER_ACCESS_TOKEN 环境变量，避免在命令中暴露 token

常见问题

Q: 如何获取 User Access Token？

A: 需要通过 OAuth 2.0 授权流程获取，参考官方文档。

Q: 搜索返回空结果？

A: 检查以下几点：

1. Token 是否有效
2. 搜索关键词是否正确
3. 时间范围是否合理
4. 用户是否有权限访问相关消息

Q: Token 过期怎么办？

A: User Access Token 有效期约 2 小时。使用 Refresh Token 刷新：

# 通过飞书开放平台 API 刷新 Token
curl -X POST "https://open.feishu.cn/open-apis/authen/v1/oidc/refresh_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "<your_refresh_token>",
    "app_id": "<app_id>",
    "app_secret": "<app_secret>"
  }'

Refresh Token 有效期 30 天，过期后需要用户重新授权。

搜索结果结构

消息搜索返回的每条结果包含：

字段	说明
message_id	消息唯一 ID
content	消息内容
sender	发送者信息（user_id、name）
chat_id	所在会话 ID
create_time	发送时间（Unix 时间戳）
message_type	消息类型（text/image/file 等）

应用搜索返回的每条结果包含：

字段	说明
app_id	应用 ID
name	应用名称
description	应用描述