lyhue1991 tvsearch
封装 tvsearch 命令行工具，用于通过 Tavily API 进行网页搜索。
核心能力
- 网页搜索 - 查询公开网页与资讯内容，返回结构化结果
- 时间过滤 - 支持最近一天、一周、一月、一年的结果过滤
- 搜索深度 - 支持 basic (1 credit) 和 advanced (2 credit) 两种深度
- 主题分类 - 支持 general (通用) 和 news (新闻) 两种主题
- 多格式输出 - 支持 JSON、Markdown、表格格式
- 配置管理 - 支持 API Key 配置与默认参数管理
- 配额查询 - 查看 Tavily API 配额使用情况
工作流程
搜索执行
当用户表达搜索、查资料、查新闻、做调研意图时，执行搜索命令:
tvsearch "关键词" --format json --count 10
常用搜索模式:
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
command -v tvsearch
如果未安装，执行:
npm install -g @lyhue1991/tvsearch
或直接使用 npx:
npx @lyhue1991/tvsearch "关键词"
Step 2: 检查认证配置
检查本地配置:
tvsearch config --show
如果未配置，检查环境变量:
printenv TAVILY_API_KEY
如果仍然未配置，需要用户提供 Tavily API Key，然后执行:
tvsearch config --set-api-key "tvly-xxxxx"
获取 API Key: https://tavily.com
配置管理
设置 API Key 和默认参数:
tvsearch config --set-api-key "tvly-xxxxx"
tvsearch config --default-format json --default-count 10
查看当前配置:
tvsearch config --show
重置配置:
tvsearch config --reset
配额查询
查看 Tavily API 配额使用情况:
tvsearch usage # JSON 格式
tvsearch usage --format table # 表格格式
tvsearch usage --format markdown # Markdown 格式
配额信息包括：
- API Key 级别使用量（search/crawl/extract/map/research）
- 账户套餐信息和使用量
- 剩余额度
时间过滤搜索
当用户需要"最新"、"最近"的内容时:
tvsearch "AI 新闻" --freshness pd --format json # 过去一天
tvsearch "大模型进展" --freshness pw --format json # 过去一周
tvsearch "科技动态" --freshness pm --format json # 过去一月
tvsearch "年度回顾" --freshness py --format json # 过去一年
新闻主题搜索
当用户明确搜索新闻时:
tvsearch "科技新闻" --topic news --freshness pd
深度搜索
当用户需要更全面的结果时:
tvsearch "详细调研" --depth advanced
注意: advanced 模式消耗 2 credits，basic 模式消耗 1 credit
阅读友好输出
当用户需要直接阅读结果时:
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 (不保存到配置) |
注意事项
- 优先用 JSON - 需要进一步分析、提取字段、总结时，优先使用
--format json - 认证要求 - 使用前必须配置
TAVILY_API_KEY环境变量或通过config --set-api-key保存 - API Key 格式 - Tavily API Key 以
tvly-开头 - Credit 消耗 - basic 搜索消耗 1 credit，advanced 搜索消耗 2 credits
- 新闻搜索 - 搜索新闻时建议配合
--topic news和--freshness使用
退出码
| 退出码 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 参数错误或通用运行错误 |
| 2 | 配置缺失或认证失败 |
| 3 | 接口限流或上游服务异常 |
快速参考
# 查看帮助
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"