Duckduckgo 搜索

通過 DuckDuckGo 進行免費網絡搜索 — 文本、新聞、圖片、視頻。無需 API 密鑰。如果已安裝，首選使用 ddgs CLI；僅在驗證當前運行時中存在 ddgs 後，才使用 Python DDGS 庫。

技能元數據


來源	可選 — 使用 `hermes skills install official/research/duckduckgo-search` 安裝
路徑	`optional-skills/research/duckduckgo-search`
版本	`1.3.0`
作者	gamedevCloudy
許可證	MIT
標籤	`search`, `duckduckgo`, `web-search`, `free`, `fallback`
相關技能	`arxiv`

參考：完整 SKILL.md

信息

以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理看到的指令。

DuckDuckGo 搜索

使用 DuckDuckGo 進行免費網絡搜索。無需 API 密鑰。

當 web_search 不可用或不適合時使用（例如未設置 FIRECRAWL_API_KEY 時）。如果特別需要 DuckDuckGo 的結果，也可以將其用作獨立的搜索路徑。

檢測流程

在選擇方法之前，檢查實際可用的資源：

# Check CLI availability
command -v ddgs >/dev/null && echo "DDGS_CLI=installed" || echo "DDGS_CLI=missing"

決策樹：

如果已安裝 ddgs CLI，首選 terminal + ddgs
如果缺少 ddgs CLI，不要假設 execute_code 可以導入 ddgs
如果用戶特別想要 DuckDuckGo，請先在相關環境中安裝 ddgs
否則回退到內置的網絡/瀏覽器工具

重要的運行時說明：

Terminal 和 execute_code 是獨立的運行時
Shell 安裝成功並不保證 execute_code 可以導入 ddgs
切勿假設 execute_code 中預安裝了第三方 Python 包

安裝

僅在特別需要 DuckDuckGo 搜索且運行時尚未提供該功能時，才安裝 ddgs。

# Python package + CLI entrypoint
pip install ddgs

# Verify CLI
ddgs --help

如果工作流依賴 Python 導入，請在使用 from ddgs import DDGS 之前，驗證同一運行時是否可以導入 ddgs。

方法 1：CLI 搜索（首選）

如果存在 ddgs 命令，則通過 terminal 使用它。這是首選路徑，因為它避免假設 execute_code 沙箱中已安裝 ddgs Python 包。

# Text search
ddgs text -q "python async programming" -m 5

# News search
ddgs news -q "artificial intelligence" -m 5

# Image search
ddgs images -q "landscape photography" -m 10

# Video search
ddgs videos -q "python tutorial" -m 5

# With region filter
ddgs text -q "best restaurants" -m 5 -r us-en

# Recent results only (d=day, w=week, m=month, y=year)
ddgs text -q "latest AI news" -m 5 -t w

# JSON output for parsing
ddgs text -q "fastapi tutorial" -m 5 -o json

CLI 標誌

標誌	描述	示例
`-q`	查詢 — 必需	`-q "search terms"`
`-m`	最大結果數	`-m 5`
`-r`	區域	`-r us-en`
`-t`	時間限制	`-t w`（周）
`-s`	安全搜索	`-s off`
`-o`	輸出格式	`-o json`

方法 2：Python API（僅在驗證後使用）

僅在驗證 ddgs 已安裝在 execute_code 或其他 Python 運行時中後，才使用其中的 DDGS 類。不要假設 execute_code 默認包含第三方包。

安全的表述方式：

“如果需要，在安裝或驗證包之後，在 execute_code 中使用 ddgs”

避免說：

“execute_code 包含 ddgs”
“DuckDuckGo 搜索在 execute_code 中默認可用”

重要： max_results 必須始終作為關鍵字參數傳遞 — 在所有方法中使用位置參數都會引發錯誤。

文本搜索

適用於：一般研究、公司、文檔。

from ddgs import DDGS

with DDGS() as ddgs:
    for r in ddgs.text("python async programming", max_results=5):
        print(r["title"])
        print(r["href"])
        print(r.get("body", "")[:200])
        print()

返回：title, href, body

新聞搜索

適用於：當前事件、突發新聞、最新更新。

from ddgs import DDGS

with DDGS() as ddgs:
    for r in ddgs.news("AI regulation 2026", max_results=5):
        print(r["date"], "-", r["title"])
        print(r.get("source", ""), "|", r["url"])
        print(r.get("body", "")[:200])
        print()

返回：date, title, body, url, image, source

圖片搜索

適用於：視覺參考、產品圖片、圖表。

from ddgs import DDGS

with DDGS() as ddgs:
    for r in ddgs.images("semiconductor chip", max_results=5):
        print(r["title"])
        print(r["image"])
        print(r.get("thumbnail", ""))
        print(r.get("source", ""))
        print()

返回：title, image, thumbnail, url, height, width, source

視頻搜索

適用於：教程、演示、解釋性視頻。

from ddgs import DDGS

with DDGS() as ddgs:
    for r in ddgs.videos("FastAPI tutorial", max_results=5):
        print(r["title"])
        print(r.get("content", ""))
        print(r.get("duration", ""))
        print(r.get("provider", ""))
        print(r.get("published", ""))
        print()

返回：title, content, description, duration, provider, published, statistics, uploader

快速參考

方法	使用時機	關鍵字段
`text()`	一般研究、公司	title, href, body
`news()`	當前事件、更新	date, title, source, body, url
`images()`	視覺內容、圖表	title, image, thumbnail, url
`videos()`	教程、演示	title, content, duration, provider

工作流：先搜索後提取

DuckDuckGo 返回標題、URL 和摘要 — 而非完整的頁面內容。要獲取完整的頁面內容，請先搜索，然後使用 web_extract、瀏覽器工具或 curl 提取最相關的 URL。

CLI 示例：

ddgs text -q "fastapi deployment guide" -m 3 -o json

Python 示例，僅在驗證該運行時中已安裝 ddgs 後使用：

from ddgs import DDGS

with DDGS() as ddgs:
    results = list(ddgs.text("fastapi deployment guide", max_results=3))
    for r in results:
        print(r["title"], "->", r["href"])

然後使用 web_extract 或其他內容檢索工具提取最佳 URL。

限制

速率限制：DuckDuckGo 可能在大量快速請求後進行限流。如有需要，請在搜索之間添加短暫延遲。
無內容提取：ddgs 返回的是摘要片段，而非完整的頁面內容。如需獲取完整文章或頁面，請使用 web_extract、瀏覽器工具或 curl。
結果質量：通常良好，但可配置性不如 Firecrawl 的搜索功能。
可用性：DuckDuckGo 可能會阻止來自某些雲 IP 的請求。如果搜索返回空結果，請嘗試不同的關鍵詞或等待幾秒鐘。
字段可變性：返回的字段可能因結果或 ddgs 版本而異。使用 .get() 訪問可選字段以避免 KeyError。
運行時隔離：在終端中成功安裝 ddgs 並不意味著 execute_code 可以自動導入它。

故障排除

問題	可能原因	解決方法
`ddgs: command not found`	Shell 環境中未安裝 CLI	安裝 `ddgs`，或改用內置的 web/瀏覽器工具
`ModuleNotFoundError: No module named 'ddgs'`	Python 運行時未安裝該包	在該運行時準備就緒之前，不要在其中使用 Python DDGS
搜索返回空結果	臨時限流或查詢不佳	等待幾秒鐘後重試，或調整查詢條件
CLI 可用但 `execute_code` 導入失敗	終端和 `execute_code` 屬於不同的運行時	繼續使用 CLI，或單獨準備 Python 運行時

常見陷阱

max_results 僅支持關鍵字參數：ddgs.text("query", 5) 會引發錯誤。請使用 ddgs.text("query", max_results=5)。
不要假設 CLI 存在：使用前請檢查 command -v ddgs。
不要假設 execute_code 可以導入 ddgs：除非單獨準備了該運行時，否則 from ddgs import DDGS 可能會因 ModuleNotFoundError 而失敗。
包名稱：包名為 ddgs（此前為 duckduckgo-search）。使用 pip install ddgs 進行安裝。
不要混淆 -q 和 -m（CLI）：-q 用於指定查詢，-m 用於指定最大結果數量。
空結果：如果 ddgs 返回空結果，可能是受到了限流。請等待幾秒鐘後重試。

驗證環境

已針對 ddgs==9.11.2 的語義驗證示例。技能指南現在將 CLI 可用性和 Python 導入可用性視為獨立的問題，以確保文檔化的工作流程與實際運行時行為一致。

技能元數據​

參考：完整 SKILL.md​

DuckDuckGo 搜索

檢測流程​

安裝​

方法 1：CLI 搜索（首選）​

CLI 標誌​

方法 2：Python API（僅在驗證後使用）​

文本搜索​

新聞搜索​

圖片搜索​

視頻搜索​

快速參考​

工作流：先搜索後提取​

限制​

故障排除​

常見陷阱​

驗證環境​