@cozeclaw/coze-openclaw-plugin 0.1.0

package/src/tools/web-fetch.ts

@@ -0,0 +1,125 @@
+import { Static, Type } from "@sinclair/typebox";
+import type { AnyAgentTool } from "openclaw/plugin-sdk/core";
+import { formatCozeError } from "../client.js";
+import { getMissingCozeConfigMessage, resolveCozeClientConfig } from "../config.js";
+import { fetchContent } from "../shared/fetch.js";
+
+type ToolLogger = {
+  debug?: (message: string) => void;
+  info?: (message: string) => void;
+  warn: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+const FetchToolSchema = Type.Object(
+  {
+    urls: Type.Array(Type.String({ description: "URL to fetch." }), {
+      description: "One or more URLs to fetch.",
+      minItems: 1,
+    }),
+    format: Type.Optional(
+      Type.Unsafe<"text" | "markdown" | "json">({
+        type: "string",
+        enum: ["text", "markdown", "json"],
+        description: "Formatting preference for the textual output.",
+      }),
+    ),
+    textOnly: Type.Optional(
+      Type.Boolean({ description: "Only return extracted text, without images or links." }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+type FetchToolParams = Static<typeof FetchToolSchema>;
+
+function renderFetchedText(
+  items: Awaited<ReturnType<typeof fetchContent>>,
+  format: "text" | "markdown" | "json",
+): string {
+  if (format === "json") {
+    return JSON.stringify(items, null, 2);
+  }
+  if (format === "markdown") {
+    return items
+      .map((item) => {
+        const parts = [`# ${item.title ?? item.url}`, "", `**URL**: ${item.url}`, "", item.text];
+        if (item.links.length > 0) {
+          parts.push("", "## Links");
+          for (const link of item.links) {
+            parts.push(`- [${link.title ?? link.url ?? "Link"}](${link.url ?? ""})`);
+          }
+        }
+        return parts.join("\n");
+      })
+      .join("\n\n---\n\n");
+  }
+  return items
+    .map((item, index) => {
+      const lines = [`[${index + 1}] ${item.title ?? item.url}`, `URL: ${item.url}`, "", item.text];
+      if (item.links.length > 0) {
+        lines.push("", "Links:");
+        for (const link of item.links) {
+          lines.push(`- ${link.title ?? link.url ?? "Link"} -> ${link.url ?? ""}`);
+        }
+      }
+      if (item.images.length > 0) {
+        lines.push("", "Images:");
+        for (const image of item.images) {
+          lines.push(`- ${image.url ?? ""}`);
+        }
+      }
+      return lines.join("\n");
+    })
+    .join("\n\n============================================================\n\n");
+}
+
+function buildErrorResult(message: string) {
+  return {
+    content: [{ type: "text" as const, text: `Error: ${message}` }],
+    details: { error: true, message },
+  };
+}
+
+export function createCozeWebFetchTool(params: {
+  pluginConfig?: Record<string, unknown>;
+  logger: ToolLogger;
+  env?: NodeJS.ProcessEnv;
+}): AnyAgentTool {
+  return {
+    name: "coze_web_fetch",
+    label: "Coze Web Fetch",
+    description:
+      "Fetch and extract structured content from web pages or documents through Coze.",
+    parameters: FetchToolSchema,
+    execute: async (_toolCallId, rawParams) => {
+      const toolParams = rawParams as FetchToolParams;
+      const clientConfig = resolveCozeClientConfig(params.pluginConfig, params.env);
+      if (!clientConfig.apiKey) {
+        return buildErrorResult(getMissingCozeConfigMessage());
+      }
+      try {
+        const items = await fetchContent(
+          {
+            urls: toolParams.urls,
+            textOnly: toolParams.textOnly,
+          },
+          clientConfig,
+        );
+        const format = toolParams.format ?? "text";
+        return {
+          content: [{ type: "text", text: renderFetchedText(items, format) }],
+          details: {
+            count: items.length,
+            urls: items.map((item) => item.url),
+            items,
+          },
+        };
+      } catch (error) {
+        const message = formatCozeError(error);
+        params.logger.warn(`coze-web-fetch failed: ${message}`);
+        return buildErrorResult(message);
+      }
+    },
+  };
+}

package/src/tools/web-search.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it, vi } from "vitest";
+
+const hoisted = vi.hoisted(() => ({
+  searchWeb: vi.fn(),
+}));
+
+vi.mock("../shared/search.js", () => ({
+  searchWeb: (...args: unknown[]) => hoisted.searchWeb(...args),
+}));
+
+const { createCozeWebSearchTool } = await import("./web-search.js");
+
+function getTextContent(result: { content: Array<{ type: string; text?: string }> }): string {
+  const first = result.content[0];
+  return first?.type === "text" ? first.text ?? "" : "";
+}
+
+describe("createCozeWebSearchTool", () => {
+  it("executes web search and returns structured details", async () => {
+    hoisted.searchWeb.mockResolvedValueOnce({
+      query: "OpenClaw",
+      type: "web",
+      summary: "summary",
+      items: [
+        {
+          title: "OpenClaw",
+          url: "https://openclaw.ai",
+          siteName: "OpenClaw",
+          snippet: "AI agent",
+        },
+      ],
+    });
+
+    const tool = createCozeWebSearchTool({
+      pluginConfig: { apiKey: "test-key" },
+      logger: {
+        debug() {},
+        info() {},
+        warn() {},
+        error() {},
+      },
+      env: {},
+    });
+
+    const result = await tool.execute("call-1", {
+      query: "OpenClaw",
+      type: "web",
+      count: 5,
+      needSummary: true,
+    });
+
+    expect(hoisted.searchWeb).toHaveBeenCalledWith(
+      expect.objectContaining({
+        query: "OpenClaw",
+        type: "web",
+        count: 5,
+        needSummary: true,
+      }),
+      expect.objectContaining({ apiKey: "test-key" }),
+    );
+    expect(result.details).toMatchObject({
+      query: "OpenClaw",
+      type: "web",
+      summary: "summary",
+      count: 1,
+    });
+    expect(getTextContent(result)).toContain("OpenClaw");
+  });
+
+  it("supports image search mode", async () => {
+    hoisted.searchWeb.mockResolvedValueOnce({
+      query: "lobster",
+      type: "image",
+      items: [
+        {
+          title: "Lobster",
+          url: "https://example.com/page",
+          imageUrl: "https://example.com/image.png",
+          siteName: "Example",
+        },
+      ],
+    });
+
+    const tool = createCozeWebSearchTool({
+      pluginConfig: { apiKey: "test-key" },
+      logger: {
+        debug() {},
+        info() {},
+        warn() {},
+        error() {},
+      },
+      env: {},
+    });
+
+    const result = await tool.execute("call-2", {
+      query: "lobster",
+      type: "image",
+    });
+
+    expect(result.details).toMatchObject({
+      type: "image",
+      count: 1,
+    });
+    expect(getTextContent(result)).toContain("https://example.com/image.png");
+  });
+});

package/src/tools/web-search.ts

@@ -0,0 +1,126 @@
+import { Static, Type } from "@sinclair/typebox";
+import type { AnyAgentTool } from "openclaw/plugin-sdk/core";
+import { formatCozeError } from "../client.js";
+import { getMissingCozeConfigMessage, resolveCozeClientConfig } from "../config.js";
+import { searchWeb } from "../shared/search.js";
+
+type ToolLogger = {
+  debug?: (message: string) => void;
+  info?: (message: string) => void;
+  warn: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+const SearchToolSchema = Type.Object(
+  {
+    query: Type.String({ description: "Search query." }),
+    type: Type.Optional(
+      Type.Unsafe<"web" | "image">({
+        type: "string",
+        enum: ["web", "image"],
+        description: "Search type. Defaults to web.",
+      }),
+    ),
+    count: Type.Optional(
+      Type.Number({
+        description: "Number of results to return.",
+        minimum: 1,
+        maximum: 20,
+      }),
+    ),
+    timeRange: Type.Optional(
+      Type.Unsafe<"1d" | "1w" | "1m">({
+        type: "string",
+        enum: ["1d", "1w", "1m"],
+        description: "Recency filter for web search.",
+      }),
+    ),
+    sites: Type.Optional(
+      Type.String({ description: "Comma-separated domains to include." }),
+    ),
+    blockHosts: Type.Optional(
+      Type.String({ description: "Comma-separated domains to exclude." }),
+    ),
+    needSummary: Type.Optional(
+      Type.Boolean({ description: "Whether to include Coze summary output." }),
+    ),
+    needContent: Type.Optional(
+      Type.Boolean({ description: "Whether to include extracted page content." }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+type SearchToolParams = Static<typeof SearchToolSchema>;
+
+function buildSearchText(params: Awaited<ReturnType<typeof searchWeb>>): string {
+  const lines = [`Coze web search: ${params.query}`];
+  if (params.summary) {
+    lines.push("", `Summary: ${params.summary}`);
+  }
+  lines.push("", `Results (${params.items.length})`);
+  for (const [index, item] of params.items.entries()) {
+    lines.push(`${index + 1}. ${item.title}`);
+    if (item.url) {
+      lines.push(`   URL: ${item.url}`);
+    }
+    if (item.imageUrl) {
+      lines.push(`   Image: ${item.imageUrl}`);
+    }
+    if (item.siteName) {
+      lines.push(`   Source: ${item.siteName}`);
+    }
+    if (item.publishTime) {
+      lines.push(`   Published: ${item.publishTime}`);
+    }
+    if (item.snippet) {
+      lines.push(`   ${item.snippet}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function buildErrorResult(message: string) {
+  return {
+    content: [{ type: "text" as const, text: `Error: ${message}` }],
+    details: { error: true, message },
+  };
+}
+
+export function createCozeWebSearchTool(params: {
+  pluginConfig?: Record<string, unknown>;
+  logger: ToolLogger;
+  env?: NodeJS.ProcessEnv;
+}): AnyAgentTool {
+  return {
+    name: "coze_web_search",
+    label: "Coze Web Search",
+    description:
+      "Search the web or images through Coze. Supports summaries, recency filters, and site restrictions.",
+    parameters: SearchToolSchema,
+    execute: async (_toolCallId, rawParams) => {
+      const toolParams = rawParams as SearchToolParams;
+      const clientConfig = resolveCozeClientConfig(params.pluginConfig, params.env);
+      if (!clientConfig.apiKey) {
+        return buildErrorResult(getMissingCozeConfigMessage());
+      }
+      try {
+        const result = await searchWeb(toolParams, clientConfig);
+        return {
+          content: [{ type: "text", text: buildSearchText(result) }],
+          details: {
+            query: result.query,
+            type: result.type,
+            summary: result.summary,
+            count: result.items.length,
+            items: result.items,
+          },
+        };
+      } catch (error) {
+        const message = formatCozeError(error);
+        params.logger.warn(`coze-web-search failed: ${message}`);
+        return buildErrorResult(message);
+      }
+    },
+  };
+}