@downcity/plugins 1.0.56 → 1.0.59

package/bin/tts/Plugin.js

@@ -1,491 +1,214 @@
 /**
- * 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 { 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) {
+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) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+/**
+ * 归一化 action payload。
+ */
+function normalize_tts_payload(payload) {
+    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",
-                },
-                {
-                    key: "voice",
-                    label: "默认音色",
-                    type: "string",
-                    placeholder: "可选音色 ID",
-                },
-            ],
-            saveAction: "configure",
-            statusAction: "status",
-        },
-        async availability(context) {
-            if (!isPluginEnabled({ plugin, context })) {
-                return {
-                    enabled: false,
-                    available: false,
-                    reasons: ["tts plugin disabled in project config"],
-                };
-            }
-            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
-                            : 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
-                        : {};
-                    const { enabled: _ignoredEnabled, ...patch } = payloadObject;
-                    const current = readTtsPluginConfig(context);
-                    const next = {
-                        ...current,
-                        ...patch,
-                    };
-                    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.install !== false) {
-                        const installResult = await installTtsSynthesizer({
-                            context,
-                            input: payload && typeof payload === "object" && !Array.isArray(payload)
-                                ? payload
-                                : 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)) || {},
-                        },
-                    };
-                },
-            },
-            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)) || {},
-                        },
-                    };
-                },
+        ...record,
+        text,
+    };
+}
+/**
+ * 判断返回值是否已经是 AI SDK UIMessage。
+ */
+function is_ui_message_result(value) {
+    const record = to_record(value);
+    return Boolean(record && Array.isArray(record.parts));
+}
+/**
+ * 读取简单音频结果中的 URL。
+ */
+function read_audio_url(record) {
+    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) {
+    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", text }] : []),
+            {
+                type: "file",
+                mediaType: media_type,
+                filename,
+                url,
             },
-            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.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,
-                        },
-                    });
+        ],
+    };
+}
+/**
+ * 校验并归一化 TTS 返回结果。
+ */
+function normalize_tts_result(result) {
+    if (is_ui_message_result(result)) {
+        return result;
+    }
+    return simple_audio_to_ui_message(result);
+}
+/**
+ * Agent TTS 插件。
+ */
+export class TtsPlugin extends BasePlugin {
+    /**
+     * 当前 plugin 稳定名称。
+     */
+    name;
+    /**
+     * 插件标题。
+     */
+    title;
+    /**
+     * 插件说明。
+     */
+    description;
+    tts;
+    language;
+    voice;
+    format;
+    constructor(options) {
+        super();
+        const name = String(options.name || DEFAULT_TTS_PLUGIN_NAME).trim();
+        if (!name) {
+            throw new Error("TtsPlugin requires a non-empty name");
+        }
+        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) {
+        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 合成。
+     */
+    async synthesize(input) {
+        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 集合。
+     */
+    actions = {
+        synthesize: {
+            execute: async ({ payload }) => {
+                try {
+                    const input = normalize_tts_payload(payload);
+                    const message = await this.synthesize(input);
                     return {
                         success: true,
-                        data: {
-                            plugin: toJsonObject(nextConfig) || {},
-                        },
+                        data: message,
+                        message: "speech synthesized",
                     };
-                },
-            },
-            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");
-                        }
-                        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") }
-                                : {}),
-                        };
-                    },
-                },
-                execute: async ({ context, payload }) => {
-                    const pluginStatus = await plugin.availability(context);
-                    if (!pluginStatus.enabled || !pluginStatus.available) {
-                        return {
-                            success: false,
-                            error: pluginStatus.reasons[0] || "tts plugin unavailable",
-                            message: pluginStatus.reasons[0] || "tts plugin unavailable",
-                        };
-                    }
-                    const input = payload && typeof payload === "object" && !Array.isArray(payload)
-                        ? payload
-                        : {};
-                    const result = await synthesizeSpeechFile({
-                        context,
-                        config: readTtsPluginConfig(context),
-                        input,
-                    });
+                }
+                catch (error) {
                     return {
-                        success: true,
-                        data: {
-                            outputPath: result.outputPath,
-                            fileTag: result.fileTag,
-                            bytes: result.bytes,
-                            ...(result.stderrSummary ? { stderr: result.stderrSummary } : {}),
-                        },
+                        success: false,
+                        error: String(error),
+                        message: String(error),
                     };
-                },
+                }
             },
         },
-        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 {
-    name = "tts";
-    constructor() {
-        super();
-        Object.assign(this, createTtsPluginDefinition(this));
-    }
-}
 //# sourceMappingURL=Plugin.js.map