@downcity/plugins 1.0.56 → 1.0.59

package/src/tts/Plugin.ts

@@ -1,517 +1,250 @@
 /**
- * TTS Plugin。
+ * TtsPlugin：文本转语音插件。
  *
  * 关键点（中文）
- * - TTS Plugin 现在自己内聚本地模型与 Python 依赖，不再依赖 console 模型池。
- * - Console 只通过 setup / action 与插件交互，保持极简统一。
+ * - TTS 能力通过 constructor 注入，推荐传入 `city.ai.tts`。
+ * - plugin 不负责本地模型、Python 依赖、provider 或项目配置。
+ * - action 返回 AI SDK UIMessage，音频 file part 会由 plugin tool bridge 统一落盘到资源目录。
  */
 
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
-import type { Plugin } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  JsonObject,
+  JsonValue,
+} from "@downcity/agent/internal/types/common/Json.js";
 import type {
-  TtsInstallInput,
-  TtsPluginConfig,
-  TtsSynthesizeInput,
+  TtsPluginInput,
+  TtsPluginOptions,
+  TtsPluginResult,
+  TtsPluginSimpleAudioResult,
+  TtsPluginUiMessageResult,
 } from "@/tts/types/TtsPlugin.js";
-import { isPluginEnabled } from "@downcity/agent/internal/plugin/core/Activation.js";
-import { writeProjectPluginEnabled } from "@downcity/agent/internal/plugin/core/ProjectConfigStore.js";
-import {
-  checkTtsSynthesizer,
-  installTtsSynthesizer,
-  listTtsModelOptions,
-  readTtsPluginConfig,
-  writeTtsPluginConfig,
-} from "@/tts/Dependency.js";
-import { resolveTtsModelId } from "@/tts/runtime/Catalog.js";
-import { synthesizeSpeechFile } from "@/tts/runtime/Synthesizer.js";
-import {
-  getBooleanOpt,
-  getNumberOpt,
-  getStringOpt,
-  toJsonObject,
-} from "@/tts/PluginSupport.js";
 
-function createTtsPluginDefinition(plugin: Plugin): Plugin {
+const DEFAULT_TTS_PLUGIN_NAME = "tts";
+const DEFAULT_TTS_PLUGIN_TITLE = "TTS";
+const DEFAULT_TTS_PLUGIN_DESCRIPTION =
+  "Synthesize speech through an injected TTS function and return assistant audio file parts.";
+const DEFAULT_MEDIA_TYPE = "audio/wav";
+const DEFAULT_FILENAME = "speech.wav";
+
+/**
+ * 判断值是否为普通对象。
+ */
+function to_record(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+/**
+ * 归一化 action payload。
+ */
+function normalize_tts_payload(payload: JsonValue | undefined): TtsPluginInput {
+  const record = to_record(payload ?? {});
+  if (!record) {
+    throw new TypeError("TtsPlugin.synthesize payload must be an object");
+  }
+  const text = typeof record.text === "string" ? record.text.trim() : "";
+  if (!text) {
+    throw new Error("TtsPlugin.synthesize requires text");
+  }
   return {
-    name: "tts",
-  title: "Text To Speech",
-  description:
-    "Generates local speech audio files from plain text through an installed TTS model, then returns a reusable audio file tag for downstream sending.",
-  config: {
-    plugin: "tts",
-    scope: "project",
-    defaultValue: {
-      provider: "local",
-      modelId: "qwen3-tts-0.6b",
-      format: "wav",
-      speed: 1,
-    },
-  },
-  setup: {
-    mode: "install-configure",
-    title: "安装语音合成",
-    description: "选择模型后直接完成模型下载、独立运行环境准备与配置写入。",
-    fields: [
-      {
-        key: "modelId",
-        label: "模型",
-        type: "select",
-        required: true,
-        sourceAction: "models",
-      },
-      {
-        key: "format",
-        label: "输出格式",
-        type: "select",
-        required: true,
-        options: [
-          { label: "WAV", value: "wav" },
-          { label: "FLAC", value: "flac" },
-        ],
-      },
-    ],
-    primaryAction: "install",
-    statusAction: "status",
-  },
-  usage: {
-    title: "配置语音合成",
-    description: "设置当前 agent 默认使用的语音模型与输出参数。",
-    fields: [
-      {
-        key: "modelId",
-        label: "默认模型",
-        type: "select",
-        required: true,
-        sourceAction: "models",
-      },
-      {
-        key: "format",
-        label: "输出格式",
-        type: "select",
-        required: true,
-        options: [
-          { label: "WAV", value: "wav", description: "兼容性最好，适合绝大多数渠道。" },
-          { label: "FLAC", value: "flac", description: "体积更小，适合存档或传输。" },
-        ],
-      },
-      {
-        key: "speed",
-        label: "默认语速",
-        type: "number",
-        placeholder: "1",
-        description: "1 为正常语速，可按需要设置为 0.8、1.2 等。",
-      },
-      {
-        key: "language",
-        label: "默认语言提示",
-        type: "string",
-        placeholder: "auto / zh / en",
-      },
+    ...(record as TtsPluginInput),
+    text,
+  };
+}
+
+/**
+ * 判断返回值是否已经是 AI SDK UIMessage。
+ */
+function is_ui_message_result(value: TtsPluginResult): value is TtsPluginUiMessageResult {
+  const record = to_record(value);
+  return Boolean(record && Array.isArray(record.parts));
+}
+
+/**
+ * 读取简单音频结果中的 URL。
+ */
+function read_audio_url(record: Record<string, unknown>): string {
+  const url =
+    typeof record.url === "string"
+      ? record.url.trim()
+      : typeof record.data_url === "string"
+        ? record.data_url.trim()
+        : typeof record.audio_path === "string"
+          ? record.audio_path.trim()
+          : "";
+  if (!url) {
+    throw new TypeError(
+      "TtsPlugin tts function must return a UIMessage or { url | data_url | audio_path }",
+    );
+  }
+  return url;
+}
+
+/**
+ * 把简单音频结果归一为 UIMessage。
+ */
+function simple_audio_to_ui_message(
+  result: TtsPluginSimpleAudioResult,
+): TtsPluginUiMessageResult {
+  const record = to_record(result);
+  if (!record) {
+    throw new TypeError("TtsPlugin tts function returned an invalid result");
+  }
+  const url = read_audio_url(record);
+  const media_type =
+    typeof record.media_type === "string" && record.media_type.trim()
+      ? record.media_type.trim()
+      : DEFAULT_MEDIA_TYPE;
+  const filename =
+    typeof record.filename === "string" && record.filename.trim()
+      ? record.filename.trim()
+      : DEFAULT_FILENAME;
+  const text = typeof record.text === "string" ? record.text.trim() : "";
+
+  return {
+    id: `tts:${Date.now()}`,
+    role: "assistant",
+    parts: [
+      ...(text ? [{ type: "text" as const, text }] : []),
       {
-        key: "voice",
-        label: "默认音色",
-        type: "string",
-        placeholder: "可选音色 ID",
+        type: "file" as const,
+        mediaType: media_type,
+        filename,
+        url,
       },
     ],
-    saveAction: "configure",
-    statusAction: "status",
-  },
-  async availability(context) {
-    if (!isPluginEnabled({ plugin, context })) {
-      return {
-        enabled: false,
-        available: false,
-        reasons: ["tts plugin disabled in project config"],
-      };
+  };
+}
+
+/**
+ * 校验并归一化 TTS 返回结果。
+ */
+function normalize_tts_result(result: TtsPluginResult): TtsPluginUiMessageResult {
+  if (is_ui_message_result(result)) {
+    return result;
+  }
+  return simple_audio_to_ui_message(result);
+}
+
+/**
+ * Agent TTS 插件。
+ */
+export class TtsPlugin extends BasePlugin {
+  /**
+   * 当前 plugin 稳定名称。
+   */
+  readonly name: string;
+
+  /**
+   * 插件标题。
+   */
+  readonly title: string;
+
+  /**
+   * 插件说明。
+   */
+  readonly description: string;
+
+  private readonly tts: TtsPluginOptions["tts"];
+  private readonly language?: string;
+  private readonly voice?: string;
+  private readonly format?: string;
+
+  constructor(options: TtsPluginOptions) {
+    super();
+    const name = String(options.name || DEFAULT_TTS_PLUGIN_NAME).trim();
+    if (!name) {
+      throw new Error("TtsPlugin requires a non-empty name");
     }
-    const dependencyStatus = await checkTtsSynthesizer(context);
-    return {
-      enabled: true,
-      available: dependencyStatus.available,
-      reasons: dependencyStatus.reasons,
-    };
-  },
-  actions: {
-    status: {
-      allowWhenDisabled: true,
-      command: {
-        description: "查看 tts plugin 当前状态",
-        mapInput() {
-          return {};
-        },
-      },
-      execute: async ({ context }) => {
-        const config = readTtsPluginConfig(context);
-        const availability = await plugin.availability!(context);
-        const synthesizer = await checkTtsSynthesizer(context);
-        return {
-          success: true,
-          data: {
-            plugin: toJsonObject(config) || {},
-            availability: {
-              enabled: availability.enabled,
-              available: availability.available,
-              reasons: availability.reasons,
-            },
-            synthesizer: {
-              available: synthesizer.available,
-              reasons: synthesizer.reasons,
-              details: synthesizer.details || null,
-            },
-          },
-        };
-      },
-    },
-    doctor: {
-      allowWhenDisabled: true,
-      command: {
-        description: "检查 tts plugin 依赖状态",
-        mapInput() {
-          return {};
-        },
-      },
-      execute: async ({ context }) => {
-        const result = await checkTtsSynthesizer(context);
-        return {
-          success: true,
-          data: {
-            available: result.available,
-            reasons: result.reasons,
-            details: result.details || null,
-          },
-        };
-      },
-    },
-    models: {
-      allowWhenDisabled: true,
-      command: {
-        description: "列出可用于 tts 的本地模型",
-        mapInput() {
-          return {};
-        },
-      },
-      execute: async () => {
-        return {
-          success: true,
-          data: {
-            options: listTtsModelOptions(),
-          },
-        };
-      },
-    },
-    install: {
-      allowWhenDisabled: true,
-      command: {
-        description: "安装 tts 语音合成依赖",
-        configure(command) {
-          command
-            .argument("[models...]")
-            .option("--active-model <modelId>", "安装完成后设为当前模型")
-            .option("--models-dir <path>", "模型目录（可选）")
-            .option("--python <bin>", "Python 可执行文件（默认 python3）")
-            .option("--no-install-deps", "跳过依赖安装")
-            .option("--force", "强制覆盖已存在资源")
-            .option("--hf-token <token>", "HuggingFace token（可选）")
-            .option("--format <format>", "默认输出格式（wav/flac）");
-        },
-        mapInput({ args, opts }) {
-          return {
-            modelIds: args,
-            ...(getStringOpt(opts, "activeModel")
-              ? { activeModel: getStringOpt(opts, "activeModel") }
-              : {}),
-            ...(getStringOpt(opts, "modelsDir")
-              ? { modelsDir: getStringOpt(opts, "modelsDir") }
-              : {}),
-            ...(getStringOpt(opts, "python")
-              ? { pythonBin: getStringOpt(opts, "python") }
-              : {}),
-            installDeps: getBooleanOpt(opts, "installDeps", true),
-            force: getBooleanOpt(opts, "force", false),
-            ...(getStringOpt(opts, "hfToken")
-              ? { hfToken: getStringOpt(opts, "hfToken") }
-              : {}),
-            ...(getStringOpt(opts, "format")
-              ? { format: getStringOpt(opts, "format") }
-              : {}),
-          };
-        },
-      },
-      execute: async ({ context, payload }) => {
-        const result = await installTtsSynthesizer({
-          context,
-          input:
-            payload && typeof payload === "object" && !Array.isArray(payload)
-              ? (payload as TtsInstallInput)
-              : undefined,
-        });
-        return {
-          success: result.success,
-          ...(result.message ? { message: result.message } : {}),
-          ...(result.details !== undefined ? { data: result.details } : {}),
-          ...(result.success ? {} : { error: result.message || "install failed" }),
-        };
-      },
-    },
-    configure: {
-      allowWhenDisabled: true,
-      execute: async ({ context, payload }) => {
-        const payloadObject =
-          payload && typeof payload === "object" && !Array.isArray(payload)
-            ? (payload as Partial<TtsPluginConfig> & Record<string, unknown>)
-            : {};
-        const { enabled: _ignoredEnabled, ...patch } = payloadObject;
-        const current = readTtsPluginConfig(context);
-        const next = {
-          ...current,
-          ...(patch as Partial<TtsPluginConfig>),
-        } satisfies TtsPluginConfig;
-        await writeTtsPluginConfig({
-          context,
-          value: next,
-        });
-        return {
-          success: true,
-          data: {
-            plugin: toJsonObject(next) || {},
-          },
-        };
-      },
-    },
-    on: {
-      allowWhenDisabled: true,
-      command: {
-        description: "启用 tts plugin，并可选安装本地依赖",
-        configure(command) {
-          command
-            .argument("[models...]")
-            .option("--active-model <modelId>", "安装完成后设为当前模型")
-            .option("--models-dir <path>", "模型目录（可选）")
-            .option("--python <bin>", "Python 可执行文件（默认 python3）")
-            .option("--no-install", "仅启用 plugin，不安装依赖")
-            .option("--no-install-deps", "跳过依赖安装")
-            .option("--force", "强制覆盖已存在资源")
-            .option("--hf-token <token>", "HuggingFace token（可选）")
-            .option("--format <format>", "默认输出格式（wav/flac）");
-        },
-        mapInput({ args, opts }) {
-          return {
-            modelIds: args,
-            ...(getStringOpt(opts, "activeModel")
-              ? { activeModel: getStringOpt(opts, "activeModel") }
-              : {}),
-            ...(getStringOpt(opts, "modelsDir")
-              ? { modelsDir: getStringOpt(opts, "modelsDir") }
-              : {}),
-            ...(getStringOpt(opts, "python")
-              ? { pythonBin: getStringOpt(opts, "python") }
-              : {}),
-            install: getBooleanOpt(opts, "install", true),
-            installDeps: getBooleanOpt(opts, "installDeps", true),
-            force: getBooleanOpt(opts, "force", false),
-            ...(getStringOpt(opts, "hfToken")
-              ? { hfToken: getStringOpt(opts, "hfToken") }
-              : {}),
-            ...(getStringOpt(opts, "format")
-              ? { format: getStringOpt(opts, "format") }
-              : {}),
-          };
-        },
-      },
-      execute: async ({ context, payload }) => {
-        await writeProjectPluginEnabled({
-          pluginName: "tts",
-          enabled: true,
-          context,
-        });
-        if ((payload as { install?: unknown }).install !== false) {
-          const installResult = await installTtsSynthesizer({
-            context,
-            input:
-              payload && typeof payload === "object" && !Array.isArray(payload)
-                ? (payload as TtsInstallInput)
-                : undefined,
-          });
-          if (!installResult.success) {
-            return {
-              success: false,
-              error: installResult.message || "tts dependency install failed",
-              message: installResult.message || "tts dependency install failed",
-            };
-          }
-        }
-        return {
-          success: true,
-          data: {
-            plugin: toJsonObject(readTtsPluginConfig(context) as Record<string, unknown>) || {},
-          },
-        };
-      },
-    },
-    off: {
-      command: {
-        description: "关闭 tts plugin",
-        mapInput() {
-          return {};
-        },
-      },
-      execute: async ({ context }) => {
-        await writeProjectPluginEnabled({
-          pluginName: "tts",
-          enabled: false,
-          context,
-        });
-        return {
-          success: true,
-          data: {
-            plugin: toJsonObject(readTtsPluginConfig(context) as Record<string, unknown>) || {},
-          },
-        };
-      },
-    },
-    use: {
-      allowWhenDisabled: true,
-      command: {
-        description: "切换 tts 当前模型",
-        configure(command) {
-          command.argument("<modelId>");
-        },
-        mapInput({ args }) {
-          const modelId = String(args[0] || "").trim();
-          if (!modelId) {
-            throw new Error("modelId is required");
-          }
-          return {
-            modelId,
-          };
-        },
-      },
-      execute: async ({ context, payload }) => {
-        const modelId = String((payload as { modelId?: unknown }).modelId || "").trim();
-        const resolvedModelId = resolveTtsModelId(modelId);
-        if (!resolvedModelId) {
-          return {
-            success: false,
-            error: `Unsupported tts model: ${modelId}`,
-            message: `Unsupported tts model: ${modelId}`,
-          };
-        }
-        const nextConfig = await writeTtsPluginConfig({
-          context,
-          value: {
-            ...readTtsPluginConfig(context),
-            modelId: resolvedModelId,
-          },
-        });
-        return {
-          success: true,
-          data: {
-            plugin: toJsonObject(nextConfig as Record<string, unknown>) || {},
-          },
-        };
-      },
-    },
+    if (typeof options.tts !== "function") {
+      throw new Error("TtsPlugin requires a tts function");
+    }
+    this.name = name;
+    this.title = String(options.title || DEFAULT_TTS_PLUGIN_TITLE).trim();
+    this.description = String(
+      options.description || DEFAULT_TTS_PLUGIN_DESCRIPTION,
+    ).trim();
+    this.tts = options.tts;
+    this.language =
+      typeof options.language === "string" && options.language.trim()
+        ? options.language.trim()
+        : undefined;
+    this.voice =
+      typeof options.voice === "string" && options.voice.trim()
+        ? options.voice.trim()
+        : undefined;
+    this.format =
+      typeof options.format === "string" && options.format.trim()
+        ? options.format.trim()
+        : undefined;
+  }
+
+  /**
+   * TTS 插件给模型的使用说明。
+   */
+  system(_context: AgentContext): string {
+    return [
+      "# TTS Plugin",
+      "",
+      "Use this plugin when the user asks to create spoken audio, voice output, narration, or a reusable audio file.",
+      "Do not call it for ordinary text replies unless the user explicitly wants audio.",
+      "",
+      "Call through `plugin_call`:",
+      "",
+      "```ts",
+      "plugin_call({",
+      `  plugin: "${this.name}",`,
+      '  action: "synthesize",',
+      "  payload: {",
+      '    text: "...",',
+      "  },",
+      "});",
+      "```",
+      "",
+      "Payload rules:",
+      "- `text` is required.",
+      "- Optional fields: `language`, `voice`, `format`, `speed`, `provider_options`.",
+      "- The returned audio file part is saved under project `.downcity/resources` and attached to the final assistant message automatically.",
+    ].join("\n");
+  }
+
+  /**
+   * 执行一次 TTS 合成。
+   */
+  private async synthesize(input: TtsPluginInput): Promise<TtsPluginUiMessageResult> {
+    const result = await this.tts({
+      ...(this.language ? { language: this.language } : {}),
+      ...(this.voice ? { voice: this.voice } : {}),
+      ...(this.format ? { format: this.format } : {}),
+      ...input,
+    });
+    return normalize_tts_result(result);
+  }
+
+  /**
+   * 显式 action 集合。
+   */
+  readonly actions = {
     synthesize: {
-      command: {
-        description: "将文本生成语音文件",
-        configure(command) {
-          command
-            .argument("<text>")
-            .option("--model <modelId>", "语音模型 ID")
-            .option("--language <language>", "语言提示（可选，例如 zh / en）")
-            .option("--voice <voice>", "音色 ID（可选）")
-            .option("--format <format>", "输出格式（wav/flac）")
-            .option("--speed <speed>", "语速倍率", Number)
-            .option("--output <path>", "输出文件路径或目录（可选）");
-        },
-        mapInput({ args, opts }) {
-          const text = String(args[0] || "").trim();
-          if (!text) {
-            throw new Error("text is required");
-          }
+      execute: async ({ payload }: { payload: JsonValue }) => {
+        try {
+          const input = normalize_tts_payload(payload);
+          const message = await this.synthesize(input);
           return {
-            text,
-            ...(getStringOpt(opts, "model")
-              ? { modelId: getStringOpt(opts, "model") }
-              : {}),
-            ...(getStringOpt(opts, "language")
-              ? { language: getStringOpt(opts, "language") }
-              : {}),
-            ...(getStringOpt(opts, "voice")
-              ? { voice: getStringOpt(opts, "voice") }
-              : {}),
-            ...(getStringOpt(opts, "format")
-              ? { format: getStringOpt(opts, "format") }
-              : {}),
-            ...(typeof getNumberOpt(opts, "speed") === "number"
-              ? { speed: getNumberOpt(opts, "speed") }
-              : {}),
-            ...(getStringOpt(opts, "output")
-              ? { output: getStringOpt(opts, "output") }
-              : {}),
+            success: true,
+            data: message as unknown as JsonObject,
+            message: "speech synthesized",
           };
-        },
-      },
-      execute: async ({ context, payload }) => {
-        const pluginStatus = await plugin.availability!(context);
-        if (!pluginStatus.enabled || !pluginStatus.available) {
+        } catch (error) {
           return {
             success: false,
-            error: pluginStatus.reasons[0] || "tts plugin unavailable",
-            message: pluginStatus.reasons[0] || "tts plugin unavailable",
+            error: String(error),
+            message: String(error),
           };
         }
-
-        const input =
-          payload && typeof payload === "object" && !Array.isArray(payload)
-            ? (payload as TtsSynthesizeInput)
-            : {};
-        const result = await synthesizeSpeechFile({
-          context,
-          config: readTtsPluginConfig(context),
-          input,
-        });
-        return {
-          success: true,
-          data: {
-            outputPath: result.outputPath,
-            fileTag: result.fileTag,
-            bytes: result.bytes,
-            ...(result.stderrSummary ? { stderr: result.stderrSummary } : {}),
-          },
-        };
       },
     },
-  },
-  system(context) {
-    if (!isPluginEnabled({ plugin, context })) {
-      return "";
-    }
-    return [
-      "# TTS Plugin",
-      "The agent can call the tts plugin to synthesize speech audio from plain text.",
-      "Typical usage flow:",
-      "1. Check availability with the `status` action when you need to confirm whether the plugin and model are ready.",
-      "2. Generate audio with the `synthesize` action.",
-      "3. Optionally override synthesis parameters in the action payload: `voice`, `language`, `format`, `speed`, and `output`.",
-      "Use the `tts.synthesize` action when the user asks to generate spoken audio or a reusable audio file tag.",
-      "A successful synthesis returns a local output path and a reusable `<file type=\"audio\">...</file>` tag for downstream sending.",
-      "If the Python runner prints non-fatal stderr, the command still succeeds and returns that stderr summary as extra context.",
-      "Example: `plugin_call({ plugin: \"tts\", action: \"synthesize\", payload: { text: \"你好，欢迎来到 Downcity\", format: \"wav\" } })`",
-    ].join("\n");
-  },
   };
 }
-
-/**
- * TtsPlugin：文本转语音插件。
- */
-export class TtsPlugin extends BasePlugin {
-  readonly name = "tts";
-
-  constructor() {
-    super();
-    Object.assign(this, createTtsPluginDefinition(this));
-  }
-}