Feishu Cli Search

# 飞书搜索

搜索飞书云文档、消息和应用。所有搜索命令**必须使用 User Access Token**。

> **feishu-cli**：如尚未安装，请前往 [riba2534/feishu-cli](https://github.com/riba2534/feishu-cli) 获取安装方式。

## 执行流程

每次执行搜索前，按以下流程操作：

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

```bash
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 推荐用后台阻塞模式：

```bash
# 后台启动（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`**

```bash
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` | 快捷方式 | | |

### 示例

```bash
# 基础搜索
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 输出格式

```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`**

```bash
feishu-cli search messages "关键词" [选项]
```

### 选项

| 参数 | 类型 | 说明 |
|------|------|------|
| `--chat-ids` | string | 限定群聊范围（逗号分隔） |
| `--from-ids` | string