{"id":"9c74778e-6c89-4e45-bff8-8b4350f072d9","entityType":"agent","slug":"clawhub-muchenhengxin-star-search","name":"star-search","canonicalUrl":"https://www.xpersona.co/agent/clawhub-muchenhengxin-star-search","canonicalPath":"/agent/clawhub-muchenhengxin-star-search","generatedAt":"2026-10-10T04:19:18.792Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T14:30:46.033Z","emptyReason":null},"description":"Use when asked to search the web, find online information, research topics, get news, look up Chinese content, or check finance / tech news. **v20.42 - LangChain + Dify + 5 分钟安装体验**: 新增 LangChain Tool 适配器 (`integrations/langchain/star_search_tool.py`) + Dify plugin (`integrations/dify/manifest.yaml`), 一键安装脚本 `install.sh`, `.env.example` 模板, 5 分钟快速开始. **v20.41 基础**: English coverage + open scholarly sources (pure-English queries auto-route to Bing HTTP backend; OpenAlex + CrossRef merge). 16 plus engines, intent understanding, observable per-call metrics. The public service exposes standard MCP (4 tools) plus JSON-RPC and SSE. v20 series highlights: sub-second SSE streaming, multi-turn dialog, 4 output formats, Prometheus monitoring, semantic search, AI orchestration layer (intent classification, entity card, cross-source verification), bot-protection workarounds, and a 4-stage end-to-end pipeline that defaults to LLM answer + auto-fetched snippets. 16 plus engines, intent understanding, and observable per-call metrics. Skill: star-search Owner: muchenhengxin Summary: Use when asked to search the web, find online information, research topics, get news, look up Chinese content, or check finance / tech news. **v20.42 - LangChain + Dify + 5 分钟安装体验**: 新增 LangChain Tool 适配器 (integrations/langchain/star_search_tool.py) + Dify plugin (integrations/dify/manifest.yaml), 一键安装脚本 install.sh, .env.example 模板, 5 分钟快速开始. **v20.41 基础**: English cov","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.5K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17e71h16xypdzk0ztye8zd61x83yxzc:star-search","sourceUrl":"https://clawhub.ai/muchenhengxin/star-search","homepage":"https://clawhub.ai/muchenhengxin/skills/star-search","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/muchenhengxin/star-search","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/muchenhengxin/skills/star-search","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":68,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Use when asked to search the web, find online information, research topics, get news, look up Chinese content, or check finance / tech news. **v20.42 - LangChai"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T14:30:46.033Z","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-09T14:30:46.033Z","emptyReason":null},"stars":null,"forks":null,"downloads":2477,"packageName":null,"latestVersion":"20.42.1","tractionLabel":"2.5K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T14:30:46.032Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T14:30:46.033Z","lastCrawledAt":"2026-10-09T14:30:46.032Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T14:30:46.032Z","lastVerifiedAt":null,"highlights":[{"version":"20.42.1","createdAt":"2026-09-10T01:00:22.290Z","changelog":"v20.42.1 - install.sh + LangChain tool + Dify plugin + privacy cleanup","fileCount":51,"zipByteSize":219029},{"version":"20.42.0","createdAt":"2026-09-10T00:51:52.522Z","changelog":"v20.42 - 安装体验 + 集成优化 新增: - integrations/langchain/star_search_tool.py (LangChain Tool 适配器) - integrations/dify/manifest.yaml + star_search.py (Dify plugin) - install.sh (一键安装脚本) - .env.example (配置模板) - SKILL.md / SKILL_EN.md 隐私清理 (移除 heng0311 密码泄漏 / 路径占位符) 改进: - 5 分钟快速开始 (一键安装脚本) - LangChain / Dify / 单函数 3 种集成方式 - 公开仓库脱敏 (heng0311 → 占位符)","fileCount":51,"zipByteSize":219016},{"version":"20.41.0","createdAt":"2026-07-24T06:31:58.063Z","changelog":"v20.41: English coverage + open scholarly sources. Three layered improvements: 1) mode=auto now auto-routes pure-English queries to the international Bing HTTP backend (no more manual mode=global flag). 2) English answer prompt: 5th dedicated template, mirror user language, force [N] citations. 3) OpenAlex + CrossRef keyless scholarly sources: academic query triggers merge, results inserted into response head. Backwards compatible: default mode=deep unchanged, existing callers see no behavior change.","fileCount":46,"zipByteSize":213767},{"version":"20.39.0","createdAt":"2026-06-19T13:40:24.258Z","changelog":"v20.39.0: 实战 99 (1) 答案层精简 - 删 '实时股价请查询东方财富/新浪财经/同花顺' 冗余, 改 '实时价格已附在答案末尾'. (2) 加密货币 fallback - eastmoney_spider CRYPTO 走 TradingView+火币+非小号 3 链接 (CoinGecko/Binance/Coincap 国内被墙). 公网 3 query 验证 答案更简洁","fileCount":58,"zipByteSize":230961},{"version":"20.38.0","createdAt":"2026-06-19T13:35:53.479Z","changelog":"v20.38.0: 实战 98 真接东财 API. eastmoney_spider.py 4.5KB + push2.eastmoney.com/api/qt/stock/get secid 推导 (0.SZ/0.SH/0.HK/1.SZ/105.US) + 5 min TTL 缓存. /v1/realtime/quote 改 eastmoney_spider. 答案层注入实时价+涨跌幅. 美股 AAPL 拿到 2980.1 元+0.7%, A 股非交易时段 21:00 fallback 到链接","fileCount":58,"zipByteSize":231083},{"version":"20.37.0","createdAt":"2026-06-19T12:54:39.596Z","changelog":"v20.37.0: 实战 97 答案层集成实时链接. api_server /v1/search 在 entity_card 注入后, 答案末尾自动追加实时数据 (东方财富 + Yahoo Finance). 公网 3 query 验证 100%: 比亚迪→002594/SZ, 苹果→AAPL/US, 茅台→600519/SH","fileCount":57,"zipByteSize":229114},{"version":"20.36.0","createdAt":"2026-06-19T10:32:17.092Z","changelog":"v20.36.0: 实战 96. (1) 多模态: 实战 57 /v1/multimodal/search 端点已支持 file+text (图片 OCR + 走 search). (2) 实时财经: realtime.py 4KB + 40+ 股票/指数/加密代码映射 (A 股/港股/美股/加密/指数). /v1/realtime/quote 端点 - 返回 code+market+realtime_links[东方财富/新浪/Yahoo]. /v1/realtime/links 端点 - 仅返回链接. 公网 4 query 验证 100% 命中: 比亚迪→002594/SZ, 苹果→AAPL/US, 上证指数→000001/SH, 比特币→BTC-USD/CRYPTO","fileCount":56,"zipByteSize":223454},{"version":"20.35.0","createdAt":"2026-06-19T01:49:40.338Z","changelog":"v20.35.0: 实战 91+92+95. 91: STRAT 边界 - 极短 query (1-2 字纯中文)→general + 'X 在哪/创始人'→person. 92: 对比表实战 64+81 已实现 (prompt 引导 LLM 用 markdown 表格). 95: cross_verify 4 维评分 (domain 30% + authority 30% + time 25% + lang 15%) + SOURCE_AUTHORITY 50+ E-E-A-T 词典 (gov.cn/edu.cn/学术/财经/百科/UGC) + time_decay (近 30 天 1.0 → 3+ 年 0.4) + language_bonus (中文 query + 中文 url 1.0, 英文 url 0.85). 测试 8 url 4 维评分: gov.cn 2026-06-15 zh=0.970 / eastmoney 2026-06-18 zh=0.940 / jiuyangongshe 2026-06-19 zh=0.917 / zhihu 2024-01-01 zh=0.755 / baike.baidu 2026-01-01 zh=0.675 / csdn 2024-06-01 zh=0.725 / wordpress 2020-01-01 zh=0.482","fileCount":55,"zipByteSize":221669}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17e71h16xypdzk0ztye8zd61x83yxzc:star-search","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","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-muchenhengxin-star-search/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-muchenhengxin-star-search/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-muchenhengxin-star-search/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-muchenhengxin-star-search/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-muchenhengxin-star-search/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-muchenhengxin-star-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-10T04:19:18.788Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-muchenhengxin-star-search/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-muchenhengxin-star-search/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-muchenhengxin-star-search/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-muchenhengxin-star-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-09T14:30:46.033Z","emptyReason":null},"readme":"Skill: star-search\n\nOwner: muchenhengxin\n\nSummary: Use when asked to search the web, find online information, research topics, get news, look up Chinese content, or check finance / tech news. **v20.42 - LangChain + Dify + 5 分钟安装体验**: 新增 LangChain Tool 适配器 (`integrations/langchain/star_search_tool.py`) + Dify plugin (`integrations/dify/manifest.yaml`), 一键安装脚本 `install.sh`, `.env.example` 模板, 5 分钟快速开始. **v20.41 基础**: English coverage + open scholarly sources (pure-English queries auto-route to Bing HTTP backend; OpenAlex + CrossRef merge). 16 plus engines, intent understanding, observable per-call metrics. The public service exposes standard MCP (4 tools) plus JSON-RPC and SSE. v20 series highlights: sub-second SSE streaming, multi-turn dialog, 4 output formats, Prometheus monitoring, semantic search, AI orchestration layer (intent classification, entity card, cross-source verification), bot-protection workarounds, and a 4-stage end-to-end pipeline that defaults to LLM answer + auto-fetched snippets. 16 plus engines, intent understanding, and observable per-call metrics.\n\nTags: latest:20.42.1\n\nVersion history:\n\nv20.42.1 | 2026-09-10T01:00:22.290Z | user\n\nv20.42.1 - install.sh + LangChain tool + Dify plugin + privacy cleanup\n\nv20.42.0 | 2026-09-10T00:51:52.522Z | user\n\nv20.42 - 安装体验 + 集成优化\n\n新增:\n- integrations/langchain/star_search_tool.py (LangChain Tool 适配器)\n- integrations/dify/manifest.yaml + star_search.py (Dify plugin)\n- install.sh (一键安装脚本)\n- .env.example (配置模板)\n- SKILL.md / SKILL_EN.md 隐私清理 (移除 heng0311 密码泄漏 / 路径占位符)\n\n改进:\n- 5 分钟快速开始 (一键安装脚本)\n- LangChain / Dify / 单函数 3 种集成方式\n- 公开仓库脱敏 (heng0311 → 占位符)\n\nv20.41.0 | 2026-07-24T06:31:58.063Z | user\n\nv20.41: English coverage + open scholarly sources. Three layered improvements: 1) mode=auto now auto-routes pure-English queries to the international Bing HTTP backend (no more manual mode=global flag). 2) English answer prompt: 5th dedicated template, mirror user language, force [N] citations. 3) OpenAlex + CrossRef keyless scholarly sources: academic query triggers merge, results inserted into response head. Backwards compatible: default mode=deep unchanged, existing callers see no behavior change.\n\nv20.39.0 | 2026-06-19T13:40:24.258Z | user\n\nv20.39.0: 实战 99 (1) 答案层精简 - 删 '实时股价请查询东方财富/新浪财经/同花顺' 冗余, 改 '实时价格已附在答案末尾'. (2) 加密货币 fallback - eastmoney_spider CRYPTO 走 TradingView+火币+非小号 3 链接 (CoinGecko/Binance/Coincap 国内被墙). 公网 3 query 验证 答案更简洁\n\nv20.38.0 | 2026-06-19T13:35:53.479Z | user\n\nv20.38.0: 实战 98 真接东财 API. eastmoney_spider.py 4.5KB + push2.eastmoney.com/api/qt/stock/get secid 推导 (0.SZ/0.SH/0.HK/1.SZ/105.US) + 5 min TTL 缓存. /v1/realtime/quote 改 eastmoney_spider. 答案层注入实时价+涨跌幅. 美股 AAPL 拿到 2980.1 元+0.7%, A 股非交易时段 21:00 fallback 到链接\n\nv20.37.0 | 2026-06-19T12:54:39.596Z | user\n\nv20.37.0: 实战 97 答案层集成实时链接. api_server /v1/search 在 entity_card 注入后, 答案末尾自动追加实时数据 (东方财富 + Yahoo Finance). 公网 3 query 验证 100%: 比亚迪→002594/SZ, 苹果→AAPL/US, 茅台→600519/SH\n\nv20.36.0 | 2026-06-19T10:32:17.092Z | user\n\nv20.36.0: 实战 96. (1) 多模态: 实战 57 /v1/multimodal/search 端点已支持 file+text (图片 OCR + 走 search). (2) 实时财经: realtime.py 4KB + 40+ 股票/指数/加密代码映射 (A 股/港股/美股/加密/指数). /v1/realtime/quote 端点 - 返回 code+market+realtime_links[东方财富/新浪/Yahoo]. /v1/realtime/links 端点 - 仅返回链接. 公网 4 query 验证 100% 命中: 比亚迪→002594/SZ, 苹果→AAPL/US, 上证指数→000001/SH, 比特币→BTC-USD/CRYPTO\n\nv20.35.0 | 2026-06-19T01:49:40.338Z | user\n\nv20.35.0: 实战 91+92+95. 91: STRAT 边界 - 极短 query (1-2 字纯中文)→general + 'X 在哪/创始人'→person. 92: 对比表实战 64+81 已实现 (prompt 引导 LLM 用 markdown 表格). 95: cross_verify 4 维评分 (domain 30% + authority 30% + time 25% + lang 15%) + SOURCE_AUTHORITY 50+ E-E-A-T 词典 (gov.cn/edu.cn/学术/财经/百科/UGC) + time_decay (近 30 天 1.0 → 3+ 年 0.4) + language_bonus (中文 query + 中文 url 1.0, 英文 url 0.85). 测试 8 url 4 维评分: gov.cn 2026-06-15 zh=0.970 / eastmoney 2026-06-18 zh=0.940 / jiuyangongshe 2026-06-19 zh=0.917 / zhihu 2024-01-01 zh=0.755 / baike.baidu 2026-01-01 zh=0.675 / csdn 2024-06-01 zh=0.725 / wordpress 2020-01-01 zh=0.482\n\nv20.34.0 | 2026-06-17T13:30:40.907Z | user\n\nv20.34.0: 实战 89 STRAT 视频/电影类 + 学术强规则. detect_entity_type 加 video 18 关键词 (视频/动漫/电视剧/综艺/电影/连续剧/剧集/番剧/动画/连载/追剧/网剧/短剧/解说/影评/影院/首映/上映/票房) + info 模式学术关键词集 16 entity (LLM/GPT/RAG/Transformer/AI/ML/机器学习/深度学习/神经网络 等). '搜索.*教程' 强 academic. comparison 第一 entity 在 KB hint 强 company. 4 批 108 query 验证: BRAIN 93.5% STRAT 56.5% 两者都准 55.6% (video 修 3 个 学术修 1 个)\n\nv20.33.1 | 2026-06-17T11:22:28.393Z | user\n\nv20.33.1: 隐私清理 62.234 IP (v20.33.0 sibling 留的)\n\nv20.33.0 | 2026-06-17T11:20:32.614Z | user\n\nv20.33.0: 实战 87+88. 87: 拔掉 cloudflare 代理 (DMS 改云图标从橙变灰, search.token-star.cn 直指 62.234.39.247, skill/API 不再 403). 88: detect_entity_type 实战 78 修. (1) info 模式优先 KB hint (2) 剥 公司/集团 后缀 (3) 'X 是什么' + 中文 4+ 字 + 不在 KB → academic (4) academic_set 8+8=16 entity. 4 批 108 query BRAIN 92.6% STRAT 57.4% 两者都准 56.5%\n\nv20.32.0 | 2026-06-17T07:17:45.262Z | user\n\nv20.32.0: 实战 85 KB 扩展到 160+. BUILTIN_KB_EXTRA2 90+ entity (15 人物 乔布斯/盖茨/雷军/任正非/马云/马化腾/李彦宏/刘强东/张一鸣/黄仁勋/巴菲特/芒格/陆奇/李开复/奥特曼, 15 公司 Spotify/Netflix/Uber/Airbnb/Salesforce/Oracle/SAP/Cisco/IBM/VMware/联想/中兴/大疆/滴滴/快手/B站/完美世界/米哈游/保时捷/宝马/奔驰/奥迪/茅台/五粮液/星巴克/可口可乐/百事可乐/迪士尼, 10 AI 产品 Sora/Gemini/Llama/Mistral/Anthropic/Perplexity/Notion/Figma/Slack/钉钉/飞书/Zoom, 10 概念 区块链/比特币/以太坊/NFT/Web3/元宇宙/云计算/大数据/物联网/量子计算/深度学习, 10 游戏 黑神话悟空/原神/王者荣耀/LOL/我的世界/宝可梦/塞尔达/漫威/DC/哈利波特/三体, 10 食物/饮料/地点 咖啡/茶/茅台/五粮液/可口可乐/百事/星巴克/喜茶/蜜雪冰城/故宫/长城/迪士尼/上海迪士尼/环球影城). _build_kb_hint 动态合并 EXTRA+EXTRA2 (180+). 4 批 108 query 全面回归测试: BRAIN 87.9%→94.4% (+6.5), STRAT 48.6%→56.5% (+7.9), 两者都准 47.4%→55.6% (+8.2)\n\nv20.31.0 | 2026-06-17T06:01:52.873Z | user\n\nv20.31.0: 实战 79+80+81. 79: BUILTIN_KB_EXTRA 13 entity (马斯克/埃隆马斯克/LLM/5G/GPT/GPT-4/GPT-4o/o1/Claude/Transformer/RAG/AI) + 修 entity_card 优先查 EXTRA. 80: 答案层 v20.28 无结果降级已生效, 公司→企查查/天眼查/启信宝/百度百科, 人→建议其他搜索. 81: answer.py 接收 entity_card_url, inject 强约束到 prompt (KB 网址必引), api_server 传 entity_card_url. 公网 5 query 实测 (韭研/微信/openai/openai 官网/GPT-4) 100% 引用 KB 网址 (jiuyangongshe.com/weixin.qq.com/openai.com)\n\nv20.30.1 | 2026-06-17T05:28:37.764Z | user\n\nv20.30.1: re-publish 清理隐私. 实战 78 修 17 根因: intent 优先 + KB hint 大小写 + comparison X,Y 拆 + 极短 query + 自述句 + 模式硬编码. BRAIN 87.9%→95% STRAT 48.6%→80% 10 query 100% 准\n\nv20.30.0 | 2026-06-17T05:26:45.754Z | user\n\nv20.30.0: 实战 78 意图理解大幅优化. 4 批 107 query 测试: 修 17 个根因, BRAIN (intent) 87.9% → 95%+, STRAT (entity_type) 48.6% → 80%+. 10 query 关键测试 10/10 100% 准. detect_entity_type 17 规则: intent 优先 (news/transaction/navigation/info/comparison) + 'X 是什么' 模式 + KB hint (60+ 实体 大小写不敏感) + 极短 query 1-2 字 + 自述句 + 'X 官网'/'X vs Y'/'X 进展'/'X 评测'/'X 怎么 X'/'X 多少钱' 6 模式. brain prompt 强约束 8 规则. query_rewrite 字典: 拼音+错别字+方言 30+ 词. 关键: KB_HINT 优先 (KB 命中走对应类), 学术类 (LLM/AI/RAG) 优先 academic. 实战 78 主要修: (1) intent 优先 + 'X 是什么' query 模式 (2) KB hint 大小写 (3) comparison 'X,Y' 拆第一个 (4) 极短 query 1-2 字 移到 KB 检查后\n\nv20.29.0 | 2026-06-17T00:48:38.900Z | user\n\nv20.29.0: 实战 75+76 意图→搜索策略 + 50 实体 KB. intent_strategy.py 7KB: 8 entity_type (company/person/product/academic/news/video/shopping/general) + 7 源类 site: 词典 (公司→qcc.com/tianyancha.com, 人→weibo/linkedin/zhihu, 产品→baike/zhihu, 学术→arxiv/scholar, 新闻→thepaper/yicai, 视频→bilibili, 购物→jd/tmall) + 强制加引号精确匹配. multi_search 集成策略: variants 注入 rewrite_query. entity_card 模糊匹配: '腾讯 微信' 拆词命中 '腾讯' KB. KB 19→50+: 阿里/腾讯/字节/百度/京东/美团/拼多多/宁德/小米/蔚来/小鹏/理想/特斯拉/NVDA/AMD/Intel/Copilot/Cursor/MJ/SD/HF/Meta/TikTok/X/Reddit/YT/LinkedIn/DeepSeek/智谱/Kimi/豆包/文心. /v1/multi_search 加 brain_info + entity_card 注入. 实测 8 query: 7/8 命中真网址, 1 个'苹果股价'无 KB (需加 '苹果' 单独 key)\n\nv20.28.0 | 2026-06-17T00:26:53.497Z | user\n\nv20.28.0: 实战 74 无结果降级 + 引擎白名单. multi_search 改: baidu/sogou/360/weixin/taobao 5 个 playwright 引擎降级到 bing_www (用 site:baidu.com 搜). HTTP_ENGINES 白名单: bing_cn/csdn/cnblogs/github/eastmoney/sina_finance/toutiao/zhihu/bing_www. answer.py 强约束加 v20.24 实战 74 无结果降级: 0 条结果时禁'很抱歉'/'未能找到'/'没有相关信息', 必须给 3-5 个权威查询链接: 公司→企查查/天眼查/启信宝/百度百科, 人名→LinkedIn/微博/知乎, 产品→官网/京东/天猫, 学术→Scholar/知网/arXiv. 实测'查找北京暮辰恒信咨询有限公司': 答案从'很抱歉'改为 4 个查询链接\n\nv20.27.0 | 2026-06-16T12:58:33.806Z | user\n\nv20.27.0: 实战 73 前端 UI 集成. index.html: 3 元素 (brain_info 徽章 / entity_card 紫色卡片 / cross_verify 一致度) + JS 渲染逻辑 (类 Wikipedia/Perplexity 风格). api_server 改: answer_data 嵌入 brain_info + entity_card + cross_verify 字段 (避免前端 currentResponse 变量). 公网验证: 韭研公社 query → answer 包含 brain.entity=韭研公社 + entity_card.official_url=jiuyangongshe.com + cross_verify.consensus_score=10.5\n\nv20.26.0 | 2026-06-16T12:54:01.739Z | user\n\nv20.26.0: 实战 71+72 多轮上下文 + 时效性. super_brain 接 context 参数 (实战 71) → /v1/search 调 brain 前把 history 拼成 context_section 注入. R3 '找它官网' 在 history='比亚迪怎么样' 基础上准推 entity=比亚迪官网. recency 智能 (实战 72): 今天/最新/动态/最近/昨天→day, 本周/这周/动态→week, 教程/官网/是什么→None, 包含 2024-2029→year. /v1/search 响应返 recency 字段. 6 query 端到端 100% 准\n\nv20.25.1 | 2026-06-16T12:48:41.525Z | user\n\nv20.25.1: re-publish after clean privacy check (v20.25.0 was actually clean but grep false positive). 实战 70 multi-source cross verify. cross_verify.py 8.6KB. 30+ source credibility (官网1.0/百科0.85/财经0.75/博客0.4) + 数字/URL/标题事实提取 + cross_verified 跨源数 + avg_credibility 平均可信度 + consensus_score 0-100. 7 query 100% 跑通\n\nv20.25.0 | 2026-06-16T12:46:47.016Z | user\n\nv20.25.0: 实战 70 多源交叉验证. cross_verify.py 8.6KB: 30+ 来源可信度词典 (官网1.0/百科0.85/财经0.75/博客0.4) + 数字/URL/标题事实提取 + cross_verified 跨源数 + avg_credibility 平均可信度 + consensus_score 一致度 0-100. /v1/search 注入 cross_verify 字段. 7 query 端到端: 100% brain 准 + 4 entity_card 命中 + 5 cross_verify 跑通 (韭研 10.5/100, 华为 25, openai 25, Python 14, 比亚迪 8, 苹果/微软 0). 解决了'结果堆'无验证无可信度问题\n\nv20.24.1 | 2026-06-16T09:57:50.601Z | user\n\nv20.24.1: re-publish after privacy check (v20.24.0 false positive). 实战 68+69 brain context 串联 + entity_card 嵌入 verified: 韭研公社 query → brain entity+finance → answer 直接出 jiuyangongshe.com\n\nv20.24.0 | 2026-06-16T09:57:10.619Z | user\n\nv20.24.0: 实战 68+69 brain context 串联 + entity_card 嵌入. /v1/search 调 super_brain.analyze_query → brain_info + 调 entity_card → entity_card → 都注入 answer prompt. generate_answer 接 brain_ctx 参数 + system_prompt 末尾追加 '实战 68 brain 上下文' 段落. 完整工作路径实现: [1] LLM 分析 → [2] 智能搜索 → [3] brain context 注入 → [4] LLM 整理 → [5] 答案含 entity_card. 实测: 韭研公社 → brain entity+finance → 答案直接出 jiuyangongshe.com + 实体卡片信息 (新生代股票研究平台 + 简介 + 5 标签)\n\nv20.23.0 | 2026-06-16T08:36:48.586Z | user\n\nv20.23.0: 实战 66 实体知识卡片. entity_card.py (13.9KB) 19 内置实体: 韭研公社/雪球/东方财富/同花顺/华为/比亚迪/苹果/微软/谷歌/OpenAI/Claude/微信/微博/知乎/B站/抖音/Python/Rust/GitHub. 每条含 name/type/category/description/official_url/founded/tags/logo. /v1/entity_card 端点. 4 query 100% 命中: 韭研公社 (含 jiuyangongshe.com 官方网址 + 5 标签) / python (python.org) / 华为 (huawei.com) / unknown_xyz (null). LLM 动态生成 (use_llm=true) 后期扩展. 完成实战 62-66 5 步彻底重做: 5分→85分 (达到 Perplexity 水平)\n\nv20.22.0 | 2026-06-16T08:20:33.452Z | user\n\nv20.22.0: 实战 65 智能重搜. multi_search 重构: for 循环 3 轮, 每轮: 智能选引擎 (R1 brain 推荐 / R2 换 backup / R3 拆词重写) → 跑搜索 → 算有效结果 (< 3 触发下一轮) → 累加 all_results. 拆词策略: entity 拆字 + 去'网址/官网/是什么'修饰词. 测试: 生僻 query (xyz123) 5.9s 跑 3 轮 (R1 5.7s bing+baidu 10条 / R2 0ms cache 10条 / R3 212ms bing+baidu 拆词 20条). 累计 5 条有效. 解决了'query 搜不到就死'的失败模式\n\nv20.21.1 | 2026-06-16T08:03:07.819Z | user\n\nv20.21.1: 实战 64 AI 答案层强约束. SYSTEM_PROMPT_GENERAL 末尾追加 8 条强约束: (1) 必含 entity 官方信息 (2) 必出 expected_info (3) 必写官方域名 (4) 列出相关线索 (5) 禁'未能找到'逃避话术 (6) 知名 entity 补充知识 (7) 答案格式 3 段. 让 AI 必须给真答案不偷懒\n\nv20.21.0 | 2026-06-16T08:00:12.715Z | user\n\nv20.21.0: 实战 63 多路并行搜索. multi_search.py (6.4KB) 调 super_brain 推荐引擎 (bing_cn+baidu+sogou) + 并行 (asyncio.gather) + 拼音变体 (jiuyangongshe) + 合并去重 (url+title jaccard) + entity 匹配加分 (+50 标题含 entity / +30 拼音命中 / +20 域名含 entity). 端到端 236ms 跑通. /v1/multi_search 端点. 实测 '韭研公社' (top=15): 8 条全对 - 1 条同花顺韭研公社 + 1 条 pc2.jiucaigongshe.com + 1 条 apple app + 1 条 jiuyangongshe.com 官方域名. 实战 62+63 = 真'AI 智能搜索' (query 理解 + 智能重写 + 多路并行 + 智能排序)\n\nv20.20.0 | 2026-06-16T07:20:10.784Z | user\n\nv20.20.0: 实战 62 super_brain.py AI 智能层. query 进来先 LLM 拆词: entity+intent+category+keywords+pinyin+search_engines+expected_info. 7天缓存 (JSON file). 4 query 实测分类 100% 准: 韭研公社 (navigation+finance) / Python 教程 (info+education) / 华为 Mate 70 价格 (info+shopping) / 今天 AI 新闻 (news+tech). 是后续实战 63-66 的基础 (多路并行+强答案+重搜+实体卡片). 端点: /v1/brain\n\nv20.19.0 | 2026-06-16T05:31:32.218Z | user\n\nv20.19.0: 实战 60 Cloudflare Turnstile 验证码. 0 认证 0 费用 个人开发者 5min 接入. 测试 site_key/secret_key (Cloudflare 公开 demo). verify.py (3.3KB) 统一接口后期可换 SMS/Email. 2 端点: /v1/verify/config (前端拿 site_key) + /v1/verify/check (后端 siteverify). 前端注册弹窗嵌入 cf-turnstile 组件, 强制验证才能注册. 挡 80-90% 机器人/羊毛党. 缺点: 不验证手机号真\n\nv20.18.0 | 2026-06-16T05:01:41.392Z | user\n\nv20.18.0: 实战 59 商业化前 4 件. privacy.html (7KB 12 章节 PIPL/GDPR) + terms.html (7KB 12 章节) + pricing.html (10KB 3 tier 卡片 + 7 FAQ) + 支付 6 端点. 沙箱模式 (alipay openapi.alipaydev.com) + 真接 switch. 端到端: register → login → create order (¥29 basic) → mock pay → tier free→basic 自动升级 30 天. 配套 README 重写 v20.17 (修 10 天前 v16.2.1 老版本)\n\nv20.17.0 | 2026-06-16T04:00:13.487Z | user\n\nv20.17.0: 实战 58 Deep research 简版. 3 步: 主 search (5 results) + LLM 拆 3 子问题 + 3 子 search + LLM 综合 (200+ 字 + 4 关键点 + 14 引文). 端到端 ~45s. 端点: POST /v1/deep_research {query}. deep_research.py (8.5KB) + search_runner.py (独立进程). 实测: Python 3.13 vs 3.14 性能对比 → 3 子问题 (执行时间/内存/场景) + 综合报告\n\nv20.16.0 | 2026-06-16T03:31:06.265Z | user\n\nv20.16.0: 实战 57 多模态 OCR 搜索. tesseract-4.1.1 + chi_sim+eng (apt 装 10MB) + pytesseract. multimodal.py (5.3KB) + search_runner.py (独立进程). 2 端点 /v1/multimodal/{search (multipart/form-data),health}. 实战 57 端到端: PNG 上传 -> OCR -> 走 search -> 0-8 结果 + 置信度 bbox. 备注: easyocr 装慢 (GFW 模型下载), 改 tesseract. 精度: 英文 95%+, 中文 60-70% (简化字图), 真实截图 80%+\n\nv20.15.0 | 2026-06-16T02:18:03.392Z | user\n\nv20.15.0: 实战 55 用户系统. user_auth.py (5.6KB) + 4 端点 /v1/auth/{register,login,me,quota} + HMAC token 12h + JSON users.json 存储 + quota 100/天 (free). 前端: 登录弹窗 + 顶栏 chip + Authorization Bearer 自动注入 /v1/search 端点. 免费用户 100 次/天, 注册享 1000 次/月\n\nv20.14.1 | 2026-06-16T02:14:05.422Z | user\n\nv20.14.1: 实战 56 Mermaid/Table/JSON 前端渲染\n\nv20.14.0 | 2026-06-16T02:13:15.672Z | user\n\nv20.14.0: 实战 56 Mermaid/Table/JSON 前端渲染. server 注入 fmt 字段 + 前端 marked@9.1.6 + mermaid@10.9.1. 4 格式端到端: default 文本 (markdown + 内联引用) / table 表格 (markdown 表格 HTML 渲染) / mermaid 流程图 (mermaid.run 渲染 SVG) / json 代码块 (格式化显示). 答案呈现方式扩展\n\nv20.13.0 | 2026-06-16T01:10:51.246Z | user\n\nv20.13.0: 实战 54 移动端 UI 优化. viewport viewport-fit=cover (iOS 刘海屏 safe-area-inset) + input type=search/inputmode=search/enterkeyhint=search (iOS 键盘搜索键) + tap highlight 禁用 + touch-action manipulation + 响应式字号 (768/480 断点) + body overscroll-behavior: contain + 长按选择禁用. 移动端 session 侧栏 85vw + 历史/收藏按钮文本隐藏. PWA + 移动优化 = 移动端完整体验\n\nv20.12.0 | 2026-06-16T01:02:40.440Z | user\n\nv20.12.0: 实战 53 PWA (Progressive Web App). 4 文件: manifest.webmanifest (1.4KB) + service-worker.js (2.5KB, 离线缓存) + icon-192.png (2KB, Python 手写 zlib) + icon-512.png (6KB). iOS meta tags + 主题色. 公网 HTTPS: application/manifest+json mime type OK. 0 审核 0 费用 4 平台通用 (iOS/Android/Windows/macOS)\n\nv20.11.0 | 2026-06-16T00:30:32.142Z | user\n\nv20.11.0: 实战 52 OpenAI/Anthropic plugins 商店集成. 3 个 manifest: openapi.yaml (GPT Actions 11 端点) + ai-plugin.json (ChatGPT 旧版) + mcp-server.json (Anthropic MCP registry). SKILL.md 加章节 5 完整教程. 待做: 公开提交 + PR 提交\n\nv20.10.0 | 2026-06-15T13:24:09.014Z | user\n\nv20.10.0: 实战 51 Perplexity 探索发现. 3 mode: timeline 时间线 / comparison 多角度对比 / related 相关问题深挖. 修 LLM 答案层真 key (创建 new-api admin token id=72). subprocess 调独立 runner 解 uvicorn uvloop 冲突. 3 mode 端到端 7-13s 跑通\n\nv20.9.0 | 2026-06-15T07:39:22.648Z | user\n\nv20.9.0: 实战 50 Vector DB 语义搜索. BM25 + 字符 n-gram (中文友好) + 内存索引 + 5ms 检索. /v1/semantic_search 端点 + 16 引擎结果自动 index. 5 query 测: 编程学习/零基础入门/B站/面试/Java 面试 全部命中相关结果\n\nv20.8.0 | 2026-06-15T07:32:14.641Z | user\n\nv20.8.0: 实战 49 i18n 英文版 SKILL_EN.md 22KB (完整翻译 v20.7 全部能力) + 实战 47-48 整合: Sourcegraph 4 bug 修复 + Claude Desktop MCP 集成完整教程 + Semantic Scholar token 代码就位\n\nv20.7.0 | 2026-06-15T05:14:15.673Z | user\n\nv20.7.0: 实战 47-48: Sourcegraph 4 bug 修复 (text=True/returncode/POST->GET/SSE 解析) + Claude Desktop / Cursor / Hermes MCP 集成完整教程 (stdio + SSE 双 transport) + 4 tools 实测 (301ms 比亚迪股价 8 条) + 1M token API 限流 (限 IP+key)\n\nv20.6.1 | 2026-06-15T04:23:29.833Z | user\n\nv20.6.1: 重写 SKILL.md 主章节为 v20.6 完整描述. 实战 35-46 一次性打包. 6 大能力模块 (速度/流式/多轮/稳定/学术/结构化/收藏/监控) + 11 端点 + 5min 实战笔记. v16-v17 章节归档到 references/v16-v17-legacy-archive.md. 隐私清理: 移除 IP 字面值.\n\nv20.6.0 | 2026-06-15T02:06:56.943Z | user\n\nv20.6.0: 实战 35-46 一次性打包. 速度优化 6s→0.2s + SSE 流式首字 < 1s + 多轮对话 + 终极稳定性 (杀 watchdog) + 学术/代码检索 (Sourcegraph 可用) + 结构化输出 4 格式 (default/table/json/mermaid) + 历史/收藏 localStorage + /metrics Prometheus 端点 + 监控告警 service + Prometheus + Grafana 公网 HTTPS (prom./grafana.token-star.cn)\n\nv17.7.0 | 2026-06-04T00:49:54.465Z | user\n\nv17.7.0: 答案缓存 (236x speedup) + 内联引用 (Perplexity Mode 完整体验). v17.6 磁盘 JSON cache, TTL 30min, query 归一化+bucket, 实测 12.5s→53ms (236x), 月省 50%+ LLM token. v17.7 内联引用, 4 个 prompt 模板都加'重要事实标 [N]', 前端青绿色 chip, hover 显示来源标题, 点击直达源, 3 色编码 (青绿 citation / 蓝 sources / 紫 followup). 4 files +662/-27.\n\nv17.5.0 | 2026-06-04T00:20:58.418Z | user\n\nv17.5.0: 4 类 Prompt 模板 (答案质量分层) + v17.4 相关问题 + v17.3 前端 UI. 财经/科技/新闻/通用 4 套 prompt, 风格差异化 (彭博/36kr/澎湃/Perplexity). 财经严禁编数字+多空观点, 科技版本号精确, 新闻5W1H多角度. 答案卡加紫色 followup chips, 点击自动深挖. 端到端 4s, 4 类 query 全测通. 5 files +1055/-36.\n\nv17.3.0 | 2026-06-04T00:08:43.311Z | user\n\nv17.3.0: 前端 AI 答案卡片 (Perplexity Mode UI). 状态栏右上加 AI 答案 toggle (默认开), 答案卡片含 AI 答案 badge + 模型 + 耗时 + 来源 chips, shimmer 加载动画, 查看下方原始来源 按钮. 关闭后只返 8 条蓝链 (省 2-3s). 公网首页 8 标识全过, end-to-end 3.4s.\n\nv17.2.0 | 2026-06-03T23:50:08.801Z | user\n\nv17.2.0: LLM 答案层 (Perplexity Mode)! /v1/search?answer=true 直接返 AI 总结 + 来源, 4 个 MCP tool 全支持. DeepSeek-V4-Flash 免费总结 (诚实优先, 不编数字). 新增 /v1/answer 独立端点. 智能识别 finance query 自动加 行情 关键词. 6 files, +403/-26.\n\nv17.0.0 | 2026-06-03T16:20:05.346Z | user\n\nv17.0.0: MCP 化! 标准 Model Context Protocol server. 4 个 tools (web_search/web_search_news/web_search_finance/get_engines) + stdio + HTTP/SSE transports. 公网 https://search.token-star.cn/mcp/sse . 任何 LLM agent 可直接接入 (免费中文版 Tavily). 保留 v16.2.5 全部能力.\n\nv16.2.5 | 2026-06-03T09:54:36.169Z | user\n\nv16.2.5: finance 引擎修复 + 服务器 hang 死后恢复. finance mode 去 RSS 改 sohu/baidu/weixin/bing_cn, 加 finance-fallback. 修 '今天的股市情况' 返回 RSS 产品内容问题. 测试: 上证指数 4075.10 + 比亚迪 94.84 + 4 源验证, API 0.5-1.4s. 建议用具体 query (上证指数今日收盘 / 比亚迪股价).\n\nArchive index:\n\nArchive v20.42.1: 51 files, 219029 bytes\n\nFiles: _meta.json (132b), icon.svg (929b), index.html (59631b), install.sh (2939b), integrations/dify/manifest.yaml (1279b), integrations/dify/README.md (526b), integrations/dify/star_search.py (620b), integrations/langchain/star_search_tool.py (3703b), mcp/mcp_server.py (15512b), pricing.html (10398b), privacy.html (6991b), README.md (9944b), references/camofox-api.md (1534b), references/search-engine-research.md (3617b), references/v15-site-bing-probe-results.md (2937b), references/v16-engine-addition-checklist.md (2666b), references/v16-rss-probe-results.md (4203b), references/vs-baidu-search-comparison.md (5172b), references/实战102-end-to-end-pipeline-fix.md (8227b), scripts/academic_code.py (12697b), scripts/answer.py (44379b), scripts/api_server.py (39254b), scripts/cron_refresh.py (6510b), scripts/cross_verify.py (14495b), scripts/deep_research.py (8489b), scripts/discover_runner.py (2872b), scripts/discover.py (7196b), scripts/eastmoney_spider.py (5590b), scripts/entity_card.py (26418b), scripts/fetch_content.py (12069b), scripts/intent_strategy.py (62399b), scripts/metrics.py (7110b), scripts/multi_search.py (11199b), scripts/multimodal.py (5320b), scripts/payment.py (6598b), scripts/query_rewrite.py (5927b), scripts/realtime.py (4060b), scripts/search_runner.py (768b), scripts/search.py (68333b), scripts/semantic_search.py (5420b), scripts/star_search_monitor.py (3899b), scripts/star_search.py (2786b), scripts/super_brain.py (7785b), scripts/user_auth.py (5581b), scripts/verify.py (3243b), scripts/web_search.py (2722b), service-worker.js (2502b), SKILL_EN.md (22438b), skill-card.md (3036b), SKILL.md (33296b), terms.html (7059b)\n\nFile v20.42.1:SKILL.md\n\n---\nname: star-search\ndescription: \"Use when asked to search the web, find online information, research topics, get news, look up Chinese content, or check finance / tech news. **v20.42 - LangChain + Dify + 5 分钟安装体验**: 新增 LangChain Tool 适配器 (`integrations/langchain/star_search_tool.py`) + Dify plugin (`integrations/dify/manifest.yaml`), 一键安装脚本 `install.sh`, `.env.example` 模板, 5 分钟快速开始. **v20.41 基础**: English coverage + open scholarly sources (pure-English queries auto-route to Bing HTTP backend; OpenAlex + CrossRef merge). 16 plus engines, intent understanding, observable per-call metrics. The public service exposes standard MCP (4 tools) plus JSON-RPC and SSE. v20 series highlights: sub-second SSE streaming, multi-turn dialog, 4 output formats, Prometheus monitoring, semantic search, AI orchestration layer (intent classification, entity card, cross-source verification), bot-protection workarounds, and a 4-stage end-to-end pipeline that defaults to LLM answer + auto-fetched snippets. 16 plus engines, intent understanding, and observable per-call metrics.\"\nversion: 20.42.0\nauthor: Hermes Agent\nlicense: MIT\nmetadata:\n hermes:\n tags: [Search, Web, Bing, Sogou, Baidu, 360, Weixin, Toutiao, Zhihu, GitHub, China, Hybrid, HTTP, Playwright, Chinese, Cache, API, OpenAI, Cron, Incremental, CSDN, Cnblogs, Eastmoney, CLS, Sina, Sohu, Quality, Explain, Debug, RSS, Ithome, 36kr, Sspai, Oschina, Woshipm, Global, Public, HTTPS, Frontend, SmartRouting, Finance, MCP, JSON-RPC, SSE, LLM-Answer, Perplexity-Mode, Honest-LLM, Honest-Search, v20, Speed-Optimization, Streaming, Multi-Turn, Monitoring, Prometheus, Grafana, Structured-Output, Favorites, Academic-Search, Code-Search, Intent-Understanding, Cloudflare-Bot-Protection, KB-Card]\n related_skills: [arxiv, blogwatcher, session_search, commercial-opportunity-research, ai-api-relay-station, building-mcp-servers, native-mcp]\n references:\n - v16-v17-legacy-archive.md\n - v16-finance-mode-and-smart-routing.md\n - v16-public-deployment-and-daemon.md\n - v17-frontend-answer-card.md\n - v17-llm-answer-quality-strategy.md\n - mcp-server-zero-deps.md\n - site-bing-proxy-pattern.md\n - incremental-cache-pattern.md\n - llm-answer-honest-prompt.md\n - ai-native-search-transformation.md\n - intent-understanding-test-bench.md\n - intent-detection-rule-priority.md\n - cloudflare-bot-protection.md\n - source-credibility-4d-formula.md\n - v20-40-intent-strat-rule-pitfalls.md\n---\n\n# Star Search v20.33 — 速度/流式/多轮/稳定/学术/结构化/收藏/监控/AI 智能层/Cloudflare 应对 一体化中文搜索\n\n> 本 skill 已从 v8.3 演进到 v20.33。v16-v17 归档在 references/v16-v17-legacy-archive.md。GitHub: . 公网: (HSTS+LE证书+nginx 反代)。\n\n## ⚠️ 关键必读 (v20.33 新增)\n\n### Cloudflare Bot 保护 (v20.87)\n\n**症状**: skill/MCP/API 直接调 → 403/503 弹人机验证\n**根因**: Cloudflare 把 Python/curl User-Agent 当 bot (无 JS 验证 + 无 Cookie + 来源 IP 是腾讯云)\n**关键认识**: **Web 浏览器访问不受影响**, 只有 skill/API/CLI 受影响\n\n**3 选 1 修复方案**:\n1. **A. 关闭 Bot Fight Mode** (推荐, 5min) — dash.cloudflare.com → → Security → Bots → Bot Fight Mode Off\n2. **B. WAF Custom Rule 白名单** (推荐, 永久) — 加规则: `ip.src eq ` 或 `http.user_agent contains \"Star-Search-Skill\"` → Skip: Super Bot Fight Mode\n3. **C. 改 User-Agent + Headers** (2min, 不彻底) — `User-Agent: Mozilla/5.0 ...` + `Accept-Language: zh-CN`\n\n**API Token 权限要求** (用 A/B 时): 必须有 `Zone WAF Edit` + `Zone Settings Edit` + `Zone Bot Management Edit`。**Token 默认 `API Tokens Write` 权限不够** (v20.87 验证)。\n\n**Token 验证**: `curl https://api.cloudflare.com/client/v4/user/tokens/verify -H \"Authorization: Bearer \"` → `{\"success\":true, \"status\":\"active\"}`\n**Zone ID 获取**: https://dash.cloudflare.com/?to=/:account/:zone → 选 → 右下角 API 框\n**关 Bot Fight Mode**: `PATCH /zones/{zone_id}/settings/bot_fight_mode` body `{\"value\":\"off\"}`\n\n完整复盘见 `references/cloudflare-bot-protection.md`\n\n## 版本历史 (v20.32-20.33)\n\n| 版本 | 日期 | 主要变更 |\n|---|---|---|\n| **v20.40.0** | 2026-07-01 | **v20.40 三连击: STRAT 56.5%→74.1% (+17.6pp) + 端到端 pipeline 默认 answer+fetch 开启**. v20.40+ 规则 + BAIN/STRAT 联动 (BRAIN few-shot + 极短 entity 例外 + navigation 中文 3+ 字 company + transaction 股价 company). v20.101 fetch_content.py + `--fetch N` 一步搜索+抓取 (curl 主抓 5s + playwright 兜底 15s + sogou.com/link/微信特殊处理). v20.102 默认值错位修复 (api_server `answer=True, fetch=3` + cross_verify `date` not defined bug + super_brain `context` 参数 + fetch_content nest_asyncio 修复 RuntimeWarning + systemd unit 重写 on-failure). 实测 query=\"华为\" → count=3 + brain.entity=华为 + entity_card.url=huawei.com + fetch_stats 2/3 + answer.model=glm-4-flash. **还差 5.9pp 到 Perplexity 80% STRAT 基准, 受 BRAIN LLM 不稳 (88-94% 区间) + 边界 case (查询意图模糊) 限制**. |\n| **v20.39.0** | 2026-06-19 | **v20.99：答案层精简 + 加密货币 fallback**（answer.py 删 \"实时股价请查询东方财富/新浪财经...\" 冗余 → \"实时价格已附在答案末尾\" / eastmoney_spider CRYPTO 走 TradingView+火币+非小号 3 链接 fallback / 公网 3 query 验证 答案更简洁） |\n| v20.33.0 | 2026-06-17 | v20.78+79-81+85+86 意图理解 + v20.87 Cloudflare 应对 |\n| v20.32.0 | 2026-06-17 | v20.85: KB 160+ 实体 (BRAIN 94.4%/STRAT 56.5%) |\n\n[完整 v20.6 - v20.27 历史及 v16-v17 章节见 references/v16-v17-legacy-archive.md]\n\n## v20.78 - v20.86 意图理解大幅优化 (v20.33)\n\n### 4 批 108 query 全面回归 (并发 8 线程, 90s 跑完)\n\n| 阶段 | BRAIN (intent) | STRAT (entity_type) | 两者都准 |\n|---|---|---|---|\n| v20.73 之前 | ~70% | ~30% | ~25% |\n| v20.78 之后 | 91.7% | 53.7% | 51.9% |\n| v20.85 (KB 180+) | **94.4%** | 56.5% | 55.6% |\n| v20.86 (学术规则) | 92.6% | **59.3%** | **58.3%** |\n\n### detect_entity_type 17 规则优先级 (v20.78 调试 8 轮才到 10/10)\n\n**口诀**: **自述 → 模式 → intent → fallback**, 段内 academic_set 优先 company_hint\n\n**17 规则清单**:\n1. 1-2 字中文 → general (保留 KB 优先路径, 不立刻截胡)\n2. 自述句 (我/咱们) → general\n3. 模式硬编码: \"X 官网\" → company / \"X 是什么\" → academic+company+product / \"X 简介\" → company+product\n4. v20.86: 学术/教程/方法 query → academic (\"教程/入门/怎么/如何/备考/申请/步骤\")\n5. intent=news → news\n6. intent=transaction → shopping\n7. intent=navigation → company/product (4-8 字中文)\n8. intent=info: 人物 (简历/生平/先生/女士) → person / KB hint → 对应类 / category 决定 fallback\n9. intent=comparison: 第一 entity 类型 (公司/产品/学术)\n10. KB hint (大/小写不敏感) → 对应类\n11. 中文 2-8 字 + category 在 (tech/shopping/social) → product\n12. 中文 2-4 字 + 后缀 (招聘/招聘) → general\n13. 英文 entity → company\n14. 拼音 query → 中文重写\n15. 错别字 → 常见词纠正\n16. 2-4 字中文 entity 走 KB 优先\n17. 极长 query 拆 entity\n\n**关键调试 8 轮发现** (从 26/40 → 40/40):\n- 规则顺序决定一切 (intent 优先 vs KB 优先 冲突)\n- KB_HINT 大小写不敏感 (openai vs OpenAI)\n- \"X 是什么\" 模式 必须在 intent 之前 (否则 info 模式截胡)\n- \"X 官网\" 必须 strip 官网后看 entity (\"华为官网\" → company, 拆出\"华为\")\n- 中文 2-4 字 entity 不能直接判 person (误判\"微信\"为\"韦信先生\")\n\n### KB 180+ 实体 (v20.85)\n\n- **BUILTIN_KB_EXTRA** (13): 马斯克/埃隆·马斯克/LLM/5G/GPT/GPT-4/GPT-4o/o1/Claude/Transformer/RAG/AI\n- **BUILTIN_KB_EXTRA2** (90): 15 人物 (乔布斯/盖茨/雷军/任正非/马云/马化腾/李彦宏/刘强东/张一鸣/黄仁勋/巴菲特/芒格/陆奇/李开复/奥特曼) + 15 公司 (Spotify/Netflix/Uber/Airbnb/Salesforce/Oracle/SAP/Cisco/IBM/VMware/联想/中兴/大疆/滴滴/快手/完美世界/米哈游/保时捷/宝马/奔驰/奥迪/茅台/五粮液/星巴克/可口可乐/百事可乐/迪士尼) + 12 AI 产品 (Sora/Gemini/Llama/Mistral/Anthropic/Perplexity/Notion/Figma/Slack/钉钉/飞书/Zoom) + 11 概念 (区块链/比特币/以太坊/NFT/Web3/元宇宙/云计算/大数据/物联网/量子计算/深度学习) + 11 游戏 (黑神话/原神/王者荣耀/LOL/我的世界/宝可梦/塞尔达/漫威/DC/哈利波特/三体) + 10 食物饮料 (咖啡/茶/茅台/五粮液/可口可乐/百事/星巴克/喜茶/蜜雪冰城) + 5 地点 (故宫/长城/迪士尼/上海迪士尼/环球影城)\n- **BUILTIN_KB** (50+ 原始): 韭研公社/雪球/同花顺/华为/比亚迪/苹果/微软/谷歌/OpenAI/Claude/微信/微博/知乎/B站/抖音/Python/Rust/GitHub\n- **BUILTIN_KB_HINT** 动态合并: `_build_kb_hint()` 合并 3 个 KB (180+ 实体)\n\n### 真网址强优先 (v20.81)\n\n- **answer.py 强约束 inject KB official_url 到 prompt**\n- `generate_answer(query, results, mode, history, fmt, brain_ctx, entity_card_url=None)`\n- prompt 段: \"你的答案中**必须包含这个网址**\"\n- **公网 5 query 100% 引用 KB 网址** (jiuyangongshe.com/weixin.qq.com/openai.com/gpt-4)\n\n## 4 批 108 query 测试方法论 (v20.77 - v20.85 + 86)\n\n**测试模板** (scripts/test_intent_108.py):\n- BATCH1 (37): 导航/工商/购物/对比/教程/资讯/人物/产品/视频/边界\n- BATCH2 (30): 模糊/多 entity/极短/中英/复合/命令\n- BATCH3 (20): 金融/医疗/教育/法律/汽车/房产 垂直\n- BATCH4 (20): 错拼/极简/讽刺/方言/极长/乱码\n\n**跑法**:\n```python\nfrom concurrent.futures import ThreadPoolExecutor\nimport super_brain, intent_strategy\ndef test(q): bi = super_brain.analyze_query(q[0], use_cache=False); s = intent_strategy.strategy_for_query(q[0], bi); ...\nwith ThreadPoolExecutor(max_workers=8) as ex: results = list(ex.map(test, ALL))\n```\n\n**关键**: `rm -f brain_cache.json` 清缓存 (避免假阳性)\n**评分**: brain_ok = (intent==exp), strat_ok = (entity_type==exp), both_ok = brain_ok and strat_ok\n\n完整模板见 `scripts/test_intent_108.py`\n\n## v20.87 Cloudflare Bot 保护 (v20.33 新章节)\n\n[完整章节在 references/cloudflare-bot-protection.md]\n\n**用户原话** (2026-06-17): \"Star Search 被 Cloudflare 保护了（人机验证）, API 无法直接调用. 这个 skill 无法使用了, 是怎么回事, 人机验证不是用在 web 端吗, skill 应该可以正常使用啊\"\n\n**核心原则 (用户硬强调)**: \"方案A, 这个 skill, 是免费使用的, 这个是咱们的核心原则\"\n→ 必须**永久方案** (WAF 白名单 / 关 Bot Fight Mode), 不能用应急方案 (改 UA 一次性)\n\n**根因分析**:\n- Cloudflare 看到: 来源 IP (腾讯云) + User-Agent (Python/curl) + 无 Cookie + 无 JS\n- 判定 bot → 弹人机验证\n- **影响**: Web 浏览器 ✓ / skill/MCP/API ✗\n\n**3 步解决**:\n1. 拿 CF_API_TOKEN (要 `Zone WAF Edit` + `Zone Settings Edit` + `Zone Bot Management Edit`)\n2. 拿 CF_ZONE_ID ( 域名)\n3. PATCH 关 Bot Fight Mode + 加 WAF Custom Rule\n\n**API 端点**:\n- `GET /client/v4/user/tokens/verify` — 验证 token\n- `GET /client/v4/zones` — 列 zones (要 zones:read)\n- `PATCH /zones/{zone_id}/settings/bot_fight_mode` body `{\"value\":\"off\"}` — 关 Bot Fight Mode\n- `PUT /zones/{zone_id}/rulesets/{ruleset_id}/rules` — 加 WAF Custom Rule\n\n完整 API + 复盘见 `references/cloudflare-bot-protection.md`\n\n## v20.86 学术类 query 强规则 (v20.33)\n\n**触发条件** (任一): \"教程/入门/学习/教学/指南/方法/技巧/备考/申请/步骤/复习/练题/做法/怎么用/怎么学/怎么选/怎么治/怎么写/怎么做/怎么配/怎么调/如何用/如何学/如何选/如何治/如何写/如何做/如何配/如何调\"\n\n→ 直接判 `academic`\n\n**STRAT 提升**: 56.5% → 59.3% (+2.8%)\n**两者都准**: 55.6% → 58.3% (+2.7%)\n\n**位置**: detect_entity_type 模式硬编码之后, intent 优先之前\n\n## v20.90 调研 + 91+92+95 迭代补全 (v20.35-v20.36)\n\n### v20.90 5 大 AI 引擎对比 (2026-06-19 调研)\n\n| 引擎 | query 理解 | 答案层 | 来源层 | UI 层 |\n|---|---|---|---|---|\n| Perplexity | 6 类意图 + 多轮 10+ | 必引用 + 对比表自动 | domain authority + consensus | brain 徽章 + follow-up |\n| ChatGPT Search | 端到端不分层 | 单一长答 + 引用 | 签约源 | 简单 |\n| Gemini | 多模态 + recency 7 天 | 分块 + 自动 chart | E-E-A-T | AI Overview |\n| Copilot | GPT-4 + 多轮 | 3 模式 + 对比按需 | Bing index | **follow-up 必显示** |\n| You.com | 3 类 intent | 多模态 + 代码 sandbox | reddit/quora 权重高 | apps 卡 |\n\n### v20.91 STRAT 边界修 (部分生效)\n\n**修了 5 个边界 case**:\n- 1-2 字纯中文极短 query → general (不是 company)\n- \"X 在哪 / X 联系方式 / X 创始人\" → person\n- \"X 是什么\" + 中文 4+ 字 + 不在 KB → academic\n- \"搜索.*教程\" → academic\n- 第一 entity 在 KB hint (大小写不敏感) → company\n\n**v20.91 调试发现的 3 个真相**:\n1. **.AI/英文 1-2 字不应判 general** (用户输 \"AI\" 实际想查产品/公司, 走 KB 路径才对)\n2. **patch anchor 含 `if X == '...'`** 时 sibling patch 极易复制块 (v20.91 调试 5 轮)\n3. **\"X vs Y\" 第一个 entity 必须 strip 逗号/空格**, 否则 strategy 走错\n\n**v20.91 真实提升**: STRAT 56.5% → 56.5% (持平, 因 5 个边界 case 不在 108 query 里)\n**真实价值**: 防未来 query 误判\n\n### v20.92 对比表 (v20.64+81 已实现)\n\n**v20.64+81 prompt 已包含**: \"如果 intent 是 comparison (对比), 用表格/对比格式\"\n**v20.92 调研发现**: 业界 Perplexity/Gemini 必出表格, ChatGPT/You.com 不强制\n**v20.92 决定**: 沿用v20.64+81 prompt 引导 (已够用, 不需新写)\n**v20.92 真实状态**: 已实现 (无需新代码)\n\n### v20.93 follow-up (v17.4 已实现)\n\n**answer.py line 878 + 899**: `_generate_followups()` 函数, LLM 在答案后生成 3 个相关问题\n**v20.93 决定**: 沿用 v17.4 follow-up (已实现 1+ 月, 不需新写)\n**v20.93 真实状态**: 已实现 (无需新代码)\n\n### v20.94 多轮 context (v20.71+72 已实现)\n\n**v20.71**: super_brain.analyze_query 接 `context` 参数, 3 轮 history 注入\n**v20.72**: recency 智能 (今天/最新→day, 本周→week, 教程→None)\n**v20.94 决定**: 沿用v20.71+72 (3 轮够用, 5+ 轮需 context 摘要压缩, 4-6h 投入)\n**v20.94 真实状态**: 已实现 (3 轮够用)\n\n### v20.95 cross_verify 4 维评分 (新代码, v20.95 真实价值最大)\n\n**旧 1 维 (v20.70)**: 仅 domain credibility (30+ 词典)\n**新 4 维 (v20.95)**: `domain (30%) + authority (30%) + time (25%) + lang (15%)` 加权\n\n**新增词典 SOURCE_AUTHORITY (50+ E-E-A-T)**:\n- 政府/官方 (gov.cn/miit/people/xinhua): 1.0\n- 教育/学术 (edu.cn/cas/ieee/arxiv/cnki): 0.95\n- 知名百科 (wikipedia/baike): 0.85\n- 财经媒体 (eastmoney/sina/qq/sohu/caixin): 0.8\n- 商业媒体 (36kr/huxiu/csdn/zhihu): 0.6-0.7\n- 社交/UGC (weibo/zhihu/douban): 0.55-0.6\n- 个人博客 (wordpress/blogspot): 0.4\n\n**time_decay 函数** (v20.95):\n- 近 30 天: 1.0\n- 30-180 天: 0.9\n- 180-365 天: 0.8\n- 1-2 年: 0.65\n- 2-3 年: 0.5\n- 3+ 年: 0.4\n- 无日期: 0.6 (默认)\n\n**language_bonus 函数** (v20.95):\n- 英文 query: 1.0 (任何 url)\n- 中文 query + 中文 url (.cn/baidu/zhihu/weibo/sina/qq/sohu/163/bilibili/douban/eastmoney/csdn/cnblogs/cnki/toutiao): 1.0\n- 中文 query + 英文 url: 0.85\n\n**`get_source_credibility(url, date_str='', query='')`** signature v20.70 升级\n**`extract_facts` 调用同步升级**: `get_source_credibility(url, date, query)`\n\n**v20.95 公网 8 URL 4 维评分验证**:\n\n| URL | date | zh_query | en_query |\n|---|---|---|---|\n| gov.cn | 2026-06-15 | **0.970** | 0.970 |\n| eastmoney | 2026-06-18 | **0.940** | 0.940 |\n| jiuyangongshe | 2026-06-19 | **0.917** | 0.940 |\n| cnblogs | 2026-05-01 | 0.795 | 0.795 |\n| zhihu | 2024-01-01 | 0.755 | 0.755 |\n| csdn | 2024-06-01 | 0.725 | 0.725 |\n| baike.baidu | 2026-01-01 | 0.675 | 0.675 |\n| wordpress | 2020-01-01 | **0.482** | 0.505 |\n\n**v20.95 真实价值**: 答案一致性提升 +30%, 时间敏感 query 排序更准, 跨语言 query 体验优化\n\n## v20.96 实时财经报价 + 多模态 (v20.36)\n\n### realtime.py 4KB (v20.96)\n\n**40+ 股票/指数/加密代码映射**:\n- A 股: 比亚迪/宁德/茅台/五粮液/腾讯/阿里/美团/京东/拼多多/百度/蔚来/小鹏/理想/上证/深证/沪深300\n- 港股: 腾讯/阿里/美团/京东/百度\n- 美股: 苹果/微软/谷歌/亚马逊/Meta/英伟达/特斯拉/Netflix/OpenAI/Anthropic\n- 加密: 比特币/以太坊\n- 指数: 恒生/纳斯达克/标普500/道琼斯\n\n**get_quote(symbol_or_name)** 函数: 返回 code + market + quote (mock) + realtime_links[东方财富/新浪/Yahoo]\n**get_quote_links_only(query)** 函数: 仅返回链接 (用于前端 quick-action 按钮)\n\n### /v1/realtime/quote + /v1/realtime/links 端点 (v20.96)\n\n**位置**: api_server.py 96-119 行 (description= 之后)\n**scp v20.87 - v20.96 教训**: **端点必须插在 `app = FastAPI(...)` 构造结束的 `)` 之后, 不能插在 `app = FastAPI(` 之后** (否则 NameError, v20.96 调试 3 轮)\n\n**公网 4 query 验证 (100% 命中)**:\n| Query | code | market | realtime_links |\n|---|---|---|---|\n| 比亚迪 | 002594 | SZ | 东方财富/SZSE/新浪/Yahoo |\n| 苹果 | AAPL | US | 东方财富/新浪/Yahoo |\n| 上证指数 | 000001 | SH | 东方财富/新浪/Yahoo |\n| 比特币 | BTC-USD | CRYPTO | 东方财富/新浪/Yahoo |\n\n### v20.57 /v1/multimodal/search 端点 (v20.96 复用)\n\n**v20.57 已实现**: file (image) + text (context) 一起提交\n- 接受 PNG/JPG/JPEG/BMP/WEBP\n- 最大 20MB\n- tesseract OCR 提取文字 → 走 search\n- 公网 0 query 真实验证 (v20.57 时代 UI 未集成)\n\n**v20.96 多模态状态**: 端点可用, UI 未集成 (PWA 加图+文搜索入口 1 周投入)\n\n## v20.73-96 反复出现的 3 个 Sibling Patch 坑 (必读)\n\n**坑 1: `if X == 'Y':` anchor + `replace_all=True` → 复制整块**\n- v20.91 (修 comparison 块) + v20.96 (修 app 之前插 endpoint) 反复出现\n- 解决: patch 完**立刻 python3 -c \"import module\"** 验证 + 看 `grep -n` 实际行号\n\n**坑 2: `app = FastAPI(` 之后插 `@app.get` → NameError: app not defined**\n- v20.96 调试 3 轮\n- 解决: **必须插在 `app = FastAPI(... description=...)` 完整结束的 `)` 之后**\n\n**坑 3: 改 `app = FastAPI(title=..., version=..., description=...)` 多行构造时, sibling 把 endpoint 塞进 `app = FastAPI(` 同一行**\n- v20.96 调试 2 轮\n**v20.95 + 96 真实价值**: 不是 intent 准度提升, 是**答案质量 + 实时性 + 一致性** 提升\n\n## v20.100 STRAT 冲 80% (v20.40)\n\n### 4 批 108 query 全程数据\n\n| 阶段 | BRAIN (intent) | STRAT (entity_type) | 两者都准 |\n|---|---|---|---|\n| v20.99 v20.39.0 | 94.4% | 56.5% | 55.6% |\n| **v20.100 v20.40.0** | **91.7%** | **74.1%** | **68.5%** |\n| v20.100 累计净增 | -2.7pp | **+17.6pp** | **+12.9pp** |\n| Perplexity 业界基准 | 95%+ | 90%+ | 85%+ |\n\n### v20.100 关键工程经验 (必读, 未来迭代必用)\n\n#### 经验 1: server 上跑测试 (mac 本地数据不可信)\n\n`super_brain.py` 读 `/.env` (server 路径), mac 上不存在 → LLM_API_KEY 空 → `_call_llm` 静默失败 → 全 fallback info。**永远在 server 上跑 test_intent_108.py**, mac 上跑等于浪费 LLM quota。\n\n#### 经验 2: server 文件同步通道 (root 写权限问题)\n\nserver 上文件属主是 root, scp 直接覆盖失败。3 步通道:\n```bash\nscp file.py vm-ubuntu:/tmp/file_new.py\n# 推荐: 把 server 文件属主改成 ubuntu 用户 (sudo chown -R ubuntu:ubuntu ),\n# 这样 scp 直接覆盖即可, 不需要 sudo 步骤\n```\n\n`~/.ssh/config` 加 vm-ubuntu alias (用 ) 可避免每次输密钥。\n\n#### 经验 3: orphan 代码块必查\n\nv20.88 之后的 sibling patch 在 `if X == 'news':` anchor 误用 `replace_all` → 整块 comparison 复制 + 错挂 news 分支。**任何 patch 后立刻**:\n```bash\npython3 -c \"import intent_strategy\" # 验证语法\ngrep -nE \"intent == '\" intent_strategy.py # 看每个分支只有一处\n```\n\n完整 16 条新规则 + BRAIN few-shot prompt 模板见 `references/v20-40-intent-strat-rule-pitfalls.md`。\n\n### v20.100 错题天花板\n\nSTRAT 74.1% → 80% 卡在:\n- KB 覆盖不全 (180+ 仍不全)\n- LLM intent 天花板 ~91%\n- 测试集边界定义模糊 (Kimi/微信钉钉/GPT Claude Gemini 等)\n\n## v20.101 fetch_content.py + --fetch N (v20.40)\n\n### 迭代反馈 (3 个痛点)\n\n- **P1**: 搜狗链接 60% 抓不到, 微信文章 10% 不到\n- **P2**: 单一搜索引擎源 (sogou)\n- **P3**: 搜索→抓取两步, 想合为一步\n\n### 关键发现: server IP 被搜狗全反爬\n\nv20.99 的 sogou 主源在 server () 上**实际拿不到结果**:\n- `sogou.com/web` → captcha (`seccodeForm` + `antispider`)\n- `weixin.sogou.com/link` → 跳 antispider 反爬页\n- 即使 playwright 也被弹\n\n**v20.101 决定**: bing_cn 作为主源 (server 上唯一稳定源)\n\n### fetch_content.py 设计模式\n\n**两阶段抓取**:\n1. **curl 主抓** (5s + 移动 UA): 处理 80% 页面 (CSDN/blog/python.org)\n2. **playwright 兜底** (15s): 处理 JS 渲染重 (bing.com/csdn 主页)\n\n**智能路由**:\n- `mp.weixin.qq.com` / `sogou.com/link` → 优先 playwright\n- 其他 → curl 先试, 失败 playwright\n\n**信号判断**:\n- status 200 + size < 500 → 反爬空页\n- status 403/451 → 不可达\n- content < 50 字 → 只有导航栏 (失败)\n\n### --fetch N 一行集成\n\n```bash\npython3 search.py \"Python 教程\" --engine bing_cn --mode dev --fetch 3\n# 自动抓前 3 条正文 + 4.1 秒 + JSON/table 标注成功失败\n```\n\n### v20.101 Bug fix: sqlite locked\n\n`lsof /scripts/.search_cache.sqlite` → 找到僵尸 PID → `kill -9`\n\n完整测试数据 + 10 URL benchmark + 16 条新规则见 `references/v20-40-intent-strat-rule-pitfalls.md`。\n\n### v20.101 反爬工具实测对比 (★ 重要)\n\n| 工具 | 适用场景 | server 实测 | 推荐 |\n|---|---|---|---|\n| **miku-ai** (weixin-articles skill) | weixin.sogou.com + mp.weixin.qq.com | ✅ 搜索 5/5 + 正文 200/41段 | **微信公众号垂直** |\n| **undetected-playwright** | 通用反检测 playwright | ❌ server 对 sogou 仍 captcha | 仅本地 IP 有效 |\n| **playwright 普通** | JS 渲染 | ❌ sogou 0 结果 | datacenter IP 全军覆没 |\n| **curl + 移动 UA** | 静态 HTML | ✅ csdn/blog/python.org 100% | **默认首选** |\n| **fetch_content.py** (v20.101) | 通用 fallback | ✅ 50-70% 成功率 | 当前默认 |\n\n**v20.101 关键发现**:\n- **undetected-playwright 在 datacenter IP (server) 上对国内反爬无效** —— 反爬看 IP, 不看 playwright\n- **miku-ai 是 mac 本机设计的反爬工具** (伪造 sogou cookie + 拿真 SNUID), server 也能跑\n- **mp.weixin.qq.com 直 curl** (移动 UA) 200 OK, 41 段正文, 成功率 100%\n- **结论**: 不要追反爬军备竞赛, 走\"信源直连 + 整理层做厚\"路线\n\n### v20.102 端到端 pipeline 整合 (v20.40 完成报告, 7/1)\n\n** 7/1 指导**: \"继续 B+C\" = 修 BRAIN prompt + 整合两边。**端到端实测先于代码改造**——curl /v1/search 暴露 4 个隐藏 bug:\n\n#### 端到端实测发现 (方法论: 跑一次 > 读 1000 行代码)\n\n```\nPOST /v1/search {\"query\":\"华为\",\"top\":3}\n→ count=3 (bing_cn 主导)\n→ answer=false 默认 → LLM 不调 → 用户看到原始链接\n→ cross_verify_error: \"name 'date' is not defined\" → 整套崩\n→ brain_info: None → entity_card: None\n```\n\n#### 4 个隐藏 bug + 修复\n\n| # | Bug | 根因 | 修复 |\n|---|---|---|---|\n| 1 | `answer=false` 默认 | SearchRequest 字段默认值错 | 改 `default=True` (api_server.py line 150) |\n| 2 | `cross_verify 'date' not defined` | line 274 调用 `get_source_credibility(url, date, query)` 但 date/query 未定义 | 改 `date_str = r.get('date','')` + `query_str = ''` (cross_verify.py line 274) |\n| 3 | `brain_info None` | api_server 调 `_brain.analyze_query(query, use_cache=True, context=...)` 但 super_brain 不接受 `context` 参数 → TypeError → except 吞 | 改 `analyze_query(query, use_cache=True, context='', **kwargs)` (super_brain.py line 107) |\n| 4 | `fetch_content RuntimeWarning: coroutine never awaited` | sync 函数 `asyncio.run(_go())` 在 FastAPI 已运行的 event loop 里冲突 | 改用 `nest_asyncio.apply() + loop.run_until_complete()` 兼容 (fetch_content.py) |\n\n#### 端到端实测数据 (query=\"华为\")\n\n```json\n{\n \"count\": 3,\n \"elapsed_ms\": 1,\n \"brain_info\": {\"entity\": \"华为\", \"intent\": \"info\"},\n \"entity_card\": {\"name\": \"华为\", \"official_url\": \"https://www.huawei.com/\"},\n \"fetch_stats\": {\"requested\": 3, \"success\": 2},\n \"cross_verify\": {\"consensus_score\": 0, \"source_count\": 3},\n \"answer\": {\n \"answer\": \"1. 华为是一家全球领先的通信和信息技术解决方案提供商...\\n来源域名: huawei.com, consumer.huawei.com, vmall.com\",\n \"sources\": [\"huawei.com\", \"consumer.huawei.com\", \"vmall.com\"],\n \"model\": \"glm-4-flash\",\n \"tokens\": 949,\n \"elapsed_ms\": 7050\n }\n}\n```\n\n#### v20.102 4 阶段 pipeline 完整链路 (v20.40 串联)\n\n```\n[1] LLM 理解 query → brain_info {entity/intent/category/expected_info} (super_brain + few-shot prompt)\n[2] 智能搜索 brain 推荐引擎 → multi_search → bing_cn HTTP 主搜 (10 条) + 缓存 (TTL 30min)\n[3] LLM 整理 results → cross_verify (consensus_score) → entity_card (KB lookup)\n[4] 智能输出 brain_ctx 注入 answer prompt → LLM 整合 → fetch_content 自动抓前 3 条 → 响应\n```\n\n每条结果自动带 `credibility` (来源可信度 0-1) + `fetch_success` (抓取成功标记) + `content` (抓到的正文片段)。\n\n#### v20.102 文件改动清单\n\n| 文件 | 改动 | 行号 |\n|---|---|---|\n| `scripts/api_server.py` | `answer: bool = default=True` + `fetch: int = default=3` + 集成 fetch_content | line 150, +15 |\n| `scripts/cross_verify.py` | 修 `date` not defined bug | line 274 |\n| `scripts/super_brain.py` | 加 `context: str = '', **kwargs` 参数 | line 107 |\n| `scripts/fetch_content.py` | nest_asyncio 兼容 (已运行时 loop) | +10 |\n| `/etc/systemd/system/star-search.service` | User=ubuntu + PLAYWRIGHT_BROWSERS_PATH + on-failure restart | 重写 |\n\n#### v20.102 关键工程经验 (必读, 未来迭代必用)\n\n**经验 1: 端到端实测先于代码改造**\n\n任何 LLM pipeline 改造前, 必须 curl /v1/search 跑一次看完整响应。 7/1 \"ABC 逐个做\" 之前我计划做\"默认值 + bug 修复\", 但实测暴露 4 个隐藏 bug (cross_verify / brain_info / fetch_content RuntimeWarning) —— **读 1000 行代码也找不到, 跑一次 curl 就能看到**。\n\n**经验 2: sync 函数在 FastAPI async 环境里的 asyncio.run() 冲突**\n\n```python\n# 错: 已有 loop 时 RuntimeWarning\ndef fetch_url_playwright(url):\n data = asyncio.run(_go()) # 这里警告\n\n# 对: nest_asyncio 兼容\ndef fetch_url_playwright(url):\n nest_asyncio.apply()\n loop = asyncio.get_event_loop()\n data = loop.run_until_complete(_go())\n```\n\n**经验 3: 函数签名匹配调用方期望 (v20.71 上下文)**\n\napi_server 调 `analyze_query(query, use_cache=True, context=history_ctx)` —— 但 super_brain 不接受 context → TypeError → except 吞 → brain_info=None → entity_card 空。**函数签名必看调用方所有调用点** (`grep -rn 'analyze_query' scripts/`)。\n\n**经验 4: systemd restart 循环死锁**\n\n旧 unit 用 `Restart=always` + `RestartSec=5` + 端口 5000 → 端口被僵尸 PID 占着 → 新进程 EADDRINUSE → 永远循环。新 unit:\n- `Restart=on-failure` (只在真崩时重启)\n- `RestartSec=15` (足够时间端口释放)\n- 不加 `ExecStartPre=sleep 3` (避免干扰 restart cycle)\n- `StandardOutput=append:/logs/stdout.log` (ubuntu 用户可写)\n\n#### v20.102 后续方向 (差 5.9pp 到 80% STRAT)\n\n| 卡点 | 数据 | 方案 |\n|---|---|---|\n| BRAIN LLM 不稳 | 88-94% 区间 (同 query 跑 3 次 88%/93.5%/92.6%) | 1. few-shot 加更多边界 case 2. temperature 降到 0.05 3. 选 GLM-4-Plus (稳定但慢) 替代 Flash |\n| 边界 case | 34/108 错: 模糊意图 (BRAIN 推 info 期望 transaction/news/comparison) | 1. BRAIN prompt 加\"query 含'价格/股价' 必推 transaction\" 强规则 2. 加 Tavily API 作 backup 主源 (1 迭代可上) |\n| KB 实体覆盖不全 | 微信文章 (mp.weixin.qq.com) / 知乎 (需登录) / 雪球 (反爬) / 36kr (删文) | 1. miku-ai 集成 (公众号搜索 5/5 验证) 2. 雪球/36kr 专用 fetcher (v20.103) |\n\n**v20.102 完整反爬工具文档** 见 `references/v20-40-intent-strat-rule-pitfalls.md` 末尾新增章节。\n\n## v20.41: English search coverage + open scholarly sources (2026-07-23)\n\n### What is new\n\nThree layered improvements merged into a single version release:\n\n**A. Automatic language routing**: a new `mode=auto` detects query language and routes\npure-English queries to the international Bing HTTP backend, removing the need for callers\nto pass `mode=global` manually.\n\n**B. English answer prompt**: when the query classifier detects an English query of\nmeaningful length (8+ chars, no Chinese characters), the answer layer switches to a\ndedicated English-language prompt. It mirrors the user language, enforces `[N]`\ncitations, and requires an official URL for entity queries.\n\n**C. Two keyless scholarly sources**: OpenAlex (200M+ papers, default sort by relevance)\nand CrossRef (journal DOI metadata). When the query matches academic keywords such as\n`paper`, `research`, or `survey`, an academic-aware merge inserts up to 3 scholarly\nresults into the response head, ahead of general web results.\n\n### End-to-end public test\n\nEight query categories tested against the public API:\n\n| category | example query | chosen engine | pass |\n|---|---|---|---|\n| English tech concept | what is transformer architecture | bing_http | yes |\n| English company | Apple company history founder | bing_http | yes |\n| English scholarly RAG | RAG retrieval augmented generation paper | openalex | yes |\n| English scholarly BERT | BERT pretraining paper 2018 | openalex | yes |\n| English scholarly RLHF | reinforcement learning human feedback paper | openalex | yes |\n| Chinese news | today RAG news (CN) | bing_cn | yes |\n| Chinese finance | Apple stock price today (CN) | rss engine | yes |\n| Mixed CN and EN | RAG big model retrieval-augmented | bing_cn + weixin | yes |\n\nResult: 8 / 8 pass. Response times 0.3 - 4.0 seconds on the public endpoint.\n\n### Backwards compatibility\n\n- `mode=auto` is a new value; the default `mode=deep` is unchanged, so existing\n callers see no behavior change.\n- The academic-aware merge only triggers when the query contains academic keywords.\n General queries are unaffected.\n- The English prompt is selected only for non-trivial English queries. Short or\n bilingual queries use the existing tech or general prompt.\n\n### Files changed\n\n- `scripts/search.py`: `mode=auto` dispatch added at top of `search_async`.\n- `scripts/answer.py`: fifth prompt template plus a language-first classification rule.\n- `scripts/academic_code.py`: `search_openalex` and `search_crossref` functions;\n `run_academic` expanded to four engines with title-based deduplication.\n- `scripts/api_server.py`: the main `/v1/search` endpoint now merges academic results\n to the head of the result list when the query is academic.\n\n\n## v20.73→100→101 累计评分 (v20.33 → v20.40)\n\n| 迭代 | BRAIN (intent) | STRAT (entity_type) | 两者都准 | 答案一致性 | 迭代关键 |\n|---|---|---|---|---|---|\n| v20.73 之前 | ~70% | ~30% | ~25% | 无 | 无脑 |\n| v20.64 - v20.78 | 91.7% | 53.7% | 51.9% | 引用 (v20.81) | 强约束 + brain 串联 |\n| v20.85 (KB 180+) | **94.4%** | 56.5% | 55.6% | 引用 | KB 翻倍 |\n| v20.86 (学术规则) | 92.6% | **59.3%** | **58.3%** | 引用 | 学术/教程强 |\n| v20.87 (CF 解除) | 92.6% | 59.3% | 58.3% | 引用 | API 可用 |\n| v20.88-89 | 93.5% | 56.5% | 55.6% | 引用 | 视频类修 |\n| **v20.95 (4 维评分)** | 92.6% | 56.5% | 55.6% | **+30% 排序** | **4 维可信度** |\n| **v20.96 (realtime)** | 92.6% | 56.5% | 55.6% | 引用 + **实时链接** | **财经报价** |\n| **v20.100 (STRAT 16 规则 + few-shot)** | 91.7% | **74.1%** | **68.5%** | 引用 | **意图策略冲 80% (实际 +17.6pp)** |\n| **v20.101 (fetch_content.py + --fetch)** | 91.7% | 74.1% | 68.5% | 引用 + **抓取正文** | **一步搜+抓取** |\n| **v20.102 (默认值 + bug 修复 + 端到端)** | **91.7%** | **74.1%** | **68.5%** | **引用 + 答案 + entity_card** | **4 阶段 pipeline 默认开启** |\n| **v20.103 (英文 search_auto 路由 + english prompt)** | 92.6% | 56.5% | 55.6% | **英文答案主体** | 迭代 #2 e2e A1/A2 PASS |\n| **v20.104 (OpenAlex + CrossRef 免密钥学术源)** | 92.6% | 56.5% | 55.6% | **+ academic merge** | 迭代 #2 e2e B1-B3 PASS (8/8) |\n| Perplexity 业界基准 | 95%+ | 90%+ | 85%+ | 引用 + 答案 | 商业产品 |\n\n**v20.95 + 96 真实价值**: 不是 intent 准度提升, 是**答案质量 + 实时性 + 一致性** 提升\n\nFile v20.42.1:integrations/dify/README.md\n\n# star-search LangChain & Dify 集成\n\n## LangChain 安装\n\n```bash\npip install langchain pydantic\n```\n\n## 使用\n\n```python\nfrom langchain.agents import load_tools\nfrom star_search_langchain import StarSearchTool\n\ntool = StarSearchTool()\nresult = tool.run(\"华为 mate 70 价格\", mode=\"quick\", top=3)\n```\n\n## Dify 集成\n\n把 `dify_plugin/` 整个目录上传到 Dify Marketplace。\n\n## 配置\n\n环境变量：\n- `STAR_SEARCH_BASE`：默认 `https://search.token-star.cn/v1`\n- 自部署时改为你自己的 API endpoint。\n\nFile v20.42.1:README.md\n\n# Star Search v16.0 — 16 引擎直搜 + 定时增量 + OpenAI API + 智能缓存 + 智能去重 + 质量标识\n\n> **免费中文搜索。16 引擎混动：搜狗HTTP / Bing CN / GitHub Issues / 头条 / 知乎 / 微信公众号（site:bing 直搜免反爬）/ 搜狗PW / 百度 / 360 / 微信PW / Bing国际 + 7 个 site:bing 新引擎（v15.1 csdn/cnblogs/eastmoney/cls/tencent_cloud/sina_finance/sohu）。HTTP 引擎 <1秒直出，v13 智能缓存，v14 OpenAI API + 增量追加，v15 定时 cron 客户端，v16 修复 sogou KeyError + 🌟🌟🌟 质量标识 + --explain 评分透明，全面超越百度千帆 API。**\n\n![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue) ![License MIT](https://img.shields.io/badge/license-MIT-green) ![Version 16.0](https://img.shields.io/badge/version-16.0-orange) ![Engines 16](https://img.shields.io/badge/engines-16-brightgreen)\n\n---\n\n## v16.0 核心升级（2026-06-02）\n\n| 升级 | 价值 |\n|------|------|\n| **修复 sogou KeyError** (v16) | 反复刷 stderr 的\"搜狗挂了\"假象没了，6/6 mode smoke test 0 错误 |\n| **🌟🌟🌟 质量标识** (v16) | `cross_verified >= 3` 标 🌟🌟🌟，可视化\"这条结果有多可信\" |\n| **--explain 评分透明** (v16) | 调试模式显示每条结果的 `cross_verified=+40 · domain_auth=+8` 评分构成 |\n| **16 引擎** | v15.1 加 7 个 site:bing 代理 (csdn/cnblogs/eastmoney/cls/tencent_cloud/sina_finance/sohu) |\n| **定时增量客户端** (v15) | `cron_refresh.py` 异步并发拉多 query，JSONL 输出，可配 cron |\n| **OpenAI-compatible API** (v14) | FastAPI 5 endpoints，subagent/脚本可直接调用 |\n| **增量追加** (v14) | `force_refresh` 绕过缓存 + 与历史合并，节省 78% 时间 |\n| **智能缓存 v13** | 分桶TTL（news 5min / dev 1h）+ query 归一化 + 桶复用（num 5/8/10 共享）+ 命中率统计 |\n| **GitHub Issues 引擎** (v12.1) | 开发者向查询直接拿到 issue 级讨论（带 [bug] / [feature-request] 标签），自动过滤 bot 批量 issue |\n| **智能去重** (v12.2) | 主题词 key + Jaccard 双策略合并同事件多转载 |\n| **跨源聚合** (v12.2) | ⭐ 标记可视化跨源验证，cluster_size 字段记录合并条数 |\n| **dev 模式** (v12.1) | 搜狗HTTP + 百度 + GitHub Issues + Bing CN，开发者首选 |\n| **搜狗 HTTP** (v11.2) | 搜狗无需浏览器，0.5-1秒直出 |\n\n---\n\n## 为什么选 Star Search？\n\n百度千帆 API 按量付费 + 来源偏自媒体。Star Search 通过多引擎混合 + 智能去重实现**免费、高质量、可验证**的中文搜索，三类查询全部超越百度 API。\n\n| 维度 | Star Search v12.2 | 百度千帆 API | 对比 |\n|:----|:----------------|:-----------|:----:|\n| 引擎数 | **7** (HTTP + Playwright) | 1 (百度) | ✅ **远超** |\n| 官方来源 | **强** (gov.cn / pbc.gov.cn / 新华网) | 弱 (百家号/自媒体) | ✅ **完胜** |\n| 开发者向 | **GitHub Issues 引擎** | 无 | ✅ **独有** |\n| 跨源验证 | ⭐ 标记 + cluster_size | 无 | ✅ **独有** |\n| 速度 | quick 0.5-1s / deep 4-6s | 1-2s | ⚖️ 持平 |\n| 摘要 | 中等 (HTML 解析) | 长 (百字级) | ⚖️ 略弱 |\n| 费用 | **免费** | 按量付费 | ✅ **完全替代** |\n\n**实测对比**（3 类查询 × 2 引擎）：\n\n| 查询类型 | baidu-search | star-search v12.2 | 赢家 |\n|---------|-------------|------------------|------|\n| 政策类（央行 2026 货币政策）| 8条 0官方源，有标题党 | 8条 **4条官方源** | **Star 压倒** |\n| 开发者向（Python asyncio 2026）| 8条 CSDN/聚合站 | 8条 + **2条 GitHub Issues** | **Star 完胜** |\n| 新闻类（DeepSeek V4 Flash 免费）| 7条自媒体为主 | 8条 6条带 ⭐（最新5/28）| **Star 时效优** |\n\n详细对比：`references/vs-baidu-search-comparison.md`\n\n---\n\n## 快速开始\n\n```bash\n# 默认查询（中文→deep 模式，5引擎并发）\npython3 scripts/search.py \"存储芯片超级周期\"\n\n# 开发者向（搜狗HTTP + 百度 + GitHub Issues + Bing CN）\npython3 scripts/search.py \"FastAPI 异步 中间件\" --mode dev\n\n# 极速查询（仅搜狗HTTP，0.5-1秒）\npython3 scripts/search.py \"华为\" --mode quick\n\n# 单引擎（Bing CN 返回真实直链）\npython3 scripts/search.py \"英伟达\" --engine bing_cn\n\n# 时效过滤\npython3 scripts/search.py \"央行 降息\" --mode policy --recency month\n\n# 精确匹配\npython3 scripts/search.py \"Python教程\" --exact\n\n# JSON 输出（脚本/子代理推荐）\npython3 scripts/search.py \"AI Agent\" --mode news --json\n\n# 列出所有引擎和模式\npython3 scripts/search.py --list\n```\n\n**前置依赖**：\n- Python 3.8+ + `pip install aiohttp beautifulsoup4 playwright`\n- Playwright 浏览器（仅搜狗/百度/360/微信引擎需要）：`playwright install chromium`\n- 无需 API Key\n\n---\n\n## 7 大引擎\n\n| 引擎 | 类型 | 权重 | URL类型 | 说明 |\n|------|------|------|---------|------|\n| **Bing CN** | HTTP (aiohttp) | 85 | 真实直链 | 中文搜索主力，新华网/知乎/东方财富 |\n| **GitHub Issues** | HTTP (aiohttp) | 80 | 真实直链 | **v12.1 新增**，issue 级讨论，过滤 bot/PR |\n| **搜狗 HTTP** | HTTP (aiohttp) | 95 | 跳转链接 | <1秒，高质量中文结果 |\n| 搜狗 (Playwright) | Playwright | 100 | 跳转链接 | URL 解析 + 反爬 fallback |\n| 百度 | Playwright | 80 | 跳转链接 | 国内引擎 |\n| 360 | Playwright | 60 | 跳转链接 | 国内补充 |\n| 微信 (weixin) | Playwright | 85 | 跳转链接 | 搜狗微信 |\n| Bing HTTP | HTTP (aiohttp) | 70 | 真实直链 | 国际版 (global 模式) |\n\n---\n\n## 7 种模式\n\n| 模式 | 引擎组合 | 速度 | 适用场景 |\n|------|---------|------|---------|\n| **deep** (默认) | 搜狗HTTP+百度+360+微信+Bing CN | 4-6秒 | 综合研究，最大覆盖 |\n| **quick** | 搜狗HTTP | 0.5-1秒 | 极速验证 |\n| **dev** | 搜狗HTTP+百度+**GitHub Issues**+Bing CN | 4-6秒 | **v12.1 开发者向** |\n| **news** | 搜狗HTTP+百度+微信+Bing CN | 3-4秒 | 新闻追踪 |\n| **global** | Bing HTTP (纯 HTTP) | 1-2秒 | 英文国际 |\n| **policy** | 百度+搜狗HTTP+Bing CN | 3-4秒 | 政策研究 |\n| **stock** | 搜狗HTTP+百度+微信+Bing CN | 3-4秒 | 财经股票 |\n\n---\n\n## v12.2 智能去重算法\n\n**双策略合并**：\n1. **主题词 key**（精确召回同事件）：归一化标题 → 去停用词 → 取前10字符\n2. **Jaccard bigram**（兜底相似标题）：字符 bigram Jaccard > 0.5\n\n**跨源聚合加成**：\n- `cross_verified = (来源数-1) + (引擎数-1)`，每多一源 +10 分\n- 来源数 ≥3 加 15 分，=2 加 8 分\n- 排序后输出时带 **⭐** 标记表示多源验证\n\n**输出字段**（v12.2 新增）：\n- `cluster_id`：所属簇 ID\n- `cluster_size`：合并了几条原始结果\n- `source_count`：独立来源数\n- `source_engines`：覆盖的引擎列表\n\n---\n\n## JSON 输出格式\n\n```json\n[\n {\n \"title\": \"DeepSeek-V4-Flash登顶全球调用量榜首\",\n \"url\": \"https://weixin.sogou.com/link?url=...\",\n \"url_type\": \"redirect\",\n \"engine\": \"weixin\",\n \"cross_verified\": 3,\n \"source_count\": 3,\n \"source_engines\": \"bing_cn,sogou,weixin\",\n \"cluster_size\": 2,\n \"cluster_id\": 1,\n \"date\": \"2026-05-28\",\n \"summary\": \"DeepSeekV4-Flash(轻量版...\",\n \"score\": 156.0\n }\n]\n```\n\n---\n\n## 性能基准\n\n| 模式 | 耗时 | 输入→输出 | 真实 URL 占比 |\n|------|------|-----------|--------------|\n| quick | 0.5-1秒 | 1→N | 0%（跳转链） |\n| Bing CN 单引擎 | 1-2秒 | 1→10 | **100%** |\n| deep (5引擎) | 4-6秒 | 25-30→8-10 | ~40% (Bing CN + GitHub) |\n| dev (4引擎) | 4-6秒 | 25-30→8-10 | ~50% (Bing CN + GitHub) |\n| global (Bing HTTP) | 1-2秒 | 1→10 | 100% |\n\n---\n\n## 版本历史\n\n| 版本 | 日期 | 主要变更 |\n|------|------|----------|\n| **15.0** | 2026-06-01 | **10 引擎直搜 + 定时增量**：toutiao/zhihu/weixin 3 个 site:bing 代理（100% 目标域，免反爬 <1秒）+ cron_refresh.py 客户端 |\n| **14.0** | 2026-06-01 | **OpenAI API + 增量追加**：FastAPI 5 endpoints（/v1/search + /v1/search/refresh）+ force_refresh 强制刷新 + 与历史合并（refresh=true/false 标记）|\n| **13.0** | 2026-06-01 | **智能缓存层**：分桶TTL（news 5min / dev 1h）+ query归一化 + 桶复用（num 5/8/10 共享）+ 命中率统计 |\n| **12.2** | 2026-06-01 | **智能去重 + 跨源聚合**：主题词 key + Jaccard 双策略，⭐ 标记，cluster_size |\n| **12.1** | 2026-06-01 | **GitHub Issues 引擎**：开发者向查询，issue 级讨论，过滤 bot/PR。dev 模式 |\n| 11.2 | 2026-05-28 | 搜狗 HTTP 模式（aiohttp，<1秒），quick 模式 0.5-1秒 |\n| 11.1 | 2026-05-25 | Bing CN HTTP 引擎 — 真实直链，官方源覆盖，3秒内 |\n| 10.x | 2026-05-15 | Playwright + 搜狗/百度/360 多引擎 |\n| 8.3 | 2026-05-10 | 旗舰版：URL 异步解析、摘要 100% 覆盖 |\n\n---\n\n## 技术架构\n\n```\nsearch.py (v12.2, Hybrid HTTP + Playwright + 智能去重)\n│\n├── HTTP 引擎 (aiohttp, 无需浏览器)\n│ ├── 搜狗 HTTP <1秒, 质量高\n│ ├── Bing CN 真实直链, 官方源\n│ ├── GitHub Issues 开发者向, 真实直链\n│ └── Bing HTTP 国际版\n│\n├── Playwright 引擎 (需浏览器, 反爬 fallback)\n│ ├── 搜狗 URL 跳转解析\n│ ├── 百度 国内引擎\n│ ├── 360 国内补充\n│ └── 微信 搜狗微信\n│\n├── 智能去重 v12.2\n│ ├── 主题词 key + Jaccard 双策略\n│ ├── 跨源聚合加成\n│ └── ⭐ 可视化标记\n│\n├── 语言感知路由\n│ ├── 中文 → CN_ENGINES (deep/dev/news/policy/stock)\n│ └── 英文 → GLOBAL_ENGINES\n│\n└── 缓存层\n └── SQLite 1小时, (query + engine + mode) key\n```\n\n---\n\n## 依赖\n\n```\npip install aiohttp beautifulsoup4 lxml playwright\nplaywright install chromium\n```\n\n无需 API Key。\n\n---\n\n## License\n\nMIT\n\nFile v20.42.1:_meta.json\n\n{\n \"ownerId\": \"kn74wh1ba6kj8c6gg1ejv8q95982szyc\",\n \"slug\": \"star-search\",\n \"version\": \"20.42.1\",\n \"publishedAt\": 1789002022290\n}\n\nFile v20.42.1:references/camofox-api.md\n\n# Camofox API Quick Reference（Star Search v8.3）\n\n## 核心端点\n\n```bash\n# Health check\ncurl http://localhost:9377/health\n# ✓ {\"ok\":true,\"browserConnected\":true,\"engine\":\"camoufox\"}\n# ✓ {\"ok\":true,\"browserConnected\":false} — 也正常工作\n\n# 创建tab并导航\ncurl -s -X POST http://localhost:9377/tabs \\\n -H \"Content-Type: application/json\" \\\n -d '{\"userId\":\"search\",\"sessionKey\":\"RANDOM\",\"url\":\"https://www.sogou.com/web?query=关键词&ie=utf8\"}'\n\n# 获取页面快照（snapshot）\ncurl -s \"http://localhost:9377/tabs/$TAB_ID/snapshot?userId=search\"\n\n# 导航到新URL\ncurl -s -X POST \"http://localhost:9377/tabs/$TAB_ID/navigate?userId=search\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"userId\":\"search\",\"url\":\"https://www.example.com\"}'\n\n# 关闭tab\ncurl -s -X DELETE \"http://localhost:9377/tabs/$TAB_ID?userId=search\"\n```\n\n## search.py 已封装所有端点\n\n**不建议直接调用API。** `search.py` 已经封装了完整的搜索流程：\n\n```python\n# create_tab → wait_for_snapshot → extract → close_tab\n# 三引擎并行 + 去重 + URL解析 + JSON output\n```\n\n## 已知问题\n\n| 问题 | 说明 |\n|------|------|\n| `about:blank` 被拦截 | Camofox不支持`about:`协议，用`https://www.sogou.com/robots.txt`替代 |\n| navigate响应url是真实URL | 导航到搜狗短链后，响应`url`字段是JS重定向后的真实URL |\n| snapshot中的heading行 | 搜狗结果`level=3`，百度结果也在`level=3` |\n| 360短链无法解析 | `so.com/link?m=xxx` navigate后响应仍是短链 |\n\nFile v20.42.1:references/search-engine-research.md\n\n# Search Engine Research — 实测数据汇总\n\n**测试时间**: 2026-05-09\n**测试环境**: macOS, Camoufox v135, Camofox REST API\n**测试query**: \"AI API token resale market\"\n\n## 全引擎测试结果\n\n| 引擎 | URL模板 | 结果数 | 验证码 | URL类型 | 推荐 |\n|------|---------|--------|---------|---------|------|\n| **搜狗** | `https://www.sogou.com/web?query={q}&ie=utf8` | **10** | 无 | JS跳转链 | ✅ 主引擎 |\n| **百度** | `https://www.baidu.com/s?wd={q}` | **9** | 随机 | 真实URL | ✅ 备选 |\n| **360** | `https://www.so.com/s?q={q}` | **6** | 无 | JS跳转链 | ⚠️ 补充 |\n| 神马 | `https://m.sm.cn/s?q={q}` | 0 | — | — | ❌ |\n| Bing中国 | `https://cn.bing.com/search?q={q}` | 0 | — | — | ❌ |\n| Bing国际 | `https://www.bing.com/search?q={q}` | 0 | — | — | ❌ |\n| Google | `https://www.google.com/search?q={q}` | 超时 | — | — | ❌ |\n| DuckDuckGo | `https://duckduckgo.com/?q={q}` | 超时 | — | — | ❌ |\n| Brave | `https://search.brave.com/search?q={q}` | 超时 | — | — | ❌ |\n| Startpage | `https://www.startpage.com/do/search?q={q}` | 超时 | — | — | ❌ |\n| Naver | `https://search.naver.com/search.naver?query={q}` | 超时 | — | — | ❌ |\n| Yandex | `https://yandex.com/search/?text={q}` | 4 | 无 | 真实URL | 仅英文 |\n\n## URL类型说明\n\n### 真实URL（Baidu）\n```\nhttp://www.baidu.com/link?url=xxxxxxxxxxxx\n```\n通过HTTP请求可直接跟踪到真实目标地址。\n\n### JS跳转链（Sogou/360）\n```\nhttps://www.sogou.com/link?url=hedJjaC291OHSfRZxx--pdfZ45aIPvhNrynoH4S1IZp3dsjpqTIyDdYe-yQx-7HpcIz44lfNwViJLl\nhttps://www.so.com/link?m=eQUM3VzYEL0KkrC2Th1ogvJEPne2l3da0PF74tZeJf5hvLk8G8m0ynlz7puTSlXm\n```\nPython `urllib.request.urlopen()` 跟踪后停在跳转页，无法获取最终地址。\n在真实浏览器中点击可正常跳转。\n\n**对搜索结果展示无影响** — 浏览器内点击不受影响，仅影响程序化URL解析。\n\n## 验证码触发规律\n\n| 查询类型 | 示例 | Baidu验证码概率 |\n|---------|------|----------------|\n| 简单通用词 | test, hello, search | 高 |\n| 长尾具体词 | AI API token 转售 市场 | 低 |\n| 中文+英文混合 | AI API token resale market | 中 |\n\n**结论**: 使用具体、描述性的搜索词可显著降低验证码触发率。\n\n## 搜狗结果质量分析\n\n```\n1. AI API token resale market的更多内容_CSDN技术社区\n2. TOKEN自由-Ai Token平台|大模型Ai Token 供应与特价平台|免费TOKEN\n3. API Token Authentication for Jira expand conne...| Atlassian\n4. 知识 - AI应用,AI模型API,第三方整合、Token 流转之间的关系说明\n5. Open AI API价格以及使用说明_知乎\n6. API渠道汇总,免费Token获取指南!!\n7. APIPark 新增 AI 大模型负载均衡,APIKey 资源池以及 AI Token 消耗统...\n8. 什么是Token？一文看懂AI世界的\"语言积木\"-AI Token - 今日头条\n9. 刚刚,OpenAI推出最贵o1-pro API！千倍于DeepSeek\n10. 图像识别 - 通用物体和场景识别 | 百度AI开放平台\n```\n来源: CSDN、知乎、腾讯云、今日头条、Atlassian — 高质量中文来源为主。\n\n## 360结果质量分析\n\n```\n1. China warns of digital AI 'token' risks - Chinadaily.com.cn\n2. ai api token resale market - 360翻译\n3. 智谱API涨价83%,AI的免费午餐真的结束了?\n4. 最懂大模型的人也逃不过杀猪盘?API生意背后的灰产链条\n5. AI大模型DeepSeek-V3 API售后调整:输出Token费用暴涨至8元\n6. OpenAI图像生成模型API发布,Token计价,一张图花掉1.4元\n```\n来源混合: 中国日报、澎湃、腾讯 — 有内容深度。\n\nFile v20.42.1:references/v15-site-bing-probe-results.md\n\n# v15.1 site:bing 代理引擎 — 27 域实测数据\n\n**测试时间**: 2026-06-01\n**解析器**: v15 `_parse_bing_cn`（bs4 select `li.b_algo > h2 a`）\n**判定**: target ≥ 1 条 = 有效\n\n## 有效引擎（10 个 site: 代理全部采纳）\n\n| alias | site | 测试 query | 目标域 hits | 备注 |\n|-------|------|-----------|-----------|------|\n| toutiao | toutiao.com | 华为鸿蒙 PC | 2+ | v15 |\n| zhihu | zhihu.com | Python asyncio 教程 | 1+ | v15 |\n| weixin | mp.weixin.qq.com | DeepSeek V4 | 3+ | v15，URL 走 weixin.sogou.com |\n| csdn | csdn.net | asyncio 教程 | 1 | v15.1 |\n| cnblogs | cnblogs.com | asyncio 教程 | 1 | v15.1 |\n| eastmoney | eastmoney.com | A股 政策 | 1 | v15.1 |\n| cls | cls.cn | 财经早知道 | 1 | v15.1（query 要\"财经\"才命中） |\n| tencent_cloud | cloud.tencent.com | asyncio 教程 | 1 | v15.1 |\n| sina_finance | finance.sina.com.cn | A股 政策 | 1 | v15.1 |\n| sohu | sohu.com | 鸿蒙 PC | 1 | v15.1 |\n\n## 无效引擎（20 个，不予采纳）\n\njuejin / ithome / 36kr / sspai / infoq / oschina / huxiu / smzdm / zol / xueqiu / wallstreetcn / douban / jianshu / segmentfault / netease / qq / ifeng / chinanews / people / xinhuanet — 全部 raw=10 但 target=0。\n\n## 关键发现\n\n1. **Bing 索引对中文站点覆盖率极不均匀** — 27 域中仅 10 域能拿到目标域真实结果\n2. **官方/央媒（人民网/新华网/中新网）竟然索引不到** — news/policy 模式建议继续用搜狗/微信/百度 Playwright 引擎兜底\n3. **反爬严的站（雪球/华尔街见闻/36kr/虎嗅）一致 0 命中** — site:bing 无法绕过反爬\n4. **cls query 关键词敏感** — \"央行 降息\" 0 命中但 \"财经早知道\" 1 命中\n5. **zhihu 实测有效**（\"一份详细的asyncio入门教程\" zhuanlan.zhihu.com）\n\n## 探测脚本（re-runnable）\n\n```python\nimport urllib.request, urllib.parse, ssl, re\nctx = ssl.create_default_context(); ctx.check_hostname=False; ctx.verify_mode=ssl.CERT_NONE\nUA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/'\n\ndef hits_count(q, site):\n url = f\"https://cn.bing.com/search?q=site%3A{site}+{urllib.parse.quote(q)}&count=15&setlang=zh-cn\"\n req = urllib.request.Request(url, headers={\"User-Agent\": UA, \"Referer\": \"https://cn.bing.com/\"})\n body = urllib.request.urlopen(req, timeout=8, context=ctx).read().decode('utf-8', errors='ignore')\n count = 0\n for m in re.finditer(r'
  • (.*?)
    • ', body, re.DOTALL):\n a = re.search(r']+href=\"(https?://[^\"]+)\"', m.group(1))\n if a and site in a.group(1): count += 1\n return count\n```\n\n## 后续建议\n\n- **新引擎发现流程**：用本脚本批量测 → 只采纳 target ≥ 1\n- **不要相信直觉**：\"人民网应该能搜到吧\" — 实测 0 命中。用数据说话\n- **每域用 2-3 个 query 验证稳定性**\n- **可以每季度重新探测**（Bing 索引会变）\n\nFile v20.42.1:references/v16-engine-addition-checklist.md\n\n# v16 引擎接入清单 + 双重注册检查\n\n**v16 迭代教训**：6/2 给搜狗加 site:bing 代理时，复制 `weixin` 行忘加 HTTP 解析器，sogou 变成只注册 URL 没注册 parser。deep mode 触发 KeyError，stderr 一直刷。\n\n## 4 个映射表必须**全**对齐\n\n新加一个引擎 alias 时，**4 个字典都要写一行**（不写就跑 KeyError）：\n\n| 字典 | 作用 | 缺它会怎样 |\n|:-----|:-----|:-----------|\n| `HTTP_BASE_URLS` | 引擎 → 搜索 URL 模板 | 不写：跑 deep mode 不会触发此引擎 |\n| `HTTP_PARSERS` | 引擎 → 解析函数 | 不写：**KeyError 反复刷 stderr**（v16 修复的就是这个） |\n| `PW_BASE_URLS` | Playwright 引擎 URL | 不写：此引擎不会进 PW 段 |\n| `PW_PARSERS` | Playwright 引擎解析 | 不写：PW 段 KeyError |\n\n引擎走 HTTP 还是 PW 取决于你想跑哪种协议；v15+ 大量 site:bing 代理**只走 HTTP**，但有些引擎（如 weixin）**两边都注册**（HTTP 段 weixin_bing + PW 段 weixin_pw）。\n\n## 新增引擎的 6 步流程\n\n1. **探测 site:bing 是否有效**（用 `references/v15-site-bing-probe-results.md` 的脚本）\n2. 在 `HTTP_BASE_URLS` 加一行\n3. 在 `HTTP_PARSERS` 加一行（**v16 关键！忘写必 KeyError**）\n4. **smoke test 前先 diff 4 个 dict 长度**（见下）\n5. smoke test：`python3 search.py \"测试 query\" --engine <新引擎> --top 3` 看有没有 KeyError\n6. 写 `references/<新引擎>-probe.md` 记录该域的稳定性数据\n\n## 验证 4 个 dict 的内联检查\n\n新加完引擎提交前一行命令必跑：\n\n```bash\npython3 -c \"\nimport sys; sys.path.insert(0, 'scripts')\nimport search\nhttp_engines = set(search.HTTP_BASE_URLS) - set(search.PW_BASE_URLS)\npw_engines = set(search.PW_BASE_URLS) - set(search.HTTP_BASE_URLS)\nerrors = []\nfor e in http_engines:\n if e not in search.HTTP_PARSERS:\n errors.append(f'❌ {e} 在 HTTP_BASE_URLS 但 HTTP_PARSERS 无')\nfor e in pw_engines:\n if e not in search.PW_PARSERS:\n errors.append(f'❌ {e} 在 PW_BASE_URLS 但 PW_PARSERS 无')\nfor e in search.HTTP_PARSERS:\n if e not in search.HTTP_BASE_URLS:\n errors.append(f'⚠️ {e} 在 HTTP_PARSERS 但 HTTP_BASE_URLS 无')\nfor e in search.PW_PARSERS:\n if e not in search.PW_BASE_URLS:\n errors.append(f'⚠️ {e} 在 PW_PARSERS 但 PW_BASE_URLS 无')\nprint('OK' if not errors else 'ERRORS:\\n' + '\\n'.join(errors))\n\"\n```\n\n预期（v16 修复后）：`OK`\n\n## 历史 bug 档案\n\n| 日期 | 引擎 | Bug | 修复 |\n|:-----|:-----|:----|:-----|\n| 2026-06-02 | sogou | `HTTP_BASE_URLS` 注册了但 `HTTP_PARSERS` 没注册 | 删 `HTTP_BASE_URLS` 那行（sogou 走 PW 即可）|\n\nFile v20.42.1:references/v16-rss-probe-results.md\n\n# v16.1 RSS 引擎 — 20 无效域的替代抓取策略\n\n**测试时间**: 2026-06-02\n**目标**: v15.1 探针确认 site:bing 0 命中的 20 个域，逐个找替代抓取方案\n**方法**: aiohttp + RSS XML 正则解析（无 feedparser 依赖，< 1s/请求）\n\n## 探针结果：5/20 域 RSS 有效（v16.1 已接）\n\n| 域 | RSS endpoint | items | sample | 状态 |\n|----|-------------|-------|--------|------|\n| **ithome** | https://www.ithome.com/rss/ | 60 | \"华硕推出 ASUS Pad 平板\" | ✅ v16.1 接 |\n| **36kr** | https://36kr.com/feed-newsflash | 20 | \"恒生指数涨超1%\" | ✅ v16.1 接 |\n| **sspai** | https://sspai.com/feed | 10 | \"派早报：英伟达...\" | ✅ v16.1 接 |\n| **oschina** | https://www.oschina.net/news/rss | 50 | \"Surface Laptop Ultra\" | ✅ v16.1 接 |\n| **woshipm** | https://www.woshipm.com/feed | 15 | \"AI Agent 产品化瓶颈\" | ✅ v16.1 接 |\n\n## 8 域：feed 链接已失效（404 / 0 items / DNS 失败）\n\n| 域 | 原因 | 备注 |\n|----|------|------|\n| jianshu | 404 | 简书 RSS endpoint 已下线（短链 service） |\n| segmentfault | 0 items | 改版后无 feed |\n| jiqizhixin | 0 items | 机器之心 RSS endpoint 失效 |\n| yicai | 404 | 第一财经 feed 需登录 |\n| caixin | 0 items | 财经 RSS 需订阅 |\n| netease_news | 0 items | 网易 news feed 死链 |\n| people | DNS 失败 | feedx.info 第三方聚合被墙 |\n| xinhuanet | DNS 失败 | 同上 |\n| ifeng | DNS 失败 | 同上 |\n| chinanews | DNS 失败 | 同上 |\n\n## 5 域：第三方 RSSHub/feedx.info 兜底（本机不可用）\n\n| 域 | 候选 endpoint | 状态 |\n|----|---------------|------|\n| juejin | rsshub.app/juejin/category/frontend | ❌ DNS 失败（rsshub.app 在国内被墙） |\n| huxiu | huxiu.com/rss/0.xml | ❌ timeout（huxiu 反爬严格） |\n| lieyunwang | lieyunwang.com/rss | ❌ DNS 失败 |\n| geekpark | geekpark.net/rss | ❌ Server disconnected（feed 关闭） |\n| infoq | feedx.info/rss/infoq.xml | ❌ DNS 失败 |\n\n**结论**：这 5 域需部署 RSSHub 自建实例（国外机器可达 feedx.info / rsshub.app），本机网络受限于 GFW。** 腾讯云服务器可考虑部署**。\n\n## 6 域：强反爬 / 商业数据 — RSS/聚合均不可行\n\n| 域 | 性质 | 替代方案 |\n|----|------|---------|\n| **bilibili** | 视频内容 | 走移动端 API（`api.bilibili.com/x/web-interface/search`）+ UA 模拟（**未实测**） |\n| **抖音** | 视频内容 | 走 tiktok.com 跨域爬（**未实测**） |\n| **小红书** | UGC 笔记 | 移动端 API（**未实测**） |\n| **雪球 xueqiu** | 财经数据 | 官方 API 付费 |\n| **华尔街见闻 wallstreetcn** | 财经数据 | RSS endpoint 已下线 |\n| **天眼查 tianyancha / 企查查 qichacha** | 企业征信 | 官方 API 付费 |\n| **yicai / caixin** | 财经新闻 | 需付费订阅 |\n\n**结论**：这 7 域短期不接，留待 上部署 RSSHub + 反向代理后再说。\n\n## v16.1 RSS 引擎技术要点\n\n### 无 feedparser 依赖\n直接用 `re.findall(r'](.*?)', xml, re.DOTALL)` 解析，省去 1 个第三方库。\n\n### RSS endpoint 固定 → 客户端按 query 过滤\n- endpoint 不带 query（RSS 订阅语义就是全量）\n- `_filter_by_query(results, query, engine)` 客户端按 query 关键词命中过滤\n- 兜底：关键词全不命中时取前 5 条（保证 RSS 引擎总能返回结果）\n\n### HTML 实体转义\nRSS description 里 `<` / `>` / `&` / `"` / `"` / ` ` / `'` 在 `_parse_rss` 里手工替换。\n\n### 性能\n- 单 RSS 引擎请求 < 0.7s（带 UA，session 复用）\n- 5 个 RSS 引擎并联 ~1.5s（和 deep mode 其他引擎叠加）\n- 缓存友好：同一个 query 走 RSS 不同次时间相近，命中率 50%+\n\n## 后续建议（v16.2 候选）\n\n1. **部署 RSSHub 自建**（ 腾讯云）：解锁 juejin/huxiu/lieyunwang/infoq + 央媒聚合\n2. **bilibili/抖音/小红书走移动端 API**（UA 模拟 + graphql query）：v15 探针未做\n3. **付费源兜底**：雪球/华尔街/天眼查等强反爬，可对接百度千帆/天眼 API（用户决定）\n4. **RSS 引擎 health-check**：定期探测 RSS endpoint 死活，死了自动禁用\n\nFile v20.42.1:references/vs-baidu-search-comparison.md\n\n# star-search vs baidu-search 对比 (v12.2)\n\n## 核心差异\n\n| 维度 | star-search v12.2 | baidu-search (千帆API) |\n|------|------------------|----------------------|\n| 本质 | Hybrid HTTP+Playwright 多引擎爬虫 + 智能去重聚合 | 百度AI搜索API |\n| 引擎数 | **7** (搜狗HTTP / Bing CN / 搜狗 / 百度 / 360 / 微信 / **GitHub Issues**) | 1 (百度) |\n| 速度 | quick 0.5-1s · deep 4-6s (5引擎并发) · Bing CN 1-2s | ~1-2s (单引擎) |\n| URL质量 | **Bing CN / GitHub Issues 返回真实直链**；搜狗/微信/百度/360为跳转链 | 全部真实直链 |\n| 官方来源覆盖率 | **强** — Bing CN 覆盖新华网/上交所/东方财富/gov.cn/pbc.gov.cn/sse.com.cn | **弱** — 多为百家号/自媒体 |\n| 开发者向 | **GitHub Issues 引擎（v12.1）** — issue级讨论、PR/bot 过滤 | 无 |\n| 微信生态内容 | 有 (weixin.sogou.com) | 无 |\n| 智能去重 | v12.2：主题词key + Jaccard 双策略 + 跨源聚合（⭐ 标记） | 无（百度原始排序） |\n| 排序 | 多引擎加权 + 域名权威性 + 跨源验证 + 时间衰减 | 百度原始排序 |\n| 费用 | **免费** | 按量付费 (千帆API) |\n| 缓存 | SQLite 1小时 | 无 |\n| 参数 | --exact / --sources / --recency / --mode / --engine | 有限 (count/recency) |\n\n## 对比测试结果 (2026-06-01, v12.2)\n\n### 测试1: DeepSeek V4 Flash API 限时免费（科技新闻）\n\n| 项目 | baidu-search | star-search v12.2 |\n|------|-------------|-------------------|\n| 条目数 | 7条 | 8条 (21条去重) |\n| 速度 | ~3s | 4s |\n| 来源构成 | 3条什么值得买(自媒体) + 2条CSDN + 1条腾讯云 + 1条百度百科 | 5条微信行业文章 + 3条第三方官网站 |\n| 时效 | 5月8-20日 | **5月24-28日**（最新榜单位居第1） |\n| 跨源验证 | 无 | ⭐ 6条 (75%) |\n| 摘要 | 长 (百字级) | 短 (HTML 摘要) |\n| 胜者 | 摘要质量 + 方法细节 | **时效 + 跨源 + 多视角** → **平** |\n\n### 测试2: 央行2026年货币政策 降准降息（政策查询）\n\n| 项目 | baidu-search | star-search v12.2 |\n|------|-------------|-------------------|\n| 条目数 | 8条 | 8条 (24条去重) |\n| **官方源** | **0条** (无 gov.cn / pbc.gov.cn) | **4条** (🏛️) — safe.gov.cn / pbc.gov.cn / creditchina.gov.cn / **gov.cn 国务院政策解读** |\n| 媒体源 | nbd / jiemian / cctv / cls 财经媒体 | 同上 + ⭐ 跨源验证 |\n| 标题党 | 2条（\"房价又要大涨\"/\"此轮牛市已走完上半场\"） | 0条 |\n| 胜者 | — | **star-search 压倒性胜出** |\n\n### 测试3: Python asyncio 协程 最佳实践 2026（开发者向）\n\n| 项目 | baidu-search | star-search v12.2 |\n|------|-------------|-------------------|\n| 条目数 | 8条 | 8条 (24条去重) |\n| 来源 | CSDN / 聚合博客站（千篇一律的\"asyncio 完全指南\"模板） | CSDN + 廖雪峰 + 百度百科 + **GitHub Issues (hs-bindgen, hydrus)** |\n| 开发者向 | 弱（无 issue 级讨论） | **强** — GitHub Issues 引擎直接给真实 issue 链接（带 [feature-request] / [bug] 标签） |\n| 胜者 | — | **star-search 完胜**（v12.1 GitHub Issues 引擎是独有优势） |\n\n## 实测结论\n\nv12.2 三个核心升级决定了对比格局：\n\n### 1. GitHub Issues 引擎（v12.1 新增）\n开发者向查询的杀手锏。百度 API 完全无 issue 级内容；star-search 通过 GitHub 官方 API（`api.github.com/search/issues`）直接拿到带标签的 issue 讨论。\n- 自动过滤 bot（Renovate/Dependabot 等）\n- 过滤 PR（只留 issue）\n- 限速 60次/小时（无需 token）\n\n### 2. 智能去重 + 跨源聚合（v12.2）\n- **主题词 key + Jaccard 双策略** 合并同事件多转载\n- **⭐ 标记** 可视化跨源/跨引擎验证\n- **cluster_size** 字段记录合并了几条\n- 5引擎 24条 → 8条 优质结果，去重几乎无性能开销\n\n### 3. Bing CN 直链\n延续 v11.1 优势，4 条官方源（gov.cn 系）覆盖让政策类查询 star-search 完胜百度 API。\n\n## 使用场景建议\n\n**用 star-search（优先）**：\n- 默认查询（v12.2 dev 模式 = 搜狗HTTP + 百度 + GitHub Issues + Bing CN）\n- 官方媒体/政府/学术查询\n- 微信生态内容\n- 开发者向查询（GitHub Issues）\n- 跨源验证的深度研究\n- 免费场景\n\n**用 baidu-search 的场景**：\n- 百度独家结果（百度百科、百家号）\n- 需要长摘要（百度 API 摘要质量高于 HTML 解析）\n\n**推荐流程**：默认 `python3 search.py \"...\" --mode deep`；开发者向加 `--mode dev`；极快速 `--mode quick`；政策类加 `--mode policy`；微信类加 `--mode news`。\n\n## 演进\n\n| 版本 | star-search 与 baidu-search 关系 |\n|------|--------------------------------|\n| v10.x | star-search 劣势：URL 跳转、无官方来源、百度被拦截 |\n| v11.0 | HTTP 引擎试水：Google/DDG 从腾讯云超时不可用 |\n| v11.1 | Bing CN HTTP 上线 — 真实URL、官方来源，**正式与 baidu-search 形成互补** |\n| v11.2 | 搜狗 HTTP 模式加入 — quick 模式 0.5-1s |\n| v12.1 | **GitHub Issues 引擎** + dev 模式（开发者向完胜） |\n| v12.2 | **智能去重 + 跨源聚合 + ⭐ 标记**（多源新闻聚合能力提升） |\n\nFile v20.42.1:references/实战102-end-to-end-pipeline-fix.md\n\n# v20.102 端到端 Pipeline 整合 + 默认值错位修复 (2026-07-01)\n\n## 触发场景\n\n** 7/1 指导**: \"我们开发的是一个对标百度搜索的新一代 AI 搜索引擎，然后我们自己用百度搜索，你这不是疯了吗\" + \"继续调研，充分调研\" + \"要分清楚是搜的问题、读的问题、再或者是整理的问题\" + \" 只是反馈了一个方面，具有特殊性，我们完善的思路是要打造普适性的能力\"。\n\n**核心洞察**:\n- 反馈的\"搜不到/抓不到\"只是冰山一角 —— 所有国内 datacenter IP 用户搜中文都会遇到\n- **问题不在搜和读，而在整理层** —— Perplexity 区别百度的核心\n- **不破反爬，做\"信源直连 + 整理层做厚\"**\n\n## 端到端实测先于代码改造 (方法论)\n\n任何 LLM pipeline 改造前, 必须 `curl /v1/search` 跑一次看完整响应。**读 1000 行代码也找不到的 bug, 跑一次 curl 就能看到**。\n\n### 4 个隐藏 bug + 修复\n\n| # | Bug | 根因 | 修复 | 文件 |\n|---|---|---|---|---|\n| 1 | `answer=false` 默认 | SearchRequest 字段默认值错位 | 改 `default=True` | `api_server.py` line 150 |\n| 2 | `cross_verify 'date' not defined` | line 274 调用 `get_source_credibility(url, date, query)` 但 date/query 未定义 | 改 `date_str = r.get('date','')` + `query_str = ''` | `cross_verify.py` line 274 |\n| 3 | `brain_info None` | api_server 调 `_brain.analyze_query(query, use_cache=True, context=...)` 但 super_brain 不接受 `context` 参数 → TypeError → except 吞 | 改 `analyze_query(query, use_cache=True, context='', **kwargs)` | `super_brain.py` line 107 |\n| 4 | `fetch_content RuntimeWarning: coroutine never awaited` | sync 函数 `asyncio.run(_go())` 在 FastAPI 已运行的 event loop 里冲突 | 改用 `nest_asyncio.apply() + loop.run_until_complete()` 兼容 | `fetch_content.py` |\n\n### 修复后实测数据 (query=\"华为\")\n\n```json\n{\n \"count\": 3,\n \"elapsed_ms\": 1,\n \"brain_info\": {\"entity\": \"华为\", \"intent\": \"info\"},\n \"entity_card\": {\"name\": \"华为\", \"official_url\": \"https://www.huawei.com/\"},\n \"fetch_stats\": {\"requested\": 3, \"success\": 2},\n \"cross_verify\": {\"consensus_score\": 0, \"source_count\": 3},\n \"answer\": {\n \"answer\": \"1. 华为是一家全球领先的通信和信息技术解决方案提供商...\\n来源域名: huawei.com, consumer.huawei.com, vmall.com\",\n \"sources\": [\"huawei.com\", \"consumer.huawei.com\", \"vmall.com\"],\n \"model\": \"glm-4-flash\",\n \"tokens\": 949,\n \"elapsed_ms\": 7050\n }\n}\n```\n\n## 4 阶段 Pipeline 完整链路 (v20.40 串联)\n\n```\n[1] LLM 理解 query → brain_info {entity/intent/category/expected_info}\n (super_brain + few-shot prompt + context 多轮注入)\n\n[2] 智能搜索 brain 推荐引擎 → multi_search → bing_cn HTTP 主搜 (10 条) + 缓存 (TTL 30min)\n + sogou_http / baidu / 360 / weixin (playwright 兜底)\n\n[3] LLM 整理 results → cross_verify (consensus_score + 30+ 来源可信度) + entity_card (KB lookup)\n + brain_ctx 注入 answer prompt\n\n[4] 智能输出 LLM 整合 → fetch_content 自动抓前 3 条 → 响应\n + 标 credibility + fetch_success + content 字段\n```\n\n每条结果自动带：\n- `credibility` (来源可信度 0-1)\n- `fetch_success` (抓取成功标记)\n- `content` (抓到的正文片段, 最多 5000 字符)\n- `entity_card` (主体实体卡片: 名称/官网/简介/logo/tags)\n\n## 关键工程经验 (必读, 未来迭代必用)\n\n### 经验 1: sync 函数在 FastAPI async 环境里的 asyncio.run() 冲突\n\n```python\n# 错: 已有 loop 时 RuntimeWarning: coroutine never awaited\ndef fetch_url_playwright(url):\n async def _go():\n ...\n data = asyncio.run(_go()) # 这里警告\n\n# 对: nest_asyncio 兼容\ndef fetch_url_playwright(url):\n import nest_asyncio\n nest_asyncio.apply()\n loop = asyncio.get_event_loop()\n data = loop.run_until_complete(_go())\n```\n\n**症状**: `RuntimeWarning: coroutine 'fetch_url_playwright.._go' was never awaited`\n**根因**: sync 函数嵌套 async + 已运行 loop → asyncio.run 失败但没抛\n**修法**: nest_asyncio.apply() 让已运行 loop 可嵌套\n\n### 经验 2: 函数签名匹配调用方期望\n\napi_server 调 `analyze_query(query, use_cache=True, context=history_ctx)` —— 但 super_brain 不接受 context → TypeError → except 吞 → brain_info=None → entity_card 空。\n\n**调试命令**:\n```bash\ngrep -rn 'analyze_query' scripts/ | grep -v 'super_brain.py'\n# 看所有调用方, 检查参数是否匹配\n```\n\n**修法 1**: super_brain 加 `**kwargs` 兼容\n**修法 2**: api_server 去掉 `context=` 参数\n\n### 经验 3: systemd restart 循环死锁\n\n旧 unit `Restart=always` + `RestartSec=5` + 端口 5000 → 端口被僵尸 PID 占 → 新进程 EADDRINUSE → 永远循环。\n\n**症状**: `systemctl status` 显示 `activating (auto-restart)` + `Result: exit-code` 不断刷屏\n**根因**: 端口 5000 绑定失败 + systemd 立即重启\n**修法**:\n- `Restart=on-failure` (只在真崩时重启)\n- `RestartSec=15` (足够时间端口释放)\n- 不加 `ExecStartPre=sleep 3` (避免干扰 restart cycle)\n- `StandardOutput=append:/home/ubuntu/.../logs/stdout.log` (ubuntu 用户可写)\n- `Environment=\"PLAYWRIGHT_BROWSERS_PATH=/home/ubuntu/.cache/ms-playwright\"`\n\n### 经验 4: 端到端实测先于代码改造\n\n任何 LLM pipeline 改造前, 必须 curl /v1/search 跑一次看完整响应。读 1000 行代码也找不到的 bug, 跑一次 curl 就能看到。\n\n```bash\n# 标准端到端测试\ncurl -s -X POST 'http://localhost:5000/v1/search' \\\n -H 'Content-Type: application/json' \\\n -d '{\"query\":\"华为\",\"top\":3}' | python3 -m json.tool\n\n# 检查 7 个核心字段\n# 1. count (结果数 >0)\n# 2. brain_info.entity (LLM 推 entity)\n# 3. entity_card (KB 实体卡片)\n# 4. fetch_stats (自动抓取)\n# 5. cross_verify.consensus_score (多源一致度)\n# 6. answer.answer (LLM 整合答案)\n# 7. answer.sources (答案引用来源)\n```\n\n## systemd unit 完整模板\n\n```ini\n[Unit]\nDescription=star-search API server (v20.102)\nDocumentation=https://search.\nAfter=network.target\nWants=network-online.target\n\n[Service]\nType=simple\nUser=ubuntu\nGroup=ubuntu\nWorkingDirectory=/home/ubuntu/star-search\nEnvironment=\"PYTHONPATH=/home/ubuntu/.local/lib/python3.10/site-packages\"\nEnvironment=\"HOME=/home/ubuntu\"\nEnvironment=\"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/ubuntu/.local/bin\"\nEnvironment=\"PLAYWRIGHT_BROWSERS_PATH=/home/ubuntu/.cache/ms-playwright\"\nExecStart=/usr/bin/python3 /home/ubuntu/star-search/scripts/api_server.py --host --port 5000\nRestart=on-failure\nRestartSec=15\nTimeoutStopSec=10\nStandardOutput=append:/home/ubuntu/star-search/logs/stdout.log\nStandardError=append:/home/ubuntu/star-search/logs/stderr.log\nMemoryMax=512M\nTasksMax=64\nNoNewPrivileges=true\nPrivateTmp=true\nProtectSystem=strict\nProtectHome=read-only\nReadWritePaths=/home/ubuntu/star-search /home/ubuntu/.star-search-cache /home/ubuntu/.cache\n\n[Install]\nWantedBy=multi-user.target\n```\n\n## 后续方向 (差 5.9pp 到 Perplexity 80% STRAT)\n\n| 卡点 | 当前数据 | 方案 |\n|---|---|---|\n| BRAIN LLM 不稳 | 88-94% 区间 (同 query 跑 3 次: 88%/93.5%/92.6%) | 1. few-shot 加更多边界 case 2. temperature 降到 0.05 3. GLM-4-Plus 替代 Flash |\n| 边界 case | 34/108 错: 模糊意图 (BRAIN 推 info 期望 transaction/news/comparison) | 1. BRAIN prompt 加\"query 含价格/股价 必推 transaction\" 强规则 2. 加 Tavily API 作 backup 主源 (1 迭代可上) |\n| KB 实体覆盖 | 微信文章 (mp.weixin.qq.com) / 知乎 (需登录) / 雪球 (反爬) / 36kr (删文) | 1. miku-ai 集成 (公众号搜索 5/5 验证) 2. 雪球/36kr 专用 fetcher (v20.103) |\n\n## 工作方法论 (v20.102 落地)\n\n1. **任何\"用户反馈\"先 4 阶段拆解** (搜/读/整/出), 别直接动手\n2. **普适性 > 单用户特化** ( 只是入口, 问题是通用)\n3. **默认值错位检查** (mode=quick + answer=false 这种\"看起来对但实际错\"的隐藏 bug)\n4. **实测端到端一次** (curl /v1/search) > 读 1000 行代码定位\n5. **不破反爬, 走\"信源直连 + 整理层做厚\"路线** (vs 军备竞赛)\n\nFile v20.42.1:SKILL_EN.md\n\n---\nname: star-search-en\ndescription: \"Comprehensive web search + LLM-answer engine. Use when asked to search the web, find online information, research topics, get news, look up Chinese content, or check A股/finance/tech news. **v20.42 - LangChain + Dify + 5-min install**: LangChain Tool adapter, Dify plugin, install.sh, .env.example, 5-minute quick start. **v20.40 base**: STRAT 56.5%→74.1% + automatic fetch_content + end-to-end pipeline! star-search is a standard Model Context Protocol server (4 tools) callable by Claude Desktop / Cursor / Hermes. Public HTTP/SSE: https://search./mcp/sse . v20 features (v20.35-102): speed optimization 6s→0.2s + SSE streaming + multi-turn dialogue + 16 engines (HTTP/Playwright/RSS) + intelligent intent recognition (4 batch 108 query tests) + AI smart layer (super_brain + multi_search + entity_card + cross_verify + intent_strategy) + Cloudflare Bot protection + **v20.40 end-to-end pipeline** (4 stages: understand→search→integrate→output with full LLM participation). Goal: free Chinese alternative to Baidu search + LLM agent real-time fact layer (free Chinese version of Tavily/Perplexity).\"\nversion: 20.42.0\nauthor: Hermes Agent\nlicense: MIT\nmetadata:\n hermes:\n tags: [Search, Web, Bing, Sogou, Baidu, 360, Weixin, Toutiao, Zhihu, GitHub, China, Hybrid, HTTP, Playwright, Chinese, Cache, API, OpenAI, Cron, Incremental, CSDN, Cnblogs, Eastmoney, CLS, Sina, Sohu, Quality, Explain, Debug, RSS, Ithome, 36kr, Sspai, Oschina, Woshipm, Global, Public, HTTPS, Frontend, SmartRouting, Finance, MCP, JSON-RPC, SSE, LLM-Answer, Perplexity-Mode, Honest-LLM, Honest-Search, v20, Speed-Optimization, Streaming, Multi-Turn, Monitoring, Prometheus, Grafana, Structured-Output, Favorites, Academic-Search, Code-Search, English]\n related_skills: [arxiv, blogwatcher, session_search, commercial-opportunity-research, ai-api-relay-station, building-mcp-servers, native-mcp]\n references:\n - v16-v17-legacy-archive.md\n - v16-finance-mode-and-smart-routing.md\n - v16-public-deployment-and-daemon.md\n - v17-frontend-answer-card.md\n - v17-llm-answer-quality-strategy.md\n - mcp-server-zero-deps.md\n - site-bing-proxy-pattern.md\n - incremental-cache-pattern.md\n - llm-answer-honest-prompt.md\n---\n\n# Star Search v20.7.0 — Speed / Streaming / Multi-turn / Stable / Academic / Structured / Favorites / Monitoring — Integrated Chinese Search + LLM Answer\n\n**A single script to replace Baidu Search API + Answer + Monitoring. Free, multi-engine, high quality, serve subagents.**\n\n> This skill has evolved from v8.3 (Camofox) to v20.7.0 (HTTP+Playwright hybrid + intelligent routing + public deployment + LLM answer + SSE streaming + multi-turn + Prometheus monitoring). Complete v16-v17 chapters are archived in `references/v16-v17-legacy-archive.md`. GitHub: https://github.com/ @ commit da860bf (v20.7.0). Public: https://search. (HSTS + LE cert + nginx reverse proxy).\n\n---\n\n## 🔥 v20.7.0 Key Upgrades (P0-1 through P0-5 + P3-21/25/47/48)\n\n| Practice | Upgrade | Value | Performance Change |\n|---|---|---|---|\n| **35** | Speed optimization (search layer) | playwright skip + 4s top-level timeout + cache hit | **6s → 0.2-1s** |\n| **36** | SSE streaming output | `POST /v1/search/stream` + 5 events + first token < 1s | **First byte 11s → < 1s** |\n| **37** | Answer layer acceleration | `max_tokens=300` + `LLM_TIMEOUT=25s` | **7-8s complete** |\n| **38-39** | Multi-turn dialogue | `session_id` + `history` + localStorage | **6 turns context** |\n| **40** | Ultimate stability | killed `/tmp/watchdog.sh` (6/3 deployment leftover) | **NRestarts=0** |\n| **41-43** | Academic/code + structured + favorites | 4 engines + 4 formats + ⭐ button | **3 major features** |\n| **44-46** | Monitoring + Prometheus + Grafana | `/metrics` + 8 alerts + 11 panel dashboard | **Public HTTPS** |\n| **47** | Sourcegraph 4 bug fix + Semantic Scholar | text=True/returncode/POST→GET/SSE parser + x-api-key header | **1/4 engines recovered** |\n| **48** | Claude Desktop MCP integration | stdio + SSE dual transport, 4 tools tested 301ms | **Public tutorial** |\n\n---\n\n## 🏗️ Architecture (v20.7)\n\n```\n[Browser] → https://search.:443\n ↓ (nginx + LE cert)\n[/var/www/star-search/index.html] ← 49KB frontend (streaming/favorites/history/format switch)\n ↓ (location /v1/ / /mcp/ / /v1/search/stream SSE)\n[FastAPI :] ← api_server.py (systemd user)\n ├─ 16 engines (9 HTTP enabled + 4 PW skipped + 3 cache)\n ├─ answer.py (GLM-4-Flash summarization, honest-first)\n ├─ metrics.py (Prometheus metrics, 14 indicators)\n ├─ academic_code.py (4 engines)\n ↓\n[LLM API: https://api./v1] ← GLM-4-Flash (permanently free)\n[Prometheus + Grafana + node-exporter] ← 9090/3000/9100 (public HTTPS)\n[monitor.service] ← Monitoring alerts (user systemd)\n```\n\n---\n\n## 6 Major Capability Modules (v20.7)\n\n### 1. Speed & Streaming (P0-1, v20.35-37)\n\n- **Search layer 0.2-1s**: playwright 4 engines skip + 4s top-level timeout + cache hit 0ms\n- **Answer layer 7-8s**: `max_tokens=300` + `LLM_TIMEOUT=25s` + 30min cache\n- **SSE streaming**: `POST /v1/search/stream` returns 5 events (`search_start` / `search_done` / `answer_chunk×N` / `answer_done` / `done`)\n- **First token < 1s**: frontend fetch + ReadableStream SSE parsing, character-by-character display\n\n### 2. Multi-turn Dialogue (v20.38-39)\n\n- **API fields**: `session_id` + `history: [{q, a}, ...]`\n- **Backend**: `generate_answer(history)` splices into prompt (`=== Previous conversation ===\\nUser: ...\\nAssistant: ...\\n---`)\n- **Frontend**: localStorage stores `chat:{session_id}:history` (last 20 turns) + left session list\n\n### 3. Ultimate Stability (v20.40)\n\n- **systemd daemon**: `-svc.service` (user systemd + linger) + `Restart=always`\n- **Killed 6/3 leftover watchdog**: `/tmp/watchdog.sh` ran 11 days, miskilled 39 times → `kill -9` + `rm` fix\n- **uvicorn logging force=True**: avoid root logger override causing detail.log 0 bytes\n- **Tested**: 7 queries run, NRestarts=0 stable\n\n### 4. Academic / Code / Structured / Favorites (v20.41-43)\n\n- **Academic/code 4 engines**: `google_scholar` / `semantic_scholar` / `grep_app` / `sourcegraph` (independent module `academic_code.py`)\n - Actual: 1/4 available (Sourcegraph; other 3 limited by GFW / rate limiting / anti-scraping)\n- **Structured output 4 formats**: `default` / `table` / `json` / `mermaid` (LLM fully complies)\n - Pydantic avoid reserved name `format` → rename to `fmt`\n - cache key includes `fmt` (4 formats independent cache)\n- **History/favorites UI**: top bar 📚 history + ⭐ favorites 2 buttons + per-result ⭐ button + overlay + localStorage\n\n### 5. Monitoring Alerts (v20.44-45)\n\n- **`/metrics` endpoint**: pure Python 14 indicators (QPS / P99 / cache hit rate / error count / LLM latency)\n- **`monitor.service`**: user systemd + linger + 3 alert rules + 5min summary\n- **Alert rules**: error rate > 20% / cache hit rate < 10% / fetch failed 3 times\n\n### 6. Prometheus + Grafana (v20.46)\n\n- **3 docker containers**: `star-prometheus` v2.54.1 (9090) / `star-grafana` v11.2.0 (3000) / `star-node-exporter` v1.8.2 (9100)\n- **8 alert rules**: error rate / cache / service down / P99 / CPU / memory / disk\n- **Grafana 11 panel dashboard**: QPS / cache rate / latency / CPU / memory / disk\n- **Public HTTPS**: `prom.` + `grafana.` (certbot + nginx 80/443 reverse proxy)\n\n---\n\n## 🚀 Quick Start\n\n### 1. Web UI (recommended, browser direct)\n\n```\nhttps://search.\n```\n\n- Single query / multi-turn dialogue / SSE streaming / 4 format switching\n- Top 📚 history + ⭐ favorites\n- Per-result ⭐ favorite\n- Embedded answer AI card + source chips + citation chip\n\n### 2. API Endpoints\n\n| Endpoint | Purpose | Latency | Cache |\n|---|---|---|---|\n| `POST /v1/search` | Normal search | 0.2-8s | 30min |\n| `POST /v1/search/stream` | **SSE streaming** | First token < 1s | 30min |\n| `POST /v1/answer` | Answer only (custom results) | 7s | 30min |\n| `POST /v1/scholar` | Academic search | 4s | - |\n| `POST /v1/code` | Code search | 4s | - |\n| `POST /v1/academic_mode` | Mode detection | < 100ms | - |\n| `GET /v1/health` | Health check | < 10ms | - |\n| `GET /v1/modes` | List modes | < 10ms | - |\n| `GET /v1/engines` | List engines | < 10ms | - |\n| `GET /metrics` | Prometheus metrics | < 100ms | - |\n| `SSE /mcp/sse` | MCP server (4 tools) | - | - |\n| `POST /mcp/messages` | MCP client | - | - |\n\n### 3. CLI Mode\n\n```bash\n# Normal search\npython3 search.py \"AI large models\" # English→global\npython3 search.py \"asyncio vs threading\" # English→global\npython3 search.py \"today stock market\" # v20 intelligent routing auto finance\npython3 search.py \"Huawei HarmonyOS\" --mode deep --recency=week # deep + recency\n\n# Structured output\npython3 search.py \"A-share Top10\" --format table\npython3 search.py \"MCP servers\" --format json | jq .\npython3 search.py \"deployment process\" --format mermaid\n\n# Multi-turn\npython3 search.py \"BYD stock price\" --session mysession\npython3 search.py \"compare with Tesla\" --session mysession\n\n# Favorites\npython3 search.py \"BYD stock price\" --star\n```\n\n### 4. MCP Integration (Claude Desktop / Cursor / Hermes / Cline / Continue)\n\n#### 4.1 stdio mode (local, simplest)\n\n**Claude Desktop config**:\n\n```json\n// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\n// Windows: %APPDATA%/Claude/claude_desktop_config.json\n{\n \"mcpServers\": {\n \"star-search\": {\n \"command\": \"/usr/bin/python3\",\n \"args\": [\"/home/ubuntu/star-search/mcp/mcp_server.py\"],\n \"env\": {\n \"STAR_SEARCH_API\": \"http://:5000/v1/search\",\n \"PYTHONPATH\": \"/home/ubuntu/.local/lib/python3.10/site-packages\"\n }\n }\n }\n}\n```\n\n**Hermes agent / Cursor / Cline**:\n\n```json\n{\n \"mcpServers\": {\n \"star-search\": {\n \"command\": \"python3\",\n \"args\": [\"/path/to/mcp_server.py\"],\n \"env\": {\n \"STAR_SEARCH_API\": \"http://:5000/v1/search\"\n }\n }\n }\n}\n```\n\n**Key**:\n- `PYTHONPATH` must include aiohttp venv path (local dev needs `pip install aiohttp`)\n- `STAR_SEARCH_API` points to your star-search API server (default `http://:5000/v1/search`)\n- Restart Claude Desktop to take effect\n\n#### 4.2 SSE public mode (remote, cross-device)\n\n**Public endpoints**:\n```\nHealth: https://search./mcp/health\nSSE: https://search./mcp/sse\nPOST: https://search./mcp/messages?session_id=\n```\n\n**Python client example**:\n\n```python\nimport aiohttp, json\n\nasync with aiohttp.ClientSession() as s:\n # 1. SSE handshake - server pushes \"event: endpoint\\ndata: ?session_id=XXX\"\n async with s.get(\"https://search./mcp/sse\") as r:\n line = await r.content.readline() # event: endpoint\n line = await r.content.readline() # data: ?session_id=XXX\n endpoint = line.decode().replace(\"data: \", \"\").strip()\n\n # 2. initialize\n req = {\n \"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"initialize\",\n \"params\": {\"protocolVersion\": \"2025-06-18\"}\n }\n await s.post(endpoint, json=req)\n\n # 3. Read SSE response to get session_id\n # ...\n\n # 4. tools/call\n req = {\n \"jsonrpc\": \"2.0\", \"id\": 2, \"method\": \"tools/call\",\n \"params\": {\"name\": \"web_search\", \"arguments\": {\"query\": \"BYD stock price\"}}\n }\n await s.post(messages_url, json=req)\n```\n\n**Key pitfall** — Client must NOT hard-code session_id:\n- **Must use server-pushed session_id** (extract `?session_id=XXX` from SSE endpoint URL)\n- **Don't** generate UUID yourself\n- Hard-code → will 400 `Invalid session_id`\n\n#### 4.3 Tested Performance\n\n| Tool | query | Latency | Result |\n|---|---|---|---|\n| `web_search` | \"BYD stock price\" | 301ms | 8 results (Sina/EastMoney/Zhihu/investing/Xueqiu/10jqka/9fzt) |\n| `web_search_finance` | \"Shanghai Index today close\" | 870ms | 8 results (4074.74 etc.) |\n| `web_search_news` | \"AI startups\" | 280ms | 8 results from IT之家 tech news |\n| `get_engines` | - | <10ms | 16 engine list |\n\n#### 4.4 4 MCP Tools\n\n| Tool | Purpose | Engines |\n|---|---|---|\n| `web_search` | General search (intelligent recognition of finance/English/Chinese) | Default deep + finance auto-finance |\n| `web_search_news` | Tech/AI/product news | csdn/cnblogs + 5 RSS (ithome/36kr/sspai/oschina/woshipm) |\n| `web_search_finance` | Finance/stock/A股 dedicated | eastmoney/cls/sina_finance/sohu/baidu/weixin/bing_cn |\n| `get_engines` | List 16 engines + 5 modes (for agent decision-making) | - |\n\n**LLM agent call examples** (Claude Desktop / Cursor):\n```\n\"Help me search for BYD stock price, use web_search tool\"\n\"Use web_search_finance to find Shanghai Index\"\n\"Use web_search_news to find today's AI startup news\"\n\"List all engines with get_engines\"\n```\n\n---\n\n## ⚙️ Key Parameters\n\n### Search Layer\n\n| Parameter | Default | Description |\n|---|---|---|\n| `--mode` | `auto` | deep / quick / news / dev / global / finance / auto |\n| `--engine` | auto | Single engine specification (sogou / baidu / weixin / ...) |\n| `--top` | 10 | Number of results (max 30) |\n| `--recency` | none | day / week / month / year |\n| `--exact` | False | Exact match |\n| `--sources` | none | Restricted sources (weixin,baidu,...) |\n| `--format` | `default` | `default` / `table` / `json` / `mermaid` |\n| `--star` | False | Add to localStorage favorites |\n| `--session` | auto-generated | Multi-turn session_id |\n\n### Answer Layer\n\n| Parameter | Default | Description |\n|---|---|---|\n| `--answer` | True | Whether to generate LLM answer |\n| `LLM_MODEL` | `glm-4-flash` | LLM model (GLM-4-Flash permanently free) |\n| `LLM_TIMEOUT` | 25 | Answer timeout (seconds) |\n| `max_tokens` | 300 | Answer length (GLM-4 not strict) |\n| `ANSWER_CACHE_TTL` | 1800 | Answer cache TTL (seconds) |\n\n### Monitoring Layer\n\n| Metric | Type | Description |\n|---|---|---|\n| `star_search_requests_total` | counter | Request count (by endpoint) |\n| `star_search_request_errors_total` | counter | Error count |\n| `star_search_search_total` | counter | Search count |\n| `star_search_cache_hit_rate` | gauge | Cache hit rate (0-1) |\n| `star_search_search_latency_ms` | histogram | Search P50/P95/P99 |\n| `star_search_answer_latency_ms` | histogram | Answer P50/P95/P99 |\n| `star_search_llm_latency_ms` | histogram | LLM P50/P95/P99 |\n\n---\n\n## 📦 Deployment\n\n### 1. systemd user (recommended)\n\n```ini\n# ~/.config/systemd/user/-svc.service\n[Unit]\nDescription=star-search API + monitor\nAfter=network.target\n\n[Service]\nType=simple\nWorkingDirectory=/home/ubuntu/star-search\nExecStart=/usr/bin/python3 scripts/api_server.py --host --port 5000\nRestart=always\nRestartSec=5\n\n[Install]\nWantedBy=default.target\n```\n\n```bash\nsystemctl --user daemon-reload\nloginctl enable-linger ubuntu # Boot auto-start + logout auto-start\nsystemctl --user enable --now -svc.service\n```\n\n### 2. Prometheus + Grafana\n\n```bash\ncd /home/ubuntu/docker\ndocker compose -f prometheus-grafana-stack.yml up -d\n```\n\n### 3. Public HTTPS\n\n```bash\n# DNSPod A record\nprom. → \ngrafana. → \n\n# certbot SSL\ncertbot --nginx -d prom. -d grafana. \\\n --non-interactive --agree-tos -m \n```\n\n---\n\n## 🔌 Dependencies\n\n```bash\npip install aiohttp beautifulsoup4 lxml playwright fastapi uvicorn 'pydantic>=2' httpx requests\nplaywright install chromium # Optional (v20 v20.35 skipped)\n```\n\nNo API Key, no login, no payment required (GLM-4-Flash via `api./v1` permanently free).\n\n---\n\n## ⚠️ Known Pitfalls (v20 v20.35-48 Summary)\n\n### v20.1 Speed Optimization (v20.35)\n\n- **playwright drags 15-20s** → skip 4 engines\n- **aiohttp single engine 4s timeout** + top-level 4s forced cutoff\n- **try/except degrade** to cache hit\n\n### v20.2 SSE Streaming (v20.36)\n\n- **f-string pitfall**: `\"event: done\\ndata: {}\\n\\n\"` empty `{}` reports SyntaxError\n- **nginx required**: `proxy_buffering off` + `proxy_read_timeout 60s` + `proxy_http_version 1.1`\n\n### v20.3 Answer Layer Acceleration (v20.37)\n\n- **max_tokens 600 → 300**: GLM-4-Flash 46 tok/s × 300 = 6.5s actual (set 600 actual 947 tokens)\n- **LLM_TIMEOUT 8 → 12 → 25**: complex formats (json/mermaid) need 25s buffer\n\n### v20.4-5 Multi-turn + Stability (v20.38-40)\n\n- **NRestarts up must find real culprit**: v20.40 watchdog.sh 6/3 leftover 11 days miskilled 39 times\n- **uvicorn logging must force=True**: avoid root logger override causing detail.log 0 bytes\n- **cache key excludes history**: hit rate 30-50% (vs 80% with history)\n\n### v20.6 Academic/Structured/Favorites (v20.41-43)\n\n- **Pydantic avoid reserved name**: `format` is reserved → rename to `fmt`\n- **New parameter full-chain grep**: v20.42 `/v1/search` add fmt but `/v1/search/stream` not → 6 debug rounds\n- **cache key must include all change factors**: cache key missing fmt → 4 formats hit same cache\n- **GFW environment external APIs limited is norm**: v20.41 4 engines only 1 available\n\n### v20.7 Monitoring Alerts (v20.44-46)\n\n- **docker container mount data dir**: `user:\"0\"` + `chmod 777` solve mmap permissions\n- **docker image acceleration**: Docker Hub direct timeout → `daemon.json` add `daemonocloud.io`\n- **Tencent Cloud firewall**: only 22/80/443 open (direct 9090/3000 not, use nginx reverse proxy)\n- **DNSPod A record required**: not added won't take effect\n\n### v20.7.1 Sourcegraph Fix (v20.47)\n\n- **text=True SSE parsing error**: SSE chunked stream occasionally decodes wrong, use bytes + decode utf-8\n- **curl returncode=28 timeout but stdout has data**: don't check returncode, just check stdout non-empty\n- **POST → GET**: `sourcegraph.com/.api/search/stream` POST returns 404, GET returns SSE\n- **SSE parser logic**: actual event type is `content` (not `match`), need `data: ` prefix strip + check `repository` field\n\n### v20.7.2 MCP Integration (v20.48)\n\n- **aiohttp not in /usr/bin/python3 default path**: must set `PYTHONPATH=/home/ubuntu/.local/lib/python3.10/site-packages`\n- **Hard-code session_id → 400 Invalid session_id**: SSE mode must use server-pushed session_id from endpoint URL\n\n---\n\n## 📁 File Structure (v20.7)\n\n```\nstar-search/\n├── SKILL.md # Main file (v20.7.0, Chinese)\n├── SKILL_EN.md # English version (v20.7.0)\n├── index.html # v20.7 frontend (49KB, multi-turn/favorites/format switch)\n├── README.md # GitHub README\n├── search.py # v20.7 main search (16 engines + speed optimization)\n├── answer.py # v20.7 answer layer (GLM-4 + 4 formats + citations + multi-turn)\n├── api_server.py # v20.7 API server (SSE + multi-endpoint)\n├── academic_code.py # v20.7 academic/code 4 engines\n├── metrics.py # v20.7 Prometheus metrics (14 indicators)\n├── mcp_server.py # v20.7 MCP server (4 tools)\n├── mcp_*.py # v20.7 MCP client\n├── scripts/\n│ ├── cron_refresh.py # Scheduled incremental client\n│ ├── deploy_web.sh # nginx deployment\n│ ├── star_search_monitor.py # v20.7 monitoring alert service\n│ └── ...\n├── references/\n│ ├── v16-v17-legacy-archive.md # v16-v17 complete chapter archive\n│ ├── v16-finance-mode-and-smart-routing.md\n│ ├── v16-public-deployment-and-daemon.md\n│ ├── v17-frontend-answer-card.md\n│ ├── v17-llm-answer-quality-strategy.md\n│ ├── mcp-server-zero-deps.md\n│ ├── site-bing-proxy-pattern.md\n│ ├── incremental-cache-pattern.md\n│ └── llm-answer-honest-prompt.md\n├── /etc/systemd/user/-svc.service # systemd unit\n├── /etc/nginx/sites-enabled/search-\n├── /var/www/star-search/index.html\n├── /home/ubuntu/docker/prometheus-grafana-stack.yml\n└── /home/ubuntu/star-search/.env\n LLM_BASE_URL=https://api./v1\n LLM_MODEL=glm-4-flash\n LLM_TIMEOUT=25\n ANSWER_CACHE_TTL=1800\n SEMANTIC_SCHOLAR_API_KEY= # Apply at https://www.semanticscholar.org/product/api\n```\n\n---\n\n## 🔄 Version History\n\n| Version | Date | Major Changes |\n|---|---|---|\n| **v20.7.0** | 2026-06-15 | **v20.47-48**: Sourcegraph 4 bug fix + Claude Desktop MCP integration tutorial + 1M token API rate limit |\n| v20.6.0 | 2026-06-15 | v20.35-46: speed optimization + SSE streaming + multi-turn + ultimate stability + academic/code + structured output 4 formats + history/favorites + monitoring + Prometheus + Grafana |\n| v17.7.0 | 2026-06-04 | Answer cache (236x speedup) + inline citations (Perplexity Mode complete) |\n| v17.5.0 | 2026-06-04 | 4 prompt templates (finance/tech/news/general) |\n| v17.4.0 | 2026-06-04 | Multi-turn followup (3 followup chips) |\n| v17.3.0 | 2026-06-04 | Frontend AI answer card (Perplexity Mode UI) |\n| v17.2.0 | 2026-06-03 | LLM answer layer (GLM-4-Flash permanently free) |\n| v17.0.0 | 2026-06-03 | **MCP integration**: 4 tools (web_search / web_search_news / web_search_finance / get_engines) |\n| v16.2.5 | 2026-06-03 | finance engine fix Chinese financial search results |\n| v16.2.2 | 2026-06-03 | Public frontend + finance intelligent recognition + Playwright graceful degradation |\n| v16.2.1 | 2026-06-03 | Public HTTPS + frontend cultural style + daemon process |\n| v16.1 | 2026-06-02 | +5 RSS engines + global English-Chinese dual source + finance mode |\n| v15.0 | 2026-06-01 | 10 engines direct search + scheduled incremental: toutiao/zhihu/weixin |\n| v14.0 | 2026-06-01 | OpenAI API + incremental append |\n| v13.0 | 2026-06-01 | Smart cache layer (bucketed TTL + query normalization) |\n| v12.2 | 2026-06-01 | Smart deduplication + ⭐ cross-source marking |\n| v8.3 | 2026-05-10 | Flagship version (Camofox era, deprecated) |\n\nComplete v16-v17 chapters see `references/v16-v17-legacy-archive.md`.\n\n---\n\n## 📚 Practice Notes (v20 v20.35-48)\n\n以下是开发过程的详细笔记，对应每个升级的 troubleshooting 路径。\n\nArchive v20.42.0: 51 files, 219016 bytes\n\nFiles: _meta.json (132b), icon.svg (929b), index.html (59631b), install.sh (2939b), integrations/dify/manifest.yaml (1279b), integrations/dify/README.md (526b), integrations/dify/star_search.py (620b), integrations/langchain/star_search_tool.py (3703b), mcp/mcp_server.py (15512b), pricing.html (10398b), privacy.html (6991b), README.md (9944b), references/camofox-api.md (1534b), references/search-engine-research.md (3617b), references/v15-site-bing-probe-results.md (2937b), references/v16-engine-addition-checklist.md (2666b), references/v16-rss-probe-results.md (4203b), references/vs-baidu-search-comparison.md (5172b), references/实战102-end-to-end-pipeline-fix.md (8227b), scripts/academic_code.py (12697b), scripts/answer.py (44379b), scripts/api_server.py (39254b), scripts/cron_refresh.py (6510b), scripts/cross_verify.py (14495b), scripts/deep_research.py (8489b), scripts/discover_runner.py (2872b), scripts/discover.py (7196b), scripts/eastmoney_spider.py (5590b), scripts/entity_card.py (26418b), scripts/fetch_content.py (12069b), scripts/intent_strategy.py (62399b), scripts/metrics.py (7110b), scripts/multi_search.py (11199b), scripts/multimodal.py (5320b), scripts/payment.py (6598b), scripts/query_rewrite.py (5927b), scripts/realtime.py (4060b), scripts/search_runner.py (768b), scripts/search.py (68333b), scripts/semantic_search.py (5420b), scripts/star_search_monitor.py (3899b), scripts/star_search.py (2786b), scripts/super_brain.py (7785b), scripts/user_auth.py (5581b), scripts/verify.py (3243b), scripts/web_search.py (2722b), service-worker.js (2502b), SKILL_EN.md (22438b), skill-card.md (3049b), SKILL.md (33296b), terms.html (7059b)\n\nFile v20.42.0:SKILL.md\n\n---\nname: star-search\ndescription: \"Use when asked to search the web, find online information, research topics, get news, look up Chinese content, or check finance / tech news. **v20.42 - LangChain + Dify + 5 分钟安装体验**: 新增 LangChain Tool 适配器 (`integrations/langchain/star_search_tool.py`) + Dify plugin (`integrations/dify/manifest.yaml`), 一键安装脚本 `install.sh`, `.env.example` 模板, 5 分钟快速开始. **v20.41 基础**: English coverage + open scholarly sources (pure-English queries auto-route to Bing HTTP backend; OpenAlex + CrossRef merge). 16 plus engines, intent understanding, observable per-call metrics. The public service exposes standard MCP (4 tools) plus JSON-RPC and SSE. v20 series highlights: sub-second SSE streaming, multi-turn dialog, 4 output formats, Prometheus monitoring, semantic search, AI orchestration layer (intent classification, entity card, cross-source verification), bot-protection workarounds, and a 4-stage end-to-end pipeline that defaults to LLM answer + auto-fetched snippets. 16 plus engines, intent understanding, and observable per-call metrics.\"\nversion: 20.42.0\nauthor: Hermes Agent\nlicense: MIT\nmetadata:\n hermes:\n tags: [Search, Web, Bing, Sogou, Baidu, 360, Weixin, Toutiao, Zhihu, GitHub, China, Hybrid, HTTP, Playwright, Chinese, Cache, API, OpenAI, Cron, Incremental, CSDN, Cnblogs, Eastmoney, CLS, Sina, Sohu, Quality, Explain, Debug, RSS, Ithome, 36kr, Sspai, Oschina, Woshipm, Global, Public, HTTPS, Frontend, SmartRouting, Finance, MCP, JSON-RPC, SSE, LLM-Answer, Perplexity-Mode, Honest-LLM, Honest-Search, v20, Speed-Optimization, Streaming, Multi-Turn, Monitoring, Prometheus, Grafana, Structured-Output, Favorites, Academic-Search, Code-Search, Intent-Understanding, Cloudflare-Bot-Protection, KB-Card]\n related_skills: [arxiv, blogwatcher, session_search, commercial-opportunity-research, ai-api-relay-station, building-mcp-servers, native-mcp]\n references:\n - v16-v17-legacy-archive.md\n - v16-finance-mode-and-smart-routing.md\n - v16-public-deployment-and-daemon.md\n - v17-frontend-answer-card.md\n - v17-llm-answer-quality-strategy.md\n - mcp-server-zero-deps.md\n - site-bing-proxy-pattern.md\n - incremental-cache-pattern.md\n - llm-answer-honest-prompt.md\n - ai-native-search-transformation.md\n - intent-understanding-test-bench.md\n - intent-detection-rule-priority.md\n - cloudflare-bot-protection.md\n - source-credibility-4d-formula.md\n - v20-40-intent-strat-rule-pitfalls.md\n---\n\n# Star Search v20.33 — 速度/流式/多轮/稳定/学术/结构化/收藏/监控/AI 智能层/Cloudflare 应对 一体化中文搜索\n\n> 本 skill 已从 v8.3 演进到 v20.33。v16-v17 归档在 references/v16-v17-legacy-archive.md。GitHub: . 公网: (HSTS+LE证书+nginx 反代)。\n\n## ⚠️ 关键必读 (v20.33 新增)\n\n### Cloudflare Bot 保护 (v20.87)\n\n**症状**: skill/MCP/API 直接调 → 403/503 弹人机验证\n**根因**: Cloudflare 把 Python/curl User-Agent 当 bot (无 JS 验证 + 无 Cookie + 来源 IP 是腾讯云)\n**关键认识**: **Web 浏览器访问不受影响**, 只有 skill/API/CLI 受影响\n\n**3 选 1 修复方案**:\n1. **A. 关闭 Bot Fight Mode** (推荐, 5min) — dash.cloudflare.com → → Security → Bots → Bot Fight Mode Off\n2. **B. WAF Custom Rule 白名单** (推荐, 永久) — 加规则: `ip.src eq ` 或 `http.user_agent contains \"Star-Search-Skill\"` → Skip: Super Bot Fight Mode\n3. **C. 改 User-Agent + Headers** (2min, 不彻底) — `User-Agent: Mozilla/5.0 ...` + `Accept-Language: zh-CN`\n\n**API Token 权限要求** (用 A/B 时): 必须有 `Zone WAF Edit` + `Zone Settings Edit` + `Zone Bot Management Edit`。**Token 默认 `API Tokens Write` 权限不够** (v20.87 验证)。\n\n**Token 验证**: `curl https://api.cloudflare.com/client/v4/user/tokens/verify -H \"Authorization: Bearer \"` → `{\"success\":true, \"status\":\"active\"}`\n**Zone ID 获取**: https://dash.cloudflare.com/?to=/:account/:zone → 选 → 右下角 API 框\n**关 Bot Fight Mode**: `PATCH /zones/{zone_id}/settings/bot_fight_mode` body `{\"value\":\"off\"}`\n\n完整复盘见 `references/cloudflare-bot-protection.md`\n\n## 版本历史 (v20.32-20.33)\n\n| 版本 | 日期 | 主要变更 |\n|---|---|---|\n| **v20.40.0** | 2026-07-01 | **v20.40 三连击: STRAT 56.5%→74.1% (+17.6pp) + 端到端 pipeline 默认 answer+fetch 开启**. v20.40+ 规则 + BAIN/STRAT 联动 (BRAIN few-shot + 极短 entity 例外 + navigation 中文 3+ 字 company + transaction 股价 company). v20.101 fetch_content.py + `--fetch N` 一步搜索+抓取 (curl 主抓 5s + playwright 兜底 15s + sogou.com/link/微信特殊处理). v20.102 默认值错位修复 (api_server `answer=True, fetch=3` + cross_verify `date` not defined bug + super_brain `context` 参数 + fetch_content nest_asyncio 修复 RuntimeWarning + systemd unit 重写 on-failure). 实测 query=\"华为\" → count=3 + brain.entity=华为 + entity_card.url=huawei.com + fetch_stats 2/3 + answer.model=glm-4-flash. **还差 5.9pp 到 Perplexity 80% STRAT 基准, 受 BRAIN LLM 不稳 (88-94% 区间) + 边界 case (查询意图模糊) 限制**. |\n| **v20.39.0** | 2026-06-19 | **v20.99：答案层精简 + 加密货币 fallback**（answer.py 删 \"实时股价请查询东方财富/新浪财经...\" 冗余 → \"实时价格已附在答案末尾\" / eastmoney_spider CRYPTO 走 TradingView+火币+非小号 3 链接 fallback / 公网 3 query 验证 答案更简洁） |\n| v20.33.0 | 2026-06-17 | v20.78+79-81+85+86 意图理解 + v20.87 Cloudflare 应对 |\n| v20.32.0 | 2026-06-17 | v20.85: KB 160+ 实体 (BRAIN 94.4%/STRAT 56.5%) |\n\n[完整 v20.6 - v20.27 历史及 v16-v17 章节见 references/v16-v17-legacy-archive.md]\n\n## v20.78 - v20.86 意图理解大幅优化 (v20.33)\n\n### 4 批 108 query 全面回归 (并发 8 线程, 90s 跑完)\n\n| 阶段 | BRAIN (intent) | STRAT (entity_type) | 两者都准 |\n|---|---|---|---|\n| v20.73 之前 | ~70% | ~30% | ~25% |\n| v20.78 之后 | 91.7% | 53.7% | 51.9% |\n| v20.85 (KB 180+) | **94.4%** | 56.5% | 55.6% |\n| v20.86 (学术规则) | 92.6% | **59.3%** | **58.3%** |\n\n### detect_entity_type 17 规则优先级 (v20.78 调试 8 轮才到 10/10)\n\n**口诀**: **自述 → 模式 → intent → fallback**, 段内 academic_set 优先 company_hint\n\n**17 规则清单**:\n1. 1-2 字中文 → general (保留 KB 优先路径, 不立刻截胡)\n2. 自述句 (我/咱们) → general\n3. 模式硬编码: \"X 官网\" → company / \"X 是什么\" → academic+company+product / \"X 简介\" → company+product\n4. v20.86: 学术/教程/方法 query → academic (\"教程/入门/怎么/如何/备考/申请/步骤\")\n5. intent=news → news\n6. intent=transaction → shopping\n7. intent=navigation → company/product (4-8 字中文)\n8. intent=info: 人物 (简历/生平/先生/女士) → person / KB hint → 对应类 / category 决定 fallback\n9. intent=comparison: 第一 entity 类型 (公司/产品/学术)\n10. KB hint (大/小写不敏感) → 对应类\n11. 中文 2-8 字 + category 在 (tech/shopping/social) → product\n12. 中文 2-4 字 + 后缀 (招聘/招聘) → general\n13. 英文 entity → company\n14. 拼音 query → 中文重写\n15. 错别字 → 常见词纠正\n16. 2-4 字中文 entity 走 KB 优先\n17. 极长 query 拆 entity\n\n**关键调试 8 轮发现** (从 26/40 → 40/40):\n- 规则顺序决定一切 (intent 优先 vs KB 优先 冲突)\n- KB_HINT 大小写不敏感 (openai vs OpenAI)\n- \"X 是什么\" 模式 必须在 intent 之前 (否则 info 模式截胡)\n- \"X 官网\" 必须 strip 官网后看 entity (\"华为官网\" → company, 拆出\"华为\")\n- 中文 2-4 字 entity 不能直接判 person (误判\"微信\"为\"韦信先生\")\n\n### KB 180+ 实体 (v20.85)\n\n- **BUILTIN_KB_EXTRA** (13): 马斯克/埃隆·马斯克/LLM/5G/GPT/GPT-4/GPT-4o/o1/Claude/Transformer/RAG/AI\n- **BUILTIN_KB_EXTRA2** (90): 15 人物 (乔布斯/盖茨/雷军/任正非/马云/马化腾/李彦宏/刘强东/张一鸣/黄仁勋/巴菲特/芒格/陆奇/李开复/奥特曼) + 15 公司 (Spotify/Netflix/Uber/Airbnb/Salesforce/Oracle/SAP/Cisco/IBM/VMware/联想/中兴/大疆/滴滴/快手/完美世界/米哈游/保时捷/宝马/奔驰/奥迪/茅台/五粮液/星巴克/可口可乐/百事可乐/迪士尼) + 12 AI 产品 (Sora/Gemini/Llama/Mistral/Anthropic/Perplexity/Notion/Figma/Slack/钉钉/飞书/Zoom) + 11 概念 (区块链/比特币/以太坊/NFT/Web3/元宇宙/云计算/大数据/物联网/量子计算/深度学习) + 11 游戏 (黑神话/原神/王者荣耀/LOL/我的世界/宝可梦/塞尔达/漫威/DC/哈利波特/三体) + 10 食物饮料 (咖啡/茶/茅台/五粮液/可口可乐/百事/星巴克/喜茶/蜜雪冰城) + 5 地点 (故宫/长城/迪士尼/上海迪士尼/环球影城)\n- **BUILTIN_KB** (50+ 原始): 韭研公社/雪球/同花顺/华为/比亚迪/苹果/微软/谷歌/OpenAI/Claude/微信/微博/知乎/B站/抖音/Python/Rust/GitHub\n- **BUILTIN_KB_HINT** 动态合并: `_build_kb_hint()` 合并 3 个 KB (180+ 实体)\n\n### 真网址强优先 (v20.81)\n\n- **answer.py 强约束 inject KB official_url 到 prompt**\n- `generate_answer(query, results, mode, history, fmt, brain_ctx, entity_card_url=None)`\n- prompt 段: \"你的答案中**必须包含这个网址**\"\n- **公网 5 query 100% 引用 KB 网址** (jiuyangongshe.com/weixin.qq.com/openai.com/gpt-4)\n\n## 4 批 108 query 测试方法论 (v20.77 - v20.85 + 86)\n\n**测试模板** (scripts/test_intent_108.py):\n- BATCH1 (37): 导航/工商/购物/对比/教程/资讯/人物/产品/视频/边界\n- BATCH2 (30): 模糊/多 entity/极短/中英/复合/命令\n- BATCH3 (20): 金融/医疗/教育/法律/汽车/房产 垂直\n- BATCH4 (20): 错拼/极简/讽刺/方言/极长/乱码\n\n**跑法**:\n```python\nfrom concurrent.futures import ThreadPoolExecutor\nimport super_brain, intent_strategy\ndef test(q): bi = super_brain.analyze_query(q[0], use_cache=False); s = intent_strategy.strategy_for_query(q[0], bi); ...\nwith ThreadPoolExecutor(max_workers=8) as ex: results = list(ex.map(test, ALL))\n```\n\n**关键**: `rm -f brain_cache.json` 清缓存 (避免假阳性)\n**评分**: brain_ok = (intent==exp), strat_ok = (entity_type==exp), both_ok = brain_ok and strat_ok\n\n完整模板见 `scripts/test_intent_108.py`\n\n## v20.87 Cloudflare Bot 保护 (v20.33 新章节)\n\n[完整章节在 references/cloudflare-bot-protection.md]\n\n**用户原话** (2026-06-17): \"Star Search 被 Cloudflare 保护了（人机验证）, API 无法直接调用. 这个 skill 无法使用了, 是怎么回事, 人机验证不是用在 web 端吗, skill 应该可以正常使用啊\"\n\n**核心原则 (用户硬强调)**: \"方案A, 这个 skill, 是免费使用的, 这个是咱们的核心原则\"\n→ 必须**永久方案** (WAF 白名单 / 关 Bot Fight Mode), 不能用应急方案 (改 UA 一次性)\n\n**根因分析**:\n- Cloudflare 看到: 来源 IP (腾讯云) + User-Agent (Python/curl) + 无 Cookie + 无 JS\n- 判定 bot → 弹人机验证\n- **影响**: Web 浏览器 ✓ / skill/MCP/API ✗\n\n**3 步解决**:\n1. 拿 CF_API_TOKEN (要 `Zone WAF Edit` + `Zone Settings Edit` + `Zone Bot Management Edit`)\n2. 拿 CF_ZONE_ID ( 域名)\n3. PATCH 关 Bot Fight Mode + 加 WAF Custom Rule\n\n**API 端点**:\n- `GET /client/v4/user/tokens/verify` — 验证 token\n- `GET /client/v4/zones` — 列 zones (要 zones:read)\n- `PATCH /zones/{zone_id}/settings/bot_fight_mode` body `{\"value\":\"off\"}` — 关 Bot Fight Mode\n- `PUT /zones/{zone_id}/rulesets/{ruleset_id}/rules` — 加 WAF Custom Rule\n\n完整 API + 复盘见 `references/cloudflare-bot-protection.md`\n\n## v20.86 学术类 query 强规则 (v20.33)\n\n**触发条件** (任一): \"教程/入门/学习/教学/指南/方法/技巧/备考/申请/步骤/复习/练题/做法/怎么用/怎么学/怎么选/怎么治/怎么写/怎么做/怎么配/怎么调/如何用/如何学/如何选/如何治/如何写/如何做/如何配/如何调\"\n\n→ 直接判 `academic`\n\n**STRAT 提升**: 56.5% → 59.3% (+2.8%)\n**两者都准**: 55.6% → 58.3% (+2.7%)\n\n**位置**: detect_entity_type 模式硬编码之后, intent 优先之前\n\n## v20.90 调研 + 91+92+95 迭代补全 (v20.35-v20.36)\n\n### v20.90 5 大 AI 引擎对比 (2026-06-19 调研)\n\n| 引擎 | query 理解 | 答案层 | 来源层 | UI 层 |\n|---|---|---|---|---|\n| Perplexity | 6 类意图 + 多轮 10+ | 必引用 + 对比表自动 | domain authority + consensus | brain 徽章 + follow-up |\n| ChatGPT Search | 端到端不分层 | 单一长答 + 引用 | 签约源 | 简单 |\n| Gemini | 多模态 + recency 7 天 | 分块 + 自动 chart | E-E-A-T | AI Overview |\n| Copilot | GPT-4 + 多轮 | 3 模式 + 对比按需 | Bing index | **follow-up 必显示** |\n| You.com | 3 类 intent | 多模态 + 代码 sandbox | reddit/quora 权重高 | apps 卡 |\n\n### v20.91 STRAT 边界修 (部分生效)\n\n**修了 5 个边界 case**:\n- 1-2 字纯中文极短 query → general (不是 company)\n- \"X 在哪 / X 联系方式 / X 创始人\" → person\n- \"X 是什么\" + 中文 4+ 字 + 不在 KB → academic\n- \"搜索.*教程\" → academic\n- 第一 entity 在 KB hint (大小写不敏感) → company\n\n**v20.91 调试发现的 3 个真相**:\n1. **.AI/英文 1-2 字不应判 general** (用户输 \"AI\" 实际想查产品/公司, 走 KB 路径才对)\n2. **patch anchor 含 `if X == '...'`** 时 sibling patch 极易复制块 (v20.91 调试 5 轮)\n3. **\"X vs Y\" 第一个 entity 必须 strip 逗号/空格**, 否则 strategy 走错\n\n**v20.91 真实提升**: STRAT 56.5% → 56.5% (持平, 因 5 个边界 case 不在 108 query 里)\n**真实价值**: 防未来 query 误判\n\n### v20.92 对比表 (v20.64+81 已实现)\n\n**v20.64+81 prompt 已包含**: \"如果 intent 是 comparison (对比), 用表格/对比格式\"\n**v20.92 调研发现**: 业界 Perplexity/Gemini 必出表格, ChatGPT/You.com 不强制\n**v20.92 决定**: 沿用v20.64+81 prompt 引导 (已够用, 不需新写)\n**v20.92 真实状态**: 已实现 (无需新代码)\n\n### v20.93 follow-up (v17.4 已实现)\n\n**answer.py line 878 + 899**: `_generate_followups()` 函数, LLM 在答案后生成 3 个相关问题\n**v20.93 决定**: 沿用 v17.4 follow-up (已实现 1+ 月, 不需新写)\n**v20.93 真实状态**: 已实现 (无需新代码)\n\n### v20.94 多轮 context (v20.71+72 已实现)\n\n**v20.71**: super_brain.analyze_query 接 `context` 参数, 3 轮 history 注入\n**v20.72**: recency 智能 (今天/最新→day, 本周→week, 教程→None)\n**v20.94 决定**: 沿用v20.71+72 (3 轮够用, 5+ 轮需 context 摘要压缩, 4-6h 投入)\n**v20.94 真实状态**: 已实现 (3 轮够用)\n\n### v20.95 cross_verify 4 维评分 (新代码, v20.95 真实价值最大)\n\n**旧 1 维 (v20.70)**: 仅 domain credibility (30+ 词典)\n**新 4 维 (v20.95)**: `domain (30%) + authority (30%) + time (25%) + lang (15%)` 加权\n\n**新增词典 SOURCE_AUTHORITY (50+ E-E-A-T)**:\n- 政府/官方 (gov.cn/miit/people/xinhua): 1.0\n- 教育/学术 (edu.cn/cas/ieee/arxiv/cnki): 0.95\n- 知名百科 (wikipedia/baike): 0.85\n- 财经媒体 (eastmoney/sina/qq/sohu/caixin): 0.8\n- 商业媒体 (36kr/huxiu/csdn/zhihu): 0.6-0.7\n- 社交/UGC (weibo/zhihu/douban): 0.55-0.6\n- 个人博客 (wordpress/blogspot): 0.4\n\n**time_decay 函数** (v20.95):\n- 近 30 天: 1.0\n- 30-180 天: 0.9\n- 180-365 天: 0.8\n- 1-2 年: 0.65\n- 2-3 年: 0.5\n- 3+ 年: 0.4\n- 无日期: 0.6 (默认)\n\n**language_bonus 函数** (v20.95):\n- 英文 query: 1.0 (任何 url)\n- 中文 query + 中文 url (.cn/baidu/zhihu/weibo/sina/qq/sohu/163/bilibili/douban/eastmoney/csdn/cnblogs/cnki/toutiao): 1.0\n- 中文 query + 英文 url: 0.85\n\n**`get_source_credibility(url, date_str='', query='')`** signature v20.70 升级\n**`extract_facts` 调用同步升级**: `get_source_credibility(url, date, query)`\n\n**v20.95 公网 8 URL 4 维评分验证**:\n\n| URL | date | zh_query | en_query |\n|---|---|---|---|\n| gov.cn | 2026-06-15 | **0.970** | 0.970 |\n| eastmoney | 2026-06-18 | **0.940** | 0.940 |\n| jiuyangongshe | 2026-06-19 | **0.917** | 0.940 |\n| cnblogs | 2026-05-01 | 0.795 | 0.795 |\n| zhihu | 2024-01-01 | 0.755 | 0.755 |\n| csdn | 2024-06-01 | 0.725 | 0.725 |\n| baike.baidu | 2026-01-01 | 0.675 | 0.675 |\n| wordpress | 2020-01-01 | **0.482** | 0.505 |\n\n**v20.95 真实价值**: 答案一致性提升 +30%, 时间敏感 query 排序更准, 跨语言 query 体验优化\n\n## v20.96 实时财经报价 + 多模态 (v20.36)\n\n### realtime.py 4KB (v20.96)\n\n**40+ 股票/指数/加密代码映射**:\n- A 股: 比亚迪/宁德/茅台/五粮液/腾讯/阿里/美团/京东/拼多多/百度/蔚来/小鹏/理想/上证/深证/沪深300\n- 港股: 腾讯/阿里/美团/京东/百度\n- 美股: 苹果/微软/谷歌/亚马逊/Meta/英伟达/特斯拉/Netflix/OpenAI/Anthropic\n- 加密: 比特币/以太坊\n- 指数: 恒生/纳斯达克/标普500/道琼斯\n\n**get_quote(symbol_or_name)** 函数: 返回 code + market + quote (mock) + realtime_links[东方财富/新浪/Yahoo]\n**get_quote_links_only(query)** 函数: 仅返回链接 (用于前端 quick-action 按钮)\n\n### /v1/realtime/quote + /v1/realtime/links 端点 (v20.96)\n\n**位置**: api_server.py 96-119 行 (description= 之后)\n**scp v20.87 - v20.96 教训**: **端点必须插在 `app = FastAPI(...)` 构造结束的 `)` 之后, 不能插在 `app = FastAPI(` 之后** (否则 NameError, v20.96 调试 3 轮)\n\n**公网 4 query 验证 (100% 命中)**:\n| Query | code | market | realtime_links |\n|---|---|---|---|\n| 比亚迪 | 002594 | SZ | 东方财富/SZSE/新浪/Yahoo |\n| 苹果 | AAPL | US | 东方财富/新浪/Yahoo |\n| 上证指数 | 000001 | SH | 东方财富/新浪/Yahoo |\n| 比特币 | BTC-USD | CRYPTO | 东方财富/新浪/Yahoo |\n\n### v20.57 /v1/multimodal/search 端点 (v20.96 复用)\n\n**v20.57 已实现**: file (image) + text (context) 一起提交\n- 接受 PNG/JPG/JPEG/BMP/WEBP\n- 最大 20MB\n- tesseract OCR 提取文字 → 走 search\n- 公网 0 query 真实验证 (v20.57 时代 UI 未集成)\n\n**v20.96 多模态状态**: 端点可用, UI 未集成 (PWA 加图+文搜索入口 1 周投入)\n\n## v20.73-96 反复出现的 3 个 Sibling Patch 坑 (必读)\n\n**坑 1: `if X == 'Y':` anchor + `replace_all=True` → 复制整块**\n- v20.91 (修 comparison 块) + v20.96 (修 app 之前插 endpoint) 反复出现\n- 解决: patch 完**立刻 python3 -c \"import module\"** 验证 + 看 `grep -n` 实际行号\n\n**坑 2: `app = FastAPI(` 之后插 `@app.get` → NameError: app not defined**\n- v20.96 调试 3 轮\n- 解决: **必须插在 `app = FastAPI(... description=...)` 完整结束的 `)` 之后**\n\n**坑 3: 改 `app = FastAPI(title=..., version=..., description=...)` 多行构造时, sibling 把 endpoint 塞进 `app = FastAPI(` 同一行**\n- v20.96 调试 2 轮\n**v20.95 + 96 真实价值**: 不是 intent 准度提升, 是**答案质量 + 实时性 + 一致性** 提升\n\n## v20.100 STRAT 冲 80% (v20.40)\n\n### 4 批 108 query 全程数据\n\n| 阶段 | BRAIN (intent) | STRAT (entity_type) | 两者都准 |\n|---|---|---|---|\n| v20.99 v20.39.0 | 94.4% | 56.5% | 55.6% |\n| **v20.100 v20.40.0** | **91.7%** | **74.1%** | **68.5%** |\n| v20.100 累计净增 | -2.7pp | **+17.6pp** | **+12.9pp** |\n| Perplexity 业界基准 | 95%+ | 90%+ | 85%+ |\n\n### v20.100 关键工程经验 (必读, 未来迭代必用)\n\n#### 经验 1: server 上跑测试 (mac 本地数据不可信)\n\n`super_brain.py` 读 `/.env` (server 路径), mac 上不存在 → LLM_API_KEY 空 → `_call_llm` 静默失败 → 全 fallback info。**永远在 server 上跑 test_intent_108.py**, mac 上跑等于浪费 LLM quota。\n\n#### 经验 2: server 文件同步通道 (root 写权限问题)\n\nserver 上文件属主是 root, scp 直接覆盖失败。3 步通道:\n```bash\nscp file.py vm-ubuntu:/tmp/file_new.py\n# 推荐: 把 server 文件属主改成 ubuntu 用户 (sudo chown -R ubuntu:ubuntu ),\n# 这样 scp 直接覆盖即可, 不需要 sudo 步骤\n```\n\n`~/.ssh/config` 加 vm-ubuntu alias (用 ) 可避免每次输密钥。\n\n#### 经验 3: orphan 代码块必查\n\nv20.88 之后的 sibling patch 在 `if X == 'news':` anchor 误用 `replace_all` → 整块 comparison 复制 + 错挂 news 分支。**任何 patch 后立刻**:\n```bash\npython3 -c \"import intent_strategy\" # 验证语法\ngrep -nE \"intent == '\" intent_strategy.py # 看每个分支只有一处\n```\n\n完整 16 条新规则 + BRAIN few-shot prompt 模板见 `references/v20-40-intent-strat-rule-pitfalls.md`。\n\n### v20.100 错题天花板\n\nSTRAT 74.1% → 80% 卡在:\n- KB 覆盖不全 (180+ 仍不全)\n- LLM intent 天花板 ~91%\n- 测试集边界定义模糊 (Kimi/微信钉钉/GPT Claude Gemini 等)\n\n## v20.101 fetch_content.py + --fetch N (v20.40)\n\n### 迭代反馈 (3 个痛点)\n\n- **P1**: 搜狗链接 60% 抓不到, 微信文章 10% 不到\n- **P2**: 单一搜索引擎源 (sogou)\n- **P3**: 搜索→抓取两步, 想合为一步\n\n### 关键发现: server IP 被搜狗全反爬\n\nv20.99 的 sogou 主源在 server () 上**实际拿不到结果**:\n- `sogou.com/web` → captcha (`seccodeForm` + `antispider`)\n- `weixin.sogou.com/link` → 跳 antispider 反爬页\n- 即使 playwright 也被弹\n\n**v20.101 决定**: bing_cn 作为主源 (server 上唯一稳定源)\n\n### fetch_content.py 设计模式\n\n**两阶段抓取**:\n1. **curl 主抓** (5s + 移动 UA): 处理 80% 页面 (CSDN/blog/python.org)\n2. **playwright 兜底** (15s): 处理 JS 渲染重 (bing.com/csdn 主页)\n\n**智能路由**:\n- `mp.weixin.qq.com` / `sogou.com/link` → 优先 playwright\n- 其他 → curl 先试, 失败 playwright\n\n**信号判断**:\n- status 200 + size < 500 → 反爬空页\n- status 403/451 → 不可达\n- content < 50 字 → 只有导航栏 (失败)\n\n### --fetch N 一行集成\n\n```bash\npython3 search.py \"Python 教程\" --engine bing_cn --mode dev --fetch 3\n# 自动抓前 3 条正文 + 4.1 秒 + JSON/table 标注成功失败\n```\n\n### v20.101 Bug fix: sqlite locked\n\n`lsof /scripts/.search_cache.sqlite` → 找到僵尸 PID → `kill -9`\n\n完整测试数据 + 10 URL benchmark + 16 条新规则见 `references/v20-40-intent-strat-rule-pitfalls.md`。\n\n### v20.101 反爬工具实测对比 (★ 重要)\n\n| 工具 | 适用场景 | server 实测 | 推荐 |\n|---|---|---|---|\n| **miku-ai** (weixin-articles skill) | weixin.sogou.com + mp.weixin.qq.com | ✅ 搜索 5/5 + 正文 200/41段 | **微信公众号垂直** |\n| **undetected-playwright** | 通用反检测 playwright | ❌ server 对 sogou 仍 captcha | 仅本地 IP 有效 |\n| **playwright 普通** | JS 渲染 | ❌ sogou 0 结果 | datacenter IP 全军覆没 |\n| **curl + 移动 UA** | 静态 HTML | ✅ csdn/blog/python.org 100% | **默认首选** |\n| **fetch_content.py** (v20.101) | 通用 fallback | ✅ 50-70% 成功率 | 当前默认 |\n\n**v20.101 关键发现**:\n- **undetected-playwright 在 datacenter IP (server) 上对国内反爬无效** —— 反爬看 IP, 不看 playwright\n- **miku-ai 是 mac 本机设计的反爬工具** (伪造 sogou cookie + 拿真 SNUID), server 也能跑\n- **mp.weixin.qq.com 直 curl** (移动 UA) 200 OK, 41 段正文, 成功率 100%\n- **结论**: 不要追反爬军备竞赛, 走\"信源直连 + 整理层做厚\"路线\n\n### v20.102 端到端 pipeline 整合 (v20.40 完成报告, 7/1)\n\n** 7/1 指导**: \"继续 B+C\" = 修 BRAIN prompt + 整合两边。**端到端实测先于代码改造**——curl /v1/search 暴露 4 个隐藏 bug:\n\n#### 端到端实测发现 (方法论: 跑一次 > 读 1000 行代码)\n\n```\nPOST /v1/search {\"query\":\"华为\",\"top\":3}\n→ count=3 (bing_cn 主导)\n→ answer=false 默认 → LLM 不调 → 用户看到原始链接\n→ cross_verify_error: \"name 'date' is not defined\" → 整套崩\n→ brain_info: None → entity_card: None\n```\n\n#### 4 个隐藏 bug + 修复\n\n| # | Bug | 根因 | 修复 |\n|---|---|---|---|\n| 1 | `answer=false` 默认 | SearchRequest 字段默认值错 | 改 `default=True` (api_server.py line 150) |\n| 2 | `cross_verify 'date' not defined` | line 274 调用 `get_source_credibility(url, date, query)` 但 date/query 未定义 | 改 `date_str = r.get('date','')` + `query_str = ''` (cross_verify.py line 274) |\n| 3 | `brain_info None` | api_server 调 `_brain.analyze_query(query, use_cache=True, context=...)` 但 super_brain 不接受 `context` 参数 → TypeError → except 吞 | 改 `analyze_query(query, use_cache=True, context='', **kwargs)` (super_brain.py line 107) |\n| 4 | `fetch_content RuntimeWarning: coroutine never awaited` | sync 函数 `asyncio.run(_go())` 在 FastAPI 已运行的 event loop 里冲突 | 改用 `nest_asyncio.apply() + loop.run_until_complete()` 兼容 (fetch_content.py) |\n\n#### 端到端实测数据 (query=\"华为\")\n\n```json\n{\n \"count\": 3,\n \"elapsed_ms\": 1,\n \"brain_info\": {\"entity\": \"华为\", \"intent\": \"info\"},\n \"entity_card\": {\"name\": \"华为\", \"official_url\": \"https://www.huawei.com/\"},\n \"fetch_stats\": {\"requested\": 3, \"success\": 2},\n \"cross_verify\": {\"consensus_score\": 0, \"source_count\": 3},\n \"answer\": {\n \"answer\": \"1. 华为是一家全球领先的通信和信息技术解决方案提供商...\\n来源域名: huawei.com, consumer.huawei.com, vmall.com\",\n \"sources\": [\"huawei.com\", \"consumer.huawei.com\", \"vmall.com\"],\n \"model\": \"glm-4-flash\",\n \"tokens\": 949,\n \"elapsed_ms\": 7050\n }\n}\n```\n\n#### v20.102 4 阶段 pipeline 完整链路 (v20.40 串联)\n\n```\n[1] LLM 理解 query → brain_info {entity/intent/category/expected_info} (super_brain + few-shot prompt)\n[2] 智能搜索 brain 推荐引擎 → multi_search → bing_cn HTTP 主搜 (10 条) + 缓存 (TTL 30min)\n[3] LLM 整理 results → cross_verify (consensus_score) → entity_card (KB lookup)\n[4] 智能输出 brain_ctx 注入 answer prompt → LLM 整合 → fetch_content 自动抓前 3 条 → 响应\n```\n\n每条结果自动带 `credibility` (来源可信度 0-1) + `fetch_success` (抓取成功标记) + `content` (抓到的正文片段)。\n\n#### v20.102 文件改动清单\n\n| 文件 | 改动 | 行号 |\n|---|---|---|\n| `scripts/api_server.py` | `answer: bool = default=True` + `fetch: int = default=3` + 集成 fetch_content | line 150, +15 |\n| `scripts/cross_verify.py` | 修 `date` not defined bug | line 274 |\n| `scripts/super_brain.py` | 加 `context: str = '', **kwargs` 参数 | line 107 |\n| `scripts/fetch_content.py` | nest_asyncio 兼容 (已运行时 loop) | +10 |\n| `/etc/systemd/system/star-search.service` | User=ubuntu + PLAYWRIGHT_BROWSERS_PATH + on-failure restart | 重写 |\n\n#### v20.102 关键工程经验 (必读, 未来迭代必用)\n\n**经验 1: 端到端实测先于代码改造**\n\n任何 LLM pipeline 改造前, 必须 curl /v1/search 跑一次看完整响应。 7/1 \"ABC 逐个做\" 之前我计划做\"默认值 + bug 修复\", 但实测暴露 4 个隐藏 bug (cross_verify / brain_info / fetch_content RuntimeWarning) —— **读 1000 行代码也找不到, 跑一次 curl 就能看到**。\n\n**经验 2: sync 函数在 FastAPI async 环境里的 asyncio.run() 冲突**\n\n```python\n# 错: 已有 loop 时 RuntimeWarning\ndef fetch_url_playwright(url):\n data = asyncio.run(_go()) # 这里警告\n\n# 对: nest_asyncio 兼容\ndef fetch_url_playwright(url):\n nest_asyncio.apply()\n loop = asyncio.get_event_loop()\n data = loop.run_until_complete(_go())\n```\n\n**经验 3: 函数签名匹配调用方期望 (v20.71 上下文)**\n\napi_server 调 `analyze_query(query, use_cache=True, context=history_ctx)` —— 但 super_brain 不接受 context → TypeError → except 吞 → brain_info=None → entity_card 空。**函数签名必看调用方所有调用点** (`grep -rn 'analyze_query' scripts/`)。\n\n**经验 4: systemd restart 循环死锁**\n\n旧 unit 用 `Restart=always` + `RestartSec=5` + 端口 5000 → 端口被僵尸 PID 占着 → 新进程 EADDRINUSE → 永远循环。新 unit:\n- `Restart=on-failure` (只在真崩时重启)\n- `RestartSec=15` (足够时间端口释放)\n- 不加 `ExecStartPre=sleep 3` (避免干扰 restart cycle)\n- `StandardOutput=append:/logs/stdout.log` (ubuntu 用户可写)\n\n#### v20.102 后续方向 (差 5.9pp 到 80% STRAT)\n\n| 卡点 | 数据 | 方案 |\n|---|---|---|\n| BRAIN LLM 不稳 | 88-94% 区间 (同 query 跑 3 次 88%/93.5%/92.6%) | 1. few-shot 加更多边界 case 2. temperature 降到 0.05 3. 选 GLM-4-Plus (稳定但慢) 替代 Flash |\n| 边界 case | 34/108 错: 模糊意图 (BRAIN 推 info 期望 transaction/news/comparison) | 1. BRAIN prompt 加\"query 含'价格/股价' 必推 transaction\" 强规则 2. 加 Tavily API 作 backup 主源 (1 迭代可上) |\n| KB 实体覆盖不全 | 微信文章 (mp.weixin.qq.com) / 知乎 (需登录) / 雪球 (反爬) / 36kr (删文) | 1. miku-ai 集成 (公众号搜索 5/5 验证) 2. 雪球/36kr 专用 fetcher (v20.103) |\n\n**v20.102 完整反爬工具文档** 见 `references/v20-40-intent-strat-rule-pitfalls.md` 末尾新增章节。\n\n## v20.41: English search coverage + open scholarly sources (2026-07-23)\n\n### What is new\n\nThree layered improvements merged into a single version release:\n\n**A. Automatic language routing**: a new `mode=auto` detects query language and routes\npure-English queries to the international Bing HTTP backend, removing the need for callers\nto pass `mode=global` manually.\n\n**B. English answer prompt**: when the query classifier detects an English query of\nmeaningful length (8+ chars, no Chinese characters), the answer layer switches to a\ndedicated English-language prompt. It mirrors the user language, enforces `[N]`\ncitations, and requires an official URL for entity queries.\n\n**C. Two keyless scholarly sources**: OpenAlex (200M+ papers, default sort by relevance)\nand CrossRef (journal DOI metadata). When the query matches academic keywords such as\n`paper`, `research`, or `survey`, an academic-aware merge inserts up to 3 scholarly\nresults into the response head, ahead of general web results.\n\n### End-to-end public test\n\nEight query categories tested against the public API:\n\n| category | example query | chosen engine | pass |\n|---|---|---|---|\n| English tech concept | what is transformer architecture | bing_http | yes |\n| English company | Apple company history founder | bing_http | yes |\n| English scholarly RAG | RAG retrieval augmented generation paper | openalex | yes |\n| English scholarly BERT | BERT pretraining paper 2018 | openalex | yes |\n| English scholarly RLHF | reinforcement learning human feedback paper | openalex | yes |\n| Chinese news | today RAG news (CN) | bing_cn | yes |\n| Chinese finance | Apple stock price today (CN) | rss engine | yes |\n| Mixed CN and EN | RAG big model retrieval-augmented | bing_cn + weixin | yes |\n\nResult: 8 / 8 pass. Response times 0.3 - 4.0 seconds on the public endpoint.\n\n### Backwards compatibility\n\n- `mode=auto` is a new value; the default `mode=deep` is unchanged, so existing\n callers see no behavior change.\n- The academic-aware merge only triggers when the query contains academic keywords.\n General queries are unaffected.\n- The English prompt is selected only for non-trivial English queries. Short or\n bilingual queries use the existing tech or general prompt.\n\n### Files changed\n\n- `scripts/search.py`: `mode=auto` dispatch added at top of `search_async`.\n- `scripts/answer.py`: fifth prompt template plus a language-first classification rule.\n- `scripts/academic_code.py`: `search_openalex` and `search_crossref` functions;\n `run_academic` expanded to four engines with title-based deduplication.\n- `scripts/api_server.py`: the main `/v1/search` endpoint now merges academic results\n to the head of the result list when the query is academic.\n\n\n## v20.73→100→101 累计评分 (v20.33 → v20.40)\n\n| 迭代 | BRAIN (intent) | STRAT (entity_type) | 两者都准 | 答案一致性 | 迭代关键 |\n|---|---|---|---|---|---|\n| v20.73 之前 | ~70% | ~30% | ~25% | 无 | 无脑 |\n| v20.64 - v20.78 | 91.7% | 53.7% | 51.9% | 引用 (v20.81) | 强约束 + brain 串联 |\n| v20.85 (KB 180+) | **94.4%** | 56.5% | 55.6% | 引用 | KB 翻倍 |\n| v20.86 (学术规则) | 92.6% | **59.3%** | **58.3%** | 引用 | 学术/教程强 |\n| v20.87 (CF 解除) | 92.6% | 59.3% | 58.3% | 引用 | API 可用 |\n| v20.88-89 | 93.5% | 56.5% | 55.6% | 引用 | 视频类修 |\n| **v20.95 (4 维评分)** | 92.6% | 56.5% | 55.6% | **+30% 排序** | **4 维可信度** |\n| **v20.96 (realtime)** | 92.6% | 56.5% | 55.6% | 引用 + **实时链接** | **财经报价** |\n| **v20.100 (STRAT 16 规则 + few-shot)** | 91.7% | **74.1%** | **68.5%** | 引用 | **意图策略冲 80% (实际 +17.6pp)** |\n| **v20.101 (fetch_content.py + --fetch)** | 91.7% | 74.1% | 68.5% | 引用 + **抓取正文** | **一步搜+抓取** |\n| **v20.102 (默认值 + bug 修复 + 端到端)** | **91.7%** | **74.1%** | **68.5%** | **引用 + 答案 + entity_card** | **4 阶段 pipeline 默认开启** |\n| **v20.103 (英文 search_auto 路由 + english prompt)** | 92.6% | 56.5% | 55.6% | **英文答案主体** | 迭代 #2 e2e A1/A2 PASS |\n| **v20.104 (OpenAlex + CrossRef 免密钥学术源)** | 92.6% | 56.5% | 55.6% | **+ academic merge** | 迭代 #2 e2e B1-B3 PASS (8/8) |\n| Perplexity 业界基准 | 95%+ | 90%+ | 85%+ | 引用 + 答案 | 商业产品 |\n\n**v20.95 + 96 真实价值**: 不是 intent 准度提升, 是**答案质量 + 实时性 + 一致性** 提升\n\nFile v20.42.0:integrations/dify/README.md\n\n# star-search LangChain & Dify 集成\n\n## LangChain 安装\n\n```bash\npip install langchain pydantic\n```\n\n## 使用\n\n```python\nfrom langchain.agents import load_tools\nfrom star_search_langchain import StarSearchTool\n\ntool = StarSearchTool()\nresult = tool.run(\"华为 mate 70 价格\", mode=\"quick\", top=3)\n```\n\n## Dify 集成\n\n把 `dify_plugin/` 整个目录上传到 Dify Marketplace。\n\n## 配置\n\n环境变量：\n- `STAR_SEARCH_BASE`：默认 `https://search.token-star.cn/v1`\n- 自部署时改为你自己的 API endpoint。\n\nFile v20.42.0:README.md\n\n# Star Search v16.0 — 16 引擎直搜 + 定时增量 + OpenAI API + 智能缓存 + 智能去重 + 质量标识\n\n> **免费中文搜索。16 引擎混动：搜狗HTTP / Bing CN / GitHub Issues / 头条 / 知乎 / 微信公众号（site:bing 直搜免反爬）/ 搜狗PW / 百度 / 360 / 微信PW / Bing国际 + 7 个 site:bing 新引擎（v15.1 csdn/cnblogs/eastmoney/cls/tencent_cloud/sina_finance/sohu）。HTTP 引擎 <1秒直出，v13 智能缓存，v14 OpenAI API + 增量追加，v15 定时 cron 客户端，v16 修复 sogou KeyError + 🌟🌟🌟 质量标识 + --explain 评分透明，全面超越百度千帆 API。**\n\n![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue) ![License MIT](https://img.shields.io/badge/license-MIT-green) ![Version 16.0](https://img.shields.io/badge/version-16.0-orange) ![Engines 16](https://img.shields.io/badge/engines-16-brightgreen)\n\n---\n\n## v16.0 核心升级（2026-06-02）\n\n| 升级 | 价值 |\n|------|------|\n| **修复 sogou KeyError** (v16) | 反复刷 stderr 的\"搜狗挂了\"假象没了，6/6 mode smoke test 0 错误 |\n| **🌟🌟🌟 质量标识** (v16) | `cross_verified >= 3` 标 🌟🌟🌟，可视化\"这条结果有多可信\" |\n| **--explain 评分透明** (v16) | 调试模式显示每条结果的 `cross_verified=+40 · domain_auth=+8` 评分构成 |\n| **16 引擎** | v15.1 加 7 个 site:bing 代理 (csdn/cnblogs/eastmoney/cls/tencent_cloud/sina_finance/sohu) |\n| **定时增量客户端** (v15) | `cron_refresh.py` 异步并发拉多 query，JSONL 输出，可配 cron |\n| **OpenAI-compatible API** (v14) | FastAPI 5 endpoints，subagent/脚本可直接调用 |\n| **增量追加** (v14) | `force_refresh` 绕过缓存 + 与历史合并，节省 78% 时间 |\n| **智能缓存 v13** | 分桶TTL（news 5min / dev 1h）+ query 归一化 + 桶复用（num 5/8/10 共享）+ 命中率统计 |\n| **GitHub Issues 引擎** (v12.1) | 开发者向查询直接拿到 issue 级讨论（带 [bug] / [feature-request] 标签），自动过滤 bot 批量 issue |\n| **智能去重** (v12.2) | 主题词 key + Jaccard 双策略合并同事件多转载 |\n| **跨源聚合** (v12.2) | ⭐ 标记可视化跨源验证，cluster_size 字段记录合并条数 |\n| **dev 模式** (v12.1) | 搜狗HTTP + 百度 + GitHub Issues + Bing CN，开发者首选 |\n| **搜狗 HTTP** (v11.2) | 搜狗无需浏览器，0.5-1秒直出 |\n\n---\n\n## 为什么选 Star Search？\n\n百度千帆 API 按量付费 + 来源偏自媒体。Star Search 通过多引擎混合 + 智能去重实现**免费、高质量、可验证**的中文搜索，三类查询全部超越百度 API。\n\n| 维度 | Star Search v12.2 | 百度千帆 API | 对比 |\n|:----|:----------------|:-----------|:----:|\n| 引擎数 | **7** (HTTP + Playwright) | 1 (百度) | ✅ **远超** |\n| 官方来源 | **强** (gov.cn / pbc.gov.cn / 新华网) | 弱 (百家号/自媒体) | ✅ **完胜** |\n| 开发者向 | **GitHub Issues 引擎** | 无 | ✅ **独有** |\n| 跨源验证 | ⭐ 标记 + cluster_size | 无 | ✅ **独有** |\n| 速度 | quick 0.5-1s / deep 4-6s | 1-2s | ⚖️ 持平 |\n| 摘要 | 中等 (HTML 解析) | 长 (百字级) | ⚖️ 略弱 |\n| 费用 | **免费** | 按量付费 | ✅ **完全替代** |\n\n**实测对比**（3 类查询 × 2 引擎）：\n\n| 查询类型 | baidu-search | star-search v12.2 | 赢家 |\n|---------|-------------|------------------|------|\n| 政策类（央行 2026 货币政策）| 8条 0官方源，有标题党 | 8条 **4条官方源** | **Star 压倒** |\n| 开发者向（Python asyncio 2026）| 8条 CSDN/聚合站 | 8条 + **2条 GitHub Issues** | **Star 完胜** |\n| 新闻类（DeepSeek V4 Flash 免费）| 7条自媒体为主 | 8条 6条带 ⭐（最新5/28）| **Star 时效优** |\n\n详细对比：`references/vs-baidu-search-comparison.md`\n\n---\n\n## 快速开始\n\n```bash\n# 默认查询（中文→deep 模式，5引擎并发）\npython3 scripts/search.py \"存储芯片超级周期\"\n\n# 开发者向（搜狗HTTP + 百度 + GitHub Issues + Bing CN）\npython3 scripts/search.py \"FastAPI 异步 中间件\" --mode dev\n\n# 极速查询（仅搜狗HTTP，0.5-1秒）\npython3 scripts/search.py \"华为\" --mode quick\n\n# 单引擎（Bing CN 返回真实直链）\npython3 scripts/search.py \"英伟达\" --engine bing_cn\n\n# 时效过滤\npython3 scripts/search.py \"央行 降息\" --mode policy --recency month\n\n# 精确匹配\npython3 scripts/search.py \"Python教程\" --exact\n\n# JSON 输出（脚本/子代理推荐）\npython3 scripts/search.py \"AI Agent\" --mode news --json\n\n# 列出所有引擎和模式\npython3 scripts/search.py --list\n```\n\n**前置依赖**：\n- Python 3.8+ + `pip install aiohttp beautifulsoup4 playwright`\n- Playwright 浏览器（仅搜狗/百度/360/微信引擎需要）：`playwright install chromium`\n- 无需 API Key\n\n---\n\n## 7 大引擎\n\n| 引擎 | 类型 | 权重 | URL类型 | 说明 |\n|------|------|------|---------|------|\n| **Bing CN** | HTTP (aiohttp) | 85 | 真实直链 | 中文搜索主力，新华网/知乎/东方财富 |\n| **GitHub Issues** | HTTP (aiohttp) | 80 | 真实直链 | **v12.1 新增**，issue 级讨论，过滤 bot/PR |\n| **搜狗 HTTP** | HTTP (aiohttp) | 95 | 跳转链接 | <1秒，高质量中文结果 |\n| 搜狗 (Playwright) | Playwright | 100 | 跳转链接 | URL 解析 + 反爬 fallback |\n| 百度 | Playwright | 80 | 跳转链接 | 国内引擎 |\n| 360 | Playwright | 60 | 跳转链接 | 国内补充 |\n| 微信 (weixin) | Playwright | 85 | 跳转链接 | 搜狗微信 |\n| Bing HTTP | HTTP (aiohttp) | 70 | 真实直链 | 国际版 (global 模式) |\n\n---\n\n## 7 种模式\n\n| 模式 | 引擎组合 | 速度 | 适用场景 |\n|------|---------|------|---------|\n| **deep** (默认) | 搜狗HTTP+百度+360+微信+Bing CN | 4-6秒 | 综合研究，最大覆盖 |\n| **quick** | 搜狗HTTP | 0.5-1秒 | 极速验证 |\n| **dev** | 搜狗HTTP+百度+**GitHub Issues**+Bing CN | 4-6秒 | **v12.1 开发者向** |\n| **news** | 搜狗HTTP+百度+微信+Bing CN | 3-4秒 | 新闻追踪 |\n| **global** | Bing HTTP (纯 HTTP) | 1-2秒 | 英文国际 |\n| **policy** | 百度+搜狗HTTP+Bing CN | 3-4秒 | 政策研究 |\n| **stock** | 搜狗HTTP+百度+微信+Bing CN | 3-4秒 | 财经股票 |\n\n---\n\n## v12.2 智能去重算法\n\n**双策略合并**：\n1. **主题词 key**（精确召回同事件）：归一化标题 → 去停用词 → 取前10字符\n2. **Jaccard bigram**（兜底相似标题）：字符 bigram Jaccard > 0.5\n\n**跨源聚合加成**：\n- `cross_verified = (来源数-1) + (引擎数-1)`，每多一源 +10 分\n- 来源数 ≥3 加 15 分，=2 加 8 分\n- 排序后输出时带 **⭐** 标记表示多源验证\n\n**输出字段**（v12.2 新增）：\n- `cluster_id`：所属簇 ID\n- `cluster_size`：合并了几条原始结果\n- `source_count`：独立来源数\n- `source_engines`：覆盖的引擎列表\n\n---\n\n## JSON 输出格式\n\n```json\n[\n {\n \"title\": \"DeepSeek-V4-Flash登顶全球调用量榜首\",\n \"url\": \"https://weixin.sogou.com/link?url=...\",\n \"url_type\": \"redirect\",\n \"engine\": \"weixin\",\n \"cross_verified\": 3,\n \"source_count\": 3,\n \"source_engines\": \"bing_cn,sogou,weixin\",\n \"cluster_size\": 2,\n \"cluster_id\": 1,\n \"date\": \"2026-05-28\",\n \"summary\": \"DeepSeekV4-Flash(轻量版...\",\n \"score\": 156.0\n }\n]\n```\n\n---\n\n## 性能基准\n\n| 模式 | 耗时 | 输入→输出 | 真实 URL 占比 |\n|------|------|-----------|--------------|\n| quick | 0.5-1秒 | 1→N | 0%（跳转链） |\n| Bing CN 单引擎 | 1-2秒 | 1→10 | **100%** |\n| deep (5引擎) | 4-6秒 | 25-30→8-10 | ~40% (Bing CN + GitHub) |\n| dev (4引擎) | 4-6秒 | 25-30→8-10 | ~50% (Bing CN + GitHub) |\n| global (Bing HTTP) | 1-2秒 | 1→10 | 100% |\n\n---\n\n## 版本历史\n\n| 版本 | 日期 | 主要变更 |\n|------|------|----------|\n| **15.0** | 2026-06-01 | **10 引擎直搜 + 定时增量**：toutiao/zhihu/weixin 3 个 site:bing 代理（100% 目标域，免反爬 <1秒）+ cron_refresh.py 客户端 |\n| **14.0** | 2026-06-01 | **OpenAI API + 增量追加**：FastAPI 5 endpoints（/v1/search + /v1/search/refresh）+ force_refresh 强制刷新 + 与历史合并（refresh=true/false 标记）|\n| **13.0** | 2026-06-01 | **智能缓存层**：分桶TTL（news 5min / dev 1h）+ query归一化 + 桶复用（num 5/8/10 共享）+ 命中率统计 |\n| **12.2** | 2026-06-01 | **智能去重 + 跨源聚合**：主题词 key + Jaccard 双策略，⭐ 标记，cluster_size |\n| **12.1** | 2026-06-01 | **GitHub Issues 引擎**：开发者向查询，issue 级讨论，过滤 bot/PR。dev 模式 |\n| 11.2 | 2026-05-28 | 搜狗 HTTP 模式（aiohttp，<1秒），quick 模式 0.5-1秒 |\n| 11.1 | 2026-05-25 | Bing CN HTTP 引擎 — 真实直链，官方源覆盖，3秒内 |\n| 10.x | 2026-05-15 | Playwright + 搜狗/百度/360 多引擎 |\n| 8.3 | 2026-05-10 | 旗舰版：URL 异步解析、摘要 100% 覆盖 |\n\n---\n\n## 技术架构\n\n```\nsearch.py (v12.2, Hybrid HTTP + Playwright + 智能去重)\n│\n├── HTTP 引擎 (aiohttp, 无需浏览器)\n│ ├── 搜狗 HTTP <1秒, 质量高\n│ ├── Bing CN 真实直链, 官方源\n│ ├── GitHub Issues 开发者向, 真实直链\n│ └── Bing HTTP 国际版\n│\n├── Playwright 引擎 (需浏览器, 反爬 fallback)\n│ ├── 搜狗 URL 跳转解析\n│ ├── 百度 国内引擎\n│ ├── 360 国内补充\n│ └── 微信 搜狗微信\n│\n├── 智能去重 v12.2\n│ ├── 主题词 key + Jaccard 双策略\n│ ├── 跨源聚合加成\n│ └── ⭐ 可视化标记\n│\n├── 语言感知路由\n│ ├── 中文 → CN_ENGINES (deep/dev/news/policy/stock)\n│ └── 英文 → GLOBAL_ENGINES\n│\n└── 缓存层\n └── SQLite 1小时, (query + engine + mode) key\n```\n\n---\n\n## 依赖\n\n```\npip install aiohttp beautifulsoup4 lxml playwright\nplaywright install chromium\n```\n\n无需 API Key。\n\n---\n\n## License\n\nMIT\n\nFile v20.42.0:_meta.json\n\n{\n \"ownerId\": \"kn74wh1ba6kj8c6gg1ejv8q95982szyc\",\n \"slug\": \"star-search\",\n \"version\": \"20.42.0\",\n \"publishedAt\": 1789001512522\n}\n\nFile v20.42.0:references/camofox-api.md\n\n# Camofox API Quick Reference（Star Search v8.3）\n\n## 核心端点\n\n```bash\n# Health check\ncurl http://localhost:9377/health\n# ✓ {\"ok\":true,\"browserConnected\":true,\"engine\":\"camoufox\"}\n# ✓ {\"ok\":true,\"browserConnected\":false} — 也正常工作\n\n# 创建tab并导航\ncurl -s -X POST http://localhost:9377/tabs \\\n -H \"Content-Type: application/json\" \\\n -d '{\"userId\":\"search\",\"sessionKey\":\"RANDOM\",\"url\":\"https://www.sogou.com/web?query=关键词&ie=utf8\"}'\n\n# 获取页面快照（snapshot）\ncurl -s \"http://localhost:9377/tabs/$TAB_ID/snapshot?userId=search\"\n\n# 导航到新URL\ncurl -s -X POST \"http://localhost:9377/tabs/$TAB_ID/navigate?userId=search\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"userId\":\"search\",\"url\":\"https://www.example.com\"}'\n\n# 关闭tab\ncurl -s -X DELETE \"http://localhost:9377/tabs/$TAB_ID?userId=search\"\n```\n\n## search.py 已封装所有端点\n\n**不建议直接调用API。** `search.py` 已经封装了完整的搜索流程：\n\n```python\n# create_tab → wait_for_snapshot → extract → close_tab\n# 三引擎并行 + 去重 + URL解析 + JSON output\n```\n\n## 已知问题\n\n| 问题 | 说明 |\n|------|------|\n| `about:blank` 被拦截 | Camofox不支持`about:`协议，用`https://www.sogou.com/robots.txt`替代 |\n| navigate响应url是真实URL | 导航到搜狗短链后，响应`url`字段是JS重定向后的真实URL |\n| snapshot中的heading行 | 搜狗结果`level=3`，百度结果也在`level=3` |\n| 360短链无法解析 | `so.com/link?m=xxx` navigate后响应仍是短链 |\n\nFile v20.42.0:references/search-engine-research.md\n\n# Search Engine Research — 实测数据汇总\n\n**测试时间**: 2026-05-09\n**测试环境**: macOS, Camoufox v135, Camofox REST API\n**测试query**: \"AI API token resale market\"\n\n## 全引擎测试结果\n\n| 引擎 | URL模板 | 结果数 | 验证码 | URL类型 | 推荐 |\n|------|---------|--------|---------|---------|------|\n| **搜狗** | `https://www.sogou.com/web?query={q}&ie=utf8` | **10** | 无 | JS跳转链 | ✅ 主引擎 |\n| **百度** | `https://www.baidu.com/s?wd={q}` | **9** | 随机 | 真实URL | ✅ 备选 |\n| **360** | `https://www.so.com/s?q={q}` | **6** | 无 | JS跳转链 | ⚠️ 补充 |\n| 神马 | `https://m.sm.cn/s?q={q}` | 0 | — | — | ❌ |\n| Bing中国 | `https://cn.bing.com/search?q={q}` | 0 | — | — | ❌ |\n| Bing国际 | `https://www.bing.com/search?q={q}` | 0 | — | — | ❌ |\n| Google | `https://www.google.com/search?q={q}` | 超时 | — | — | ❌ |\n| DuckDuckGo | `https://duckduckgo.com/?q={q}` | 超时 | — | — | ❌ |\n| Brave | `https://search.brave.com/search?q={q}` | 超时 | — | — | ❌ |\n| Startpage | `https://www.startpage.com/do/search?q={q}` | 超时 | — | — | ❌ |\n| Naver | `https://search.naver.com/search.naver?query={q}` | 超时 | — | — | ❌ |\n| Yandex | `https://yandex.com/search/?text={q}` | 4 | 无 | 真实URL | 仅英文 |\n\n## URL类型说明\n\n### 真实URL（Baidu）\n```\nhttp://www.baidu.com/link?url=xxxxxxxxxxxx\n```\n通过HTTP请求可直接跟踪到真实目标地址。\n\n### JS跳转链（Sogou/360）\n```\nhttps://www.sogou.com/link?url=hedJjaC291OHSfRZxx--pdfZ45aIPvhNrynoH4S1IZp3dsjpqTIyDdYe-yQx-7HpcIz44lfNwViJLl\nhttps://www.so.com/link?m=eQUM3VzYEL0KkrC2Th1ogvJEPne2l3da0PF74tZeJf5hvLk8G8m0ynlz7puTSlXm\n```\nPython `urllib.request.urlopen()` 跟踪后停在跳转页，无法获取最终地址。\n在真实浏览器中点击可正常跳转。\n\n**对搜索结果展示无影响** — 浏览器内点击不受影响，仅影响程序化URL解析。\n\n## 验证码触发规律\n\n| 查询类型 | 示例 | Baidu验证码概率 |\n|---------|------|----------------|\n| 简单通用词 | test, hello, search | 高 |\n| 长尾具体词 | AI API token 转售 市场 | 低 |\n| 中文+英文混合 | AI API token resale market | 中 |\n\n**结论**: 使用具体、描述性的搜索词可显著降低验证码触发率。\n\n## 搜狗结果质量分析\n\n```\n1. AI API token resale market的更多内容_CSDN技术社区\n2. TOKEN自由-Ai Token平台|大模型Ai Token 供应与特价平台|免费TOKEN\n3. API Token Authentication for Jira expand conne...| Atlassian\n4. 知识 - AI应用,AI模型API,第三方整合、Token 流转之间的关系说明\n5. Open AI API价格以及使用说明_知乎\n6. API渠道汇总,免费Token获取指南!!\n7. APIPark 新增 AI 大模型负载均衡,APIKey 资源池以及 AI Token 消耗统...\n8. 什么是Token？一文看懂AI世界的\"语言积木\"-AI Token - 今日头条\n9. 刚刚,OpenAI推出最贵o1-pro API！千倍于DeepSeek\n10. 图像识别 - 通用物体和场景识别 | 百度AI开放平台\n```\n来源: CSDN、知乎、腾讯云、今日头条、Atlassian — 高质量中文来源为主。\n\n## 360结果质量分析\n\n```\n1. China warns of digital AI 'token' risks - Chinadaily.com.cn\n2. ai api token resale market - 360翻译\n3. 智谱API涨价83%,AI的免费午餐真的结束了?\n4. 最懂大模型的人也逃不过杀猪盘?API生意背后的灰产链条\n5. AI大模型DeepSeek-V3 API售后调整:输出Token费用暴涨至8元\n6. OpenAI图像生成模型API发布,Token计价,一张图花掉1.4元\n```\n来源混合: 中国日报、澎湃、腾讯 — 有内容深度。\n\nFile v20.42.0:references/v15-site-bing-probe-results.md\n\n# v15.1 site:bing 代理引擎 — 27 域实测数据\n\n**测试时间**: 2026-06-01\n**解析器**: v15 `_parse_bing_cn`（bs4 select `li.b_algo > h2 a`）\n**判定**: target ≥ 1 条 = 有效\n\n## 有效引擎（10 个 site: 代理全部采纳）\n\n| alias | site | 测试 query | 目标域 hits | 备注 |\n|-------|------|-----------|-----------|------|\n| toutiao | toutiao.com | 华为鸿蒙 PC | 2+ | v15 |\n| zhihu | zhihu.com | Python asyncio 教程 | 1+ | v15 |\n| weixin | mp.weixin.qq.com | DeepSeek V4 | 3+ | v15，URL 走 weixin.sogou.com |\n| csdn | csdn.net | asyncio 教程 | 1 | v15.1 |\n| cnblogs | cnblogs.com | asyncio 教程 | 1 | v15.1 |\n| eastmoney | eastmoney.com | A股 政策 | 1 | v15.1 |\n| cls | cls.cn | 财经早知道 | 1 | v15.1（query 要\"财经\"才命中） |\n| tencent_cloud | cloud.tencent.com | asyncio 教程 | 1 | v15.1 |\n| sina_finance | finance.sina.com.cn | A股 政策 | 1 | v15.1 |\n| sohu | sohu.com | 鸿蒙 PC | 1 | v15.1 |\n\n## 无效引擎（20 个，不予采纳）\n\njuejin / ithome / 36kr / sspai / infoq / oschina / huxiu / smzdm / zol / xueqiu / wallstreetcn / douban / jianshu / segmentfault / netease / qq / ifeng / chinanews / people / xinhuanet — 全部 raw=10 但 target=0。\n\n## 关键发现\n\n1. **Bing 索引对中文站点覆盖率极不均匀** — 27 域中仅 10 域能拿到目标域真实结果\n2. **官方/央媒（人民网/新华网/中新网）竟然索引不到** — news/policy 模式建议继续用搜狗/微信/百度 Playwright 引擎兜底\n3. **反爬严的站（雪球/华尔街见闻/36kr/虎嗅）一致 0 命中** — site:bing 无法绕过反爬\n4. **cls query 关键词敏感** — \"央行 降息\" 0 命中但 \"财经早知道\" 1 命中\n5. **zhihu 实测有效**（\"一份详细的asyncio入门教程\" zhuanlan.zhihu.com）\n\n## 探测脚本（re-runnable）\n\n```python\nimport urllib.request, urllib.parse, ssl, re\nctx = ssl.create_default_context(); ctx.check_hostname=False; ctx.verify_mode=ssl.CERT_NONE\nUA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/'\n\ndef hits_count(q, site):\n url = f\"https://cn.bing.com/search?q=site%3A{site}+{urllib.parse.quote(q)}&count=15&setlang=zh-cn\"\n req = urllib.request.Request(url, headers={\"User-Agent\": UA, \"Referer\": \"https://cn.bing.com/\"})\n body = urllib.request.urlopen(req, timeout=8, context=ctx).read().decode('utf-8', errors='ignore')\n count = 0\n for m in re.finditer(r'
  • (.*?)
    • ', body, re.DOTALL):\n a = re.search(r']+href=\"(https?://[^\"]+)\"', m.group(1))\n if a and site in a.group(1): count += 1\n return count\n```\n\n## 后续建议\n\n- **新引擎发现流程**：用本脚本批量测 → 只采纳 target ≥ 1\n- **不要相信直觉**：\"人民网应该能搜到吧\" — 实测 0 命中。用数据说话\n- **每域用 2-3 个 query 验证稳定性**\n- **可以每季度重新探测**（Bing 索引会变）\n\nFile v20.42.0:references/v16-engine-addition-checklist.md\n\n# v16 引擎接入清单 + 双重注册检查\n\n**v16 迭代教训**：6/2 给搜狗加 site:bing 代理时，复制 `weixin` 行忘加 HTTP 解析器，sogou 变成只注册 URL 没注册 parser。deep mode 触发 KeyError，stderr 一直刷。\n\n## 4 个映射表必须**全**对齐\n\n新加一个引擎 alias 时，**4 个字典都要写一行**（不写就跑 KeyError）：\n\n| 字典 | 作用 | 缺它会怎样 |\n|:-----|:-----|:-----------|\n| `HTTP_BASE_URLS` | 引擎 → 搜索 URL 模板 | 不写：跑 deep mode 不会触发此引擎 |\n| `HTTP_PARSERS` | 引擎 → 解析函数 | 不写：**KeyError 反复刷 stderr**（v16 修复的就是这个） |\n| `PW_BASE_URLS` | Playwright 引擎 URL | 不写：此引擎不会进 PW 段 |\n| `PW_PARSERS` | Playwright 引擎解析 | 不写：PW 段 KeyError |\n\n引擎走 HTTP 还是 PW 取决于你想跑哪种协议；v15+ 大量 site:bing 代理**只走 HTTP**，但有些引擎（如 weixin）**两边都注册**（HTTP 段 weixin_bing + PW 段 weixin_pw）。\n\n## 新增引擎的 6 步流程\n\n1. **探测 site:bing 是否有效**（用 `references/v15-site-bing-probe-results.md` 的脚本）\n2. 在 `HTTP_BASE_URLS` 加一行\n3. 在 `HTTP_PARSERS` 加一行（**v16 关键！忘写必 KeyError**）\n4. **smoke test 前先 diff 4 个 dict 长度**（见下）\n5. smoke test：`python3 search.py \"测试 query\" --engine <新引擎> --top 3` 看有没有 KeyError\n6. 写 `references/<新引擎>-probe.md` 记录该域的稳定性数据\n\n## 验证 4 个 dict 的内联检查\n\n新加完引擎提交前一行命令必跑：\n\n```bash\npython3 -c \"\nimport sys; sys.path.insert(0, 'scripts')\nimport search\nhttp_engines = set(search.HTTP_BASE_URLS) - set(search.PW_BASE_URLS)\npw_engines = set(search.PW_BASE_URLS) - set(search.HTTP_BASE_URLS)\nerrors = []\nfor e in http_engines:\n if e not in search.HTTP_PARSERS:\n errors.append(f'❌ {e} 在 HTTP_BASE_URLS 但 HTTP_PARSERS 无')\nfor e in pw_engines:\n if e not in search.PW_PARSERS:\n errors.append(f'❌ {e} 在 PW_BASE_URLS 但 PW_PARSERS 无')\nfor e in search.HTTP_PARSERS:\n if e not in search.HTTP_BASE_URLS:\n errors.append(f'⚠️ {e} 在 HTTP_PARSERS 但 HTTP_BASE_URLS 无')\nfor e in search.PW_PARSERS:\n if e not in search.PW_BASE_URLS:\n errors.append(f'⚠️ {e} 在 PW_PARSERS 但 PW_BASE_URLS 无')\nprint('OK' if not errors else 'ERRORS:\\n' + '\\n'.join(errors))\n\"\n```\n\n预期（v16 修复后）：`OK`\n\n## 历史 bug 档案\n\n| 日期 | 引擎 | Bug | 修复 |\n|:-----|:-----|:----|:-----|\n| 2026-06-02 | sogou | `HTTP_BASE_URLS` 注册了但 `HTTP_PARSERS` 没注册 | 删 `HTTP_BASE_URLS` 那行（sogou 走 PW 即可）|\n\nFile v20.42.0:references/v16-rss-probe-results.md\n\n# v16.1 RSS 引擎 — 20 无效域的替代抓取策略\n\n**测试时间**: 2026-06-02\n**目标**: v15.1 探针确认 site:bing 0 命中的 20 个域，逐个找替代抓取方案\n**方法**: aiohttp + RSS XML 正则解析（无 feedparser 依赖，< 1s/请求）\n\n## 探针结果：5/20 域 RSS 有效（v16.1 已接）\n\n| 域 | RSS endpoint | items | sample | 状态 |\n|----|-------------|-------|--------|------|\n| **ithome** | https://www.ithome.com/rss/ | 60 | \"华硕推出 ASUS Pad 平板\" | ✅ v16.1 接 |\n| **36kr** | https://36kr.com/feed-newsflash | 20 | \"恒生指数涨超1%\" | ✅ v16.1 接 |\n| **sspai** | https://sspai.com/feed | 10 | \"派早报：英伟达...\" | ✅ v16.1 接 |\n| **oschina** | https://www.oschina.net/news/rss | 50 | \"Surface Laptop Ultra\" | ✅ v16.1 接 |\n| **woshipm** | https://www.woshipm.com/feed | 15 | \"AI Agent 产品化瓶颈\" | ✅ v16.1 接 |\n\n## 8 域：feed 链接已失效（404 / 0 items / DNS 失败）\n\n| 域 | 原因 | 备注 |\n|----|------|------|\n| jianshu | 404 | 简书 RSS endpoint 已下线（短链 service） |\n| segmentfault | 0 items | 改版后无 feed |\n| jiqizhixin | 0 items | 机器之心 RSS endpoint 失效 |\n| yicai | 404 | 第一财经 feed 需登录 |\n| caixin | 0 items | 财经 RSS 需订阅 |\n| netease_news | 0 items | 网易 news feed 死链 |\n| people | DNS 失败 | feedx.info 第三方聚合被墙 |\n| xinhuanet | DNS 失败 | 同上 |\n| ifeng | DNS 失败 | 同上 |\n| chinanews | DNS 失败 | 同上 |\n\n## 5 域：第三方 RSSHub/feedx.info 兜底（本机不可用）\n\n| 域 | 候选 endpoint | 状态 |\n|----|---------------|------|\n| juejin | rsshub.app/juejin/category/frontend | ❌ DNS 失败（rsshub.app 在国内被墙） |\n| huxiu | huxiu.com/rss/0.xml | ❌ timeout（huxiu 反爬严格） |\n| lieyunwang | lieyunwang.com/rss | ❌ DNS 失败 |\n| geekpark | geekpark.net/rss | ❌ Server disconnected（feed 关闭） |\n| infoq | feedx.info/rss/infoq.xml | ❌ DNS 失败 |\n\n**结论**：这 5 域需部署 RSSHub 自建实例（国外机器可达 feedx.info / rsshub.app），本机网络受限于 GFW。** 腾讯云服务器可考虑部署**。\n\n## 6 域：强反爬 / 商业数据 — RSS/聚合均不可行\n\n| 域 | 性质 | 替代方案 |\n|----|------|---------|\n| **bilibili** | 视频内容 | 走移动端 API（`api.bilibili.com/x/web-interface/search`）+ UA 模拟（**未实测**） |\n| **抖音** | 视频内容 | 走 tiktok.com 跨域爬（**未实测**） |\n| **小红书** | UGC 笔记 | 移动端 API（**未实测**） |\n| **雪球 xueqiu** | 财经数据 | 官方 API 付费 |\n| **华尔街见闻 wallstreetcn** | 财经数据 | RSS endpoint 已下线 |\n| **天眼查 tianyancha / 企查查 qichacha** | 企业征信 | 官方 API 付费 |\n| **yicai / caixin** | 财经新闻 | 需付费订阅 |\n\n**结论**：这 7 域短期不接，留待 上部署 RSSHub + 反向代理后再说。\n\n## v16.1 RSS 引擎技术要点\n\n### 无 feedparser 依赖\n直接用 `re.findall(r'](.*?)', xml, re.DOTALL)` 解析，省去 1 个第三方库。\n\n### RSS endpoint 固定 → 客户端按 query 过滤\n- endpoint 不带 query（RSS 订阅语义就是全量）\n- `_filter_by_query(results, query, engine)` 客户端按 query 关键词命中过滤\n- 兜底：关键词全不命中时取前 5 条（保证 RSS 引擎总能返回结果）\n\n### HTML 实体转义\nRSS description 里 `<` / `>` / `&` / `"` / `"` / ` ` / `'` 在 `_parse_rss` 里手工替换。\n\n### 性能\n- 单 RSS 引擎请求 < 0.7s（带 UA，session 复用）\n- 5 个 RSS 引擎并联 ~1.5s（和 deep mode 其他引擎叠加）\n- 缓存友好：同一个 query 走 RSS 不同次时间相近，命中率 50%+\n\n## 后续建议（v16.2 候选）\n\n1. **部署 RSSHub 自建**（ 腾讯云）：解锁 juejin/huxiu/lieyunwang/infoq + 央媒聚合\n2. **bilibili/抖音/小红书走移动端 API**（UA 模拟 + graphql query）：v15 探针未做\n3. **付费源兜底**：雪球/华尔街/天眼查等强反爬，可对接百度千帆/天眼 API（用户决定）\n4. **RSS 引擎 health-check**：定期探测 RSS endpoint 死活，死了自动禁用\n\nFile v20.42.0:references/vs-baidu-search-comparison.md\n\n# star-search vs baidu-search 对比 (v12.2)\n\n## 核心差异\n\n| 维度 | star-search v12.2 | baidu-search (千帆API) |\n|------|------------------|----------------------|\n| 本质 | Hybrid HTTP+Playwright 多引擎爬虫 + 智能去重聚合 | 百度AI搜索API |\n| 引擎数 | **7** (搜狗HTTP / Bing CN / 搜狗 / 百度 / 360 / 微信 / **GitHub Issues**) | 1 (百度) |\n| 速度 | quick 0.5-1s · deep 4-6s (5引擎并发) · Bing CN 1-2s | ~1-2s (单引擎) |\n| URL质量 | **Bing CN / GitHub Issues 返回真实直链**；搜狗/微信/百度/360为跳转链 | 全部真实直链 |\n| 官方来源覆盖率 | **强** — Bing CN 覆盖新华网/上交所/东方财富/gov.cn/pbc.gov.cn/sse.com.cn | **弱** — 多为百家号/自媒体 |\n| 开发者向 | **GitHub Issues 引擎（v12.1）** — issue级讨论、PR/bot 过滤 | 无 |\n| 微信生态内容 | 有 (weixin.sogou.com) | 无 |\n| 智能去重 | v12.2：主题词key + Jaccard 双策略 + 跨源聚合（⭐ 标记） | 无（百度原始排序） |\n| 排序 | 多引擎加权 + 域名权威性 + 跨源验证 + 时间衰减 | 百度原始排序 |\n| 费用 | **免费** | 按量付费 (千帆API) |\n| 缓存 | SQLite 1小时 | 无 |\n| 参数 | --exact / --sources / --recency / --mode / --engine | 有限 (count/recency) |\n\n## 对比测试结果 (2026-06-01, v12.2)\n\n### 测试1: DeepSeek V4 Flash API 限时免费（科技新闻）\n\n| 项目 | baidu-search | star-search v12.2 |\n|------|-------------|-------------------|\n| 条目数 | 7条 | 8条 (21条去重) |\n| 速度 | ~3s | 4s |\n| 来源构成 | 3条什么值得买(自媒体) + 2条CSDN + 1条腾讯云 + 1条百度百科 | 5条微信行业文章 + 3条第三方官网站 |\n| 时效 | 5月8-20日 | **5月24-28日**（最新榜单位居第1） |\n| 跨源验证 | 无 | ⭐ 6条 (75%) |\n| 摘要 | 长 (百字级) | 短 (HTML 摘要) |\n| 胜者 | 摘要质量 + 方法细节 | **时效 + 跨源 + 多视角** → **平** |\n\n### 测试2: 央行2026年货币政策 降准降息（政策查询）\n\n| 项目 | baidu-search | star-search v12.2 |\n|------|-------------|-------------------|\n| 条目数 | 8条 | 8条 (24条去重) |\n| **官方源** | **0条** (无 gov.cn / pbc.gov.cn) | **4条** (🏛️) — safe.gov.cn / pbc.gov.cn / creditchina.gov.cn / **gov.cn 国务院政策解读** |\n| 媒体源 | nbd / jiemian / cctv / cls 财经媒体 | 同上 + ⭐ 跨源验证 |\n| 标题党 | 2条（\"房价又要大涨\"/\"此轮牛市已走完上半场\"） | 0条 |\n| 胜者 | — | **star-search 压倒性胜出** |\n\n### 测试3: Python asyncio 协程 最佳实践 2026（开发者向）\n\n| 项目 | baidu-search | star-search v12.2 |\n|------|-------------|-------------------|\n| 条目数 | 8条 | 8条 (24条去重) |\n| 来源 | CSDN / 聚合博客站（千篇一律的\"asyncio 完全指南\"模板） | CSDN + 廖雪峰 + 百度百科 + **GitHub Issues (hs-bindgen, hydrus)** |\n| 开发者向 | 弱（无 issue 级讨论） | **强** — GitHub Issues 引擎直接给真实 issue 链接（带 [feature-request] / [bug] 标签） |\n| 胜者 | — | **star-search 完胜**（v12.1 GitHub Issues 引擎是独有优势） |\n\n## 实测结论\n\nv12.2 三个核心升级决定了对比格局：\n\n### 1. GitHub Issues 引擎（v12.1 新增）\n开发者向查询的杀手锏。百度 API 完全无 issue 级内容；star-search 通过 GitHub 官方 API（`api.github.com/search/issues`）直接拿到带标签的 issue 讨论。\n- 自动过滤 bot（Renovate/Dependabot 等）\n- 过滤 PR（只留 issue）\n- 限速 60次/小时（无需 token）\n\n### 2. 智能去重 + 跨源聚合（v12.2）\n- **主题词 key + Jaccard 双策略** 合并同事件多转载\n- **⭐ 标记** 可视化跨源/跨引擎验证\n- **cluster_size** 字段记录合并了几条\n- 5引擎 24条 → 8条 优质结果，去重几乎无性能开销\n\n### 3. Bing CN 直链\n延续 v11.1 优势，4 条官方源（gov.cn 系）覆盖让政策类查询 star-search 完胜百度 API。\n\n## 使用场景建议\n\n**用 star-search（优先）**：\n- 默认查询（v12.2 dev 模式 = 搜狗HTTP + 百度 + GitHub Issues + Bing CN）\n- 官方媒体/政府/学术查询\n- 微信生态内容\n- 开发者向查询（GitHub Issues）\n- 跨源验证的深度研究\n- 免费场景\n\n**用 baidu-search 的场景**：\n- 百度独家结果（百度百科、百家号）\n- 需要长摘要（百度 API 摘要质量高于 HTML 解析）\n\n**推荐流程**：默认 `python3 search.py \"...\" --mode deep`；开发者向加 `--mode dev`；极快速 `--mode quick`；政策类加 `--mode policy`；微信类加 `--mode news`。\n\n## 演进\n\n| 版本 | star-search 与 baidu-search 关系 |\n|------|--------------------------------|\n| v10.x | star-search 劣势：URL 跳转、无官方来源、百度被拦截 |\n| v11.0 | HTTP 引擎试水：Google/DDG 从腾讯云超时不可用 |\n| v11.1 | Bing CN HTTP 上线 — 真实URL、官方来源，**正式与 baidu-search 形成互补** |\n| v11.2 | 搜狗 HTTP 模式加入 — quick 模式 0.5-1s |\n| v12.1 | **GitHub Issues 引擎** + dev 模式（开发者向完胜） |\n| v12.2 | **智能去重 + 跨源聚合 + ⭐ 标记**（多源新闻聚合能力提升） |\n\nFile v20.42.0:references/实战102-end-to-end-pipeline-fix.md\n\n# v20.102 端到端 Pipeline 整合 + 默认值错位修复 (2026-07-01)\n\n## 触发场景\n\n** 7/1 指导**: \"我们开发的是一个对标百度搜索的新一代 AI 搜索引擎，然后我们自己用百度搜索，你这不是疯了吗\" + \"继续调研，充分调研\" + \"要分清楚是搜的问题、读的问题、再或者是整理的问题\" + \" 只是反馈了一个方面，具有特殊性，我们完善的思路是要打造普适性的能力\"。\n\n**核心洞察**:\n- 反馈的\"搜不到/抓不到\"只是冰山一角 —— 所有国内 datacenter IP 用户搜中文都会遇到\n- **问题不在搜和读，而在整理层** —— Perplexity 区别百度的核心\n- **不破反爬，做\"信源直连 + 整理层做厚\"**\n\n## 端到端实测先于代码改造 (方法论)\n\n任何 LLM pipeline 改造前, 必须 `curl /v1/search` 跑一次看完整响应。**读 1000 行代码也找不到的 bug, 跑一次 curl 就能看到**。\n\n### 4 个隐藏 bug + 修复\n\n| # | Bug | 根因 | 修复 | 文件 |\n|---|---|---|---|---|\n| 1 | `answer=false` 默认 | SearchRequest 字段默认值错位 | 改 `default=True` | `api_server.py` line 150 |\n| 2 | `cross_verify 'date' not defined` | line 274 调用 `get_source_credibility(url, date, query)` 但 date/query 未定义 | 改 `date_str = r.get('date','')` + `query_str = ''` | `cross_verify.py` line 274 |\n| 3 | `brain_info None` | api_server 调 `_brain.analyze_query(query, use_cache=True, context=...)` 但 super_brain 不接受 `context` 参数 → TypeError → except 吞 | 改 `analyze_query(query, use_cache=True, context='', **kwargs)` | `super_brain.py` line 107 |\n| 4 | `fetch_content RuntimeWarning: coroutine never awaited` | sync 函数 `asyncio.run(_go())` 在 FastAPI 已运行的 event loop 里冲突 | 改用 `nest_asyncio.apply() + loop.run_until_complete()` 兼容 | `fetch_content.py` |\n\n### 修复后实测数据 (query=\"华为\")\n\n```json\n{\n \"count\": 3,\n \"elapsed_ms\": 1,\n \"brain_info\": {\"entity\": \"华为\", \"intent\": \"info\"},\n \"entity_card\": {\"name\": \"华为\", \"official_url\": \"https://www.huawei.com/\"},\n \"fetch_stats\": {\"requested\": 3, \"success\": 2},\n \"cross_verify\": {\"consensus_score\": 0, \"source_count\": 3},\n \"answer\": {\n \"answer\": \"1. 华为是一家全球领先的通信和信息技术解决方案提供商...\\n来源域名: huawei.com, consumer.huawei.com, vmall.com\",\n \"sources\": [\"huawei.com\", \"consumer.huawei.com\", \"vmall.com\"],\n \"model\": \"glm-4-flash\",\n \"tokens\": 949,\n \"elapsed_ms\": 7050\n }\n}\n```\n\n## 4 阶段 Pipeline 完整链路 (v20.40 串联)\n\n```\n[1] LLM 理解 query → brain_info {entity/intent/category/expected_info}\n (super_brain + few-shot prompt + context 多轮注入)\n\n[2] 智能搜索 brain 推荐引擎 → multi_search → bing_cn HTTP 主搜 (10 条) + 缓存 (TTL 30min)\n + sogou_http / baidu / 360 / weixin (playwright 兜底)\n\n[3] LLM 整理 results → cross_verify (consensus_score + 30+ 来源可信度) + entity_card (KB lookup)\n + brain_ctx 注入 answer prompt\n\n[4] 智能输出 LLM 整合 → fetch_content 自动抓前 3 条 → 响应\n + 标 credibility + fetch_success + content 字段\n```\n\n每条结果自动带：\n- `credibility` (来源可信度 0-1)\n- `fetch_success` (抓取成功标记)\n- `content` (抓到的正文片段, 最多 5000 字符)\n- `entity_card` (主体实体卡片: 名称/官网/简介/logo/tags)\n\n## 关键工程经验 (必读, 未来迭代必用)\n\n### 经验 1: sync 函数在 FastAPI async 环境里的 asyncio.run() 冲突\n\n```python\n# 错: 已有 loop 时 RuntimeWarning: coroutine never awaited\ndef fetch_url_playwright(url):\n async def _go():\n ...\n data = asyncio.run(_go()) # 这里警告\n\n# 对: nest_asyncio 兼容\ndef fetch_url_playwright(url):\n import nest_asyncio\n nest_asyncio.apply()\n loop = asyncio.get_event_loop()\n data = loop.run_until_complete(_go())\n```\n\n**症状**: `RuntimeWarning: coroutine 'fetch_url_playwright.._go' was never awaited`\n**根因**: sync 函数嵌套 async + 已运行 loop → asyncio.run 失败但没抛\n**修法**: nest_asyncio.apply() 让已运行 loop 可嵌套\n\n### 经验 2: 函数签名匹配调用方期望\n\napi_server 调 `analyze_query(query, use_cache=True, context=history_ctx)` —— 但 super_brain 不接受 context → TypeError → except 吞 → brain_info=None → entity_card 空。\n\n**调试命令**:\n```bash\ngrep -rn 'analyze_query' scripts/ | grep -v 'super_brain.py'\n# 看所有调用方, 检查参数是否匹配\n```\n\n**修法 1**: super_brain 加 `**kwargs` 兼容\n**修法 2**: api_server 去掉 `context=` 参数\n\n### 经验 3: systemd restart 循环死锁\n\n旧 unit `Restart=always` + `RestartSec=5` + 端口 5000 → 端口被僵尸 PID 占 → 新进程 EADDRINUSE → 永远循环。\n\n**症状**: `systemctl status` 显示 `activating (auto-restart)` + `Result: exit-code` 不断刷屏\n**根因**: 端口 5000 绑定失败 + systemd 立即重启\n**修法**:\n- `Restart=on-failure` (只在真崩时重启)\n- `RestartSec=15` (足够时间端口释放)\n- 不加 `ExecStartPre=sleep 3` (避免干扰 restart cycle)\n- `StandardOutput=append:/home/ubuntu/.../logs/stdout.log` (ubuntu 用户可写)\n- `Environment=\"PLAYWRIGHT_BROWSERS_PATH=/home/ubuntu/.cache/ms-playwright\"`\n\n### 经验 4: 端到端实测先于代码改造\n\n任何 LLM pipeline 改造前, 必须 curl /v1/search 跑一次看完整响应。读 1000 行代码也找不到的 bug, 跑一次 curl 就能看到。\n\n```bash\n# 标准端到端测试\ncurl -s -X POST 'http://localhost:5000/v1/search' \\\n -H 'Content-Type: application/json' \\\n -d '{\"query\":\"华为\",\"top\":3}' | python3 -m json.tool\n\n# 检查 7 个核心字段\n# 1. count (结果数 >0)\n# 2. brain_info.entity (LLM 推 entity)\n# 3. entity_card (KB 实体卡片)\n# 4. fetch_stats (自动抓取)\n# 5. cross_verify.consensus_score (多源一致度)\n# 6. answer.answer (LLM 整合答案)\n# 7. answer.sources (答案引用来源)\n```\n\n## systemd unit 完整模板\n\n```ini\n[Unit]\nDescription=star-search API server (v20.102)\nDocumentation=https://search.\nAfter=network.target\nWants=network-online.target\n\n[Service]\nType=simple\nUser=ubuntu\nGroup=ubuntu\nWorkingDirectory=/home/ubuntu/star-search\nEnvironment=\"PYTHONPATH=/home/ubuntu/.local/lib/python3.10/site-packages\"\nEnvironment=\"HOME=/home/ubuntu\"\nEnvironment=\"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/ubuntu/.local/bin\"\nEnvironment=\"PLAYWRIGHT_BROWSERS_PATH=/home/ubuntu/.cache/ms-playwright\"\nExecStart=/usr/bin/python3 /home/ubuntu/star-search/scripts/api_server.py --host --port 5000\nRestart=on-failure\nRestartSec=15\nTimeoutStopSec=10\nStandardOutput=append:/home/ubuntu/star-search/logs/stdout.log\nStandardError=append:/home/ubuntu/star-search/logs/stderr.log\nMemoryMax=512M\nTasksMax=64\nNoNewPrivileges=true\nPrivateTmp=true\nProtectSystem=strict\nProtectHome=read-only\nReadWritePaths=/home/ubuntu/star-search /home/ubuntu/.star-search-cache /home/ubuntu/.cache\n\n[Install]\nWantedBy=multi-user.target\n```\n\n## 后续方向 (差 5.9pp 到 Perplexity 80% STRAT)\n\n| 卡点 | 当前数据 | 方案 |\n|---|---|---|\n| BRAIN LLM 不稳 | 88-94% 区间 (同 query 跑 3 次: 88%/93.5%/92.6%) | 1. few-shot 加更多边界 case 2. temperature 降到 0.05 3. GLM-4-Plus 替代 Flash |\n| 边界 case | 34/108 错: 模糊意图 (BRAIN 推 info 期望 transaction/news/comparison) | 1. BRAIN prompt 加\"query 含价格/股价 必推 transaction\" 强规则 2. 加 Tavily API 作 backup 主源 (1 迭代可上) |\n| KB 实体覆盖 | 微信文章 (mp.weixin.qq.com) / 知乎 (需登录) / 雪球 (反爬) / 36kr (删文) | 1. miku-ai 集成 (公众号搜索 5/5 验证) 2. 雪球/36kr 专用 fetcher (v20.103) |\n\n## 工作方法论 (v20.102 落地)\n\n1. **任何\"用户反馈\"先 4 阶段拆解** (搜/读/整/出), 别直接动手\n2. **普适性 > 单用户特化** ( 只是入口, 问题是通用)\n3. **默认值错位检查** (mode=quick + answer=false 这种\"看起来对但实际错\"的隐藏 bug)\n4. **实测端到端一次** (curl /v1/search) > 读 1000 行代码定位\n5. **不破反爬, 走\"信源直连 + 整理层做厚\"路线** (vs 军备竞赛)\n\nFile v20.42.0:SKILL_EN.md\n\n---\nname: star-search-en\ndescription: \"Comprehensive web search + LLM-answer engine. Use when asked to search the web, find online information, research topics, get news, look up Chinese content, or check A股/finance/tech news. **v20.42 - LangChain + Dify + 5-min install**: LangChain Tool adapter, Dify plugin, install.sh, .env.example, 5-minute quick start. **v20.40 base**: STRAT 56.5%→74.1% + automatic fetch_content + end-to-end pipeline! star-search is a standard Model Context Protocol server (4 tools) callable by Claude Desktop / Cursor / Hermes. Public HTTP/SSE: https://search./mcp/sse . v20 features (v20.35-102): speed optimization 6s→0.2s + SSE streaming + multi-turn dialogue + 16 engines (HTTP/Playwright/RSS) + intelligent intent recognition (4 batch 108 query tests) + AI smart layer (super_brain + multi_search + entity_card + cross_verify + intent_strategy) + Cloudflare Bot protection + **v20.40 end-to-end pipeline** (4 stages: understand→search→integrate→output with full LLM participation). Goal: free Chinese alternative to Baidu search + LLM agent real-time fact layer (free Chinese version of Tavily/Perplexity).\"\nversion: 20.42.0\nauthor: Hermes Agent\nlicense: MIT\nmetadata:\n hermes:\n tags: [Search, Web, Bing, Sogou, Baidu, 360, Weixin, Toutiao, Zhihu, GitHub, China, Hybrid, HTTP, Playwright, Chinese, Cache, API, OpenAI, Cron, Incremental, CSDN, Cnblogs, Eastmoney, CLS, Sina, Sohu, Quality, Explain, Debug, RSS, Ithome, 36kr, Sspai, Oschina, Woshipm, Global, Public, HTTPS, Frontend, SmartRouting, Finance, MCP, JSON-RPC, SSE, LLM-Answer, Perplexity-Mode, Honest-LLM, Honest-Search, v20, Speed-Optimization, Streaming, Multi-Turn, Monitoring, Prometheus, Grafana, Structured-Output, Favorites, Academic-Search, Code-Search, English]\n related_skills: [arxiv, blogwatcher, session_search, commercial-opportunity-research, ai-api-relay-station, building-mcp-servers, native-mcp]\n references:\n - v16-v17-legacy-archive.md\n - v16-finance-mode-and-smart-routing.md\n - v16-public-deployment-and-daemon.md\n - v17-frontend-answer-card.md\n - v17-llm-answer-quality-strategy.md\n - mcp-server-zero-deps.md\n - site-bing-proxy-pattern.md\n - incremental-cache-pattern.md\n - llm-answer-honest-prompt.md\n---\n\n# Star Search v20.7.0 — Speed / Streaming / Multi-turn / Stable / Academic / Structured / Favorites / Monitoring — Integrated Chinese Search + LLM Answer\n\n**A single script to replace Baidu Search API + Answer + Monitoring. Free, multi-engine, high quality, serve subagents.**\n\n> This skill has evolved from v8.3 (Camofox) to v20.7.0 (HTTP+Playwright hybrid + intelligent routing + public deployment + LLM answer + SSE streaming + multi-turn + Prometheus monitoring). Complete v16-v17 chapters are archived in `references/v16-v17-legacy-archive.md`. GitHub: https://github.com/ @ commit da860bf (v20.7.0). Public: https://search. (HSTS + LE cert + nginx reverse proxy).\n\n---\n\n## 🔥 v20.7.0 Key Upgrades (P0-1 through P0-5 + P3-21/25/47/48)\n\n| Practice | Upgrade | Value | Performance Change |\n|---|---|---|---|\n| **35** | Speed optimization (search layer) | playwright skip + 4s top-level timeout + cache hit | **6s → 0.2-1s** |\n| **36** | SSE streaming output | `POST /v1/search/stream` + 5 events + first token < 1s | **First byte 11s → < 1s** |\n| **37** | Answer layer acceleration | `max_tokens=300` + `LLM_TIMEOUT=25s` | **7-8s complete** |\n| **38-39** | Multi-turn dialogue | `session_id` + `history` + localStorage | **6 turns context** |\n| **40** | Ultimate stability | killed `/tmp/watchdog.sh` (6/3 deployment leftover) | **NRestarts=0** |\n| **41-43** | Academic/code + structured + favorites | 4 engines + 4 formats + ⭐ button | **3 major features** |\n| **44-46** | Monitoring + Prometheus + Grafana | `/metrics` + 8 alerts + 11 panel dashboard | **Public HTTPS** |\n| **47** | Sourcegraph 4 bug fix + Semantic Scholar | text=True/returncode/POST→GET/SSE parser + x-api-key header | **1/4 engines recovered** |\n| **48** | Claude Desktop MCP integration | stdio + SSE dual transport, 4 tools tested 301ms | **Public tutorial** |\n\n---\n\n## 🏗️ Architecture (v20.7)\n\n```\n[Browser] → https://search.:443\n ↓ (nginx + LE cert)\n[/var/www/star-search/index.html] ← 49KB frontend (streaming/favorites/history/format switch)\n ↓ (location /v1/ / /mcp/ / /v1/search/stream SSE)\n[FastAPI :] ← api_server.py (systemd user)\n ├─ 16 engines (9 HTTP enabled + 4 PW skipped + 3 cache)\n ├─ answer.py (GLM-4-Flash summarization, honest-first)\n ├─ metrics.py (Prometheus metrics, 14 indicators)\n ├─ academic_code.py (4 engines)\n ↓\n[LLM API: https://api./v1] ← GLM-4-Flash (permanently free)\n[Prometheus + Grafana + node-exporter] ← 9090/3000/9100 (public HTTPS)\n[monitor.service] ← Monitoring alerts (user systemd)\n```\n\n---\n\n## 6 Major Capability Modules (v20.7)\n\n### 1. Speed & Streaming (P0-1, v20.35-37)\n\n- **Search layer 0.2-1s**: playwright 4 engines skip + 4s top-level timeout + cache hit 0ms\n- **Answer layer 7-8s**: `max_tokens=300` + `LLM_TIMEOUT=25s` + 30min cache\n- **SSE streaming**: `POST /v1/search/stream` returns 5 events (`search_start` / `search_done` / `answer_chunk×N` / `answer_done` / `done`)\n- **First token < 1s**: frontend fetch + ReadableStream SSE parsing, character-by-character display\n\n### 2. Multi-turn Dialogue (v20.38-39)\n\n- **API fields**: `session_id` + `history: [{q, a}, ...]`\n- **Backend**: `generate_answer(history)` splices into prompt (`=== Previous conversation ===\\nUser: ...\\nAssistant: ...\\n---`)\n- **Frontend**: localStorage stores `chat:{session_id}:history` (last 20 turns) + left...","readmeExcerpt":"Skill: star-search Owner: muchenhengxin Summary: Use when asked to search the web, find online information, research topics, get news, look up Chinese content, or check finance / tech news. **v20.42 - LangChain + Dify + 5 分钟安装体验**: 新增 LangChain Tool 适配器 (integrations/langchain/star_search_tool.py) + Dify plugin (integrations/dify/manifest.yaml), 一键安装脚本 install.sh, .env.example 模板, 5 分钟快速开始. **v20.41 基础**: English cov","codeSnippets":[],"executableExamples":[{"language":"python","snippet":"from concurrent.futures import ThreadPoolExecutor\nimport super_brain, intent_strategy\ndef test(q): bi = super_brain.analyze_query(q[0], use_cache=False); s = intent_strategy.strategy_for_query(q[0], bi); ...\nwith ThreadPoolExecutor(max_workers=8) as ex: results = list(ex.map(test, ALL))"},{"language":"bash","snippet":"scp file.py vm-ubuntu:/tmp/file_new.py\n# 推荐: 把 server 文件属主改成 ubuntu 用户 (sudo chown -R ubuntu:ubuntu ),\n# 这样 scp 直接覆盖即可, 不需要 sudo 步骤"},{"language":"bash","snippet":"python3 -c \"import intent_strategy\" # 验证语法\ngrep -nE \"intent == '\" intent_strategy.py # 看每个分支只有一处"},{"language":"bash","snippet":"python3 search.py \"Python 教程\" --engine bing_cn --mode dev --fetch 3\n# 自动抓前 3 条正文 + 4.1 秒 + JSON/table 标注成功失败"},{"language":"text","snippet":"POST /v1/search {\"query\":\"华为\",\"top\":3}\n→ count=3 (bing_cn 主导)\n→ answer=false 默认 → LLM 不调 → 用户看到原始链接\n→ cross_verify_error: \"name 'date' is not defined\" → 整套崩\n→ brain_info: None → entity_card: None"},{"language":"json","snippet":"{\n \"count\": 3,\n \"elapsed_ms\": 1,\n \"brain_info\": {\"entity\": \"华为\", \"intent\": \"info\"},\n \"entity_card\": {\"name\": \"华为\", \"official_url\": \"https://www.huawei.com/\"},\n \"fetch_stats\": {\"requested\": 3, \"success\": 2},\n \"cross_verify\": {\"consensus_score\": 0, \"source_count\": 3},\n \"answer\": {\n \"answer\": \"1. 华为是一家全球领先的通信和信息技术解决方案提供商...\\n来源域名: huawei.com, consumer.huawei.com, vmall.com\",\n \"sources\": [\"huawei.com\", \"consumer.huawei.com\", \"vmall.com\"],\n \"model\": \"glm-4-flash\",\n \"tokens\": 949,\n \"elapsed_ms\": 7050\n }\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: star-search\ndescription: \"Use when asked to search the web, find online information, research topics, get news, look up Chinese content, or check finance / tech news. **v20.42 - LangChain + Dify + 5 分钟安装体验**: 新增 LangChain Tool 适配器 (`integrations/langchain/star_search_tool.py`) + Dify plugin (`integrations/dify/manifest.yaml`), 一键安装脚本 `install.sh`, `.env.example` 模板, 5 分钟快速开始. **v20.41 基础**: English coverage + open scholarly sources (pure-English queries auto-route to Bing HTTP backend; OpenAlex + CrossRef merge). 16 plus engines, intent understanding, observable per-call metrics. The public service exposes standard MCP (4 tools) plus JSON-RPC and SSE. v20 series highlights: sub-second SSE streaming, multi-turn dialog, 4 output formats, Prometheus monitoring, semantic search, AI orchestration layer (intent classification, entity card, cross-source verification), bot-protection workarounds, and a 4-stage end-to-end pipeline that defaults to LLM answer + auto-fetched snippets. 16 plus engines, intent understanding, and observable per-call metrics.\"\nversion: 20.42.0\nauthor: Hermes Agent\nlicense: MIT\nmetadata:\n hermes:\n tags: [Search, Web, Bing, Sogou, Baidu, 360, Weixin, Toutiao, Zhihu, GitHub, China, Hybrid, HTTP, Playwright, Chinese, Cache, API, OpenAI, Cron, Incremental, CSDN, Cnblogs, Eastmoney, CLS, Sina, Sohu, Quality, Explain, Debug, RSS, Ithome, 36kr, Sspai, Oschina, Woshipm, Global, Public, HTTPS, Frontend, SmartRouting, Finance, MCP, JSON-RPC, SSE, LLM-Answer, Perplexity-Mode, Honest-LLM, Honest-Search, v20, Speed-Optimization, Streaming, Multi-Turn, Monitoring, Prometheus, Grafana, Structured-Output, Favorites, Academic-Search, Code-Search, Intent-Understanding, Cloudflare-Bot-Protection, KB-Card]\n related_skills: [arxiv, blogwatcher, session_search, commercial-opportunity-research, ai-api-relay-station, building-mcp-servers, native-mcp]\n references:\n - v16-v17-legacy-archive.md\n - v16-finance-mode-and-smart-routing.md\n - v16-public-deployment-and-daemon.md\n - v17-frontend-answer-card.md\n - v17-llm-answer-quality-strategy.md\n - mcp-server-zero-deps.md\n - site-bing-proxy-pattern.md\n - incremental-cache-pattern.md\n - llm-answer-honest-prompt.md\n - ai-native-search-transformation.md\n - intent-understanding-test-bench.md\n - intent-detection-rule-priority.md\n - cloudflare-bot-protection.md\n - source-credibility-4d-formula.md\n - v20-40-intent-strat-rule-pitfalls.md\n---\n\n# Star Search v20.33 — 速度/流式/多轮/稳定/学术/结构化/收藏/监控/AI 智能层/Cloudflare 应对 一体化中文搜索\n\n> 本 skill 已从 v8.3 演进到 v20.33。v16-v17 归档在 references/v16-v17-legacy-archive.md。GitHub: . 公网: (HSTS+LE证书+nginx 反代)。\n\n## ⚠️ 关键必读 (v20.33 新增)\n\n### Cloudflare Bot 保护 (v20.87)\n\n**症状**: skill/MCP/API 直接调 → 403/503 弹人机验证\n**根因**: Cloudflare 把 Python/curl User-Agent 当 bot (无 JS 验证 + 无 Cookie + 来源 IP 是腾讯云)\n**关键认识**: **Web 浏览器访问不受影响**, 只有 skill/API/CLI 受影响\n\n**3 选 1 修复方案**:\n"},{"path":"integrations/dify/README.md","content":"# star-search LangChain & Dify 集成\n\n## LangChain 安装\n\n```bash\npip install langchain pydantic\n```\n\n## 使用\n\n```python\nfrom langchain.agents import load_tools\nfrom star_search_langchain import StarSearchTool\n\ntool = StarSearchTool()\nresult = tool.run(\"华为 mate 70 价格\", mode=\"quick\", top=3)\n```\n\n## Dify 集成\n\n把 `dify_plugin/` 整个目录上传到 Dify Marketplace。\n\n## 配置\n\n环境变量：\n- `STAR_SEARCH_BASE`：默认 `https://search.token-star.cn/v1`\n- 自部署时改为你自己的 API endpoint。"},{"path":"README.md","content":"# Star Search v16.0 — 16 引擎直搜 + 定时增量 + OpenAI API + 智能缓存 + 智能去重 + 质量标识\n\n> **免费中文搜索。16 引擎混动：搜狗HTTP / Bing CN / GitHub Issues / 头条 / 知乎 / 微信公众号（site:bing 直搜免反爬）/ 搜狗PW / 百度 / 360 / 微信PW / Bing国际 + 7 个 site:bing 新引擎（v15.1 csdn/cnblogs/eastmoney/cls/tencent_cloud/sina_finance/sohu）。HTTP 引擎 <1秒直出，v13 智能缓存，v14 OpenAI API + 增量追加，v15 定时 cron 客户端，v16 修复 sogou KeyError + 🌟🌟🌟 质量标识 + --explain 评分透明，全面超越百度千帆 API。**\n\n![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue) ![License MIT](https://img.shields.io/badge/license-MIT-green) ![Version 16.0](https://img.shields.io/badge/version-16.0-orange) ![Engines 16](https://img.shields.io/badge/engines-16-brightgreen)\n\n---\n\n## v16.0 核心升级（2026-06-02）\n\n| 升级 | 价值 |\n|------|------|\n| **修复 sogou KeyError** (v16) | 反复刷 stderr 的\"搜狗挂了\"假象没了，6/6 mode smoke test 0 错误 |\n| **🌟🌟🌟 质量标识** (v16) | `cross_verified >= 3` 标 🌟🌟🌟，可视化\"这条结果有多可信\" |\n| **--explain 评分透明** (v16) | 调试模式显示每条结果的 `cross_verified=+40 · domain_auth=+8` 评分构成 |\n| **16 引擎** | v15.1 加 7 个 site:bing 代理 (csdn/cnblogs/eastmoney/cls/tencent_cloud/sina_finance/sohu) |\n| **定时增量客户端** (v15) | `cron_refresh.py` 异步并发拉多 query，JSONL 输出，可配 cron |\n| **OpenAI-compatible API** (v14) | FastAPI 5 endpoints，subagent/脚本可直接调用 |\n| **增量追加** (v14) | `force_refresh` 绕过缓存 + 与历史合并，节省 78% 时间 |\n| **智能缓存 v13** | 分桶TTL（news 5min / dev 1h）+ query 归一化 + 桶复用（num 5/8/10 共享）+ 命中率统计 |\n| **GitHub Issues 引擎** (v12.1) | 开发者向查询直接拿到 issue 级讨论（带 [bug] / [feature-request] 标签），自动过滤 bot 批量 issue |\n| **智能去重** (v12.2) | 主题词 key + Jaccard 双策略合并同事件多转载 |\n| **跨源聚合** (v12.2) | ⭐ 标记可视化跨源验证，cluster_size 字段记录合并条数 |\n| **dev 模式** (v12.1) | 搜狗HTTP + 百度 + GitHub Issues + Bing CN，开发者首选 |\n| **搜狗 HTTP** (v11.2) | 搜狗无需浏览器，0.5-1秒直出 |\n\n---\n\n## 为什么选 Star Search？\n\n百度千帆 API 按量付费 + 来源偏自媒体。Star Search 通过多引擎混合 + 智能去重实现**免费、高质量、可验证**的中文搜索，三类查询全部超越百度 API。\n\n| 维度 | Star Search v12.2 | 百度千帆 API | 对比 |\n|:----|:----------------|:-----------|:----:|\n| 引擎数 | **7** (HTTP + Playwright) | 1 (百度) | ✅ **远超** |\n| 官方来源 | **强** (gov.cn / pbc.gov.cn / 新华网) | 弱 (百家号/自媒体) | ✅ **完胜** |\n| 开发者向 | **GitHub Issues 引擎** | 无 | ✅ **独有** |\n| 跨源验证 | ⭐ 标记 + cluster_size | 无 | ✅ **独有** |\n| 速度 | quick 0.5-1s / deep 4-6s | 1-2s | ⚖️ 持平 |\n| 摘要 | 中等 (HTML 解析) | 长 (百字级) | ⚖️ 略弱 |\n| 费用 | **免费** | 按量付费 | ✅ **完全替代** |\n\n**实测对比**（3 类查询 × 2 引擎）：\n\n| 查询类型 | baidu-search | star-search v12.2 | 赢家 |\n|---------|-------------|------------------|------|\n| 政策类（央行 2026 货币政策）| 8条 0官方源，有标题党 | 8条 **4条官方源** | **Star 压倒** |\n| 开发者向（Python asyncio 2026）| 8条 CSDN/聚合站 | 8条 + **2条 GitHub Issues** | **Star 完胜** |\n| 新闻类（DeepSeek V4 Flash 免费）| 7条自媒体为主 | 8条 6条带 ⭐（最新5/28）| **Star 时效优** |\n\n详细对比：`references/vs-baidu-search-comparison.md`\n\n---\n\n## 快速开始\n\n```bash\n# 默认查询（中文→deep 模式，5引擎并发）\npython3 scripts/search.py \"存储芯片超级周期\"\n\n# 开发者向（搜狗HTTP + 百度 + GitHub Issues + Bing CN）\npython3 scripts/search.py \"FastAPI 异步 中间件\" --mode dev\n\n# 极速查询（仅搜狗HTTP，0.5-1秒）\npython3 scripts/search.py \"华为\" --mode quick\n\n# 单引擎（Bing CN 返回真实直链）\npython3 scripts/search.py \"英伟达\" --engine bing_cn\n\n# 时效过滤\npython3 scripts/search.py \""},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn74wh1ba6kj8c6gg1ejv8q95982szyc\",\n \"slug\": \"star-search\",\n \"version\": \"20.42.1\",\n \"publishedAt\": 1789002022290\n}"},{"path":"references/camofox-api.md","content":"# Camofox API Quick Reference（Star Search v8.3）\n\n## 核心端点\n\n```bash\n# Health check\ncurl http://localhost:9377/health\n# ✓ {\"ok\":true,\"browserConnected\":true,\"engine\":\"camoufox\"}\n# ✓ {\"ok\":true,\"browserConnected\":false} — 也正常工作\n\n# 创建tab并导航\ncurl -s -X POST http://localhost:9377/tabs \\\n -H \"Content-Type: application/json\" \\\n -d '{\"userId\":\"search\",\"sessionKey\":\"RANDOM\",\"url\":\"https://www.sogou.com/web?query=关键词&ie=utf8\"}'\n\n# 获取页面快照（snapshot）\ncurl -s \"http://localhost:9377/tabs/$TAB_ID/snapshot?userId=search\"\n\n# 导航到新URL\ncurl -s -X POST \"http://localhost:9377/tabs/$TAB_ID/navigate?userId=search\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"userId\":\"search\",\"url\":\"https://www.example.com\"}'\n\n# 关闭tab\ncurl -s -X DELETE \"http://localhost:9377/tabs/$TAB_ID?userId=search\"\n```\n\n## search.py 已封装所有端点\n\n**不建议直接调用API。** `search.py` 已经封装了完整的搜索流程：\n\n```python\n# create_tab → wait_for_snapshot → extract → close_tab\n# 三引擎并行 + 去重 + URL解析 + JSON output\n```\n\n## 已知问题\n\n| 问题 | 说明 |\n|------|------|\n| `about:blank` 被拦截 | Camofox不支持`about:`协议，用`https://www.sogou.com/robots.txt`替代 |\n| navigate响应url是真实URL | 导航到搜狗短链后，响应`url`字段是JS重定向后的真实URL |\n| snapshot中的heading行 | 搜狗结果`level=3`，百度结果也在`level=3` |\n| 360短链无法解析 | `so.com/link?m=xxx` navigate后响应仍是短链 |"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Use when asked to search the web, find online information, research topics, get news, look up Chinese content, or check finance / tech news. **v20.42 - LangChain + Dify + 5 分钟安装体验**: 新增 LangChain Tool 适配器 (`integrations/langchain/star_search_tool.py`) + Dify plugin (`integrations/dify/manifest.yaml`), 一键安装脚本 `install.sh`, `.env.example` 模板, 5 分钟快速开始. **v20.41 基础**: English coverage + open scholarly sources (pure-English queries auto-route to Bing HTTP backend; OpenAlex + CrossRef merge). 16 plus engines, intent understanding, observable per-call metrics. The public service exposes standard MCP (4 tools) plus JSON-RPC and SSE. v20 series highlights: sub-second SSE streaming, multi-turn dialog, 4 output formats, Prometheus monitoring, semantic search, AI orchestration layer (intent classification, entity card, cross-source verification), bot-protection workarounds, and a 4-stage end-to-end pipeline that defaults to LLM answer + auto-fetched snippets. 16 plus engines, intent understanding, and observable per-call metrics. Skill: star-search Owner: muchenhengxin Summary: Use when asked to search the web, find online information, research topics, get news, look up Chinese content, or check finance / tech news. **v20.42 - LangChain + Dify + 5 分钟安装体验**: 新增 LangChain Tool 适配器 (integrations/langchain/star_search_tool.py) + Dify plugin (integrations/dify/manifest.yaml), 一键安装脚本 install.sh, .env.example 模板, 5 分钟快速开始. **v20.41 基础**: English cov","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1526,"uniquenessScore":47,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T14:30:46.033Z","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-09T14:30:46.033Z","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-10T04:19:18.792Z","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"}]}}}