npm package: @lyhue1991/tvsearch
Description: Tavily Search API 命令行工具
Latest version: 0.1.1

# tvsearch

这是一个提供 Tavily 网页搜索能力的 SKILL，基于 NodeJS。

## 安装此 SKILL

```bash
npx skills add lyhue1991/tvsearch
```

## 获取 Tavily API Key

访问 https://tavily.com 注册账号并创建 API Key。

注：免费套餐每月 1000 次搜索额度。

---

## 作为 CLI 工具使用

### 安装

```bash
npm install -g @lyhue1991/tvsearch
```

## 快速开始

### 1. 配置 API Key

首先需要获取 Tavily API Key，访问 [https://tavily.com](https://tavily.com) 注册账号并创建 API Key。

然后通过以下方式之一配置：

**方式一：环境变量**
```bash
export TAVILY_API_KEY="tvly-your-api-key"
```

**方式二：命令行配置**
```bash
tvsearch config --set-api-key "tvly-your-api-key"
```

### 2. 执行搜索

```bash
# 基础搜索
tvsearch "人工智能"

# 指定结果数量
tvsearch "TypeScript 教程" --count 5

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

# Markdown 格式输出
tvsearch "Node.js" --format markdown
```

## 使用说明

### 搜索命令

```bash
tvsearch <关键词> [选项]
```

| 选项 | 简写 | 说明 |
|------|------|------|
| `--count <number>` | `-c` | 返回结果数量 (1-50)，默认 10 |
| `--format <format>` | `-f` | 输出格式 (json/markdown/table)，默认 json |
| `--freshness <value>` | | 时间过滤 |
| `--depth <depth>` | | 搜索深度 (basic/advanced)，默认 basic |
| `--topic <topic>` | | 搜索主题 (general/news)，默认 general |
| `--api-key <key>` | | 临时使用指定 API Key |

#### 时间过滤参数

| 值 | 说明 |
|----|------|
| `pd` | 过去一天 |
| `pw` | 过去一周 |
| `pm` | 过去一月 |
| `py` | 过去一年 |
| `YYYY-MM-DDtoYYYY-MM-DD` | 自定义日期范围 |

### 配置命令

```bash
tvsearch config [选项]
```

| 选项 | 简写 | 说明 |
|------|------|------|
| `--set-api-key <key>` | | 保存 API Key |
| `--default-format <format>` | | 设置默认输出格式 |
| `--default-count <number>` | | 设置默认结果数量 |
| `--default-freshness <value>` | | 设置默认时间范围 |
| `--show` | `-s` | 显示当前配置 |
| `--reset` | `-r` | 重置所有配置 |

### 配额查询命令

```bash
tvsearch usage [选项]
```

| 选项 | 说明 |
|------|------|
| `--format <format>` | 输出格式 (json/markdown/table)，默认 json |
| `--api-key <key>` | 临时使用指定 API Key |

查询 Tavily API 配额使用情况：

```bash
# 查看配额（JSON 格式）
tvsearch usage

# Markdown 格式
tvsearch usage --format markdown

# 表格格式
tvsearch usage --format table
```

### 示例

```bash
# 搜索最近一周的 AI 新闻
tvsearch "AI 新闻" --freshness pw --topic news --format markdown

# 高级搜索（更多结果）
tvsearch "深度学习" --depth advanced --count 20

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

# 查看当前配置
tvsearch config --show

# 设置默认值
tvsearch config --default-format markdown --default-count 15
```

## 输出格式

### JSON 格式（默认）

```json
[
  {
    "title": "结果标题",
    "url": "https://example.com",
    "content": "内容摘要...",
    "score": 0.95
  }
]
```

### Markdown 格式

```markdown
## 1. 结果标题
[https://example.com](https://example.com)

内容摘要...

**相关度**: 0.95

---
```

### Table 格式

```
┌────┬──────────────────┬──────────────────────────────────┬──────────┐
│ #  │ 标题             │ 来源                              │ 相关度   │
├────┼──────────────────┼──────────────────────────────────┼──────────┤
│ 1  │ 结果标题         │ https://example.com              │ 0.95     │
└────┴──────────────────┴──────────────────────────────────┴──────────┘
```

## 配置优先级

1. 命令行参数 `--api-key`
2. 环境变量 `TAVILY_API_KEY`
3. 配置文件中的 `apiKey`
4. 配置文件中的默认值
5. 内建默认值

## 注意事项

- **API 额度**: Tavily 免费套餐每月 1000 次搜索
- **API Key 格式**: 以 `tvly-` 开头
- **搜索深度**: `advanced` 消耗 2 credits，`basic` 消耗 1 credit

## 开发

```bash
# 安装依赖
npm install

# 编译
npm run build

# 测试
npm test

# 本地运行
node dist/index.js "test"
```

## License

MIT