ddg-search

核心用法

ddg-search 是一款命令行 DuckDuckGo 搜索抓取工具，无需 API 密钥即可获取搜索结果。支持 JSON、JSONL、CSV、Markdown、OpenSearch XML 及专为 LLM 设计的 compact 格式。

典型用法：

• ddg-search "query" — 默认 JSON 输出，抓取 5 页
• ddg-search -f compact "query" — 最小 token 输出，直接喂给 LLM
• ddg-search -p 0 "query" — 无限制翻页，抓取全部结果
• ddg-search -t w -r us-en "topic" — 限定近一周、美国英语区结果

管道友好设计： stdout 输出结果，stderr 显示进度，天然适配 Unix 管道（如 | jq -r '.items[].link' 提取链接）。

显著优点

1. 零配置即开即用：无需注册、无 API 配额限制
2. 多格式输出：尤其 compact 格式专为 LLM 上下文优化，显著降低 token 消耗
3. 隐私导向：基于 DuckDuckGo，不追踪用户
4. 灵活筛选：支持时间范围（日/周/月/年）、区域、结果数量控制
5. Node.js 生态：npm 一键安装，跨平台可用

潜在局限与风险

架构性限制：

• 网页抓取依赖：非官方 API，HTML 结构变更即可能失效
• 反爬机制：DuckDuckGo 可能触发 bot 检测，导致结果不完整；工具仅返回已抓取部分，无重试或代理支持
• 速率限制：虽有 800–2900ms 随机延迟，但大规模抓取仍可能被封禁

稳定性风险：

• 输出字段随 DuckDuckGo 页面结构调整而变化
• compact 格式无结构化保证，下游解析脆弱
• 无内置缓存机制，重复查询效率低

合规考量：

• 需遵守 DuckDuckGo 服务条款及 robots.txt
• 商业场景大规模使用存在法律灰色地带

适合人群

• 需要快速原型或本地脚本集成搜索的开发者
• 构建隐私优先 LLM 工作流的技术用户
• 无法/不愿申请 Google/Bing API 密钥的个人项目
• 数据量小、频次低、对稳定性要求不苛刻的自动化场景

常规风险

| 类别 | 等级 | 说明 |

|------|------|------|

| 服务可用性 | 中高 | 依赖未授权抓取，随时可能失效 |

| 数据完整性 | 中 | 反爬触发时结果截断，无警告机制 |

| 合规风险 | 中 | 需自行评估 TOU 合规性 |

| 供应链安全 | 低 | npm 包来源明确，Node.js 生态相对成熟 |

核心用法

ddg-search 是一款面向命令行的 DuckDuckGo 搜索爬取工具，专为需要将搜索结果集成到自动化工作流或 LLM 上下文中的用户设计。用户通过简单命令即可发起搜索，支持 JSON、JSONL、CSV、Markdown、OpenSearch 等多种输出格式，并可通过 -p（页数）、-n（结果数）、-r（区域）、-t（时间过滤）等参数精确控制搜索范围。

典型使用场景包括：开发者为 CI/CD 流水线添加实时信息检索能力、研究人员批量收集学术资料链接、内容创作者快速生成引用清单，以及 AI Agent 通过 compact 格式获取极简上下文填充。工具默认自动插入 800-2900ms 随机延迟以避免触发反爬机制，进度信息输出至 stderr，便于脚本化处理。

显著优点

隐私优先：依托 DuckDuckGo 不追踪用户的核心优势，无需注册 API 密钥即可使用，杜绝搜索行为画像与数据泄露风险。

格式灵活：六种输出格式覆盖全场景需求——compact 专为 LLM 上下文优化极简 token；jsonl 适配流式处理；json 包含 OpenSearch 元数据与零点击答案；csv 直通表格分析；markdown 便于文档嵌入；opensearch 生成标准 Atom feeds。

零配置即用：通过 npm 一键全局安装，无需复杂认证流程，开箱即用的体验大幅降低技术门槛。

智能节流：内置随机延迟与自动停止机制，在被识别为机器人前优雅退出并返回已收集结果，兼顾成功率与合规性。

潜在缺点与局限性

结果完整性风险：DuckDuckGo 的 bot 检测机制可能导致搜索提前中断，无法保证获取全部预期结果，不适合对数据完整性要求极高的学术研究或商业情报采集。

功能边界受限：相比官方 API，爬取模式无法访问高级搜索参数（如站点限定、文件类型过滤），且受限于 HTML 解析的稳定性，页面结构变更可能导致工具失效。

速率与规模瓶颈：随机延迟机制虽合规但显著降低大规模数据采集效率，单 IP 长时间高频使用仍有封禁风险。

维护依赖不确定性：作为个人开发者维护的社区项目，长期更新响应速度与功能迭代承诺弱于企业级产品。

适合的目标群体

• 开发者与 DevOps 工程师：需要在脚本、自动化测试或监控系统中嵌入轻量级搜索能力
• AI Agent 构建者：为 LLM 应用提供实时网络信息增强（RAG 场景中的检索端）
• 学术与媒体研究者：快速获取文献链接、新闻来源清单，对单页结果完整性容忍度较高
• 隐私敏感型用户：拒绝 Google/Bing 账户体系，偏好匿名搜索的数据分析师

使用风险

供应链风险：核心功能依赖 npm 包 ddg-search，存在包被篡改或作者账号被盗的潜在威胁，建议锁定具体版本并在隔离环境运行。

网络与合规风险：爬取行为可能违反 DuckDuckGo 服务条款（虽未明确禁止），过度使用导致 IP 临时封禁；企业环境需确认是否符合内部网络安全策略。

性能波动：受目标网站响应与反爬策略影响，执行时间与结果数量高度不可预测，不适合实时性要求强的生产链路。

许可证缺失：当前未明确声明开源许可证，商业使用存在法律不确定性，建议联系作者确认或选择替代方案。