# Tvsearch

> Tavily 网页搜索工具。使用 tvsearch CLI 通过 Tavily Search API 搜索网页内容。触发场景：用户要求 Tavily 搜索、网页搜索、互联网搜索、查新闻、查资料、查教程、做主题调研、获取公开网页信息、需要结构化搜索结果。

- Skill: `lyhue1991/tvsearch` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lyhue1991/tvsearch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lyhue1991/tvsearch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: lyhue1991 (https://skillmd.com/u/lyhue1991)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lyhue1991/tvsearch

---


# tvsearch

封装 `tvsearch` 命令行工具，用于通过 Tavily API 进行网页搜索。

## 核心能力

1. **网页搜索** - 查询公开网页与资讯内容，返回结构化结果
2. **时间过滤** - 支持最近一天、一周、一月、一年的结果过滤
3. **搜索深度** - 支持 basic (1 credit) 和 advanced (2 credit) 两种深度
4. **主题分类** - 支持 general (通用) 和 news (新闻) 两种主题
5. **多格式输出** - 支持 JSON、Markdown、表格格式
6. **配置管理** - 支持 API Key 配置与默认参数管理
7. **配额查询** - 查看 Tavily API 配额使用情况

## 工作流程

### 搜索执行

当用户表达搜索、查资料、查新闻、做调研意图时，执行搜索命令:

```bash
tvsearch "关键词" --format json --count 10
```

常用搜索模式:

```bash
tvsearch "人工智能" --count 10 --format json      # 基础搜索，JSON 格式
tvsearch "最新新闻" --topic news --freshness pd   # 搜索新闻，过去一天
tvsearch "深度调研" --depth advanced              # 高级搜索，结果更精准
tvsearch "AI 教程" -f markdown -c 5               # Markdown 输出 5 条结果
```

### 错误排查

如果执行失败，按以下步骤排查:

```
1. 检查安装 → 2. 检查认证配置
```

**Step 1: 检查是否安装 tvsearch**

```bash
command -v tvsearch
```

如果未安装，执行:
```bash
npm install -g @lyhue1991/tvsearch
```

或直接使用 npx:
```bash
npx @lyhue1991/tvsearch "关键词"
```

**Step 2: 检查认证配置**

检查本地配置:
```bash
tvsearch config --show
```

如果未配置，检查环境变量:
```bash
printenv TAVILY_API_KEY
```

如果仍然未配置，需要用户提供 Tavily API Key，然后执行:
```bash
tvsearch config --set-api-key "tvly-xxxxx"
```

获取 API Key: https://tavily.com

### 配置管理

设置 API Key 和默认参数:
```bash
tvsearch config --set-api-key "tvly-xxxxx"
tvsearch config --default-format json --default-count 10
```

查看当前配置:
```bash
tvsearch config --show
```

重置配置:
```bash
tvsearch config --reset
```

### 配额查询

查看 Tavily API 配额使用情况:
```bash
tvsearch usage                  # JSON 格式
tvsearch usage --format table   # 表格格式
tvsearch usage --format markdown # Markdown 格式
```

配额信息包括：
- API Key 级别使用量（search/crawl/extract/map/research）
- 账户套餐信息和使用量
- 剩余额度

### 时间过滤搜索

当用户需要"最新"、"最近"的内容时:
```bash
tvsearch "AI 新闻" --freshness pd --format json    # 过去一天
tvsearch "大模型进展" --freshness pw --format json  # 过去一周
tvsearch "科技动态" --freshness pm --format json    # 过去一月
tvsearch "年度回顾" --freshness py --format json    # 过去一年
```

### 新闻主题搜索

当用户明确搜索新闻时:
```bash
tvsearch "科技新闻" --topic news --freshness pd
```

### 深度搜索

当用户需要更全面的结果时:
```bash
tvsearch "详细调研" --depth advanced
```

注意: advanced 模式消耗 2 credits，basic 模式消耗 1 credit

### 阅读友好输出

当用户需要直接阅读结果时:
```bash
tvsearch "Node.js" --format markdown
tvsearch "Python" -c 5 --format table
```

## 参数说明

| 参数 | 说明 |
|------|------|
| `query` | 搜索关键词，必填 |
| `-c, --count <number>` | 结果数量，范围 1-50，默认 10 |
| `-f, --format <format>` | 输出格式: json(默认), markdown, table |
| `--freshness <value>` | 时间过滤: pd(一天), pw(一周), pm(一月), py(一年) |
| `--depth <depth>` | 搜索深度: basic(1credit), advanced(2credit) |
| `--topic <topic>` | 搜索主题: general(通用), news(新闻) |
| `--api-key <key>` | 临时使用 API Key (不保存到配置) |

## 配置命令参数

| 参数 | 说明 |
|------|------|
| `--set-api-key <key>` | 保存 API Key 到配置文件 (永久保存) |
| `--default-format <format>` | 设置默认输出格式 |
| `--default-count <number>` | 设置默认结果数量 |
| `--default-freshness <value>` | 设置默认时间范围 |
| `-s, --show` | 显示当前配置 (API Key 脱敏) |
| `-r, --reset` | 重置所有配置 |

## 配额查询命令参数

| 参数 | 说明 |
|------|------|
| `--format <format>` | 输出格式: json(默认), markdown, table |
| `--api-key <key>` | 临时使用 API Key (不保存到配置) |

## 注意事项

1. **优先用 JSON** - 需要进一步分析、提取字段、总结时，优先使用 `--format json`
2. **认证要求** - 使用前必须配置 `TAVILY_API_KEY` 环境变量或通过 `config --set-api-key` 保存
3. **API Key 格式** - Tavily API Key 以 `tvly-` 开头
4. **Credit 消耗** - basic 搜索消耗 1 credit，advanced 搜索消耗 2 credits
5. **新闻搜索** - 搜索新闻时建议配合 `--topic news` 和 `--freshness` 使用

## 退出码

| 退出码 | 含义 |
|--------|------|
| 0 | 成功 |
| 1 | 参数错误或通用运行错误 |
| 2 | 配置缺失或认证失败 |
| 3 | 接口限流或上游服务异常 |

## 快速参考

```bash
# 查看帮助
tvsearch --help
tvsearch config --help
tvsearch usage --help

# 查看版本
tvsearch --version

# 查看配置
tvsearch config --show

# 查看配额
tvsearch usage
tvsearch usage --format table

# 设置 API Key
tvsearch config --set-api-key "tvly-xxxxx"

# 基础搜索
tvsearch "人工智能" --format json

# 指定结果数量
tvsearch "TypeScript 教程" -c 5 --format json

# 时间过滤
tvsearch "最新新闻" --freshness pd --format json

# 新闻搜索
tvsearch "科技新闻" --topic news --freshness pw

# 深度搜索
tvsearch "详细调研" --depth advanced

# Markdown 输出
tvsearch "Node.js" -f markdown

# 表格输出
tvsearch "Python" --format table

# 临时使用其他 API Key
tvsearch "测试" --api-key "tvly-yyyyy"
```