@cozeclaw/coze-openclaw-plugin 0.1.0

package/src/config.ts

@@ -0,0 +1,158 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { CozeConfig } from "coze-coding-dev-sdk";
+import JSON5 from "json5";
+
+type CozePluginConfig = {
+  apiKey?: unknown;
+  baseUrl?: unknown;
+  modelBaseUrl?: unknown;
+  retryTimes?: unknown;
+  retryDelay?: unknown;
+  timeout?: unknown;
+};
+
+type OpenClawConfigFile = {
+  plugins?: {
+    entries?: Record<
+      string,
+      {
+        config?: CozePluginConfig;
+      }
+    >;
+  };
+};
+
+function readString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function readNumber(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const parsed = Number(trimmed);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function resolveHomeDir(env: NodeJS.ProcessEnv): string {
+  const home = env.HOME?.trim() || env.USERPROFILE?.trim() || os.homedir();
+  return home || os.homedir();
+}
+
+function expandHomeDir(rawPath: string, env: NodeJS.ProcessEnv): string {
+  if (rawPath === "~") {
+    return resolveHomeDir(env);
+  }
+  if (rawPath.startsWith("~/") || rawPath.startsWith("~\\")) {
+    return path.join(resolveHomeDir(env), rawPath.slice(2));
+  }
+  return rawPath;
+}
+
+export function resolveOpenClawConfigPath(env: NodeJS.ProcessEnv = process.env): string {
+  const explicitPath = env.OPENCLAW_CONFIG_PATH?.trim() || env.CLAWDBOT_CONFIG_PATH?.trim();
+  if (explicitPath) {
+    return path.resolve(expandHomeDir(explicitPath, env));
+  }
+
+  const stateDir = env.OPENCLAW_STATE_DIR?.trim();
+  if (stateDir) {
+    return path.resolve(expandHomeDir(path.join(stateDir, "openclaw.json"), env));
+  }
+
+  return path.join(resolveHomeDir(env), ".openclaw", "openclaw.json");
+}
+
+function resolveEnvTemplate(value: string, env: NodeJS.ProcessEnv): string | undefined {
+  const pattern = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
+  let missing = false;
+  const resolved = value.replace(pattern, (_match, envName: string) => {
+    const envValue = env[envName]?.trim();
+    if (!envValue) {
+      missing = true;
+      return "";
+    }
+    return envValue;
+  });
+  if (missing && !resolved.trim()) {
+    return undefined;
+  }
+  return resolved.trim() ? resolved : undefined;
+}
+
+function normalizePluginConfigFromFile(
+  value: CozePluginConfig | undefined,
+  env: NodeJS.ProcessEnv,
+): CozePluginConfig | undefined {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+
+  const maybeResolveString = (input: unknown): string | undefined => {
+    if (typeof input !== "string") {
+      return undefined;
+    }
+    return resolveEnvTemplate(input, env) ?? readString(input);
+  };
+
+  return {
+    apiKey: maybeResolveString(value.apiKey),
+    baseUrl: maybeResolveString(value.baseUrl),
+    modelBaseUrl: maybeResolveString(value.modelBaseUrl),
+    retryTimes:
+      typeof value.retryTimes === "string"
+        ? maybeResolveString(value.retryTimes)
+        : value.retryTimes,
+    retryDelay:
+      typeof value.retryDelay === "string"
+        ? maybeResolveString(value.retryDelay)
+        : value.retryDelay,
+    timeout: typeof value.timeout === "string" ? maybeResolveString(value.timeout) : value.timeout,
+  };
+}
+
+export async function loadCozePluginConfigFromOpenClawConfig(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<CozePluginConfig | undefined> {
+  const configPath = resolveOpenClawConfigPath(env);
+
+  try {
+    const content = await fs.readFile(configPath, "utf-8");
+    const parsed = JSON5.parse(content) as OpenClawConfigFile;
+    const pluginConfig = parsed.plugins?.entries?.["coze-openclaw-plugin"]?.config;
+    return normalizePluginConfigFromFile(pluginConfig, env);
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveCozeClientConfig(
+  pluginConfig?: CozePluginConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): CozeConfig {
+  return {
+    apiKey: readString(pluginConfig?.apiKey),
+    baseUrl: readString(pluginConfig?.baseUrl),
+    modelBaseUrl: readString(pluginConfig?.modelBaseUrl),
+    retryTimes: readNumber(pluginConfig?.retryTimes),
+    retryDelay: readNumber(pluginConfig?.retryDelay),
+    timeout: readNumber(pluginConfig?.timeout),
+  };
+}
+
+export function getMissingCozeConfigMessage(): string {
+  return "Coze API key missing. Set plugins.entries.coze-openclaw-plugin.config.apiKey.";
+}

package/src/shared/asr.ts

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import { randomUUID } from "node:crypto";
+import type { CozeConfig } from "coze-coding-dev-sdk";
+import { createAsrClient } from "../client.js";
+
+export type AsrInput = {
+  url?: string;
+  file?: string;
+};
+
+export type AsrResult = {
+  text: string;
+  duration?: number;
+  segments?: number;
+};
+
+export async function transcribeSpeech(
+  input: AsrInput,
+  clientConfig: CozeConfig,
+): Promise<AsrResult> {
+  const client = await createAsrClient({ config: clientConfig });
+  const request =
+    input.file !== undefined
+      ? {
+          uid: `coze-openclaw-plugin-asr-${randomUUID()}`,
+          base64Data: fs.readFileSync(input.file).toString("base64"),
+        }
+      : {
+          uid: `coze-openclaw-plugin-asr-${randomUUID()}`,
+          url: input.url,
+        };
+  const result = await client.recognize(request);
+  return {
+    text: result.text,
+    duration: result.duration,
+    segments: result.utterances?.length,
+  };
+}

package/src/shared/fetch.ts

@@ -0,0 +1,79 @@
+import type { CozeConfig, FetchContentItem, FetchResponse } from "coze-coding-dev-sdk";
+import { createFetchClient } from "../client.js";
+
+export type FetchInput = {
+  urls: string[];
+  textOnly?: boolean;
+};
+
+export type FetchResultLink = {
+  title?: string;
+  url?: string;
+};
+
+export type FetchResultImage = {
+  url?: string;
+  width?: number;
+  height?: number;
+};
+
+export type FetchResultItem = {
+  url: string;
+  title?: string;
+  text: string;
+  links: FetchResultLink[];
+  images: FetchResultImage[];
+};
+
+function joinText(items: FetchContentItem[]): string {
+  return items
+    .filter((item) => item.type === "text" && item.text)
+    .map((item) => item.text?.trim() ?? "")
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+function collectLinks(items: FetchContentItem[]): FetchResultLink[] {
+  return items
+    .filter((item) => item.type === "link")
+    .map((item) => ({
+      title: item.text,
+      url: item.url,
+    }));
+}
+
+function collectImages(items: FetchContentItem[]): FetchResultImage[] {
+  return items
+    .filter((item) => item.type === "image")
+    .map((item) => ({
+      url: item.image?.display_url ?? item.image?.image_url,
+      width: item.image?.width,
+      height: item.image?.height,
+    }));
+}
+
+function normalizeFetchedItem(response: FetchResponse, textOnly: boolean): FetchResultItem {
+  const content = response.content ?? [];
+  return {
+    url: response.url ?? "",
+    title: response.title,
+    text: joinText(content),
+    links: textOnly ? [] : collectLinks(content),
+    images: textOnly ? [] : collectImages(content),
+  };
+}
+
+export async function fetchContent(
+  input: FetchInput,
+  clientConfig: CozeConfig,
+): Promise<FetchResultItem[]> {
+  const client = await createFetchClient({ config: clientConfig });
+  const results: FetchResultItem[] = [];
+
+  for (const url of input.urls) {
+    const response = await client.fetch(url);
+    results.push(normalizeFetchedItem(response, input.textOnly === true));
+  }
+
+  return results;
+}

package/src/shared/image-gen.ts

@@ -0,0 +1,41 @@
+import type { CozeConfig, ImageGenerationRequest } from "coze-coding-dev-sdk";
+import { createImageGenerationClient } from "../client.js";
+
+export type ImageGenerationInput = {
+  prompt: string;
+  count?: number;
+  size?: string;
+  sequential?: boolean;
+  maxSequential?: number;
+};
+
+export type ImageGenerationResult = {
+  prompt: string;
+  urls: string[];
+};
+
+export async function generateImages(
+  input: ImageGenerationInput,
+  clientConfig: CozeConfig,
+): Promise<ImageGenerationResult[]> {
+  const client = await createImageGenerationClient({ config: clientConfig });
+  const count = input.count ?? 1;
+  const results: ImageGenerationResult[] = [];
+
+  for (let index = 0; index < count; index += 1) {
+    const request: ImageGenerationRequest = {
+      prompt: input.prompt,
+      size: input.size ?? "2K",
+      sequentialImageGeneration: input.sequential ? "auto" : "disabled",
+      sequentialImageGenerationMaxImages: input.maxSequential ?? 5,
+    };
+    const response = await client.generate(request);
+    const helper = client.getResponseHelper(response);
+    results.push({
+      prompt: input.prompt,
+      urls: helper.imageUrls,
+    });
+  }
+
+  return results;
+}

package/src/shared/search.ts

@@ -0,0 +1,96 @@
+import type { CozeConfig, ImageItem, SearchResponse, WebItem } from "coze-coding-dev-sdk";
+import { createSearchClient } from "../client.js";
+
+export type SearchInput = {
+  query: string;
+  type?: "web" | "image";
+  count?: number;
+  timeRange?: string;
+  sites?: string;
+  blockHosts?: string;
+  needSummary?: boolean;
+  needContent?: boolean;
+};
+
+export type SearchResultItem = {
+  title: string;
+  url?: string;
+  siteName?: string;
+  snippet?: string;
+  content?: string;
+  publishTime?: string;
+  imageUrl?: string;
+  imageWidth?: number;
+  imageHeight?: number;
+};
+
+export type SearchResult = {
+  query: string;
+  type: "web" | "image";
+  summary?: string;
+  items: SearchResultItem[];
+};
+
+function mapWebItem(item: WebItem): SearchResultItem {
+  return {
+    title: item.title,
+    url: item.url,
+    siteName: item.site_name,
+    snippet: item.snippet,
+    content: item.content,
+    publishTime: item.publish_time,
+  };
+}
+
+function mapImageItem(item: ImageItem): SearchResultItem {
+  return {
+    title: item.title ?? "Untitled",
+    url: item.url,
+    siteName: item.site_name,
+    publishTime: item.publish_time,
+    imageUrl: item.image?.url,
+    imageWidth: item.image?.width,
+    imageHeight: item.image?.height,
+  };
+}
+
+function hasAdvancedOptions(input: SearchInput): boolean {
+  return Boolean(input.timeRange || input.sites || input.blockHosts || input.needContent);
+}
+
+export async function searchWeb(input: SearchInput, clientConfig: CozeConfig): Promise<SearchResult> {
+  const client = await createSearchClient({ config: clientConfig });
+  const type = input.type ?? "web";
+  const count = input.count ?? 10;
+  let response: SearchResponse;
+
+  if (type === "image") {
+    response = await client.imageSearch(input.query, count);
+    return {
+      query: input.query,
+      type,
+      items: (response.image_items ?? []).map(mapImageItem),
+    };
+  }
+
+  if (hasAdvancedOptions(input)) {
+    response = await client.advancedSearch(input.query, {
+      searchType: "web",
+      count,
+      timeRange: input.timeRange,
+      sites: input.sites,
+      blockHosts: input.blockHosts,
+      needSummary: input.needSummary,
+      needContent: input.needContent,
+    });
+  } else {
+    response = await client.webSearch(input.query, count, input.needSummary);
+  }
+
+  return {
+    query: input.query,
+    type,
+    summary: response.summary,
+    items: (response.web_items ?? []).map(mapWebItem),
+  };
+}

package/src/shared/tts.ts

@@ -0,0 +1,45 @@
+import { randomUUID } from "node:crypto";
+import type { AudioFormat, CozeConfig, SampleRate } from "coze-coding-dev-sdk";
+import { createTtsClient } from "../client.js";
+
+export type TtsInput = {
+  texts: string[];
+  speaker?: string;
+  format?: AudioFormat;
+  sampleRate?: SampleRate;
+  speechRate?: number;
+  loudnessRate?: number;
+};
+
+export type TtsResult = {
+  text: string;
+  audioUri: string;
+  audioSize: number;
+};
+
+export async function synthesizeSpeech(
+  input: TtsInput,
+  clientConfig: CozeConfig,
+): Promise<TtsResult[]> {
+  const client = await createTtsClient({ config: clientConfig });
+  const results: TtsResult[] = [];
+
+  for (const text of input.texts) {
+    const response = await client.synthesize({
+      uid: `coze-openclaw-plugin-tts-${randomUUID()}`,
+      text,
+      speaker: input.speaker,
+      audioFormat: input.format,
+      sampleRate: input.sampleRate,
+      speechRate: input.speechRate,
+      loudnessRate: input.loudnessRate,
+    });
+    results.push({
+      text,
+      audioUri: response.audioUri,
+      audioSize: response.audioSize,
+    });
+  }
+
+  return results;
+}

package/src/skill-cli.ts

@@ -0,0 +1,178 @@
+import type { CozeConfig } from "coze-coding-dev-sdk";
+import { formatCozeError } from "./client.js";
+import {
+  getMissingCozeConfigMessage,
+  loadCozePluginConfigFromOpenClawConfig,
+  resolveCozeClientConfig,
+} from "./config.js";
+import { transcribeSpeech } from "./shared/asr.js";
+import { generateImages } from "./shared/image-gen.js";
+import { synthesizeSpeech } from "./shared/tts.js";
+
+type SkillIo = {
+  log: (message: string) => void;
+  error: (message: string) => void;
+};
+
+function createDefaultIo(): SkillIo {
+  return {
+    log(message: string) {
+      console.log(message);
+    },
+    error(message: string) {
+      console.error(message);
+    },
+  };
+}
+
+async function requireConfig(env: NodeJS.ProcessEnv): Promise<CozeConfig> {
+  const pluginConfig = await loadCozePluginConfigFromOpenClawConfig(env);
+  const config = resolveCozeClientConfig(pluginConfig, env);
+  if (!config.apiKey) {
+    throw new Error(getMissingCozeConfigMessage());
+  }
+  return config;
+}
+
+function readArg(args: string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+function readTrailingValues(args: string[], name: string): string[] {
+  const index = args.indexOf(name);
+  if (index < 0) {
+    return [];
+  }
+  const values: string[] = [];
+  for (let cursor = index + 1; cursor < args.length; cursor += 1) {
+    const value = args[cursor];
+    if (value.startsWith("--")) {
+      break;
+    }
+    values.push(value);
+  }
+  return values;
+}
+
+function readNumberArg(args: string[], name: string): number | undefined {
+  const value = readArg(args, name);
+  if (!value) {
+    return undefined;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+export async function runImageCli(
+  args: string[],
+  env: NodeJS.ProcessEnv = process.env,
+  io: SkillIo = createDefaultIo(),
+): Promise<number> {
+  const prompt = readArg(args, "--prompt");
+  if (!prompt) {
+    io.error("Error: --prompt is required");
+    return 1;
+  }
+  try {
+    const config = await requireConfig(env);
+    const results = await generateImages(
+      {
+        prompt,
+        count: readNumberArg(args, "--count"),
+        size: readArg(args, "--size"),
+        sequential: args.includes("--sequential"),
+        maxSequential: readNumberArg(args, "--max-sequential"),
+      },
+      config,
+    );
+    for (const [index, item] of results.entries()) {
+      io.log(`[${index + 1}/${results.length}] ${item.prompt}`);
+      for (const url of item.urls) {
+        io.log(`  ${url}`);
+      }
+    }
+    return 0;
+  } catch (error) {
+    io.error(`Error: ${formatCozeError(error)}`);
+    return 1;
+  }
+}
+
+export async function runTtsCli(
+  args: string[],
+  env: NodeJS.ProcessEnv = process.env,
+  io: SkillIo = createDefaultIo(),
+): Promise<number> {
+  const text = readArg(args, "--text");
+  const texts = readTrailingValues(args, "--texts");
+  const mergedTexts = text ? [text] : texts;
+  if (mergedTexts.length === 0) {
+    io.error("Error: --text or --texts is required");
+    return 1;
+  }
+  try {
+    const config = await requireConfig(env);
+    const results = await synthesizeSpeech(
+      {
+        texts: mergedTexts,
+        speaker: readArg(args, "--speaker"),
+        format: readArg(args, "--format") as "mp3" | "pcm" | "ogg_opus" | undefined,
+        sampleRate: readNumberArg(args, "--sample-rate") as
+          | 8000
+          | 16000
+          | 22050
+          | 24000
+          | 32000
+          | 44100
+          | 48000
+          | undefined,
+        speechRate: readNumberArg(args, "--speech-rate"),
+        loudnessRate: readNumberArg(args, "--loudness-rate"),
+      },
+      config,
+    );
+    for (const [index, item] of results.entries()) {
+      io.log(
+        `[${index + 1}/${results.length}] ${item.text.slice(0, 50)}${item.text.length > 50 ? "..." : ""}`,
+      );
+      io.log(`  ${item.audioUri}`);
+    }
+    return 0;
+  } catch (error) {
+    io.error(`Error: ${formatCozeError(error)}`);
+    return 1;
+  }
+}
+
+export async function runAsrCli(
+  args: string[],
+  env: NodeJS.ProcessEnv = process.env,
+  io: SkillIo = createDefaultIo(),
+): Promise<number> {
+  const url = readArg(args, "--url") ?? readArg(args, "-u");
+  const file = readArg(args, "--file") ?? readArg(args, "-f");
+  if (!url && !file) {
+    io.error("Error: --url or --file is required");
+    return 1;
+  }
+  try {
+    const config = await requireConfig(env);
+    const result = await transcribeSpeech({ url, file }, config);
+    io.log("============================================================");
+    io.log("TRANSCRIPTION");
+    io.log("============================================================");
+    io.log(result.text);
+    io.log("============================================================");
+    if (result.duration !== undefined) {
+      io.log(`Duration: ${result.duration}`);
+    }
+    if (result.segments !== undefined) {
+      io.log(`Segments: ${result.segments}`);
+    }
+    return 0;
+  } catch (error) {
+    io.error(`Error: ${formatCozeError(error)}`);
+    return 1;
+  }
+}

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

@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from "vitest";
+
+const hoisted = vi.hoisted(() => ({
+  fetchContent: vi.fn(),
+}));
+
+vi.mock("../shared/fetch.js", () => ({
+  fetchContent: (...args: unknown[]) => hoisted.fetchContent(...args),
+}));
+
+const { createCozeWebFetchTool } = await import("./web-fetch.js");
+
+function getTextContent(result: { content: Array<{ type: string; text?: string }> }): string {
+  const first = result.content[0];
+  return first?.type === "text" ? first.text ?? "" : "";
+}
+
+describe("createCozeWebFetchTool", () => {
+  it("fetches multiple urls and returns normalized details", async () => {
+    hoisted.fetchContent.mockResolvedValueOnce([
+      {
+        url: "https://example.com/one",
+        title: "One",
+        text: "First page",
+        links: [],
+        images: [],
+      },
+      {
+        url: "https://example.com/two",
+        title: "Two",
+        text: "Second page",
+        links: [{ title: "Ref", url: "https://example.com/ref" }],
+        images: [],
+      },
+    ]);
+
+    const tool = createCozeWebFetchTool({
+      pluginConfig: { apiKey: "test-key" },
+      logger: {
+        debug() {},
+        info() {},
+        warn() {},
+        error() {},
+      },
+      env: {},
+    });
+
+    const result = await tool.execute("call-1", {
+      urls: ["https://example.com/one", "https://example.com/two"],
+      textOnly: true,
+    });
+
+    expect(hoisted.fetchContent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        urls: ["https://example.com/one", "https://example.com/two"],
+        textOnly: true,
+      }),
+      expect.objectContaining({ apiKey: "test-key" }),
+    );
+    expect(result.details).toMatchObject({
+      count: 2,
+      urls: ["https://example.com/one", "https://example.com/two"],
+    });
+    const text = getTextContent(result);
+    expect(text).toContain("First page");
+    expect(text).toContain("Second page");
+  });
+});