npm - @eogee-tech/eosearch - Versions diffs - 0.2.0 → 0.2.1 - Mend

@eogee-tech/eosearch 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md +210 -208
package/build-cli/cli.js +206 -99
package/build-cli/updateCheck.js +140 -0
package/package.json +2 -1
package/skill/SKILL.md +214 -0
package/skill/eosearch-video/SKILL.md +119 -0
package/skill/eosearch-video/helpers/grab.sh +58 -0

package/README.md CHANGED Viewed

@@ -1,208 +1,210 @@
-# EoSearch
-本地优先、透明可验证的 Agent 搜索基础设施。查询经意图路由分发到多引擎并行搜索，结果融合去重、透明评分后返回结构化数据；正文抽取内置站点适配器与通用正文提取，`deep_search` 一步产出 token 预算内的干净检索上下文。
-**三种交付形态**：
-- **MCP 服务**：部署在服务端，用户通过 Streamable HTTP 端点接入，源码不出服务器；
-- **CLI 命令行客户端**：npm 包 `@eogee-tech/eosearch`（命令名 `eosearch`），薄客户端只封装服务端调用，Agent 与人都能在 Shell 里直接用；npm 包内不含任何引擎与聚合代码；
-- **Skill 开通入口**：`skill/SKILL.md` 交付给最终用户，放入客户端技能目录即生效——Agent 按其中指引完成接入，用户填入极会员密钥后 EoSearch 能力即开放；纯文档零代码。
-**鉴权与计费**：与 eogee.com 极会员体系打通——极会员个人密钥即 EoSearch 的访问凭证，按 Key 计配额；不提供匿名通道，未携带有效 Key 的请求一律拒绝。
-引擎爬取层派生自开源项目 [Open-WebSearch](https://github.com/Aas-ee/open-webSearch)（Apache License 2.0），聚合管线为原创实现。协议与归属声明见 [NOTICE](./NOTICE)。
-## MCP 工具
-| 工具 | 用途 | 关键参数 |
-|------|------|---------|
-| `eosearch_search` | 多引擎融合搜索，结果带透明评分 | `query` 必填；`limit`、`engines`、`zone`、`searchMode`、`freshness`、`includeDomains`、`excludeDomains`、`format` 可选 |
-| `eosearch_batch_search` | 一次调用并行跑多个独立搜索（默认至多 5 条），每条独立路由与评分 | `queries` 必填（字符串或对象数组）；`zone`、`format` 可选 |
-| `eosearch_fetch` | 正文抽取，CSDN/掘金/知乎/Linux.do/GitHub 自动走站点适配器 | `url` 必填；`maxChars`、`readability`、`renderMode` 可选 |
-| `eosearch_deep_search` | 搜索 + 选源 + 并行抓取正文，返回 token 预算内的检索摘录 | `query` 必填；`topN`、`tokenBudget`、`zone`、`engines`、`freshness`、`includeDomains`、`excludeDomains`、`format` 可选 |
-每条搜索结果携带 `score`（0-100）、`engines`（来源引擎）与 `reasons`（可读排序理由，如 `#1 on csdn`、`also found by bing`、`download-page penalty`），评分机制完全透明。
-**委派抓取**：反爬拦截、需 JS 渲染或非文本（PDF/图片）的页面，服务端无法直接提取正文时会返回带 `[委派]` 标记的分级接力指引，由调用方 Agent 用用户本机的浏览器工具完成读取（浏览器直读 → 打印 PDF 交 MinerU 免 Key 极速版 → 精确解析兜底），详见 Skill 文档。
-**时效与域名过滤**：`freshness`（day/week/month/year）在 baidu、sogou、duckduckgo、hackernews 上走引擎原生时间过滤，其余引擎按标题与描述中可解析的日期做后置兜底（无日期结果保留，不误杀）；`includeDomains`/`excludeDomains` 做子域名级的站内/站外过滤。被过滤掉的结果数通过 `filteredOut` 字段透明返回。
-## 服务用户接入
-用户开通 EoSearch 的标准路径：把 `skill/SKILL.md` 安装到客户端技能目录（如 `.zcode/skills/`、`.claude/skills/`），Agent 按其中指引完成接入；用户填入极会员个人密钥（eogee.com 个人中心「MCP密钥」申请）后，能力即开放、无需其他配置。密钥占位与各客户端（ZCode、Claude Code、Cherry Studio、Cursor 等）的完整配置示例都在 Skill 中。核心配置形如：
-```json
-{
-  "mcpServers": {
-    "eosearch": {
-      "type": "http",
-      "url": "https://eogee.com/search/v1/mcp",
-      "headers": { "X-API-Key": "极会员个人密钥" }
-    }
-  }
-}
-```
-## CLI 命令行客户端
-npm 包 `@eogee-tech/eosearch` 提供 `eosearch` 命令，面向所有能用 Shell 的场景：Agent 的 Bash 工具、CI、一次性沙箱容器、管道组合。服务端与 MCP 共用同一端点与配额，CLI 每次工具调用计 1 次配额，握手不计。
-```bash
-npm install -g @eogee-tech/eosearch     # 或免安装：npx @eogee-tech/eosearch
-export EOSEARCH_API_KEY=<极会员密钥>   # 或在 ~/.eosearchrc 写 {"apiKey":"..."}
-eosearch whoami                     # 自检：密钥有效即接入完成
-eosearch search "llama.cpp 新版本" --json --limit 5
-eosearch deep "2026 国产大模型对比" --top-n 3
-eosearch batch "量子计算现状" "相关ETF" --json
-eosearch fetch https://github.com/ggml-org/llama.cpp
-```
-| 子命令 | 对应 MCP 工具 | 说明 |
-|--------|--------------|------|
-| `search <query>` | `eosearch_search` | `--limit`、`--engines`、`--zone`、`--search-mode`、`--freshness`、`--include-domains`、`--exclude-domains`、`--json` |
-| `batch <q1> ... <q5>` | `eosearch_batch_search` | 并行 1-5 条查询，配额计 1 次 |
-| `fetch <url>` | `eosearch_fetch` | `--max-chars`、`--no-readability`、`--render-mode`、`--json` |
-| `deep <query>` | `eosearch_deep_search` | `--top-n`、`--token-budget`、其余过滤项同 search |
-| `whoami` | initialize 握手 | 验证密钥与服务连接，不计配额 |
-设计约定：密钥只从环境变量或 `~/.eosearchrc` 读取（不进命令行参数，避免泄漏进 Shell 历史）；数据走 stdout、诊断走 stderr；`--json` 输出与服务端 MCP 工具字段一致；语义化退出码——0 成功、1 业务空结果、2 用法错误、3 鉴权失败、4 配额限流、5 服务不可用或执行失败；报错固定三段式（错误/原因/下一步）。
-薄客户端边界：npm 包 `files` 只含 `build-cli/`（`src/cli/` 的编译产物），引擎爬取层与聚合层代码不出仓库；顶层 `eosearch` 包名已被无关包占用，故发布名为 `@eogee-tech/eosearch`，命令名仍为 `eosearch`。
-## 服务端部署
-```bash
-npm install && npm run build
-EOSEARCH_EOGEE_AUTH=true EOSEARCH_REQUIRE_KEY=true MODE=http PORT=3000 node build/index.js
-```
-前置 Nginx 反代并终止 TLS 即可对外服务。生产环境务必配置：
-1. `EOSEARCH_REQUIRE_KEY=true`（拒绝匿名访问，当前生产口径）；
-2. `EOSEARCH_API_KEYS` 预留若干静态 Key 供内部测试。
-服务本身零 LLM 依赖：搜索与摘录全部由确定性代码完成，理解与总结交给调用方 Agent。
-健康检查端点 `GET /health` 无需鉴权，返回各引擎熔断状态，可接入监控。
-## 极会员体系集成
-启用 `EOSEARCH_EOGEE_AUTH=true` 后，用户传入的密钥会回源 `https://eogee.com/kb/v1/mcp`（MCP 网关）校验：无效密钥网关返回 401，有效密钥返回 200。校验结果带 TTL 缓存（有效 10 分钟、无效 2 分钟），不会每次调用都回源。
-- 密钥头兼容两种写法：`X-API-Key: <key>`（eogee 生态惯例）与 `Authorization: Bearer <key>`；
-- 回源失败时默认拒绝（503，保收费），设 `EOSEARCH_EOGEE_FAIL_OPEN=true` 改为放行（保可用）；
-- 极会员校验与静态 Key（`EOSEARCH_API_KEYS`）可叠加，静态 Key 优先命中。
-### 两档配额
-| 档位 | 判定条件 | 每日 | 每分钟 |
-|------|---------|------|--------|
-| 极会员 | 有效 Key 且等级为 premium | 不限 | 60 次 |
-| 普通用户 | 有效 Key 且等级为 regular | 100 次 | 10 次 |
-| 匿名 | 无 Key | 拒绝（401） | — |
-匿名通道不开放：生产配置 `EOSEARCH_REQUIRE_KEY=true`，未携带有效 Key 的请求一律 401。引擎层的匿名配额能力（`EOSEARCH_ANON_*`）仅供自用/内测模式。
-### 普通用户 Key 的等级识别（eogee.com 侧对接契约）
-eogee.com 签发普通用户 Key 后，EoSearch 用以下任一机制识别等级，**可先用地一再升级**：
-1. **Key 前缀约定（零后端改动）**：普通用户 Key 统一带固定前缀（如 `reg_`），EoSearch 侧配置 `EOSEARCH_REGULAR_KEY_PREFIX=reg_` 即可自动归入普通档；
-2. **网关响应头（推荐，最终形态）**：网关在 initialize 响应中回传 `X-Member-Level: premium` 或 `X-Member-Level: regular` 头，EoSearch 自动解析并缓存，前缀规则随之不再依赖。
-两种机制同时存在时，响应头优先。
-## 鉴权与配额
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `EOSEARCH_API_KEYS` | 空 | 逗号分隔的静态 Key 列表；为空且未开极会员时鉴权整体关闭（自用模式） |
-| `EOSEARCH_EOGEE_AUTH` | `false` | 启用极会员密钥回源校验 |
-| `EOSEARCH_EOGEE_MCP_URL` | `https://eogee.com/kb/v1/mcp` | 极会员校验网关地址 |
-| `EOSEARCH_EOGEE_FAIL_OPEN` | `false` | 校验后端不可达时 true 放行 / false 拒绝 |
-| `EOSEARCH_EOGEE_CACHE_TTL_MS` | `600000` | 有效密钥缓存时长 |
-| `EOSEARCH_EOGEE_INVALID_TTL_MS` | `120000` | 无效密钥缓存时长（短于有效期，密钥吊销后尽快生效） |
-| `EOSEARCH_EOGEE_CACHE_MAX_ENTRIES` | `5000` | 校验结果缓存容量上限（LRU 驱逐，防恶意喷射 Key 撑爆内存） |
-| `EOSEARCH_REQUIRE_KEY` | `false` | `true` 时拒绝匿名访问（纯会员模式） |
-| `EOSEARCH_REGULAR_KEY_PREFIX` | 空 | 普通用户 Key 前缀约定（如 `reg_`），命中则归入普通档 |
-| `EOSEARCH_KEY_DAILY_LIMIT` | `0`（不限） | 极会员每日配额，营销口径"不限次数" |
-| `EOSEARCH_KEY_MINUTE_LIMIT` | `60` | 极会员每分钟限速（防滥用的真正防线） |
-| `EOSEARCH_REGULAR_DAILY_LIMIT` | `100` | 普通用户每日配额 |
-| `EOSEARCH_REGULAR_MINUTE_LIMIT` | `10` | 普通用户每分钟限速 |
-| `EOSEARCH_ANON_DAILY_LIMIT` | `50` | 匿名每日配额，0 = 不限（仅自用/内测模式，生产拒绝匿名） |
-| `EOSEARCH_ANON_MINUTE_LIMIT` | `10` | 匿名每分钟限速，0 = 不限（仅自用/内测模式） |
-配额只计实际工具调用（`tools/call`），连接握手与工具列表查询不计费；一次 `eosearch_batch_search` 无论含几条 query 都只计 1 次调用（单次批量的 query 数上限由 `EOSEARCH_BATCH_MAX_QUERIES` 控制，默认 5）。超限返回 429 并携带 `Retry-After`；成功调用响应携带 `X-Quota-Remaining-Today`。
-## 工作原理
-```mermaid
-graph LR
-    A[MCP 四工具] --> H[鉴权与配额<br/>极会员 / 普通用户两档]
-    H --> B[意图路由<br/>语言与领域识别]
-    B --> C[引擎健康门<br/>熔断剔除]
-    C --> D[多引擎并行<br/>SERP 缓存]
-    D --> E[融合评分<br/>去重与透明 score]
-    A --> F[抽取管线<br/>站点适配器 + Readability]
-    A --> G[deep_search<br/>选源与 token 预算]
-    F --> G
-```
-1. **意图路由**：识别查询语言与意图（技术文档 / 代码 / 资讯 / 通用），自动选择引擎组合。中文技术查询优先 CSDN、掘金、Bing；英文代码查询优先 DuckDuckGo、Hacker News。显式传 `engines` 可绕过路由。
-2. **融合评分**：按归一化 URL 去重聚合，评分 = 引擎内排名 + 多引擎佐证 + 查询词相关性 + 引擎权威度加权；下载站与文库页自动降权，全部分量写入 `reasons`；融合后可再按 `freshness` 与 `includeDomains`/`excludeDomains` 做后置过滤，剔除数透明计入 `filteredOut`。
-3. **健康监控**：单引擎连续失败触发熔断（冷却后半开重试），单引擎调用有超时竞速，个别引擎卡死不拖慢整体。
-4. **抽取管线**：CSDN、掘金、知乎、Linux.do 文章与 GitHub README 走专用适配器，失败自动回落通用抓取（Mozilla Readability）。
-5. **缓存**：SERP 与页面带 TTL 进程内缓存，重复查询零网络开销。
-## 环境变量（引擎层，沿用上游）
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `MODE` | `both` | `stdio`、`http` 或 `both` |
-| `PORT` | `3000` | HTTP 端口 |
-| `DEFAULT_SEARCH_ENGINE` | `bing` | 显式指定未知引擎时的默认引擎 |
-| `ALLOWED_SEARCH_ENGINES` | 全部 | 逗号分隔的引擎白名单 |
-| `USE_PROXY` / `PROXY_URL` | 关闭 | 引擎层 HTTP 代理 |
-| `SEARCH_MODE` | `auto` | Bing 搜索策略 |
-| `EOSEARCH_ROUTE_TOPK` | `3` | 自动路由选择的引擎数量（1-6） |
-| `EOSEARCH_ENGINE_TIMEOUT_MS` | `15000` | 单引擎调用超时 |
-| `EOSEARCH_BREAKER_THRESHOLD` | `3` | 连续失败熔断阈值 |
-| `EOSEARCH_BREAKER_COOLDOWN_MS` | `300000` | 熔断冷却时长 |
-| `EOSEARCH_CACHE_TTL_MS` | `600000` | 搜索结果缓存 TTL |
-| `EOSEARCH_FETCH_CACHE_TTL_MS` | `1800000` | 页面抽取缓存 TTL |
-| `EOSEARCH_BATCH_MAX_QUERIES` | `5` | 单次批量搜索的 query 数上限（1-20） |
-| `EOSEARCH_BATCH_CONCURRENCY` | `2` | 批量搜索的批内并发度（1-10） |
-| `EOSEARCH_EOGEE_KB_API_KEY` | 空 | eogee KB 垂直引擎的服务 Key；配置后 eogee.com 站内内容接入搜索路由，留空则引擎不启用 |
-| `EOSEARCH_EOGEE_KB_MCP_URL` | 同 `EOSEARCH_EOGEE_MCP_URL` | KB 网关地址，同机部署可指向内网回环 |
-Playwright 浏览器兜底为可选能力，配置方式与上游一致，详见 [Open-WebSearch README](https://github.com/Aas-ee/open-webSearch#readme)。
-## 支持的搜索引擎
-baidu、bing、csdn、duckduckgo、exa、brave、juejin、startpage、sogou、hackernews、zhihu、linuxdo（上游标记暂不可用，显式指定仍可尝试）、eogee（eogee.com 知识库垂直源，原创实现）。
-eogee 引擎把 eogee.com 站内教程与资讯接入中文技术文档与资讯意图的优先路由：配置 `EOSEARCH_EOGEE_KB_API_KEY` 后自动启用（未配置则不参与路由），通过 MCP 协议调用知识库网关 `search_articles`，多词 query 自动分词多探针并行搜索并按命中覆盖度合并。生产与 KB 同机部署时建议将 `EOSEARCH_EOGEE_KB_MCP_URL` 指向内网回环地址。
-## 本地开发
-```bash
-git clone <本仓库>
-cd eosearch
-npm install
-npm run build          # 编译到 build/
-npm run smoke          # 冒烟测试：路由单测 + 真实搜索/抓取/deep_search
-node test/auth-http-test.mjs <极会员Key>   # 鉴权集成测试（需先以测试配置起服务）
-npx @modelcontextprotocol/inspector build/index.js   # MCP 调试器
-```
-## 许可证与商业化说明
-Apache License 2.0。引擎爬取层派生自 Open-WebSearch 项目，归属与修改声明见 [NOTICE](./NOTICE)。
-Apache 2.0 的源码公开义务仅在**分发**软件时触发；将本项目部署于自有服务器对外提供服务不属于分发，源码无需公开。前提：本仓库保持私有、不发布 npm 包。依赖链均为 MIT / Apache 2.0，无 GPL 传染。
-使用提示：本项目通过抓取公开搜索引擎结果页工作，引擎自身的服务条款与反爬策略不受本项目控制，请保持合理调用频率，生产环境依靠缓存命中率与限流设计控制风险。
-## 数据留存说明
-服务进程只在内存中缓存查询词与搜索结果（TTL 到期即弃，进程重启即清零），不落盘、无第三方统计与遥测组件。搜索引擎调用会把查询词转发给相应的搜索引擎（百度、必应、搜狗等），其各自的隐私政策不在本项目控制范围；极会员鉴权仅向 eogee.com 网关回源校验密钥有效性，不做其他数据外传。HTTP 访问日志由 Nginx 等前置网关按运维侧策略管理。
+# EoSearch
+本地优先、透明可验证的 Agent 搜索基础设施。查询经意图路由分发到多引擎并行搜索，结果融合去重、透明评分后返回结构化数据；正文抽取内置站点适配器与通用正文提取，`deep_search` 一步产出 token 预算内的干净检索上下文。
+**三种交付形态**：
+- **MCP 服务**：部署在服务端，用户通过 Streamable HTTP 端点接入，源码不出服务器；
+- **CLI 命令行客户端**：npm 包 `@eogee-tech/eosearch`（命令名 `eosearch`），薄客户端只封装服务端调用，Agent 与人都能在 Shell 里直接用；npm 包内不含任何引擎与聚合代码；
+- **Skill 开通入口**：`skill/SKILL.md` 交付给最终用户，放入客户端技能目录即生效——Agent 按其中指引完成接入，用户填入API密钥后 EoSearch 能力即开放；纯文档零代码。
+**鉴权与计费**：与 eogee.com 极会员体系打通——极会员个人密钥即 EoSearch 的访问凭证，按 Key 计配额；不提供匿名通道，未携带有效 Key 的请求一律拒绝。
+引擎爬取层派生自开源项目 [Open-WebSearch](https://github.com/Aas-ee/open-webSearch)（Apache License 2.0），聚合管线为原创实现。协议与归属声明见 [NOTICE](./NOTICE)。
+## MCP 工具
+| 工具 | 用途 | 关键参数 |
+|------|------|---------|
+| `eosearch_search` | 多引擎融合搜索，结果带透明评分 | `query` 必填；`limit`、`engines`、`zone`、`searchMode`、`freshness`、`includeDomains`、`excludeDomains`、`format` 可选 |
+| `eosearch_batch_search` | 一次调用并行跑多个独立搜索（默认至多 5 条），每条独立路由与评分 | `queries` 必填（字符串或对象数组）；`zone`、`format` 可选 |
+| `eosearch_fetch` | 正文抽取，CSDN/掘金/知乎/Linux.do/GitHub 自动走站点适配器 | `url` 必填；`maxChars`、`readability`、`renderMode` 可选 |
+| `eosearch_deep_search` | 搜索 + 选源 + 并行抓取正文，返回 token 预算内的检索摘录 | `query` 必填；`topN`、`tokenBudget`、`zone`、`engines`、`freshness`、`includeDomains`、`excludeDomains`、`format` 可选 |
+每条搜索结果携带 `score`（0-100）、`engines`（来源引擎）与 `reasons`（可读排序理由，如 `#1 on csdn`、`also found by bing`、`download-page penalty`），评分机制完全透明。
+**委派抓取**：反爬拦截、需 JS 渲染或非文本（PDF/图片）的页面，服务端无法直接提取正文时会返回带 `[委派]` 标记的分级接力指引，由调用方 Agent 用用户本机的浏览器工具完成读取（浏览器直读 → 打印 PDF 交 MinerU 免 Key 极速版 → 精确解析兜底），详见 Skill 文档。
+**时效与域名过滤**：`freshness`（day/week/month/year）在 baidu、sogou、duckduckgo、hackernews 上走引擎原生时间过滤，其余引擎按标题与描述中可解析的日期做后置兜底（无日期结果保留，不误杀）；`includeDomains`/`excludeDomains` 做子域名级的站内/站外过滤。被过滤掉的结果数通过 `filteredOut` 字段透明返回。
+## 服务用户接入
+用户开通 EoSearch 的标准路径：把 `skill/SKILL.md` 安装到客户端技能目录（如 `.zcode/skills/`、`.claude/skills/`），Agent 按其中指引完成接入；用户填入极会员个人密钥（eogee.com 个人中心「MCP密钥」申请）后，能力即开放、无需其他配置。密钥占位与各客户端（ZCode、Claude Code、Cherry Studio、Cursor 等）的完整配置示例都在 Skill 中。核心配置形如：
+```json
+{
+  "mcpServers": {
+    "eosearch": {
+      "type": "http",
+      "url": "https://eogee.com/search/v1/mcp",
+      "headers": { "X-API-Key": "极会员个人密钥" }
+    }
+  }
+}
+```
+## CLI 命令行客户端
+npm 包 `@eogee-tech/eosearch` 提供 `eosearch` 命令，面向所有能用 Shell 的场景：Agent 的 Bash 工具、CI、一次性沙箱容器、管道组合。服务端与 MCP 共用同一端点与配额，CLI 每次工具调用计 1 次配额，握手不计。
+```bash
+npm install -g @eogee-tech/eosearch     # 或免安装：npx @eogee-tech/eosearch
+export EOSEARCH_API_KEY=<你的API密钥>   # 或在 ~/.eosearchrc 写 {"apiKey":"..."}
+eosearch whoami                     # 自检：密钥有效即接入完成
+eosearch search "llama.cpp 新版本" --json --limit 5
+eosearch deep "2026 国产大模型对比" --top-n 3
+eosearch batch "量子计算现状" "相关ETF" --json
+eosearch fetch https://github.com/ggml-org/llama.cpp
+```
+CLI 每次启动会在后台最多每日检查一次 npm 新版本（缓存 `~/.eosearch-update.json`），有更新时在 stderr 提示，不阻塞当前命令；`CI` / `NO_UPDATE_NOTIFIER=1` 关闭，`--json` 调用不提示。
+| 子命令 | 对应 MCP 工具 | 说明 |
+|--------|--------------|------|
+| `search <query>` | `eosearch_search` | `--limit`、`--engines`、`--zone`、`--search-mode`、`--freshness`、`--include-domains`、`--exclude-domains`、`--json` |
+| `batch <q1> ... <q5>` | `eosearch_batch_search` | 并行 1-5 条查询，配额计 1 次 |
+| `fetch <url>` | `eosearch_fetch` | `--max-chars`、`--no-readability`、`--render-mode`、`--json` |
+| `deep <query>` | `eosearch_deep_search` | `--top-n`、`--token-budget`、其余过滤项同 search |
+| `whoami` | initialize 握手 | 验证密钥与服务连接，不计配额 |
+设计约定：密钥只从环境变量或 `~/.eosearchrc` 读取（不进命令行参数，避免泄漏进 Shell 历史）；数据走 stdout、诊断走 stderr；`--json` 输出与服务端 MCP 工具字段一致；语义化退出码——0 成功、1 业务空结果、2 用法错误、3 鉴权失败、4 配额限流、5 服务不可用或执行失败；报错固定三段式（错误/原因/下一步）。
+薄客户端边界：npm 包 `files` 只含 `build-cli/`（`src/cli/` 的编译产物），引擎爬取层与聚合层代码不出仓库；顶层 `eosearch` 包名已被无关包占用，故发布名为 `@eogee-tech/eosearch`，命令名仍为 `eosearch`。
+## 服务端部署
+```bash
+npm install && npm run build
+EOSEARCH_EOGEE_AUTH=true EOSEARCH_REQUIRE_KEY=true MODE=http PORT=3000 node build/index.js
+```
+前置 Nginx 反代并终止 TLS 即可对外服务。生产环境务必配置：
+1. `EOSEARCH_REQUIRE_KEY=true`（拒绝匿名访问，当前生产口径）；
+2. `EOSEARCH_API_KEYS` 预留若干静态 Key 供内部测试。
+服务本身零 LLM 依赖：搜索与摘录全部由确定性代码完成，理解与总结交给调用方 Agent。
+健康检查端点 `GET /health` 无需鉴权，返回各引擎熔断状态，可接入监控。
+## 极会员体系集成
+启用 `EOSEARCH_EOGEE_AUTH=true` 后，用户传入的密钥会回源 `https://eogee.com/kb/v1/mcp`（MCP 网关）校验：无效密钥网关返回 401，有效密钥返回 200。校验结果带 TTL 缓存（有效 10 分钟、无效 2 分钟），不会每次调用都回源。
+- 密钥头兼容两种写法：`X-API-Key: <key>`（eogee 生态惯例）与 `Authorization: Bearer <key>`；
+- 回源失败时默认拒绝（503，保收费），设 `EOSEARCH_EOGEE_FAIL_OPEN=true` 改为放行（保可用）；
+- 极会员校验与静态 Key（`EOSEARCH_API_KEYS`）可叠加，静态 Key 优先命中。
+### 两档配额
+| 档位 | 判定条件 | 每日 | 每分钟 |
+|------|---------|------|--------|
+| 极会员 | 有效 Key 且等级为 premium | 不限 | 60 次 |
+| 普通用户 | 有效 Key 且等级为 regular | 100 次 | 10 次 |
+| 匿名 | 无 Key | 拒绝（401） | — |
+匿名通道不开放：生产配置 `EOSEARCH_REQUIRE_KEY=true`，未携带有效 Key 的请求一律 401。引擎层的匿名配额能力（`EOSEARCH_ANON_*`）仅供自用/内测模式。
+### 普通用户 Key 的等级识别（eogee.com 侧对接契约）
+eogee.com 签发普通用户 Key 后，EoSearch 用以下任一机制识别等级，**可先用地一再升级**：
+1. **Key 前缀约定（零后端改动）**：普通用户 Key 统一带固定前缀（如 `reg_`），EoSearch 侧配置 `EOSEARCH_REGULAR_KEY_PREFIX=reg_` 即可自动归入普通档；
+2. **网关响应头（推荐，最终形态）**：网关在 initialize 响应中回传 `X-Member-Level: premium` 或 `X-Member-Level: regular` 头，EoSearch 自动解析并缓存，前缀规则随之不再依赖。
+两种机制同时存在时，响应头优先。
+## 鉴权与配额
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `EOSEARCH_API_KEYS` | 空 | 逗号分隔的静态 Key 列表；为空且未开极会员时鉴权整体关闭（自用模式） |
+| `EOSEARCH_EOGEE_AUTH` | `false` | 启用 API 密钥回源校验 |
+| `EOSEARCH_EOGEE_MCP_URL` | `https://eogee.com/kb/v1/mcp` | 极会员校验网关地址 |
+| `EOSEARCH_EOGEE_FAIL_OPEN` | `false` | 校验后端不可达时 true 放行 / false 拒绝 |
+| `EOSEARCH_EOGEE_CACHE_TTL_MS` | `600000` | 有效密钥缓存时长 |
+| `EOSEARCH_EOGEE_INVALID_TTL_MS` | `120000` | 无效密钥缓存时长（短于有效期，密钥吊销后尽快生效） |
+| `EOSEARCH_EOGEE_CACHE_MAX_ENTRIES` | `5000` | 校验结果缓存容量上限（LRU 驱逐，防恶意喷射 Key 撑爆内存） |
+| `EOSEARCH_REQUIRE_KEY` | `false` | `true` 时拒绝匿名访问（纯会员模式） |
+| `EOSEARCH_REGULAR_KEY_PREFIX` | 空 | 普通用户 Key 前缀约定（如 `reg_`），命中则归入普通档 |
+| `EOSEARCH_KEY_DAILY_LIMIT` | `0`（不限） | 极会员每日配额，营销口径"不限次数" |
+| `EOSEARCH_KEY_MINUTE_LIMIT` | `60` | 极会员每分钟限速（防滥用的真正防线） |
+| `EOSEARCH_REGULAR_DAILY_LIMIT` | `100` | 普通用户每日配额 |
+| `EOSEARCH_REGULAR_MINUTE_LIMIT` | `10` | 普通用户每分钟限速 |
+| `EOSEARCH_ANON_DAILY_LIMIT` | `50` | 匿名每日配额，0 = 不限（仅自用/内测模式，生产拒绝匿名） |
+| `EOSEARCH_ANON_MINUTE_LIMIT` | `10` | 匿名每分钟限速，0 = 不限（仅自用/内测模式） |
+配额只计实际工具调用（`tools/call`），连接握手与工具列表查询不计费；一次 `eosearch_batch_search` 无论含几条 query 都只计 1 次调用（单次批量的 query 数上限由 `EOSEARCH_BATCH_MAX_QUERIES` 控制，默认 5）。超限返回 429 并携带 `Retry-After`；成功调用响应携带 `X-Quota-Remaining-Today`。
+## 工作原理
+```mermaid
+graph LR
+    A[MCP 四工具] --> H[鉴权与配额<br/>极会员 / 普通用户两档]
+    H --> B[意图路由<br/>语言与领域识别]
+    B --> C[引擎健康门<br/>熔断剔除]
+    C --> D[多引擎并行<br/>SERP 缓存]
+    D --> E[融合评分<br/>去重与透明 score]
+    A --> F[抽取管线<br/>站点适配器 + Readability]
+    A --> G[deep_search<br/>选源与 token 预算]
+    F --> G
+```
+1. **意图路由**：识别查询语言与意图（技术文档 / 代码 / 资讯 / 通用），自动选择引擎组合。中文技术查询优先 CSDN、掘金、Bing；英文代码查询优先 DuckDuckGo、Hacker News。显式传 `engines` 可绕过路由。
+2. **融合评分**：按归一化 URL 去重聚合，评分 = 引擎内排名 + 多引擎佐证 + 查询词相关性 + 引擎权威度加权；下载站与文库页自动降权，全部分量写入 `reasons`；融合后可再按 `freshness` 与 `includeDomains`/`excludeDomains` 做后置过滤，剔除数透明计入 `filteredOut`。
+3. **健康监控**：单引擎连续失败触发熔断（冷却后半开重试），单引擎调用有超时竞速，个别引擎卡死不拖慢整体。
+4. **抽取管线**：CSDN、掘金、知乎、Linux.do 文章与 GitHub README 走专用适配器，失败自动回落通用抓取（Mozilla Readability）。
+5. **缓存**：SERP 与页面带 TTL 进程内缓存，重复查询零网络开销。
+## 环境变量（引擎层，沿用上游）
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `MODE` | `both` | `stdio`、`http` 或 `both` |
+| `PORT` | `3000` | HTTP 端口 |
+| `DEFAULT_SEARCH_ENGINE` | `bing` | 显式指定未知引擎时的默认引擎 |
+| `ALLOWED_SEARCH_ENGINES` | 全部 | 逗号分隔的引擎白名单 |
+| `USE_PROXY` / `PROXY_URL` | 关闭 | 引擎层 HTTP 代理 |
+| `SEARCH_MODE` | `auto` | Bing 搜索策略 |
+| `EOSEARCH_ROUTE_TOPK` | `3` | 自动路由选择的引擎数量（1-6） |
+| `EOSEARCH_ENGINE_TIMEOUT_MS` | `15000` | 单引擎调用超时 |
+| `EOSEARCH_BREAKER_THRESHOLD` | `3` | 连续失败熔断阈值 |
+| `EOSEARCH_BREAKER_COOLDOWN_MS` | `300000` | 熔断冷却时长 |
+| `EOSEARCH_CACHE_TTL_MS` | `600000` | 搜索结果缓存 TTL |
+| `EOSEARCH_FETCH_CACHE_TTL_MS` | `1800000` | 页面抽取缓存 TTL |
+| `EOSEARCH_BATCH_MAX_QUERIES` | `5` | 单次批量搜索的 query 数上限（1-20） |
+| `EOSEARCH_BATCH_CONCURRENCY` | `2` | 批量搜索的批内并发度（1-10） |
+| `EOSEARCH_EOGEE_KB_API_KEY` | 空 | eogee KB 垂直引擎的服务 Key；配置后 eogee.com 站内内容接入搜索路由，留空则引擎不启用 |
+| `EOSEARCH_EOGEE_KB_MCP_URL` | 同 `EOSEARCH_EOGEE_MCP_URL` | KB 网关地址，同机部署可指向内网回环 |
+Playwright 浏览器兜底为可选能力，配置方式与上游一致，详见 [Open-WebSearch README](https://github.com/Aas-ee/open-webSearch#readme)。
+## 支持的搜索引擎
+baidu、bing、csdn、duckduckgo、exa、brave、juejin、startpage、sogou、hackernews、zhihu、linuxdo（上游标记暂不可用，显式指定仍可尝试）、eogee（eogee.com 知识库垂直源，原创实现）。
+eogee 引擎把 eogee.com 站内教程与资讯接入中文技术文档与资讯意图的优先路由：配置 `EOSEARCH_EOGEE_KB_API_KEY` 后自动启用（未配置则不参与路由），通过 MCP 协议调用知识库网关 `search_articles`，多词 query 自动分词多探针并行搜索并按命中覆盖度合并。生产与 KB 同机部署时建议将 `EOSEARCH_EOGEE_KB_MCP_URL` 指向内网回环地址。
+## 本地开发
+```bash
+git clone <本仓库>
+cd eosearch
+npm install
+npm run build          # 编译到 build/
+npm run smoke          # 冒烟测试：路由单测 + 真实搜索/抓取/deep_search
+node test/auth-http-test.mjs <极会员Key>   # 鉴权集成测试（需先以测试配置起服务）
+npx @modelcontextprotocol/inspector build/index.js   # MCP 调试器
+```
+## 许可证与商业化说明
+Apache License 2.0。引擎爬取层派生自 Open-WebSearch 项目，归属与修改声明见 [NOTICE](./NOTICE)。
+Apache 2.0 的源码公开义务仅在**分发**软件时触发；将本项目部署于自有服务器对外提供服务不属于分发，源码无需公开。前提：本仓库保持私有、不发布 npm 包。依赖链均为 MIT / Apache 2.0，无 GPL 传染。
+使用提示：本项目通过抓取公开搜索引擎结果页工作，引擎自身的服务条款与反爬策略不受本项目控制，请保持合理调用频率，生产环境依靠缓存命中率与限流设计控制风险。
+## 数据留存说明
+服务进程只在内存中缓存查询词与搜索结果（TTL 到期即弃，进程重启即清零），不落盘、无第三方统计与遥测组件。搜索引擎调用会把查询词转发给相应的搜索引擎（百度、必应、搜狗等），其各自的隐私政策不在本项目控制范围；极会员鉴权仅向 eogee.com 网关回源校验密钥有效性，不做其他数据外传。HTTP 访问日志由 Nginx 等前置网关按运维侧策略管理。