Mr-remon219/search-boost

SearchBoost

面向 AI 编程代理的多引擎网页搜索与证据综合
一个共享核心运行时，深度适配 MCP、Pi 和 DeepSeek Harness

version
npm version
Node version
License
Architecture
Free tier

English · 中文文档

[!NOTE]
发布与分支说明：原先独立的 pi-search-boost 和 dsh-search-boost 项目已合并到 lib/ 下的同一代码库中。文档中指定 @latest 的命令会获取官方发布的 npm 包。若要测试尚未发布到正式版本的代码，请检出所需的分支或标签，并按照从源码安装与开发进行操作。

v0.2.2：新增 AnySearch、相关性感知融合评分，以及带已批准结果分页的批量 Jev 目标研究。包含针对版本匹配、发布时间戳和缓存清理的发布审计修复。参见发布与迁移说明。源码合并不会发布 npm；只有在单独进行 npm 发布后，@latest 才会包含此版本。

目录

- 核心特性
- 系统架构
- 支持的主机矩阵
- 快速开始（30 秒）
- 升级与迁移指南
- 交互式控制台（TUI）
- 工具套件与使用指南
- 工具职责与边界
- 1. fused_search 多引擎搜索
- 2. fetch_page 智能内容读取器
- 3. x_search X（Twitter）情报
- 4. adaptive_search Jev 证据循环（实验性）
- 引擎池与评分预设
- 并行多代理研究工作流
- 安全
- CLI 命令参考（无头与 CI）
- 从源码安装与开发
- 友情链接
- 许可证

核心特性

- 多引擎并行融合（fused_search）
并行查询多个搜索提供商。内置开箱即用的无密钥免费池（Bing、DuckDuckGo、Yahoo、Exa-free、AnySearch）以及带密钥的 API 池（Tavily、Brave、Exa、AnySearch）。自动执行跨引擎 URL 去重、域名路由和相关性重排序。
- 干净的网页内容提取器（fetch_page）
优先抓取源站以降低延迟，可选同路由 curl 兼容回退以及 Jina Reader 备份。剥离 CSS、JS 和广告杂讯。支持通过 focus 进行聚焦式上下文段落提取，并由内存缓存和大小限制提供支持。
- X / Twitter 社区情报（x_search）
通过官方 xAI API 或匿名回退通道检索公开帖子、用户时间线和讨论串。从 Snowflake 帖子 ID 恢复准确的 UTC 时间戳，并在不产生幻觉的情况下强制执行本地作者/日期过滤。
- Jev 自适应证据循环（adaptive_search · 实验性）
接受任务上下文、关键词替代方案和验收目标。每一轮最多使用三次 Jev 调用：规划、评分和覆盖。返回已批准的 URL、标题和描述，支持游标分页，且没有固定的累计结果数上限；执行仍然受预算约束。
- 原生多智能体并行研究
捆绑 search-boost 和 search-boost-parallel-research 技能。在支持子智能体的宿主（Cursor、Claude Code、Pi、DSH）中，任务可以分派给并行的 Searcher（收集证据）和 Summarizer（无工具的纯综合），同时支持 Fast 和 Complex 波次。
- 跨所有宿主生态系统的统一核心
一个单一的、宿主中立的核心运行时，为标准的模型上下文协议（MCP）服务器提供支持，同时为 Pi 提供原生扩展，并为 DeepSeek Harness（DSH）提供 Cordis 插件包。
- 零配置入门与严格安全
使用免费引擎池启动时无需任何 API 密钥。敏感凭据以明文形式存储在本地私有配置中，并具有受限的文件权限（POSIX 0600）；这不是静态加密。使用本地网络和代理 DNS，具有有界请求和显式回退，且零凭据泄漏到模型提示中。

系统架构

SearchBoost 遵循 “一个核心，三个适配器” 架构。所有搜索逻辑、内容解析、去重算法和网络安全机制都驻留在共享核心中：

SearchBoost TUI / CLI
安装 · 配置 · 更新
│
共享 SearchBoost 核心
lib/runtime.mjs 门面
搜索 · 抓取 · X · 自适应证据
│
┌───────────────┼───────────────┐
│               │               │
MCP 适配器       Pi 适配器      DSH 适配器
stdio 服务器     扩展           Cordis 包
│               │               │
┌────────┴────────┐      ▼               ▼
│ Cursor / Claude │      Pi       DeepSeek Harness
│ Codex / Grok    │
│ Antigravity     │
└─────────────────┘

- 核心（lib/）：与宿主无关的算法、引擎编排、Jev 客户端协议以及网络安全策略。
- 适配器（adapters/）：将核心操作映射到宿主特定的协议（MCP JSON-RPC、Pi Extension API、DSH Cordis 生命周期）。
- 代理（agents/）：宿主提示词契约、工作流模板以及原生技能定义。

支持的宿主矩阵

| 宿主 | 集成类型 | 文件 / 机制 | 能力与说明 |
| :--- | :--- | :--- | :--- |
| Cursor / Cursor CLI | MCP + Skills | ~/.cursor/mcp.json / skills/ | 支持 CLI 自动批准（cli-config.json）、会话启动注入、并行研究技能 |
| Claude Code | MCP + Prompts | 官方 claude MCP 配置 | 具备提示词边界的完整多引擎搜索与页面提取工具 |
| Codex | MCP + Prompts | 宿主 MCP 配置 | 无缝访问融合搜索、X 检索与阅读器工具 |
| Grok Build | MCP + Plugin | MCP 配置 + 捆绑插件 | 当 grok CLI 可用时，自动同步并安装配套插件 |
| Google Antigravity | MCP + Workspace | 工作区 MCP 配置 | 按项目提供工作区指导以及完整的搜索工具套件 |
| Pi | 原生扩展 | ~/.pi/agent/extensions/ / prompts/ | 注册原生扩展、/fast-parallel、/complex-parallel、搜索器/摘要器角色 |
| DeepSeek Harness | 原生捆绑包 | cordis.patch.yml / dsh plugin | 与 Cordis 运行时集成；提供原生 research_parallel 子代理与调用卡片 |

快速开始（30 秒）

前置条件
- Node.js：>= 22.13.0
- 包管理器：npm（或 pnpm）

1. 安装并启动仪表盘
bash
Install globally
npm install -g search-boost

Launch the interactive terminal UI (TUI)
search-boost

[!TIP]
零 API 密钥即可开始：SearchBoost 内置了强大的免费引擎池（Bing、DuckDuckGo、Yahoo、Exa-free）。无需注册任何付费提供商，即可立即开始搜索！

2. 三步设置向导
1. 在 TUI 菜单中选择 Setup。配置引擎密钥（或跳过以使用免费层级）以及可选的 X 凭据。
2. 勾选你想要集成的代理（Cursor、Claude Code、Pi 等），确认自动批准与原生搜索替换。
3. 重启或重新加载你所选的代理，然后在对话中让它们研究任何内容！

升级与迁移指南

1. 常规更新：通过 TUI 升级

无论你运行的是统一的 search-boost，还是安装了旧版的 pi-search-boost / dsh-search-boost，在 TUI 中选择 Update 即可升级所有内容：
bash
Option 1: Open the interactive menu
search-boost
-> Select "Update"

Option 2: Run headless update
search-boost upgrade -y
更新行为：获取最新发布的版本，更新 SearchBoost，并刷新所有已配置代理中的提示资源，同时保留现有密钥、层选择和权限设置。

2. 从旧版 search-boost-mcp 迁移

[!IMPORTANT]
如果你安装了旧的全局包 search-boost-mcp，npm 无法在包重命名后自动替换全局二进制文件。请使用一行 npx 迁移命令：
bash
通过 npx 执行安全迁移
npx --yes --package=search-boost@latest -- search-boost migrate -y

迁移完成后，日常更新只需：
search-boost
-> 选择 "Update"（或 search-boost upgrade -y）

交互式控制台（TUI）

不带参数启动 search-boost 即可访问基于 Clack 构建的交互式仪表板。轻松管理安装、更新和凭据：

| 菜单选项 | 用途 |
| :--- | :--- |
| Setup | 完成初始引导：配置引擎、搜索层、X 凭据并安装代理。 |
| Install / update agents | 安装或刷新选定的宿主集成，保留现有凭据和层设置。 |
| Update | 一键升级：检查 npm 更新，升级 SearchBoost，并刷新所有已安装的代理（包括旧版 Pi/DSH 适配器）。 |
| API keys / Search layer | 管理 Tavily、Brave、Exa 和可选的 AnySearch 凭据，并更改默认搜索层（free / api）。 |
| X credentials | 管理 X（Twitter）身份验证；支持从本地 Grok 登录一键导入。 |
| Jev credentials (experimental) | 配置 TypeSafe Jev 认知引擎端点和 Bearer 令牌。 |
| Native web search | 为支持配置开关的宿主启用或禁用宿主原生搜索。 |
| Status | 检查当前引擎可用性、配置状态和活动集成。 |
| Print MCP snippet | 将 MCP JSON 配置片段打印到 stdout，以便手动设置。 |
| Uninstall | 从选定的代理中安全移除 SearchBoost 集成，保持用户配置不变。 |

工具套件与使用指南

集成后，代理会自动接收标准工具定义，并自主决定何时调用它们。

工具职责与边界

| 工具 | 最适合用于 | 边界 / 非目标 |
| :--- | :--- | :--- |
| fused_search | 并行多引擎查询、去重和多样性重排序 | 单个搜索步骤；后续决策仍由父代理负责 |
| fetch_page | 从公共 URL 读取干净内容，可选关键词聚焦 | 不是带登录状态的浏览器；无法访问内部/私有网络 |
| x_search | 检索公开 X 帖子、作者时间线或讨论线程 | 不保证详尽的评论线程或完整的情绪采样 |
| adaptive_search | 实验性：Jev 引导的自主后续跟进与证据评估 | 已批准的 URL 和描述；模型批准并非独立验证 |
| search_stats | 读取引擎状态、内存缓存命中情况以及近期诊断统计信息 | 只读；配置就绪并不保证外部网络实际可达 |
| search_layer | 查看或切换 MCP 中的兼容性搜索层 | show 为只读；更改层会修改磁盘上的持久化配置 |

1. fused_search 多引擎搜索

并发地将查询分发到多个引擎，规范化 URL，去除重定向，并应用多样性过滤。

工具参数示例（JSON）：json
{
"query": "Node.js 22 built-in WebSocket API guide",
"include_domains": ["nodejs.org", "developer.mozilla.org"],
"engine_pool": "free",
"ranking": "balanced",
"complexity": "simple",
"max_results": 5
}

- engine_pool：free（无需密钥的 Bing、DuckDuckGo、Yahoo、Exa-free）、api（仅限已配置的付费引擎）或 hybrid（所有可用引擎）。
- ranking：评分预设：balanced（默认）、research（偏好权威/文档来源）或 fresh（偏好近期发布内容）。
- complexity：simple（1 个查询变体）、medium（最多 2 个变体）、complex（最多 3 个深度变体）。
- community：布尔值（默认 false）。设为 true 可将实时 X 开发者讨论混入最终结果配额。

2. fetch_page 智能内容阅读器

从搜索 URL 读取网页内容。优先读取并清理原始来源；安装后由 curl 处理传输兼容性，Jina Reader 作为备用。

工具参数示例：json
{
"url": "https://nodejs.org/api/globals.html",
"focus": "AbortSignal.any"
}

- focus（可选）：过滤并保留与目标关键词匹配的段落。
[!TIP]
focus 未命中并不能证明该信息不存在于页面中。如有疑问，请在不使用 focus 的情况下重新获取，以检查完整上下文。

3. x_search X（Twitter）情报

专为实时技术追踪和第一方开发者动态而设计。支持关键词搜索、作者时间线和线程对话。

工具参数示例：json
{
"query": "Claude 3.7 Sonnet hybrid reasoning from:AnthropicAI",
"mode": "keyword",
"max_results": 5
}

- 精确时间戳：当平台时间戳缺失或不一致时，从 64 位 Snowflake ID 恢复真实的 UTC 创建时间。
- 原生操作符：完全支持 from:username、since:YYYY-MM-DD 和 until:YYYY-MM-DD。

4. adaptive_search Jev 证据循环（实验性）
Vercel 支持：在 TUI → Jev credentials 中，输入 https://ai-gateway.vercel.sh/v1 和一个 Vercel AI Gateway 密钥。SearchBoost 选择官方 SDK 评估模型 typesafe-ai/jev，而不是 chat completions。默认的 TypeSafe /systemone 路径仍然受支持。两条路径都只使用规范的用户 Jev 凭据，而不是环境密钥，并遵守服务器速率限制延迟。

调用方提供任务上下文、关键词替代项和明确的验收问题。Jev 选择查询策略和引擎，然后对检索到的证据进行评分，并判断哪些目标需要再进行一轮。每一轮最多有三个逻辑请求，而不是每个 URL 一个请求。
json
{
"tasks": [{
"context": "ExampleDB 4.2 upgrade impact",
"targets": [{
"id": "migration",
"keywords": ["migration guide", "upgrade guide"],
"question": "What migration steps are required from 4.1 to 4.2?"
}]
}],
"page_size": 20
}

- 最多 6 个任务，每个任务 4 个目标，共 12 个目标；旧版 questions 输入仍然受支持。
- results 是一个扁平的 {url, title, description} 列表，仅包含已评估、已批准的材料，不包含未评估/已拒绝的候选内容。
- 使用 {"cursor":""} 读取更多内容：不会进行新的搜索或 Jev 调用。每页默认 20 条结果（最多 50 条），并有字节预算，但累计已批准结果没有固定数量上限。
- 检查 coverageComplete 和警告。分页结束并不等于穷尽搜索，模型批准也不等于独立的事实核验。
- 结果是进程本地的，最多保留 30 分钟 / 32 个最近结果集；过期、驱逐或重启会使游标失效。
- 可选的任务 time_range 区分发布日期和事件日期；未知日期不能作为今天的证据。

请参阅自适应搜索契约与限制。

引擎池与评分预设

engine_pool 选择引擎，ranking 选择共享的跨池权重，complexity 仅控制预算。AnySearch 是一个逻辑引擎：在 free 中匿名，在 api 中需要密钥，在 hybrid 中优先使用密钥。配置 ANYSEARCH_API_KEY 或 config keys --set anysearch=KEY。

| 引擎 | balanced | research | fresh |
| --- | ---: | ---: | ---: |
| bing | 0.957 | 0.927 | 1.020 |
| ddg | 0.981 | 0.903 | 0.927 |
| yahoo | 0.957 | 0.877 | 0.902 |
| exa-free | 1.004 | 1.085 | 0.951 |
| tavily | 1.049 | 1.105 | 1.084 |
| brave | 1.004 | 0.951 | 1.125 |
| exa | 1.049 | 1.146 | 1.063 |
| anysearch | 1.004 | 1.042 | 0.951 |

这些是未校准的冷启动先验，不是经过测量的质量排名。consensus-v2.1 结合原始排名、相关提供方折扣和 max+log 共识，元数据调整上限为 20%。质量分数和列表选择分数保持分离；零权重来源不能投票。重新校准旧的 min_score 阈值。请参阅评分与迁移和池路由。

并行多智能体研究工作流

一个共享工作流，带有三种宿主绑定。父智能体将问题拆分为相互独立的轨道；每个搜索器通过 fused_search 和 fetch_page 收集证据；随后一个无工具的总结器（或父智能体本身）将这些报告整合为一个答案。
text
[ Parent Agent ]
splits tracks · owns the answer
│
┌───────────────┴───────────────┐
▼                               ▼
[ Searcher A ]                  [ Searcher B ]
fused_search · fetch_page       fused_search · fetch_page
│                               │
└───────────────┬───────────────┘
▼
[ Summarizer ]
no tools · synthesis only
▼
[ Parent Report ]

| 宿主 | 入口点 | 子智能体如何运行 |
| :--- | :--- | :--- |
| Pi | /fast-parallel 和 /complex-parallel 提示词；search-parallel-subagent 工具；searcher / summarizer 角色 | 每个搜索器都是一个子进程，显式加载 SearchBoost Pi 扩展（adapters/pi/index.js），并且只能调用 fused_search 和 fetch_page；总结器以 --no-tools 启动。调用方选择波次大小——此运行器不设置并发上限。 |
| DeepSeek Harness | 原生 research_parallel 工具 | 子智能体通过宿主的子智能体服务在同一 Cordis 上下文上生成。搜索器接收 toolFilter.allow = ['fused_search','fetch_page']；总结器接收空允许列表。在一波开始前，research_parallel 会验证这两个工具均已注册，否则拒绝生成。句柄在成功和失败时都会被释放，且 maxDepth 保持为 1，因此子智能体无法进一步嵌套研究。 |
| MCP 宿主（Cursor、Claude Code、Codex、Grok、Antigravity） | 捆绑的 search-boost-parallel-research 技能 | 该技能嵌入相同的角色和工作流，并通过宿主提供的任何子智能体机制运行它们。没有可用委托机制的宿主会回退到由父智能体进行串行研究。 |

安装到 MCP 宿主时，还会安装配套的 search-boost 路由技能，它会为开放式问题选择正确的工具。

- 快速模式：一波搜索器，然后由父智能体综合——没有总结器，也没有第二波。
- 复杂模式：一到三波，中间进行差距审查；只有在仍存在实质性差距时才启动另一波，当证据充分时运行会提前停止。这些波次限制是工作流指令，而不是跨独立工具调用强制执行的全局配额。
- 回退：如果宿主无法委托，父智能体会串行研究，并如实说明，而不是假装运行了一波。

[!IMPORTANT]
子进程返回 ok 意味着它以非空文本结束，并不意味着其声明已验证。失败或部分报告仍会显示，但其 URL 会被排除在成功聚合之外，最终判断始终属于父进程。

关于 Pi/DSH 子工具加载、过时的 pi-search-boost 引用以及已停用的 deep_research 工具，请参见子代理工具设置与诊断。

安全

API 密钥使用本工具自有的凭据存储。它们不会被写入提示词、工具结果或 shell 配置文件中：

- 私有文件权限：密钥存放在 ~/.search-boost/config/keys.json 中（可通过 SEARCH_BOOST_HOME 重定向根目录）。在 POSIX 系统上，存储目录权限为 0700，文件权限为 0600；重写时基于一个全新的 0600 临时文件构建，而非就地写入，因此现有文件权限绝不会被放宽。同一根目录下的备份和升级回执同样为 0600。通过环境变量覆盖的目录保留其自身权限模式，而凭据文件仍以 0600 创建。Windows 没有 POSIX 权限位——那里适用 ACL 继承。
- 原子化、加锁写入：替换使用 O_EXCL 临时文件加重命名，因此读取者看到的要么是旧文件，要么是新文件，绝不会是部分写入的文件；写入失败会自行清理，并保持先前文件不变。读-改-写循环会获取排他锁，因此两个写入者不会静默丢失彼此的更新，被拒绝的更改也完全不会触及文件。
- 绝不回显：密钥只会发送给它所属的引擎（Tavily、Brave、Exa 和 AnySearch 的请求参数/请求头）。状态输出、search-boost config keys --show 以及诊断报告打印的都是掩码值（abcd****wxyz）；错误消息经过测试，确保不包含凭据材料，Jev 评估载荷也刻意不携带密钥、掩码密钥或指纹。AnySearch 在 free 模式下使用匿名配额，在 api 模式下需要密钥，在 hybrid 模式下优先使用已配置的密钥。其可能携带凭据的错误信封绝不会被回显或持久化。

CLI 命令参考（无头模式与 CI）

除交互式 TUI 外，SearchBoost 还提供了一套全面的 CLI，用于脚本编写和自动化：
bash
----------------- 核心与交互 -----------------
search-boost                                # 启动交互式仪表盘（TUI）
search-boost status                         # 打印当前活动配置和主机摘要
search-boost --help                         # 显示完整 CLI 文档

----------------- 无头安装 -----------------
search-boost install -t cursor -y           # 为 Cursor 安装并自动批准
search-boost install -t claude,codex --keep-native  # 安装同时保留主机原生搜索
search-boost install -t antigravity --workspace /path/to/project # 指定特定工作区
search-boost install -t pi -y               # 挂载 Pi 扩展和提示词模板
search-boost install -t dsh --profile web   # 连接到 DeepSeek Harness Web 配置文件
search-boost install -t cursor --dry-run    # 预览安装而不写入文件

----------------- 配置管理 -----------------
search-boost config keys                    # 从 CLI 管理 API 密钥
search-boost config keys --set anysearch=KEY  # 配置 AnySearch 密钥（ANYSEARCH_API_KEY）
search-boost config layer                   # 切换默认层（free / api）
search-boost config x --import-grok         # 从本地 Grok 登录导入 X 凭据
search-boost config jev                     # 配置 Jev 端点和令牌

----------------- 诊断与健康检查 -----------------
search-boost doctor                         # 运行离线诊断检查
search-boost doctor --strict                # 严格模式（出现警告时以非零状态退出）
search-boost doctor --json                  # 输出机器可读的 JSON 报告

----------------- 卸载 -----------------
search-boost uninstall -t cursor,claude -y  # 从选定的宿主中移除集成

从源码安装与开发

使用此路径可以为 SearchBoost 做贡献，或测试尚未包含在已发布版本中的代码。在其他地方，@latest 指的是已发布的包。

前置条件

- Node.js >= 22.13.0（与 package.json 匹配）
- git 和 npm
- 可选：curl，用于 fetch_page 中同路由传输兼容性回退

设置检出
bash
1. 克隆仓库
git clone https://github.com/Mr-remon219/search-boost.git
cd search-boost

2. 完全按照 CI 的方式安装依赖
npm ci

3. 重新生成捆绑的 Grok 插件资源
npm run plugin:sync-grok

克隆会落在仓库的默认分支上。要测试不同的分支或标签，请在安装依赖之前检出它（git checkout BRANCH_OR_TAG）。

无需全局安装即可运行
bash
node cli.mjs                  # 直接从检出目录运行交互式 TUI
node cli.mjs status           # 一次性状态摘要
node cli.mjs install -t pi -y # 从此检出目录挂载 Pi 扩展
node cli.mjs install -t dsh --profile web

node cli.mjs 接受与已安装的 search-boost 二进制文件相同的命令。如果你希望在终端中使用裸命令，请链接检出目录而不是从 npm 安装：
bash
npm link        # 或：npm install -g .
search-boost

更改适配器或代理资源后，请为该宿主重新运行相同的安装命令（node cli.mjs install -t HOST），以便宿主获取新文件，然后重启或重新加载该宿主。

PR 前的测试关卡

| 命令 | 覆盖范围 |
| :--- | :--- |
| npm run check | 对 CLI、核心、适配器和脚本进行语法检查 |
| npm run prepublishOnly | 完整的离线测试套件：插件同步、语法、CLI、安装、doctor、fusion、X、engines、X auth、Jev、密钥权限、dry-run、网络、搜索路由、适配器、并行研究、升级、MCP 和冒烟测试 |
| npm run test:network | 代理重试、curl 回退、请求边界和兼容性回归 |
| npm run test:adapters | MCP、Pi 和 DSH 适配器协议套件，以及 Pi 子代理设置迁移/诊断 |
| npm run test:parallel | 搜索器/摘要器契约、DSH 调度预检、取消和工具隔离 |
| npm run test:adaptive | Jev 自适应证据循环 |
| npm run smoke | MCP JSON-RPC 协议冒烟测试 |

这些套件针对回环测试夹具和进程替身运行，因此不需要引擎密钥；npm run prepublishOnly 通过是 PR 的标准。

友情链接

- LINUX DO

许可证

本项目基于 MIT License 授权。