@eogee-tech/eosearch 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Open-WebSearch MCP Server Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,37 @@
+eosearch
+Copyright 2026 eosearch contributors
+
+This product includes software developed as part of the Open-WebSearch project.
+
+Open-WebSearch MCP Server
+Copyright 2025 Open-WebSearch MCP Server Contributors
+https://github.com/Aas-ee/open-webSearch
+Licensed under the Apache License, Version 2.0
+
+Derivative portions of this product (the search engine adapters and network
+utility layer, located under src/engines/, src/utils/, src/core/, src/types/,
+src/config.ts, src/types.ts and src/runtime/) are derived from Open-WebSearch
+and remain licensed under the Apache License, Version 2.0, with the exception
+of the eogee vertical engine adapter (src/engines/eogee/) and the bilibili
+vertical engine adapter (src/engines/bilibili/), which are original eosearch
+code (connecting to the eogee.com knowledge-base gateway and to the Bilibili
+on-site search API, respectively) and are not derived from Open-WebSearch.
+
+Modifications made by eosearch contributors include: wiring the Zhihu engine
+and Zhihu article fetcher into the runtime, replacing the original entrypoint
+and MCP tool layer with the eosearch aggregation pipeline (intent routing,
+fusion ranking, TTL caching, circuit-breaker health monitoring, deep search
+and the eosearch tool set), adding native freshness (time-range) parameters
+to the Baidu, Sogou, DuckDuckGo and Hacker News engine adapters together with
+the corresponding shared search execution context field, extending the shared
+web content extractor (src/engines/web/fetchWebContent.ts) so that same-type
+container candidates are concatenated for list-style pages instead of taking
+the first match and a much-shorter Readability result no longer overrides a
+longer built-in extraction, registering a new bilibili vertical search engine
+in the supported engine list (src/core/search/searchEngines.ts), and unwrapping
+Baidu/Sogou redirect-wrapped result links in the aggregation pipeline, and
+related refactoring.
+
+The eosearch aggregation layer (src/eosearch/, src/tools/, src/index.ts) is
+Copyright 2026 eosearch contributors and is likewise licensed under the
+Apache License, Version 2.0.

package/README.md

@@ -1,3 +1,210 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 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 等前置网关按运维侧策略管理。