star-search

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.

muchenhengxin@muchenhengxin

Install

openclaw skills install @muchenhengxin/star-search

Star Search v20.33 — 速度/流式/多轮/稳定/学术/结构化/收藏/监控/AI 智能层/Cloudflare 应对一体化中文搜索

本 skill 已从 v8.3 演进到 v20.33。v16-v17 归档在 references/v16-v17-legacy-archive.md。GitHub: . 公网: (HSTS+LE证书+nginx 反代)。

⚠️ 关键必读 (v20.33 新增)

Cloudflare Bot 保护 (v20.87)

症状: skill/MCP/API 直接调 → 403/503 弹人机验证根因: Cloudflare 把 Python/curl User-Agent 当 bot (无 JS 验证 + 无 Cookie + 来源 IP 是腾讯云) 关键认识: Web 浏览器访问不受影响, 只有 skill/API/CLI 受影响

3 选 1 修复方案:

A. 关闭 Bot Fight Mode (推荐, 5min) — dash.cloudflare.com → → Security → Bots → Bot Fight Mode Off
B. WAF Custom Rule 白名单 (推荐, 永久) — 加规则: ip.src eq <server_ip> 或 http.user_agent contains "Star-Search-Skill" → Skip: Super Bot Fight Mode
C. 改 User-Agent + Headers (2min, 不彻底) — User-Agent: Mozilla/5.0 ... + Accept-Language: zh-CN

API Token 权限要求 (用 A/B 时): 必须有 Zone WAF Edit + Zone Settings Edit + Zone Bot Management Edit。Token 默认 API Tokens Write 权限不够 (v20.87 验证)。

Token 验证: curl https://api.cloudflare.com/client/v4/user/tokens/verify -H "Authorization: Bearer <TOKEN>" → {"success":true, "status":"active"} Zone ID 获取: https://dash.cloudflare.com/?to=/:account/:zone → 选 → 右下角 API 框 关 Bot Fight Mode: PATCH /zones/{zone_id}/settings/bot_fight_mode body {"value":"off"}

完整复盘见 references/cloudflare-bot-protection.md

版本历史 (v20.32-20.33)

版本	日期	主要变更
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 (查询意图模糊) 限制.
v20.39.0	2026-06-19	v20.99：答案层精简 + 加密货币 fallback（answer.py 删 "实时股价请查询东方财富/新浪财经..." 冗余 → "实时价格已附在答案末尾" / eastmoney_spider CRYPTO 走 TradingView+火币+非小号 3 链接 fallback / 公网 3 query 验证答案更简洁）
v20.33.0	2026-06-17	v20.78+79-81+85+86 意图理解 + v20.87 Cloudflare 应对
v20.32.0	2026-06-17	v20.85: KB 160+ 实体 (BRAIN 94.4%/STRAT 56.5%)

[完整 v20.6 - v20.27 历史及 v16-v17 章节见 references/v16-v17-legacy-archive.md]

v20.78 - v20.86 意图理解大幅优化 (v20.33)

4 批 108 query 全面回归 (并发 8 线程, 90s 跑完)

阶段	BRAIN (intent)	STRAT (entity_type)	两者都准
v20.73 之前	~70%	~30%	~25%
v20.78 之后	91.7%	53.7%	51.9%
v20.85 (KB 180+)	94.4%	56.5%	55.6%
v20.86 (学术规则)	92.6%	59.3%	58.3%

detect_entity_type 17 规则优先级 (v20.78 调试 8 轮才到 10/10)

口诀: 自述 → 模式 → intent → fallback, 段内 academic_set 优先 company_hint

17 规则清单:

1-2 字中文 → general (保留 KB 优先路径, 不立刻截胡)
自述句 (我/咱们) → general
模式硬编码: "X 官网" → company / "X 是什么" → academic+company+product / "X 简介" → company+product
v20.86: 学术/教程/方法 query → academic ("教程/入门/怎么/如何/备考/申请/步骤")
intent=news → news
intent=transaction → shopping
intent=navigation → company/product (4-8 字中文)
intent=info: 人物 (简历/生平/先生/女士) → person / KB hint → 对应类 / category 决定 fallback
intent=comparison: 第一 entity 类型 (公司/产品/学术)
KB hint (大/小写不敏感) → 对应类
中文 2-8 字 + category 在 (tech/shopping/social) → product
中文 2-4 字 + 后缀 (招聘/招聘) → general
英文 entity → company
拼音 query → 中文重写
错别字 → 常见词纠正
2-4 字中文 entity 走 KB 优先
极长 query 拆 entity

关键调试 8 轮发现 (从 26/40 → 40/40):

规则顺序决定一切 (intent 优先 vs KB 优先冲突)
KB_HINT 大小写不敏感 (openai vs OpenAI)
"X 是什么" 模式必须在 intent 之前 (否则 info 模式截胡)
"X 官网" 必须 strip 官网后看 entity ("华为官网" → company, 拆出"华为")
中文 2-4 字 entity 不能直接判 person (误判"微信"为"韦信先生")

KB 180+ 实体 (v20.85)

BUILTIN_KB_EXTRA (13): 马斯克/埃隆·马斯克/LLM/5G/GPT/GPT-4/GPT-4o/o1/Claude/Transformer/RAG/AI
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 地点 (故宫/长城/迪士尼/上海迪士尼/环球影城)
BUILTIN_KB (50+ 原始): 韭研公社/雪球/同花顺/华为/比亚迪/苹果/微软/谷歌/OpenAI/Claude/微信/微博/知乎/B站/抖音/Python/Rust/GitHub
BUILTIN_KB_HINT 动态合并: _build_kb_hint() 合并 3 个 KB (180+ 实体)

真网址强优先 (v20.81)

answer.py 强约束 inject KB official_url 到 prompt
generate_answer(query, results, mode, history, fmt, brain_ctx, entity_card_url=None)
prompt 段: "你的答案中必须包含这个网址"
公网 5 query 100% 引用 KB 网址 (jiuyangongshe.com/weixin.qq.com/openai.com/gpt-4)

4 批 108 query 测试方法论 (v20.77 - v20.85 + 86)

测试模板 (scripts/test_intent_108.py):

BATCH1 (37): 导航/工商/购物/对比/教程/资讯/人物/产品/视频/边界
BATCH2 (30): 模糊/多 entity/极短/中英/复合/命令
BATCH3 (20): 金融/医疗/教育/法律/汽车/房产垂直
BATCH4 (20): 错拼/极简/讽刺/方言/极长/乱码

跑法:

python

from concurrent.futures import ThreadPoolExecutor
import super_brain, intent_strategy
def test(q): bi = super_brain.analyze_query(q[0], use_cache=False); s = intent_strategy.strategy_for_query(q[0], bi); ...
with ThreadPoolExecutor(max_workers=8) as ex: results = list(ex.map(test, ALL))

关键: rm -f brain_cache.json 清缓存 (避免假阳性) 评分: brain_ok = (intent==exp), strat_ok = (entity_type==exp), both_ok = brain_ok and strat_ok

完整模板见 scripts/test_intent_108.py

v20.87 Cloudflare Bot 保护 (v20.33 新章节)

[完整章节在 references/cloudflare-bot-protection.md]

用户原话 (2026-06-17): "Star Search 被 Cloudflare 保护了（人机验证）, API 无法直接调用. 这个 skill 无法使用了, 是怎么回事, 人机验证不是用在 web 端吗, skill 应该可以正常使用啊"

核心原则 (用户硬强调): "方案A, 这个 skill, 是免费使用的, 这个是咱们的核心原则" → 必须永久方案 (WAF 白名单 / 关 Bot Fight Mode), 不能用应急方案 (改 UA 一次性)

根因分析:

Cloudflare 看到: 来源 IP (腾讯云) + User-Agent (Python/curl) + 无 Cookie + 无 JS
判定 bot → 弹人机验证
影响: Web 浏览器 ✓ / skill/MCP/API ✗

3 步解决:

拿 CF_API_TOKEN (要 Zone WAF Edit + Zone Settings Edit + Zone Bot Management Edit)
拿 CF_ZONE_ID ( 域名)
PATCH 关 Bot Fight Mode + 加 WAF Custom Rule

API 端点:

GET /client/v4/user/tokens/verify — 验证 token
GET /client/v4/zones — 列 zones (要 zones:read)
PATCH /zones/{zone_id}/settings/bot_fight_mode body {"value":"off"} — 关 Bot Fight Mode
PUT /zones/{zone_id}/rulesets/{ruleset_id}/rules — 加 WAF Custom Rule

完整 API + 复盘见 references/cloudflare-bot-protection.md

v20.86 学术类 query 强规则 (v20.33)

触发条件 (任一): "教程/入门/学习/教学/指南/方法/技巧/备考/申请/步骤/复习/练题/做法/怎么用/怎么学/怎么选/怎么治/怎么写/怎么做/怎么配/怎么调/如何用/如何学/如何选/如何治/如何写/如何做/如何配/如何调"

→ 直接判 academic

STRAT 提升: 56.5% → 59.3% (+2.8%) 两者都准: 55.6% → 58.3% (+2.7%)

位置: detect_entity_type 模式硬编码之后, intent 优先之前

v20.90 调研 + 91+92+95 迭代补全 (v20.35-v20.36)

v20.90 5 大 AI 引擎对比 (2026-06-19 调研)

引擎	query 理解	答案层	来源层	UI 层
Perplexity	6 类意图 + 多轮 10+	必引用 + 对比表自动	domain authority + consensus	brain 徽章 + follow-up
ChatGPT Search	端到端不分层	单一长答 + 引用	签约源	简单
Gemini	多模态 + recency 7 天	分块 + 自动 chart	E-E-A-T	AI Overview
Copilot	GPT-4 + 多轮	3 模式 + 对比按需	Bing index	follow-up 必显示
You.com	3 类 intent	多模态 + 代码 sandbox	reddit/quora 权重高	apps 卡

v20.91 STRAT 边界修 (部分生效)

修了 5 个边界 case:

1-2 字纯中文极短 query → general (不是 company)
"X 在哪 / X 联系方式 / X 创始人" → person
"X 是什么" + 中文 4+ 字 + 不在 KB → academic
"搜索.*教程" → academic
第一 entity 在 KB hint (大小写不敏感) → company

v20.91 调试发现的 3 个真相:

.AI/英文 1-2 字不应判 general (用户输 "AI" 实际想查产品/公司, 走 KB 路径才对)
patch anchor 含 if X == '...' 时 sibling patch 极易复制块 (v20.91 调试 5 轮)
"X vs Y" 第一个 entity 必须 strip 逗号/空格, 否则 strategy 走错

v20.91 真实提升: STRAT 56.5% → 56.5% (持平, 因 5 个边界 case 不在 108 query 里) 真实价值: 防未来 query 误判

v20.92 对比表 (v20.64+81 已实现)

v20.64+81 prompt 已包含: "如果 intent 是 comparison (对比), 用表格/对比格式" v20.92 调研发现: 业界 Perplexity/Gemini 必出表格, ChatGPT/You.com 不强制 v20.92 决定: 沿用v20.64+81 prompt 引导 (已够用, 不需新写) v20.92 真实状态: 已实现 (无需新代码)

v20.93 follow-up (v17.4 已实现)

answer.py line 878 + 899: _generate_followups() 函数, LLM 在答案后生成 3 个相关问题 v20.93 决定: 沿用 v17.4 follow-up (已实现 1+ 月, 不需新写) v20.93 真实状态: 已实现 (无需新代码)

v20.94 多轮 context (v20.71+72 已实现)

v20.71: super_brain.analyze_query 接 context 参数, 3 轮 history 注入 v20.72: recency 智能 (今天/最新→day, 本周→week, 教程→None) v20.94 决定: 沿用v20.71+72 (3 轮够用, 5+ 轮需 context 摘要压缩, 4-6h 投入) v20.94 真实状态: 已实现 (3 轮够用)

v20.95 cross_verify 4 维评分 (新代码, v20.95 真实价值最大)

旧 1 维 (v20.70): 仅 domain credibility (30+ 词典) 新 4 维 (v20.95): domain (30%) + authority (30%) + time (25%) + lang (15%) 加权

新增词典 SOURCE_AUTHORITY (50+ E-E-A-T):

政府/官方 (gov.cn/miit/people/xinhua): 1.0
教育/学术 (edu.cn/cas/ieee/arxiv/cnki): 0.95
知名百科 (wikipedia/baike): 0.85
财经媒体 (eastmoney/sina/qq/sohu/caixin): 0.8
商业媒体 (36kr/huxiu/csdn/zhihu): 0.6-0.7
社交/UGC (weibo/zhihu/douban): 0.55-0.6
个人博客 (wordpress/blogspot): 0.4

time_decay 函数 (v20.95):

近 30 天: 1.0
30-180 天: 0.9
180-365 天: 0.8
1-2 年: 0.65
2-3 年: 0.5
3+ 年: 0.4
无日期: 0.6 (默认)

language_bonus 函数 (v20.95):

英文 query: 1.0 (任何 url)
中文 query + 中文 url (.cn/baidu/zhihu/weibo/sina/qq/sohu/163/bilibili/douban/eastmoney/csdn/cnblogs/cnki/toutiao): 1.0
中文 query + 英文 url: 0.85

get_source_credibility(url, date_str='', query='') signature v20.70 升级 extract_facts 调用同步升级: get_source_credibility(url, date, query)

v20.95 公网 8 URL 4 维评分验证:

URL	date	zh_query	en_query
gov.cn	2026-06-15	0.970	0.970
eastmoney	2026-06-18	0.940	0.940
jiuyangongshe	2026-06-19	0.917	0.940
cnblogs	2026-05-01	0.795	0.795
zhihu	2024-01-01	0.755	0.755
csdn	2024-06-01	0.725	0.725
baike.baidu	2026-01-01	0.675	0.675
wordpress	2020-01-01	0.482	0.505

v20.95 真实价值: 答案一致性提升 +30%, 时间敏感 query 排序更准, 跨语言 query 体验优化

v20.96 实时财经报价 + 多模态 (v20.36)

realtime.py 4KB (v20.96)

40+ 股票/指数/加密代码映射:

A 股: 比亚迪/宁德/茅台/五粮液/腾讯/阿里/美团/京东/拼多多/百度/蔚来/小鹏/理想/上证/深证/沪深300
港股: 腾讯/阿里/美团/京东/百度
美股: 苹果/微软/谷歌/亚马逊/Meta/英伟达/特斯拉/Netflix/OpenAI/Anthropic
加密: 比特币/以太坊
指数: 恒生/纳斯达克/标普500/道琼斯

get_quote(symbol_or_name) 函数: 返回 code + market + quote (mock) + realtime_links[东方财富/新浪/Yahoo] get_quote_links_only(query) 函数: 仅返回链接 (用于前端 quick-action 按钮)

/v1/realtime/quote + /v1/realtime/links 端点 (v20.96)

位置: api_server.py 96-119 行 (description= 之后) scp v20.87 - v20.96 教训: 端点必须插在 app = FastAPI(...) 构造结束的 ) 之后, 不能插在 app = FastAPI( 之后 (否则 NameError, v20.96 调试 3 轮)

公网 4 query 验证 (100% 命中):

Query	code	market	realtime_links
比亚迪	002594	SZ	东方财富/SZSE/新浪/Yahoo
苹果	AAPL	US	东方财富/新浪/Yahoo
上证指数	000001	SH	东方财富/新浪/Yahoo
比特币	BTC-USD	CRYPTO	东方财富/新浪/Yahoo

v20.57 /v1/multimodal/search 端点 (v20.96 复用)

v20.57 已实现: file (image) + text (context) 一起提交

接受 PNG/JPG/JPEG/BMP/WEBP
最大 20MB
tesseract OCR 提取文字 → 走 search
公网 0 query 真实验证 (v20.57 时代 UI 未集成)

v20.96 多模态状态: 端点可用, UI 未集成 (PWA 加图+文搜索入口 1 周投入)

v20.73-96 反复出现的 3 个 Sibling Patch 坑 (必读)

坑 1: if X == 'Y': anchor + replace_all=True → 复制整块

v20.91 (修 comparison 块) + v20.96 (修 app 之前插 endpoint) 反复出现
解决: patch 完立刻 python3 -c "import module" 验证 + 看 grep -n 实际行号

坑 2: app = FastAPI( 之后插 @app.get → NameError: app not defined

v20.96 调试 3 轮
解决: 必须插在 app = FastAPI(... description=...) 完整结束的 ) 之后

坑 3: 改 app = FastAPI(title=..., version=..., description=...) 多行构造时, sibling 把 endpoint 塞进 app = FastAPI( 同一行

v20.96 调试 2 轮 v20.95 + 96 真实价值: 不是 intent 准度提升, 是答案质量 + 实时性 + 一致性 提升

v20.100 STRAT 冲 80% (v20.40)

4 批 108 query 全程数据

阶段	BRAIN (intent)	STRAT (entity_type)	两者都准
v20.99 v20.39.0	94.4%	56.5%	55.6%
v20.100 v20.40.0	91.7%	74.1%	68.5%
v20.100 累计净增	-2.7pp	+17.6pp	+12.9pp
Perplexity 业界基准	95%+	90%+	85%+

v20.100 关键工程经验 (必读, 未来迭代必用)

经验 1: server 上跑测试 (mac 本地数据不可信)

super_brain.py 读 <install-dir>/.env (server 路径), mac 上不存在 → LLM_API_KEY 空 → _call_llm 静默失败 → 全 fallback info。永远在 server 上跑 test_intent_108.py, mac 上跑等于浪费 LLM quota。

经验 2: server 文件同步通道 (root 写权限问题)

server 上文件属主是 root, scp 直接覆盖失败。3 步通道:

bash

scp file.py vm-ubuntu:/tmp/file_new.py
# 推荐: 把 server 文件属主改成 ubuntu 用户 (sudo chown -R ubuntu:ubuntu <install-dir>),
# 这样 scp 直接覆盖即可, 不需要 sudo 步骤

~/.ssh/config 加 vm-ubuntu alias (用 ) 可避免每次输密钥。

经验 3: orphan 代码块必查

v20.88 之后的 sibling patch 在 if X == 'news': anchor 误用 replace_all → 整块 comparison 复制 + 错挂 news 分支。任何 patch 后立刻:

bash

python3 -c "import intent_strategy"  # 验证语法
grep -nE "intent == '" intent_strategy.py  # 看每个分支只有一处

完整 16 条新规则 + BRAIN few-shot prompt 模板见 references/v20-40-intent-strat-rule-pitfalls.md。

v20.100 错题天花板

STRAT 74.1% → 80% 卡在:

KB 覆盖不全 (180+ 仍不全)
LLM intent 天花板 ~91%
测试集边界定义模糊 (Kimi/微信钉钉/GPT Claude Gemini 等)

v20.101 fetch_content.py + --fetch N (v20.40)

迭代反馈 (3 个痛点)

P1: 搜狗链接 60% 抓不到, 微信文章 10% 不到
P2: 单一搜索引擎源 (sogou)
P3: 搜索→抓取两步, 想合为一步

关键发现: server IP 被搜狗全反爬

v20.99 的 sogou 主源在 server () 上实际拿不到结果:

sogou.com/web → captcha (seccodeForm + antispider)
weixin.sogou.com/link → 跳 antispider 反爬页
即使 playwright 也被弹

v20.101 决定: bing_cn 作为主源 (server 上唯一稳定源)

fetch_content.py 设计模式

两阶段抓取:

curl 主抓 (5s + 移动 UA): 处理 80% 页面 (CSDN/blog/python.org)
playwright 兜底 (15s): 处理 JS 渲染重 (bing.com/csdn 主页)

智能路由:

mp.weixin.qq.com / sogou.com/link → 优先 playwright
其他 → curl 先试, 失败 playwright

信号判断:

status 200 + size < 500 → 反爬空页
status 403/451 → 不可达
content < 50 字 → 只有导航栏 (失败)

--fetch N 一行集成

bash

python3 search.py "Python 教程" --engine bing_cn --mode dev --fetch 3
# 自动抓前 3 条正文 + 4.1 秒 + JSON/table 标注成功失败

v20.101 Bug fix: sqlite locked

lsof <install-dir>/scripts/.search_cache.sqlite → 找到僵尸 PID → kill -9

完整测试数据 + 10 URL benchmark + 16 条新规则见 references/v20-40-intent-strat-rule-pitfalls.md。

v20.101 反爬工具实测对比 (★ 重要)

工具	适用场景	server 实测	推荐
miku-ai (weixin-articles skill)	weixin.sogou.com + mp.weixin.qq.com	✅ 搜索 5/5 + 正文 200/41段	微信公众号垂直
undetected-playwright	通用反检测 playwright	❌ server 对 sogou 仍 captcha	仅本地 IP 有效
playwright 普通	JS 渲染	❌ sogou 0 结果	datacenter IP 全军覆没
curl + 移动 UA	静态 HTML	✅ csdn/blog/python.org 100%	默认首选
fetch_content.py (v20.101)	通用 fallback	✅ 50-70% 成功率	当前默认

v20.101 关键发现:

undetected-playwright 在 datacenter IP (server) 上对国内反爬无效 —— 反爬看 IP, 不看 playwright
miku-ai 是 mac 本机设计的反爬工具 (伪造 sogou cookie + 拿真 SNUID), server 也能跑
mp.weixin.qq.com 直 curl (移动 UA) 200 OK, 41 段正文, 成功率 100%
结论: 不要追反爬军备竞赛, 走"信源直连 + 整理层做厚"路线

v20.102 端到端 pipeline 整合 (v20.40 完成报告, 7/1)

7/1 指导: "继续 B+C" = 修 BRAIN prompt + 整合两边。端到端实测先于代码改造——curl /v1/search 暴露 4 个隐藏 bug:

端到端实测发现 (方法论: 跑一次 > 读 1000 行代码)

text

POST /v1/search {"query":"华为","top":3}
→ count=3 (bing_cn 主导)
→ answer=false 默认 → LLM 不调 → 用户看到原始链接
→ cross_verify_error: "name 'date' is not defined" → 整套崩
→ brain_info: None → entity_card: None

4 个隐藏 bug + 修复

#	Bug	根因	修复
1	`answer=false` 默认	SearchRequest 字段默认值错	改 `default=True` (api_server.py line 150)
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)
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)
4	`fetch_content RuntimeWarning: coroutine never awaited`	sync 函数 `asyncio.run(_go())` 在 FastAPI 已运行的 event loop 里冲突	改用 `nest_asyncio.apply() + loop.run_until_complete()` 兼容 (fetch_content.py)

端到端实测数据 (query="华为")

json

{
  "count": 3,
  "elapsed_ms": 1,
  "brain_info": {"entity": "华为", "intent": "info"},
  "entity_card": {"name": "华为", "official_url": "https://www.huawei.com/"},
  "fetch_stats": {"requested": 3, "success": 2},
  "cross_verify": {"consensus_score": 0, "source_count": 3},
  "answer": {
    "answer": "1. 华为是一家全球领先的通信和信息技术解决方案提供商...\n来源域名: huawei.com, consumer.huawei.com, vmall.com",
    "sources": ["huawei.com", "consumer.huawei.com", "vmall.com"],
    "model": "glm-4-flash",
    "tokens": 949,
    "elapsed_ms": 7050
  }
}

v20.102 4 阶段 pipeline 完整链路 (v20.40 串联)

text

[1] LLM 理解  query → brain_info {entity/intent/category/expected_info} (super_brain + few-shot prompt)
[2] 智能搜索  brain 推荐引擎 → multi_search → bing_cn HTTP 主搜 (10 条) + 缓存 (TTL 30min)
[3] LLM 整理  results → cross_verify (consensus_score) → entity_card (KB lookup)
[4] 智能输出  brain_ctx 注入 answer prompt → LLM 整合 → fetch_content 自动抓前 3 条 → 响应

每条结果自动带 credibility (来源可信度 0-1) + fetch_success (抓取成功标记) + content (抓到的正文片段)。

v20.102 文件改动清单

文件	改动	行号
`scripts/api_server.py`	`answer: bool = default=True` + `fetch: int = default=3` + 集成 fetch_content	line 150, +15
`scripts/cross_verify.py`	修 `date` not defined bug	line 274
`scripts/super_brain.py`	加 `context: str = '', **kwargs` 参数	line 107
`scripts/fetch_content.py`	nest_asyncio 兼容 (已运行时 loop)	+10
`/etc/systemd/system/star-search.service`	User=ubuntu + PLAYWRIGHT_BROWSERS_PATH + on-failure restart	重写

v20.102 关键工程经验 (必读, 未来迭代必用)

经验 1: 端到端实测先于代码改造

任何 LLM pipeline 改造前, 必须 curl /v1/search 跑一次看完整响应。 7/1 "ABC 逐个做" 之前我计划做"默认值 + bug 修复", 但实测暴露 4 个隐藏 bug (cross_verify / brain_info / fetch_content RuntimeWarning) —— 读 1000 行代码也找不到, 跑一次 curl 就能看到。

经验 2: sync 函数在 FastAPI async 环境里的 asyncio.run() 冲突

python

# 错: 已有 loop 时 RuntimeWarning
def fetch_url_playwright(url):
    data = asyncio.run(_go())  # 这里警告

# 对: nest_asyncio 兼容
def fetch_url_playwright(url):
    nest_asyncio.apply()
    loop = asyncio.get_event_loop()
    data = loop.run_until_complete(_go())

经验 3: 函数签名匹配调用方期望 (v20.71 上下文)

api_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/)。

经验 4: systemd restart 循环死锁

旧 unit 用 Restart=always + RestartSec=5 + 端口 5000 → 端口被僵尸 PID 占着 → 新进程 EADDRINUSE → 永远循环。新 unit:

Restart=on-failure (只在真崩时重启)
RestartSec=15 (足够时间端口释放)
不加 ExecStartPre=sleep 3 (避免干扰 restart cycle)
StandardOutput=append:<install-dir>/logs/stdout.log (ubuntu 用户可写)

v20.102 后续方向 (差 5.9pp 到 80% STRAT)

卡点	数据	方案
BRAIN LLM 不稳	88-94% 区间 (同 query 跑 3 次 88%/93.5%/92.6%)	1. few-shot 加更多边界 case 2. temperature 降到 0.05 3. 选 GLM-4-Plus (稳定但慢) 替代 Flash
边界 case	34/108 错: 模糊意图 (BRAIN 推 info 期望 transaction/news/comparison)	1. BRAIN prompt 加"query 含'价格/股价' 必推 transaction" 强规则 2. 加 Tavily API 作 backup 主源 (1 迭代可上)
KB 实体覆盖不全	微信文章 (mp.weixin.qq.com) / 知乎 (需登录) / 雪球 (反爬) / 36kr (删文)	1. miku-ai 集成 (公众号搜索 5/5 验证) 2. 雪球/36kr 专用 fetcher (v20.103)

v20.102 完整反爬工具文档 见 references/v20-40-intent-strat-rule-pitfalls.md 末尾新增章节。

v20.41: English search coverage + open scholarly sources (2026-07-23)

What is new

Three layered improvements merged into a single version release:

A. Automatic language routing: a new mode=auto detects query language and routes pure-English queries to the international Bing HTTP backend, removing the need for callers to pass mode=global manually.

B. English answer prompt: when the query classifier detects an English query of meaningful length (8+ chars, no Chinese characters), the answer layer switches to a dedicated English-language prompt. It mirrors the user language, enforces [N] citations, and requires an official URL for entity queries.

C. Two keyless scholarly sources: OpenAlex (200M+ papers, default sort by relevance) and CrossRef (journal DOI metadata). When the query matches academic keywords such as paper, research, or survey, an academic-aware merge inserts up to 3 scholarly results into the response head, ahead of general web results.

End-to-end public test

Eight query categories tested against the public API:

category	example query	chosen engine	pass
English tech concept	what is transformer architecture	bing_http	yes
English company	Apple company history founder	bing_http	yes
English scholarly RAG	RAG retrieval augmented generation paper	openalex	yes
English scholarly BERT	BERT pretraining paper 2018	openalex	yes
English scholarly RLHF	reinforcement learning human feedback paper	openalex	yes
Chinese news	today RAG news (CN)	bing_cn	yes
Chinese finance	Apple stock price today (CN)	rss engine	yes
Mixed CN and EN	RAG big model retrieval-augmented	bing_cn + weixin	yes

Result: 8 / 8 pass. Response times 0.3 - 4.0 seconds on the public endpoint.

Backwards compatibility

mode=auto is a new value; the default mode=deep is unchanged, so existing callers see no behavior change.
The academic-aware merge only triggers when the query contains academic keywords. General queries are unaffected.
The English prompt is selected only for non-trivial English queries. Short or bilingual queries use the existing tech or general prompt.

Files changed

scripts/search.py: mode=auto dispatch added at top of search_async.
scripts/answer.py: fifth prompt template plus a language-first classification rule.
scripts/academic_code.py: search_openalex and search_crossref functions; run_academic expanded to four engines with title-based deduplication.
scripts/api_server.py: the main /v1/search endpoint now merges academic results to the head of the result list when the query is academic.

v20.73→100→101 累计评分 (v20.33 → v20.40)

迭代	BRAIN (intent)	STRAT (entity_type)	两者都准	答案一致性	迭代关键
v20.73 之前	~70%	~30%	~25%	无	无脑
v20.64 - v20.78	91.7%	53.7%	51.9%	引用 (v20.81)	强约束 + brain 串联
v20.85 (KB 180+)	94.4%	56.5%	55.6%	引用	KB 翻倍
v20.86 (学术规则)	92.6%	59.3%	58.3%	引用	学术/教程强
v20.87 (CF 解除)	92.6%	59.3%	58.3%	引用	API 可用
v20.88-89	93.5%	56.5%	55.6%	引用	视频类修
v20.95 (4 维评分)	92.6%	56.5%	55.6%	+30% 排序	4 维可信度
v20.96 (realtime)	92.6%	56.5%	55.6%	引用 + 实时链接	财经报价
v20.100 (STRAT 16 规则 + few-shot)	91.7%	74.1%	68.5%	引用	意图策略冲 80% (实际 +17.6pp)
v20.101 (fetch_content.py + --fetch)	91.7%	74.1%	68.5%	引用 + 抓取正文	一步搜+抓取
v20.102 (默认值 + bug 修复 + 端到端)	91.7%	74.1%	68.5%	引用 + 答案 + entity_card	4 阶段 pipeline 默认开启
v20.103 (英文 search_auto 路由 + english prompt)	92.6%	56.5%	55.6%	英文答案主体	迭代 #2 e2e A1/A2 PASS
v20.104 (OpenAlex + CrossRef 免密钥学术源)	92.6%	56.5%	55.6%	+ academic merge	迭代 #2 e2e B1-B3 PASS (8/8)
Perplexity 业界基准	95%+	90%+	85%+	引用 + 答案	商业产品

v20.95 + 96 真实价值: 不是 intent 准度提升, 是答案质量 + 实时性 + 一致性 提升

star-search

Install

Star Search v20.33 — 速度/流式/多轮/稳定/学术/结构化/收藏/监控/AI 智能层/Cloudflare 应对 一体化中文搜索

⚠️ 关键必读 (v20.33 新增)

Cloudflare Bot 保护 (v20.87)

版本历史 (v20.32-20.33)

v20.78 - v20.86 意图理解大幅优化 (v20.33)

4 批 108 query 全面回归 (并发 8 线程, 90s 跑完)

detect_entity_type 17 规则优先级 (v20.78 调试 8 轮才到 10/10)

KB 180+ 实体 (v20.85)

真网址强优先 (v20.81)

4 批 108 query 测试方法论 (v20.77 - v20.85 + 86)

v20.87 Cloudflare Bot 保护 (v20.33 新章节)

v20.86 学术类 query 强规则 (v20.33)

v20.90 调研 + 91+92+95 迭代补全 (v20.35-v20.36)

v20.90 5 大 AI 引擎对比 (2026-06-19 调研)

v20.91 STRAT 边界修 (部分生效)

v20.92 对比表 (v20.64+81 已实现)

v20.93 follow-up (v17.4 已实现)

v20.94 多轮 context (v20.71+72 已实现)

v20.95 cross_verify 4 维评分 (新代码, v20.95 真实价值最大)

v20.96 实时财经报价 + 多模态 (v20.36)

realtime.py 4KB (v20.96)

/v1/realtime/quote + /v1/realtime/links 端点 (v20.96)

v20.57 /v1/multimodal/search 端点 (v20.96 复用)

v20.73-96 反复出现的 3 个 Sibling Patch 坑 (必读)

v20.100 STRAT 冲 80% (v20.40)

4 批 108 query 全程数据

v20.100 关键工程经验 (必读, 未来迭代必用)

经验 1: server 上跑测试 (mac 本地数据不可信)

经验 2: server 文件同步通道 (root 写权限问题)

经验 3: orphan 代码块必查

v20.100 错题天花板

v20.101 fetch_content.py + --fetch N (v20.40)

迭代反馈 (3 个痛点)

关键发现: server IP 被搜狗全反爬

fetch_content.py 设计模式

--fetch N 一行集成

v20.101 Bug fix: sqlite locked

v20.101 反爬工具实测对比 (★ 重要)

v20.102 端到端 pipeline 整合 (v20.40 完成报告, 7/1)

端到端实测发现 (方法论: 跑一次 > 读 1000 行代码)

4 个隐藏 bug + 修复

端到端实测数据 (query="华为")

v20.102 4 阶段 pipeline 完整链路 (v20.40 串联)

v20.102 文件改动清单

v20.102 关键工程经验 (必读, 未来迭代必用)

v20.102 后续方向 (差 5.9pp 到 80% STRAT)

v20.41: English search coverage + open scholarly sources (2026-07-23)

What is new

End-to-end public test

Backwards compatibility

Files changed

v20.73→100→101 累计评分 (v20.33 → v20.40)

Star Search v20.33 — 速度/流式/多轮/稳定/学术/结构化/收藏/监控/AI 智能层/Cloudflare 应对一体化中文搜索