@qzhike/agent-search 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qzhike
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @qzhike/agent-search
+
+OpenClaw 插件：为 Agent 提供 **原生工具** `qzhike_search`（多后端检索 + RAGFlow 知识库）与 `qzhike_read_url`（Jina Reader 读页）。安装后随包加载 Skill **`qzhike-agent-search`**，指导工具路由与编排。
+
+## 工具
+
+| 工具 | 用途 |
+|---|---|
+| **`qzhike_search`** | 知识库（RAGFlow）+ 公网搜索；支持 fallback / concurrent |
+| **`qzhike_read_url`** | 给定 URL 拉取可读 Markdown 正文 |
+
+配置路径：`plugins.entries.qzhike-agent-search.config`（OpenClaw 解析 `${ENV}`；**插件不读** `process.env`）。
+
+## 安装
+
+```bash
+openclaw plugins install @qzhike/agent-search
+openclaw gateway restart
+openclaw plugins inspect qzhike-agent-search --runtime --json
+```
+
+本地路径（开发）：
+
+```bash
+openclaw plugins install --link /absolute/path/to/qzhike-agent-search
+```
+
+## OpenClaw 配置
+
+### 启用插件与工具
+
+```json5
+{
+  plugins: {
+    allow: ["qzhike-agent-search"],
+    entries: {
+      "qzhike-agent-search": {
+        enabled: true,
+        config: {
+          searchMode: "fallback",
+          fallback: ["ragflow", "searxng", "brave", "tavily"],
+          providers: {
+            ragflow: {
+              auth: "deeproute",
+              baseUrl: "${DEEPROUTE_CONSOLE_URL}",
+              apiKey: "${DEEPROUTE_API_KEY}",
+            },
+            brave: {
+              auth: "deeproute",
+              baseUrl: "${DEEPROUTE_CONSOLE_URL}",
+              apiKey: "${DEEPROUTE_API_KEY}",
+            },
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    allow: ["qzhike_search", "qzhike_read_url"],
+    deny: ["web_search"],
+  },
+}
+```
+
+在 `~/.openclaw/.env` 中设置 `DEEPROUTE_CONSOLE_URL`、`DEEPROUTE_API_KEY` 等占位符。更完整的 DeepRoute 全 provider 模板见开源仓库 **`examples/openclaw.config.json5`**（npm 包内不含该文件）。
+
+### DeepRoute 扩展服务（凭据托管）
+
+插件 `auth: "deeproute"` 时，只需 Console **origin + user `sk`**；厂商 Key、RAGFlow `dataset_ids`、SearXNG Base URL 等在 Console **扩展服务**入库。
+
+| 插件 provider | Console 扩展服务键 |
+|---|---|
+| `ragflow` | `ragflow_base_url`、`ragflow`、`ragflow_dataset_ids` |
+| `searxng` | `searxng` |
+| `brave` / `tavily` / `serper` / `metaso` / `zai` / `exa` / `jina` / `minimax` | 同名键 |
+| `kimi` | 不走 mirror；`baseUrl`: `{Console}/api/v1` + 同一 user `sk` |
+
+## Bundled Skill
+
+本包含 **`skills/qzhike-agent-search/SKILL.md`**，在 `openclaw.plugin.json` 中声明；**启用插件并 restart Gateway 后自动加载**，一般无需再 symlink 到 `~/.openclaw/skills/`。
+
+Skill 约定：
+
+- 检索类问题优先 **`qzhike_search`**（组织内文档 → 将 `ragflow` 放在 `fallback` 前列）
+- 已有 URL 需全文 → **`qzhike_read_url`**
+- 已安装本插件时 **`deny: ["web_search"]`**，避免与内置搜索冲突
+
+可在 `~/.openclaw/workspace/TOOLS.md` 中强化路由规则（见 Skill 正文）。
+
+## 工具 API（摘要）
+
+### `qzhike_search`
+
+| 参数 | 说明 |
+|---|---|
+| `query` | 必填，检索词 |
+| `count` | 可选，1–10 |
+| `searchMode` | 可选，`fallback` / `concurrent` |
+| `provider` | 可选，强制单一 backend |
+
+### `qzhike_read_url`
+
+| 参数 | 说明 |
+|---|---|
+| `url` | 必填，HTTP(S) URL |
+
+## 排错
+
+| 现象 | 检查 |
+|---|---|
+| 工具未出现 | `plugins.allow` 含 `qzhike-agent-search`；`tools.allow` 含两个工具名 |
+| provider 被跳过 | `plugins.entries.qzhike-agent-search.config.providers.*` 是否配齐 |
+| RAGFlow 无结果 | Console 扩展服务 `ragflow_*`；deeproute 下勿在插件 config 写 `dataset_ids` |
+| 改配置不生效 | `openclaw gateway restart` 并新开会话 |
+
+## 要求
+
+- Node >= 22
+- OpenClaw >= 2026.5.17
+
+## License
+
+MIT

package/dist/adapters/brave-config.js

@@ -0,0 +1,46 @@
+import { configString, trimTrailingSlashes } from "../http.js";
+import { resolveDeeprouteMirrorRoot } from "./deeproute-mirror.js";
+import { resolveProviderAuthMode } from "./provider-auth.js";
+export const DEFAULT_BRAVE_DIRECT_BASE = "https://api.search.brave.com";
+export const BRAVE_WEB_SEARCH_PATH = "/res/v1/web/search";
+export function resolveBraveAuthMode(auth) {
+    return resolveProviderAuthMode(auth);
+}
+export function resolveBraveBaseUrl(cfg, auth) {
+    const configured = configString(cfg?.baseUrl);
+    if (configured) {
+        if (auth === "deeproute") {
+            return resolveDeeprouteMirrorRoot(configured, "brave");
+        }
+        return trimTrailingSlashes(configured);
+    }
+    if (auth === "direct") {
+        return DEFAULT_BRAVE_DIRECT_BASE;
+    }
+    return undefined;
+}
+export function buildBraveSearchUrl(baseUrl, query, count, extra) {
+    const url = new URL(`${baseUrl}${BRAVE_WEB_SEARCH_PATH}`);
+    url.searchParams.set("q", query);
+    url.searchParams.set("count", String(count));
+    const country = extra?.country?.trim();
+    if (country) {
+        url.searchParams.set("country", country);
+    }
+    const freshness = extra?.freshness?.trim();
+    if (freshness) {
+        url.searchParams.set("freshness", freshness);
+    }
+    return url.toString();
+}
+export function buildBraveRequestHeaders(auth, apiKey) {
+    const headers = { Accept: "application/json" };
+    if (auth === "deeproute") {
+        headers.Authorization = `Bearer ${apiKey}`;
+    }
+    else {
+        headers["X-Subscription-Token"] = apiKey;
+    }
+    return headers;
+}
+//# sourceMappingURL=brave-config.js.map

package/dist/adapters/brave.js

@@ -0,0 +1,83 @@
+import { configString, fetchJson } from "../http.js";
+import { formatResultsAsContent, resolveTimeoutSeconds } from "../result.js";
+import { buildBraveRequestHeaders, buildBraveSearchUrl, resolveBraveAuthMode, resolveBraveBaseUrl, } from "./brave-config.js";
+export async function searchBrave(config, query, count, signal, runOptions) {
+    const provider = "brave";
+    const cfg = config.providers?.brave;
+    const auth = resolveBraveAuthMode(cfg?.auth);
+    if (!auth) {
+        return {
+            ok: false,
+            provider,
+            error: "invalid_auth",
+            message: 'Invalid providers.brave.auth. Use "direct" (Brave API) or "deeproute" (Console mirror).',
+        };
+    }
+    const apiKey = configString(cfg?.apiKey);
+    if (!apiKey) {
+        return {
+            ok: false,
+            provider,
+            error: "missing_api_key",
+            message: auth === "deeproute"
+                ? "deeproute: set providers.brave.apiKey to your New API user sk (Bearer)."
+                : "direct: set providers.brave.apiKey to your Brave X-Subscription-Token.",
+        };
+    }
+    const baseUrl = resolveBraveBaseUrl(cfg, auth);
+    if (!baseUrl) {
+        return {
+            ok: false,
+            provider,
+            error: "missing_base_url",
+            message: "deeproute: set providers.brave.baseUrl (e.g. http://host:20316/api/mirror/brave).",
+        };
+    }
+    const url = buildBraveSearchUrl(baseUrl, query, count, {
+        country: runOptions?.brave?.country ?? cfg?.country,
+        freshness: runOptions?.brave?.freshness ?? cfg?.freshness,
+    });
+    const startedAt = Date.now();
+    try {
+        const { data } = await fetchJson(url, {
+            method: "GET",
+            headers: buildBraveRequestHeaders(auth, apiKey),
+            timeoutSeconds: resolveTimeoutSeconds(config),
+            signal,
+        });
+        const raw = Array.isArray(data.web?.results) ? data.web.results : [];
+        const results = raw.slice(0, count).map((entry) => ({
+            title: entry.title ?? "",
+            url: entry.url ?? "",
+            snippet: entry.description ?? "",
+            siteName: entry.url ? safeHostname(entry.url) : undefined,
+        }));
+        const citations = [...new Set(results.map((r) => r.url).filter(Boolean))];
+        return {
+            ok: true,
+            provider,
+            query,
+            tookMs: Date.now() - startedAt,
+            results,
+            citations,
+            content: formatResultsAsContent(results),
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            provider,
+            error: "brave_request_failed",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function safeHostname(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=brave.js.map

package/dist/adapters/deeproute-mirror.js

@@ -0,0 +1,31 @@
+import { trimTrailingSlashes } from "../http.js";
+/**
+ * Resolve mirror root for `auth: "deeproute"`.
+ * Accepts Console **origin only** (`http://host:20316`) or legacy full path
+ * (`…/api/mirror/{provider}`) for backward compatibility.
+ */
+export function resolveDeeprouteMirrorRoot(baseUrl, provider) {
+    const trimmed = trimTrailingSlashes(baseUrl.trim());
+    const mirrorSuffix = `/api/mirror/${provider}`;
+    if (trimmed.endsWith(mirrorSuffix)) {
+        return trimmed;
+    }
+    try {
+        const href = trimmed.includes("://") ? trimmed : `http://${trimmed}`;
+        const u = new URL(href);
+        const path = u.pathname.replace(/\/$/, "") || "";
+        if (path === mirrorSuffix || path.endsWith(mirrorSuffix)) {
+            return `${u.origin}${path}`;
+        }
+        return `${u.origin}${mirrorSuffix}`;
+    }
+    catch {
+        return `${trimmed}${mirrorSuffix}`;
+    }
+}
+export function joinMirrorPath(mirrorRoot, upstreamPath) {
+    const root = trimTrailingSlashes(mirrorRoot);
+    const path = upstreamPath.startsWith("/") ? upstreamPath : `/${upstreamPath}`;
+    return `${root}${path}`;
+}
+//# sourceMappingURL=deeproute-mirror.js.map

package/dist/adapters/exa-config.js

@@ -0,0 +1,35 @@
+import { configString, trimTrailingSlashes } from "../http.js";
+import { joinMirrorPath, resolveDeeprouteMirrorRoot, } from "./deeproute-mirror.js";
+import { buildDeeprouteBearerHeaders, resolveProviderAuthMode, } from "./provider-auth.js";
+export const DEFAULT_EXA_DIRECT_BASE = "https://api.exa.ai";
+export const EXA_SEARCH_PATH = "/search";
+export function resolveExaAuthMode(auth) {
+    return resolveProviderAuthMode(auth);
+}
+export function resolveExaSearchUrl(cfg, auth) {
+    const configured = configString(cfg?.baseUrl);
+    if (auth === "deeproute") {
+        if (!configured)
+            return undefined;
+        const root = resolveDeeprouteMirrorRoot(configured, "exa");
+        return joinMirrorPath(root, EXA_SEARCH_PATH);
+    }
+    const base = configured
+        ? trimTrailingSlashes(configured)
+        : DEFAULT_EXA_DIRECT_BASE;
+    return joinMirrorPath(base, EXA_SEARCH_PATH);
+}
+export function buildExaRequestHeaders(auth, apiKey) {
+    const headers = {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+    };
+    if (auth === "deeproute") {
+        Object.assign(headers, buildDeeprouteBearerHeaders(apiKey));
+    }
+    else {
+        headers["x-api-key"] = apiKey;
+    }
+    return headers;
+}
+//# sourceMappingURL=exa-config.js.map

package/dist/adapters/exa.js

@@ -0,0 +1,91 @@
+import { configString, fetchJson } from "../http.js";
+import { formatResultsAsContent, resolveTimeoutSeconds } from "../result.js";
+import { buildExaRequestHeaders, resolveExaAuthMode, resolveExaSearchUrl, } from "./exa-config.js";
+export async function searchExa(config, query, count, signal) {
+    const provider = "exa";
+    const cfg = config.providers?.exa;
+    const auth = resolveExaAuthMode(cfg?.auth);
+    if (!auth) {
+        return {
+            ok: false,
+            provider,
+            error: "invalid_auth",
+            message: 'Invalid providers.exa.auth. Use "direct" or "deeproute".',
+        };
+    }
+    const apiKey = configString(cfg?.apiKey);
+    if (!apiKey) {
+        return {
+            ok: false,
+            provider,
+            error: "missing_api_key",
+            message: auth === "deeproute"
+                ? "deeproute: set providers.exa.apiKey to your DeepRoute user sk."
+                : "direct: set providers.exa.apiKey to your Exa API key.",
+        };
+    }
+    const url = resolveExaSearchUrl(cfg, auth);
+    if (!url) {
+        return {
+            ok: false,
+            provider,
+            error: "missing_base_url",
+            message: "deeproute: set providers.exa.baseUrl to Console origin (e.g. http://host:20316).",
+        };
+    }
+    const startedAt = Date.now();
+    try {
+        const { data } = await fetchJson(url, {
+            method: "POST",
+            headers: buildExaRequestHeaders(auth, apiKey),
+            body: {
+                query,
+                numResults: count,
+                type: "auto",
+                useAutoprompt: true,
+                contents: { highlights: { maxCharacters: 500 } },
+            },
+            timeoutSeconds: resolveTimeoutSeconds(config),
+            signal,
+        });
+        const raw = Array.isArray(data.results) ? data.results : [];
+        const results = raw.slice(0, count).map((entry) => {
+            const snippet = Array.isArray(entry.highlights) && entry.highlights.length > 0
+                ? entry.highlights.join(" ")
+                : (entry.text ?? "");
+            return {
+                title: entry.title ?? "",
+                url: entry.url ?? "",
+                snippet,
+                siteName: entry.url ? safeHostname(entry.url) : undefined,
+            };
+        });
+        const citations = [...new Set(results.map((r) => r.url).filter(Boolean))];
+        return {
+            ok: true,
+            provider,
+            query,
+            tookMs: Date.now() - startedAt,
+            results,
+            citations,
+            content: formatResultsAsContent(results),
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            provider,
+            error: "exa_request_failed",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function safeHostname(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=exa.js.map

package/dist/adapters/jina-config.js

@@ -0,0 +1,102 @@
+import { configString, trimTrailingSlashes } from "../http.js";
+import { joinMirrorPath, resolveDeeprouteMirrorRoot, } from "./deeproute-mirror.js";
+import { buildDeeprouteBearerHeaders, resolveProviderAuthMode, } from "./provider-auth.js";
+export const DEFAULT_JINA_SEARCH_DIRECT_BASE = "https://s.jina.ai";
+export const DEFAULT_JINA_READER_DIRECT_BASE = "https://r.jina.ai";
+export const JINA_SEARCH_MIRROR_SUFFIX = "/s";
+export const JINA_READER_MIRROR_PREFIX = "/r";
+export function resolveJinaAuthMode(auth) {
+    return resolveProviderAuthMode(auth);
+}
+export function resolveJinaSearchBaseUrl(cfg, auth) {
+    const configured = configString(cfg?.baseUrl);
+    if (configured) {
+        if (auth === "deeproute") {
+            return resolveDeeprouteMirrorRoot(configured, "jina");
+        }
+        return trimTrailingSlashes(configured);
+    }
+    if (auth === "direct") {
+        return DEFAULT_JINA_SEARCH_DIRECT_BASE;
+    }
+    return undefined;
+}
+export function resolveJinaSearchUrl(baseUrl, auth) {
+    if (auth === "deeproute") {
+        return joinMirrorPath(baseUrl, JINA_SEARCH_MIRROR_SUFFIX);
+    }
+    const trimmed = trimTrailingSlashes(baseUrl || DEFAULT_JINA_SEARCH_DIRECT_BASE);
+    try {
+        const url = new URL(trimmed);
+        if (url.hostname.toLowerCase() === "s.jina.ai") {
+            url.pathname = url.pathname === "" ? "/" : url.pathname;
+            return url.toString();
+        }
+        url.pathname = `${url.pathname.replace(/\/$/, "")}/`;
+        return url.toString();
+    }
+    catch {
+        return `${DEFAULT_JINA_SEARCH_DIRECT_BASE}/`;
+    }
+}
+export function resolveJinaReaderBaseUrl(cfg, auth) {
+    const configured = configString(cfg?.baseUrl);
+    if (configured) {
+        if (auth === "deeproute") {
+            return resolveDeeprouteMirrorRoot(configured, "jina");
+        }
+        return trimTrailingSlashes(configured);
+    }
+    if (auth === "direct") {
+        return DEFAULT_JINA_READER_DIRECT_BASE;
+    }
+    return undefined;
+}
+/** Build GET URL for Jina Reader (direct r.jina.ai or DeepRoute /api/mirror/jina/r/…). */
+export function resolveJinaReaderUrl(baseUrl, auth, targetPageUrl) {
+    const encoded = encodeURI(targetPageUrl.trim());
+    if (auth === "deeproute") {
+        return joinMirrorPath(baseUrl, `${JINA_READER_MIRROR_PREFIX}/${encoded}`);
+    }
+    const root = trimTrailingSlashes(baseUrl || DEFAULT_JINA_READER_DIRECT_BASE);
+    try {
+        const url = new URL(root);
+        if (url.hostname.toLowerCase() === "r.jina.ai") {
+            return `${url.origin}/${encoded}`;
+        }
+        return `${root}/${encoded}`;
+    }
+    catch {
+        return `${DEFAULT_JINA_READER_DIRECT_BASE}/${encoded}`;
+    }
+}
+export function buildJinaReaderRequestHeaders(auth, apiKey) {
+    const headers = { Accept: "application/json" };
+    if (auth === "deeproute") {
+        if (apiKey) {
+            Object.assign(headers, buildDeeprouteBearerHeaders(apiKey));
+        }
+        return headers;
+    }
+    if (apiKey) {
+        headers.Authorization = `Bearer ${apiKey}`;
+    }
+    return headers;
+}
+export function buildJinaSearchRequestHeaders(auth, apiKey) {
+    const headers = {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+    };
+    if (auth === "deeproute") {
+        if (!apiKey) {
+            return headers;
+        }
+        Object.assign(headers, buildDeeprouteBearerHeaders(apiKey));
+    }
+    else if (apiKey) {
+        headers.Authorization = `Bearer ${apiKey}`;
+    }
+    return headers;
+}
+//# sourceMappingURL=jina-config.js.map

package/dist/adapters/jina-reader.js

@@ -0,0 +1,83 @@
+import { configString, fetchJson } from "../http.js";
+import { resolveTimeoutSeconds } from "../result.js";
+import { buildJinaReaderRequestHeaders, resolveJinaAuthMode, resolveJinaReaderBaseUrl, resolveJinaReaderUrl, } from "./jina-config.js";
+function extractReaderFields(data, fallbackUrl) {
+    const payload = data.data ?? data;
+    return {
+        title: payload.title?.trim() ?? "",
+        content: payload.content?.trim() ?? "",
+        url: payload.url?.trim() || fallbackUrl,
+    };
+}
+export async function readUrlWithJina(config, targetUrl, signal) {
+    const provider = "jina";
+    const cfg = config.providers?.jina;
+    const auth = resolveJinaAuthMode(cfg?.auth) ?? "direct";
+    const apiKey = configString(cfg?.apiKey);
+    if (auth === "deeproute" && !apiKey) {
+        return {
+            ok: false,
+            provider,
+            error: "missing_api_key",
+            message: "deeproute: set providers.jina.apiKey to your DeepRoute user sk (Bearer). Reader does not require a Console Jina vendor key.",
+        };
+    }
+    const baseUrl = resolveJinaReaderBaseUrl(cfg, auth);
+    if (!baseUrl) {
+        return {
+            ok: false,
+            provider,
+            error: "missing_base_url",
+            message: "deeproute: set providers.jina.baseUrl to Console origin (e.g. http://host:20316).",
+        };
+    }
+    let normalizedTarget;
+    try {
+        normalizedTarget = new URL(targetUrl).toString();
+    }
+    catch {
+        return {
+            ok: false,
+            provider,
+            error: "invalid_url",
+            message: `Invalid URL: ${targetUrl}`,
+        };
+    }
+    const url = resolveJinaReaderUrl(baseUrl, auth, normalizedTarget);
+    const startedAt = Date.now();
+    try {
+        const { data, text } = await fetchJson(url, {
+            method: "GET",
+            headers: buildJinaReaderRequestHeaders(auth, apiKey),
+            timeoutSeconds: resolveTimeoutSeconds(config),
+            signal,
+        });
+        const { title, content, url: resolvedUrl, } = extractReaderFields(data, normalizedTarget);
+        const bodyText = content || (text && !content ? text.slice(0, 500_000) : "");
+        if (!bodyText.trim()) {
+            return {
+                ok: false,
+                provider,
+                error: "empty_content",
+                message: "Jina Reader returned no content for this URL.",
+            };
+        }
+        return {
+            ok: true,
+            provider,
+            url: resolvedUrl,
+            tookMs: Date.now() - startedAt,
+            title,
+            content: bodyText,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            provider,
+            error: "jina_reader_failed",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+//# sourceMappingURL=jina-reader.js.map