dsh-search-enhance 0.1.5 → 0.1.7

package/README.md

@@ -1,223 +1,103 @@
-# 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 主搜索
-      │                      ├─ 按需要补充 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` | 直接调用。已知精确 `/org/project` 时传 `library_id`；已知包或产品名时传 `library_name`；不知道库身份时用 `provider: auto` 进行 Exa 发现 |
-| `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` | 用户明确要求检查搜索配置或连接状态 |
+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).
 
-披露与调用遵循以下规则：
+## Quick start
 
-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 和工具限制约束，插件不会绕过这些限制。
+### 1. Install
 
-这种固定网关设计保留了按需披露，同时避免插件因披露状态变化而改写发送给 DeepSeek 的 system 文本、tool schema/顺序或 Code Mode SDK 前缀，从而消除插件自身造成的前缀变化。
-
-### 一次完整搜索如何进行
-
-1. 通用问题直接调用 `web_search`，文档问题直接调用 `docs_search`。
-2. 调用 `docs_search` 时保持任务问题与库身份分离。例如 `{"query":"JWT authentication middleware API","library_name":"FastAPI"}`。同时提供 `library_id` 和 `library_name` 时，合法 `library_id` 优先并跳过 resolve。
-3. `provider: auto` 没有 `library_id`/`library_name` 时只使用 Exa；`provider: context7` 或 `all` 缺少库身份会在凭据、缓存和网络前失败。普通 `web_search` 的文档增强也只使用 Exa，不猜测 Context7 库。
-4. 当搜索产生来源时，结果会包含可见来源、`source_ref` 和追加的 `search_sources` manifest，同时自动激活 `sources`。
-5. 在下一 step 需要更多来源时，调用 `search_call({ operation: 'search_sources', arguments: { source_ref, offset: 0, limit: 20, format: 'compact' } })` 分页读取，而不是直接调用 `search_sources`。
-6. 对重要结论，选择权威链接并直接调用 `web_extract` 获取网页正文。
-7. 如果任务需要站点内发现、研究计划、精细 Context7 查询或连接检查，先调用例如 `search_tools({ capabilities: ['site_map'] })` 取得 manifest；`progressive` 模式从下一 step、`all` 模式立即通过 `search_call({ operation: 'web_map', arguments: { url: 'https://example.com' } })` 调用相应 operation。
-8. 最终回答综合主搜索、补充来源和已经读取的网页正文，并保留来源链接。
-
-`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 搜索配置；其他选项可以先保持默认。
-
-### 1. 配置 Grok 搜索
-
-至少确认以下三项：
-
-| 配置项 | 说明 |
-| --- | --- |
-| 接口地址 | xAI 官方地址或第三方 Grok 服务地址 |
-| 模型 | 该服务实际支持的 Grok 模型名称 |
-| Grok 密钥 | 在页面的“凭据”区域填写 |
-
-页面还可以选择请求协议、思考等级和超时时间。请求协议需要与所使用的服务保持一致：
-
-- `completions`：使用聊天补全接口；
-- `responses`：使用 Responses 接口。
-
-默认的 Grok 密钥名称是 `SEARCH_API_KEY`。密钥值只填写在“凭据”区域，不要写进接口地址或普通配置项。
-
-### 2. 配置补充来源
-
-这些服务不是完成主搜索的必要条件，可以按需要配置：
-
-| 服务 | 用途 | 默认密钥名称 |
-| --- | --- | --- |
-| Context7 | 使用显式 `library_name` 或 `library_id` 查找库和框架文档 | `CONTEXT7_API_KEY` |
-| Exa | 补充文档和网页结果 | `EXA_API_KEY` |
-| Tavily | 补充搜索、读取网页和发现站点页面 | `TAVILY_API_KEY` |
-| Firecrawl | 补充搜索和读取网页 | `FIRECRAWL_API_KEY` |
-
-在“补充 Provider”中填写服务地址，在“凭据”中填写对应密钥。没有配置的服务会被跳过，不影响已经配置好的搜索来源。
-
-Tavily 和 Firecrawl 参与普通搜索的数量由“每次搜索的补充来源数量”控制，默认值为 `0`，不会自动发起补充搜索。需要时按搜索类型显式设置非零数量；只配置了其中一个服务时，该服务获得全部数量。
-
-### 3. 配置搜索方式
-
-页面可以设置默认搜索类型和搜索深度：
+Under **Grok search backend**, configure:
 
-- `compact`：结果更简短；
-- `normal`：信息量适中；
-- `deep`：适合需要更多来源的问题。
+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.
 
-同一页面还可以设置“每次搜索的补充来源数量”，逐个搜索类型控制 Tavily/Firecrawl 的补充数量。
+Save the settings, restart DSH, and ask a current-information question. A successful run shows a `Search` tool row, an answer, and source links.
 
-“工具披露模式”建议保持 `progressive`，让延迟 operation 按需披露并从下一模型 step 激活；`all` 只让所有延迟 operation 从一开始处于 active 状态。两种模式都保留同一组五个模型工具及相同 schema，不会显示额外的独立工具。
+## Example requests
 
-### 4. 配置网页代理
+Use normal language; the plugin gives the Agent routing guidance.
 
-代理设置位于：
+- “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.”
 
-```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
-```
+Ask explicitly when you need complete source pagination, site discovery, a research plan, or Provider diagnostics.
 
-重启后，新配置才会用于搜索。
+## Providers
 
-## 使用
+Configure only the routes you need.
 
-安装并配置完成后，直接在 DSH 中描述需求即可，例如：
+| 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 |
 
-```text
-搜索最近的相关信息，并列出来源。
-```
+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.
 
-```text
-查找这个库当前版本的官方 API 用法。
-```
+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.
 
-```text
-读取并总结 https://example.com/page 的正文。
-```
+## Tool disclosure
 
-```text
-对这个问题做多来源核对，并说明各来源是否一致。
-```
+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.
 
-更新到 npm 上的最新版本：
+When `web_search` or `docs_search` returns a `source_ref`, the plugin automatically activates source pagination and appends its real operation manifest.
 
-```bash
-dsh plugin --profile web add dsh-search-enhance@latest
-```
+## Update and uninstall
 
-卸载插件：
+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,103 @@
+# 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 失败也会在结果中显示。
+
+完整的路由、证据处理和渐进披露流程见[搜索链路架构](https://github.com/KKKneko/dsh-search-enhance/blob/main/guides/search-workflow.zh.md)。
+
+## 快速开始
+
+### 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/package.json

@@ -1,7 +1,12 @@
 {
   "name": "dsh-search-enhance",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Bounded search, documentation, extraction, progressively disclosed site mapping/research planning, and read-only diagnostics for DeepSeek Harness",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KKKneko/dsh-search-enhance.git"
+  },
+  "homepage": "https://github.com/KKKneko/dsh-search-enhance#readme",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -119,6 +124,7 @@
     "@deepseek-ai/dsh-storage-domain": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1",
     "react": "^18.2.0"
   },
   "peerDependenciesMeta": {
@@ -131,7 +137,6 @@
     "react": { "optional": true }
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1",
     "defuddle": "0.18.1",
     "linkedom": "0.18.12",
     "wreq-js": "2.3.1",
@@ -171,6 +176,7 @@
     "@deepseek-ai/dsh-storage-json": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1",
     "@testing-library/react": "16.3.2",
     "@types/node": "^24.0.0",
     "@types/react": "18.3.28",