介绍
# Web Search
使用 DuckDuckGo 的即时回答 API 进行免费网络搜索。无需 API 密钥。
## 快速开始
```bash # Basic search cd /home/hxx/clawd/tools && ./web-search.sh "your query"
# Examples ./web-search.sh "what is artificial intelligence" ./web-search.sh "python programming" ./web-search.sh "define recursion" ./web-search.sh "2+2" ```
## 命令行选项
### 核心选项 - `-h, --help` - 显示包含使用示例的帮助信息 - `--format <format>` - 输出格式：`text`、`markdown`、`plain`（默认：`text`） - `text`：彩色终端输出（默认） - `markdown`：整洁的 Markdown 格式（无 ANSI 颜色） - `plain`：无颜色的纯文本 - `--no-color` - 禁用彩色输出（等同于 `--format plain`） - `--max-related <N>` - 控制显示的相关主题数量（默认：5） - `--quiet` - 最小输出模式（仅显示结果，无页眉/页脚）
### 输出到文件 使用 Shell 重定向将结果保存到文件：
```bash # Save to file ./web-search.sh "query" > output.txt
# With markdown format ./web-search.sh --format markdown "query" > results.md
# With no colors for logs ./web-search.sh --no-color "query" > search.log ```
## 返回内容
该工具提供几种结果类型：
- **答案** - 针对计算、换算、天气等的直接回答 - **摘要** - 包含来源和 URL 的百科全书式摘要 - **定义** - 单词/术语定义 - **相关主题** - 其他相关结果（可配置，默认 5 个）
## 最佳实践
1. **具体明确** - 更具体的查询能获得更好的即时回答 2. **尝试变体** - 如果没有结果，请重新表述您的查询 3. **用于事实查询** - 定义、计算、快速查询效果最佳 4. **检查 URL** - 始终提供 DuckDuckGo 链接以进行完整搜索 5. **使用适当的格式**： - 终端输出：`--format text`（彩色，默认） - 文档：`--format markdown` > file.md` - 日志/管道：`--format plain` 或 `--no-color`
## 局限性
- 无完整网络搜索结果（仅限即时回答） - 某些查询返回的结果有限，取决于 DuckDuckGo 的数据 - 某些摘要中存在字符编码问题（已知局限性） - 需要互联网连接才能查询 DuckDuckGo API - 并非所有查询类型都返回即时回答（例如 `sqrt(144)` 等复杂数学运算） - 并非所有术语都能获取到定义 - 近期新闻可能不会出现（DuckDuckGo 侧重于常青内容）
## 使用示例
### 基础搜索 ```bash # Simple query ./web-search.sh "open source AI models"
# Wikipedia-style query ./web-search.sh "what is recursion" ```
### Markdown 格式 ```bash # Clean markdown output ./web-search.sh --format markdown "python programming"
# Save to markdown file ./web-search.sh --format markdown "AI research" > research.md ```
### 纯文本/无颜色 ```bash # For logs or piping ./web-search.sh --format plain "search query"
# Disable colors explicitly ./web-search.sh --no-color "search query" ```
### 控制相关主题 ```bash # Show fewer related topics ./web-search.sh --max-related 3 "machine learning"
# Show more related topics ./web-search.sh --max-related 10 "open source" ```
### 安静模式 ```bash # Minimal output (just results) ./web-search.sh --quiet "what is 42 + 7" ```
### 组合选项 ```bash # Markdown, no color, saved to file ./web-search.sh --format markdown --no-color "topic" > results.md
# Quiet with custom related count ./web-search.sh --quiet --max-related 2 "definition" ```
## 已测试场景
已测试并验证可用的场景： - ✅ 计算：`2+2`、`500 的 10%` - ✅ 换算：`100 miles to km` - ✅ 百科查询：`what is artificial intelligence` - ✅ 编程：`what is python`、`how to install docker` - ✅ 人物：`who is Elon Musk` - ✅ 科学事实：`speed of light` - ✅ 天气：`weather in Tokyo` - ✅ 边缘情况：空查询、特殊字符、无结果 - ✅ 输出格式：text、markdown、plain - ✅ 标志：--help、--format、--no-color、--max-related、--quiet
详细的测试结果请参阅 [test-outputs.md](test-outputs.md)。
## 故障排除
### "未找到直接结果" 尝试重新表述您的查询，或使用提供的 DuckDuckGo URL 进行完整搜索。
### 网络错误 检查互联网连接。该工具需要网络访问权限。
### 字符编码问题 某些摘要显示乱码。这是基本解析的一个已知问题（安装 `jq` 以获得更好的结果）。
### "未找到 jq" 警告 该工具可以使用基本文本提取在没有 `jq` 的情况下工作，但安装 `jq` 可以改进 JSON 解析： ```bash # Ubuntu/Debian sudo apt-get install jq
# macOS brew install jq
# Via package managers npm install -g jq ```
## 输出格式
### 文本格式（默认） - **蓝色** - 标题和搜索信息 - **绿色** - 结果标记和内容 - **黄色** - 来源、URL 和警告 - **红色** - 错误
使用 `--format plain` 或 `--no-color` 禁用颜色。
### Markdown 格式 整洁的 Markdown 格式，包含： - `##` 用于章节标题 - `**粗体**` 用于强调 - `-` 项目符号列表 - `*斜体*` 用于元数据 - `[链接]()` 用于 URL
### 纯文本格式 无 ANSI 代码或 Markdown 格式 - 适用于日志和管道传输。
## 系统要求
- `curl` 或 `wget`（用于 HTTP 请求） - 可选：`jq`（用于更好的 JSON 解析）