//! fetch_search AI 工具声明式注册(搜索引擎查询,DuckDuckGo HTML 免 key)。
//!
//! 工具职责:GET DuckDuckGo HTML 端点 → 解析结果列表(标题+URL+摘要)→ 截断 max_results
//! → 返回 {query, results, count}。补「fetch_url 只抓已知 URL,无搜索能力」缺口:
//! 用户给"调研 X"时,LLM 需先搜索找文档入口,再 fetch_url 深读。
//!
//! 风险:Low(只读 GET 搜索,无副作用,与 fetch_url 同级)。SSRF 防护复用 commands/ai/http.rs
//! (validate_url / resolve_and_check_host / build_client / execute_with_redirects)。
//! DDG HTML 免 API key(html.duckduckgo.com/html/),返回结果列表 HTML,handler 解析提取。
//!
//! handler 在 commands/ai/fetch_search.rs::execute_fetch_search,声明式注册收敛样板。
//! 无 db 捕获,纯网络 GET + HTML 字符串扫描解析(对齐 fetch_url::extract_title 风格,
//! 不引 scraper 重依赖 — html5ever+selectors+cssparser 编译产物大,DDG 单一来源不值)。

use std::sync::Arc;

use df_ai::ai_tools::{AiToolRegistry, RiskLevel};
use df_ai::declare_tool;

/// 注册 fetch_search 工具到 `$registry`(无 db 捕获,纯网络 GET + HTML 解析)。
///
/// - name/desc/schema 面向 LLM 的工具说明
/// - risk=Low(只读 GET 搜索,无副作用,与 fetch_url 同级)
/// - handler 转调 fetch_search.rs::execute_fetch_search(SSRF 防护 + DDG GET + HTML 解析全在那)
pub fn register(registry: &mut AiToolRegistry) {
    // 无捕获:占位 Arc<()>(handler 不持 db,仅转调 fetch_search.rs)。
    let dummy: Arc<()> = Arc::new(());
    // schema:query(必填)+ max_results(可选,默认 5,clamp [1,10])。
    let schema = {
        let mut props = serde_json::Map::new();
        props.insert("query".into(), serde_json::json!({ "type": "string", "description": "搜索关键词(必填)。返回 DuckDuckGo HTML 结果列表(标题+URL+摘要),供挑选入口用 fetch_url 深读" }));
        props.insert("max_results".into(), serde_json::json!({ "type": "integer", "description": "返回结果数(默认 5,clamp [1, 10])", "minimum": 1, "maximum": 10, "default": 5 }));
        serde_json::json!({
            "type": "object",
            "properties": props,
            "required": ["query"],
        })
    };
    declare_tool!(
        registry,
        dummy: Arc<()>,
        "fetch_search",
        "搜索引擎查询(免 API key),返回 DuckDuckGo 结果列表(标题+URL+摘要)。补「fetch_url 只抓已知 URL」缺口:用户给「调研 X」时,先用本工具找文档入口,再 fetch_url 深读。参数:query(必填,搜索关键词)、max_results(默认 5,clamp [1,10])。安全:只读 GET,SSRF 防护复用 fetch_url/http_request 同套(仅 http/https + 拒私网 + 重定向≤3 跳)。返回 {query, results:[{title,url,snippet}], count, status, elapsed_ms}。每条 url 已解包 DDG 重定向跳板(uddg 参数 percent-decode),可直接 fetch_url",
        RiskLevel::Low,
        schema: schema,
        args => {
            // 转调 fetch_search.rs handler(SSRF 防护 + DDG GET + HTML 解析 + 截断全在那)
            crate::commands::ai::fetch_search::execute_fetch_search(args).await
        }
    );
}
