@xiongtao.xt/tau-plugins 0.11.0 → 0.13.0

package/TTS.md

@@ -0,0 +1,20 @@
+# 语音提供方
+
+需要 SDK 0.13.0 和包含语音插件能力的 Tau 0.59.0 客户端。
+
+在activate中调用context.tts.register({id: context.pluginId, name, create})。create(config, modelId)同步创建任务实例，固定该账号配置和模型，不发送网络请求。每个插件可对应多个用户账号，不能用插件全局变量保存“当前API Key”。
+
+| 方法或字段                                         | 职责                                                                                |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| getVoices(signal)                                  | 返回id、name、type（system/cloned/custom）、可选description组成的音色数组           |
+| synthesize({text,voiceId,options},signal)          | 返回{audio:Uint8Array,mime:string}；options仅含speed、volume、pitch                 |
+| cloneVoice({file,requestedId?,name?},signal)，可选 | 每次一个{name,mimeType,content}参考文件，返回实际创建的音色；不返回上传文件ID或void |
+| textInstructions，可选                             | 当前模型的合成文本规则；供宿主播客脚本使用，缺省为纯文本                            |
+
+请求使用context.fetch并传入方法收到的signal。服务商超时用AbortSignal.any组合，不能覆盖取消信号；退避等待也须取消，不把AbortError当作可重试错误。
+
+配置通过settings.register的target:"tts"挂载。组件接收ttsConfig.instanceId、value、models和save(value,models)，只保存当前账号，不自动选为默认，不覆盖同插件其他账号。模型项为{id,label?}；用户可填写自定义模型。保存失败保留表单并显示错误，不另存一份凭据到context.storage。
+
+需要公开上传参考音频时调用context.upload.uploadRemote(file,{signal})，复用用户选定的远端上传配置。本地模式明确报错；MiniMax自有文件上传不需要图床。不要自行选择用户的上传插件、读取上传凭据或修改桶权限。
+
+主进程只转发数据和提供宿主能力。插件在主窗口渲染进程执行，不使用Node后台入口。宿主负责音频播放、合并和保存；插件不直接写笔记或文件。

package/UPLOAD.md

@@ -0,0 +1,35 @@
+# 资源上传插件
+
+需要 SDK 0.12.0 和包含资源上传插件能力的 Tau 0.59.0 客户端。上传返回正文可直接引用的 HTTP(S) 地址；数据库和资源目录同步使用 SYNC.md 的另一套接口。
+
+SDK 0.13.0 增加第三个signal参数与context.upload.uploadRemote(file,{signal})。提供方应将signal合并进context.fetch请求；调用方使用uploadRemote时，本地目标明确报错，不自动更换存储。signal取消会结束等待并通知提供方，不代表撤回已经上传的远端对象。
+
+在 activate 中注册提供方：
+
+```tsx
+context.upload.register({
+  id: context.pluginId,
+  name: "我的资源存储",
+  async upload(file, config, signal) {
+    // 用 context.fetch 请求服务商，认证与路径由本次 config 决定。
+    // file.name 已唯一命名，file.mimeType 是 MIME，file.content 为 Uint8Array。
+    return uploadToStorage(context.fetch, file, config, signal);
+  },
+});
+context.settings.register({
+  id: "upload",
+  title: "我的资源存储",
+  target: "upload",
+  component: UploadSettings,
+});
+```
+
+UploadSettings 接收 PluginSettingsProps。读取 uploadConfig.value，在用户保存时调用 await uploadConfig.save(config)，宿主保存并选中该提供方；不要将同一份上传配置再存到 context.storage。配置是 JsonValue，读取时自行校验字段并给出错误提示。组件在资源存储设置页显示；插件详情页提供跳转入口。
+
+每个插件只能注册一个上传提供方，id 必须等于 context.pluginId。宿主负责压缩、文件唯一命名、本地保存和跨窗口转发。插件只负责远端上传和返回资源地址，不读取用户文件路径，也不修改笔记内容。
+
+请求通过 context.fetch 发送，失败抛出错误，不返回空地址或吞掉失败。停用插件会取消上下文请求并拒绝迟到结果。插件在渲染进程执行，不使用 Node 模块或额外后台入口。
+
+返回地址必须长期可引用；不要返回短期签名 URL。桶或仓库的公开读取策略由用户配置，上传成功不等于匿名用户可以访问。不要自动修改用户桶权限。需要自定义公开域名时由插件设置提供，按对象路径返回完整 URL。
+
+完成后验证：本地模式不调用插件、远端上传成功及失败、保存配置、停用、独立窗口上传、重启恢复。README.md 应说明如何配置公开访问和常见服务商错误。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiongtao.xt/tau-plugins",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/types/packages/plugins/src/contract.d.ts

@@ -8,6 +8,8 @@ import type { PluginEditorExtension } from "./editor";
 import type { MarkdownCodec } from "../../markdown/src/index";
 import type { PluginSettings } from "./settings";
 import type { PluginSync } from "./sync";
+import type { PluginUpload } from "./upload";
+import type { PluginTTS } from "./tts";
 import type { PluginSidebar } from "./sidebar";
 import type { PluginExcerpts, PluginMaterials } from "./excerpts";
 import type { PluginMCP } from "./mcp";
@@ -39,6 +41,8 @@ export interface PluginContext {
     readonly editor: PluginEditor;
     readonly settings: PluginSettings;
     readonly sync: PluginSync;
+    readonly upload: PluginUpload;
+    readonly tts: PluginTTS;
     readonly sidebar: PluginSidebar;
     readonly excerpts: PluginExcerpts;
     readonly materials: PluginMaterials;

package/types/packages/plugins/src/index.d.ts

@@ -1,4 +1,6 @@
 import type { PluginDefinition } from "./contract";
+export type * from "./upload";
+export type * from "./tts";
 export type { JsonValue, Disposable, PluginStorage, PluginCommand, PluginContext, PluginInstance, PluginDefinition, } from "./contract";
 export type { PluginSettings, PluginSettingsDefinition, PluginSettingsProps, PluginSettingsHandle, } from "./settings";
 export * from "./editor";

package/types/packages/plugins/src/settings.d.ts

@@ -3,6 +3,22 @@ import type { Disposable, PluginContext } from "./index";
 import type { JsonValue } from "./json";
 export interface PluginSettingsProps {
     readonly context: PluginContext;
+    readonly ttsConfig?: {
+        readonly instanceId: string;
+        readonly value: JsonValue;
+        readonly models: readonly {
+            id: string;
+            label?: string;
+        }[];
+        save(value: JsonValue, models: readonly {
+            id: string;
+            label?: string;
+        }[]): Promise<void>;
+    };
+    readonly uploadConfig?: {
+        readonly value: JsonValue;
+        save(value: JsonValue): Promise<void>;
+    };
     readonly syncConfig?: {
         readonly value: JsonValue;
         save(value: JsonValue): Promise<void>;
@@ -12,8 +28,8 @@ export interface PluginSettingsDefinition {
     id: string;
     title: string;
     description?: string;
-    /** 同步提供方的配置表单挂载到宿主同步设置。 */
-    target?: "sync";
+    /** 提供方配置表单挂载到对应宿主设置；普通插件设置省略。 */
+    target?: "sync" | "upload" | "tts";
     component: ComponentType<PluginSettingsProps>;
 }
 export interface PluginSettingsHandle extends Disposable {
@@ -21,6 +37,6 @@ export interface PluginSettingsHandle extends Disposable {
     open(): Promise<void>;
 }
 export interface PluginSettings {
-    /** 分区随本次激活回收，保存使用 context.storage。 */
+    /** 分区随本次激活回收；提供方保存使用配置属性，普通设置使用 context.storage。 */
     register(definition: PluginSettingsDefinition): PluginSettingsHandle;
 }

package/types/packages/plugins/src/tts.d.ts

@@ -0,0 +1,42 @@
+import type { Disposable, JsonValue } from "./contract";
+import type { UploadFile } from "./upload";
+export interface TTSVoice {
+    id: string;
+    name: string;
+    type: "system" | "cloned" | "custom";
+    description?: string;
+}
+export interface TTSSynthesizeOptions {
+    speed?: number;
+    volume?: number;
+    pitch?: number;
+}
+export interface TTSSynthesizeRequest {
+    text: string;
+    voiceId: string;
+    options?: TTSSynthesizeOptions;
+}
+export interface TTSAudio {
+    audio: Uint8Array;
+    mime: string;
+}
+export interface TTSCloneRequest {
+    file: UploadFile;
+    requestedId?: string;
+    name?: string;
+}
+export interface TTSInstance {
+    readonly textInstructions?: string;
+    getVoices(signal: AbortSignal): Promise<TTSVoice[]>;
+    synthesize(request: TTSSynthesizeRequest, signal: AbortSignal): Promise<TTSAudio>;
+    cloneVoice?(request: TTSCloneRequest, signal: AbortSignal): Promise<TTSVoice>;
+}
+export interface TTSProviderDefinition {
+    id: string;
+    name: string;
+    /** 每次任务固定配置和模型，创建时不发网络请求。 */
+    create(config: JsonValue, modelId: string): TTSInstance;
+}
+export interface PluginTTS {
+    register(definition: TTSProviderDefinition): Disposable;
+}

package/types/packages/plugins/src/upload.d.ts

@@ -0,0 +1,20 @@
+import type { Disposable, JsonValue } from "./contract";
+export interface UploadFile {
+    /** 提供方收到宿主唯一命名后的文件；uploadRemote的调用者传原始文件名。 */
+    name: string;
+    mimeType: string;
+    content: Uint8Array;
+}
+export interface UploadProviderDefinition {
+    id: string;
+    name: string;
+    /** 返回可供正文直接引用的HTTP(S)地址，不返回临时签名URL。 */
+    upload(file: UploadFile, config: JsonValue, signal: AbortSignal): Promise<string>;
+}
+export interface PluginUpload {
+    register(definition: UploadProviderDefinition): Disposable;
+    /** 使用用户当前远端配置；本地模式明确失败，不自动选择其他存储。 */
+    uploadRemote(file: UploadFile, options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+}