{"id":"e3897a63-d43b-4666-b10c-b3bbecf1e336","entityType":"agent","slug":"clawhub-valenovo-baidu-api-search","name":"Baidu API Search","canonicalUrl":"https://www.xpersona.co/agent/clawhub-valenovo-baidu-api-search","canonicalPath":"/agent/clawhub-valenovo-baidu-api-search","generatedAt":"2026-10-14T15:16:29.759Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-12T01:32:13.438Z","emptyReason":null},"description":"面向 Agent 的中文网页来源检索包 Skill: Baidu API Search Owner: valenovo Summary: 面向 Agent 的中文网页来源检索包 Tags: latest:1.0.3 Version history: v1.0.3 | 2026-05-16T16:02:31.386Z | user Localize the ClawHub-facing skill description, README, and agent prompt to Chinese while keeping a separate English README. v1.0.2 | 2026-05-16T15:53:24.563Z | user Add bilingual Chinese and English documentation inside the published skill package. v1.0.1 | 2026-05-16T15:48","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 961 downloads reported by the source. Last updated 10/12/2026.","installCommand":"clawhub skill install s179p61n385sw9fkrysksnqb8d86tm0e:baidu-api-search","sourceUrl":"https://clawhub.ai/valenovo/baidu-api-search","homepage":"https://clawhub.ai/valenovo/skills/baidu-api-search","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/valenovo/baidu-api-search","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/valenovo/skills/baidu-api-search","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"面向 Agent 的中文网页来源检索包 Skill: Baidu API Search Owner: valenovo Summary: 面向 Agent 的中文网页来源检索包 Tags: latest:1.0.3 Version history: v1.0.3 | 2026-05-16T16:02:31.386Z |"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-12T01:32:13.438Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T01:32:13.438Z","emptyReason":null},"stars":null,"forks":null,"downloads":961,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.0.3","tractionLabel":"961 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T01:32:13.424Z","emptyReason":null},"lastUpdatedAt":"2026-10-12T01:32:13.438Z","lastCrawledAt":"2026-10-12T01:32:13.424Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-13T01:32:13.424Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.3","createdAt":"2026-05-16T16:02:31.386Z","changelog":"Localize the ClawHub-facing skill description, README, and agent prompt to Chinese while keeping a separate English README.","fileCount":21,"zipByteSize":42274},{"version":"1.0.2","createdAt":"2026-05-16T15:53:24.563Z","changelog":"Add bilingual Chinese and English documentation inside the published skill package.","fileCount":19,"zipByteSize":39939},{"version":"1.0.1","createdAt":"2026-05-16T15:48:08.320Z","changelog":"Rename to Baidu API Search and align ClawHub slug with API-based positioning.","fileCount":18,"zipByteSize":38167},{"version":"1.0.0","createdAt":"2026-05-16T15:45:09.855Z","changelog":"Initial release","fileCount":18,"zipByteSize":38163}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s179p61n385sw9fkrysksnqb8d86tm0e:baidu-api-search","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-valenovo-baidu-api-search/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-valenovo-baidu-api-search/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-valenovo-baidu-api-search/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-valenovo-baidu-api-search/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-valenovo-baidu-api-search/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-valenovo-baidu-api-search/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-14T15:16:29.756Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-valenovo-baidu-api-search/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-valenovo-baidu-api-search/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-valenovo-baidu-api-search/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-valenovo-baidu-api-search/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-12T01:32:13.438Z","emptyReason":null},"readme":"Skill: Baidu API Search\n\nOwner: valenovo\n\nSummary: 面向 Agent 的中文网页来源检索包\n\nTags: latest:1.0.3\n\nVersion history:\n\nv1.0.3 | 2026-05-16T16:02:31.386Z | user\n\nLocalize the ClawHub-facing skill description, README, and agent prompt to Chinese while keeping a separate English README.\n\nv1.0.2 | 2026-05-16T15:53:24.563Z | user\n\nAdd bilingual Chinese and English documentation inside the published skill package.\n\nv1.0.1 | 2026-05-16T15:48:08.320Z | user\n\nRename to Baidu API Search and align ClawHub slug with API-based positioning.\n\nv1.0.0 | 2026-05-16T15:45:09.855Z | user\n\nInitial release\n\nArchive index:\n\nArchive v1.0.3: 21 files, 42274 bytes\n\nFiles: agents/openai.yaml (444b), README.en.md (1827b), README.md (1969b), references/baidu-api.md (2862b), references/baike-api.md (2648b), references/dedupe-policy.md (1277b), references/operations.md (3007b), references/output-schema.md (4080b), references/query-planning.md (2212b), references/search-strategy.md (2278b), scripts/adaptive_search.py (16353b), scripts/baidu_web_search.py (8941b), scripts/build_research_pack.py (8704b), scripts/dedupe_results.py (8469b), scripts/lookup.py (17380b), scripts/plan_queries.py (11617b), scripts/run_search_plan.py (5338b), scripts/search.py (1144b), skill-card.md (2698b), SKILL.md (7069b), _meta.json (135b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: baidu-api-search\ndescription: 面向 Agent 的百度 API 搜索 Skill。用于中文“查一下/搜索/联网查/最近/最新/热点”等场景，调用百度百科和百度 AI Search API，保留原始结果、去重并生成 research pack。\nversion: 1.0.3\nhomepage: https://github.com/valenovo/baidu-search-skill\nmetadata: {\"openclaw\":{\"requires\":{\"env\":[\"BAIDU_AI_SEARCH_API_KEYS\"],\"anyBins\":[\"python3\",\"python\"]},\"primaryEnv\":\"BAIDU_AI_SEARCH_API_KEYS\",\"envVars\":[{\"name\":\"BAIDU_AI_SEARCH_API_KEYS\",\"required\":true,\"description\":\"百度 AI Search / AppBuilder API Key 列表，多个 Key 用英文逗号分隔，用于失败切换和额度隔离。\"}],\"homepage\":\"https://github.com/valenovo/baidu-search-skill\"}}\n---\n\n# Baidu API Search\n\n把百度百科查询和百度 AI Search API 整理成适合 Agent 使用的中文资料检索流程。遇到中文“查一下 / 搜索 / 联网查 / 最近 / 最新 / 热点”这类请求时，优先使用本 Skill，而不是通用 `web_search`。目标是保留原始来源给 AI 分析，不是用生成式摘要替代证据。\n\n## 工作流程\n\n1. 先选择模式：`lookup`、`fast`、`normal` 或 `deep`。\n2. 默认使用统一入口 `{baseDir}/scripts/search.py`；它会把 `lookup` 路由到百度百科，把网页搜索模式路由到自适应搜索。\n3. 真实搜索必须读取 `BAIDU_AI_SEARCH_API_KEYS`，不要把 Key 写死在文件里。\n4. 简单实体问题，例如“这是什么”“这个人是谁”，优先使用 `lookup`，能用百科解决就不额外搜索网页。\n5. `fast` 用于快速找一批来源，`normal` 用于普通问答，`deep` 只在用户明确要求全面覆盖或首轮覆盖不足时使用。\n6. 只在需要查看或手动调整搜索词时使用 `scripts/plan_queries.py`。\n7. 只有用户明确要求完整跑完所有计划查询时，才使用 `scripts/run_search_plan.py`。\n8. 需要刷新结果包时，使用 `scripts/dedupe_results.py` 和 `scripts/build_research_pack.py`。\n9. 汇报时说明查询次数、原始结果数、去重后来源数、主要域名、覆盖缺口和下一步建议。\n10. 回答事实性结论时，引用 `research_pack.md` 里的 `source_id` 加 URL 或域名；百科查询引用 `lookup_pack.md` 里的词条 URL 或 ID。\n\n## 模式\n\n- `lookup`：调用百度百科候选词和内容接口，通常 1-2 次 API 调用，适合实体定义和消歧。\n- `fast`：只跑 1 个搜索词，`top_k=10`，默认使用百度 `lite` 搜索版本，适合快速发现来源。\n- `normal`：默认模式，先跑 3 个搜索词，最多规划 12 个多角度搜索词，`top_k=20`。\n- `deep`：深度模式，先跑 5 个搜索词，`top_k=30`，必要时基于已有结果继续扩展搜索词。\n\n不要默认直接使用 `deep`。只有用户要求深度覆盖，或首轮结果明显缺少关键角度时，再提高搜索预算。\n\n## 命令\n\n生成搜索词计划：\n\n```bash\npython \"{baseDir}/scripts/plan_queries.py\" --topic \"新能源汽车 口碑\" --mode normal --output runs/ev-reputation/query_plan.json\n```\n\n只检查百度 API 请求体，不真正调用接口：\n\n```bash\npython \"{baseDir}/scripts/baidu_web_search.py\" --query \"新能源汽车 口碑\" --top-k 50 --dry-run\n```\n\n运行轻量百科查询：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"量子计算\" --mode lookup\n```\n\n先查百科，百科没有候选词时只回退到一次轻量网页搜索：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"某个新产品名称\" --mode lookup --fallback-search\n```\n\n设置 `BAIDU_AI_SEARCH_API_KEYS` 后运行自适应搜索：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal\n```\n\n用户要求最近或最新信息时，限制网页结果时间范围：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal --freshness year --no-cache\n```\n\n用户要求最新或当前信息时，强制绕过缓存：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal --no-cache\n```\n\n只有用户要求广覆盖或压力测试时，才固定预算跑完整深度搜索：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode deep --fixed --top-k 50\n```\n\n只有明确需要时，才跑完计划里的每个搜索词：\n\n```bash\npython \"{baseDir}/scripts/run_search_plan.py\" --plan runs/ev-reputation/query_plan.json --out-dir runs/ev-reputation --top-k 50\n```\n\n去重：\n\n```bash\npython \"{baseDir}/scripts/dedupe_results.py\" --input runs/ev-reputation/raw_results.jsonl --output runs/ev-reputation/deduped_sources.json\n```\n\n生成 research pack：\n\n```bash\npython \"{baseDir}/scripts/build_research_pack.py\" --run-dir runs/ev-reputation --output runs/ev-reputation/research_pack.md\n```\n\n## 参考资料\n\n- 修改请求或鉴权逻辑前，先读 `references/baidu-api.md`。\n- 修改百科查询逻辑前，先读 `references/baike-api.md`。\n- 修改搜索词扩展逻辑前，先读 `references/query-planning.md`。\n- 修改去重逻辑前，先读 `references/dedupe-policy.md`。\n- 修改输出文件结构前，先读 `references/output-schema.md`。\n- 修改 Key 池、限速或运行目录逻辑前，先读 `references/operations.md`。\n- 修改自适应停止条件前，先读 `references/search-strategy.md`。\n\n## 规则\n\n- 不要把 API Key 写入文件、Git、日志或回复。\n- 不要打印或 echo Key 环境变量。检查是否配置时，只做布尔检查，例如 `python -c \"import os; raise SystemExit(0 if os.getenv('BAIDU_AI_SEARCH_API_KEYS') else 1)\"`，也可以直接运行 `scripts/search.py` 让它报告缺少配置。\n- 多个 Key 只用于可靠性和额度隔离，不用于把同一个关键词当分页刷完。\n- 使用查询缓存避免重复调用；用户要求最新或当前信息时，用 `--no-cache` 绕过缓存。\n- 去重时不要丢弃原始结果，必须保留重复映射。\n- 搜索词扩展优先使用固定模板和结果驱动扩展，不要完全依赖无限制的 AI 猜词。\n- 实质性事实结论必须引用来源：使用 `research_pack.md` 里的 source ID、URL 或域名。\n- 搜索计划要覆盖多角度：`normal` 模式下也应尽早包含官方来源和平台特定查询。\n- 搜索预算分阶段使用：先跑种子查询，再跑覆盖查询，最后做结果驱动扩展。\n- 当必要意图已经覆盖，且新增查询的唯一来源产出很低时停止，除非用户明确要求穷尽搜索。\n- 默认不要使用百度视频搜索、图片搜索、秒懂百科视频、阿拉丁或智能搜索生成。本 Skill 是来源检索工具，不是生成答案包装器。\n\n## Agent 接入\n\n给其他 Agent 使用时，最稳的默认命令是：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"<topic>\" --mode normal\n```\n\n简单实体定义使用：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"<topic>\" --mode lookup\n```\n\n先读 `run_summary.json`。百科查询读 `lookup_pack.md`；网页搜索读 `research_pack.md` 里的覆盖判断，需要核查原始证据时再读 `raw_results.jsonl`。\n\nFile v1.0.3:README.md\n\n# Baidu API Search\n\n简体中文 | [English](README.en.md)\n\n面向 Agent 的百度 API 搜索 Skill。它调用百度 AI Search API 和百度百科 API，把中文搜索结果整理成可复查、可引用的 research pack，适合需要中文网页来源的 AI Agent 使用。\n\n这个 Skill 不是爬虫，也不是答案生成接口。它只负责检索、去重、保留原始结果，并把来源整理给 Agent 后续分析。\n\n## 功能\n\n- 百度 AI Search `web_search`\n- 百度百科轻量实体查询\n- `lookup`、`fast`、`normal`、`deep` 四种模式\n- 自动规划搜索词并根据覆盖情况提前停止\n- URL 去重和近似重复合并\n- 输出 `research_pack.md`、`raw_results.jsonl`、`run_summary.json`\n- 支持本地缓存和多个 API Key 失败切换\n\n## 环境要求\n\n- Python 3.10+\n- 百度 AI Search / AppBuilder API Key\n- 能读取 `SKILL.md` 并运行本地 Python 脚本的 Agent 环境\n\n脚本只使用 Python 标准库，不需要额外安装依赖。\n\nAPI Key 请放在环境变量里：\n\n```bash\nexport BAIDU_AI_SEARCH_API_KEYS=\"your-key\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:BAIDU_AI_SEARCH_API_KEYS = \"your-key\"\n```\n\n多个 Key 用英文逗号分隔：\n\n```bash\nexport BAIDU_AI_SEARCH_API_KEYS=\"key1,key2,key3\"\n```\n\n不要把真实 Key 写进配置文件、README、Prompt、日志或 Git 提交里。\n\n## 快速使用\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal\n```\n\n简单实体查询：\n\n```bash\npython scripts/search.py \"量子计算\" --mode lookup\n```\n\n查询最近或当前信息：\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal --freshness year --no-cache\n```\n\n## 给 Agent 的推荐指令\n\n```text\n中文网页搜索、百度百科查询、最近/最新/热点类中文问题，以及用户说“查一下”“搜索”“联网查”时，优先使用 baidu-api-search skill。回答事实性结论时引用 research_pack.md 里的 source_id 或 URL。\n```\n\nFile v1.0.3:_meta.json\n\n{\n  \"ownerId\": \"kn702h51bcntppmj04vwcpqzn982ptk8\",\n  \"slug\": \"baidu-api-search\",\n  \"version\": \"1.0.3\",\n  \"publishedAt\": 1778947351386\n}\n\nFile v1.0.3:references/baidu-api.md\n\n# Baidu AI Search API Notes\n\nUse this reference before changing request/auth behavior.\n\n## Endpoint\n\n```text\nPOST https://qianfan.baidubce.com/v2/ai_search/web_search\n```\n\nThis skill targets the web search endpoint because it returns raw-ish `references` suitable for downstream AI analysis. Do not replace it with generated answer endpoints when the user asks for original information.\n\n## Request Shape\n\nThe current script builds this payload:\n\n```json\n{\n  \"messages\": [{\"role\": \"user\", \"content\": \"新能源汽车 口碑\"}],\n  \"search_source\": \"baidu_search_v2\",\n  \"resource_type_filter\": [{\"type\": \"web\", \"top_k\": 50}]\n}\n```\n\nFor low-latency discovery, `fast` mode may add:\n\n```json\n{\n  \"edition\": \"lite\"\n}\n```\n\n`lite` reduces recall/reranking depth for better latency. Use `standard` for normal and deep research.\n\nOptional filters:\n\n```json\n{\n  \"search_filter\": {\n    \"match\": {\n      \"site\": [\"example.com\"]\n    },\n    \"items\": {\n      \"block_websites\": [\"spam.example\"]\n    }\n  },\n  \"search_recency_filter\": \"year\"\n}\n```\n\n`search_recency_filter` accepts `week`, `month`, `semiyear`, or `year`. The exact advanced filter grammar should be verified with live API testing before relying on site or block filters. Basic `messages`, `search_source`, `resource_type_filter`, and optional `edition` are the core contract.\n\n## Authentication\n\nDo not hardcode keys. Use:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nThe script can send both:\n\n```text\nAuthorization: Bearer <key>\nX-Appbuilder-Authorization: Bearer <key>\n```\n\nIf live testing shows only one header is accepted, use `--auth-header authorization` or `--auth-header x-appbuilder`.\n\n## Limits\n\n- `top_k` is clamped to 50.\n- `edition` can be `standard` or `lite`; `standard` remains the default for research.\n- There is no known offset/page/next-token for `web_search`.\n- Multiple keys should not be treated as pagination for the same query.\n- Repeated identical calls should use the local query cache unless the task requires current/latest results.\n\n## Expected Response\n\nThe response should expose `references` either at the top level or under `data.references`. The scripts accept both.\n\nUseful fields:\n\n```text\ntitle\nurl\ndate\ncontent\nsnippet\nwebsite\ntype\nmarkdown_text\nrerank_score\nauthority_score\n```\n\n## Live Testing Checklist\n\nWhen an API key is available:\n\n1. Run `baidu_web_search.py --query \"新能源汽车 口碑\" --top-k 10 --output smoke.json`.\n2. Confirm the response contains `references`.\n3. Run `run_search_plan.py` with a tiny 2-query plan.\n4. Confirm `raw_results.jsonl` has one reference per line.\n5. Confirm no key is printed in logs.\n\n## Cache Safety\n\nThe cache stores endpoint, payload, raw API response, and timestamp. It must not store API keys, Authorization headers, or full key identifiers. Cached responses should use `key_id: \"cache\"` in downstream raw results.\n\nFile v1.0.3:references/baike-api.md\n\n# Baidu Baike API Notes\n\nUse this reference before changing lightweight entity lookup behavior.\n\n## Purpose\n\nBaike lookup is a low-budget path for simple entity questions such as:\n\n```text\n这是什么？\n量子计算是什么？\n某个产品/机构/地点有没有百科词条？\n```\n\nIt is not a substitute for web research, recent news, reviews, complaints, or forum discussion.\n\n## Candidate List\n\n```text\nGET https://appbuilder.baidu.com/v2/baike/lemma/get_list_by_title\n```\n\nQuery parameters:\n\n```text\nlemma_title=<term>\ntop_k=1..100\n```\n\nExpected useful fields:\n\n```text\nlemma_id\nlemma_title\nlemma_desc\nis_default\nurl\n```\n\nUse this first when the term may be ambiguous.\n\n## Content Lookup\n\n```text\nGET https://appbuilder.baidu.com/v2/baike/lemma/get_content\n```\n\nQuery parameters:\n\n```text\nsearch_type=lemmaTitle|lemmaId\nsearch_key=<title-or-id>\n```\n\nPrefer `lemmaId` when the candidate list returned an ID.\n\nExpected useful fields:\n\n```text\nlemma_id\nlemma_title\nlemma_desc\nurl\nsummary\nabstract_plain\nabstract_html\nabstract_structured\npic_url\nsquare_pic_url\nrelations\n```\n\n## Authentication\n\nUse the same key environment as web search:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nNever write or print the full key. `lookup.py` defaults to the official Baike header:\n\n```text\nAuthorization: Bearer <key>\n```\n\nIt can also send these when compatibility testing requires it:\n\n```text\nX-Appbuilder-Authorization: Bearer <key>\n```\n\nUse `--auth-header both` or `--auth-header x-appbuilder` only if live testing shows the default `Authorization` header is not accepted in a specific environment.\n\n## Response Compatibility\n\nThe official docs describe a `result` array for candidate lists, while the success example shows a top-level array. `lookup.py` normalizes both shapes into:\n\n```json\n{\"result\": [...]}\n```\n\n## Cache\n\nBaike lookup uses `cache/baike` by default. The cache stores URL, response, and timestamp only. It must not store Authorization headers or keys.\n\nBypass cache with:\n\n```bash\npython scripts/search.py \"<topic>\" --mode lookup --no-cache\n```\n\n## Output\n\nLookup runs write:\n\n```text\nbaike_candidates.json\nbaike_content.json\nfallback_web_results.json\nerrors.jsonl\nrun_summary.json\nlookup_pack.md\n```\n\nUse `lookup_pack.md` for agent-readable output. Use JSON files for exact raw response inspection.\n\n## Excluded APIs\n\nDo not add these to the default path:\n\n- SecondKnow video\n- image or video search\n- Aladdin beta cards\n- intelligent search generation / generated-answer endpoints\n\nThese either do not serve the text-first search-tool goal or add a generated summary layer that conflicts with preserving source evidence.\n\nFile v1.0.3:references/dedupe-policy.md\n\n# Dedupe Policy\n\nUse this reference before changing dedupe behavior.\n\n## Principle\n\nDeduplication must not destroy evidence. Keep raw results and write duplicate mappings.\n\n## URL Canonicalization\n\nNormalize:\n\n```text\nscheme\nhost case\nmobile host prefix m.\ntrailing slash\ntracking params such as utm_*, from, spm, share, source\nfragment removal\n```\n\nKeep:\n\n```text\noriginal_url\ncanonical_url\nquery\nrank\n```\n\n## Title and Summary Similarity\n\nClean text by:\n\n```text\nlower/casefold\nremove whitespace and punctuation noise\nremove common source suffixes\n```\n\nDefault thresholds:\n\n```text\ntitle_similarity >= 0.92\nsummary_similarity >= 0.94\n```\n\nThese thresholds are conservative for v1. If they remove too much, lower their influence or mark near-duplicates without dropping them from selected sources.\n\n## Quality Flags\n\nCurrent v1 flags:\n\n```text\npossible_ad_or_low_quality\ndeep_subdomain\nmissing_url\ndomain_limit_overflow\n```\n\nDo not treat these as final truth. They are signals for ranking and human/agent review.\n\n## Domain Distribution\n\nDefault `--domain-limit 8` flags overflow from a single domain. It does not delete the source by default.\n\nOfficial, primary, or high-authority domains may deserve a higher cap. SEO aggregators and mirrors should receive lower priority.\n\nFile v1.0.3:references/operations.md\n\n# Operations\n\nUse this reference for key pool, rate limit, and run behavior.\n\n## Key Pool\n\nSet keys in the environment:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nAllowed uses:\n\n```text\nfailover\nquota isolation\nlegal rate limiting\nseparating dev/test/prod usage\n```\n\nDo not describe the key pool as a way to bypass official limits.\n\n## Rate Limit Defaults\n\nPrefer `adaptive_search.py`; it uses mode-specific budgets and stops early when marginal value drops.\n\nAdaptive stop conditions are coverage-aware. Normal/deep runs should attempt required intent coverage before stopping on low yield or the raw-result soft cap. This keeps high `top_k` runs from returning only seed-query results.\n\n`run_search_plan.py` is the fixed-budget fallback and defaults to:\n\n```text\n--sleep 0.5\n--timeout 30\n```\n\nFor real usage, increase sleep if errors, throttling, or unstable responses appear.\n\n## Adaptive Defaults\n\n```text\nfast:   runs 1 query, top_k=10\nnormal: starts with 3 queries, plans up to 12 diverse queries, top_k=20\ndeep:   starts with 5 queries, top_k=30 and up to 5 expansion terms\n```\n\nUse:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal\n```\n\nUse `--dry-run` to inspect planned budget without calling the API.\n\nUse `--fixed --top-k 50` only when the user explicitly wants broad/exhaustive coverage or when testing the Skill:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode deep --fixed --top-k 50\n```\n\nIf `--out-dir` is omitted, output is written under:\n\n```text\nskill/runs/<timestamp>-<process-id>-<mode>-<topic>\n```\n\nThe timestamp includes microseconds and the process ID to avoid collisions when several agents or dry-runs start in the same second.\n\n## API Testing Without a Key\n\nUse:\n\n```bash\npython scripts/baidu_web_search.py --query \"新能源汽车 口碑\" --top-k 50 --dry-run\n```\n\nThis prints endpoint and payload only.\n\n## API Testing With a Key\n\nUse a small smoke test first:\n\n```bash\nset BAIDU_AI_SEARCH_API_KEYS=...\npython scripts/baidu_web_search.py --query \"新能源汽车 口碑\" --top-k 10 --output smoke.json\n```\n\nThen run a 2-query plan before running deep mode.\n\n## Caching\n\nAdaptive and fixed plan runs use a query-level cache by default under:\n\n```text\nskill/cache/web_search\n```\n\nThe cache is keyed by:\n\n```text\nendpoint\nquery\ntop_k\nfreshness\ninclude_domains\nblock_domains\n```\n\nThe cache stores request payloads and raw API responses. It never stores API keys. Cached responses are marked with `key_id: \"cache\"` and `cache_hit: true`.\n\nDefault TTL is 24 hours:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal --cache-ttl 86400\n```\n\nForce live API calls for latest/current questions:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal --no-cache\n```\n\nCache should not hide raw API failures; failed calls are not cached.\n\n## File Hygiene\n\nFor draft usage, write runs under the skill folder or a user-specified run directory. Do not scatter temporary outputs across Desktop or home.\n\nFile v1.0.3:references/output-schema.md\n\n# Output Schema\n\nUse this reference before changing output files.\n\n## Run Directory\n\nRecommended web research shape:\n\n```text\nruns/<topic-or-run-id>/\n├── query_plan.json\n├── raw_results.jsonl\n├── errors.jsonl\n├── run_summary.json\n├── deduped_sources.json\n├── adaptive_trace.json\n└── research_pack.md\n```\n\nRecommended lookup shape:\n\n```text\nruns/<topic-or-run-id>/\n├── baike_candidates.json\n├── baike_content.json\n├── fallback_web_results.json\n├── errors.jsonl\n├── run_summary.json\n└── lookup_pack.md\n```\n\n## query_plan.json\n\n```json\n{\n  \"topic\": \"新能源汽车 口碑\",\n  \"mode\": \"normal\",\n  \"profile\": \"product\",\n  \"max_queries\": 10,\n  \"queries\": [\n    {\n      \"query\": \"新能源汽车 口碑 评测\",\n      \"intent\": \"review\",\n      \"source\": \"template\",\n      \"reason\": \"reviews and evaluations\"\n    }\n  ]\n}\n```\n\n## raw_results.jsonl\n\nOne search result reference per line:\n\n```json\n{\n  \"topic\": \"新能源汽车 口碑\",\n  \"mode\": \"normal\",\n  \"query\": \"新能源汽车 口碑 评测\",\n  \"query_intent\": \"review\",\n  \"query_source\": \"template\",\n  \"rank\": 1,\n  \"title\": \"...\",\n  \"url\": \"...\",\n  \"snippet\": \"...\",\n  \"content\": \"...\",\n  \"website\": \"...\",\n  \"date\": \"...\",\n  \"rerank_score\": 0.0,\n  \"authority_score\": 0.0,\n  \"key_id\": \"sha256-prefix\"\n}\n```\n\nNever write the full API key. `key_id` is a hash prefix only.\n\n## deduped_sources.json\n\n```json\n{\n  \"summary\": {\n    \"raw_count\": 100,\n    \"deduped_count\": 63,\n    \"duplicate_count\": 37,\n    \"domain_count\": 28\n  },\n  \"sources\": [\n    {\n      \"source_id\": \"src_0001\",\n      \"title\": \"...\",\n      \"url\": \"...\",\n      \"canonical_url\": \"...\",\n      \"domain\": \"...\",\n      \"snippet\": \"...\",\n      \"best_rank\": 1,\n      \"matched_queries\": [\"新能源汽车 口碑\", \"新能源汽车 口碑 评测\"],\n      \"matched_intents\": [\"overview\", \"review\"],\n      \"matched_stages\": [\"seed\"],\n      \"matched_query_sources\": [\"template\"],\n      \"duplicate_count\": 2,\n      \"quality_flags\": []\n    }\n  ],\n  \"duplicates\": [\n    {\n      \"kept_source_id\": \"src_0001\",\n      \"reason\": \"duplicate_url\",\n      \"query\": \"新能源汽车 口碑 评测\",\n      \"rank\": 3,\n      \"url\": \"...\"\n    }\n  ]\n}\n```\n\n## research_pack.md\n\nA compact Markdown pack for downstream AI analysis. It should include:\n\n```text\nsearch coverage\ncoverage decision and recommended next steps\nquery plan\nmajor domains\nintent coverage\nselected sources\nduplicate note\nlimitations\n```\n\nAgents should cite `source_id` plus URL or domain for factual claims derived from selected sources. The pack is a source pack, not a license to make uncited assertions.\n\n## adaptive_trace.json\n\nWritten by `adaptive_search.py`:\n\n```json\n{\n  \"summary\": {\n      \"query_count\": 3,\n      \"raw_result_count\": 60,\n      \"deduped_count\": 44,\n      \"error_count\": 0,\n      \"cache_hit_count\": 0,\n      \"cache_enabled\": true,\n      \"cache_dir\": \"cache/web_search\",\n      \"cache_ttl\": 86400,\n      \"required_intents\": [\"official\", \"overview\", \"platform\", \"review\"],\n      \"attempted_intents\": [\"official\", \"overview\", \"platform\", \"review\"],\n      \"missing_required_intents\": [],\n      \"stop_reason\": \"low_unique_yield\"\n  },\n  \"trace\": [\n    {\n      \"query\": \"新能源汽车 口碑 评测\",\n      \"intent\": \"review\",\n      \"stage\": \"seed\",\n      \"reference_count\": 20,\n      \"new_unique_count\": 18,\n      \"unique_yield\": 0.9,\n      \"cache_hit\": false\n    }\n  ]\n}\n```\n\n## lookup run_summary.json\n\nWritten by `lookup.py`:\n\n```json\n{\n  \"topic\": \"量子计算\",\n  \"mode\": \"lookup\",\n  \"candidate_count\": 5,\n  \"content_count\": 1,\n  \"fallback_search_used\": false,\n  \"fallback_result_count\": 0,\n  \"error_count\": 0,\n  \"cache_hit_count\": 0,\n  \"cache_enabled\": true,\n  \"cache_dir\": \"cache/baike\",\n  \"cache_ttl\": 86400,\n  \"lookup_pack\": \"runs/.../lookup_pack.md\"\n}\n```\n\n## lookup_pack.md\n\nA compact Markdown pack for entity lookup. It should include:\n\n```text\nsummary\nBaike candidates\nBaike content\noptional fallback web results\nlimitations\n```\n\nAgents should cite the Baike lemma URL or lemma ID for factual claims from lookup output.\n\nFile v1.0.3:references/query-planning.md\n\n# Query Planning\n\nUse this reference before changing query expansion behavior.\n\n## Principle\n\nDo not rely on free-form AI guessing alone. Use a priority-ordered query plan:\n\n```text\nseed templates\n-> coverage templates\n-> platform templates\n-> optional AI/user expansions\n-> result-driven second pass\n-> coverage feedback\n```\n\n## Modes\n\n```text\nfast:\n  1 query\n  low-cost discovery\n\nnormal:\n  5-12 queries\n  default mode\n\ndeep:\n  10-30 queries\n  add second-pass terms when available\n```\n\nThe planner assigns every query an `intent`, `stage`, and `priority`. It must select by diversity slots first, then fill remaining slots by priority. Do not simply append templates and truncate; that wastes calls on similar intents while missing official/platform/complaint coverage.\n\n## Template Classes\n\nBase queries cover:\n\n```text\noverview\nreview\ncomplaint\nprice\nexperience\nforum\nplatform\ncomparison\nservice\n```\n\nHigh-priority default order:\n\n```text\noverview\nreview\ncomplaint\nofficial\nplatform-specific sources early enough for normal mode\nexperience / owner reports\nquality\nprice\nforum\ncomparison\n```\n\nProduct-like topics add:\n\n```text\nowner reports\nfuel/range/specs\nused market\nmaintenance\nquality/common defects\n```\n\nEvent-like topics add:\n\n```text\nlatest\ntimeline\nofficial notice\nfollow-up\ncontroversy\ncause/impact\n```\n\nProject/API-like topics add:\n\n```text\nofficial docs\nGitHub\nissues\nbugs\nalternatives\ntutorials\n```\n\n## Result-Driven Expansion\n\nAfter a first pass, extract terms from titles/snippets:\n\n```text\nentities\ncompetitors\nplatform names\nfailure words\norganization names\nmodel/version names\nregions\n```\n\nThen create second-pass queries:\n\n```text\n{topic} {new_entity}\n{topic} {new_issue}\n{topic} {competitor} 对比\n{topic} {platform}\n```\n\nThe v1 script accepts `--extra-terms` as a JSON list. Later versions can add automatic term extraction.\n\n`adaptive_search.py` already performs lightweight term extraction in deep mode and inserts a small number of result-driven expansion queries.\n\n## Coverage Feedback\n\nStop expanding a query family when the unique URL yield drops below roughly 20%. Add targeted queries when an intent is missing, for example no official source, no complaints, or no forum source.\n\nFile v1.0.3:references/search-strategy.md\n\n# Search Strategy\n\nUse this reference before changing adaptive search behavior.\n\n## Design Goal\n\nFollow the same broad pattern as mature tool-using search agents:\n\n```text\nstart with a small search\ninspect sources\nexpand only when needed\npreserve all sources\nstop when marginal value drops\n```\n\nThe goal is not to maximize API calls. The goal is to maximize useful unique sources per call.\n\n## Default Budgets\n\n```text\nfast:\n  initial_queries: 1\n  planned_query_limit: 1\n  top_k: 10\n  second_pass_terms: 0\n\nnormal:\n  initial_queries: 3\n  planned_query_limit: 12\n  top_k: 20\n  second_pass_terms: 0\n\ndeep:\n  initial_queries: 5\n  top_k: 30\n  second_pass_terms: 5\n```\n\nUse `run_search_plan.py --top-k 50` only when the user wants a fixed, exhaustive run or when smoke testing the known Baidu `top_k=50` ceiling.\n\nThe preferred fixed-budget command is:\n\n```bash\npython scripts/adaptive_search.py --topic \"<topic>\" --mode deep --fixed --top-k 50\n```\n\nThis still writes the same `run_summary.json`, `adaptive_trace.json`, `deduped_sources.json`, and `research_pack.md`.\n\n## Stop Conditions\n\nAdaptive search should stop after the initial stage when:\n\n```text\nrequired intent coverage has been attempted\nand\nraw_result_count >= max_raw_results\nor\nnew_unique_sources / returned_references < min_unique_yield for low_yield_patience queries\n```\n\nDefault unique-yield thresholds:\n\n```text\nfast: 0.35\nnormal: 0.25\ndeep: 0.18\n```\n\nThese are intentionally conservative. If users complain about missing coverage, lower the threshold or increase patience.\n\n`max_raw_results` is a soft cap until required intent coverage has been attempted. For normal product searches, required coverage includes overview, review, complaint, official, platform, and experience. This prevents a high `top_k` run from stopping before official/platform queries.\n\n## Expansion Order\n\nUse this order:\n\n1. Seed queries: core topic, review, complaint.\n2. Official and platform queries: official source, Zhihu, Tieba, Xiaohongshu, Bilibili, Weibo.\n3. Coverage queries: owner/user reports, quality, price, forum/comparison.\n4. Result-driven terms: only in deep mode by default.\n\n## Reporting\n\nAlways report:\n\n```text\nqueries run\nraw result count\ndeduped source count\nduplicate count\nstop reason\ntop domains\nknown gaps\n```\n\nFile v1.0.3:README.en.md\n\n# Baidu API Search\n\n[简体中文](README.md) | English\n\nBaidu API Search is a source-retrieval skill for AI agents that need Chinese web references.\n\nIt calls Baidu AI Search API and Baidu Baike API, then writes raw results, deduplicated sources, and a compact research pack for downstream analysis. It is not a crawler, scraper, or answer-generation service.\n\n## Features\n\n- Baidu AI Search `web_search`\n- Lightweight Baidu Baike lookup\n- Four modes: `lookup`, `fast`, `normal`, `deep`\n- Query planning with adaptive stop conditions\n- URL and near-duplicate cleanup\n- `research_pack.md`, `raw_results.jsonl`, and `run_summary.json` outputs\n- Local cache and multi-key failover\n\n## Requirements\n\n- Python 3.10+\n- A Baidu AI Search / AppBuilder API key\n- An agent runtime that can read `SKILL.md` and run local Python scripts\n\nSet your API key in the environment:\n\n```bash\nexport BAIDU_AI_SEARCH_API_KEYS=\"your-key\"\n```\n\nWindows PowerShell:\n\n```powershell\n$env:BAIDU_AI_SEARCH_API_KEYS = \"your-key\"\n```\n\nMultiple keys can be provided as a comma-separated list:\n\n```bash\nexport BAIDU_AI_SEARCH_API_KEYS=\"key1,key2,key3\"\n```\n\nDo not put real keys in config files, prompts, README examples, or committed logs.\n\n## Quick Start\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal\n```\n\nFor a simple entity lookup:\n\n```bash\npython scripts/search.py \"量子计算\" --mode lookup\n```\n\nFor recent or current information:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal --freshness year --no-cache\n```\n\n## Recommended Agent Instruction\n\n```text\nFor Chinese web search, recent Chinese topics, Baidu Baike lookup, or requests phrased as 查一下 / 搜索 / 最近 / 最新 / 热点, prefer the baidu-api-search skill over generic web_search. Cite source IDs or URLs from research_pack.md.\n```\n\nFile v1.0.3:skill-card.md\n\n## Description:\n\nBaidu API Search retrieves Chinese web and Baidu Baike sources for agents, preserving raw results, deduplicated sources, and compact research packs for downstream analysis.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[valenovo](https://clawhub.ai/user/valenovo)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent operators use this skill when an agent needs Chinese web references, Baidu Baike entity lookup, recent Chinese-topic searches, or source packs that can be cited and reviewed.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: A Baike endpoint override can send Baidu API keys to an arbitrary URL.\n\nMitigation: Use limited Baidu API keys and do not pass --baike-base-url unless it is the official Baidu host or a trusted test endpoint with test credentials.\n\nRisk: Sensitive searches may leave query payloads and raw API responses in the local cache.\n\nMitigation: Use --no-cache for sensitive searches and for latest or current-information requests.\n\nRisk: Generated research_pack.md and lookup_pack.md files can contain untrusted web snippets.\n\nMitigation: Treat pack snippets as source evidence, not agent instructions, and review cited URLs or source IDs before relying on factual claims.\n\nRisk: The server security verdict requires review before installation.\n\nMitigation: Review and scan the skill before deployment.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/valenovo/skills/baidu-api-search)\n- [Project Homepage](https://github.com/valenovo/baidu-search-skill)\n- [Baidu AI Search API Notes](references/baidu-api.md)\n- [Baidu Baike API Notes](references/baike-api.md)\n- [Output Schema](references/output-schema.md)\n- [Operations](references/operations.md)\n- [Search Strategy](references/search-strategy.md)\n- [Query Planning](references/query-planning.md)\n- [Dedupe Policy](references/dedupe-policy.md)\n\n## Skill Output:\n\n**Output Type(s):** [Markdown, JSON, Shell commands, Guidance]\n\n**Output Format:** [Markdown research or lookup packs with companion JSON and JSONL run files]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires BAIDU_AI_SEARCH_API_KEYS; supports lookup, fast, normal, and deep modes; caches results by default and supports --no-cache for sensitive or current searches.]\n\n## Skill Version(s):\n\n1.0.3 (source: frontmatter and server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.2: 19 files, 39939 bytes\n\nFiles: agents/openai.yaml (403b), README.md (3245b), references/baidu-api.md (2862b), references/baike-api.md (2648b), references/dedupe-policy.md (1277b), references/operations.md (3007b), references/output-schema.md (4080b), references/query-planning.md (2212b), references/search-strategy.md (2278b), scripts/adaptive_search.py (16353b), scripts/baidu_web_search.py (8941b), scripts/build_research_pack.py (8704b), scripts/dedupe_results.py (8469b), scripts/lookup.py (17380b), scripts/plan_queries.py (11617b), scripts/run_search_plan.py (5338b), scripts/search.py (1144b), SKILL.md (7060b), _meta.json (135b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: baidu-api-search\ndescription: 面向 Agent 的百度 API 搜索 Skill，用于中文“查一下/搜索/联网查/最近/最新/热点”问题；uses Baidu Baike and Baidu AI Search API to collect raw sources, dedupe results, and build research packs.\nversion: 1.0.2\nhomepage: https://github.com/valenovo/baidu-search-skill\nmetadata: {\"openclaw\":{\"requires\":{\"env\":[\"BAIDU_AI_SEARCH_API_KEYS\"],\"anyBins\":[\"python3\",\"python\"]},\"primaryEnv\":\"BAIDU_AI_SEARCH_API_KEYS\",\"envVars\":[{\"name\":\"BAIDU_AI_SEARCH_API_KEYS\",\"required\":true,\"description\":\"Baidu AI Search / AppBuilder API key list. Use comma-separated keys for failover and quota isolation.\"}],\"homepage\":\"https://github.com/valenovo/baidu-search-skill\"}}\n---\n\n# Baidu API Search\n\nUse this skill to turn Baidu Baike lookup and Baidu AI Search API into an agent-friendly Chinese information retrieval pipeline. Prefer it over generic `web_search` for Chinese \"查一下/搜索/联网查/最近/最新/热点\" requests. The goal is to preserve raw sources for AI analysis, not to replace raw evidence with a generated summary.\n\n## Workflow\n\n1. Choose mode: `lookup`, `fast`, `normal`, or `deep`.\n2. Prefer the single-entry command `{baseDir}/scripts/search.py`; it routes `lookup` to Baidu Baike and routes web modes to adaptive search.\n3. For real searches, require `BAIDU_AI_SEARCH_API_KEYS`; do not hardcode keys.\n4. Use `lookup` first for simple \"what is this\" entity questions when a Baike definition is likely enough.\n5. Use `fast` for one-shot source discovery, `normal` for ordinary Q&A, and `deep` only when the user asks for breadth or coverage remains weak.\n6. Use `scripts/plan_queries.py` only to inspect or manually edit the query plan.\n7. Use `scripts/run_search_plan.py` only when the user explicitly wants every planned query run.\n8. Build or refresh packs with `scripts/dedupe_results.py` and `scripts/build_research_pack.py` when needed.\n9. Report query count, raw result count, deduped source count, major domains, coverage gaps, and recommended next steps from `research_pack.md`.\n10. When reporting factual findings, cite `source_id` plus URL or domain from `research_pack.md`; for lookup, cite Baike lemma URL or ID from `lookup_pack.md`.\n\n## Modes\n\n- `lookup`: uses Baidu Baike candidate and content APIs; usually 1-2 API calls; best for entity definitions and disambiguation.\n- `fast`: runs 1 query, `top_k=10`, and defaults to Baidu `lite` search edition; quick low-cost source discovery.\n- `normal`: starts with 3 queries, plans up to 12 diverse queries, `top_k=20`; default for ordinary Q&A.\n- `deep`: starts with 5 queries, `top_k=30`; may add result-driven expansion terms.\n\nDo not jump to `deep` by default. Increase budget only when the user asks for depth or the first pass leaves clear coverage gaps.\n\n## Commands\n\nCreate a query plan:\n\n```bash\npython \"{baseDir}/scripts/plan_queries.py\" --topic \"新能源汽车 口碑\" --mode normal --output runs/ev-reputation/query_plan.json\n```\n\nInspect the Baidu API payload without calling the API:\n\n```bash\npython \"{baseDir}/scripts/baidu_web_search.py\" --query \"新能源汽车 口碑\" --top-k 50 --dry-run\n```\n\nRun a lightweight Baike lookup:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"量子计算\" --mode lookup\n```\n\nRun lookup and fall back to one lite web search only if Baike has no candidate:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"某个新产品名称\" --mode lookup --fallback-search\n```\n\nRun adaptively after `BAIDU_AI_SEARCH_API_KEYS` is set:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal\n```\n\nLimit web results to recent pages when the user asks for recent/latest information:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal --freshness year --no-cache\n```\n\nForce a fresh live API run when the user asks for latest/current information:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal --no-cache\n```\n\nRun a fuller fixed-budget pass only when the user asks for broad coverage or exhaustive testing:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode deep --fixed --top-k 50\n```\n\nRun every query in a plan only when explicitly needed:\n\n```bash\npython \"{baseDir}/scripts/run_search_plan.py\" --plan runs/ev-reputation/query_plan.json --out-dir runs/ev-reputation --top-k 50\n```\n\nDeduplicate:\n\n```bash\npython \"{baseDir}/scripts/dedupe_results.py\" --input runs/ev-reputation/raw_results.jsonl --output runs/ev-reputation/deduped_sources.json\n```\n\nBuild a research pack:\n\n```bash\npython \"{baseDir}/scripts/build_research_pack.py\" --run-dir runs/ev-reputation --output runs/ev-reputation/research_pack.md\n```\n\n## References\n\n- Read `references/baidu-api.md` before changing request/auth logic.\n- Read `references/baike-api.md` before changing Baike lookup logic.\n- Read `references/query-planning.md` before changing query expansion.\n- Read `references/dedupe-policy.md` before changing dedupe behavior.\n- Read `references/output-schema.md` before changing output files.\n- Read `references/operations.md` for key-pool, rate-limit, and run-directory behavior.\n- Read `references/search-strategy.md` before changing adaptive stop conditions.\n\n## Rules\n\n- Never write API keys into files, git, logs, or responses.\n- Never print or echo key environment variables. If you need to check readiness, use a boolean check such as `python -c \"import os; raise SystemExit(0 if os.getenv('BAIDU_AI_SEARCH_API_KEYS') else 1)\"` or run `scripts/search.py` and let it report missing configuration.\n- Treat multiple keys as reliability/quota isolation, not as pagination for one query.\n- Use the query cache to avoid repeated identical calls; bypass it with `--no-cache` for latest/current topics.\n- Never discard raw results when deduplicating; keep duplicate mappings.\n- Prefer fixed templates plus result-driven expansion over unconstrained AI guessing.\n- Require citations for substantive claims: use source IDs, URLs, or domains from `research_pack.md`.\n- Keep query plans diverse: include official and platform-specific queries early enough for normal mode.\n- Spend search budget in stages: seed query first, coverage queries second, result expansion last.\n- Stop when required intent coverage has been attempted and additional queries have low unique-source yield unless the user explicitly requests exhaustive search.\n- Do not use Baidu video search, image search, SecondKnow video, Aladdin, or intelligent search generation by default. This skill is a source retrieval tool, not a generated-answer wrapper.\n\n## Agent Handoff\n\nFor another agent, the safest default command is:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"<topic>\" --mode normal\n```\n\nFor simple entity definitions, use:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"<topic>\" --mode lookup\n```\n\nRead `run_summary.json` first. For lookup runs, read `lookup_pack.md`; for web runs, read the `Coverage Decision` section in `research_pack.md`, then inspect `raw_results.jsonl` only when raw evidence is needed.\n\nFile v1.0.2:README.md\n\n# Baidu API Search\n\n简体中文 | English\n\n面向 Agent 的百度 API 搜索 Skill。它调用百度 AI Search API 和百度百科 API，把中文搜索结果整理成可复查、可引用的 research pack，适合需要中文网页来源的 AI Agent 使用。\n\n这个 Skill 不是爬虫，也不是答案生成接口。它只负责检索、去重、保留原始结果，并把来源整理给 Agent 后续分析。\n\n## 功能\n\n- 百度 AI Search `web_search`\n- 百度百科轻量实体查询\n- `lookup`、`fast`、`normal`、`deep` 四种模式\n- 自动规划搜索词并根据覆盖情况提前停止\n- URL 去重和近似重复合并\n- 输出 `research_pack.md`、`raw_results.jsonl`、`run_summary.json`\n- 支持本地缓存和多个 API Key 失败切换\n\n## 环境要求\n\n- Python 3.10+\n- 百度 AI Search / AppBuilder API Key\n- 能读取 `SKILL.md` 并运行本地 Python 脚本的 Agent 环境\n\n脚本只使用 Python 标准库，不需要额外安装依赖。\n\nAPI Key 请放在环境变量里：\n\n```bash\nexport BAIDU_AI_SEARCH_API_KEYS=\"your-key\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:BAIDU_AI_SEARCH_API_KEYS = \"your-key\"\n```\n\n多个 Key 用英文逗号分隔：\n\n```bash\nexport BAIDU_AI_SEARCH_API_KEYS=\"key1,key2,key3\"\n```\n\n不要把真实 Key 写进配置文件、README、Prompt、日志或 Git 提交里。\n\n## 快速使用\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal\n```\n\n简单实体查询：\n\n```bash\npython scripts/search.py \"量子计算\" --mode lookup\n```\n\n查询最近或当前信息：\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal --freshness year --no-cache\n```\n\n## 给 Agent 的推荐指令\n\n```text\n中文网页搜索、百度百科查询、最近/最新/热点类中文问题，以及用户说“查一下”“搜索”“联网查”时，优先使用 baidu-api-search skill。回答事实性结论时引用 research_pack.md 里的 source_id 或 URL。\n```\n\n## English\n\nBaidu API Search is a source-retrieval skill for AI agents that need Chinese web references.\n\nIt calls Baidu AI Search API and Baidu Baike API, then writes raw results, deduplicated sources, and a compact research pack for downstream analysis. It is not a crawler, scraper, or answer-generation service.\n\n### Features\n\n- Baidu AI Search `web_search`\n- Lightweight Baidu Baike lookup\n- Four modes: `lookup`, `fast`, `normal`, `deep`\n- Query planning with adaptive stop conditions\n- URL and near-duplicate cleanup\n- `research_pack.md`, `raw_results.jsonl`, and `run_summary.json` outputs\n- Local cache and multi-key failover\n\n### Requirements\n\n- Python 3.10+\n- A Baidu AI Search / AppBuilder API key\n- An agent runtime that can read `SKILL.md` and run local Python scripts\n\nSet your API key in the environment:\n\n```bash\nexport BAIDU_AI_SEARCH_API_KEYS=\"your-key\"\n```\n\nWindows PowerShell:\n\n```powershell\n$env:BAIDU_AI_SEARCH_API_KEYS = \"your-key\"\n```\n\n### Quick Start\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal\n```\n\nFor a simple entity lookup:\n\n```bash\npython scripts/search.py \"量子计算\" --mode lookup\n```\n\nFor recent or current information:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal --freshness year --no-cache\n```\n\nFile v1.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn702h51bcntppmj04vwcpqzn982ptk8\",\n  \"slug\": \"baidu-api-search\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1778946804563\n}\n\nFile v1.0.2:references/baidu-api.md\n\n# Baidu AI Search API Notes\n\nUse this reference before changing request/auth behavior.\n\n## Endpoint\n\n```text\nPOST https://qianfan.baidubce.com/v2/ai_search/web_search\n```\n\nThis skill targets the web search endpoint because it returns raw-ish `references` suitable for downstream AI analysis. Do not replace it with generated answer endpoints when the user asks for original information.\n\n## Request Shape\n\nThe current script builds this payload:\n\n```json\n{\n  \"messages\": [{\"role\": \"user\", \"content\": \"新能源汽车 口碑\"}],\n  \"search_source\": \"baidu_search_v2\",\n  \"resource_type_filter\": [{\"type\": \"web\", \"top_k\": 50}]\n}\n```\n\nFor low-latency discovery, `fast` mode may add:\n\n```json\n{\n  \"edition\": \"lite\"\n}\n```\n\n`lite` reduces recall/reranking depth for better latency. Use `standard` for normal and deep research.\n\nOptional filters:\n\n```json\n{\n  \"search_filter\": {\n    \"match\": {\n      \"site\": [\"example.com\"]\n    },\n    \"items\": {\n      \"block_websites\": [\"spam.example\"]\n    }\n  },\n  \"search_recency_filter\": \"year\"\n}\n```\n\n`search_recency_filter` accepts `week`, `month`, `semiyear`, or `year`. The exact advanced filter grammar should be verified with live API testing before relying on site or block filters. Basic `messages`, `search_source`, `resource_type_filter`, and optional `edition` are the core contract.\n\n## Authentication\n\nDo not hardcode keys. Use:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nThe script can send both:\n\n```text\nAuthorization: Bearer <key>\nX-Appbuilder-Authorization: Bearer <key>\n```\n\nIf live testing shows only one header is accepted, use `--auth-header authorization` or `--auth-header x-appbuilder`.\n\n## Limits\n\n- `top_k` is clamped to 50.\n- `edition` can be `standard` or `lite`; `standard` remains the default for research.\n- There is no known offset/page/next-token for `web_search`.\n- Multiple keys should not be treated as pagination for the same query.\n- Repeated identical calls should use the local query cache unless the task requires current/latest results.\n\n## Expected Response\n\nThe response should expose `references` either at the top level or under `data.references`. The scripts accept both.\n\nUseful fields:\n\n```text\ntitle\nurl\ndate\ncontent\nsnippet\nwebsite\ntype\nmarkdown_text\nrerank_score\nauthority_score\n```\n\n## Live Testing Checklist\n\nWhen an API key is available:\n\n1. Run `baidu_web_search.py --query \"新能源汽车 口碑\" --top-k 10 --output smoke.json`.\n2. Confirm the response contains `references`.\n3. Run `run_search_plan.py` with a tiny 2-query plan.\n4. Confirm `raw_results.jsonl` has one reference per line.\n5. Confirm no key is printed in logs.\n\n## Cache Safety\n\nThe cache stores endpoint, payload, raw API response, and timestamp. It must not store API keys, Authorization headers, or full key identifiers. Cached responses should use `key_id: \"cache\"` in downstream raw results.\n\nFile v1.0.2:references/baike-api.md\n\n# Baidu Baike API Notes\n\nUse this reference before changing lightweight entity lookup behavior.\n\n## Purpose\n\nBaike lookup is a low-budget path for simple entity questions such as:\n\n```text\n这是什么？\n量子计算是什么？\n某个产品/机构/地点有没有百科词条？\n```\n\nIt is not a substitute for web research, recent news, reviews, complaints, or forum discussion.\n\n## Candidate List\n\n```text\nGET https://appbuilder.baidu.com/v2/baike/lemma/get_list_by_title\n```\n\nQuery parameters:\n\n```text\nlemma_title=<term>\ntop_k=1..100\n```\n\nExpected useful fields:\n\n```text\nlemma_id\nlemma_title\nlemma_desc\nis_default\nurl\n```\n\nUse this first when the term may be ambiguous.\n\n## Content Lookup\n\n```text\nGET https://appbuilder.baidu.com/v2/baike/lemma/get_content\n```\n\nQuery parameters:\n\n```text\nsearch_type=lemmaTitle|lemmaId\nsearch_key=<title-or-id>\n```\n\nPrefer `lemmaId` when the candidate list returned an ID.\n\nExpected useful fields:\n\n```text\nlemma_id\nlemma_title\nlemma_desc\nurl\nsummary\nabstract_plain\nabstract_html\nabstract_structured\npic_url\nsquare_pic_url\nrelations\n```\n\n## Authentication\n\nUse the same key environment as web search:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nNever write or print the full key. `lookup.py` defaults to the official Baike header:\n\n```text\nAuthorization: Bearer <key>\n```\n\nIt can also send these when compatibility testing requires it:\n\n```text\nX-Appbuilder-Authorization: Bearer <key>\n```\n\nUse `--auth-header both` or `--auth-header x-appbuilder` only if live testing shows the default `Authorization` header is not accepted in a specific environment.\n\n## Response Compatibility\n\nThe official docs describe a `result` array for candidate lists, while the success example shows a top-level array. `lookup.py` normalizes both shapes into:\n\n```json\n{\"result\": [...]}\n```\n\n## Cache\n\nBaike lookup uses `cache/baike` by default. The cache stores URL, response, and timestamp only. It must not store Authorization headers or keys.\n\nBypass cache with:\n\n```bash\npython scripts/search.py \"<topic>\" --mode lookup --no-cache\n```\n\n## Output\n\nLookup runs write:\n\n```text\nbaike_candidates.json\nbaike_content.json\nfallback_web_results.json\nerrors.jsonl\nrun_summary.json\nlookup_pack.md\n```\n\nUse `lookup_pack.md` for agent-readable output. Use JSON files for exact raw response inspection.\n\n## Excluded APIs\n\nDo not add these to the default path:\n\n- SecondKnow video\n- image or video search\n- Aladdin beta cards\n- intelligent search generation / generated-answer endpoints\n\nThese either do not serve the text-first search-tool goal or add a generated summary layer that conflicts with preserving source evidence.\n\nFile v1.0.2:references/dedupe-policy.md\n\n# Dedupe Policy\n\nUse this reference before changing dedupe behavior.\n\n## Principle\n\nDeduplication must not destroy evidence. Keep raw results and write duplicate mappings.\n\n## URL Canonicalization\n\nNormalize:\n\n```text\nscheme\nhost case\nmobile host prefix m.\ntrailing slash\ntracking params such as utm_*, from, spm, share, source\nfragment removal\n```\n\nKeep:\n\n```text\noriginal_url\ncanonical_url\nquery\nrank\n```\n\n## Title and Summary Similarity\n\nClean text by:\n\n```text\nlower/casefold\nremove whitespace and punctuation noise\nremove common source suffixes\n```\n\nDefault thresholds:\n\n```text\ntitle_similarity >= 0.92\nsummary_similarity >= 0.94\n```\n\nThese thresholds are conservative for v1. If they remove too much, lower their influence or mark near-duplicates without dropping them from selected sources.\n\n## Quality Flags\n\nCurrent v1 flags:\n\n```text\npossible_ad_or_low_quality\ndeep_subdomain\nmissing_url\ndomain_limit_overflow\n```\n\nDo not treat these as final truth. They are signals for ranking and human/agent review.\n\n## Domain Distribution\n\nDefault `--domain-limit 8` flags overflow from a single domain. It does not delete the source by default.\n\nOfficial, primary, or high-authority domains may deserve a higher cap. SEO aggregators and mirrors should receive lower priority.\n\nFile v1.0.2:references/operations.md\n\n# Operations\n\nUse this reference for key pool, rate limit, and run behavior.\n\n## Key Pool\n\nSet keys in the environment:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nAllowed uses:\n\n```text\nfailover\nquota isolation\nlegal rate limiting\nseparating dev/test/prod usage\n```\n\nDo not describe the key pool as a way to bypass official limits.\n\n## Rate Limit Defaults\n\nPrefer `adaptive_search.py`; it uses mode-specific budgets and stops early when marginal value drops.\n\nAdaptive stop conditions are coverage-aware. Normal/deep runs should attempt required intent coverage before stopping on low yield or the raw-result soft cap. This keeps high `top_k` runs from returning only seed-query results.\n\n`run_search_plan.py` is the fixed-budget fallback and defaults to:\n\n```text\n--sleep 0.5\n--timeout 30\n```\n\nFor real usage, increase sleep if errors, throttling, or unstable responses appear.\n\n## Adaptive Defaults\n\n```text\nfast:   runs 1 query, top_k=10\nnormal: starts with 3 queries, plans up to 12 diverse queries, top_k=20\ndeep:   starts with 5 queries, top_k=30 and up to 5 expansion terms\n```\n\nUse:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal\n```\n\nUse `--dry-run` to inspect planned budget without calling the API.\n\nUse `--fixed --top-k 50` only when the user explicitly wants broad/exhaustive coverage or when testing the Skill:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode deep --fixed --top-k 50\n```\n\nIf `--out-dir` is omitted, output is written under:\n\n```text\nskill/runs/<timestamp>-<process-id>-<mode>-<topic>\n```\n\nThe timestamp includes microseconds and the process ID to avoid collisions when several agents or dry-runs start in the same second.\n\n## API Testing Without a Key\n\nUse:\n\n```bash\npython scripts/baidu_web_search.py --query \"新能源汽车 口碑\" --top-k 50 --dry-run\n```\n\nThis prints endpoint and payload only.\n\n## API Testing With a Key\n\nUse a small smoke test first:\n\n```bash\nset BAIDU_AI_SEARCH_API_KEYS=...\npython scripts/baidu_web_search.py --query \"新能源汽车 口碑\" --top-k 10 --output smoke.json\n```\n\nThen run a 2-query plan before running deep mode.\n\n## Caching\n\nAdaptive and fixed plan runs use a query-level cache by default under:\n\n```text\nskill/cache/web_search\n```\n\nThe cache is keyed by:\n\n```text\nendpoint\nquery\ntop_k\nfreshness\ninclude_domains\nblock_domains\n```\n\nThe cache stores request payloads and raw API responses. It never stores API keys. Cached responses are marked with `key_id: \"cache\"` and `cache_hit: true`.\n\nDefault TTL is 24 hours:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal --cache-ttl 86400\n```\n\nForce live API calls for latest/current questions:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal --no-cache\n```\n\nCache should not hide raw API failures; failed calls are not cached.\n\n## File Hygiene\n\nFor draft usage, write runs under the skill folder or a user-specified run directory. Do not scatter temporary outputs across Desktop or home.\n\nFile v1.0.2:references/output-schema.md\n\n# Output Schema\n\nUse this reference before changing output files.\n\n## Run Directory\n\nRecommended web research shape:\n\n```text\nruns/<topic-or-run-id>/\n├── query_plan.json\n├── raw_results.jsonl\n├── errors.jsonl\n├── run_summary.json\n├── deduped_sources.json\n├── adaptive_trace.json\n└── research_pack.md\n```\n\nRecommended lookup shape:\n\n```text\nruns/<topic-or-run-id>/\n├── baike_candidates.json\n├── baike_content.json\n├── fallback_web_results.json\n├── errors.jsonl\n├── run_summary.json\n└── lookup_pack.md\n```\n\n## query_plan.json\n\n```json\n{\n  \"topic\": \"新能源汽车 口碑\",\n  \"mode\": \"normal\",\n  \"profile\": \"product\",\n  \"max_queries\": 10,\n  \"queries\": [\n    {\n      \"query\": \"新能源汽车 口碑 评测\",\n      \"intent\": \"review\",\n      \"source\": \"template\",\n      \"reason\": \"reviews and evaluations\"\n    }\n  ]\n}\n```\n\n## raw_results.jsonl\n\nOne search result reference per line:\n\n```json\n{\n  \"topic\": \"新能源汽车 口碑\",\n  \"mode\": \"normal\",\n  \"query\": \"新能源汽车 口碑 评测\",\n  \"query_intent\": \"review\",\n  \"query_source\": \"template\",\n  \"rank\": 1,\n  \"title\": \"...\",\n  \"url\": \"...\",\n  \"snippet\": \"...\",\n  \"content\": \"...\",\n  \"website\": \"...\",\n  \"date\": \"...\",\n  \"rerank_score\": 0.0,\n  \"authority_score\": 0.0,\n  \"key_id\": \"sha256-prefix\"\n}\n```\n\nNever write the full API key. `key_id` is a hash prefix only.\n\n## deduped_sources.json\n\n```json\n{\n  \"summary\": {\n    \"raw_count\": 100,\n    \"deduped_count\": 63,\n    \"duplicate_count\": 37,\n    \"domain_count\": 28\n  },\n  \"sources\": [\n    {\n      \"source_id\": \"src_0001\",\n      \"title\": \"...\",\n      \"url\": \"...\",\n      \"canonical_url\": \"...\",\n      \"domain\": \"...\",\n      \"snippet\": \"...\",\n      \"best_rank\": 1,\n      \"matched_queries\": [\"新能源汽车 口碑\", \"新能源汽车 口碑 评测\"],\n      \"matched_intents\": [\"overview\", \"review\"],\n      \"matched_stages\": [\"seed\"],\n      \"matched_query_sources\": [\"template\"],\n      \"duplicate_count\": 2,\n      \"quality_flags\": []\n    }\n  ],\n  \"duplicates\": [\n    {\n      \"kept_source_id\": \"src_0001\",\n      \"reason\": \"duplicate_url\",\n      \"query\": \"新能源汽车 口碑 评测\",\n      \"rank\": 3,\n      \"url\": \"...\"\n    }\n  ]\n}\n```\n\n## research_pack.md\n\nA compact Markdown pack for downstream AI analysis. It should include:\n\n```text\nsearch coverage\ncoverage decision and recommended next steps\nquery plan\nmajor domains\nintent coverage\nselected sources\nduplicate note\nlimitations\n```\n\nAgents should cite `source_id` plus URL or domain for factual claims derived from selected sources. The pack is a source pack, not a license to make uncited assertions.\n\n## adaptive_trace.json\n\nWritten by `adaptive_search.py`:\n\n```json\n{\n  \"summary\": {\n      \"query_count\": 3,\n      \"raw_result_count\": 60,\n      \"deduped_count\": 44,\n      \"error_count\": 0,\n      \"cache_hit_count\": 0,\n      \"cache_enabled\": true,\n      \"cache_dir\": \"cache/web_search\",\n      \"cache_ttl\": 86400,\n      \"required_intents\": [\"official\", \"overview\", \"platform\", \"review\"],\n      \"attempted_intents\": [\"official\", \"overview\", \"platform\", \"review\"],\n      \"missing_required_intents\": [],\n      \"stop_reason\": \"low_unique_yield\"\n  },\n  \"trace\": [\n    {\n      \"query\": \"新能源汽车 口碑 评测\",\n      \"intent\": \"review\",\n      \"stage\": \"seed\",\n      \"reference_count\": 20,\n      \"new_unique_count\": 18,\n      \"unique_yield\": 0.9,\n      \"cache_hit\": false\n    }\n  ]\n}\n```\n\n## lookup run_summary.json\n\nWritten by `lookup.py`:\n\n```json\n{\n  \"topic\": \"量子计算\",\n  \"mode\": \"lookup\",\n  \"candidate_count\": 5,\n  \"content_count\": 1,\n  \"fallback_search_used\": false,\n  \"fallback_result_count\": 0,\n  \"error_count\": 0,\n  \"cache_hit_count\": 0,\n  \"cache_enabled\": true,\n  \"cache_dir\": \"cache/baike\",\n  \"cache_ttl\": 86400,\n  \"lookup_pack\": \"runs/.../lookup_pack.md\"\n}\n```\n\n## lookup_pack.md\n\nA compact Markdown pack for entity lookup. It should include:\n\n```text\nsummary\nBaike candidates\nBaike content\noptional fallback web results\nlimitations\n```\n\nAgents should cite the Baike lemma URL or lemma ID for factual claims from lookup output.\n\nFile v1.0.2:references/query-planning.md\n\n# Query Planning\n\nUse this reference before changing query expansion behavior.\n\n## Principle\n\nDo not rely on free-form AI guessing alone. Use a priority-ordered query plan:\n\n```text\nseed templates\n-> coverage templates\n-> platform templates\n-> optional AI/user expansions\n-> result-driven second pass\n-> coverage feedback\n```\n\n## Modes\n\n```text\nfast:\n  1 query\n  low-cost discovery\n\nnormal:\n  5-12 queries\n  default mode\n\ndeep:\n  10-30 queries\n  add second-pass terms when available\n```\n\nThe planner assigns every query an `intent`, `stage`, and `priority`. It must select by diversity slots first, then fill remaining slots by priority. Do not simply append templates and truncate; that wastes calls on similar intents while missing official/platform/complaint coverage.\n\n## Template Classes\n\nBase queries cover:\n\n```text\noverview\nreview\ncomplaint\nprice\nexperience\nforum\nplatform\ncomparison\nservice\n```\n\nHigh-priority default order:\n\n```text\noverview\nreview\ncomplaint\nofficial\nplatform-specific sources early enough for normal mode\nexperience / owner reports\nquality\nprice\nforum\ncomparison\n```\n\nProduct-like topics add:\n\n```text\nowner reports\nfuel/range/specs\nused market\nmaintenance\nquality/common defects\n```\n\nEvent-like topics add:\n\n```text\nlatest\ntimeline\nofficial notice\nfollow-up\ncontroversy\ncause/impact\n```\n\nProject/API-like topics add:\n\n```text\nofficial docs\nGitHub\nissues\nbugs\nalternatives\ntutorials\n```\n\n## Result-Driven Expansion\n\nAfter a first pass, extract terms from titles/snippets:\n\n```text\nentities\ncompetitors\nplatform names\nfailure words\norganization names\nmodel/version names\nregions\n```\n\nThen create second-pass queries:\n\n```text\n{topic} {new_entity}\n{topic} {new_issue}\n{topic} {competitor} 对比\n{topic} {platform}\n```\n\nThe v1 script accepts `--extra-terms` as a JSON list. Later versions can add automatic term extraction.\n\n`adaptive_search.py` already performs lightweight term extraction in deep mode and inserts a small number of result-driven expansion queries.\n\n## Coverage Feedback\n\nStop expanding a query family when the unique URL yield drops below roughly 20%. Add targeted queries when an intent is missing, for example no official source, no complaints, or no forum source.\n\nFile v1.0.2:references/search-strategy.md\n\n# Search Strategy\n\nUse this reference before changing adaptive search behavior.\n\n## Design Goal\n\nFollow the same broad pattern as mature tool-using search agents:\n\n```text\nstart with a small search\ninspect sources\nexpand only when needed\npreserve all sources\nstop when marginal value drops\n```\n\nThe goal is not to maximize API calls. The goal is to maximize useful unique sources per call.\n\n## Default Budgets\n\n```text\nfast:\n  initial_queries: 1\n  planned_query_limit: 1\n  top_k: 10\n  second_pass_terms: 0\n\nnormal:\n  initial_queries: 3\n  planned_query_limit: 12\n  top_k: 20\n  second_pass_terms: 0\n\ndeep:\n  initial_queries: 5\n  top_k: 30\n  second_pass_terms: 5\n```\n\nUse `run_search_plan.py --top-k 50` only when the user wants a fixed, exhaustive run or when smoke testing the known Baidu `top_k=50` ceiling.\n\nThe preferred fixed-budget command is:\n\n```bash\npython scripts/adaptive_search.py --topic \"<topic>\" --mode deep --fixed --top-k 50\n```\n\nThis still writes the same `run_summary.json`, `adaptive_trace.json`, `deduped_sources.json`, and `research_pack.md`.\n\n## Stop Conditions\n\nAdaptive search should stop after the initial stage when:\n\n```text\nrequired intent coverage has been attempted\nand\nraw_result_count >= max_raw_results\nor\nnew_unique_sources / returned_references < min_unique_yield for low_yield_patience queries\n```\n\nDefault unique-yield thresholds:\n\n```text\nfast: 0.35\nnormal: 0.25\ndeep: 0.18\n```\n\nThese are intentionally conservative. If users complain about missing coverage, lower the threshold or increase patience.\n\n`max_raw_results` is a soft cap until required intent coverage has been attempted. For normal product searches, required coverage includes overview, review, complaint, official, platform, and experience. This prevents a high `top_k` run from stopping before official/platform queries.\n\n## Expansion Order\n\nUse this order:\n\n1. Seed queries: core topic, review, complaint.\n2. Official and platform queries: official source, Zhihu, Tieba, Xiaohongshu, Bilibili, Weibo.\n3. Coverage queries: owner/user reports, quality, price, forum/comparison.\n4. Result-driven terms: only in deep mode by default.\n\n## Reporting\n\nAlways report:\n\n```text\nqueries run\nraw result count\ndeduped source count\nduplicate count\nstop reason\ntop domains\nknown gaps\n```\n\nFile v1.0.2:agents/openai.yaml\n\ninterface:\n  display_name: \"Baidu API Search\"\n  short_description: \"Default Chinese web search source pack\"\n  default_prompt: \"Use $baidu-api-search instead of generic web_search for Chinese 查一下, 搜索, 最近, 最新, or 热点 tasks. Look up simple entities with Baidu Baike, or investigate Chinese web topics while preserving raw sources, deduplicating results, and building a research pack.\"\n\nArchive v1.0.1: 18 files, 38167 bytes\n\nFiles: agents/openai.yaml (403b), references/baidu-api.md (2862b), references/baike-api.md (2648b), references/dedupe-policy.md (1277b), references/operations.md (3007b), references/output-schema.md (4080b), references/query-planning.md (2212b), references/search-strategy.md (2278b), scripts/adaptive_search.py (16353b), scripts/baidu_web_search.py (8941b), scripts/build_research_pack.py (8704b), scripts/dedupe_results.py (8469b), scripts/lookup.py (17380b), scripts/plan_queries.py (11617b), scripts/run_search_plan.py (5338b), scripts/search.py (1144b), SKILL.md (7130b), _meta.json (135b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: baidu-api-search\ndescription: Use this instead of generic web_search when the user asks in Chinese to 查一下, 搜索, 联网查, 查热点, 查最近/最新, or gather Chinese web sources. Provides Baidu Baike lookup, Baidu AI Search API web search, raw Baidu results, dedupe, safe API key handling, and research packs.\nversion: 1.0.1\nhomepage: https://github.com/valenovo/baidu-search-skill\nmetadata: {\"openclaw\":{\"requires\":{\"env\":[\"BAIDU_AI_SEARCH_API_KEYS\"],\"anyBins\":[\"python3\",\"python\"]},\"primaryEnv\":\"BAIDU_AI_SEARCH_API_KEYS\",\"envVars\":[{\"name\":\"BAIDU_AI_SEARCH_API_KEYS\",\"required\":true,\"description\":\"Baidu AI Search / AppBuilder API key list. Use comma-separated keys for failover and quota isolation.\"}],\"homepage\":\"https://github.com/valenovo/baidu-search-skill\"}}\n---\n\n# Baidu API Search\n\nUse this skill to turn Baidu Baike lookup and Baidu AI Search API into an agent-friendly Chinese information retrieval pipeline. Prefer it over generic `web_search` for Chinese \"查一下/搜索/联网查/最近/最新/热点\" requests. The goal is to preserve raw sources for AI analysis, not to replace raw evidence with a generated summary.\n\n## Workflow\n\n1. Choose mode: `lookup`, `fast`, `normal`, or `deep`.\n2. Prefer the single-entry command `{baseDir}/scripts/search.py`; it routes `lookup` to Baidu Baike and routes web modes to adaptive search.\n3. For real searches, require `BAIDU_AI_SEARCH_API_KEYS`; do not hardcode keys.\n4. Use `lookup` first for simple \"what is this\" entity questions when a Baike definition is likely enough.\n5. Use `fast` for one-shot source discovery, `normal` for ordinary Q&A, and `deep` only when the user asks for breadth or coverage remains weak.\n6. Use `scripts/plan_queries.py` only to inspect or manually edit the query plan.\n7. Use `scripts/run_search_plan.py` only when the user explicitly wants every planned query run.\n8. Build or refresh packs with `scripts/dedupe_results.py` and `scripts/build_research_pack.py` when needed.\n9. Report query count, raw result count, deduped source count, major domains, coverage gaps, and recommended next steps from `research_pack.md`.\n10. When reporting factual findings, cite `source_id` plus URL or domain from `research_pack.md`; for lookup, cite Baike lemma URL or ID from `lookup_pack.md`.\n\n## Modes\n\n- `lookup`: uses Baidu Baike candidate and content APIs; usually 1-2 API calls; best for entity definitions and disambiguation.\n- `fast`: runs 1 query, `top_k=10`, and defaults to Baidu `lite` search edition; quick low-cost source discovery.\n- `normal`: starts with 3 queries, plans up to 12 diverse queries, `top_k=20`; default for ordinary Q&A.\n- `deep`: starts with 5 queries, `top_k=30`; may add result-driven expansion terms.\n\nDo not jump to `deep` by default. Increase budget only when the user asks for depth or the first pass leaves clear coverage gaps.\n\n## Commands\n\nCreate a query plan:\n\n```bash\npython \"{baseDir}/scripts/plan_queries.py\" --topic \"新能源汽车 口碑\" --mode normal --output runs/ev-reputation/query_plan.json\n```\n\nInspect the Baidu API payload without calling the API:\n\n```bash\npython \"{baseDir}/scripts/baidu_web_search.py\" --query \"新能源汽车 口碑\" --top-k 50 --dry-run\n```\n\nRun a lightweight Baike lookup:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"量子计算\" --mode lookup\n```\n\nRun lookup and fall back to one lite web search only if Baike has no candidate:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"某个新产品名称\" --mode lookup --fallback-search\n```\n\nRun adaptively after `BAIDU_AI_SEARCH_API_KEYS` is set:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal\n```\n\nLimit web results to recent pages when the user asks for recent/latest information:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal --freshness year --no-cache\n```\n\nForce a fresh live API run when the user asks for latest/current information:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal --no-cache\n```\n\nRun a fuller fixed-budget pass only when the user asks for broad coverage or exhaustive testing:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode deep --fixed --top-k 50\n```\n\nRun every query in a plan only when explicitly needed:\n\n```bash\npython \"{baseDir}/scripts/run_search_plan.py\" --plan runs/ev-reputation/query_plan.json --out-dir runs/ev-reputation --top-k 50\n```\n\nDeduplicate:\n\n```bash\npython \"{baseDir}/scripts/dedupe_results.py\" --input runs/ev-reputation/raw_results.jsonl --output runs/ev-reputation/deduped_sources.json\n```\n\nBuild a research pack:\n\n```bash\npython \"{baseDir}/scripts/build_research_pack.py\" --run-dir runs/ev-reputation --output runs/ev-reputation/research_pack.md\n```\n\n## References\n\n- Read `references/baidu-api.md` before changing request/auth logic.\n- Read `references/baike-api.md` before changing Baike lookup logic.\n- Read `references/query-planning.md` before changing query expansion.\n- Read `references/dedupe-policy.md` before changing dedupe behavior.\n- Read `references/output-schema.md` before changing output files.\n- Read `references/operations.md` for key-pool, rate-limit, and run-directory behavior.\n- Read `references/search-strategy.md` before changing adaptive stop conditions.\n\n## Rules\n\n- Never write API keys into files, git, logs, or responses.\n- Never print or echo key environment variables. If you need to check readiness, use a boolean check such as `python -c \"import os; raise SystemExit(0 if os.getenv('BAIDU_AI_SEARCH_API_KEYS') else 1)\"` or run `scripts/search.py` and let it report missing configuration.\n- Treat multiple keys as reliability/quota isolation, not as pagination for one query.\n- Use the query cache to avoid repeated identical calls; bypass it with `--no-cache` for latest/current topics.\n- Never discard raw results when deduplicating; keep duplicate mappings.\n- Prefer fixed templates plus result-driven expansion over unconstrained AI guessing.\n- Require citations for substantive claims: use source IDs, URLs, or domains from `research_pack.md`.\n- Keep query plans diverse: include official and platform-specific queries early enough for normal mode.\n- Spend search budget in stages: seed query first, coverage queries second, result expansion last.\n- Stop when required intent coverage has been attempted and additional queries have low unique-source yield unless the user explicitly requests exhaustive search.\n- Do not use Baidu video search, image search, SecondKnow video, Aladdin, or intelligent search generation by default. This skill is a source retrieval tool, not a generated-answer wrapper.\n\n## Agent Handoff\n\nFor another agent, the safest default command is:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"<topic>\" --mode normal\n```\n\nFor simple entity definitions, use:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"<topic>\" --mode lookup\n```\n\nRead `run_summary.json` first. For lookup runs, read `lookup_pack.md`; for web runs, read the `Coverage Decision` section in `research_pack.md`, then inspect `raw_results.jsonl` only when raw evidence is needed.\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn702h51bcntppmj04vwcpqzn982ptk8\",\n  \"slug\": \"baidu-api-search\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1778946488320\n}\n\nFile v1.0.1:references/baidu-api.md\n\n# Baidu AI Search API Notes\n\nUse this reference before changing request/auth behavior.\n\n## Endpoint\n\n```text\nPOST https://qianfan.baidubce.com/v2/ai_search/web_search\n```\n\nThis skill targets the web search endpoint because it returns raw-ish `references` suitable for downstream AI analysis. Do not replace it with generated answer endpoints when the user asks for original information.\n\n## Request Shape\n\nThe current script builds this payload:\n\n```json\n{\n  \"messages\": [{\"role\": \"user\", \"content\": \"新能源汽车 口碑\"}],\n  \"search_source\": \"baidu_search_v2\",\n  \"resource_type_filter\": [{\"type\": \"web\", \"top_k\": 50}]\n}\n```\n\nFor low-latency discovery, `fast` mode may add:\n\n```json\n{\n  \"edition\": \"lite\"\n}\n```\n\n`lite` reduces recall/reranking depth for better latency. Use `standard` for normal and deep research.\n\nOptional filters:\n\n```json\n{\n  \"search_filter\": {\n    \"match\": {\n      \"site\": [\"example.com\"]\n    },\n    \"items\": {\n      \"block_websites\": [\"spam.example\"]\n    }\n  },\n  \"search_recency_filter\": \"year\"\n}\n```\n\n`search_recency_filter` accepts `week`, `month`, `semiyear`, or `year`. The exact advanced filter grammar should be verified with live API testing before relying on site or block filters. Basic `messages`, `search_source`, `resource_type_filter`, and optional `edition` are the core contract.\n\n## Authentication\n\nDo not hardcode keys. Use:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nThe script can send both:\n\n```text\nAuthorization: Bearer <key>\nX-Appbuilder-Authorization: Bearer <key>\n```\n\nIf live testing shows only one header is accepted, use `--auth-header authorization` or `--auth-header x-appbuilder`.\n\n## Limits\n\n- `top_k` is clamped to 50.\n- `edition` can be `standard` or `lite`; `standard` remains the default for research.\n- There is no known offset/page/next-token for `web_search`.\n- Multiple keys should not be treated as pagination for the same query.\n- Repeated identical calls should use the local query cache unless the task requires current/latest results.\n\n## Expected Response\n\nThe response should expose `references` either at the top level or under `data.references`. The scripts accept both.\n\nUseful fields:\n\n```text\ntitle\nurl\ndate\ncontent\nsnippet\nwebsite\ntype\nmarkdown_text\nrerank_score\nauthority_score\n```\n\n## Live Testing Checklist\n\nWhen an API key is available:\n\n1. Run `baidu_web_search.py --query \"新能源汽车 口碑\" --top-k 10 --output smoke.json`.\n2. Confirm the response contains `references`.\n3. Run `run_search_plan.py` with a tiny 2-query plan.\n4. Confirm `raw_results.jsonl` has one reference per line.\n5. Confirm no key is printed in logs.\n\n## Cache Safety\n\nThe cache stores endpoint, payload, raw API response, and timestamp. It must not store API keys, Authorization headers, or full key identifiers. Cached responses should use `key_id: \"cache\"` in downstream raw results.\n\nFile v1.0.1:references/baike-api.md\n\n# Baidu Baike API Notes\n\nUse this reference before changing lightweight entity lookup behavior.\n\n## Purpose\n\nBaike lookup is a low-budget path for simple entity questions such as:\n\n```text\n这是什么？\n量子计算是什么？\n某个产品/机构/地点有没有百科词条？\n```\n\nIt is not a substitute for web research, recent news, reviews, complaints, or forum discussion.\n\n## Candidate List\n\n```text\nGET https://appbuilder.baidu.com/v2/baike/lemma/get_list_by_title\n```\n\nQuery parameters:\n\n```text\nlemma_title=<term>\ntop_k=1..100\n```\n\nExpected useful fields:\n\n```text\nlemma_id\nlemma_title\nlemma_desc\nis_default\nurl\n```\n\nUse this first when the term may be ambiguous.\n\n## Content Lookup\n\n```text\nGET https://appbuilder.baidu.com/v2/baike/lemma/get_content\n```\n\nQuery parameters:\n\n```text\nsearch_type=lemmaTitle|lemmaId\nsearch_key=<title-or-id>\n```\n\nPrefer `lemmaId` when the candidate list returned an ID.\n\nExpected useful fields:\n\n```text\nlemma_id\nlemma_title\nlemma_desc\nurl\nsummary\nabstract_plain\nabstract_html\nabstract_structured\npic_url\nsquare_pic_url\nrelations\n```\n\n## Authentication\n\nUse the same key environment as web search:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nNever write or print the full key. `lookup.py` defaults to the official Baike header:\n\n```text\nAuthorization: Bearer <key>\n```\n\nIt can also send these when compatibility testing requires it:\n\n```text\nX-Appbuilder-Authorization: Bearer <key>\n```\n\nUse `--auth-header both` or `--auth-header x-appbuilder` only if live testing shows the default `Authorization` header is not accepted in a specific environment.\n\n## Response Compatibility\n\nThe official docs describe a `result` array for candidate lists, while the success example shows a top-level array. `lookup.py` normalizes both shapes into:\n\n```json\n{\"result\": [...]}\n```\n\n## Cache\n\nBaike lookup uses `cache/baike` by default. The cache stores URL, response, and timestamp only. It must not store Authorization headers or keys.\n\nBypass cache with:\n\n```bash\npython scripts/search.py \"<topic>\" --mode lookup --no-cache\n```\n\n## Output\n\nLookup runs write:\n\n```text\nbaike_candidates.json\nbaike_content.json\nfallback_web_results.json\nerrors.jsonl\nrun_summary.json\nlookup_pack.md\n```\n\nUse `lookup_pack.md` for agent-readable output. Use JSON files for exact raw response inspection.\n\n## Excluded APIs\n\nDo not add these to the default path:\n\n- SecondKnow video\n- image or video search\n- Aladdin beta cards\n- intelligent search generation / generated-answer endpoints\n\nThese either do not serve the text-first search-tool goal or add a generated summary layer that conflicts with preserving source evidence.\n\nFile v1.0.1:references/dedupe-policy.md\n\n# Dedupe Policy\n\nUse this reference before changing dedupe behavior.\n\n## Principle\n\nDeduplication must not destroy evidence. Keep raw results and write duplicate mappings.\n\n## URL Canonicalization\n\nNormalize:\n\n```text\nscheme\nhost case\nmobile host prefix m.\ntrailing slash\ntracking params such as utm_*, from, spm, share, source\nfragment removal\n```\n\nKeep:\n\n```text\noriginal_url\ncanonical_url\nquery\nrank\n```\n\n## Title and Summary Similarity\n\nClean text by:\n\n```text\nlower/casefold\nremove whitespace and punctuation noise\nremove common source suffixes\n```\n\nDefault thresholds:\n\n```text\ntitle_similarity >= 0.92\nsummary_similarity >= 0.94\n```\n\nThese thresholds are conservative for v1. If they remove too much, lower their influence or mark near-duplicates without dropping them from selected sources.\n\n## Quality Flags\n\nCurrent v1 flags:\n\n```text\npossible_ad_or_low_quality\ndeep_subdomain\nmissing_url\ndomain_limit_overflow\n```\n\nDo not treat these as final truth. They are signals for ranking and human/agent review.\n\n## Domain Distribution\n\nDefault `--domain-limit 8` flags overflow from a single domain. It does not delete the source by default.\n\nOfficial, primary, or high-authority domains may deserve a higher cap. SEO aggregators and mirrors should receive lower priority.\n\nFile v1.0.1:references/operations.md\n\n# Operations\n\nUse this reference for key pool, rate limit, and run behavior.\n\n## Key Pool\n\nSet keys in the environment:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nAllowed uses:\n\n```text\nfailover\nquota isolation\nlegal rate limiting\nseparating dev/test/prod usage\n```\n\nDo not describe the key pool as a way to bypass official limits.\n\n## Rate Limit Defaults\n\nPrefer `adaptive_search.py`; it uses mode-specific budgets and stops early when marginal value drops.\n\nAdaptive stop conditions are coverage-aware. Normal/deep runs should attempt required intent coverage before stopping on low yield or the raw-result soft cap. This keeps high `top_k` runs from returning only seed-query results.\n\n`run_search_plan.py` is the fixed-budget fallback and defaults to:\n\n```text\n--sleep 0.5\n--timeout 30\n```\n\nFor real usage, increase sleep if errors, throttling, or unstable responses appear.\n\n## Adaptive Defaults\n\n```text\nfast:   runs 1 query, top_k=10\nnormal: starts with 3 queries, plans up to 12 diverse queries, top_k=20\ndeep:   starts with 5 queries, top_k=30 and up to 5 expansion terms\n```\n\nUse:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal\n```\n\nUse `--dry-run` to inspect planned budget without calling the API.\n\nUse `--fixed --top-k 50` only when the user explicitly wants broad/exhaustive coverage or when testing the Skill:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode deep --fixed --top-k 50\n```\n\nIf `--out-dir` is omitted, output is written under:\n\n```text\nskill/runs/<timestamp>-<process-id>-<mode>-<topic>\n```\n\nThe timestamp includes microseconds and the process ID to avoid collisions when several agents or dry-runs start in the same second.\n\n## API Testing Without a Key\n\nUse:\n\n```bash\npython scripts/baidu_web_search.py --query \"新能源汽车 口碑\" --top-k 50 --dry-run\n```\n\nThis prints endpoint and payload only.\n\n## API Testing With a Key\n\nUse a small smoke test first:\n\n```bash\nset BAIDU_AI_SEARCH_API_KEYS=...\npython scripts/baidu_web_search.py --query \"新能源汽车 口碑\" --top-k 10 --output smoke.json\n```\n\nThen run a 2-query plan before running deep mode.\n\n## Caching\n\nAdaptive and fixed plan runs use a query-level cache by default under:\n\n```text\nskill/cache/web_search\n```\n\nThe cache is keyed by:\n\n```text\nendpoint\nquery\ntop_k\nfreshness\ninclude_domains\nblock_domains\n```\n\nThe cache stores request payloads and raw API responses. It never stores API keys. Cached responses are marked with `key_id: \"cache\"` and `cache_hit: true`.\n\nDefault TTL is 24 hours:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal --cache-ttl 86400\n```\n\nForce live API calls for latest/current questions:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal --no-cache\n```\n\nCache should not hide raw API failures; failed calls are not cached.\n\n## File Hygiene\n\nFor draft usage, write runs under the skill folder or a user-specified run directory. Do not scatter temporary outputs across Desktop or home.\n\nFile v1.0.1:references/output-schema.md\n\n# Output Schema\n\nUse this reference before changing output files.\n\n## Run Directory\n\nRecommended web research shape:\n\n```text\nruns/<topic-or-run-id>/\n├── query_plan.json\n├── raw_results.jsonl\n├── errors.jsonl\n├── run_summary.json\n├── deduped_sources.json\n├── adaptive_trace.json\n└── research_pack.md\n```\n\nRecommended lookup shape:\n\n```text\nruns/<topic-or-run-id>/\n├── baike_candidates.json\n├── baike_content.json\n├── fallback_web_results.json\n├── errors.jsonl\n├── run_summary.json\n└── lookup_pack.md\n```\n\n## query_plan.json\n\n```json\n{\n  \"topic\": \"新能源汽车 口碑\",\n  \"mode\": \"normal\",\n  \"profile\": \"product\",\n  \"max_queries\": 10,\n  \"queries\": [\n    {\n      \"query\": \"新能源汽车 口碑 评测\",\n      \"intent\": \"review\",\n      \"source\": \"template\",\n      \"reason\": \"reviews and evaluations\"\n    }\n  ]\n}\n```\n\n## raw_results.jsonl\n\nOne search result reference per line:\n\n```json\n{\n  \"topic\": \"新能源汽车 口碑\",\n  \"mode\": \"normal\",\n  \"query\": \"新能源汽车 口碑 评测\",\n  \"query_intent\": \"review\",\n  \"query_source\": \"template\",\n  \"rank\": 1,\n  \"title\": \"...\",\n  \"url\": \"...\",\n  \"snippet\": \"...\",\n  \"content\": \"...\",\n  \"website\": \"...\",\n  \"date\": \"...\",\n  \"rerank_score\": 0.0,\n  \"authority_score\": 0.0,\n  \"key_id\": \"sha256-prefix\"\n}\n```\n\nNever write the full API key. `key_id` is a hash prefix only.\n\n## deduped_sources.json\n\n```json\n{\n  \"summary\": {\n    \"raw_count\": 100,\n    \"deduped_count\": 63,\n    \"duplicate_count\": 37,\n    \"domain_count\": 28\n  },\n  \"sources\": [\n    {\n      \"source_id\": \"src_0001\",\n      \"title\": \"...\",\n      \"url\": \"...\",\n      \"canonical_url\": \"...\",\n      \"domain\": \"...\",\n      \"snippet\": \"...\",\n      \"best_rank\": 1,\n      \"matched_queries\": [\"新能源汽车 口碑\", \"新能源汽车 口碑 评测\"],\n      \"matched_intents\": [\"overview\", \"review\"],\n      \"matched_stages\": [\"seed\"],\n      \"matched_query_sources\": [\"template\"],\n      \"duplicate_count\": 2,\n      \"quality_flags\": []\n    }\n  ],\n  \"duplicates\": [\n    {\n      \"kept_source_id\": \"src_0001\",\n      \"reason\": \"duplicate_url\",\n      \"query\": \"新能源汽车 口碑 评测\",\n      \"rank\": 3,\n      \"url\": \"...\"\n    }\n  ]\n}\n```\n\n## research_pack.md\n\nA compact Markdown pack for downstream AI analysis. It should include:\n\n```text\nsearch coverage\ncoverage decision and recommended next steps\nquery plan\nmajor domains\nintent coverage\nselected sources\nduplicate note\nlimitations\n```\n\nAgents should cite `source_id` plus URL or domain for factual claims derived from selected sources. The pack is a source pack, not a license to make uncited assertions.\n\n## adaptive_trace.json\n\nWritten by `adaptive_search.py`:\n\n```json\n{\n  \"summary\": {\n      \"query_count\": 3,\n      \"raw_result_count\": 60,\n      \"deduped_count\": 44,\n      \"error_count\": 0,\n      \"cache_hit_count\": 0,\n      \"cache_enabled\": true,\n      \"cache_dir\": \"cache/web_search\",\n      \"cache_ttl\": 86400,\n      \"required_intents\": [\"official\", \"overview\", \"platform\", \"review\"],\n      \"attempted_intents\": [\"official\", \"overview\", \"platform\", \"review\"],\n      \"missing_required_intents\": [],\n      \"stop_reason\": \"low_unique_yield\"\n  },\n  \"trace\": [\n    {\n      \"query\": \"新能源汽车 口碑 评测\",\n      \"intent\": \"review\",\n      \"stage\": \"seed\",\n      \"reference_count\": 20,\n      \"new_unique_count\": 18,\n      \"unique_yield\": 0.9,\n      \"cache_hit\": false\n    }\n  ]\n}\n```\n\n## lookup run_summary.json\n\nWritten by `lookup.py`:\n\n```json\n{\n  \"topic\": \"量子计算\",\n  \"mode\": \"lookup\",\n  \"candidate_count\": 5,\n  \"content_count\": 1,\n  \"fallback_search_used\": false,\n  \"fallback_result_count\": 0,\n  \"error_count\": 0,\n  \"cache_hit_count\": 0,\n  \"cache_enabled\": true,\n  \"cache_dir\": \"cache/baike\",\n  \"cache_ttl\": 86400,\n  \"lookup_pack\": \"runs/.../lookup_pack.md\"\n}\n```\n\n## lookup_pack.md\n\nA compact Markdown pack for entity lookup. It should include:\n\n```text\nsummary\nBaike candidates\nBaike content\noptional fallback web results\nlimitations\n```\n\nAgents should cite the Baike lemma URL or lemma ID for factual claims from lookup output.\n\nFile v1.0.1:references/query-planning.md\n\n# Query Planning\n\nUse this reference before changing query expansion behavior.\n\n## Principle\n\nDo not rely on free-form AI guessing alone. Use a priority-ordered query plan:\n\n```text\nseed templates\n-> coverage templates\n-> platform templates\n-> optional AI/user expansions\n-> result-driven second pass\n-> coverage feedback\n```\n\n## Modes\n\n```text\nfast:\n  1 query\n  low-cost discovery\n\nnormal:\n  5-12 queries\n  default mode\n\ndeep:\n  10-30 queries\n  add second-pass terms when available\n```\n\nThe planner assigns every query an `intent`, `stage`, and `priority`. It must select by diversity slots first, then fill remaining slots by priority. Do not simply append templates and truncate; that wastes calls on similar intents while missing official/platform/complaint coverage.\n\n## Template Classes\n\nBase queries cover:\n\n```text\noverview\nreview\ncomplaint\nprice\nexperience\nforum\nplatform\ncomparison\nservice\n```\n\nHigh-priority default order:\n\n```text\noverview\nreview\ncomplaint\nofficial\nplatform-specific sources early enough for normal mode\nexperience / owner reports\nquality\nprice\nforum\ncomparison\n```\n\nProduct-like topics add:\n\n```text\nowner reports\nfuel/range/specs\nused market\nmaintenance\nquality/common defects\n```\n\nEvent-like topics add:\n\n```text\nlatest\ntimeline\nofficial notice\nfollow-up\ncontroversy\ncause/impact\n```\n\nProject/API-like topics add:\n\n```text\nofficial docs\nGitHub\nissues\nbugs\nalternatives\ntutorials\n```\n\n## Result-Driven Expansion\n\nAfter a first pass, extract terms from titles/snippets:\n\n```text\nentities\ncompetitors\nplatform names\nfailure words\norganization names\nmodel/version names\nregions\n```\n\nThen create second-pass queries:\n\n```text\n{topic} {new_entity}\n{topic} {new_issue}\n{topic} {competitor} 对比\n{topic} {platform}\n```\n\nThe v1 script accepts `--extra-terms` as a JSON list. Later versions can add automatic term extraction.\n\n`adaptive_search.py` already performs lightweight term extraction in deep mode and inserts a small number of result-driven expansion queries.\n\n## Coverage Feedback\n\nStop expanding a query family when the unique URL yield drops below roughly 20%. Add targeted queries when an intent is missing, for example no official source, no complaints, or no forum source.\n\nFile v1.0.1:references/search-strategy.md\n\n# Search Strategy\n\nUse this reference before changing adaptive search behavior.\n\n## Design Goal\n\nFollow the same broad pattern as mature tool-using search agents:\n\n```text\nstart with a small search\ninspect sources\nexpand only when needed\npreserve all sources\nstop when marginal value drops\n```\n\nThe goal is not to maximize API calls. The goal is to maximize useful unique sources per call.\n\n## Default Budgets\n\n```text\nfast:\n  initial_queries: 1\n  planned_query_limit: 1\n  top_k: 10\n  second_pass_terms: 0\n\nnormal:\n  initial_queries: 3\n  planned_query_limit: 12\n  top_k: 20\n  second_pass_terms: 0\n\ndeep:\n  initial_queries: 5\n  top_k: 30\n  second_pass_terms: 5\n```\n\nUse `run_search_plan.py --top-k 50` only when the user wants a fixed, exhaustive run or when smoke testing the known Baidu `top_k=50` ceiling.\n\nThe preferred fixed-budget command is:\n\n```bash\npython scripts/adaptive_search.py --topic \"<topic>\" --mode deep --fixed --top-k 50\n```\n\nThis still writes the same `run_summary.json`, `adaptive_trace.json`, `deduped_sources.json`, and `research_pack.md`.\n\n## Stop Conditions\n\nAdaptive search should stop after the initial stage when:\n\n```text\nrequired intent coverage has been attempted\nand\nraw_result_count >= max_raw_results\nor\nnew_unique_sources / returned_references < min_unique_yield for low_yield_patience queries\n```\n\nDefault unique-yield thresholds:\n\n```text\nfast: 0.35\nnormal: 0.25\ndeep: 0.18\n```\n\nThese are intentionally conservative. If users complain about missing coverage, lower the threshold or increase patience.\n\n`max_raw_results` is a soft cap until required intent coverage has been attempted. For normal product searches, required coverage includes overview, review, complaint, official, platform, and experience. This prevents a high `top_k` run from stopping before official/platform queries.\n\n## Expansion Order\n\nUse this order:\n\n1. Seed queries: core topic, review, complaint.\n2. Official and platform queries: official source, Zhihu, Tieba, Xiaohongshu, Bilibili, Weibo.\n3. Coverage queries: owner/user reports, quality, price, forum/comparison.\n4. Result-driven terms: only in deep mode by default.\n\n## Reporting\n\nAlways report:\n\n```text\nqueries run\nraw result count\ndeduped source count\nduplicate count\nstop reason\ntop domains\nknown gaps\n```\n\nFile v1.0.1:agents/openai.yaml\n\ninterface:\n  display_name: \"Baidu API Search\"\n  short_description: \"Default Chinese web search source pack\"\n  default_prompt: \"Use $baidu-api-search instead of generic web_search for Chinese 查一下, 搜索, 最近, 最新, or 热点 tasks. Look up simple entities with Baidu Baike, or investigate Chinese web topics while preserving raw sources, deduplicating results, and building a research pack.\"\n\nArchive v1.0.0: 18 files, 38163 bytes\n\nFiles: agents/openai.yaml (401b), references/baidu-api.md (2862b), references/baike-api.md (2648b), references/dedupe-policy.md (1277b), references/operations.md (3007b), references/output-schema.md (4080b), references/query-planning.md (2212b), references/search-strategy.md (2278b), scripts/adaptive_search.py (16352b), scripts/baidu_web_search.py (8941b), scripts/build_research_pack.py (8704b), scripts/dedupe_results.py (8469b), scripts/lookup.py (17380b), scripts/plan_queries.py (11617b), scripts/run_search_plan.py (5338b), scripts/search.py (1144b), SKILL.md (7128b), _meta.json (135b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: baidu-ai-search\ndescription: Use this instead of generic web_search when the user asks in Chinese to 查一下, 搜索, 联网查, 查热点, 查最近/最新, or gather Chinese web sources. Provides Baidu Baike lookup, Baidu AI Search API web search, raw Baidu results, dedupe, safe API key handling, and research packs.\nversion: 1.0.0\nhomepage: https://github.com/valenovo/baidu-search-skill\nmetadata: {\"openclaw\":{\"requires\":{\"env\":[\"BAIDU_AI_SEARCH_API_KEYS\"],\"anyBins\":[\"python3\",\"python\"]},\"primaryEnv\":\"BAIDU_AI_SEARCH_API_KEYS\",\"envVars\":[{\"name\":\"BAIDU_AI_SEARCH_API_KEYS\",\"required\":true,\"description\":\"Baidu AI Search / AppBuilder API key list. Use comma-separated keys for failover and quota isolation.\"}],\"homepage\":\"https://github.com/valenovo/baidu-search-skill\"}}\n---\n\n# Baidu AI Search\n\nUse this skill to turn Baidu Baike lookup and Baidu AI Search API into an agent-friendly Chinese information retrieval pipeline. Prefer it over generic `web_search` for Chinese \"查一下/搜索/联网查/最近/最新/热点\" requests. The goal is to preserve raw sources for AI analysis, not to replace raw evidence with a generated summary.\n\n## Workflow\n\n1. Choose mode: `lookup`, `fast`, `normal`, or `deep`.\n2. Prefer the single-entry command `{baseDir}/scripts/search.py`; it routes `lookup` to Baidu Baike and routes web modes to adaptive search.\n3. For real searches, require `BAIDU_AI_SEARCH_API_KEYS`; do not hardcode keys.\n4. Use `lookup` first for simple \"what is this\" entity questions when a Baike definition is likely enough.\n5. Use `fast` for one-shot source discovery, `normal` for ordinary Q&A, and `deep` only when the user asks for breadth or coverage remains weak.\n6. Use `scripts/plan_queries.py` only to inspect or manually edit the query plan.\n7. Use `scripts/run_search_plan.py` only when the user explicitly wants every planned query run.\n8. Build or refresh packs with `scripts/dedupe_results.py` and `scripts/build_research_pack.py` when needed.\n9. Report query count, raw result count, deduped source count, major domains, coverage gaps, and recommended next steps from `research_pack.md`.\n10. When reporting factual findings, cite `source_id` plus URL or domain from `research_pack.md`; for lookup, cite Baike lemma URL or ID from `lookup_pack.md`.\n\n## Modes\n\n- `lookup`: uses Baidu Baike candidate and content APIs; usually 1-2 API calls; best for entity definitions and disambiguation.\n- `fast`: runs 1 query, `top_k=10`, and defaults to Baidu `lite` search edition; quick low-cost source discovery.\n- `normal`: starts with 3 queries, plans up to 12 diverse queries, `top_k=20`; default for ordinary Q&A.\n- `deep`: starts with 5 queries, `top_k=30`; may add result-driven expansion terms.\n\nDo not jump to `deep` by default. Increase budget only when the user asks for depth or the first pass leaves clear coverage gaps.\n\n## Commands\n\nCreate a query plan:\n\n```bash\npython \"{baseDir}/scripts/plan_queries.py\" --topic \"新能源汽车 口碑\" --mode normal --output runs/ev-reputation/query_plan.json\n```\n\nInspect the Baidu API payload without calling the API:\n\n```bash\npython \"{baseDir}/scripts/baidu_web_search.py\" --query \"新能源汽车 口碑\" --top-k 50 --dry-run\n```\n\nRun a lightweight Baike lookup:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"量子计算\" --mode lookup\n```\n\nRun lookup and fall back to one lite web search only if Baike has no candidate:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"某个新产品名称\" --mode lookup --fallback-search\n```\n\nRun adaptively after `BAIDU_AI_SEARCH_API_KEYS` is set:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal\n```\n\nLimit web results to recent pages when the user asks for recent/latest information:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal --freshness year --no-cache\n```\n\nForce a fresh live API run when the user asks for latest/current information:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal --no-cache\n```\n\nRun a fuller fixed-budget pass only when the user asks for broad coverage or exhaustive testing:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode deep --fixed --top-k 50\n```\n\nRun every query in a plan only when explicitly needed:\n\n```bash\npython \"{baseDir}/scripts/run_search_plan.py\" --plan runs/ev-reputation/query_plan.json --out-dir runs/ev-reputation --top-k 50\n```\n\nDeduplicate:\n\n```bash\npython \"{baseDir}/scripts/dedupe_results.py\" --input runs/ev-reputation/raw_results.jsonl --output runs/ev-reputation/deduped_sources.json\n```\n\nBuild a research pack:\n\n```bash\npython \"{baseDir}/scripts/build_research_pack.py\" --run-dir runs/ev-reputation --output runs/ev-reputation/research_pack.md\n```\n\n## References\n\n- Read `references/baidu-api.md` before changing request/auth logic.\n- Read `references/baike-api.md` before changing Baike lookup logic.\n- Read `references/query-planning.md` before changing query expansion.\n- Read `references/dedupe-policy.md` before changing dedupe behavior.\n- Read `references/output-schema.md` before changing output files.\n- Read `references/operations.md` for key-pool, rate-limit, and run-directory behavior.\n- Read `references/search-strategy.md` before changing adaptive stop conditions.\n\n## Rules\n\n- Never write API keys into files, git, logs, or responses.\n- Never print or echo key environment variables. If you need to check readiness, use a boolean check such as `python -c \"import os; raise SystemExit(0 if os.getenv('BAIDU_AI_SEARCH_API_KEYS') else 1)\"` or run `scripts/search.py` and let it report missing configuration.\n- Treat multiple keys as reliability/quota isolation, not as pagination for one query.\n- Use the query cache to avoid repeated identical calls; bypass it with `--no-cache` for latest/current topics.\n- Never discard raw results when deduplicating; keep duplicate mappings.\n- Prefer fixed templates plus result-driven expansion over unconstrained AI guessing.\n- Require citations for substantive claims: use source IDs, URLs, or domains from `research_pack.md`.\n- Keep query plans diverse: include official and platform-specific queries early enough for normal mode.\n- Spend search budget in stages: seed query first, coverage queries second, result expansion last.\n- Stop when required intent coverage has been attempted and additional queries have low unique-source yield unless the user explicitly requests exhaustive search.\n- Do not use Baidu video search, image search, SecondKnow video, Aladdin, or intelligent search generation by default. This skill is a source retrieval tool, not a generated-answer wrapper.\n\n## Agent Handoff\n\nFor another agent, the safest default command is:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"<topic>\" --mode normal\n```\n\nFor simple entity definitions, use:\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"<topic>\" --mode lookup\n```\n\nRead `run_summary.json` first. For lookup runs, read `lookup_pack.md`; for web runs, read the `Coverage Decision` section in `research_pack.md`, then inspect `raw_results.jsonl` only when raw evidence is needed.\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn702h51bcntppmj04vwcpqzn982ptk8\",\n  \"slug\": \"baidu-api-search\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1778946309855\n}\n\nFile v1.0.0:references/baidu-api.md\n\n# Baidu AI Search API Notes\n\nUse this reference before changing request/auth behavior.\n\n## Endpoint\n\n```text\nPOST https://qianfan.baidubce.com/v2/ai_search/web_search\n```\n\nThis skill targets the web search endpoint because it returns raw-ish `references` suitable for downstream AI analysis. Do not replace it with generated answer endpoints when the user asks for original information.\n\n## Request Shape\n\nThe current script builds this payload:\n\n```json\n{\n  \"messages\": [{\"role\": \"user\", \"content\": \"新能源汽车 口碑\"}],\n  \"search_source\": \"baidu_search_v2\",\n  \"resource_type_filter\": [{\"type\": \"web\", \"top_k\": 50}]\n}\n```\n\nFor low-latency discovery, `fast` mode may add:\n\n```json\n{\n  \"edition\": \"lite\"\n}\n```\n\n`lite` reduces recall/reranking depth for better latency. Use `standard` for normal and deep research.\n\nOptional filters:\n\n```json\n{\n  \"search_filter\": {\n    \"match\": {\n      \"site\": [\"example.com\"]\n    },\n    \"items\": {\n      \"block_websites\": [\"spam.example\"]\n    }\n  },\n  \"search_recency_filter\": \"year\"\n}\n```\n\n`search_recency_filter` accepts `week`, `month`, `semiyear`, or `year`. The exact advanced filter grammar should be verified with live API testing before relying on site or block filters. Basic `messages`, `search_source`, `resource_type_filter`, and optional `edition` are the core contract.\n\n## Authentication\n\nDo not hardcode keys. Use:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nThe script can send both:\n\n```text\nAuthorization: Bearer <key>\nX-Appbuilder-Authorization: Bearer <key>\n```\n\nIf live testing shows only one header is accepted, use `--auth-header authorization` or `--auth-header x-appbuilder`.\n\n## Limits\n\n- `top_k` is clamped to 50.\n- `edition` can be `standard` or `lite`; `standard` remains the default for research.\n- There is no known offset/page/next-token for `web_search`.\n- Multiple keys should not be treated as pagination for the same query.\n- Repeated identical calls should use the local query cache unless the task requires current/latest results.\n\n## Expected Response\n\nThe response should expose `references` either at the top level or under `data.references`. The scripts accept both.\n\nUseful fields:\n\n```text\ntitle\nurl\ndate\ncontent\nsnippet\nwebsite\ntype\nmarkdown_text\nrerank_score\nauthority_score\n```\n\n## Live Testing Checklist\n\nWhen an API key is available:\n\n1. Run `baidu_web_search.py --query \"新能源汽车 口碑\" --top-k 10 --output smoke.json`.\n2. Confirm the response contains `references`.\n3. Run `run_search_plan.py` with a tiny 2-query plan.\n4. Confirm `raw_results.jsonl` has one reference per line.\n5. Confirm no key is printed in logs.\n\n## Cache Safety\n\nThe cache stores endpoint, payload, raw API response, and timestamp. It must not store API keys, Authorization headers, or full key identifiers. Cached responses should use `key_id: \"cache\"` in downstream raw results.\n\nFile v1.0.0:references/baike-api.md\n\n# Baidu Baike API Notes\n\nUse this reference before changing lightweight entity lookup behavior.\n\n## Purpose\n\nBaike lookup is a low-budget path for simple entity questions such as:\n\n```text\n这是什么？\n量子计算是什么？\n某个产品/机构/地点有没有百科词条？\n```\n\nIt is not a substitute for web research, recent news, reviews, complaints, or forum discussion.\n\n## Candidate List\n\n```text\nGET https://appbuilder.baidu.com/v2/baike/lemma/get_list_by_title\n```\n\nQuery parameters:\n\n```text\nlemma_title=<term>\ntop_k=1..100\n```\n\nExpected useful fields:\n\n```text\nlemma_id\nlemma_title\nlemma_desc\nis_default\nurl\n```\n\nUse this first when the term may be ambiguous.\n\n## Content Lookup\n\n```text\nGET https://appbuilder.baidu.com/v2/baike/lemma/get_content\n```\n\nQuery parameters:\n\n```text\nsearch_type=lemmaTitle|lemmaId\nsearch_key=<title-or-id>\n```\n\nPrefer `lemmaId` when the candidate list returned an ID.\n\nExpected useful fields:\n\n```text\nlemma_id\nlemma_title\nlemma_desc\nurl\nsummary\nabstract_plain\nabstract_html\nabstract_structured\npic_url\nsquare_pic_url\nrelations\n```\n\n## Authentication\n\nUse the same key environment as web search:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nNever write or print the full key. `lookup.py` defaults to the official Baike header:\n\n```text\nAuthorization: Bearer <key>\n```\n\nIt can also send these when compatibility testing requires it:\n\n```text\nX-Appbuilder-Authorization: Bearer <key>\n```\n\nUse `--auth-header both` or `--auth-header x-appbuilder` only if live testing shows the default `Authorization` header is not accepted in a specific environment.\n\n## Response Compatibility\n\nThe official docs describe a `result` array for candidate lists, while the success example shows a top-level array. `lookup.py` normalizes both shapes into:\n\n```json\n{\"result\": [...]}\n```\n\n## Cache\n\nBaike lookup uses `cache/baike` by default. The cache stores URL, response, and timestamp only. It must not store Authorization headers or keys.\n\nBypass cache with:\n\n```bash\npython scripts/search.py \"<topic>\" --mode lookup --no-cache\n```\n\n## Output\n\nLookup runs write:\n\n```text\nbaike_candidates.json\nbaike_content.json\nfallback_web_results.json\nerrors.jsonl\nrun_summary.json\nlookup_pack.md\n```\n\nUse `lookup_pack.md` for agent-readable output. Use JSON files for exact raw response inspection.\n\n## Excluded APIs\n\nDo not add these to the default path:\n\n- SecondKnow video\n- image or video search\n- Aladdin beta cards\n- intelligent search generation / generated-answer endpoints\n\nThese either do not serve the text-first search-tool goal or add a generated summary layer that conflicts with preserving source evidence.\n\nFile v1.0.0:references/dedupe-policy.md\n\n# Dedupe Policy\n\nUse this reference before changing dedupe behavior.\n\n## Principle\n\nDeduplication must not destroy evidence. Keep raw results and write duplicate mappings.\n\n## URL Canonicalization\n\nNormalize:\n\n```text\nscheme\nhost case\nmobile host prefix m.\ntrailing slash\ntracking params such as utm_*, from, spm, share, source\nfragment removal\n```\n\nKeep:\n\n```text\noriginal_url\ncanonical_url\nquery\nrank\n```\n\n## Title and Summary Similarity\n\nClean text by:\n\n```text\nlower/casefold\nremove whitespace and punctuation noise\nremove common source suffixes\n```\n\nDefault thresholds:\n\n```text\ntitle_similarity >= 0.92\nsummary_similarity >= 0.94\n```\n\nThese thresholds are conservative for v1. If they remove too much, lower their influence or mark near-duplicates without dropping them from selected sources.\n\n## Quality Flags\n\nCurrent v1 flags:\n\n```text\npossible_ad_or_low_quality\ndeep_subdomain\nmissing_url\ndomain_limit_overflow\n```\n\nDo not treat these as final truth. They are signals for ranking and human/agent review.\n\n## Domain Distribution\n\nDefault `--domain-limit 8` flags overflow from a single domain. It does not delete the source by default.\n\nOfficial, primary, or high-authority domains may deserve a higher cap. SEO aggregators and mirrors should receive lower priority.\n\nFile v1.0.0:references/operations.md\n\n# Operations\n\nUse this reference for key pool, rate limit, and run behavior.\n\n## Key Pool\n\nSet keys in the environment:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nAllowed uses:\n\n```text\nfailover\nquota isolation\nlegal rate limiting\nseparating dev/test/prod usage\n```\n\nDo not describe the key pool as a way to bypass official limits.\n\n## Rate Limit Defaults\n\nPrefer `adaptive_search.py`; it uses mode-specific budgets and stops early when marginal value drops.\n\nAdaptive stop conditions are coverage-aware. Normal/deep runs should attempt required intent coverage before stopping on low yield or the raw-result soft cap. This keeps high `top_k` runs from returning only seed-query results.\n\n`run_search_plan.py` is the fixed-budget fallback and defaults to:\n\n```text\n--sleep 0.5\n--timeout 30\n```\n\nFor real usage, increase sleep if errors, throttling, or unstable responses appear.\n\n## Adaptive Defaults\n\n```text\nfast:   runs 1 query, top_k=10\nnormal: starts with 3 queries, plans up to 12 diverse queries, top_k=20\ndeep:   starts with 5 queries, top_k=30 and up to 5 expansion terms\n```\n\nUse:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal\n```\n\nUse `--dry-run` to inspect planned budget without calling the API.\n\nUse `--fixed --top-k 50` only when the user explicitly wants broad/exhaustive coverage or when testing the Skill:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode deep --fixed --top-k 50\n```\n\nIf `--out-dir` is omitted, output is written under:\n\n```text\nskill/runs/<timestamp>-<process-id>-<mode>-<topic>\n```\n\nThe timestamp includes microseconds and the process ID to avoid collisions when several agents or dry-runs start in the same second.\n\n## API Testing Without a Key\n\nUse:\n\n```bash\npython scripts/baidu_web_search.py --query \"新能源汽车 口碑\" --top-k 50 --dry-run\n```\n\nThis prints endpoint and payload only.\n\n## API Testing With a Key\n\nUse a small smoke test first:\n\n```bash\nset BAIDU_AI_SEARCH_API_KEYS=...\npython scripts/baidu_web_search.py --query \"新能源汽车 口碑\" --top-k 10 --output smoke.json\n```\n\nThen run a 2-query plan before running deep mode.\n\n## Caching\n\nAdaptive and fixed plan runs use a query-level cache by default under:\n\n```text\nskill/cache/web_search\n```\n\nThe cache is keyed by:\n\n```text\nendpoint\nquery\ntop_k\nfreshness\ninclude_domains\nblock_domains\n```\n\nThe cache stores request payloads and raw API responses. It never stores API keys. Cached responses are marked with `key_id: \"cache\"` and `cache_hit: true`.\n\nDefault TTL is 24 hours:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal --cache-ttl 86400\n```\n\nForce live API calls for latest/current questions:\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal --no-cache\n```\n\nCache should not hide raw API failures; failed calls are not cached.\n\n## File Hygiene\n\nFor draft usage, write runs under the skill folder or a user-specified run directory. Do not scatter temporary outputs across Desktop or home.\n\nFile v1.0.0:references/output-schema.md\n\n# Output Schema\n\nUse this reference before changing output files.\n\n## Run Directory\n\nRecommended web research shape:\n\n```text\nruns/<topic-or-run-id>/\n├── query_plan.json\n├── raw_results.jsonl\n├── errors.jsonl\n├── run_summary.json\n├── deduped_sources.json\n├── adaptive_trace.json\n└── research_pack.md\n```\n\nRecommended lookup shape:\n\n```text\nruns/<topic-or-run-id>/\n├── baike_candidates.json\n├── baike_content.json\n├── fallback_web_results.json\n├── errors.jsonl\n├── run_summary.json\n└── lookup_pack.md\n```\n\n## query_plan.json\n\n```json\n{\n  \"topic\": \"新能源汽车 口碑\",\n  \"mode\": \"normal\",\n  \"profile\": \"product\",\n  \"max_queries\": 10,\n  \"queries\": [\n    {\n      \"query\": \"新能源汽车 口碑 评测\",\n      \"intent\": \"review\",\n      \"source\": \"template\",\n      \"reason\": \"reviews and evaluations\"\n    }\n  ]\n}\n```\n\n## raw_results.jsonl\n\nOne search result reference per line:\n\n```json\n{\n  \"topic\": \"新能源汽车 口碑\",\n  \"mode\": \"normal\",\n  \"query\": \"新能源汽车 口碑 评测\",\n  \"query_intent\": \"review\",\n  \"query_source\": \"template\",\n  \"rank\": 1,\n  \"title\": \"...\",\n  \"url\": \"...\",\n  \"snippet\": \"...\",\n  \"content\": \"...\",\n  \"website\": \"...\",\n  \"date\": \"...\",\n  \"rerank_score\": 0.0,\n  \"authority_score\": 0.0,\n  \"key_id\": \"sha256-prefix\"\n}\n```\n\nNever write the full API key. `key_id` is a hash prefix only.\n\n## deduped_sources.json\n\n```json\n{\n  \"summary\": {\n    \"raw_count\": 100,\n    \"deduped_count\": 63,\n    \"duplicate_count\": 37,\n    \"domain_count\": 28\n  },\n  \"sources\": [\n    {\n      \"source_id\": \"src_0001\",\n      \"title\": \"...\",\n      \"url\": \"...\",\n      \"canonical_url\": \"...\",\n      \"domain\": \"...\",\n      \"snippet\": \"...\",\n      \"best_rank\": 1,\n      \"matched_queries\": [\"新能源汽车 口碑\", \"新能源汽车 口碑 评测\"],\n      \"matched_intents\": [\"overview\", \"review\"],\n      \"matched_stages\": [\"seed\"],\n      \"matched_query_sources\": [\"template\"],\n      \"duplicate_count\": 2,\n      \"quality_flags\": []\n    }\n  ],\n  \"duplicates\": [\n    {\n      \"kept_source_id\": \"src_0001\",\n      \"reason\": \"duplicate_url\",\n      \"query\": \"新能源汽车 口碑 评测\",\n      \"rank\": 3,\n      \"url\": \"...\"\n    }\n  ]\n}\n```\n\n## research_pack.md\n\nA compact Markdown pack for downstream AI analysis. It should include:\n\n```text\nsearch coverage\ncoverage decision and recommended next steps\nquery plan\nmajor domains\nintent coverage\nselected sources\nduplicate note\nlimitations\n```\n\nAgents should cite `source_id` plus URL or domain for factual claims derived from selected sources. The pack is a source pack, not a license to make uncited assertions.\n\n## adaptive_trace.json\n\nWritten by `adaptive_search.py`:\n\n```json\n{\n  \"summary\": {\n      \"query_count\": 3,\n      \"raw_result_count\": 60,\n      \"deduped_count\": 44,\n      \"error_count\": 0,\n      \"cache_hit_count\": 0,\n      \"cache_enabled\": true,\n      \"cache_dir\": \"cache/web_search\",\n      \"cache_ttl\": 86400,\n      \"required_intents\": [\"official\", \"overview\", \"platform\", \"review\"],\n      \"attempted_intents\": [\"official\", \"overview\", \"platform\", \"review\"],\n      \"missing_required_intents\": [],\n      \"stop_reason\": \"low_unique_yield\"\n  },\n  \"trace\": [\n    {\n      \"query\": \"新能源汽车 口碑 评测\",\n      \"intent\": \"review\",\n      \"stage\": \"seed\",\n      \"reference_count\": 20,\n      \"new_unique_count\": 18,\n      \"unique_yield\": 0.9,\n      \"cache_hit\": false\n    }\n  ]\n}\n```\n\n## lookup run_summary.json\n\nWritten by `lookup.py`:\n\n```json\n{\n  \"topic\": \"量子计算\",\n  \"mode\": \"lookup\",\n  \"candidate_count\": 5,\n  \"content_count\": 1,\n  \"fallback_search_used\": false,\n  \"fallback_result_count\": 0,\n  \"error_count\": 0,\n  \"cache_hit_count\": 0,\n  \"cache_enabled\": true,\n  \"cache_dir\": \"cache/baike\",\n  \"cache_ttl\": 86400,\n  \"lookup_pack\": \"runs/.../lookup_pack.md\"\n}\n```\n\n## lookup_pack.md\n\nA compact Markdown pack for entity lookup. It should include:\n\n```text\nsummary\nBaike candidates\nBaike content\noptional fallback web results\nlimitations\n```\n\nAgents should cite the Baike lemma URL or lemma ID for factual claims from lookup output.\n\nFile v1.0.0:references/query-planning.md\n\n# Query Planning\n\nUse this reference before changing query expansion behavior.\n\n## Principle\n\nDo not rely on free-form AI guessing alone. Use a priority-ordered query plan:\n\n```text\nseed templates\n-> coverage templates\n-> platform templates\n-> optional AI/user expansions\n-> result-driven second pass\n-> coverage feedback\n```\n\n## Modes\n\n```text\nfast:\n  1 query\n  low-cost discovery\n\nnormal:\n  5-12 queries\n  default mode\n\ndeep:\n  10-30 queries\n  add second-pass terms when available\n```\n\nThe planner assigns every query an `intent`, `stage`, and `priority`. It must select by diversity slots first, then fill remaining slots by priority. Do not simply append templates and truncate; that wastes calls on similar intents while missing official/platform/complaint coverage.\n\n## Template Classes\n\nBase queries cover:\n\n```text\noverview\nreview\ncomplaint\nprice\nexperience\nforum\nplatform\ncomparison\nservice\n```\n\nHigh-priority default order:\n\n```text\noverview\nreview\ncomplaint\nofficial\nplatform-specific sources early enough for normal mode\nexperience / owner reports\nquality\nprice\nforum\ncomparison\n```\n\nProduct-like topics add:\n\n```text\nowner reports\nfuel/range/specs\nused market\nmaintenance\nquality/common defects\n```\n\nEvent-like topics add:\n\n```text\nlatest\ntimeline\nofficial notice\nfollow-up\ncontroversy\ncause/impact\n```\n\nProject/API-like topics add:\n\n```text\nofficial docs\nGitHub\nissues\nbugs\nalternatives\ntutorials\n```\n\n## Result-Driven Expansion\n\nAfter a first pass, extract terms from titles/snippets:\n\n```text\nentities\ncompetitors\nplatform names\nfailure words\norganization names\nmodel/version names\nregions\n```\n\nThen create second-pass queries:\n\n```text\n{topic} {new_entity}\n{topic} {new_issue}\n{topic} {competitor} 对比\n{topic} {platform}\n```\n\nThe v1 script accepts `--extra-terms` as a JSON list. Later versions can add automatic term extraction.\n\n`adaptive_search.py` already performs lightweight term extraction in deep mode and inserts a small number of result-driven expansion queries.\n\n## Coverage Feedback\n\nStop expanding a query family when the unique URL yield drops below roughly 20%. Add targeted queries when an intent is missing, for example no official source, no complaints, or no forum source.\n\nFile v1.0.0:references/search-strategy.md\n\n# Search Strategy\n\nUse this reference before changing adaptive search behavior.\n\n## Design Goal\n\nFollow the same broad pattern as mature tool-using search agents:\n\n```text\nstart with a small search\ninspect sources\nexpand only when needed\npreserve all sources\nstop when marginal value drops\n```\n\nThe goal is not to maximize API calls. The goal is to maximize useful unique sources per call.\n\n## Default Budgets\n\n```text\nfast:\n  initial_queries: 1\n  planned_query_limit: 1\n  top_k: 10\n  second_pass_terms: 0\n\nnormal:\n  initial_queries: 3\n  planned_query_limit: 12\n  top_k: 20\n  second_pass_terms: 0\n\ndeep:\n  initial_queries: 5\n  top_k: 30\n  second_pass_terms: 5\n```\n\nUse `run_search_plan.py --top-k 50` only when the user wants a fixed, exhaustive run or when smoke testing the known Baidu `top_k=50` ceiling.\n\nThe preferred fixed-budget command is:\n\n```bash\npython scripts/adaptive_search.py --topic \"<topic>\" --mode deep --fixed --top-k 50\n```\n\nThis still writes the same `run_summary.json`, `adaptive_trace.json`, `deduped_sources.json`, and `research_pack.md`.\n\n## Stop Conditions\n\nAdaptive search should stop after the initial stage when:\n\n```text\nrequired intent coverage has been attempted\nand\nraw_result_count >= max_raw_results\nor\nnew_unique_sources / returned_references < min_unique_yield for low_yield_patience queries\n```\n\nDefault unique-yield thresholds:\n\n```text\nfast: 0.35\nnormal: 0.25\ndeep: 0.18\n```\n\nThese are intentionally conservative. If users complain about missing coverage, lower the threshold or increase patience.\n\n`max_raw_results` is a soft cap until required intent coverage has been attempted. For normal product searches, required coverage includes overview, review, complaint, official, platform, and experience. This prevents a high `top_k` run from stopping before official/platform queries.\n\n## Expansion Order\n\nUse this order:\n\n1. Seed queries: core topic, review, complaint.\n2. Official and platform queries: official source, Zhihu, Tieba, Xiaohongshu, Bilibili, Weibo.\n3. Coverage queries: owner/user reports, quality, price, forum/comparison.\n4. Result-driven terms: only in deep mode by default.\n\n## Reporting\n\nAlways report:\n\n```text\nqueries run\nraw result count\ndeduped source count\nduplicate count\nstop reason\ntop domains\nknown gaps\n```\n\nFile v1.0.0:agents/openai.yaml\n\ninterface:\n  display_name: \"Baidu AI Search\"\n  short_description: \"Default Chinese web search source pack\"\n  default_prompt: \"Use $baidu-ai-search instead of generic web_search for Chinese 查一下, 搜索, 最近, 最新, or 热点 tasks. Look up simple entities with Baidu Baike, or investigate Chinese web topics while preserving raw sources, deduplicating results, and building a research pack.\"","readmeExcerpt":"Skill: Baidu API Search Owner: valenovo Summary: 面向 Agent 的中文网页来源检索包 Tags: latest:1.0.3 Version history: v1.0.3 | 2026-05-16T16:02:31.386Z | user Localize the ClawHub-facing skill description, README, and agent prompt to Chinese while keeping a separate English README. v1.0.2 | 2026-05-16T15:53:24.563Z | user Add bilingual Chinese and English documentation inside the published skill package. v1.0.1 | 2026-05-16T15:48","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"python \"{baseDir}/scripts/plan_queries.py\" --topic \"新能源汽车 口碑\" --mode normal --output runs/ev-reputation/query_plan.json"},{"language":"bash","snippet":"python \"{baseDir}/scripts/baidu_web_search.py\" --query \"新能源汽车 口碑\" --top-k 50 --dry-run"},{"language":"bash","snippet":"python \"{baseDir}/scripts/search.py\" \"量子计算\" --mode lookup"},{"language":"bash","snippet":"python \"{baseDir}/scripts/search.py\" \"某个新产品名称\" --mode lookup --fallback-search"},{"language":"bash","snippet":"python \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal"},{"language":"bash","snippet":"python \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal --freshness year --no-cache"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: baidu-api-search\ndescription: 面向 Agent 的百度 API 搜索 Skill。用于中文“查一下/搜索/联网查/最近/最新/热点”等场景，调用百度百科和百度 AI Search API，保留原始结果、去重并生成 research pack。\nversion: 1.0.3\nhomepage: https://github.com/valenovo/baidu-search-skill\nmetadata: {\"openclaw\":{\"requires\":{\"env\":[\"BAIDU_AI_SEARCH_API_KEYS\"],\"anyBins\":[\"python3\",\"python\"]},\"primaryEnv\":\"BAIDU_AI_SEARCH_API_KEYS\",\"envVars\":[{\"name\":\"BAIDU_AI_SEARCH_API_KEYS\",\"required\":true,\"description\":\"百度 AI Search / AppBuilder API Key 列表，多个 Key 用英文逗号分隔，用于失败切换和额度隔离。\"}],\"homepage\":\"https://github.com/valenovo/baidu-search-skill\"}}\n---\n\n# Baidu API Search\n\n把百度百科查询和百度 AI Search API 整理成适合 Agent 使用的中文资料检索流程。遇到中文“查一下 / 搜索 / 联网查 / 最近 / 最新 / 热点”这类请求时，优先使用本 Skill，而不是通用 `web_search`。目标是保留原始来源给 AI 分析，不是用生成式摘要替代证据。\n\n## 工作流程\n\n1. 先选择模式：`lookup`、`fast`、`normal` 或 `deep`。\n2. 默认使用统一入口 `{baseDir}/scripts/search.py`；它会把 `lookup` 路由到百度百科，把网页搜索模式路由到自适应搜索。\n3. 真实搜索必须读取 `BAIDU_AI_SEARCH_API_KEYS`，不要把 Key 写死在文件里。\n4. 简单实体问题，例如“这是什么”“这个人是谁”，优先使用 `lookup`，能用百科解决就不额外搜索网页。\n5. `fast` 用于快速找一批来源，`normal` 用于普通问答，`deep` 只在用户明确要求全面覆盖或首轮覆盖不足时使用。\n6. 只在需要查看或手动调整搜索词时使用 `scripts/plan_queries.py`。\n7. 只有用户明确要求完整跑完所有计划查询时，才使用 `scripts/run_search_plan.py`。\n8. 需要刷新结果包时，使用 `scripts/dedupe_results.py` 和 `scripts/build_research_pack.py`。\n9. 汇报时说明查询次数、原始结果数、去重后来源数、主要域名、覆盖缺口和下一步建议。\n10. 回答事实性结论时，引用 `research_pack.md` 里的 `source_id` 加 URL 或域名；百科查询引用 `lookup_pack.md` 里的词条 URL 或 ID。\n\n## 模式\n\n- `lookup`：调用百度百科候选词和内容接口，通常 1-2 次 API 调用，适合实体定义和消歧。\n- `fast`：只跑 1 个搜索词，`top_k=10`，默认使用百度 `lite` 搜索版本，适合快速发现来源。\n- `normal`：默认模式，先跑 3 个搜索词，最多规划 12 个多角度搜索词，`top_k=20`。\n- `deep`：深度模式，先跑 5 个搜索词，`top_k=30`，必要时基于已有结果继续扩展搜索词。\n\n不要默认直接使用 `deep`。只有用户要求深度覆盖，或首轮结果明显缺少关键角度时，再提高搜索预算。\n\n## 命令\n\n生成搜索词计划：\n\n```bash\npython \"{baseDir}/scripts/plan_queries.py\" --topic \"新能源汽车 口碑\" --mode normal --output runs/ev-reputation/query_plan.json\n```\n\n只检查百度 API 请求体，不真正调用接口：\n\n```bash\npython \"{baseDir}/scripts/baidu_web_search.py\" --query \"新能源汽车 口碑\" --top-k 50 --dry-run\n```\n\n运行轻量百科查询：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"量子计算\" --mode lookup\n```\n\n先查百科，百科没有候选词时只回退到一次轻量网页搜索：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"某个新产品名称\" --mode lookup --fallback-search\n```\n\n设置 `BAIDU_AI_SEARCH_API_KEYS` 后运行自适应搜索：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal\n```\n\n用户要求最近或最新信息时，限制网页结果时间范围：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal --freshness year --no-cache\n```\n\n用户要求最新或当前信息时，强制绕过缓存：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode normal --no-cache\n```\n\n只有用户要求广覆盖或压力测试时，才固定预算跑完整深度搜索：\n\n```bash\npython \"{baseDir}/scripts/search.py\" \"新能源汽车 口碑\" --mode deep --fixed --top-k 50\n```\n\n只有明确需要时，才跑完计划里的每个搜索词：\n\n```bash\npython \"{baseDir}/scripts/run_search_plan.py\" --plan runs/ev-reputation/query_plan.json --out-dir runs/ev-reputation --top-k 50\n```\n\n去重：\n\n```bash\npython \"{baseDir}/scripts/dedupe_results.py\" --input runs/ev-reputation/raw_results.jsonl --output runs/ev-reputation/deduped_sources.json\n```\n\n生成 research pack：\n\n```bash\npython \"{baseDir}/scripts/build_resea"},{"path":"README.md","content":"# Baidu API Search\n\n简体中文 | [English](README.en.md)\n\n面向 Agent 的百度 API 搜索 Skill。它调用百度 AI Search API 和百度百科 API，把中文搜索结果整理成可复查、可引用的 research pack，适合需要中文网页来源的 AI Agent 使用。\n\n这个 Skill 不是爬虫，也不是答案生成接口。它只负责检索、去重、保留原始结果，并把来源整理给 Agent 后续分析。\n\n## 功能\n\n- 百度 AI Search `web_search`\n- 百度百科轻量实体查询\n- `lookup`、`fast`、`normal`、`deep` 四种模式\n- 自动规划搜索词并根据覆盖情况提前停止\n- URL 去重和近似重复合并\n- 输出 `research_pack.md`、`raw_results.jsonl`、`run_summary.json`\n- 支持本地缓存和多个 API Key 失败切换\n\n## 环境要求\n\n- Python 3.10+\n- 百度 AI Search / AppBuilder API Key\n- 能读取 `SKILL.md` 并运行本地 Python 脚本的 Agent 环境\n\n脚本只使用 Python 标准库，不需要额外安装依赖。\n\nAPI Key 请放在环境变量里：\n\n```bash\nexport BAIDU_AI_SEARCH_API_KEYS=\"your-key\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:BAIDU_AI_SEARCH_API_KEYS = \"your-key\"\n```\n\n多个 Key 用英文逗号分隔：\n\n```bash\nexport BAIDU_AI_SEARCH_API_KEYS=\"key1,key2,key3\"\n```\n\n不要把真实 Key 写进配置文件、README、Prompt、日志或 Git 提交里。\n\n## 快速使用\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal\n```\n\n简单实体查询：\n\n```bash\npython scripts/search.py \"量子计算\" --mode lookup\n```\n\n查询最近或当前信息：\n\n```bash\npython scripts/search.py \"新能源汽车 口碑\" --mode normal --freshness year --no-cache\n```\n\n## 给 Agent 的推荐指令\n\n```text\n中文网页搜索、百度百科查询、最近/最新/热点类中文问题，以及用户说“查一下”“搜索”“联网查”时，优先使用 baidu-api-search skill。回答事实性结论时引用 research_pack.md 里的 source_id 或 URL。\n```"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn702h51bcntppmj04vwcpqzn982ptk8\",\n  \"slug\": \"baidu-api-search\",\n  \"version\": \"1.0.3\",\n  \"publishedAt\": 1778947351386\n}"},{"path":"references/baidu-api.md","content":"# Baidu AI Search API Notes\n\nUse this reference before changing request/auth behavior.\n\n## Endpoint\n\n```text\nPOST https://qianfan.baidubce.com/v2/ai_search/web_search\n```\n\nThis skill targets the web search endpoint because it returns raw-ish `references` suitable for downstream AI analysis. Do not replace it with generated answer endpoints when the user asks for original information.\n\n## Request Shape\n\nThe current script builds this payload:\n\n```json\n{\n  \"messages\": [{\"role\": \"user\", \"content\": \"新能源汽车 口碑\"}],\n  \"search_source\": \"baidu_search_v2\",\n  \"resource_type_filter\": [{\"type\": \"web\", \"top_k\": 50}]\n}\n```\n\nFor low-latency discovery, `fast` mode may add:\n\n```json\n{\n  \"edition\": \"lite\"\n}\n```\n\n`lite` reduces recall/reranking depth for better latency. Use `standard` for normal and deep research.\n\nOptional filters:\n\n```json\n{\n  \"search_filter\": {\n    \"match\": {\n      \"site\": [\"example.com\"]\n    },\n    \"items\": {\n      \"block_websites\": [\"spam.example\"]\n    }\n  },\n  \"search_recency_filter\": \"year\"\n}\n```\n\n`search_recency_filter` accepts `week`, `month`, `semiyear`, or `year`. The exact advanced filter grammar should be verified with live API testing before relying on site or block filters. Basic `messages`, `search_source`, `resource_type_filter`, and optional `edition` are the core contract.\n\n## Authentication\n\nDo not hardcode keys. Use:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nThe script can send both:\n\n```text\nAuthorization: Bearer <key>\nX-Appbuilder-Authorization: Bearer <key>\n```\n\nIf live testing shows only one header is accepted, use `--auth-header authorization` or `--auth-header x-appbuilder`.\n\n## Limits\n\n- `top_k` is clamped to 50.\n- `edition` can be `standard` or `lite`; `standard` remains the default for research.\n- There is no known offset/page/next-token for `web_search`.\n- Multiple keys should not be treated as pagination for the same query.\n- Repeated identical calls should use the local query cache unless the task requires current/latest results.\n\n## Expected Response\n\nThe response should expose `references` either at the top level or under `data.references`. The scripts accept both.\n\nUseful fields:\n\n```text\ntitle\nurl\ndate\ncontent\nsnippet\nwebsite\ntype\nmarkdown_text\nrerank_score\nauthority_score\n```\n\n## Live Testing Checklist\n\nWhen an API key is available:\n\n1. Run `baidu_web_search.py --query \"新能源汽车 口碑\" --top-k 10 --output smoke.json`.\n2. Confirm the response contains `references`.\n3. Run `run_search_plan.py` with a tiny 2-query plan.\n4. Confirm `raw_results.jsonl` has one reference per line.\n5. Confirm no key is printed in logs.\n\n## Cache Safety\n\nThe cache stores endpoint, payload, raw API response, and timestamp. It must not store API keys, Authorization headers, or full key identifiers. Cached responses should use `key_id: \"cache\"` in downstream raw results."},{"path":"references/baike-api.md","content":"# Baidu Baike API Notes\n\nUse this reference before changing lightweight entity lookup behavior.\n\n## Purpose\n\nBaike lookup is a low-budget path for simple entity questions such as:\n\n```text\n这是什么？\n量子计算是什么？\n某个产品/机构/地点有没有百科词条？\n```\n\nIt is not a substitute for web research, recent news, reviews, complaints, or forum discussion.\n\n## Candidate List\n\n```text\nGET https://appbuilder.baidu.com/v2/baike/lemma/get_list_by_title\n```\n\nQuery parameters:\n\n```text\nlemma_title=<term>\ntop_k=1..100\n```\n\nExpected useful fields:\n\n```text\nlemma_id\nlemma_title\nlemma_desc\nis_default\nurl\n```\n\nUse this first when the term may be ambiguous.\n\n## Content Lookup\n\n```text\nGET https://appbuilder.baidu.com/v2/baike/lemma/get_content\n```\n\nQuery parameters:\n\n```text\nsearch_type=lemmaTitle|lemmaId\nsearch_key=<title-or-id>\n```\n\nPrefer `lemmaId` when the candidate list returned an ID.\n\nExpected useful fields:\n\n```text\nlemma_id\nlemma_title\nlemma_desc\nurl\nsummary\nabstract_plain\nabstract_html\nabstract_structured\npic_url\nsquare_pic_url\nrelations\n```\n\n## Authentication\n\nUse the same key environment as web search:\n\n```text\nBAIDU_AI_SEARCH_API_KEYS=key1,key2,key3\n```\n\nNever write or print the full key. `lookup.py` defaults to the official Baike header:\n\n```text\nAuthorization: Bearer <key>\n```\n\nIt can also send these when compatibility testing requires it:\n\n```text\nX-Appbuilder-Authorization: Bearer <key>\n```\n\nUse `--auth-header both` or `--auth-header x-appbuilder` only if live testing shows the default `Authorization` header is not accepted in a specific environment.\n\n## Response Compatibility\n\nThe official docs describe a `result` array for candidate lists, while the success example shows a top-level array. `lookup.py` normalizes both shapes into:\n\n```json\n{\"result\": [...]}\n```\n\n## Cache\n\nBaike lookup uses `cache/baike` by default. The cache stores URL, response, and timestamp only. It must not store Authorization headers or keys.\n\nBypass cache with:\n\n```bash\npython scripts/search.py \"<topic>\" --mode lookup --no-cache\n```\n\n## Output\n\nLookup runs write:\n\n```text\nbaike_candidates.json\nbaike_content.json\nfallback_web_results.json\nerrors.jsonl\nrun_summary.json\nlookup_pack.md\n```\n\nUse `lookup_pack.md` for agent-readable output. Use JSON files for exact raw response inspection.\n\n## Excluded APIs\n\nDo not add these to the default path:\n\n- SecondKnow video\n- image or video search\n- Aladdin beta cards\n- intelligent search generation / generated-answer endpoints\n\nThese either do not serve the text-first search-tool goal or add a generated summary layer that conflicts with preserving source evidence."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"面向 Agent 的中文网页来源检索包 Skill: Baidu API Search Owner: valenovo Summary: 面向 Agent 的中文网页来源检索包 Tags: latest:1.0.3 Version history: v1.0.3 | 2026-05-16T16:02:31.386Z | user Localize the ClawHub-facing skill description, README, and agent prompt to Chinese while keeping a separate English README. v1.0.2 | 2026-05-16T15:53:24.563Z | user Add bilingual Chinese and English documentation inside the published skill package. v1.0.1 | 2026-05-16T15:48","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":892,"uniquenessScore":48,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-12T01:32:13.438Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-12T01:32:13.438Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-14T15:16:29.759Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}