@openclaw-china/shared 0.1.29 → 0.1.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw-china/shared",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/src/asr/README.md

@@ -0,0 +1,100 @@
+# ASR 接入说明（供各插件复用）
+
+本文说明如何在任意渠道插件中复用 `@openclaw-china/shared` 的语音转文本能力。
+
+当前已提供：
+- 腾讯云录音文件识别极速版（`asr/flash/v1`）
+- 统一错误类型（便于插件侧日志和降级）
+
+## 职责边界
+
+`shared` 负责：
+- 调用 ASR 服务（签名、请求、响应解析、超时）
+- 抛出结构化错误（`ASRError` 及子类）
+
+单个插件负责：
+- 平台事件解析（如何识别语音消息）
+- 媒体下载（URL/鉴权/大小限制）
+- 业务策略（失败是否降级、回复文案、是否中断本次处理）
+- 密钥配置（建议保留在插件配置内）
+
+## 可直接使用的导出
+
+```ts
+import {
+  transcribeTencentFlash,
+  ASRError,
+  ASRTimeoutError,
+  ASRAuthError,
+  ASRRequestError,
+  ASRResponseParseError,
+  ASRServiceError,
+  ASREmptyResultError,
+} from "@openclaw-china/shared";
+```
+
+## 插件接入步骤
+
+1. 在插件配置中增加 ASR 字段（示例）
+```ts
+asr: {
+  enabled?: boolean;
+  appId?: string;
+  secretId?: string;
+  secretKey?: string;
+}
+```
+
+2. 在入站消息里识别语音附件，并下载到 `Buffer`
+- 推荐复用 `shared/media` 的下载能力：
+```ts
+import { fetchMediaFromUrl } from "@openclaw-china/shared";
+```
+
+3. 调用转写
+```ts
+const transcript = await transcribeTencentFlash({
+  audio: media.buffer,
+  config: {
+    appId: asr.appId,
+    secretId: asr.secretId,
+    secretKey: asr.secretKey,
+    // 可选，默认如下：
+    // engineType: "16k_zh",
+    // voiceFormat: "silk",
+    // timeoutMs: 30000,
+  },
+});
+```
+
+4. 按错误类型做日志与降级
+```ts
+try {
+  // transcribeTencentFlash(...)
+} catch (err) {
+  if (err instanceof ASRError) {
+    logger.warn(
+      `asr failed kind=${err.kind} provider=${err.provider} retryable=${err.retryable} msg=${err.message}`
+    );
+  } else {
+    logger.warn(`asr failed: ${String(err)}`);
+  }
+  // 在这里决定是否回退文本、提示用户、或继续其他链路
+}
+```
+
+## 错误类型语义
+
+- `ASRTimeoutError`：请求超时，通常可重试
+- `ASRAuthError`：鉴权失败（密钥错误/权限问题），通常不可重试
+- `ASRRequestError`：请求失败（网络或 HTTP 失败）
+- `ASRResponseParseError`：服务返回非 JSON 或格式异常
+- `ASRServiceError`：服务端返回业务错误码（`code != 0`）
+- `ASREmptyResultError`：识别成功但无文本
+
+## 最佳实践
+
+- 不要把密钥硬编码到仓库；仅通过配置注入。
+- 给下载和 ASR 都设置超时与大小上限。
+- 将“ASR 失败文案”放在插件侧，不放到 `shared`。
+- 先记录结构化日志，再决定业务降级策略。

package/src/asr/errors.ts

@@ -0,0 +1,61 @@
+export type ASRErrorKind =
+  | "timeout"
+  | "auth"
+  | "request"
+  | "response_parse"
+  | "service"
+  | "empty_result";
+
+export class ASRError extends Error {
+  constructor(
+    message: string,
+    public readonly kind: ASRErrorKind,
+    public readonly provider: string,
+    public readonly retryable: boolean = false
+  ) {
+    super(message);
+    this.name = "ASRError";
+  }
+}
+
+export class ASRTimeoutError extends ASRError {
+  constructor(provider: string, public readonly timeoutMs: number) {
+    super(`ASR request timeout after ${timeoutMs}ms`, "timeout", provider, true);
+    this.name = "ASRTimeoutError";
+  }
+}
+
+export class ASRAuthError extends ASRError {
+  constructor(provider: string, message: string, public readonly status?: number) {
+    super(message, "auth", provider, false);
+    this.name = "ASRAuthError";
+  }
+}
+
+export class ASRRequestError extends ASRError {
+  constructor(provider: string, message: string, public readonly status?: number) {
+    super(message, "request", provider, true);
+    this.name = "ASRRequestError";
+  }
+}
+
+export class ASRResponseParseError extends ASRError {
+  constructor(provider: string, public readonly bodySnippet: string) {
+    super("ASR response is not valid JSON", "response_parse", provider, false);
+    this.name = "ASRResponseParseError";
+  }
+}
+
+export class ASRServiceError extends ASRError {
+  constructor(provider: string, message: string, public readonly serviceCode?: number) {
+    super(message, "service", provider, false);
+    this.name = "ASRServiceError";
+  }
+}
+
+export class ASREmptyResultError extends ASRError {
+  constructor(provider: string) {
+    super("ASR returned empty transcript", "empty_result", provider, false);
+    this.name = "ASREmptyResultError";
+  }
+}

package/src/asr/index.ts

@@ -0,0 +1,11 @@
+export { transcribeTencentFlash, type TencentFlashASRConfig } from "./tencent-flash.js";
+export {
+  ASRError,
+  ASRTimeoutError,
+  ASRAuthError,
+  ASRRequestError,
+  ASRResponseParseError,
+  ASRServiceError,
+  ASREmptyResultError,
+  type ASRErrorKind,
+} from "./errors.js";

package/src/asr/tencent-flash.ts

@@ -0,0 +1,165 @@
+import { createHmac } from "node:crypto";
+import {
+  ASRAuthError,
+  ASREmptyResultError,
+  ASRRequestError,
+  ASRResponseParseError,
+  ASRServiceError,
+  ASRTimeoutError,
+} from "./errors.js";
+
+const ASR_FLASH_HOST = "asr.cloud.tencent.com";
+const ASR_FLASH_PATH_PREFIX = "/asr/flash/v1";
+const ASR_FLASH_URL_PREFIX = `https://${ASR_FLASH_HOST}${ASR_FLASH_PATH_PREFIX}`;
+const ASR_PROVIDER = "tencent-flash";
+
+export interface TencentFlashASRConfig {
+  appId: string;
+  secretId: string;
+  secretKey: string;
+  engineType?: string;
+  voiceFormat?: string;
+  timeoutMs?: number;
+}
+
+interface TencentFlashResponseSentence {
+  text?: string;
+}
+
+interface TencentFlashResponseItem {
+  text?: string;
+  sentence_list?: TencentFlashResponseSentence[];
+}
+
+interface TencentFlashResponse {
+  code?: number;
+  message?: string;
+  flash_result?: TencentFlashResponseItem[];
+}
+
+function encodeQueryValue(value: string): string {
+  return encodeURIComponent(value)
+    .replace(/%20/g, "+")
+    .replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+function buildSignedQuery(params: Record<string, string>): string {
+  return Object.entries(params)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeQueryValue(value)}`)
+    .join("&");
+}
+
+function extractTranscript(payload: TencentFlashResponse): string {
+  const items = Array.isArray(payload.flash_result) ? payload.flash_result : [];
+  const lines: string[] = [];
+
+  for (const item of items) {
+    if (typeof item?.text === "string" && item.text.trim()) {
+      lines.push(item.text.trim());
+      continue;
+    }
+    const sentenceList = Array.isArray(item?.sentence_list) ? item.sentence_list : [];
+    for (const sentence of sentenceList) {
+      if (typeof sentence?.text === "string" && sentence.text.trim()) {
+        lines.push(sentence.text.trim());
+      }
+    }
+  }
+
+  return lines.join("\n").trim();
+}
+
+export async function transcribeTencentFlash(params: {
+  audio: Buffer;
+  config: TencentFlashASRConfig;
+}): Promise<string> {
+  const { audio, config } = params;
+  const timestamp = Math.floor(Date.now() / 1000).toString();
+  const engineType = config.engineType ?? "16k_zh";
+  const voiceFormat = config.voiceFormat ?? "silk";
+  const query = buildSignedQuery({
+    engine_type: engineType,
+    secretid: config.secretId,
+    timestamp,
+    voice_format: voiceFormat,
+  });
+
+  const signText = `POST${ASR_FLASH_HOST}${ASR_FLASH_PATH_PREFIX}/${config.appId}?${query}`;
+  const authorization = createHmac("sha1", config.secretKey).update(signText).digest("base64");
+  const url = `${ASR_FLASH_URL_PREFIX}/${config.appId}?${query}`;
+  const timeoutMs = config.timeoutMs ?? 30000;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: authorization,
+        "Content-Type": "application/octet-stream",
+      },
+      body: audio,
+      signal: controller.signal,
+    });
+
+    const bodyText = await response.text();
+    let payload: TencentFlashResponse;
+    try {
+      payload = JSON.parse(bodyText) as TencentFlashResponse;
+    } catch {
+      throw new ASRResponseParseError(ASR_PROVIDER, bodyText.slice(0, 300));
+    }
+
+    if (!response.ok) {
+      const message = payload.message ?? `HTTP ${response.status}`;
+      if (response.status === 401 || response.status === 403) {
+        throw new ASRAuthError(
+          ASR_PROVIDER,
+          `Tencent Flash ASR authentication failed: ${message}`,
+          response.status
+        );
+      }
+      throw new ASRRequestError(
+        ASR_PROVIDER,
+        `Tencent Flash ASR request failed: ${message}`,
+        response.status
+      );
+    }
+
+    if (payload.code !== 0) {
+      throw new ASRServiceError(
+        ASR_PROVIDER,
+        `Tencent Flash ASR failed: ${payload.message ?? "unknown error"} (code=${payload.code})`
+        ,
+        payload.code
+      );
+    }
+
+    const transcript = extractTranscript(payload);
+    if (!transcript) {
+      throw new ASREmptyResultError(ASR_PROVIDER);
+    }
+    return transcript;
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new ASRTimeoutError(ASR_PROVIDER, timeoutMs);
+    }
+    if (
+      error instanceof ASRResponseParseError ||
+      error instanceof ASRAuthError ||
+      error instanceof ASRRequestError ||
+      error instanceof ASRServiceError ||
+      error instanceof ASREmptyResultError ||
+      error instanceof ASRTimeoutError
+    ) {
+      throw error;
+    }
+    throw new ASRRequestError(
+      ASR_PROVIDER,
+      `Tencent Flash ASR request failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/index.ts

@@ -4,7 +4,8 @@
 export * from "./logger/index.js";
 export * from "./policy/index.js";
 export * from "./http/index.js";
-export * from "./types/common.js";
-export * from "./file/index.js";
-export * from "./media/index.js";
-export * from "./cron/index.js";
+export * from "./types/common.js";
+export * from "./file/index.js";
+export * from "./media/index.js";
+export * from "./cron/index.js";
+export * from "./asr/index.js";

package/src/media/media-io.test.ts

@@ -1,180 +0,0 @@
-import { afterEach, describe, expect, it } from "vitest";
-import * as fs from "node:fs";
-import * as fsPromises from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
-import {
-  FileSizeLimitError,
-  MediaTimeoutError,
-  cleanupFileSafe,
-  downloadToTempFile,
-  finalizeInboundMediaFile,
-  pruneInboundMediaDir,
-} from "./media-io.js";
-
-const tempDirs: string[] = [];
-
-async function createTempDir(prefix: string): Promise<string> {
-  const dir = await fsPromises.mkdtemp(path.join(os.tmpdir(), prefix));
-  tempDirs.push(dir);
-  return dir;
-}
-
-afterEach(async () => {
-  for (const dir of tempDirs.splice(0, tempDirs.length)) {
-    await fsPromises.rm(dir, { recursive: true, force: true });
-  }
-});
-
-describe("downloadToTempFile", () => {
-  it("downloads HTTP response and stores a temp file", async () => {
-    const dir = await createTempDir("shared-media-io-");
-    const body = Buffer.from("hello-media", "utf8");
-    const fetchFn: typeof globalThis.fetch = async () =>
-      new Response(body, {
-        status: 200,
-        headers: {
-          "content-type": "image/png",
-          "content-length": String(body.length),
-        },
-      });
-
-    const result = await downloadToTempFile("https://example.com/a.png", {
-      fetch: fetchFn,
-      tempDir: dir,
-      tempPrefix: "dingtalk-file",
-    });
-
-    expect(result.path.startsWith(dir)).toBe(true);
-    expect(result.fileName.endsWith(".png")).toBe(true);
-    expect(result.size).toBe(body.length);
-    expect(result.contentType).toBe("image/png");
-
-    const saved = await fsPromises.readFile(result.path);
-    expect(saved.equals(body)).toBe(true);
-  });
-
-  it("throws FileSizeLimitError when Content-Length exceeds maxSize", async () => {
-    const fetchFn: typeof globalThis.fetch = async () =>
-      new Response("too-large", {
-        status: 200,
-        headers: {
-          "content-type": "application/octet-stream",
-          "content-length": "1024",
-        },
-      });
-
-    await expect(
-      downloadToTempFile("https://example.com/too-large.bin", {
-        fetch: fetchFn,
-        maxSize: 100,
-      })
-    ).rejects.toBeInstanceOf(FileSizeLimitError);
-  });
-
-  it("throws MediaTimeoutError on timeout", async () => {
-    const fetchFn: typeof globalThis.fetch = async (_url, init) =>
-      await new Promise<Response>((_resolve, reject) => {
-        const signal = init?.signal;
-        signal?.addEventListener("abort", () => {
-          const err = new Error("aborted");
-          (err as Error & { name: string }).name = "AbortError";
-          reject(err);
-        });
-      });
-
-    await expect(
-      downloadToTempFile("https://example.com/slow.bin", {
-        fetch: fetchFn,
-        timeout: 10,
-      })
-    ).rejects.toBeInstanceOf(MediaTimeoutError);
-  });
-});
-
-describe("cleanupFileSafe", () => {
-  it("removes file and ignores missing file", async () => {
-    const dir = await createTempDir("shared-media-clean-");
-    const filePath = path.join(dir, "a.txt");
-    await fsPromises.writeFile(filePath, "x", "utf8");
-    expect(fs.existsSync(filePath)).toBe(true);
-
-    await cleanupFileSafe(filePath);
-    expect(fs.existsSync(filePath)).toBe(false);
-
-    await expect(cleanupFileSafe(filePath)).resolves.toBeUndefined();
-    await expect(cleanupFileSafe(undefined)).resolves.toBeUndefined();
-  });
-});
-
-describe("inbound media retention", () => {
-  it("finalizes temp media into inbound/YYYY-MM-DD", async () => {
-    const tempDir = await createTempDir("shared-media-temp-");
-    const inboundDir = await createTempDir("shared-media-inbound-");
-    const sourcePath = path.join(tempDir, "img-1.jpg");
-    await fsPromises.writeFile(sourcePath, "abc", "utf8");
-
-    const finalPath = await finalizeInboundMediaFile({
-      filePath: sourcePath,
-      tempDir,
-      inboundDir,
-    });
-
-    expect(finalPath.startsWith(inboundDir)).toBe(true);
-    expect(fs.existsSync(finalPath)).toBe(true);
-    expect(fs.existsSync(sourcePath)).toBe(false);
-  });
-
-  it("does not move files outside tempDir", async () => {
-    const tempDir = await createTempDir("shared-media-temp-");
-    const inboundDir = await createTempDir("shared-media-inbound-");
-    const outsideDir = await createTempDir("shared-media-outside-");
-    const sourcePath = path.join(outsideDir, "a.txt");
-    await fsPromises.writeFile(sourcePath, "x", "utf8");
-
-    const finalPath = await finalizeInboundMediaFile({
-      filePath: sourcePath,
-      tempDir,
-      inboundDir,
-    });
-
-    expect(finalPath).toBe(sourcePath);
-    expect(fs.existsSync(sourcePath)).toBe(true);
-  });
-
-  it("prunes only expired files in date dirs and keeps recent files", async () => {
-    const inboundDir = await createTempDir("shared-media-prune-");
-    const oldDir = path.join(inboundDir, "2024-01-01");
-    const newDir = path.join(inboundDir, "2024-01-02");
-    await fsPromises.mkdir(oldDir, { recursive: true });
-    await fsPromises.mkdir(newDir, { recursive: true });
-
-    const oldFile = path.join(oldDir, "old.jpg");
-    const newFile = path.join(newDir, "new.jpg");
-    const nestedDir = path.join(oldDir, "nested");
-    const nestedFile = path.join(nestedDir, "nested.jpg");
-    await fsPromises.writeFile(oldFile, "old", "utf8");
-    await fsPromises.writeFile(newFile, "new", "utf8");
-    await fsPromises.mkdir(nestedDir, { recursive: true });
-    await fsPromises.writeFile(nestedFile, "nested", "utf8");
-
-    const oldTs = new Date("2024-01-01T00:00:00.000Z");
-    const newTs = new Date("2024-01-02T00:00:00.000Z");
-    await fsPromises.utimes(oldDir, oldTs, oldTs);
-    await fsPromises.utimes(oldFile, oldTs, oldTs);
-    await fsPromises.utimes(newDir, newTs, newTs);
-    await fsPromises.utimes(newFile, newTs, newTs);
-
-    const nowMs = new Date("2024-01-03T00:00:00.000Z").getTime();
-    await pruneInboundMediaDir({
-      inboundDir,
-      keepDays: 1,
-      nowMs,
-    });
-
-    expect(fs.existsSync(oldFile)).toBe(false);
-    expect(fs.existsSync(newFile)).toBe(true);
-    expect(fs.existsSync(nestedFile)).toBe(true);
-    expect(fs.existsSync(oldDir)).toBe(true);
-  });
-});