@xiongtao.xt/tau-plugins 0.9.0 → 0.10.0

package/SYNC.md

@@ -1,21 +1,37 @@
 # 同步存储插件
 
-需要 SDK 0.9.0 及以上和包含同步插件支持的 Tau 0.59.0 客户端。插件提供存储操作与配置表单，客户端负责数据库、资源、用量同步和冲突处理；CLI也可调用同一后台入口。
+需要 SDK 0.10.0 及以上，以及包含渲染端同步注册支持的 Tau 0.59.0 客户端构建。插件只在渲染进程执行，沿用main.js入口，不声明manifest.sync，也不提供Node后台产物。
 
-后台从@tau/plugins/sync导入defineSyncProvider、SyncProvider与RemoteFileInfo。defineSyncProvider接收id、name、create(config)；id与manifest.id一致，create根据本次任务配置返回提供方。用户只填写服务地址、桶、路径与凭据，没有能力声明或服务商认证流程。
+## 注册与职责
 
-同步存储插件的manifest可声明sync为sync.js，模板从src/sync.ts构建Node后台入口；main.js继续承载UI。@tau/plugins/sync由客户端后台提供，保留模板external配置。普通npm依赖打包进sync.js，Node内置模块保留运行时引用。
+在activate(context)中调用context.sync.register({ id: context.pluginId, name, create })。一个插件注册一个提供方，create(config)根据本次任务的JSON配置返回下列五个方法；停用或激活失败时注册自动回收。create在真正发起任务时调用，打开配置页不会连接存储服务。
 
-提供方只有uploadFile、downloadFile、fileExists、listFiles、createFileIfAbsent五个操作，使用Uint8Array、boolean和RemoteFileInfo[]等现有返回形状。分页在listFiles内部聚合；不新增stat/remove、流式参数、公开游标、目标身份字段或统一错误码。
+| 方法                            | 返回值                    | 用途                                                 |
+| ------------------------------- | ------------------------- | ---------------------------------------------------- |
+| uploadFile(name, bytes)         | Promise<boolean>          | 普通上传                                             |
+| downloadFile(name)              | Promise<Uint8Array>       | 读取对象                                             |
+| fileExists(name)                | Promise<boolean>          | 检查对象是否存在                                     |
+| listFiles(prefix?)              | Promise<RemoteFileInfo[]> | 内部完成分页，返回相对路径、名称、大小及可选修改时间 |
+| createFileIfAbsent(name, bytes) | Promise<boolean>          | 按远端原子条件创建对象                               |
 
-上传返回false或抛异常的处理由现有客户端控制流承担。createFileIfAbsent保留现有版本提交调用，不要求所有服务使用同一个HTTP头；响应异常后仍由客户端核验提交记录。不能用检查后覆盖偷换其含义，也不要求安装前进行额外探测。同步内容、冲突判断与恢复归客户端。
+SyncProvider、SyncProviderDefinition和RemoteFileInfo类型从@tau/plugins/sync导入。该模块仅提供纯契约与声明辅助函数，不是Node执行入口。
 
-后台入口同样参与manifest摘要、ZIP检查和安装事务。不要手动删掉完整性字段或把源码路径直接交给宿主执行。构建后通过客户端插件页安装ZIP，启用后在“设置→同步”选择插件并保存配置。
+客户端负责同步内容、对象命名、版本提交、冲突、资源计划和恢复。插件负责存储服务请求，不增加能力声明、服务商探测或独立同步引擎。条件创建不能用先查询再覆盖替代；请求失败后由客户端按原提交规则核验结果。
+
+## 网络与依赖
+
+通过context.fetch发送请求。它由宿主提供网络传输，并与插件生命周期关联。签名、URL与协议逻辑在插件内执行；浏览器可用的SDK可以把自己的HTTP传输接到context.fetch。
+
+普通npm依赖随main.js按浏览器目标打包；不导入fs、http、Node Buffer或其他Node内置模块，不借用宿主node_modules，不另打包Node依赖目录。保留模板external配置。
 
 ## 配置界面
 
-在前端activate中调用context.settings.register({ id: "sync", title: "同步存储", target: "sync", component: SyncSettings })，每个插件注册一个同步配置分区。客户端将它放在“设置→同步”，插件详情页的设置入口也跳转到这里。
+通过context.settings.register({ id: "sync", title, target: "sync", component })将配置表单挂在“设置→同步”。每个插件注册一个同步配置分区。
+
+组件从PluginSettingsProps.syncConfig.value读取配置，通过await syncConfig.save(config)保存。字段和校验由插件定义；失败时保留输入并展示错误。凭据不要写入日志或工作区context.storage；宿主按插件ID在本机应用级保存配置。
+
+客户端每次任务固定配置。关闭设置页不影响任务，停用插件保留配置；运行中的任务阻止停用和卸载。窗口关闭或崩溃时任务不会转移到Node进程继续执行。CLI不再提供同步功能。
 
-组件接收PluginSettingsProps，使用syncConfig.value初始化表单，提交时await syncConfig.save(config)。配置必须为JSON值；字段与校验由插件定义。保存失败保留输入并展示错误，保存成功后用户使用客户端已有的检查、上传和下载按钮。凭据不要写入日志或context.storage，后者按工作区隔离，不是同步配置的存储位置。
+## 从旧同步示例升级
 
-客户端在应用级按插件ID保存配置，并为每次任务提供固定快照。停用插件保留配置；后台任务运行时不能停用或卸载。作者不需要实现会话、dispose、能力探测或同步冲突引擎。CLI也从同一约定目录加载该后台入口，尊重启用意图；任务回收和进程间占用由客户端管理。
+SDK0.9.0的manifest.sync/sync.js示例已撤回。将存储实现作为普通模块由main.js导入，在activate内注册，并改用浏览器兼容依赖及context.fetch；删除manifest.sync，重新打包。不要通过其他字段恢复Node入口。

package/package.json

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

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

@@ -7,6 +7,7 @@ import type { PluginEditor } from "./editor";
 import type { PluginEditorExtension } from "./editor";
 import type { MarkdownCodec } from "../../markdown/src/index";
 import type { PluginSettings } from "./settings";
+import type { PluginSync } from "./sync";
 import type { PluginSidebar } from "./sidebar";
 import type { PluginExcerpts, PluginMaterials } from "./excerpts";
 import type { JsonValue } from "./json";
@@ -36,6 +37,7 @@ export interface PluginContext {
     readonly pages: PluginPages;
     readonly editor: PluginEditor;
     readonly settings: PluginSettings;
+    readonly sync: PluginSync;
     readonly sidebar: PluginSidebar;
     readonly excerpts: PluginExcerpts;
     readonly materials: PluginMaterials;

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

@@ -1,5 +1,9 @@
 import type { JsonValue } from "./json";
 export type { JsonValue } from "./json";
+import type { Disposable } from "./contract";
+export interface PluginSync {
+    register(definition: SyncProviderDefinition): Disposable;
+}
 export interface RemoteFileInfo {
     name: string;
     path: string;