@iflow-ai/iflow-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iflow-ai
+
+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,209 @@
+# @iflow-ai/iflow-plugin
+
+[iFlow Search (心流搜索)](https://platform.iflow.cn) plugin for [OpenClaw](https://docs.openclaw.ai).
+
+Three agent tools backed by iFlow's `/api/search/*` endpoints:
+
+| Tool | Purpose |
+|---|---|
+| `iflow_web_search` | Public web search with structured results (title / url / snippet / position / date). |
+| `iflow_image_search` | Image search with source-page attribution. |
+| `iflow_web_fetch` | Read the clean content of a single web page. |
+
+The plugin also registers `iflow` as a `web_search` provider so users can route
+the managed `web_search` tool through iFlow with one config line — this is
+**best-effort** and activates only if the running OpenClaw exposes the
+provider-registration API; otherwise the plugin runs in tools-only mode.
+
+## Install
+
+```bash
+openclaw plugins install @iflow-ai/iflow-plugin
+openclaw gateway restart
+```
+
+Or from a local checkout (during development):
+
+```bash
+git clone <repo> ~/.openclaw/extensions/iflow-plugin
+cd ~/.openclaw/extensions/iflow-plugin
+npm install --omit=dev
+openclaw gateway restart
+```
+
+## Configuration
+
+### 1. API key
+
+Get one from the [iFlow Open Platform](https://platform.iflow.cn).
+
+Either set the env var:
+
+```bash
+export IFLOW_API_KEY=sk-...
+```
+
+Or put it in `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      iflow: {
+        enabled: true,
+        config: {
+          webSearch: {
+            apiKey: "sk-...",     // sensitive; can also be a SecretRef object
+            baseUrl: "https://platform.iflow.cn",  // optional override
+            timeoutSeconds: 30,    // optional, default 30
+            cacheTtlMinutes: 15    // optional, default 15; set 0 to disable
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### 2. Route managed `web_search` through iFlow (optional)
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "iflow"
+      }
+    }
+  }
+}
+```
+
+If your OpenClaw runtime does not support third-party `web_search` providers,
+this line has no effect — the explicit tools below still work.
+
+## Tools
+
+### `iflow_web_search`
+
+| Param | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `query` | string | yes | — | Sent as iFlow `keywords` |
+| `count` | number | no | 10 | Clamped to `[1, 10]`. Sent as iFlow `num` |
+
+Returns:
+
+```json
+{
+  "query": "...",
+  "provider": "iflow",
+  "count": 3,
+  "tookMs": 1383,
+  "results": [
+    { "title": "...", "url": "...", "snippet": "...", "position": 1, "date": null }
+  ]
+}
+```
+
+### `iflow_image_search`
+
+| Param | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `query` | string | yes | — | Sent as iFlow `keywords` |
+| `count` | number | no | 10 | Clamped to `[1, 20]`. Sent as iFlow `num` |
+
+Returns:
+
+```json
+{
+  "query": "...",
+  "provider": "iflow",
+  "count": 3,
+  "tookMs": 1715,
+  "images": [
+    { "url": "...jpg", "title": "...", "sourceUrl": "..." }
+  ]
+}
+```
+
+### `iflow_web_fetch`
+
+| Param | Type | Required | Notes |
+|---|---|---|---|
+| `url` | string | yes | Must be an http(s) URL |
+
+Returns:
+
+```json
+{
+  "title": "...",
+  "url": "...",
+  "content": "...",
+  "fromCache": true,
+  "provider": "iflow",
+  "tookMs": 335
+}
+```
+
+## Local development
+
+```bash
+npm install
+npm run typecheck     # tsc --noEmit
+npm test              # vitest (uses mocked fetch, no live API calls)
+
+# Optional: live probe of all three endpoints.
+# Reads IFLOW_API_KEY from the env. Does NOT log the key.
+IFLOW_API_KEY=sk-... npm run smoke
+IFLOW_API_KEY=sk-... npm run smoke web     # web only
+IFLOW_API_KEY=sk-... npm run smoke image
+IFLOW_API_KEY=sk-... npm run smoke fetch
+```
+
+To exercise the plugin inside a real OpenClaw gateway:
+
+```bash
+# 1. Pack and install from the local build
+npm pack
+openclaw plugins install npm-pack:./iflow-ai-iflow-plugin-0.1.0.tgz
+openclaw gateway restart
+
+# 2. Verify what was registered
+openclaw plugins inspect iflow --runtime --json
+```
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Every call returns `missing_api_key` | Env var not loaded by the gateway | Restart gateway after exporting `IFLOW_API_KEY`, or put the key in `openclaw.json` |
+| `api_error` with `status: 401` | Wrong / revoked key | Rotate the key on the iFlow platform |
+| `api_error` with `status: 403` | Account not entitled to this endpoint | Check the iFlow plan / contact iFlow support |
+| `api_error` with `status: 429` | Rate limit | Lower request rate; the plugin caches identical queries for `cacheTtlMinutes` |
+| `network_timeout` | Slow upstream / cold cache | Increase `timeoutSeconds`; retry |
+| `api_business_error` with code `4xxx` | iFlow returned `success: false` | Inspect `message` / `code` in the error payload |
+| Results have a `url` field on iFlow but show as empty | iFlow renamed `link` → `url` (or similar) | Update `src/normalize.ts` mapping; tests in `src/__tests__/normalize.test.ts` show where |
+| Plugin loads but `web_search` doesn't route through iFlow | OpenClaw runtime doesn't expose `registerWebSearchProvider` (info log will say so) | Use the explicit `iflow_web_search` tool instead, or upgrade OpenClaw |
+
+## Compatibility
+
+- `peerDependency`: `openclaw >= 2025.0.0` (optional)
+- **Tools mode** (3 explicit tools): always on.
+- **Provider mode** (managed `web_search` routing): activates only when the
+  runtime exposes `api.registerWebSearchProvider` AND the SDK subpath
+  `openclaw/plugin-sdk/provider-web-search-config-contract` is importable.
+  Failure is logged at info level; the plugin keeps working in tools mode.
+
+## Acknowledgements
+
+This plugin includes an OpenClaw-specific skill definition under
+`skills/iflow-search/SKILL.md`. It is adapted from the official iFlow skill
+catalog, but uses OpenClaw tool names and normalized parameters / return
+fields instead of the upstream shell-script interface.
+
+Official iFlow skill reference:
+https://github.com/iflow-ai/iflow-skills/tree/main/skills/iflow-search
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,81 @@
+/**
+ * @iflow-ai/iflow-plugin — iFlow Search plugin for OpenClaw.
+ *
+ * Capability tiers:
+ *   - Tools mode (stable):  iflow_web_search, iflow_image_search, iflow_web_fetch
+ *                           registered via api.registerTool.
+ *   - Provider mode (best-effort): iflow registered as a web_search provider
+ *                           via api.registerWebSearchProvider, only when the
+ *                           running OpenClaw runtime exposes that API AND the
+ *                           openclaw/plugin-sdk/provider-web-search-config-contract
+ *                           subpath is importable.
+ *
+ * Both modes share the same HTTP client and normalize layer.
+ */
+import { resolveConfig, redactApiKey } from "./src/config.js";
+import { createIflowClient } from "./src/client.js";
+import { createImageSearchTool, createWebFetchTool, createWebSearchTool, } from "./src/tools.js";
+import { createIflowWebSearchProvider } from "./src/web-search-provider.js";
+const PLUGIN_ID = "iflow";
+const iflowPlugin = {
+    id: PLUGIN_ID,
+    name: "iFlow Search",
+    description: "iFlow Search (心流搜索) — web search, image search, and web content fetch tools for OpenClaw agents.",
+    kind: "tools",
+    register(api) {
+        const cfg = resolveConfig(api.pluginConfig);
+        if (!cfg.apiKey) {
+            api.logger.warn("iflow: no API key found. Set IFLOW_API_KEY or plugins.entries.iflow.config.webSearch.apiKey. Plugin idle.");
+            api.registerService({
+                id: PLUGIN_ID,
+                start: () => api.logger.info("iflow: idle (no API key)"),
+                stop: () => { },
+            });
+            return;
+        }
+        const client = createIflowClient({ config: cfg, logger: api.logger });
+        api.logger.info(`iflow: initialized (baseUrl=${cfg.baseUrl}, timeout=${Math.round(cfg.timeoutMs / 1000)}s, cacheTtl=${Math.round(cfg.cacheTtlMs / 60_000)}min, apiKey=${redactApiKey(cfg.apiKey)})`);
+        // Tier 1 — tools mode (stable baseline)
+        registerTools(api, client);
+        // Tier 2 — provider mode (best-effort)
+        void tryRegisterProvider(api, client).catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            api.logger.info(`iflow: provider mode unavailable, staying in tools-only mode (${msg})`);
+        });
+        api.registerService({
+            id: PLUGIN_ID,
+            start: () => api.logger.info("iflow: service started"),
+            stop: () => {
+                client.clearCache();
+                api.logger.info("iflow: service stopped, cache cleared");
+            },
+        });
+    },
+};
+function registerTools(api, client) {
+    api.registerTool(createWebSearchTool(client), { source: PLUGIN_ID });
+    api.registerTool(createImageSearchTool(client), { source: PLUGIN_ID });
+    api.registerTool(createWebFetchTool(client), { source: PLUGIN_ID });
+}
+async function tryRegisterProvider(api, client) {
+    if (typeof api.registerWebSearchProvider !== "function") {
+        throw new Error("registerWebSearchProvider not exposed by this OpenClaw runtime");
+    }
+    // Dynamic import: a missing subpath becomes a caught promise rejection,
+    // not a module-load error for this plugin.
+    const sdk = (await import(
+    /* @vite-ignore */ "openclaw/plugin-sdk/provider-web-search-config-contract").catch((err) => {
+        throw new Error(`openclaw/plugin-sdk/provider-web-search-config-contract not importable: ${err instanceof Error ? err.message : String(err)}`);
+    }));
+    const factory = sdk.createWebSearchProviderContractFields;
+    if (typeof factory !== "function") {
+        throw new Error("createWebSearchProviderContractFields not exported by the SDK subpath");
+    }
+    const provider = createIflowWebSearchProvider({
+        client,
+        createContractFields: factory,
+    });
+    api.registerWebSearchProvider(provider);
+    api.logger.info("iflow: registered as web_search provider (best-effort)");
+}
+export default iflowPlugin;

package/dist/src/client.js

@@ -0,0 +1,181 @@
+/**
+ * HTTP client for the iFlow Search API.
+ *
+ * Responsibilities:
+ *   - Build Bearer-authenticated POST requests
+ *   - Enforce per-request timeout via AbortController
+ *   - Classify failures into the IflowError taxonomy
+ *   - Maintain a small in-memory cache (15-minute default) keyed by call params
+ *   - Never log or echo the API key
+ */
+import { apiBusinessError, apiHttpError, isIflowError, networkError, networkTimeoutError, } from "./errors.js";
+const MAX_CACHE_ENTRIES = 100;
+const ENDPOINTS = {
+    webSearch: "/api/search/webSearch",
+    imageSearch: "/api/search/imageSearch",
+    webFetch: "/api/search/webFetch",
+};
+export function createIflowClient(opts) {
+    const { config, logger } = opts;
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const now = opts.now ?? Date.now;
+    if (typeof fetchImpl !== "function") {
+        throw new Error("createIflowClient: global fetch is not available; pass fetchImpl explicitly.");
+    }
+    const cache = new Map();
+    function readCache(key) {
+        if (config.cacheTtlMs <= 0)
+            return null;
+        const entry = cache.get(key);
+        if (!entry)
+            return null;
+        if (now() > entry.expiresAt) {
+            cache.delete(key);
+            return null;
+        }
+        // Refresh LRU position
+        cache.delete(key);
+        cache.set(key, entry);
+        return entry.value;
+    }
+    function writeCache(key, value) {
+        if (config.cacheTtlMs <= 0)
+            return;
+        if (cache.size >= MAX_CACHE_ENTRIES) {
+            const oldest = cache.keys().next();
+            if (!oldest.done)
+                cache.delete(oldest.value);
+        }
+        cache.set(key, { value, expiresAt: now() + config.cacheTtlMs });
+    }
+    async function call(endpoint, body, cacheKey, externalSignal) {
+        const start = now();
+        const cached = readCache(cacheKey);
+        if (cached) {
+            return { ok: true, data: cached, tookMs: 0, fromCache: true };
+        }
+        const url = `${config.baseUrl}${ENDPOINTS[endpoint]}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+        if (externalSignal) {
+            if (externalSignal.aborted)
+                controller.abort();
+            else
+                externalSignal.addEventListener("abort", () => controller.abort(), { once: true });
+        }
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${config.apiKey ?? ""}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const tookMs = now() - start;
+            const e = err;
+            if (e.name === "AbortError") {
+                logger.warn(`iflow ${endpoint}: timeout after ${tookMs}ms`);
+                return { ok: false, error: networkTimeoutError(config.timeoutMs), tookMs };
+            }
+            logger.warn(`iflow ${endpoint}: network error: ${e.message ?? String(err)}`);
+            return { ok: false, error: networkError(e.message ?? String(err)), tookMs };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const tookMs = now() - start;
+        if (!response.ok) {
+            let detail = "";
+            try {
+                detail = (await response.text()).slice(0, 500);
+            }
+            catch {
+                // ignore
+            }
+            logger.warn(`iflow ${endpoint}: HTTP ${response.status} (${tookMs}ms)`);
+            return {
+                ok: false,
+                error: apiHttpError(response.status, detail || response.statusText),
+                tookMs,
+            };
+        }
+        let parsed;
+        try {
+            parsed = await response.json();
+        }
+        catch (err) {
+            const e = err;
+            logger.warn(`iflow ${endpoint}: invalid JSON response: ${e.message ?? String(err)}`);
+            return {
+                ok: false,
+                error: { error: "api_error", status: response.status, message: "iFlow returned non-JSON response." },
+                tookMs,
+            };
+        }
+        const envelope = parsed;
+        if (envelope?.success !== true) {
+            const dataObj = envelope?.data && typeof envelope.data === "object" && !Array.isArray(envelope.data)
+                ? envelope.data
+                : undefined;
+            logger.warn(`iflow ${endpoint}: api business error code=${String(envelope?.code)} message=${String(envelope?.message)}`);
+            return {
+                ok: false,
+                error: apiBusinessError({
+                    code: envelope?.code ?? null,
+                    message: envelope?.message ?? null,
+                    errorMsg: dataObj?.errorMsg ?? null,
+                    errorCode: dataObj?.errorCode ?? null,
+                }),
+                tookMs,
+            };
+        }
+        writeCache(cacheKey, parsed);
+        return { ok: true, data: parsed, tookMs, fromCache: false };
+    }
+    function ensureKey() {
+        if (!config.apiKey) {
+            return {
+                ok: false,
+                error: {
+                    error: "missing_api_key",
+                    message: "iFlow Search needs an API key. Set IFLOW_API_KEY in the environment, or configure plugins.entries.iflow.config.webSearch.apiKey.",
+                },
+                tookMs: 0,
+            };
+        }
+        return null;
+    }
+    return {
+        async webSearch(query, num, signal) {
+            const missing = ensureKey();
+            if (missing)
+                return missing;
+            const key = `webSearch:${num}:${query.toLowerCase()}`;
+            return call("webSearch", { keywords: query, num }, key, signal);
+        },
+        async imageSearch(query, num, signal) {
+            const missing = ensureKey();
+            if (missing)
+                return missing;
+            const key = `imageSearch:${num}:${query.toLowerCase()}`;
+            return call("imageSearch", { keywords: query, num }, key, signal);
+        },
+        async webFetch(url, signal) {
+            const missing = ensureKey();
+            if (missing)
+                return missing;
+            const key = `webFetch:${url.toLowerCase()}`;
+            return call("webFetch", { url }, key, signal);
+        },
+        clearCache() {
+            cache.clear();
+        },
+    };
+}
+export { isIflowError };

package/dist/src/config.js

@@ -0,0 +1,55 @@
+/**
+ * Config resolution for the iFlow plugin.
+ *
+ * The plugin reads `pluginConfig.webSearch.*` and falls back to env vars
+ * for the API key. SecretRef objects (resolved by OpenClaw upstream) are
+ * tolerated by accepting `string | { value: string } | unknown`.
+ */
+export const DEFAULT_BASE_URL = "https://platform.iflow.cn";
+export const DEFAULT_TIMEOUT_SECONDS = 30;
+export const DEFAULT_CACHE_TTL_MINUTES = 15;
+export const ENV_API_KEY = "IFLOW_API_KEY";
+function readSecretString(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    if (value && typeof value === "object") {
+        const v = value.value;
+        if (typeof v === "string") {
+            const trimmed = v.trim();
+            return trimmed.length > 0 ? trimmed : undefined;
+        }
+    }
+    return undefined;
+}
+function readEnv(name) {
+    const v = process.env?.[name];
+    if (typeof v !== "string")
+        return undefined;
+    const trimmed = v.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export function resolveConfig(pluginConfig) {
+    const cfg = (pluginConfig ?? {});
+    const ws = cfg.webSearch ?? {};
+    const apiKey = readSecretString(ws.apiKey) ?? readEnv(ENV_API_KEY);
+    const rawBaseUrl = readSecretString(ws.baseUrl) ?? DEFAULT_BASE_URL;
+    const baseUrl = rawBaseUrl.replace(/\/+$/u, "") || DEFAULT_BASE_URL;
+    const timeoutSeconds = typeof ws.timeoutSeconds === "number" && Number.isFinite(ws.timeoutSeconds) && ws.timeoutSeconds > 0
+        ? ws.timeoutSeconds
+        : DEFAULT_TIMEOUT_SECONDS;
+    const timeoutMs = Math.round(timeoutSeconds * 1000);
+    const cacheTtlMinutes = typeof ws.cacheTtlMinutes === "number" && Number.isFinite(ws.cacheTtlMinutes) && ws.cacheTtlMinutes >= 0
+        ? ws.cacheTtlMinutes
+        : DEFAULT_CACHE_TTL_MINUTES;
+    const cacheTtlMs = Math.round(cacheTtlMinutes * 60_000);
+    return { apiKey, baseUrl, timeoutMs, cacheTtlMs };
+}
+export function redactApiKey(key) {
+    if (!key)
+        return "<unset>";
+    if (key.length <= 8)
+        return "***";
+    return `${key.slice(0, 4)}***${key.slice(-2)}`;
+}

package/dist/src/errors.js

@@ -0,0 +1,69 @@
+/**
+ * Error taxonomy for the iFlow plugin.
+ *
+ * Every failure path returns one of these tagged shapes so that the tool
+ * handler can render a consistent JSON payload back to the agent without
+ * leaking the API key or sensitive headers.
+ */
+export const IFLOW_ERROR_DOCS_URL = "https://platform.iflow.cn/docs/";
+export function missingApiKeyError() {
+    return {
+        error: "missing_api_key",
+        message: "iFlow Search needs an API key. Set IFLOW_API_KEY in the environment, or configure plugins.entries.iflow.config.webSearch.apiKey.",
+        docs: IFLOW_ERROR_DOCS_URL,
+    };
+}
+export function missingParamError(name) {
+    return {
+        error: "missing_param",
+        message: `Parameter "${name}" is required.`,
+    };
+}
+export function invalidParamError(name, detail) {
+    return {
+        error: "invalid_param",
+        message: `Parameter "${name}" is invalid: ${detail}`,
+    };
+}
+export function networkTimeoutError(timeoutMs) {
+    return {
+        error: "network_timeout",
+        message: `Request to iFlow timed out after ${Math.round(timeoutMs)}ms.`,
+    };
+}
+export function networkError(detail) {
+    return {
+        error: "network_error",
+        message: `Network error talking to iFlow: ${detail}`,
+    };
+}
+export function apiHttpError(status, message) {
+    let hint = message || `HTTP ${status}`;
+    if (status === 401)
+        hint = "401 Unauthorized — the iFlow API key is missing or invalid.";
+    else if (status === 403)
+        hint = "403 Forbidden — the iFlow API key is not allowed for this endpoint.";
+    else if (status === 429)
+        hint = "429 Too Many Requests — iFlow rate limit reached. Slow down or retry later.";
+    return { error: "api_error", status, message: hint, docs: IFLOW_ERROR_DOCS_URL };
+}
+export function apiBusinessError(opts) {
+    const parts = [];
+    if (opts.message)
+        parts.push(String(opts.message));
+    if (opts.errorMsg && opts.errorMsg !== opts.message)
+        parts.push(`detail: ${opts.errorMsg}`);
+    const message = parts.join(" — ") || "iFlow API returned success=false without a message.";
+    return {
+        error: "api_business_error",
+        code: opts.errorCode ?? opts.code ?? undefined,
+        message,
+        docs: IFLOW_ERROR_DOCS_URL,
+    };
+}
+export function isIflowError(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.error === "string" &&
+        typeof value.message === "string");
+}

package/dist/src/normalize.js

@@ -0,0 +1,80 @@
+/**
+ * Map raw iFlow API responses to the plugin's normalized output.
+ *
+ * Field mapping is based on real responses captured on 2026-05-12. If iFlow
+ * changes their schema, only this file (and its test) should need to move.
+ *
+ * --- FIELDS TO REVISIT IF IFLOW API CHANGES ---
+ * webSearch:
+ *   - data.organic[].link   ← iFlow uses "link", we expose it as "url"
+ *   - data.organic[].position  ← may be null on later results
+ *   - data.organic[].date      ← string or null (Chinese formatting observed: "2023年12月4日")
+ * imageSearch:
+ *   - data is a flat array (NOT data.images)
+ *   - data[].refUrl         ← exposed as "sourceUrl"
+ * webFetch:
+ *   - data.fromCache may be absent on first call (we treat undefined as null)
+ *   - data.content is a single string; large pages may exceed token budgets
+ * Error envelope (all endpoints):
+ *   - { success, code, message, exception, data: { errorMsg, errorCode } }
+ */
+function asString(v, fallback = "") {
+    return typeof v === "string" ? v : fallback;
+}
+function asNullableString(v) {
+    return typeof v === "string" && v.length > 0 ? v : null;
+}
+function asNullableNumber(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+export function normalizeWebSearch(raw, requestQuery, tookMs) {
+    const data = raw?.data;
+    const organic = Array.isArray(data?.organic) ? data.organic : [];
+    const results = organic
+        .filter((r) => r !== null && typeof r === "object")
+        .map((r) => ({
+        title: asString(r.title),
+        url: asString(r.link),
+        snippet: asString(r.snippet),
+        position: asNullableNumber(r.position),
+        date: asNullableString(r.date),
+    }));
+    return {
+        query: asString(data?.query, requestQuery),
+        provider: "iflow",
+        count: results.length,
+        tookMs,
+        results,
+    };
+}
+export function normalizeImageSearch(raw, requestQuery, tookMs) {
+    const data = raw?.data;
+    const arr = Array.isArray(data) ? data : [];
+    const images = arr
+        .filter((r) => r !== null && typeof r === "object")
+        .map((r) => ({
+        url: asString(r.url),
+        title: asNullableString(r.title),
+        sourceUrl: asNullableString(r.refUrl),
+    }))
+        .filter((img) => img.url.length > 0);
+    return {
+        query: requestQuery,
+        provider: "iflow",
+        count: images.length,
+        tookMs,
+        images,
+    };
+}
+export function normalizeWebFetch(raw, requestUrl, tookMs) {
+    const data = raw?.data;
+    const fromCache = typeof data?.fromCache === "boolean" ? data.fromCache : null;
+    return {
+        title: asNullableString(data?.title),
+        url: asString(data?.url, requestUrl),
+        content: asString(data?.content),
+        fromCache,
+        provider: "iflow",
+        tookMs,
+    };
+}

package/dist/src/tools.js

@@ -0,0 +1,165 @@
+/**
+ * The three explicit OpenClaw tools exposed by this plugin.
+ *
+ * Schemas use @sinclair/typebox, matching openclaw-tavily. Each tool returns
+ * the OpenClaw-standard `{ content: [{ type: "text", text }], details: {} }`
+ * shape, where `text` is a stringified JSON payload.
+ *
+ * Tool parameter names follow the Tavily/Brave canonical convention
+ * (`query`, `count`, `url`) for agent-side consistency. The iFlow API's
+ * actual body fields (`keywords`, `num`) are produced inside `client.ts`.
+ */
+import { Type } from "@sinclair/typebox";
+import { invalidParamError, missingParamError, } from "./errors.js";
+import { normalizeImageSearch, normalizeWebFetch, normalizeWebSearch, } from "./normalize.js";
+// -- Schemas ----------------------------------------------------------------
+export const WEB_SEARCH_DEFAULT_COUNT = 10;
+export const WEB_SEARCH_MAX_COUNT = 10;
+export const IMAGE_SEARCH_DEFAULT_COUNT = 10;
+export const IMAGE_SEARCH_MAX_COUNT = 20;
+export const IflowWebSearchSchema = Type.Object({
+    query: Type.String({
+        minLength: 1,
+        description: "Search query. Forwarded to iFlow as 'keywords'.",
+    }),
+    count: Type.Optional(Type.Number({
+        minimum: 1,
+        maximum: WEB_SEARCH_MAX_COUNT,
+        description: `Number of results (1-${WEB_SEARCH_MAX_COUNT}). Default: ${WEB_SEARCH_DEFAULT_COUNT}. Forwarded to iFlow as 'num'.`,
+    })),
+});
+export const IflowImageSearchSchema = Type.Object({
+    query: Type.String({
+        minLength: 1,
+        description: "Image search query. Forwarded to iFlow as 'keywords'.",
+    }),
+    count: Type.Optional(Type.Number({
+        minimum: 1,
+        maximum: IMAGE_SEARCH_MAX_COUNT,
+        description: `Number of images (1-${IMAGE_SEARCH_MAX_COUNT}). Default: ${IMAGE_SEARCH_DEFAULT_COUNT}. Forwarded to iFlow as 'num'.`,
+    })),
+});
+export const IflowWebFetchSchema = Type.Object({
+    url: Type.String({
+        minLength: 1,
+        description: "HTTP(S) URL to fetch.",
+    }),
+});
+function ok(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        details: {},
+    };
+}
+function fail(err) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(err, null, 2) }],
+        details: {},
+    };
+}
+function readQuery(params) {
+    const raw = params.query;
+    if (typeof raw !== "string")
+        return missingParamError("query");
+    const query = raw.trim();
+    if (query.length === 0)
+        return missingParamError("query");
+    return { query };
+}
+function readCount(params, defaultCount, maxCount) {
+    const raw = params.count;
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return defaultCount;
+    const intVal = Math.floor(raw);
+    if (intVal < 1)
+        return 1;
+    if (intVal > maxCount)
+        return maxCount;
+    return intVal;
+}
+function readUrl(params) {
+    const raw = params.url;
+    if (typeof raw !== "string")
+        return missingParamError("url");
+    const url = raw.trim();
+    if (url.length === 0)
+        return missingParamError("url");
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            return invalidParamError("url", "must be an http:// or https:// URL");
+        }
+    }
+    catch {
+        return invalidParamError("url", "not a valid URL");
+    }
+    return { url };
+}
+// -- Tool factories ---------------------------------------------------------
+export function createWebSearchTool(client) {
+    return {
+        name: "iflow_web_search",
+        label: "iFlow Web Search",
+        description: "Search the public web via iFlow Search (心流搜索). Returns titles, URLs, snippets, position, and (when available) publish date. Chinese-language results are first-class.",
+        parameters: IflowWebSearchSchema,
+        async execute(_toolCallId, params) {
+            const q = readQuery(params);
+            if ("error" in q)
+                return fail(q);
+            const count = readCount(params, WEB_SEARCH_DEFAULT_COUNT, WEB_SEARCH_MAX_COUNT);
+            const result = await client.webSearch(q.query, count);
+            if (!result.ok)
+                return fail(result.error);
+            const normalized = normalizeWebSearch(result.data, q.query, result.tookMs);
+            const payload = { ...normalized };
+            if (result.fromCache)
+                payload.cached = true;
+            return ok(payload);
+        },
+    };
+}
+export function createImageSearchTool(client) {
+    return {
+        name: "iflow_image_search",
+        label: "iFlow Image Search",
+        description: "Search the public web for images via iFlow Search. Returns image URLs, titles, and source page URLs.",
+        parameters: IflowImageSearchSchema,
+        async execute(_toolCallId, params) {
+            const q = readQuery(params);
+            if ("error" in q)
+                return fail(q);
+            const count = readCount(params, IMAGE_SEARCH_DEFAULT_COUNT, IMAGE_SEARCH_MAX_COUNT);
+            const result = await client.imageSearch(q.query, count);
+            if (!result.ok)
+                return fail(result.error);
+            const normalized = normalizeImageSearch(result.data, q.query, result.tookMs);
+            const payload = { ...normalized };
+            if (result.fromCache)
+                payload.cached = true;
+            return ok(payload);
+        },
+    };
+}
+export function createWebFetchTool(client) {
+    return {
+        name: "iflow_web_fetch",
+        label: "iFlow Web Fetch",
+        description: "Fetch the readable content of a single web page via iFlow Search. Returns title, plain-text/markdown content, and a cache hint.",
+        parameters: IflowWebFetchSchema,
+        async execute(_toolCallId, params) {
+            const u = readUrl(params);
+            if ("error" in u)
+                return fail(u);
+            const result = await client.webFetch(u.url);
+            if (!result.ok)
+                return fail(result.error);
+            const normalized = normalizeWebFetch(result.data, u.url, result.tookMs);
+            const payload = { ...normalized };
+            if (result.fromCache)
+                payload.cached = true;
+            return ok(payload);
+        },
+    };
+}
+// Exported for test fixtures.
+export const _internals = { readQuery, readCount, readUrl };

package/dist/src/web-search-provider.js

@@ -0,0 +1,53 @@
+/**
+ * Best-effort `web_search` provider for OpenClaw's managed search router.
+ *
+ * The shape of the returned object mirrors @openclaw/brave-plugin's
+ * `createBraveWebSearchProvider()` exactly, with iFlow-specific values
+ * substituted. This is a REFERENCE alignment — we make no guarantee that the
+ * third-party plugin contract is stable. The plugin entry wraps the use of
+ * `registerWebSearchProvider` and this factory in try/catch so any signature
+ * drift downgrades to tools-only mode without breaking plugin load.
+ */
+import { normalizeWebSearch } from "./normalize.js";
+const CREDENTIAL_PATH = "plugins.entries.iflow.config.webSearch.apiKey";
+export function createIflowWebSearchProvider(opts) {
+    const { client, createContractFields } = opts;
+    const contractFields = createContractFields({
+        credentialPath: CREDENTIAL_PATH,
+        searchCredential: { type: "top-level" },
+        configuredCredential: { pluginId: "iflow" },
+    });
+    return {
+        ...contractFields,
+        id: "iflow",
+        label: "iFlow Search",
+        hint: "Chinese-language web search · structured snippets",
+        onboardingScopes: ["text-inference"],
+        credentialLabel: "iFlow API key",
+        envVars: ["IFLOW_API_KEY"],
+        placeholder: "sk-...",
+        signupUrl: "https://platform.iflow.cn",
+        docsUrl: "https://platform.iflow.cn/docs/",
+        autoDetectOrder: 80,
+        credentialPath: CREDENTIAL_PATH,
+        createTool: () => null,
+        /**
+         * If the host runtime invokes this entry point instead of routing through
+         * createTool() (newer SDKs are observed to do both), perform the search
+         * and return a normalized payload. This is a forward-compatibility hook —
+         * if the runtime doesn't call it, no harm done.
+         */
+        async runManagedWebSearch(params) {
+            const query = String(params.query ?? "").trim();
+            const count = typeof params.count === "number" && Number.isFinite(params.count) && params.count > 0
+                ? Math.min(10, Math.max(1, Math.floor(params.count)))
+                : 10;
+            if (!query)
+                return { error: "missing_param", message: 'Parameter "query" is required.' };
+            const result = await client.webSearch(query, count);
+            if (!result.ok)
+                return result.error;
+            return normalizeWebSearch(result.data, query, result.tookMs);
+        },
+    };
+}

package/openclaw.plugin.json

@@ -0,0 +1,69 @@
+{
+  "id": "iflow",
+  "name": "iFlow Search",
+  "description": "iFlow Search (心流搜索) — Chinese-first web search, image search, and web content fetch. Exposes iflow_web_search, iflow_image_search, iflow_web_fetch, and registers as the 'iflow' web_search provider when the runtime supports it.",
+  "version": "0.1.0",
+  "kind": "tools",
+  "skills": ["./skills"],
+  "activation": { "onStartup": false },
+  "providerAuthEnvVars": { "iflow": ["IFLOW_API_KEY"] },
+  "setup": {
+    "providers": [
+      { "id": "iflow", "authMethods": ["api-key"], "envVars": ["IFLOW_API_KEY"] }
+    ]
+  },
+  "contracts": {
+    "tools": ["iflow_web_search", "iflow_image_search", "iflow_web_fetch"],
+    "webSearchProviders": ["iflow"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "webSearch": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "apiKey": {
+            "type": ["string", "object"],
+            "description": "iFlow API key (string or SecretRef). Falls back to the IFLOW_API_KEY env var."
+          },
+          "baseUrl": {
+            "type": ["string", "object"],
+            "description": "Override the iFlow API base URL. Defaults to https://platform.iflow.cn."
+          },
+          "timeoutSeconds": {
+            "type": "number",
+            "description": "HTTP timeout per request in seconds. Default: 30."
+          },
+          "cacheTtlMinutes": {
+            "type": "number",
+            "description": "In-memory cache TTL in minutes. Default: 15. Set 0 to disable."
+          }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "webSearch.apiKey": {
+      "label": "iFlow API Key",
+      "help": "iFlow Search API key. Falls back to the IFLOW_API_KEY environment variable.",
+      "sensitive": true,
+      "placeholder": "sk-..."
+    },
+    "webSearch.baseUrl": {
+      "label": "iFlow Base URL",
+      "help": "Optional base URL override for trusted proxies. Defaults to https://platform.iflow.cn.",
+      "advanced": true
+    },
+    "webSearch.timeoutSeconds": {
+      "label": "Timeout (seconds)",
+      "advanced": true
+    },
+    "webSearch.cacheTtlMinutes": {
+      "label": "Cache TTL (minutes)",
+      "help": "How long to cache identical search/fetch responses. Set 0 to disable.",
+      "advanced": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@iflow-ai/iflow-plugin",
+  "version": "0.1.0",
+  "description": "iFlow Search plugin for OpenClaw — exposes iflow_web_search, iflow_image_search, iflow_web_fetch, and registers (best-effort) as the web_search provider 'iflow'",
+  "type": "module",
+  "license": "MIT",
+  "author": "iflow-ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhengyanglsun/openclaw-iflow-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zhengyanglsun/openclaw-iflow-plugin/issues"
+  },
+  "homepage": "https://platform.iflow.cn",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "iflow",
+    "iflow-search",
+    "web-search",
+    "image-search",
+    "web-fetch",
+    "ai-search"
+  ],
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "0.34.47"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2025.0.0"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  }
+}

package/skills/iflow-search/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: iflow-search
+description: 中文优先的网页搜索 / 图片搜索 / 网页内容抓取，via iFlow Search (心流搜索) API. Use when the agent needs fresh public web information, image references, or to read the content of a specific URL.
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🔍",
+        "requires": { "env": ["IFLOW_API_KEY"] },
+        "primaryEnv": "IFLOW_API_KEY",
+      },
+  }
+---
+
+# iFlow Search
+
+AI-optimized web tools using the [iFlow Open Platform API](https://platform.iflow.cn).
+Three tools for search, image search, and single-page content fetch.
+
+## When to use which tool
+
+- **`iflow_web_search`** — Whenever the agent needs current, public web
+  information: news, fact-checking, finding references, looking up Chinese-language
+  resources, comparing claims across sources.
+- **`iflow_image_search`** — When the user wants visual references: photos of
+  people, places, animals, products, landmarks, diagrams, screenshots.
+- **`iflow_web_fetch`** — When the user provides a specific URL and asks the
+  agent to read it, summarize it, extract data from it, or quote from it.
+
+## Default routing
+
+When this plugin is active and registered as the `web_search` provider, the
+managed `web_search` tool routes to iFlow automatically. The three explicit
+tools above are always available regardless of provider routing.
+
+## Recommended research flow
+
+For multi-source research questions:
+
+1. Call `iflow_web_search` with a focused query.
+2. From the returned results, pick 2–4 URLs that look most relevant.
+3. Call `iflow_web_fetch` on each selected URL to get clean page content.
+4. Summarize, compare, or quote across the fetched content. Cite source URLs.
+
+For visual / product / location questions:
+
+1. Call `iflow_image_search` to surface candidate images.
+2. If the user wants context (article, product page, source attribution),
+   follow up with `iflow_web_fetch` on the image's `sourceUrl`.
+
+## When NOT to use
+
+- The user asks about files on the local disk, internal databases, or private
+  artifacts. These tools only see the public web.
+- The user explicitly asks for a different search provider.
+- The query is plainly conversational ("write a poem about cats") with no
+  factual lookup component.
+
+## Setup
+
+The plugin needs an API key from the [iFlow Open Platform](https://platform.iflow.cn).
+Either set `IFLOW_API_KEY` in the gateway environment, or configure it in your
+OpenClaw config:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "iflow": {
+        "enabled": true,
+        "config": {
+          "webSearch": { "apiKey": "sk-..." }
+        }
+      }
+    }
+  }
+}
+```
+
+## Tool response shapes
+
+`iflow_web_search`:
+
+```json
+{
+  "query": "...",
+  "provider": "iflow",
+  "count": 3,
+  "tookMs": 1383,
+  "results": [
+    { "title": "...", "url": "...", "snippet": "...", "position": 1, "date": null }
+  ]
+}
+```
+
+`iflow_image_search`:
+
+```json
+{
+  "query": "...",
+  "provider": "iflow",
+  "count": 3,
+  "tookMs": 1715,
+  "images": [
+    { "url": "...jpg", "title": "...", "sourceUrl": "..." }
+  ]
+}
+```
+
+`iflow_web_fetch`:
+
+```json
+{
+  "title": "...",
+  "url": "...",
+  "content": "...",
+  "fromCache": true,
+  "provider": "iflow",
+  "tookMs": 335
+}
+```
+
+On failure, every tool returns `{ "error": "<code>", "message": "...", "status"?, "code"?, "docs"? }`.
+Error codes: `missing_api_key`, `missing_param`, `invalid_param`,
+`network_timeout`, `network_error`, `api_error`, `api_business_error`.
+
+## Links
+
+- iFlow Open Platform docs: https://platform.iflow.cn/docs/
+- Plugin package: `@iflow-ai/iflow-plugin`
+
+## Acknowledgements
+
+This OpenClaw skill is adapted from the official iFlow skill catalog:
+
+https://github.com/iflow-ai/iflow-skills/tree/main/skills/iflow-search
+
+The capability surface is aligned with the official iFlow Search skill. Tool names, parameter shape, normalized return fields, and error handling are adapted for the OpenClaw plugin runtime.