@xiongtao.xt/tau-plugins 0.11.0 → 0.12.0

package/UPLOAD.md

@@ -0,0 +1,33 @@
+# 资源上传插件
+
+需要 SDK 0.12.0 和包含资源上传插件能力的 Tau 0.59.0 客户端。上传返回正文可直接引用的 HTTP(S) 地址；数据库和资源目录同步使用 SYNC.md 的另一套接口。
+
+在 activate 中注册提供方：
+
+```tsx
+context.upload.register({
+  id: context.pluginId,
+  name: "我的资源存储",
+  async upload(file, config) {
+    // 用 context.fetch 请求服务商，认证与路径由本次 config 决定。
+    // file.name 已唯一命名，file.mimeType 是 MIME，file.content 为 Uint8Array。
+    return uploadToStorage(context.fetch, file, config);
+  },
+});
+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.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -8,6 +8,7 @@ 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 { PluginSidebar } from "./sidebar";
 import type { PluginExcerpts, PluginMaterials } from "./excerpts";
 import type { PluginMCP } from "./mcp";
@@ -39,6 +40,7 @@ export interface PluginContext {
     readonly editor: PluginEditor;
     readonly settings: PluginSettings;
     readonly sync: PluginSync;
+    readonly upload: PluginUpload;
     readonly sidebar: PluginSidebar;
     readonly excerpts: PluginExcerpts;
     readonly materials: PluginMaterials;

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

@@ -1,4 +1,5 @@
 import type { PluginDefinition } from "./contract";
+export type * from "./upload";
 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,10 @@ import type { Disposable, PluginContext } from "./index";
 import type { JsonValue } from "./json";
 export interface PluginSettingsProps {
     readonly context: PluginContext;
+    readonly uploadConfig?: {
+        readonly value: JsonValue;
+        save(value: JsonValue): Promise<void>;
+    };
     readonly syncConfig?: {
         readonly value: JsonValue;
         save(value: JsonValue): Promise<void>;
@@ -13,7 +17,7 @@ export interface PluginSettingsDefinition {
     title: string;
     description?: string;
     /** 同步提供方的配置表单挂载到宿主同步设置。 */
-    target?: "sync";
+    target?: "sync" | "upload";
     component: ComponentType<PluginSettingsProps>;
 }
 export interface PluginSettingsHandle extends Disposable {

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

@@ -0,0 +1,16 @@
+import type { Disposable, JsonValue } from "./contract";
+export interface UploadFile {
+    /** 宿主已完成压缩和唯一命名，插件只负责追加远端路径前缀。 */
+    name: string;
+    mimeType: string;
+    content: Uint8Array;
+}
+export interface UploadProviderDefinition {
+    id: string;
+    name: string;
+    /** 返回可供正文直接引用的HTTP(S)地址，不返回临时签名URL。 */
+    upload(file: UploadFile, config: JsonValue): Promise<string>;
+}
+export interface PluginUpload {
+    register(definition: UploadProviderDefinition): Disposable;
+}