@qzhike/agent-search 1.0.1 → 1.0.2

package/README.md

@@ -27,7 +27,16 @@ openclaw plugins install --link /absolute/path/to/qzhike-agent-search
 
 ## OpenClaw 配置
 
-### 启用插件与工具
+### `searchMode`：fallback 与 concurrent
+
+| 模式 | 行为 |
+|---|---|
+| **`fallback`**（默认） | 按 **`fallback`** 数组顺序线性尝试，首个有有效结果的 provider 胜出 |
+| **`concurrent`** | 按 **`concurrent`** 列表并行调用，最多 **`concurrentMaxProviders`** 路，合并去重结果 |
+
+可同时保留 **`fallback`** 与 **`concurrent`** 数组以便切换 **`searchMode`**（可选）；下方示例各只展示该模式所需字段。单次 **`qzhike_search`** 仍可用参数 **`searchMode`** / **`provider`** 覆盖 config。
+
+### fallback 模式（串行）
 
 ```json5
 {
@@ -62,7 +71,66 @@ openclaw plugins install --link /absolute/path/to/qzhike-agent-search
 }
 ```
 
-在 `~/.openclaw/.env` 中设置 `DEEPROUTE_CONSOLE_URL`、`DEEPROUTE_API_KEY` 等占位符。更完整的 DeepRoute 全 provider 模板见开源仓库 **`examples/openclaw.config.json5`**（npm 包内不含该文件）。
+### concurrent 模式（并行）
+
+与 fallback 共用 **`providers`** 与 **`.env`**；将 **`searchMode`** 改为 **`"concurrent"`**，并配置 **`concurrent`** / **`concurrentMaxProviders`**：
+
+```json5
+{
+  plugins: {
+    allow: ["qzhike-agent-search"],
+    entries: {
+      "qzhike-agent-search": {
+        enabled: true,
+        config: {
+          searchMode: "concurrent",
+          concurrent: ["ragflow", "brave", "tavily"],
+          concurrentMaxProviders: 3,
+          providers: {
+            ragflow: {
+              auth: "deeproute",
+              baseUrl: "${DEEPROUTE_CONSOLE_URL}",
+              apiKey: "${DEEPROUTE_API_KEY}",
+            },
+            brave: {
+              auth: "deeproute",
+              baseUrl: "${DEEPROUTE_CONSOLE_URL}",
+              apiKey: "${DEEPROUTE_API_KEY}",
+            },
+            tavily: {
+              auth: "deeproute",
+              baseUrl: "${DEEPROUTE_CONSOLE_URL}",
+              apiKey: "${DEEPROUTE_API_KEY}",
+            },
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    allow: ["qzhike_search", "qzhike_read_url"],
+    deny: ["web_search"],
+  },
+}
+```
+
+合并进现有 **`openclaw.json`** 时勿整文件覆盖（保留 **`models`** 等大模型配置）。若已有 **`tools.profile`**，可用 **`tools.alsoAllow`** 追加两个工具名。
+
+在 `~/.openclaw/.env` 中设置占位符（**origin only**，无尾斜杠、**不含 `/api/v1`**）：
+
+```bash
+DEEPROUTE_CONSOLE_URL=http://<console-host>:20316
+DEEPROUTE_API_KEY=sk-...
+```
+
+**`baseUrl` 约定**（插值后由插件使用）：
+
+| Provider | `openclaw.json` 中 `baseUrl` |
+|---|---|
+| `auth: "deeproute"`（ragflow、brave、…） | `"${DEEPROUTE_CONSOLE_URL}"` → Console **`/api/mirror/{provider}/…`** |
+| **`kimi`**（无 `auth`，不走 mirror） | **`"${DEEPROUTE_CONSOLE_URL}/api/v1"`** → **`/api/v1/chat/completions`** |
+
+更完整的 DeepRoute 全 provider 模板见开源仓库 **`examples/openclaw.config.json5`**（npm 包内不含该文件）。
 
 ### DeepRoute 扩展服务（凭据托管）
 

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "qzhike-agent-search",
   "name": "Qzhike Agent Search",
   "description": "Multi-backend search (RAGFlow KB, Serper, Metaso, Zhipu, Exa, SearXNG, Kimi, Brave, Tavily, Jina, MiniMax) with fallback/concurrent modes, plus Jina Reader URL fetch. DeepRoute mirror support.",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "configSchema": {
     "type": "object",
     "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qzhike/agent-search",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Agent search plugin (OpenClaw-first): multi-backend search with RAGFlow KB, fallback/concurrent modes, Jina Reader read URL, and DeepRoute mirror support.",
   "type": "module",
   "license": "MIT",

package/skills/qzhike-agent-search/SKILL.md

@@ -7,8 +7,9 @@ description: >-
 metadata: {"openclaw":{}}
 ---
 
-> **本 Skill 随 npm 插件 `@qzhike/agent-search` 交付**：在 **`openclaw.plugin.json`** 中声明 **`skills/qzhike-agent-search`**，启用插件后 Gateway 自动加载（无需 symlink 到 **`~/.openclaw/skills/`**）。  
-> 安装与配置见包内 **`README.md`**；插件 config 路径：**`plugins.entries.qzhike-agent-search.config`**。
+> **本 Skill 随 npm 插件 `@qzhike/agent-search` 交付**：在 **`openclaw.plugin.json`** 中声明 **`skills/qzhike-agent-search`**，启用插件后 Gateway 自动加载（无需 symlink 到 **`~/.openclaw/skills/`**）。
+> 完整安装、扩展服务映射与全 provider 模板见包内 **`README.md`** / 仓库 **`examples/openclaw.config.json5`**。
+> 插件 config 路径：**`plugins.entries.qzhike-agent-search.config`**（OpenClaw 解析 `${ENV}`；**插件不读** `process.env`）。
 
 # 检索与读页工作流（原生工具）
 
@@ -25,6 +26,79 @@ metadata: {"openclaw":{}}
 
 ---
 
+## DeepRoute 配置速查（运维）
+
+### `~/.openclaw/.env`
+
+```bash
+# Console API origin：无尾斜杠，不含 /api/v1
+DEEPROUTE_CONSOLE_URL=http://<console-host>:20316
+DEEPROUTE_API_KEY=sk-<New-API-用户令牌>
+```
+
+### `providers.*.baseUrl` 与 env 的关系
+
+| Provider 类型 | `openclaw.json` 写法 | 实际 HTTP 前缀 |
+|---|---|---|
+| **`auth: "deeproute"`**（ragflow、brave、jina、…） | `baseUrl: "${DEEPROUTE_CONSOLE_URL}"` | `{origin}/api/mirror/{provider}/…` |
+| **`kimi`（无 auth 字段）** | `baseUrl: "${DEEPROUTE_CONSOLE_URL}/api/v1"` | `{origin}/api/v1/chat/completions` |
+
+**仅 kimi** 在 config 里拼接 **`/api/v1`**；**不要**把 `/api/v1` 写进 `.env` 的 `DEEPROUTE_CONSOLE_URL`（否则 kimi 路径会变成 `…/api/v1/api/v1/…`）。
+
+### 最小可运行片段（DeepRoute）
+
+合并进现有 **`openclaw.json`**（勿整文件覆盖；保留 **`models`** 等大模型配置）：
+
+```json5
+{
+  plugins: {
+    allow: ["qzhike-agent-search"],
+    entries: {
+      "qzhike-agent-search": {
+        enabled: true,
+        config: {
+          searchMode: "concurrent",
+          concurrent: ["ragflow", "brave", "kimi"],
+          concurrentMaxProviders: 3,
+          providers: {
+            ragflow: {
+              auth: "deeproute",
+              baseUrl: "${DEEPROUTE_CONSOLE_URL}",
+              apiKey: "${DEEPROUTE_API_KEY}",
+            },
+            kimi: {
+              baseUrl: "${DEEPROUTE_CONSOLE_URL}/api/v1",
+              apiKey: "${DEEPROUTE_API_KEY}",
+              model: "kimi-k2.6",
+            },
+            brave: {
+              auth: "deeproute",
+              baseUrl: "${DEEPROUTE_CONSOLE_URL}",
+              apiKey: "${DEEPROUTE_API_KEY}",
+            },
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    allow: ["qzhike_search", "qzhike_read_url"],
+    deny: ["web_search"],
+  },
+}
+```
+
+若已有 **`tools.profile`**（如 `coding`），改用 **`tools.alsoAllow`** 追加 `qzhike_search` / `qzhike_read_url`，勿仅用窄 **`tools.allow`** 覆盖默认工具集。
+
+改 **`~/.openclaw/.env`** 或插件 config 后：**`openclaw gateway restart`**。
+
+### RAGFlow（deeproute）
+
+- Console **扩展服务**入库：`ragflow_base_url`、`ragflow`、`ragflow_dataset_ids`。
+- 插件 config **勿写** `datasetIds`；检索走 **`qzhike_search`** + provider **`ragflow`**。
+
+---
+
 ## Agent 必须遵守的顺序
 
 ```
@@ -86,5 +160,5 @@ Skill 管流程与工具选择；TOOLS.md 强化调用顺序。
 
 ## 延伸阅读
 
-- 包内 **`README.md`**：安装、DeepRoute 扩展服务映射、配置示例。
-- 仓库 **`examples/openclaw.config.json5`**：完整 fallback / concurrent 与全 provider 模板。
+- 包内 **`README.md`**：安装、DeepRoute 扩展服务映射、全 provider 配置与 fallback/concurrent 模板。
+- 仓库 **`examples/openclaw.config.json5`**：完整 JSON5 示例（npm 包内不含该文件，见开源仓库）。