dsh-search-enhance 0.1.4 → 0.1.6

package/README.md

@@ -1,221 +1,101 @@
-# dsh-search-enhance
+# Search Enhance for DeepSeek Harness
 
-`dsh-search-enhance` 是 DeepSeek Harness（DSH）的增强搜索插件。它使用 Grok 完成主搜索，并按需要补充文档、网页和站点信息，最后返回回答和来源链接。
+English | [简体中文](README.zh.md)
 
-## 架构与搜索流程
+`dsh-search-enhance` is a search extension for DeepSeek Harness. It uses a Grok-compatible Search API for primary web answers and can optionally use Context7, Exa, Tavily, and Firecrawl for documentation lookup, supplementary discovery, page extraction, and site mapping.
 
-### 整体架构
+The plugin handles search, source retention, and page retrieval as separate steps. `web_search` and `docs_search` return an answer or documentation snippets with visible sources; the complete source record can be stored under a `source_ref` and paged later. Important pages can then be retrieved with `web_extract`, so search snippets remain distinct from fetched page content.
 
-```text
-用户问题
-  │
-  ▼
-DSH Agent
-  │
-  └─ 固定模型工具 surface（schema 与顺序不随披露状态变化）
-      ├─ web_search ──────> Grok 主搜索
-      │                      ├─ 按需要补充 Context7 / Exa
-      │                      ├─ 按需要补充 Tavily / Firecrawl
-      │                      └─ 返回回答、来源；有 source_ref 时追加 search_sources manifest
-      │
-      ├─ docs_search ─────> Context7 / Exa 文档检索
-      │                      └─ 返回文档片段、来源；有 source_ref 时追加 search_sources manifest
-      │
-      ├─ web_extract ─────> Tavily → Firecrawl → smart_direct → direct
-      │                      └─ 读取选中网页的正文
-      │
-      ├─ search_tools ────> 按需返回 capability / operation manifest
-      │
-      └─ search_call ─────> 调用已经激活的延迟 operation
-                             ├─ Context7 精细查询
-                             ├─ 完整来源分页
-                             ├─ 站点页面发现
-                             ├─ 研究计划
-                             └─ 配置诊断
-```
-
-插件继续使用 DSH 原有的 `web_search` 名称，不会再增加第二个普通搜索入口。在本来可以使用 `web_search` 的 Agent 中，插件提供增强后的搜索；如果某个 Agent 已经禁用网页搜索，插件不会强行重新开启。
-
-普通搜索以 Grok 为主。其他服务只负责补充文档、来源或网页内容，不会替代 Grok 的主搜索位置。
-
-### 固定模型工具 surface
-
-默认使用 `progressive`。在 DSH 未另行限制的 Agent 中，插件在初始步骤和后续步骤提供的五个固定搜索入口（Native tool / Code Mode SDK）是：
-
-| 工具 | 调用方式与用途 |
-| --- | --- |
-| `web_search` | 直接调用。使用 Grok 生成通用搜索的主要回答，并按搜索类型补充其他来源 |
-| `docs_search` | 直接调用。检索库、框架、SDK、API 和源码仓库文档 |
-| `web_extract` | 直接调用。读取指定网页正文，用于核对搜索摘要中的重要内容 |
-| `search_tools` | 直接调用。按需返回延迟能力的 operation manifest，不注册新的模型工具 |
-| `search_call` | 固定网关。通过 `search_call({ operation, arguments })` 调用已经激活的延迟 operation |
+> Bring your own endpoints and credentials. The plugin ships no API keys. A Grok-compatible endpoint is required for `web_search`; Context7, Exa, Tavily, and Firecrawl are optional.
 
-这里的“延迟”指 operation 是否处于 active 状态，而不是工具是否出现在列表中。延迟 operation 的参数 schema 通过工具结果中的 manifest 披露；输出 schema 只保存在内部 registry，用于校验规范执行结果，不会追加到模型历史，也不会作为独立工具加入模型 surface。
+![A DSH Web session that searches, checks documentation, extracts an official page, and returns a sourced answer](https://raw.githubusercontent.com/KKKneko/dsh-search-enhance/main/assets/search-workflow.png)
 
-### 渐进式披露
+## Key characteristics
 
-`search_tools` 一次可以选择一到五组能力：
+- `web_search` uses the Grok-compatible endpoint for the main answer, adds Exa for documentation-oriented queries, and uses Tavily or Firecrawl within the configured supplementary budget.
+- Sources are normalized, de-duplicated, and reordered using source category, requested version, and publication-time signals before they are shown.
+- `source_ref` keeps the complete source record in private durable storage, allowing the Agent to paginate beyond the links included in the initial result.
+- `docs_search` uses Context7 only with an explicit `library_name` or `library_id`; requests without a library identity use Exa discovery.
+- `web_extract` follows the fixed Tavily → Firecrawl → `smart_direct` → `direct` route and reports the retrieval route, evidence level, and available page metadata.
+- Source pagination, Context7 detail operations, site mapping, research planning, and diagnostics are disclosed on demand through `search_tools` and `search_call`.
+- Native Tool Mode and Code Mode use the same fixed tool surface and canonical outputs. DSH Settings, Credentials, Agent Presets, guards, and lifecycle cleanup continue to apply.
+- Optional Providers are skipped when unconfigured. Tavily and Firecrawl supplementary-search budgets default to `0`, and optional Provider failures remain visible in the result.
 
-| 能力组 | 按需返回 manifest 的 operation | 适用场景 |
-| --- | --- | --- |
-| `context7` | `context7_resolve_library_id`、`context7_query_docs`、`context7_get_library_docs`、`context7_get_cached_doc_raw` | 需要精确选择库版本或进一步读取 Context7 文档 |
-| `sources` | `search_sources` | 搜索结果中的来源较多，需要继续分页读取完整来源 |
-| `site_map` | `web_map` | 已知一个网站，需要继续发现该站点下的相关页面 |
-| `planning` | `research_plan` | 明确要求深度研究、多来源核对或复杂比较时先制定计划 |
-| `diagnostics` | `search_diagnostics` | 用户明确要求检查搜索配置或连接状态 |
+## Quick start
 
-披露与调用遵循以下规则：
+### 1. Install
 
-1. `search_tools` 返回所请求能力组的 operation manifest，其中包含真实的参数 schema 和 `search_call` 路由，但不包含内部输出 schema；它不会增加、删除或改写模型工具 schema。`search_call` 仍使用 registry 保存的输出 schema 校验规范结果。
-2. 在 `progressive` 模式下，新披露的能力组从下一模型 step 开始 active；同一步内提前调用会失败。激活范围属于当前 Agent，重复请求会再次返回同一 manifest，但不会创建第二套状态或入口。
-3. 在 `all` 模式下，唯一变化是所有延迟 operation 从一开始就 active；`search_tools` 仍按需返回 manifest。`all` 不会“显示全部 12 个工具”，两种模式的五个模型工具及其 schema 完全相同。
-4. 延迟 operation 只能通过 `search_call({ operation, arguments })` 调用，不能直接调用 `search_sources`、`web_map` 等名称；resident 的 `web_search`、`docs_search` 和 `web_extract` 仍然直接调用。
-5. `web_search` 或 `docs_search` 成功返回 `source_ref` 时，插件会自动激活 `sources`，并在结果中追加 `search_sources` manifest；在 `progressive` 模式下可从下一 step 通过 `search_call` 使用它。
-6. 固定 surface 仍受 DSH 原有 Preset、guard 和工具限制约束，插件不会绕过这些限制。
-
-这种固定网关设计保留了按需披露，同时避免插件因披露状态变化而改写发送给 DeepSeek 的 system 文本、tool schema/顺序或 Code Mode SDK 前缀，从而消除插件自身造成的前缀变化。
-
-### 一次完整搜索如何进行
-
-1. 通用问题直接调用 `web_search`，文档问题直接调用 `docs_search`。
-2. 当搜索产生来源时，结果会包含可见来源、`source_ref` 和追加的 `search_sources` manifest，同时自动激活 `sources`。
-3. 在下一 step 需要更多来源时，调用 `search_call({ operation: 'search_sources', arguments: { source_ref, offset: 0, limit: 20, format: 'compact' } })` 分页读取，而不是直接调用 `search_sources`。
-4. 对重要结论，选择权威链接并直接调用 `web_extract` 获取网页正文。
-5. 如果任务需要站点内发现、研究计划、精细 Context7 查询或连接检查，先调用例如 `search_tools({ capabilities: ['site_map'] })` 取得 manifest；`progressive` 模式从下一 step、`all` 模式立即通过 `search_call({ operation: 'web_map', arguments: { url: 'https://example.com' } })` 调用相应 operation。
-6. 最终回答综合主搜索、补充来源和已经读取的网页正文，并保留来源链接。
-
-`source_ref` 只是完整来源列表的引用，不等同于网页正文；重要事实仍应通过 `web_extract` 读取原页面后再下结论。
-
-## 安装
-
-确保 `dsh` 和 `pnpm` 已经可以使用，然后直接安装到默认的 `web` 配置：
+Install the published bundle into the DSH `web` profile:
 
 ```bash
 dsh plugin --profile web add dsh-search-enhance@latest
 ```
 
-安装完成后启动或重启 DSH：
+### 2. Start DSH Web
 
 ```bash
 dsh web
 ```
 
-如果 DSH 已经在运行，请重启后再对浏览器执行一次强制刷新。
-
-## 配置
+### 3. Configure search
 
-启动 DSH 后，打开：
+Open:
 
 ```text
-设置 → 插件 → 插件配置 → dsh-search-enhance
+Settings → Plugins → Plugin configuration → dsh-search-enhance
 ```
 
-第一次使用时，优先完成 Grok 搜索配置；其他选项可以先保持默认。
+Under **Grok search backend**, configure:
 
-### 1. 配置 Grok 搜索
+1. the xAI endpoint or an explicit Grok-compatible gateway;
+2. the matching `completions` or `responses` protocol;
+3. a model supported by that endpoint;
+4. the Grok credential in the card's Credentials section.
 
-至少确认以下三项：
+The default credential reference is `SEARCH_API_KEY`. Credential values are stored through DSH Credentials and are not exposed as model parameters.
 
-| 配置项 | 说明 |
-| --- | --- |
-| 接口地址 | xAI 官方地址或第三方 Grok 服务地址 |
-| 模型 | 该服务实际支持的 Grok 模型名称 |
-| Grok 密钥 | 在页面的“凭据”区域填写 |
+Save the settings, restart DSH, and ask a current-information question. A successful run shows a `Search` tool row, an answer, and source links.
 
-页面还可以选择请求协议、思考等级和超时时间。请求协议需要与所使用的服务保持一致：
+## Example requests
 
-- `completions`：使用聊天补全接口；
-- `responses`：使用 Responses 接口。
+Use normal language; the plugin gives the Agent routing guidance.
 
-默认的 Grok 密钥名称是 `SEARCH_API_KEY`。密钥值只填写在“凭据”区域，不要写进接口地址或普通配置项。
+- “Find the most important React 19 user-visible changes. Prefer official release notes and include source links.”
+- “Look up the current FastAPI JWT authentication API and show a minimal example from the official documentation.”
+- “Read and summarize `https://example.com/article`, separating what the page states from your inference.”
 
-### 2. 配置补充来源
+Ask explicitly when you need complete source pagination, site discovery, a research plan, or Provider diagnostics.
 
-这些服务不是完成主搜索的必要条件，可以按需要配置：
+## Providers
 
-| 服务 | 用途 | 默认密钥名称 |
-| --- | --- | --- |
-| Context7 | 查找库和框架文档 | `CONTEXT7_API_KEY` |
-| Exa | 补充文档和网页结果 | `EXA_API_KEY` |
-| Tavily | 补充搜索、读取网页和发现站点页面 | `TAVILY_API_KEY` |
-| Firecrawl | 补充搜索和读取网页 | `FIRECRAWL_API_KEY` |
+Configure only the routes you need.
 
-在“补充 Provider”中填写服务地址，在“凭据”中填写对应密钥。没有配置的服务会被跳过，不影响已经配置好的搜索来源。
+| Provider | Used for | Default credential reference | Required? |
+| --- | --- | --- | --- |
+| Grok-compatible Search API | Main `web_search` answer and sources | `SEARCH_API_KEY` | For `web_search` |
+| Context7 | Documentation lookup for an explicit library | `CONTEXT7_API_KEY` | No |
+| Exa | Broad documentation and supplementary discovery | `EXA_API_KEY` | No |
+| Tavily | Supplementary search, page extraction, and site mapping | `TAVILY_API_KEY` | No |
+| Firecrawl | Supplementary search and page extraction | `FIRECRAWL_API_KEY` | No |
 
-Tavily 和 Firecrawl 参与普通搜索的数量由“每次搜索的补充来源数量”控制，默认值为 `0`，不会自动发起补充搜索。需要时按搜索类型显式设置非零数量；只配置了其中一个服务时，该服务获得全部数量。
+Unconfigured optional Providers are skipped. Tavily and Firecrawl supplementary-search budgets default to `0` for every search profile; explicit `web_extract` and `web_map` requests use their own routes.
 
-### 3. 配置搜索方式
+For `docs_search`, Context7 requires an explicit `library_name` or `library_id`. Without one, `provider: "auto"` uses Exa instead of guessing a package name from the full question.
 
-页面可以设置默认搜索类型和搜索深度：
+## Tool disclosure
 
-- `compact`：结果更简短；
-- `normal`：信息量适中；
-- `deep`：适合需要更多来源的问题。
+The model-facing surface remains five tools: `web_search`, `docs_search`, `web_extract`, `search_tools`, and `search_call`. Advanced operations are disclosed through manifests rather than registered as additional model tools.
 
-不确定时保持默认值即可，也可以在单次搜索中临时选择其他设置。
+The default `progressive` mode activates a newly disclosed capability on the next model step. In `all` mode, deferred operations are active immediately. Native Tool Mode and Code Mode use the same schemas, execution policy, and canonical outputs.
 
-同一页面还可以设置“每次搜索的补充来源数量”，逐个搜索类型控制 Tavily/Firecrawl 的补充数量。
+When `web_search` or `docs_search` returns a `source_ref`, the plugin automatically activates source pagination and appends its real operation manifest.
 
-“工具披露模式”建议保持 `progressive`，让延迟 operation 按需披露并从下一模型 step 激活；`all` 只让所有延迟 operation 从一开始处于 active 状态。两种模式都保留同一组五个模型工具及相同 schema，不会显示额外的独立工具。
+## Update and uninstall
 
-### 4. 配置网页代理
-
-代理设置位于：
-
-```text
-补充 Provider → 高级 Provider 设置 → 网页提取代理
-```
-
-`smart_direct` 和 `direct` 可以分别填写代理地址，例如：
-
-```text
-http://127.0.0.1:7890
-```
-
-留空表示不使用该项代理。这里只支持不带账号密码的 `http://` 地址，不支持 HTTPS 或 SOCKS 代理，也不会自动读取 `HTTP_PROXY`、`HTTPS_PROXY` 或 `ALL_PROXY`。
-
-`direct` 使用代理时需要 Node.js 24.5 或更高版本。
-
-### 5. 保存并重启
-
-点击“保存配置”后重启 DSH：
-
-```bash
-dsh web
-```
-
-重启后，新配置才会用于搜索。
-
-## 使用
-
-安装并配置完成后，直接在 DSH 中描述需求即可，例如：
-
-```text
-搜索最近的相关信息，并列出来源。
-```
-
-```text
-查找这个库当前版本的官方 API 用法。
-```
-
-```text
-读取并总结 https://example.com/page 的正文。
-```
-
-```text
-对这个问题做多来源核对，并说明各来源是否一致。
-```
-
-## 更新与卸载
-
-更新到 npm 上的最新版本：
-
-```bash
-dsh plugin --profile web add dsh-search-enhance@latest
-```
-
-卸载插件：
+To update, run the installation command above again. To remove the plugin:
 
 ```bash
 dsh plugin --profile web remove dsh-search-enhance
 ```
+
+Restart DSH after updating or removing the bundle.

package/README.zh.md

@@ -0,0 +1,101 @@
+# DeepSeek Harness Search Enhance
+
+[English](README.md) | 简体中文
+
+`dsh-search-enhance` 是 DeepSeek Harness 的搜索增强插件。它使用 Grok-compatible Search API 生成普通网页搜索的主要回答，并可选用 Context7、Exa、Tavily 和 Firecrawl 完成文档检索、补充来源、网页正文提取和站点页面发现。
+
+插件将搜索、来源保留和页面读取作为不同步骤处理。`web_search` 和 `docs_search` 返回搜索回答或文档片段以及可见来源；完整来源记录可通过 `source_ref` 保存并继续分页读取；需要核对重要内容时，再由 `web_extract` 获取选中页面。因此，搜索 snippet 与实际读取的网页正文会保持明确区分。
+
+> 你需要自行提供所选服务的端点和凭据，插件不内置任何 API Key。`web_search` 需要 Grok-compatible 端点；Context7、Exa、Tavily 和 Firecrawl 均为可选 Provider。
+
+![DSH Web 会话：搜索、检索文档、提取官方页面并生成带来源的回答](https://raw.githubusercontent.com/KKKneko/dsh-search-enhance/main/assets/search-workflow.png)
+
+## 主要特点
+
+- `web_search` 使用 Grok-compatible 端点生成主要回答，对文档型问题补充 Exa 来源，并在配置的补充预算内使用 Tavily 或 Firecrawl。
+- 来源在展示前会经过 URL 标准化、去重，并根据来源类别、目标版本和发布时间信号重新排序。
+- `source_ref` 将完整来源记录保存在插件私有持久存储中，Agent 可以继续分页读取首次结果未展示的来源。
+- `docs_search` 只在提供明确 `library_name` 或 `library_id` 时使用 Context7；没有库身份的请求使用 Exa 发现。
+- `web_extract` 按 Tavily → Firecrawl → `smart_direct` → `direct` 的固定路径执行，并报告提取路径、证据等级和可用的页面元数据。
+- 来源分页、Context7 精细操作、站点映射、研究计划和诊断通过 `search_tools` 与 `search_call` 按需披露。
+- Native Tool Mode 与 Code Mode 使用相同的固定工具入口和规范输出。DSH Settings、Credentials、Agent Preset、guard 和生命周期清理继续生效。
+- 未配置的可选 Provider 会被跳过。Tavily 和 Firecrawl 的补充搜索预算默认是 `0`，可选 Provider 失败也会在结果中显示。
+
+## 快速开始
+
+### 1. 安装
+
+将已发布的 bundle 安装到 DSH `web` profile：
+
+```bash
+dsh plugin --profile web add dsh-search-enhance@latest
+```
+
+### 2. 启动 DSH Web
+
+```bash
+dsh web
+```
+
+### 3. 配置搜索
+
+打开：
+
+```text
+设置 → 插件 → 插件配置 → dsh-search-enhance
+```
+
+在 **Grok 搜索后端** 中配置：
+
+1. xAI 端点或明确的 Grok-compatible 网关；
+2. 与服务匹配的 `completions` 或 `responses` 协议；
+3. 该端点支持的模型；
+4. 设置卡片“凭据”区域中的 Grok 密钥。
+
+默认凭据引用名是 `SEARCH_API_KEY`。密钥值通过 DSH Credentials 保存，不会暴露为模型参数。
+
+保存设置并重启 DSH，然后询问一个需要当前信息的问题。成功时会看到 `Search` 工具行、回答和来源链接。
+
+## 使用示例
+
+直接使用自然语言即可，插件会为 Agent 提供路由指引。
+
+- “查找 React 19 最重要的用户可见变化，优先引用官方发布说明并附上来源链接。”
+- “查找 FastAPI 当前 JWT 认证 API，并根据官方文档给出最小示例。”
+- “读取并总结 `https://example.com/article`，区分页面原文与推断。”
+
+需要完整来源分页、站点发现、研究计划或 Provider 诊断时，请明确提出。
+
+## Provider
+
+只配置你实际需要的路径。
+
+| Provider | 用途 | 默认凭据引用名 | 是否必需 |
+| --- | --- | --- | --- |
+| Grok-compatible Search API | `web_search` 的主要回答和来源 | `SEARCH_API_KEY` | 使用 `web_search` 时 |
+| Context7 | 明确库身份的文档检索 | `CONTEXT7_API_KEY` | 否 |
+| Exa | 广泛文档发现和补充发现 | `EXA_API_KEY` | 否 |
+| Tavily | 补充搜索、网页提取和站点映射 | `TAVILY_API_KEY` | 否 |
+| Firecrawl | 补充搜索和网页提取 | `FIRECRAWL_API_KEY` | 否 |
+
+未配置的可选 Provider 会被跳过。所有搜索 profile 的 Tavily/Firecrawl 补充搜索预算默认都是 `0`；显式的 `web_extract` 和 `web_map` 请求使用各自的执行路径。
+
+对于 `docs_search`，Context7 需要明确的 `library_name` 或 `library_id`。两者都未提供时，`provider: "auto"` 使用 Exa，不会根据完整问题猜测包名。
+
+## 工具披露
+
+模型可见入口始终是五个工具：`web_search`、`docs_search`、`web_extract`、`search_tools` 和 `search_call`。高级 operation 通过 manifest 披露，不会注册成更多模型工具。
+
+默认 `progressive` 模式下，新披露的能力从下一模型 step 开始可调用。`all` 模式让延迟 operation 立即处于 active 状态。Native Tool Mode 与 Code Mode 使用相同 schema、执行策略和规范输出。
+
+`web_search` 或 `docs_search` 返回 `source_ref` 时，插件会自动激活来源分页，并追加对应的真实 operation manifest。
+
+## 更新与卸载
+
+更新时重新运行上面的安装命令。卸载插件：
+
+```bash
+dsh plugin --profile web remove dsh-search-enhance
+```
+
+更新或卸载 bundle 后请重启 DSH。

package/lib/diagnostics/probes.d.ts

@@ -4,7 +4,8 @@ import type { BoundedSourceProvider } from '../providers/types.js';
 import type { DiagnosticCapability, DiagnosticProbe, DiagnosticProbeInput, DiagnosticProbeResult, DiagnosticProviderName } from './types.js';
 /** Fixed, non-user-controlled diagnostic targets. */
 export declare const DIAGNOSTIC_SEARCH_QUERY = "search-enhance fixed connectivity diagnostic";
-export declare const DIAGNOSTIC_CONTEXT7_QUERY = "react documentation";
+export declare const DIAGNOSTIC_CONTEXT7_LIBRARY_NAME = "React";
+export declare const DIAGNOSTIC_CONTEXT7_QUERY = "documentation connectivity diagnostic";
 export declare const DIAGNOSTIC_RESULT_LIMIT = 1;
 /** Uses the public bounded model-list GET; it never calls Search API main search. */
 export declare class SearchApiModelListDiagnosticProbe implements DiagnosticProbe {

package/lib/diagnostics/probes.js

@@ -1,7 +1,8 @@
 import { throwIfAborted } from '../provider-runtime/index.js';
 /** Fixed, non-user-controlled diagnostic targets. */
 export const DIAGNOSTIC_SEARCH_QUERY = 'search-enhance fixed connectivity diagnostic';
-export const DIAGNOSTIC_CONTEXT7_QUERY = 'react documentation';
+export const DIAGNOSTIC_CONTEXT7_LIBRARY_NAME = 'React';
+export const DIAGNOSTIC_CONTEXT7_QUERY = 'documentation connectivity diagnostic';
 export const DIAGNOSTIC_RESULT_LIMIT = 1;
 const COMPLETE = Object.freeze({ state: 'complete' });
 const NOT_CONFIGURED = Object.freeze({ state: 'not_configured' });
@@ -38,6 +39,7 @@ export class Context7ResolveDiagnosticProbe {
         await this.context7.resolve({
             config: input.config,
             limit: DIAGNOSTIC_RESULT_LIMIT,
+            libraryName: DIAGNOSTIC_CONTEXT7_LIBRARY_NAME,
             onDispatch: input.onDispatch,
             query: DIAGNOSTIC_CONTEXT7_QUERY,
             signal: input.signal,

package/lib/documentation/cache.d.ts

@@ -49,6 +49,7 @@ export interface Context7CacheRepository {
 /** Cache identity includes every bounded input that can change a successful resolve value. */
 export declare function context7ResolveCacheKey(input: {
     readonly baseUrl: string;
+    readonly libraryName: string;
     readonly query: string;
     readonly maxResults: number;
     readonly maxLibraryTextCharacters: number;

package/lib/documentation/cache.js

@@ -40,11 +40,15 @@ export function context7ResolveCacheKey(input) {
     positiveSafeInteger(input.maxResults, 'maxResults');
     positiveSafeInteger(input.maxLibraryTextCharacters, 'maxLibraryTextCharacters');
     positiveSafeInteger(input.maxEntryBytes, 'maxEntryBytes');
+    const libraryName = input.libraryName.trim();
     const query = input.query.trim();
+    if (libraryName.length === 0)
+        throw new RangeError('Context7 library name must not be empty');
     if (query.length === 0)
         throw new RangeError('Context7 resolve query must not be empty');
     return `ctx7r_${digestIdentity('resolve', {
         baseUrl: normalizedBaseUrl(input.baseUrl),
+        libraryName,
         maxEntryBytes: input.maxEntryBytes,
         maxLibraryTextCharacters: input.maxLibraryTextCharacters,
         maxResults: input.maxResults,

package/lib/documentation/context7-cache.d.ts

@@ -39,6 +39,7 @@ export interface Context7CacheClock {
     now(): number;
 }
 export interface Context7ResolveCachedInput {
+    readonly libraryName: string;
     readonly query: string;
     readonly maxResults: number;
     readonly forceRefresh: boolean;

package/lib/documentation/context7-cache.js

@@ -174,6 +174,7 @@ export class Context7CachedOperations {
         throwIfAborted(input.signal);
         const cacheKey = context7ResolveCacheKey({
             baseUrl: input.config.providers.context7.baseUrl,
+            libraryName: input.libraryName,
             maxEntryBytes: input.config.cache.context7EntryMaxBytes,
             maxLibraryTextCharacters: input.config.cache.context7LibraryTextMaxCharacters,
             maxResults: input.maxResults,

package/lib/documentation/index.d.ts

@@ -1,5 +1,5 @@
 export { CONTEXT7_CACHE_DOMAIN_NAME, CONTEXT7_CACHE_DOMAIN_SPEC, CONTEXT7_CACHE_FORMAT_VERSION, CONTEXT7_CACHE_KEY_PATTERN, CONTEXT7_CACHE_TABLE_NAME, CONTEXT7_DOC_REF_PATTERN, CachedContext7LibrarySchema, CachedDocumentationSnippetSchema, Context7CacheEntrySchema, Context7CacheKeySchema, Context7DocsCacheEntrySchema, Context7DocRefSchema, Context7ResolveCacheEntrySchema, type CachedContext7Library, type CachedDocumentationSnippet, type Context7CacheDomain, type Context7CacheEntry, type Context7CacheKey, type Context7DocsCacheEntry, type Context7DocRef, type Context7ResolveCacheEntry, } from './cache-domain.js';
 export { CONTEXT7_CACHE_QUERY_MAX_SCAN_RECORDS, CONTEXT7_CACHE_QUERY_MAX_TERMS, CONTEXT7_CACHE_QUERY_MAX_TEXT_CHARACTERS, Context7CacheError, Context7CacheStore, PersistentContext7Cache, context7DocsCacheKey, context7ResolveCacheKey, isContext7DocRef, type Context7CacheErrorCode, type Context7CacheLimits, type Context7CacheRepository, type Context7CacheWriteResult, type Context7CachedDocFound, type Context7CachedDocLookup, type Context7CachedDocMatch, type Context7CachedDocMatchFound, type Context7CachedDocMatchNotFound, type Context7CachedDocNotFound, type Context7CachedDocQuery, } from './cache.js';
 export { CONTEXT7_CACHE_STATES, Context7CachedOperations, Context7OperationFailure, context7CacheEntryIsFresh, isContext7LibraryId, normalizeContext7LibraryId, permitsContext7StaleFallback, type CachedContext7Operation, type Context7CacheClock, type Context7CacheState, type Context7DocsCachedInput, type Context7DocsRemoteResult, type Context7OperationPath, type Context7RemoteDiagnostics, type Context7ResolveCachedInput, type Context7ResolveRemoteResult, } from './context7-cache.js';
-export { DOCUMENTATION_CACHE_PATH_STATES, DOCUMENTATION_CACHE_SKIP_REASONS, DOCUMENTATION_PROVIDER_STATES, DOCUMENTATION_RESULT_PROVIDERS, DOCUMENTATION_SEARCH_PROVIDERS, DOCUMENTATION_SEARCH_SERVICE_KEY, DOCUMENTATION_WARNING_CODES, DocumentationContext7Provider, DocumentationSearchInfrastructureError, DocumentationSearchService, type Context7CachedDocSearchInput, type Context7DocsInput, type Context7DocsResult, type Context7ResolveInput, type Context7ResolveResult, type DocumentationCachePath, type DocumentationCachePathState, type DocumentationCacheReport, type DocumentationCacheSkipReason, type DocumentationProviderState, type DocumentationProviderStatus, type DocumentationResultProvider, type DocumentationSearchDependencies, type DocumentationSearchInput, type DocumentationSearchProvider, type DocumentationSearchResult, type DocumentationWarning, type DocumentationWarningCode, } from './service.js';
+export { DOCUMENTATION_CACHE_PATH_STATES, DOCUMENTATION_CACHE_SKIP_REASONS, DOCUMENTATION_PROVIDER_STATES, DOCUMENTATION_RESULT_PROVIDERS, DOCUMENTATION_SEARCH_PROVIDERS, DOCUMENTATION_SEARCH_SERVICE_KEY, DOCUMENTATION_WARNING_CODES, DocumentationSearchInfrastructureError, DocumentationSearchService, type Context7CachedDocSearchInput, type Context7DocsInput, type Context7DocsResult, type Context7ResolveInput, type Context7ResolveResult, type DocumentationCachePath, type DocumentationCachePathState, type DocumentationCacheReport, type DocumentationCacheSkipReason, type DocumentationProviderState, type DocumentationProviderStatus, type DocumentationResultProvider, type DocumentationSearchDependencies, type DocumentationSearchInput, type DocumentationSearchProvider, type DocumentationSearchResult, type DocumentationWarning, type DocumentationWarningCode, } from './service.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/documentation/index.js

@@ -1,5 +1,5 @@
 export { CONTEXT7_CACHE_DOMAIN_NAME, CONTEXT7_CACHE_DOMAIN_SPEC, CONTEXT7_CACHE_FORMAT_VERSION, CONTEXT7_CACHE_KEY_PATTERN, CONTEXT7_CACHE_TABLE_NAME, CONTEXT7_DOC_REF_PATTERN, CachedContext7LibrarySchema, CachedDocumentationSnippetSchema, Context7CacheEntrySchema, Context7CacheKeySchema, Context7DocsCacheEntrySchema, Context7DocRefSchema, Context7ResolveCacheEntrySchema, } from './cache-domain.js';
 export { CONTEXT7_CACHE_QUERY_MAX_SCAN_RECORDS, CONTEXT7_CACHE_QUERY_MAX_TERMS, CONTEXT7_CACHE_QUERY_MAX_TEXT_CHARACTERS, Context7CacheError, Context7CacheStore, PersistentContext7Cache, context7DocsCacheKey, context7ResolveCacheKey, isContext7DocRef, } from './cache.js';
 export { CONTEXT7_CACHE_STATES, Context7CachedOperations, Context7OperationFailure, context7CacheEntryIsFresh, isContext7LibraryId, normalizeContext7LibraryId, permitsContext7StaleFallback, } from './context7-cache.js';
-export { DOCUMENTATION_CACHE_PATH_STATES, DOCUMENTATION_CACHE_SKIP_REASONS, DOCUMENTATION_PROVIDER_STATES, DOCUMENTATION_RESULT_PROVIDERS, DOCUMENTATION_SEARCH_PROVIDERS, DOCUMENTATION_SEARCH_SERVICE_KEY, DOCUMENTATION_WARNING_CODES, DocumentationContext7Provider, DocumentationSearchInfrastructureError, DocumentationSearchService, } from './service.js';
+export { DOCUMENTATION_CACHE_PATH_STATES, DOCUMENTATION_CACHE_SKIP_REASONS, DOCUMENTATION_PROVIDER_STATES, DOCUMENTATION_RESULT_PROVIDERS, DOCUMENTATION_SEARCH_PROVIDERS, DOCUMENTATION_SEARCH_SERVICE_KEY, DOCUMENTATION_WARNING_CODES, DocumentationSearchInfrastructureError, DocumentationSearchService, } from './service.js';
 //# sourceMappingURL=index.js.map

package/lib/documentation/service.d.ts

@@ -3,7 +3,7 @@ import type { Config } from '../config.js';
 import type { CanonicalSource, SourceRecordCandidate } from '../contracts/index.js';
 import { type ProviderAttemptRecord, type ProviderErrorKind } from '../provider-runtime/index.js';
 import { type Context7RemoteClient, type Context7Library } from '../providers/context7.js';
-import type { BoundedSourceProvider, DocumentationSnippet, SourceProviderSearchInput, SourceProviderSearchOutcome } from '../providers/types.js';
+import type { BoundedSourceProvider, DocumentationSnippet } from '../providers/types.js';
 import type { Context7DocsCacheEntry, Context7DocRef } from './cache-domain.js';
 import { type Context7CachedDocLookup, type Context7CachedDocMatch } from './cache.js';
 import { Context7CachedOperations, type Context7OperationPath } from './context7-cache.js';
@@ -43,7 +43,10 @@ export interface DocumentationWarning {
 export interface DocumentationSearchInput {
     readonly query: string;
     readonly provider?: DocumentationSearchProvider;
+    /** Exact Context7 id; when present it takes priority and bypasses resolve. */
     readonly libraryId?: string;
+    /** Explicit Context7 package/product identity; never inferred from query. */
+    readonly libraryName?: string;
     readonly maxResults: number;
     readonly forceRefresh?: boolean;
     readonly signal: AbortSignal;
@@ -138,8 +141,8 @@ declare module '@deepseek-ai/cordis' {
     }
 }
 /**
- * Lifecycle-bound documentation core shared by the high-level docs Consumer,
- * enhancement routing, and the deferred granular Context7 Consumers.
+ * Lifecycle-bound documentation core shared by the high-level docs Consumer
+ * and the deferred granular Context7 Consumers.
  */
 export declare class DocumentationSearchService extends Service {
     private readonly context7;
@@ -167,13 +170,4 @@ export declare class DocumentationSearchService extends Service {
     private runContext7;
     private runExa;
 }
-/** Context7-only adapter used by web_search while sharing the high-level service/cache. */
-export declare class DocumentationContext7Provider implements BoundedSourceProvider {
-    private readonly documentation;
-    readonly capability: "docs_search";
-    readonly provider: "context7";
-    constructor(documentation: DocumentationSearchService);
-    configured(): Promise<boolean>;
-    search(input: SourceProviderSearchInput): Promise<SourceProviderSearchOutcome>;
-}
 //# sourceMappingURL=service.d.ts.map