@eogee-tech/eosearch 0.0.0-stage → 0.2.0

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,208 @@
-# Temporary Holding Version
+# EoSearch
 
-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.
+本地优先、透明可验证的 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 等前置网关按运维侧策略管理。

package/build-cli/cli.js

@@ -0,0 +1,584 @@
+#!/usr/bin/env node
+// cli/cli.ts — EoSearch 命令行客户端入口（npm 包 @eogee-tech/eosearch）
+// 薄客户端：本地只做参数解析与输出格式化，搜索与抓取全部在 eogee.com 服务端执行
+// 退出码：0 成功；1 业务空结果；2 用法错误；3 鉴权失败；4 配额限流；5 服务不可用/执行失败
+import { createRequire } from 'node:module';
+import { resolveConfig, configFilePath, DEFAULT_SERVER_URL } from './config.js';
+import { callTool, whoami } from './client.js';
+function readVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        return require('../package.json').version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+// ---------- 用法文本 ----------
+const MAIN_HELP = `eosearch — EoSearch 联网搜索命令行客户端（v${readVersion()}）
+
+本地只做参数解析与结果展示，搜索与抓取在服务端执行；需要极会员密钥。
+
+用法: eosearch <子命令> [参数] [选项]
+
+子命令:
+  search <query>       联网搜索：意图路由 + 多引擎融合评分
+  batch <q1> <q2> ...  并行执行 1-5 条独立搜索（配额计 1 次）
+  fetch <url>          抓取网页正文（自动适配 CSDN/掘金/知乎/GitHub）
+  deep <query>         深度调研：搜索 + 选源 + 抓正文 + 摘录
+  whoami               验证密钥与服务连接
+  help [子命令]        显示帮助
+
+通用选项:
+  --json               机器可读 JSON 输出（stdout，字段与 MCP 工具一致）
+  --server-url <url>   覆盖服务地址（默认 ${DEFAULT_SERVER_URL}）
+  --timeout <秒>       单次调用超时（默认 120）
+  --version, -V        显示 CLI 版本
+  --help, -h           显示帮助
+
+密钥配置（环境变量优先，二选一）:
+  环境变量  EOSEARCH_API_KEY=<你的极会员密钥>
+  配置文件  ${configFilePath()} 写入 {"apiKey":"你的极会员密钥","serverUrl":"可选服务地址"}
+
+安全约定：密钥只从环境变量或配置文件读取，不提供命令行参数入口，避免进入 Shell 历史与进程列表。
+
+示例:
+  eosearch search "llama.cpp 新版本" --json --limit 5
+  eosearch deep "2026 国产大模型对比" --top-n 3 --timeout 300
+  eosearch batch "量子计算现状" "相关ETF" --json
+  eosearch fetch https://github.com/ggml-org/llama.cpp
+  eosearch whoami`;
+function subcommandHelp(command) {
+    const shared = `通用选项: --json 机器可读输出 | --server-url <url> 覆盖服务地址 | --timeout <秒> 单次超时（默认 120）
+
+密钥: 环境变量 EOSEARCH_API_KEY，或配置文件 ${configFilePath()} 的 {"apiKey":"..."} 字段`;
+    switch (command) {
+        case 'search':
+            return `eosearch search — 联网搜索：意图路由 + 多引擎融合评分
+
+用法: eosearch search <query> [选项]
+
+选项:
+  --limit <1-50>            返回条数上限（默认 10）
+  --engines <a,b,...>       指定引擎列表，绕过意图路由（如 bing,baidu,bilibili）
+  --zone <auto|cn|intl>     路由偏好：cn 偏中文引擎，intl 偏国际引擎（默认 auto）
+  --search-mode <模式>      request|auto|playwright（Bing 异常时用 playwright 重试）
+  --freshness <窗口>        day|week|month|year，只保留该时间窗内发布的结果
+  --include-domains <a,b>   只保留这些域名（含子域）的结果
+  --exclude-domains <a,b>   丢弃这些域名（含子域）的结果
+  --json                    输出服务端 JSON（字段含 score/engines/reasons）
+
+${shared}
+
+示例: eosearch search "llama.cpp 新版本" --freshness month --json --limit 5`;
+        case 'batch':
+            return `eosearch batch — 并行执行 1-5 条独立搜索，配额计 1 次
+
+用法: eosearch batch <query1> <query2> ... [选项]
+
+选项:
+  --zone <auto|cn|intl>     共享路由偏好，应用到未单独指定的查询
+  --json                    输出服务端 JSON（results 数组 + failures 数组）
+
+${shared}
+
+示例: eosearch batch "量子计算现状" "相关ETF" "IBM 股价" --json`;
+        case 'fetch':
+            return `eosearch fetch — 抓取网页并返回清洗后的正文
+
+用法: eosearch fetch <url> [选项]
+
+选项:
+  --max-chars <500-200000>  返回正文长度上限（默认 20000）
+  --no-readability          关闭正文主内容抽取（默认开启）
+  --render-mode <模式>      request|auto|browser（auto 需服务端装有 Playwright）
+  --json                    输出 {"url":"...","content":"..."} 结构
+
+${shared}
+
+示例: eosearch fetch https://github.com/ggml-org/llama.cpp --max-chars 8000`;
+        case 'deep':
+            return `eosearch deep — 深度调研：搜索、选源、抓正文、按 token 预算输出摘录
+
+用法: eosearch deep <query> [选项]
+
+选项:
+  --top-n <1-10>            实际读取的来源数（默认 5）
+  --token-budget <数值>     摘录 token 预算，2000-120000（默认 24000）
+  --engines <a,b,...>       指定引擎列表
+  --zone <auto|cn|intl>     路由偏好
+  --freshness <窗口>        day|week|month|year
+  --include-domains <a,b>   只保留这些域名
+  --exclude-domains <a,b>   丢弃这些域名
+  --json                    额外返回结构化 sources 数组（url/score/adapter）
+
+${shared}
+
+示例: eosearch deep "2026 国产大模型对比" --top-n 3 --timeout 300`;
+        case 'whoami':
+            return `eosearch whoami — 验证密钥与服务连接（握手不计配额）
+
+用法: eosearch whoami [选项]
+
+输出密钥有效性、服务端名称与版本、密钥来源。
+退出码: 0 密钥有效；3 密钥被拒；4 限流；5 服务不可达。
+
+${shared}
+
+示例: eosearch whoami`;
+        default:
+            return null;
+    }
+}
+const SPECS = {
+    search: {
+        valueFlags: ['limit', 'engines', 'zone', 'search-mode', 'freshness', 'include-domains', 'exclude-domains', 'server-url', 'timeout'],
+        boolFlags: ['json'],
+        minPos: 1,
+        maxPos: 1
+    },
+    batch: {
+        valueFlags: ['zone', 'server-url', 'timeout'],
+        boolFlags: ['json'],
+        minPos: 1,
+        maxPos: 5
+    },
+    fetch: {
+        valueFlags: ['max-chars', 'render-mode', 'server-url', 'timeout'],
+        boolFlags: ['json', 'no-readability'],
+        minPos: 1,
+        maxPos: 1
+    },
+    deep: {
+        valueFlags: ['top-n', 'token-budget', 'engines', 'zone', 'freshness', 'include-domains', 'exclude-domains', 'server-url', 'timeout'],
+        boolFlags: ['json'],
+        minPos: 1,
+        maxPos: 1
+    },
+    whoami: {
+        valueFlags: ['server-url', 'timeout'],
+        boolFlags: ['json'],
+        minPos: 0,
+        maxPos: 0
+    },
+    help: {
+        valueFlags: [],
+        boolFlags: [],
+        minPos: 0,
+        maxPos: 1
+    }
+};
+class UsageError extends Error {
+}
+function parseArgs(argv) {
+    if (argv.length === 0)
+        return { kind: 'ok', command: 'help', positional: [], flags: new Map() };
+    const first = argv[0];
+    if (first === 'help' || first === '--help' || first === '-h') {
+        return { kind: 'ok', command: 'help', positional: argv.slice(1), flags: new Map() };
+    }
+    if (first.startsWith('-')) {
+        return { kind: 'usage', message: `未知参数 "${first}"。先写子命令，如 eosearch search <query>；eosearch help 查看全部子命令` };
+    }
+    if (!(first in SPECS)) {
+        return { kind: 'usage', message: `未知子命令 "${first}"。eosearch help 查看全部子命令` };
+    }
+    const command = first;
+    const spec = SPECS[command];
+    const rest = argv.slice(1);
+    const flags = new Map();
+    const positional = [];
+    for (let i = 0; i < rest.length; i++) {
+        const tok = rest[i];
+        if (tok === '--') {
+            positional.push(...rest.slice(i + 1));
+            break;
+        }
+        if (tok.startsWith('--')) {
+            const eq = tok.indexOf('=');
+            if (eq >= 0) {
+                flags.set(tok.slice(2, eq), tok.slice(eq + 1));
+                continue;
+            }
+            const key = tok.slice(2);
+            const next = rest[i + 1];
+            if (spec.valueFlags.includes(key) && next !== undefined && !next.startsWith('--')) {
+                flags.set(key, next);
+                i++;
+            }
+            else {
+                flags.set(key, true);
+            }
+            continue;
+        }
+        if (tok.startsWith('-') && tok.length === 2) {
+            flags.set(tok.slice(1), true);
+            continue;
+        }
+        positional.push(tok);
+    }
+    for (const key of flags.keys()) {
+        if (!spec.valueFlags.includes(key) && !spec.boolFlags.includes(key) && !['help', 'h', 'version', 'V'].includes(key)) {
+            return {
+                kind: 'usage',
+                message: `子命令 ${command} 不支持选项 --${key}。eosearch ${command} --help 查看支持的选项`
+            };
+        }
+    }
+    if (positional.length < spec.minPos) {
+        return { kind: 'usage', message: `${command} 缺少必填参数。eosearch ${command} --help 查看用法` };
+    }
+    if (positional.length > spec.maxPos) {
+        const hint = command === 'batch' ? `batch 一次最多 ${spec.maxPos} 条查询` : `${command} 只接受 ${spec.maxPos} 个位置参数`;
+        return { kind: 'usage', message: `${hint}，收到 ${positional.length} 个。eosearch ${command} --help 查看用法` };
+    }
+    return { kind: 'ok', command, positional, flags };
+}
+// ---------- 选项读取与校验 ----------
+function rawFlag(flags, key) {
+    const value = flags.get(key);
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function intFlag(flags, key, min, max) {
+    const raw = rawFlag(flags, key);
+    if (raw === null)
+        return null;
+    if (!/^\d+$/.test(raw)) {
+        throw new UsageError(`--${key} 需要 ${min}-${max} 的整数，收到 "${raw}"`);
+    }
+    const n = parseInt(raw, 10);
+    if (n < min || n > max) {
+        throw new UsageError(`--${key} 需要在 ${min}-${max} 之间，收到 ${n}`);
+    }
+    return n;
+}
+function enumFlag(flags, key, allowed) {
+    const raw = rawFlag(flags, key);
+    if (raw === null)
+        return null;
+    if (!allowed.includes(raw)) {
+        throw new UsageError(`--${key} 只支持 ${allowed.join('|')}，收到 "${raw}"`);
+    }
+    return raw;
+}
+function commaList(flags, key) {
+    const raw = rawFlag(flags, key);
+    if (raw === null)
+        return null;
+    const list = raw.split(',').map((s) => s.trim()).filter(Boolean);
+    if (list.length === 0) {
+        throw new UsageError(`--${key} 需要逗号分隔的列表，如 a.com,b.com`);
+    }
+    return list;
+}
+function timeoutMsOf(flags) {
+    const seconds = intFlag(flags, 'timeout', 1, 600);
+    return (seconds ?? 120) * 1000;
+}
+// ---------- 输出与退出 ----------
+function emitFailure(f) {
+    console.error(`错误：${f.problem}`);
+    console.error(`原因：${f.cause}`);
+    console.error(`下一步：${f.next}`);
+}
+function emitUsage(message) {
+    console.error(`错误：${message}`);
+    process.exit(2);
+}
+function missingKeyFailure() {
+    return {
+        kind: 'failure',
+        exitCode: 3,
+        problem: '未找到 EoSearch API 密钥',
+        cause: `环境变量 EOSEARCH_API_KEY 未设置，配置文件 ${configFilePath()} 中也没有 apiKey 字段`,
+        next: '设置环境变量 export EOSEARCH_API_KEY=<你的极会员密钥>，或在 ~/.eosearchrc 写入 {"apiKey":"..."}；密钥在 eogee.com 个人中心获取'
+    };
+}
+async function callAndExit(opts) {
+    const outcome = await callTool({
+        serverUrl: opts.config.serverUrl,
+        apiKey: opts.config.apiKey,
+        clientVersion: readVersion(),
+        toolName: opts.toolName,
+        toolArgs: opts.toolArgs,
+        timeoutMs: opts.timeoutMs
+    });
+    if (outcome.kind === 'failure') {
+        emitFailure(outcome);
+        process.exit(outcome.exitCode);
+    }
+    if (opts.json) {
+        process.stdout.write(outcome.text + '\n');
+        let parsed = null;
+        try {
+            parsed = JSON.parse(outcome.text);
+        }
+        catch {
+            parsed = null;
+        }
+        if (parsed !== null) {
+            const empty = opts.emptyCheck(parsed);
+            if (empty) {
+                emitFailure(empty);
+                process.exit(empty.exitCode);
+            }
+        }
+        process.exit(0);
+    }
+    process.stdout.write(outcome.text + '\n');
+    process.exit(0);
+}
+// ---------- 子命令实现 ----------
+async function runSearch(config, positional, flags) {
+    const toolArgs = {
+        query: positional[0],
+        format: flags.get('json') === true ? 'json' : 'markdown'
+    };
+    const limit = intFlag(flags, 'limit', 1, 50);
+    if (limit !== null)
+        toolArgs.limit = limit;
+    const engines = commaList(flags, 'engines');
+    if (engines)
+        toolArgs.engines = engines;
+    const zone = enumFlag(flags, 'zone', ['auto', 'cn', 'intl']);
+    if (zone)
+        toolArgs.zone = zone;
+    const searchMode = enumFlag(flags, 'search-mode', ['request', 'auto', 'playwright']);
+    if (searchMode)
+        toolArgs.searchMode = searchMode;
+    const freshness = enumFlag(flags, 'freshness', ['day', 'week', 'month', 'year']);
+    if (freshness)
+        toolArgs.freshness = freshness;
+    const includeDomains = commaList(flags, 'include-domains');
+    if (includeDomains)
+        toolArgs.includeDomains = includeDomains;
+    const excludeDomains = commaList(flags, 'exclude-domains');
+    if (excludeDomains)
+        toolArgs.excludeDomains = excludeDomains;
+    return callAndExit({
+        config,
+        toolName: 'eosearch_search',
+        toolArgs,
+        timeoutMs: timeoutMsOf(flags),
+        json: flags.get('json') === true,
+        emptyCheck: (parsed) => {
+            const obj = parsed;
+            if (Array.isArray(obj.results) && obj.results.length === 0) {
+                return {
+                    kind: 'failure',
+                    exitCode: 1,
+                    problem: '搜索无结果',
+                    cause: '服务端多引擎融合后返回 0 条结果',
+                    next: '放宽 --freshness、更换更具体的关键词，或用 --engines 指定引擎重试'
+                };
+            }
+            return null;
+        }
+    });
+}
+async function runBatch(config, positional, flags) {
+    const toolArgs = {
+        queries: positional,
+        format: flags.get('json') === true ? 'json' : 'markdown'
+    };
+    const zone = enumFlag(flags, 'zone', ['auto', 'cn', 'intl']);
+    if (zone)
+        toolArgs.zone = zone;
+    return callAndExit({
+        config,
+        toolName: 'eosearch_batch_search',
+        toolArgs,
+        timeoutMs: timeoutMsOf(flags),
+        json: flags.get('json') === true,
+        emptyCheck: (parsed) => {
+            const obj = parsed;
+            if (typeof obj.failed === 'number' && obj.failed > 0 && obj.failed < (obj.totalQueries ?? 0)) {
+                console.error(`提示：${obj.failed} 条查询失败，详见输出中 failures 字段`);
+                return null;
+            }
+            if (typeof obj.totalQueries === 'number' && typeof obj.failed === 'number' && obj.totalQueries > 0 && obj.failed === obj.totalQueries) {
+                return {
+                    kind: 'failure',
+                    exitCode: 1,
+                    problem: `全部 ${obj.totalQueries} 条查询都失败`,
+                    cause: '服务端执行批量搜索时每条查询都未返回结果',
+                    next: '检查查询词是否过偏，减少条数或更换关键词后重试'
+                };
+            }
+            return null;
+        }
+    });
+}
+async function runFetch(config, positional, flags) {
+    const url = positional[0];
+    if (!/^https?:\/\//i.test(url)) {
+        emitUsage(`fetch 需要 http(s) 网址，收到 "${url}"`);
+    }
+    const toolArgs = { url };
+    const maxChars = intFlag(flags, 'max-chars', 500, 200000);
+    if (maxChars !== null)
+        toolArgs.maxChars = maxChars;
+    if (flags.get('no-readability') === true)
+        toolArgs.readability = false;
+    const renderMode = enumFlag(flags, 'render-mode', ['request', 'auto', 'browser']);
+    if (renderMode)
+        toolArgs.renderMode = renderMode;
+    const json = flags.get('json') === true;
+    if (!json) {
+        return callAndExit({
+            config,
+            toolName: 'eosearch_fetch',
+            toolArgs,
+            timeoutMs: timeoutMsOf(flags),
+            json: false,
+            emptyCheck: () => null
+        });
+    }
+    // fetch 的 --json：工具返回纯文本（首行元信息 + 正文），包装为结构化输出
+    const outcome = await callTool({
+        serverUrl: config.serverUrl,
+        apiKey: config.apiKey,
+        clientVersion: readVersion(),
+        toolName: 'eosearch_fetch',
+        toolArgs,
+        timeoutMs: timeoutMsOf(flags)
+    });
+    if (outcome.kind === 'failure') {
+        emitFailure(outcome);
+        process.exit(outcome.exitCode);
+    }
+    const firstLine = (outcome.text.split('\n', 1)[0] ?? '').trim();
+    const match = /^URL: (\S+)$/.exec(firstLine);
+    const payload = JSON.stringify({ url: match ? match[1] : url, content: outcome.text }, null, 2);
+    process.stdout.write(payload + '\n');
+    process.exit(0);
+}
+async function runDeep(config, positional, flags) {
+    const toolArgs = {
+        query: positional[0],
+        format: flags.get('json') === true ? 'json' : 'text'
+    };
+    const topN = intFlag(flags, 'top-n', 1, 10);
+    if (topN !== null)
+        toolArgs.topN = topN;
+    const tokenBudget = intFlag(flags, 'token-budget', 2000, 120000);
+    if (tokenBudget !== null)
+        toolArgs.tokenBudget = tokenBudget;
+    const engines = commaList(flags, 'engines');
+    if (engines)
+        toolArgs.engines = engines;
+    const zone = enumFlag(flags, 'zone', ['auto', 'cn', 'intl']);
+    if (zone)
+        toolArgs.zone = zone;
+    const freshness = enumFlag(flags, 'freshness', ['day', 'week', 'month', 'year']);
+    if (freshness)
+        toolArgs.freshness = freshness;
+    const includeDomains = commaList(flags, 'include-domains');
+    if (includeDomains)
+        toolArgs.includeDomains = includeDomains;
+    const excludeDomains = commaList(flags, 'exclude-domains');
+    if (excludeDomains)
+        toolArgs.excludeDomains = excludeDomains;
+    return callAndExit({
+        config,
+        toolName: 'eosearch_deep_search',
+        toolArgs,
+        timeoutMs: timeoutMsOf(flags),
+        json: flags.get('json') === true,
+        emptyCheck: () => null
+    });
+}
+async function runWhoami(flags) {
+    const config = resolveConfig({ serverUrl: rawFlag(flags, 'server-url') });
+    if (!config.apiKey) {
+        const f = missingKeyFailure();
+        emitFailure(f);
+        process.exit(f.exitCode);
+    }
+    const result = await whoami({
+        serverUrl: config.serverUrl,
+        apiKey: config.apiKey,
+        clientVersion: readVersion()
+    });
+    if ('kind' in result && result.kind === 'failure') {
+        const f = result;
+        emitFailure(f);
+        process.exit(f.exitCode);
+    }
+    const info = result;
+    if (flags.get('json') === true) {
+        process.stdout.write(JSON.stringify({
+            ok: true,
+            server: { name: info.serverName ?? null, version: info.serverVersion ?? null },
+            serverUrl: config.serverUrl,
+            apiKeySource: config.apiKeySource,
+            instructions: info.instructions ?? null
+        }, null, 2) + '\n');
+        process.exit(0);
+    }
+    console.log(`密钥有效，服务连接正常（密钥来自${config.apiKeySource === 'environment' ? '环境变量' : '配置文件 ~/.eosearchrc'}）`);
+    console.log(`服务端：${info.serverName ?? 'eosearch'} ${info.serverVersion ?? ''}`.trimEnd());
+    console.log(`地址：${config.serverUrl}`);
+    process.exit(0);
+}
+// ---------- 主入口 ----------
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--version') || argv.includes('-V')) {
+        console.log(readVersion());
+        process.exit(0);
+    }
+    const parsed = parseArgs(argv);
+    if (parsed.kind === 'usage')
+        emitUsage(parsed.message);
+    const { command, positional, flags } = parsed;
+    if (command === 'help' || flags.get('help') === true || flags.get('h') === true) {
+        if (command === 'help' && positional.length > 0) {
+            const sub = subcommandHelp(positional[0]);
+            if (sub === null)
+                emitUsage(`未知子命令 "${positional[0]}"。eosearch help 查看全部子命令`);
+            console.log(sub);
+        }
+        else {
+            console.log(MAIN_HELP);
+        }
+        process.exit(0);
+    }
+    const config = resolveConfig({ serverUrl: rawFlag(flags, 'server-url') });
+    const needsKey = command !== 'help';
+    if (needsKey && !config.apiKey) {
+        const f = missingKeyFailure();
+        emitFailure(f);
+        process.exit(f.exitCode);
+    }
+    try {
+        switch (command) {
+            case 'search':
+                return await runSearch(config, positional, flags);
+            case 'batch':
+                return await runBatch(config, positional, flags);
+            case 'fetch':
+                return await runFetch(config, positional, flags);
+            case 'deep':
+                return await runDeep(config, positional, flags);
+            case 'whoami':
+                return await runWhoami(flags);
+            default:
+                emitUsage(`未知子命令 "${command}"。eosearch help 查看全部子命令`);
+        }
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            emitUsage(error.message);
+        console.error('错误：CLI 内部异常');
+        console.error(`原因：${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+        console.error('下一步：重试一次；持续出现请带上上面的堆栈反馈');
+        process.exit(5);
+    }
+}
+main().catch((error) => {
+    console.error('错误：CLI 未捕获异常');
+    console.error(`原因：${error instanceof Error ? error.message : String(error)}`);
+    console.error('下一步：重试一次；持续出现请带上该信息反馈');
+    process.exit(5);
+});

package/build-cli/client.js

@@ -0,0 +1,115 @@
+// cli/client.ts — 通过 MCP Streamable HTTP 调用 eosearch 服务端
+// 每次进程：initialize 握手（不计费）→ tools/call（计费 1 次）→ 关闭会话
+// 薄客户端边界：只封装 HTTP 调用，不含任何搜索/抓取逻辑
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+function failure(exitCode, problem, cause, next) {
+    return { kind: 'failure', exitCode, problem, cause, next };
+}
+function serverMessage(message) {
+    const match = /"message"\s*:\s*"([^"]+)"/.exec(message);
+    return match ? match[1] : null;
+}
+function probe(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const httpMatch = /HTTP (\d{3})/.exec(message);
+    if (httpMatch)
+        return { status: parseInt(httpMatch[1], 10), message };
+    // 服务端 deny() 约定：-32001 = 401（鉴权拒绝），-32002 = 429（配额限流）；
+    // SDK 抛错时可能只带 JSON body（McpError code 或文本），按约定码还原 HTTP 状态
+    const rpcCode = error?.code;
+    if (rpcCode === -32001)
+        return { status: 401, message };
+    if (rpcCode === -32002)
+        return { status: 429, message };
+    if (/"code"\s*:\s*-32001/.test(message))
+        return { status: 401, message };
+    if (/"code"\s*:\s*-32002/.test(message))
+        return { status: 429, message };
+    return { status: null, message };
+}
+function isNetworkError(message) {
+    return /ENOTFOUND|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN|fetch failed|socket hang up/i.test(message);
+}
+function isTimeoutError(message) {
+    return /timed?\s*out|timeout|aborted/i.test(message);
+}
+function connectFailure(error, serverUrl) {
+    const { status, message } = probe(error);
+    if (status === 401) {
+        const detail = serverMessage(message) ? `（服务端：${serverMessage(message)}）` : '';
+        return failure(3, '服务端拒绝了这把密钥（HTTP 401）', `向 ${serverUrl} 握手时返回 401，密钥无效或请求未携带${detail}`, '到 eogee.com 个人中心核对密钥（注意无多余空格），修正 EOSEARCH_API_KEY 或 ~/.eosearchrc 后重试 eosearch whoami');
+    }
+    if (status === 429) {
+        const detail = serverMessage(message) ?? 'rate limit';
+        return failure(4, '触发限流（HTTP 429）', detail, '等待数十秒后重试；每分钟限速与每日配额档位见 eogee.com 个人中心');
+    }
+    if (status === 404) {
+        return failure(5, '服务地址不存在（HTTP 404）', `${serverUrl} 未找到`, '确认服务地址是否为 https://eogee.com/search/v1/mcp，或用 --server-url 指定正确地址');
+    }
+    if (isNetworkError(message)) {
+        return failure(5, '无法连接服务端', message, '检查本机网络与代理设置；若怀疑服务端故障，稍后用 eosearch whoami 探测恢复情况');
+    }
+    if (status !== null && status >= 500) {
+        return failure(5, `服务端错误（HTTP ${status}）`, message, '服务端临时故障，稍后重试');
+    }
+    return failure(5, '与服务端通信失败', message, '检查 --server-url 与网络环境后重试');
+}
+async function withClient(serverUrl, apiKey, clientVersion, fn) {
+    const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
+        requestInit: { headers: { 'X-API-Key': apiKey } }
+    });
+    const client = new Client({ name: 'eosearch-cli', version: clientVersion }, { capabilities: {} });
+    try {
+        await client.connect(transport);
+    }
+    catch (error) {
+        try {
+            await client.close();
+        }
+        catch { /* 关闭失败不影响错误分类 */ }
+        return { fail: connectFailure(error, serverUrl) };
+    }
+    try {
+        return { result: await fn(client) };
+    }
+    catch (error) {
+        const { message } = probe(error);
+        if (isTimeoutError(message)) {
+            return {
+                fail: failure(5, '调用超时', message, '加大 --timeout（秒，默认 120）后重试；deep 与 batch 任务较慢时建议 --timeout 300')
+            };
+        }
+        return { fail: connectFailure(error, serverUrl) };
+    }
+    finally {
+        try {
+            await client.close();
+        }
+        catch { /* 忽略关闭错误 */ }
+    }
+}
+export async function callTool(args) {
+    const outcome = await withClient(args.serverUrl, args.apiKey, args.clientVersion, async (client) => client.callTool({ name: args.toolName, arguments: args.toolArgs }, undefined, { timeout: args.timeoutMs }));
+    if ('fail' in outcome)
+        return outcome.fail;
+    const result = outcome.result;
+    const text = (result.content ?? [])
+        .filter((c) => c.type === 'text' && typeof c.text === 'string')
+        .map((c) => c.text)
+        .join('\n');
+    if (result.isError) {
+        return failure(5, '服务端执行工具失败', text || '工具返回 isError 但无错误详情', '按错误信息调整参数重试；若持续失败，用 eosearch whoami 确认服务状态');
+    }
+    return { kind: 'success', text };
+}
+export async function whoami(args) {
+    const outcome = await withClient(args.serverUrl, args.apiKey, args.clientVersion, async (client) => ({
+        serverName: client.getServerVersion()?.name,
+        serverVersion: client.getServerVersion()?.version,
+        instructions: client.getInstructions()
+    }));
+    if ('fail' in outcome)
+        return outcome.fail;
+    return outcome.result;
+}

package/build-cli/config.js

@@ -0,0 +1,33 @@
+// cli/config.ts — 密钥与服务地址解析
+// 优先级（高到低）：环境变量 > 用户级配置文件 ~/.eosearchrc
+// 安全约定：密钥不提供命令行参数入口，避免进入 Shell 历史与进程列表
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
+export const DEFAULT_SERVER_URL = 'https://eogee.com/search/v1/mcp';
+export function configFilePath() {
+    return join(homedir(), '.eosearchrc');
+}
+function readRc() {
+    try {
+        const parsed = JSON.parse(readFileSync(configFilePath(), 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function asTrimmedString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+export function resolveConfig(overrides) {
+    const rc = readRc();
+    const envKey = asTrimmedString(process.env.EOSEARCH_API_KEY);
+    const rcKey = asTrimmedString(rc.apiKey);
+    const envUrl = asTrimmedString(process.env.EOSEARCH_SERVER_URL);
+    const rcUrl = asTrimmedString(rc.serverUrl);
+    const apiKey = envKey ?? rcKey;
+    const apiKeySource = envKey ? 'environment' : rcKey ? 'config-file' : 'none';
+    const serverUrl = overrides.serverUrl ?? envUrl ?? rcUrl ?? DEFAULT_SERVER_URL;
+    return { apiKey, apiKeySource, serverUrl };
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@eogee-tech/eosearch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "EoSearch command-line client for AI agents — web search, page fetch and deep research via eogee.com (thin client; engines run server-side)",
+  "type": "module",
+  "bin": {
+    "eosearch": "build-cli/cli.js"
+  },
+  "files": [
+    "build-cli",
+    "NOTICE",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:cli": "tsc -p tsconfig.cli.json",
+    "prepublishOnly": "npm run build:cli",
+    "watch": "tsc --watch",
+    "start": "node build/index.js",
+    "inspector": "npx @modelcontextprotocol/inspector build/index.js",
+    "smoke": "node build/eosearch/smoke.js",
+    "test": "npm run build && node --test \"test/unit/*.test.mjs\""
+  },
+  "keywords": [
+    "mcp",
+    "cli",
+    "search",
+    "web-search",
+    "agent",
+    "rag"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.2",
+    "@mozilla/readability": "^0.6.0",
+    "@types/cheerio": "^0.22.35",
+    "axios": "^1.16.0",
+    "cheerio": "^1.0.0",
+    "cors": "^2.8.5",
+    "express": "^5.2.1",
+    "https-proxy-agent": "^7.0.6",
+    "ipaddr.js": "^2.3.0",
+    "jsdom": "^26.1.0",
+    "koffi": "^2.16.0",
+    "request-filtering-agent": "^3.2.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^20.17.10",
+    "typescript": "^5.3.3"
+  },
+  "main": "index.js",
+  "directories": {
+    "test": "test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@gitee.com:eogee/eosearch.git"
+  },
+  "author": ""
+}