dsh-search-enhance 0.1.7 → 0.1.9

package/README.md

@@ -8,26 +8,30 @@ The plugin handles search, source retention, and page retrieval as separate step
 
 > 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.
 
-![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)
+![A DSH Web session that searches, checks documentation, extracts an official page, and returns a sourced answer](https://raw.githubusercontent.com/umineko987/dsh-search-enhance/main/assets/search-workflow.png)
 
 ## Key characteristics
 
-- `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.
+- `web_search` uses the Grok-compatible endpoint for the main answer and runs all user-selected supplemental Providers (Exa, Tavily, Firecrawl) in parallel, with an independent per-Provider source limit.
 - 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.
+- `web_extract` requires one explicit `provider` from the user-enabled set: `tavily_extract`, `firecrawl_scrape`, `smart_direct`, or `direct`. It reports the route, evidence level, and available page metadata; failures never switch Providers.
 - 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.
+- Supplemental search defaults to no Providers selected. Unselected Providers are never requested; missing credentials and failures of selected Providers remain visible as warnings.
 
-For the complete routing, evidence, and progressive-disclosure flow, see [Search workflow architecture](https://github.com/KKKneko/dsh-search-enhance/blob/main/guides/search-workflow.md).
+For the complete routing, evidence, and progressive-disclosure flow, see [Search workflow architecture](https://github.com/umineko987/dsh-search-enhance/blob/main/guides/search-workflow.md).
 
 ## Quick start
 
 ### 1. Install
 
-Install the published bundle into the DSH `web` profile:
+Supports only DSH `0.1.5-rc.2`. DSH dependencies are pinned to this exact release; older versions and other prereleases are not supported.
+
+If migrating from the scoped `@kkkneko/dsh-search-enhance` package, first run `dsh plugin --profile web remove @kkkneko/dsh-search-enhance` to avoid loading both bundles.
+
+Install the [published npm bundle](https://www.npmjs.com/package/dsh-search-enhance) into the DSH `web` profile:
 
 ```bash
 dsh plugin --profile web add dsh-search-enhance@latest
@@ -47,15 +51,21 @@ Open:
 Settings → Plugins → Plugin configuration → dsh-search-enhance
 ```
 
-Under **Grok search backend**, configure:
+In the settings card:
 
-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.
+1. Set the xAI endpoint or an explicit Grok-compatible gateway and its key under **Credentials → Grok search**.
+2. Choose the matching `completions` or `responses` protocol and model under **Grok search backend**.
+3. Use the **Supplemental search providers** and **Available extraction providers** dropdowns to select multiple services. Each service's endpoint, timeout, and credential reference are grouped in its credential card.
 
 The default credential reference is `SEARCH_API_KEY`. Credential values are stored through DSH Credentials and are not exposed as model parameters.
 
+Official Grok endpoints automatically enable native search without another protocol or toggle:
+- Version paths may be omitted: `https://api.x.ai` / `https://us.api.x.ai` gain `/v1`; `https://openrouter.ai` gains `/api/v1` (or `/api` gains `/v1`). This applies to search and model-list requests, without duplicating complete paths or changing custom gateways.
+- **xAI**: `https://api.x.ai/v1` (also `https://us.api.x.ai/v1`), with a model such as `grok-4.6`. Requests use Responses with `web_search` + `x_search`, even when `completions` is selected; saved settings are not rewritten.
+- **OpenRouter**: `https://openrouter.ai/api/v1`, with a model such as `x-ai/grok-4.6`. The selected protocol is retained and `openrouter:web_search` with `engine: native` is sent; no `:online` suffix is needed. Model support and workspace policy still govern OpenRouter's actual engine; to prohibit its fallback, allow only `native` in the workspace.
+- Detection is restricted to those official HTTPS hosts and Grok models. Other models and compatible proxies are unchanged. Native adapters map `minimal` to `low` and `max` to `xhigh`; `off` still omits the reasoning parameter.
+- Structured citations enter the source list. If the API reports no completed search, structured citations, or search usage, the result explicitly warns that native search is unconfirmed; prose links alone are not execution evidence.
+
 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
@@ -80,7 +90,11 @@ Configure only the routes you need.
 | Tavily | Supplementary search, page extraction, and site mapping | `TAVILY_API_KEY` | No |
 | Firecrawl | Supplementary search and page extraction | `FIRECRAWL_API_KEY` | No |
 
-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.
+In the plugin settings, select any combination of **supplemental search Providers**. Each selected Provider runs alongside the main search, using `supplementalSearch.maxSourcesPerProvider` (default `5`, maximum `100`). This selection applies to all search profiles; there is no implicit Exa enhancement or shared 60/40 budget.
+
+Separately, select the **extraction Providers** available to the Agent. Each `web_extract` call must choose exactly one enabled Provider, for example `{ "url": "https://example.com/", "provider": "direct", "format": "markdown" }`. Disabled, unconfigured, unsupported, or failed Providers do not trigger automatic fallback. Extraction Providers are enabled by default; disable any you do not want the Agent to use.
+
+**Configuration change:** replace the former `extraDiscoverySources` profile budgets with `supplementalSearch` selections. Enable `exa`, `tavily`, and/or `firecrawl` explicitly; existing API credentials alone do not enable supplemental search. Existing extraction `enabled` settings remain the allowlist. Save settings and restart DSH. `fallbackMode` now applies only to the unchanged documentation-search routing.
 
 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.
 

package/README.zh.md

@@ -8,26 +8,30 @@
 
 > 你需要自行提供所选服务的端点和凭据，插件不内置任何 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)
+![DSH Web 会话：搜索、检索文档、提取官方页面并生成带来源的回答](https://raw.githubusercontent.com/umineko987/dsh-search-enhance/main/assets/search-workflow.png)
 
 ## 主要特点
 
-- `web_search` 使用 Grok-compatible 端点生成主要回答，对文档型问题补充 Exa 来源，并在配置的补充预算内使用 Tavily 或 Firecrawl。
+- `web_search` 使用 Grok-compatible 端点生成主要回答，并行调用用户勾选的全部补充搜索 Provider（Exa、Tavily、Firecrawl），每家使用独立的来源数量上限。
 - 来源在展示前会经过 URL 标准化、去重，并根据来源类别、目标版本和发布时间信号重新排序。
 - `source_ref` 将完整来源记录保存在插件私有持久存储中，Agent 可以继续分页读取首次结果未展示的来源。
 - `docs_search` 只在提供明确 `library_name` 或 `library_id` 时使用 Context7；没有库身份的请求使用 Exa 发现。
-- `web_extract` 按 Tavily → Firecrawl → `smart_direct` → `direct` 的固定路径执行，并报告提取路径、证据等级和可用的页面元数据。
+- `web_extract` 每次必须通过 `provider` 指定一家用户已启用的服务：`tavily_extract`、`firecrawl_scrape`、`smart_direct` 或 `direct`。结果报告提取路径、证据等级和页面元数据，失败不自动换服务。
 - 来源分页、Context7 精细操作、站点映射、研究计划和诊断通过 `search_tools` 与 `search_call` 按需披露。
 - Native Tool Mode 与 Code Mode 使用相同的固定工具入口和规范输出。DSH Settings、Credentials、Agent Preset、guard 和生命周期清理继续生效。
-- 未配置的可选 Provider 会被跳过。Tavily 和 Firecrawl 的补充搜索预算默认是 `0`，可选 Provider 失败也会在结果中显示。
+- 补充搜索默认不选择任何 Provider。未选中的服务不会被请求；选中服务缺少凭据或执行失败会在结果中显示警告。
 
-完整的路由、证据处理和渐进披露流程见[搜索链路架构](https://github.com/KKKneko/dsh-search-enhance/blob/main/guides/search-workflow.zh.md)。
+完整的路由、证据处理和渐进披露流程见[搜索链路架构](https://github.com/umineko987/dsh-search-enhance/blob/main/guides/search-workflow.zh.md)。
 
 ## 快速开始
 
 ### 1. 安装
 
-将已发布的 bundle 安装到 DSH `web` profile：
+仅支持 DSH `0.1.5-rc.2`。DSH 依赖精确锁定到该版本，不兼容旧版或其他预发行版。
+
+如果从带 scope 的包 `@kkkneko/dsh-search-enhance` 迁移，请先运行 `dsh plugin --profile web remove @kkkneko/dsh-search-enhance`，避免同时加载两份插件。
+
+将 [npm 上发布的 bundle](https://www.npmjs.com/package/dsh-search-enhance) 安装到 DSH `web` profile：
 
 ```bash
 dsh plugin --profile web add dsh-search-enhance@latest
@@ -47,15 +51,21 @@ dsh web
 设置 → 插件 → 插件配置 → dsh-search-enhance
 ```
 
-在 **Grok 搜索后端** 中配置：
+在设置卡片中配置：
 
-1. xAI 端点或明确的 Grok-compatible 网关；
-2. 与服务匹配的 `completions` 或 `responses` 协议；
-3. 该端点支持的模型；
-4. 设置卡片“凭据”区域中的 Grok 密钥。
+1. 在 **凭据 → Grok 搜索** 中填写 xAI 端点或明确的 Grok-compatible 网关及密钥；
+2. 在 **Grok 搜索后端** 中选择匹配的 `completions` 或 `responses` 协议及模型；
+3. 用 **补充搜索服务** 和 **可用网页提取服务** 的下拉框多选需要的服务。其他服务的接口地址、超时和凭据引用也位于各自的凭据卡片中。
 
 默认凭据引用名是 `SEARCH_API_KEY`。密钥值通过 DSH Credentials 保存，不会暴露为模型参数。
 
+官方 Grok 端点会自动启用原生搜索，无需新增协议或开关：
+- 版本路径可省略：`https://api.x.ai` / `https://us.api.x.ai` 自动补 `/v1`；`https://openrouter.ai` 自动补 `/api/v1`，填到 `/api` 时补 `/v1`。搜索与模型列表请求都会补全，不重复追加完整路径，也不改写自定义中转地址。
+- **xAI**：`https://api.x.ai/v1`（也支持 `https://us.api.x.ai/v1`），模型如 `grok-4.6`。自动使用 Responses 并发送 `web_search` + `x_search`，即使设置选择了 `completions`；不改写已保存的设置。
+- **OpenRouter**：`https://openrouter.ai/api/v1`，模型如 `x-ai/grok-4.6`。保留所选协议，发送 `openrouter:web_search`、`engine: native`，无需 `:online` 后缀。OpenRouter 的模型能力和工作区策略仍可能影响实际搜索引擎；严格禁止其回退时，在工作区仅允许 `native`。
+- 只匹配上述官方 HTTPS 域名及 Grok 模型；其他模型、中转端点保持原行为。官方适配中 `minimal` 映射为 `low`、`max` 映射为 `xhigh`，`off` 仍表示省略思考参数。
+- 结构化引用会进入来源列表。若 API 未报告完成的搜索、结构化引用或搜索用量，结果会明确提示原生搜索未确认；正文链接本身不作为执行证明。
+
 保存设置并重启 DSH，然后询问一个需要当前信息的问题。成功时会看到 `Search` 工具行、回答和来源链接。
 
 ## 使用示例
@@ -80,7 +90,11 @@ dsh web
 | Tavily | 补充搜索、网页提取和站点映射 | `TAVILY_API_KEY` | 否 |
 | Firecrawl | 补充搜索和网页提取 | `FIRECRAWL_API_KEY` | 否 |
 
-未配置的可选 Provider 会被跳过。所有搜索 profile 的 Tavily/Firecrawl 补充搜索预算默认都是 `0`；显式的 `web_extract` 和 `web_map` 请求使用各自的执行路径。
+在插件设置中，可以多选 **补充搜索 Provider**。选中项与主搜索并行执行，每家使用 `supplementalSearch.maxSourcesPerProvider` 限制来源数量（默认 `5`，最大 `100`）。选择对所有搜索 profile 生效，不再隐式启用 Exa，也不再按 60/40 分摊共享预算。
+
+另外，多选 **网页提取 Provider** 可以限制 Agent 可用的服务范围。每次 `web_extract` 必须明确选择一家已启用服务，例如 `{ "url": "https://example.com/", "provider": "direct", "format": "markdown" }`。服务被禁用、缺少凭据、不支持格式或执行失败时，直接报告错误，不自动回退。提取服务默认全部启用，可取消勾选不希望使用的服务。
+
+**配置变更：** 原 `extraDiscoverySources` 按 profile 设置的预算改为 `supplementalSearch` 选择项。需要明确启用 `exa`、`tavily` 和/或 `firecrawl`；已有 API 凭据本身不会开启补充搜索。现有提取服务的 `enabled` 开关继续作为可用名单。保存设置后重启 DSH。`fallbackMode` 现在仅影响保持原样的文档搜索路由。
 
 对于 `docs_search`，Context7 需要明确的 `library_name` 或 `library_id`。两者都未提供时，`provider: "auto"` 使用 Exa，不会根据完整问题猜测包名。