@qzhike/agent-search 1.0.1

package/openclaw.plugin.json

@@ -0,0 +1,547 @@
+{
+  "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",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "searchMode": {
+        "anyOf": [
+          {
+            "type": "string",
+            "const": "fallback"
+          },
+          {
+            "type": "string",
+            "const": "concurrent"
+          }
+        ],
+        "description": "Search strategy: \"fallback\" = linear try order; \"concurrent\" = parallel calls. Default fallback."
+      },
+      "fallback": {
+        "type": "array",
+        "items": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "ragflow"
+            },
+            {
+              "type": "string",
+              "const": "serper"
+            },
+            {
+              "type": "string",
+              "const": "metaso"
+            },
+            {
+              "type": "string",
+              "const": "zai"
+            },
+            {
+              "type": "string",
+              "const": "exa"
+            },
+            {
+              "type": "string",
+              "const": "searxng"
+            },
+            {
+              "type": "string",
+              "const": "kimi"
+            },
+            {
+              "type": "string",
+              "const": "brave"
+            },
+            {
+              "type": "string",
+              "const": "tavily"
+            },
+            {
+              "type": "string",
+              "const": "jina"
+            },
+            {
+              "type": "string",
+              "const": "minimax"
+            }
+          ]
+        },
+        "description": "Fallback mode: strict try order. Only listed configured providers run."
+      },
+      "concurrent": {
+        "type": "array",
+        "items": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "ragflow"
+            },
+            {
+              "type": "string",
+              "const": "serper"
+            },
+            {
+              "type": "string",
+              "const": "metaso"
+            },
+            {
+              "type": "string",
+              "const": "zai"
+            },
+            {
+              "type": "string",
+              "const": "exa"
+            },
+            {
+              "type": "string",
+              "const": "searxng"
+            },
+            {
+              "type": "string",
+              "const": "kimi"
+            },
+            {
+              "type": "string",
+              "const": "brave"
+            },
+            {
+              "type": "string",
+              "const": "tavily"
+            },
+            {
+              "type": "string",
+              "const": "jina"
+            },
+            {
+              "type": "string",
+              "const": "minimax"
+            }
+          ]
+        },
+        "description": "Concurrent mode: providers to call in parallel (capped by concurrentMaxProviders)."
+      },
+      "concurrentMaxProviders": {
+        "type": "number",
+        "description": "Max parallel providers in concurrent mode (1-10). Default 3.",
+        "minimum": 1,
+        "maximum": 10
+      },
+      "timeoutSeconds": {
+        "type": "number",
+        "description": "HTTP timeout per request (seconds).",
+        "minimum": 1,
+        "maximum": 120
+      },
+      "maxResults": {
+        "type": "number",
+        "description": "Default max structured results (1-10).",
+        "minimum": 1,
+        "maximum": 10
+      },
+      "providers": {
+        "type": "object",
+        "properties": {
+          "ragflow": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Set false to disable a configured provider. Omitted providers are disabled."
+              },
+              "auth": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "direct"
+                  },
+                  {
+                    "type": "string",
+                    "const": "deeproute"
+                  }
+                ],
+                "description": "direct: Bearer RAGFlow API key + datasetIds in config. deeproute: Bearer user sk; Console injects RAGFlow key and dataset_ids."
+              },
+              "baseUrl": {
+                "type": "string",
+                "description": "direct: RAGFlow service root. deeproute: Console API origin only (e.g. http://host:20316); plugin appends /api/mirror/{provider}. Legacy full mirror paths still work."
+              },
+              "apiKey": {
+                "type": "string",
+                "description": "direct: RAGFlow API key. deeproute: New API user sk (Console injects RAGFlow key)."
+              },
+              "datasetIds": {
+                "type": "string",
+                "description": "direct only: comma-separated RAGFlow dataset IDs (deeproute: configured in Console 扩展服务)."
+              },
+              "similarityThreshold": {
+                "type": "number",
+                "description": "RAGFlow similarity_threshold, default 0.2."
+              },
+              "pageSize": {
+                "type": "number",
+                "description": "RAGFlow page_size, default 30."
+              },
+              "topK": {
+                "type": "number",
+                "description": "RAGFlow top_k."
+              },
+              "timeoutSeconds": {
+                "type": "number",
+                "description": "RAGFlow HTTP timeout (seconds), default 120, max 120.",
+                "minimum": 1,
+                "maximum": 120
+              }
+            }
+          },
+          "serper": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Set false to disable a configured provider. Omitted providers are disabled."
+              },
+              "auth": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "direct"
+                  },
+                  {
+                    "type": "string",
+                    "const": "deeproute"
+                  }
+                ],
+                "description": "direct: X-API-KEY to google.serper.dev. deeproute: Bearer user sk; Console injects Serper key."
+              },
+              "apiKey": {
+                "type": "string",
+                "description": "direct: Serper API key. deeproute: New API user sk (Console injects Serper key)."
+              },
+              "baseUrl": {
+                "type": "string",
+                "description": "direct: default https://google.serper.dev. deeproute: Console API origin only (e.g. http://host:20316); plugin appends /api/mirror/{provider}. Legacy full mirror paths still work."
+              }
+            }
+          },
+          "metaso": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Set false to disable a configured provider. Omitted providers are disabled."
+              },
+              "auth": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "direct"
+                  },
+                  {
+                    "type": "string",
+                    "const": "deeproute"
+                  }
+                ],
+                "description": "direct: Bearer Metaso key. deeproute: Bearer user sk; Console injects Metaso key."
+              },
+              "apiKey": {
+                "type": "string",
+                "description": "direct: Metaso API key. deeproute: New API user sk (Console injects Metaso key)."
+              },
+              "baseUrl": {
+                "type": "string",
+                "description": "direct: default https://metaso.cn. deeproute: Console API origin only (e.g. http://host:20316); plugin appends /api/mirror/{provider}. Legacy full mirror paths still work."
+              }
+            }
+          },
+          "zai": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Set false to disable a configured provider. Omitted providers are disabled."
+              },
+              "auth": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "direct"
+                  },
+                  {
+                    "type": "string",
+                    "const": "deeproute"
+                  }
+                ],
+                "description": "direct: Bearer Zhipu key. deeproute: Bearer user sk; Console injects Zhipu key."
+              },
+              "apiKey": {
+                "type": "string",
+                "description": "direct: Zhipu API key. deeproute: New API user sk (Console injects Zhipu key)."
+              },
+              "baseUrl": {
+                "type": "string",
+                "description": "direct: default https://open.bigmodel.cn. deeproute: Console API origin only (e.g. http://host:20316); plugin appends /api/mirror/{provider}. Legacy full mirror paths still work."
+              },
+              "searchEngine": {
+                "type": "string",
+                "description": "Zhipu search_engine parameter, default \"search_pro\"."
+              }
+            }
+          },
+          "exa": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Set false to disable a configured provider. Omitted providers are disabled."
+              },
+              "auth": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "direct"
+                  },
+                  {
+                    "type": "string",
+                    "const": "deeproute"
+                  }
+                ],
+                "description": "direct: x-api-key to api.exa.ai. deeproute: Bearer user sk; Console injects Exa key."
+              },
+              "apiKey": {
+                "type": "string",
+                "description": "direct: Exa API key. deeproute: New API user sk (Console injects Exa key)."
+              },
+              "baseUrl": {
+                "type": "string",
+                "description": "direct: default https://api.exa.ai. deeproute: Console API origin only (e.g. http://host:20316); plugin appends /api/mirror/{provider}. Legacy full mirror paths still work."
+              }
+            }
+          },
+          "searxng": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Set false to disable a configured provider. Omitted providers are disabled."
+              },
+              "auth": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "direct"
+                  },
+                  {
+                    "type": "string",
+                    "const": "deeproute"
+                  }
+                ],
+                "description": "direct: SearXNG instance baseUrl. deeproute: Bearer sk to Console /api/mirror/searxng."
+              },
+              "baseUrl": {
+                "type": "string",
+                "description": "direct: SearXNG root, e.g. http://127.0.0.1:8888. deeproute: Console API origin only (e.g. http://host:20316); plugin appends /api/mirror/{provider}. Legacy full mirror paths still work."
+              },
+              "apiKey": {
+                "type": "string",
+                "description": "deeproute only: New API user sk (Bearer)."
+              },
+              "categories": {
+                "type": "string",
+                "description": "SearXNG categories, e.g. general"
+              },
+              "language": {
+                "type": "string",
+                "description": "SearXNG language code"
+              }
+            }
+          },
+          "kimi": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Set false to disable a configured provider. Omitted providers are disabled."
+              },
+              "baseUrl": {
+                "type": "string",
+                "description": "OpenAI-compatible base URL, e.g. https://new-api.example.com/v1 (New API)."
+              },
+              "apiKey": {
+                "type": "string",
+                "description": "Bearer token for Authorization header (required to enable)."
+              },
+              "model": {
+                "type": "string",
+                "description": "Model id for chat/completions, default kimi-k2.6"
+              }
+            }
+          },
+          "brave": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Set false to disable a configured provider. Omitted providers are disabled."
+              },
+              "auth": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "direct"
+                  },
+                  {
+                    "type": "string",
+                    "const": "deeproute"
+                  }
+                ],
+                "description": "direct: Brave X-Subscription-Token (default). deeproute: Bearer user sk to Console /api/mirror/brave."
+              },
+              "apiKey": {
+                "type": "string",
+                "description": "direct: Brave subscription token. deeproute: New API user sk (Console injects Brave key)."
+              },
+              "baseUrl": {
+                "type": "string",
+                "description": "direct: default https://api.search.brave.com. deeproute: Console API origin only (e.g. http://host:20316); plugin appends /api/mirror/{provider}. Legacy full mirror paths still work."
+              },
+              "country": {
+                "type": "string",
+                "description": "Brave country filter (ISO 3166-1 alpha-2), e.g. US."
+              },
+              "freshness": {
+                "type": "string",
+                "description": "Brave result freshness: \"pd\" (day), \"pw\", \"pm\", or \"py\"."
+              }
+            }
+          },
+          "tavily": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Set false to disable a configured provider. Omitted providers are disabled."
+              },
+              "auth": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "direct"
+                  },
+                  {
+                    "type": "string",
+                    "const": "deeproute"
+                  }
+                ],
+                "description": "direct: Tavily api_key in POST body. deeproute: Bearer sk; Console injects Tavily key."
+              },
+              "apiKey": {
+                "type": "string",
+                "description": "direct: Tavily API key. deeproute: New API user sk (Console injects Tavily key)."
+              },
+              "baseUrl": {
+                "type": "string",
+                "description": "direct: default https://api.tavily.com. deeproute: Console API origin only (e.g. http://host:20316); plugin appends /api/mirror/{provider}. Legacy full mirror paths still work."
+              },
+              "searchDepth": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "basic"
+                  },
+                  {
+                    "type": "string",
+                    "const": "advanced"
+                  }
+                ],
+                "description": "Tavily search depth."
+              },
+              "includeAnswer": {
+                "type": "boolean",
+                "description": "Include Tavily synthesized answer when available."
+              }
+            }
+          },
+          "jina": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Set false to disable a configured provider. Omitted providers are disabled."
+              },
+              "auth": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "direct"
+                  },
+                  {
+                    "type": "string",
+                    "const": "deeproute"
+                  }
+                ],
+                "description": "direct: POST https://s.jina.ai/ with Jina API key. deeproute: POST {baseUrl}/mirror/jina/s with user sk; Console must store valid Jina API key."
+              },
+              "apiKey": {
+                "type": "string",
+                "description": "direct: Jina API key (required). deeproute: New API user sk; vendor Jina key must be in Console 扩展服务."
+              },
+              "baseUrl": {
+                "type": "string",
+                "description": "deeproute: deeproute: Console API origin only (e.g. http://host:20316); plugin appends /api/mirror/{provider}. Legacy full mirror paths still work. direct: default https://s.jina.ai."
+              }
+            }
+          },
+          "minimax": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Set false to disable a configured provider. Omitted providers are disabled."
+              },
+              "auth": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "direct"
+                  },
+                  {
+                    "type": "string",
+                    "const": "deeproute"
+                  }
+                ],
+                "description": "direct: Bearer Token Plan key. deeproute: Bearer user sk; Console injects minimax key and region."
+              },
+              "apiKey": {
+                "type": "string",
+                "description": "direct: MiniMax Token Plan key. deeproute: New API user sk (Console injects minimax credentials)."
+              },
+              "baseUrl": {
+                "type": "string",
+                "description": "deeproute: deeproute: Console API origin only (e.g. http://host:20316); plugin appends /api/mirror/{provider}. Legacy full mirror paths still work. direct: api.minimax.io or api.minimaxi.com."
+              },
+              "region": {
+                "type": "string",
+                "description": "direct only: \"global\" (default) or \"cn\" for upstream host."
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "activation": {
+    "onStartup": true
+  },
+  "skills": [
+    "skills/qzhike-agent-search"
+  ],
+  "contracts": {
+    "tools": [
+      "qzhike_search",
+      "qzhike_read_url"
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@qzhike/agent-search",
+  "version": "1.0.1",
+  "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",
+  "main": "./dist/index.js",
+  "dependencies": {
+    "typebox": "^1.1.38"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.5.17"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -0,0 +1,90 @@
+---
+name: qzhike-agent-search
+description: >-
+  检索与读页编排：组织内知识库（RAGFlow）优先，公网多后端 fallback/concurrent，
+  已有 URL 用 Jina Reader 读全文。原生工具 qzhike_search、qzhike_read_url；
+  安装本插件后禁用 web_search。
+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`**。
+
+# 检索与读页工作流（原生工具）
+
+## 何时用哪个工具
+
+| 用户意图 | 工具 | 说明 |
+|---|---|---|
+| 组织内文档、知识库、法规/内部资料 | **`qzhike_search`** | 配置中将 **`ragflow`** 置于 **`fallback`** 首位或 **`concurrent`** 列表 |
+| 公网新闻、技术资料、开放信息 | **`qzhike_search`** | 使用 brave / tavily / searxng / kimi 等已配置 provider |
+| 搜索结果或用户给出的链接需要全文 | **`qzhike_read_url`** | Jina Reader；**不要**用 search 代替读页 |
+| 仅有一个明确 URL | **`qzhike_read_url`** | 直接读 URL |
+
+**禁止**：在本插件已启用且 `tools.deny` 含 **`web_search`** 时，仍调用内置 **`web_search`**。
+
+---
+
+## Agent 必须遵守的顺序
+
+```
+收到问题
+  │
+  ├─ 用户已给出 URL 且只需全文？
+  │   └─ 是 → qzhike_read_url({ url })
+  │
+  ├─ 需要检索（含知识库 / 公网）？
+  │   └─ 是 → qzhike_search({ query: 用户完整原话或精炼检索词 })
+  │       ├─ 组织内 / 合规 / 内部文档优先：fallback 中 ragflow 在前
+  │       ├─ 单次可指定 provider: "ragflow" 等强制 backend
+  │       └─ 若返回 attempts 全失败 → 告知用户并引用 attempts 中的 error
+  │
+  └─ 从 search 结果中选出需精读的 URL
+      └─ qzhike_read_url({ url })（按需，勿一次读过多链接）
+```
+
+### 与 `qzhike_search` 编排模式
+
+- **`fallback`**（默认）：按 config 中 **`fallback`** 顺序线性尝试，首个成功即返回。
+- **`concurrent`**：并行调用 **`concurrent`** 列表中的 provider，合并去重结果。
+- 单次调用可用参数 **`searchMode`** / **`provider`** 覆盖 config。
+
+**RAGFlow**：是 **`qzhike_search`** 的一个 provider，**不是**独立工具；deeproute 模式下 **`dataset_ids`** 由 DeepRoute Console 注入，插件 config **勿写** `datasetIds`。
+
+---
+
+## 与 `TOOLS.md` 配合
+
+在 **`~/.openclaw/workspace/TOOLS.md`** 可写入例如：
+
+```markdown
+## 检索
+- 凡需查资料、知识库、公网信息：第一条检索工具必须是 `qzhike_search`。
+- 已有 URL 需全文：使用 `qzhike_read_url`。
+- 勿使用 `web_search`（已由配置 deny）。
+```
+
+Skill 管流程与工具选择；TOOLS.md 强化调用顺序。
+
+---
+
+## 输出与引用
+
+- **`qzhike_search`** 成功时返回 **`results`**、**`content`**、**`citations`**（视 provider 而定）；正文来自 **`externalContent`**（**`untrusted: true`**），引用时说明来源 provider / URL。
+- **`qzhike_read_url`** 返回 **`content`**（Markdown 正文）与 **`title`**。
+- 工具失败时阅读 **`error`** / **`message`** / **`attempts`**，勿编造检索结果。
+
+---
+
+## 禁止事项
+
+- 跳过已配置的 **`qzhike_search`** 链，直接凭模型常识充当检索结果。
+- 用 **`qzhike_search` + provider jina** 代替 **`qzhike_read_url`** 读单一 URL 全文（职责不同）。
+- 重复 symlink 同名 Skill 到 **`~/.openclaw/skills/qzhike-agent-search`**（与 bundled Skill 冲突）。
+
+---
+
+## 延伸阅读
+
+- 包内 **`README.md`**：安装、DeepRoute 扩展服务映射、配置示例。
+- 仓库 **`examples/openclaw.config.json5`**：完整 fallback / concurrent 与全 provider 模板。