@xiongtao.xt/tau-plugins 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 更新记录
 
+## 0.22.0
+
+- 新增 `context.video.register`，接入视频来源（视频网站、自建服务器等）：插件识别链接、解析标题与清晰度，返回播放源描述（单文件、音视频分离或交给宿主解析器），下载、缓存与播放由宿主完成。
+- 视频账号与代理配置通过 `settings.register({ target: "video" })` 注册，接收每个插件一份的 `videoConfig`。
+- 新增 `services.videoExtractor.probe`，查询视频页面的标题与可下载格式；新增插件分类 `video`（在线视频）。
+
+## 0.21.0
+
+- 新增 context.publish 发布提供方、publishConfig 配置表单和文件式／快照式提交协议，本地导出仍由宿主提供。
+- 新增受控 Git 快照发布与缓存目录选择服务，插件不获得任意命令或宿主文件访问。
+- 插件分类新增博客发布。
+
 ## 0.20.0
 
 - manifest 支持 `categories`（插件中心分类）与 `keywords`（目录搜索），门户上传严格校验，客户端忽略未知值。

package/PUBLISH.md

@@ -0,0 +1,17 @@
+# 博客发布提供方
+
+需要 SDK 0.21.0 及包含博客发布能力的客户端。提供方只在渲染进程注册和执行，网络使用 `context.fetch`。本地导出由宿主提供，不注册本地发布插件。
+
+在 activate 中调用 `context.publish.register({ id: context.pluginId, name, create(config) })`。create 返回文件式或快照式实例，配置是本轮固定的 JSON 副本。提供方 ID 必须等于所属插件 ID。
+
+两种实例都实现 `describe(signal)` 与 `checkConnection(signal)`；describe 返回 `identity`、`basePath`、可选 `publicUrl`。identity 是不含密钥的物理目标稳定身份，不随插件版本、模板、Token 或提交方式变化。basePath 以斜杠开头和结尾，根路径为 `/`。
+
+文件式实例声明 `mode: "files"`，实现 `uploadFile(path, Uint8Array, signal)` 与 `deleteFile(path, signal)`，可用 `concurrency` 声明 1–32 的上限。方法成功返回 void，失败抛出异常。宿主负责增量、重试、依赖先行和入口后置、旧资源清理，不把远端目录当成可任意删除的文件清单。
+
+快照式实例声明 `mode: "snapshot"`，实现 `publish(snapshot, signal)`。snapshot 包含本轮临时 id、待上传文件的路径和摘要及删除路径。只有远端确认整轮提交后才返回；失败抛异常，不返回部分成功。可选 dispose 在会话关闭时回收连接。
+
+Git 快照使用 `context.services.git.publishSnapshot({ publicationId: snapshot.id, remote, branch, author: { name, email }, authentication: { username, password }, cacheId? }, { signal })`。remote 只接受不含凭据的 HTTPS 地址；认证通过任务通道使用，不写入 remote URL。publicationId 仅在所属窗口本轮发布中有效，不能用于读取任意本地文件。需要缓存目录时调用 `context.services.git.selectCacheDirectory({})`，由宿主选择并返回 `{ id, label }`；只保存 id 和展示用 label，不传入任意 cwd 或 shell 命令。
+
+配置视图使用 `context.settings.register({ id, title, target: "publish", component })`。组件接收 `PluginSettingsProps.publishConfig` 的 value 与 save，保存成功后再提交表单值，不用按工作区隔离的 context.storage 保存账号。普通插件详情页提供前往博客发布页的入口。
+
+离开发布页继续运行；停用、切库和发起窗口关闭使旧会话失效。每次请求都传递 signal，错误信息不得包含凭据。新安装默认停用，插件缺失或未启用时宿主保留用户配置及选择，不自动切换其他目标。

package/SERVICES.md

@@ -15,6 +15,7 @@
 | `markdown.render(source, options?)`      | Markdown 字符串                                   | `{ html, css, warnings }`           |
 | `ffmpeg.probe(file, options?)`           | `{ name, data: Blob }`                            | `{ format, streams }`               |
 | `ffmpeg.run(input, options?)`            | `{ files, args, outputs }`                        | `{ files, log }`                    |
+| `videoExtractor.probe(url, options?)`    | 视频页面地址，可选 `proxy`（SDK 0.22.0）          | `{ title, cover?, formats }`        |
 
 ## 在静态组件中获取服务
 

package/VIDEO.md

@@ -0,0 +1,40 @@
+# 视频提供方
+
+需要 SDK 0.22.0 和支持该能力的客户端。通过 `context.video.register({ id: context.pluginId, name, create })` 注册，每个插件一个提供方。视频来源可以是视频网站，也可以是自建的视频服务（如 NAS）。
+
+启用后，编辑器、白板、项目视频笔记和学习资料的「添加视频」中会出现以 `name` 命名的入口。用户从该入口粘贴视频链接，客户端先用 `matches` 确认链接属于本插件，再调用 `resolve`。
+
+插件只负责视频来源本身的知识：识别链接、查询标题与可选清晰度、给出真实的流地址和所需请求头。选择弹窗、下载进度、合并音视频、缓存和播放都由客户端完成，插件不提供这些界面，也不传输视频字节。
+
+## 实例
+
+`create(config)` 按当前插件配置同步创建实例，不发网络请求。实例需要实现四个方法：
+
+- `matches(url)`：同步判断链接是否属于本来源，不访问网络。链接属于其他已启用插件时，客户端会提示用户改用对应入口。
+- `resolve(url, signal)`：返回 `{ title, cover?, variants, defaultVariant? }`。`variants` 是可选清晰度（至少一项），每项为 `{ label, hint?, ref }`。
+- `cacheKey(ref)`：返回稳定的缓存身份，应包含清晰度。视频已缓存时客户端不再调用 `getPlayback`，可以离线播放。
+- `getPlayback(ref, signal)`：每次缓存前现取播放源，可以返回会过期的直链。
+
+## 视频引用
+
+用户选中的 `ref` 原样写入文档和数据库，以后只能通过它找回视频。它必须是可长期保存的 JSON，例如视频 ID 加清晰度，不要放会过期的直链、Cookie 或令牌。`type`、`title`、`thumbnail` 三个键由客户端占用，引用中不要使用。
+
+## 播放源
+
+`getPlayback` 返回以下三种之一：
+
+- `{ kind: "file", stream }`：单个音视频合一的文件。
+- `{ kind: "split", video, audio }`：音视频分离的流，客户端分别下载后无损合并。
+- `{ kind: "extract", url, videoFormat?, audioFormat?, proxy? }`：交给客户端内置的视频解析器下载，格式 ID 来自 `context.services.videoExtractor.probe`。
+
+`stream` 为 `{ url, headers? }`。需要 Referer、Cookie 等请求头时放在 `headers` 中，客户端只在下载时使用，不写入文档或缓存索引。网络请求使用 `context.fetch` 并传入方法的 signal，它可以设置这些请求头。
+
+## 视频解析服务
+
+`context.services.videoExtractor.probe(url, { proxy?, signal? })` 返回 `{ title, cover?, duration?, formats }`，`formats` 每项包含 `id`、`videoOnly`、`audioOnly`、`ext`、`width`、`height`、`fps`、`bitrate`、`size`、`note`。插件根据格式列表组织清晰度，再返回 `kind: "extract"` 的播放源；插件不能自行启动外部程序。
+
+## 配置
+
+账号、Cookie 或代理通过 `context.settings.register({ id, title, target: "video", component })` 注册配置视图，挂载在「设置 · 账号与连接 · 在线视频」。组件接收 `PluginSettingsProps.videoConfig`：`value` 和 `save(value)`，每个插件一份配置，保存后下一次调用 `create` 即读到新值。保存失败时保留草稿，成功后才提示已保存。
+
+插件停用或调用方取消时，进行中的请求会收到取消信号，迟到的结果被丢弃。插件未启用时，已保存的视频显示需要启用插件的提示，原数据保留。移动端和发布站点不运行插件，插件提供的视频在那里只显示说明。

package/package.json

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

package/publish-artifacts.js

@@ -43,8 +43,10 @@ var PLUGIN_CATEGORIES = [
   { id: "editor", label: "\u7F16\u8F91\u5668" },
   { id: "whiteboard", label: "\u767D\u677F" },
   { id: "blog-template", label: "\u535A\u5BA2\u6A21\u677F" },
+  { id: "blog-publish", label: "\u535A\u5BA2\u53D1\u5E03" },
   { id: "ai", label: "AI" },
   { id: "voice", label: "\u8BED\u97F3" },
+  { id: "video", label: "\u5728\u7EBF\u89C6\u9891" },
   { id: "page", label: "\u9875\u9762" }
 ];
 var PLUGIN_KEYWORD_LIMIT = 5;

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

@@ -14,12 +14,18 @@ export declare const PLUGIN_CATEGORIES: readonly [{
 }, {
     readonly id: "blog-template";
     readonly label: "博客模板";
+}, {
+    readonly id: "blog-publish";
+    readonly label: "博客发布";
 }, {
     readonly id: "ai";
     readonly label: "AI";
 }, {
     readonly id: "voice";
     readonly label: "语音";
+}, {
+    readonly id: "video";
+    readonly label: "在线视频";
 }, {
     readonly id: "page";
     readonly label: "页面";

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

@@ -11,6 +11,8 @@ import type { PluginSync } from "./sync";
 import type { PluginUpload } from "./upload";
 import type { PluginTTS } from "./tts";
 import type { PluginImages } from "./images";
+import type { PluginVideo } from "./video";
+import type { PluginPublish } from "./publish";
 import type { PluginSidebar } from "./sidebar";
 import type { PluginExcerpts, PluginMaterials } from "./excerpts";
 import type { PluginMCP } from "./mcp";
@@ -46,6 +48,8 @@ export interface PluginContext {
     readonly upload: PluginUpload;
     readonly tts: PluginTTS;
     readonly images: PluginImages;
+    readonly video: PluginVideo;
+    readonly publish: PluginPublish;
     readonly sidebar: PluginSidebar;
     readonly excerpts: PluginExcerpts;
     readonly materials: PluginMaterials;

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

@@ -2,6 +2,8 @@ import type { PluginDefinition } from "./contract";
 export type * from "./upload";
 export type * from "./tts";
 export type * from "./images";
+export type * from "./video";
+export type * from "./publish";
 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/publish.d.ts

@@ -0,0 +1,59 @@
+import type { Disposable, JsonValue } from "./contract";
+export interface PublishTarget {
+    /** 物理目标的稳定身份，不包含凭据、插件或模板版本。 */
+    identity: string;
+    basePath: string;
+    publicUrl?: string;
+}
+export interface PublicationSnapshot {
+    /** 宿主为本轮文件计划颁发的临时句柄，不能读取任意本地文件。 */
+    id: string;
+    files: readonly {
+        path: string;
+        hash: string;
+    }[];
+    deletions: readonly string[];
+}
+interface PublishInstanceBase {
+    describe(signal: AbortSignal): Promise<PublishTarget>;
+    checkConnection(signal: AbortSignal): Promise<boolean>;
+    dispose?(): void | Promise<void>;
+}
+export interface FilePublishInstance extends PublishInstanceBase {
+    mode: "files";
+    concurrency?: number;
+    uploadFile(path: string, content: Uint8Array, signal: AbortSignal): Promise<void>;
+    deleteFile(path: string, signal: AbortSignal): Promise<void>;
+}
+export interface SnapshotPublishInstance extends PublishInstanceBase {
+    mode: "snapshot";
+    publish(snapshot: PublicationSnapshot, signal: AbortSignal): Promise<void>;
+}
+export type PublishInstance = FilePublishInstance | SnapshotPublishInstance;
+export interface PublishProviderDefinition {
+    id: string;
+    name: string;
+    create(config: JsonValue): PublishInstance;
+}
+export interface PluginPublish {
+    register(definition: PublishProviderDefinition): Disposable;
+}
+export interface GitSnapshotRequest {
+    publicationId: string;
+    remote: string;
+    branch: string;
+    author: {
+        name: string;
+        email: string;
+    };
+    authentication: {
+        username: string;
+        password: string;
+    };
+    cacheId?: string;
+}
+export interface GitCacheDirectory {
+    id: string;
+    label: string;
+}
+export {};

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

@@ -1,5 +1,6 @@
 import type { Descendant } from "slate";
 import type { MarkdownCodec } from "../../markdown/src/index";
+import type { GitSnapshotRequest, GitCacheDirectory } from "./publish";
 export type { Descendant } from "slate";
 export interface ServiceOptions {
     signal?: AbortSignal;
@@ -38,7 +39,31 @@ export interface MediaInfo {
         channels?: number;
     }[];
 }
+export interface VideoFormat {
+    id: string;
+    /** 只含视频或只含音频的流；两者都为 false 时是音视频合一的流。 */
+    videoOnly: boolean;
+    audioOnly: boolean;
+    ext?: string;
+    width?: number;
+    height?: number;
+    fps?: number;
+    /** 码率，单位 kbps。 */
+    bitrate?: number;
+    size?: number;
+    note?: string;
+}
+export interface VideoProbeResult {
+    title: string;
+    cover?: string;
+    duration?: number;
+    formats: VideoFormat[];
+}
 export interface PluginServices {
+    git: {
+        publishSnapshot(input: GitSnapshotRequest, options?: ServiceOptions): Promise<void>;
+        selectCacheDirectory(input: Record<string, never>, options?: ServiceOptions): Promise<GitCacheDirectory | null>;
+    };
     tailwind: {
         compile(input: {
             source: string;
@@ -91,6 +116,12 @@ export interface PluginServices {
             log: string;
         }>;
     };
+    /** 宿主视频解析器（yt-dlp），只查询页面的标题与可下载格式，下载经视频播放源交给宿主。 */
+    videoExtractor: {
+        probe(url: string, options?: ServiceOptions & {
+            proxy?: string;
+        }): Promise<VideoProbeResult>;
+    };
 }
 /** 每个调用同时受调用方与插件实例生命周期约束。 */
 export declare function bindPluginServices(adapter: PluginServices | undefined, lifetime: AbortSignal, assertActive: () => void): PluginServices;

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 publishConfig?: {
+        readonly value: JsonValue;
+        save(value: JsonValue): Promise<void>;
+    };
     readonly imageConfig?: {
         readonly instanceId: string;
         readonly value: JsonValue;
@@ -25,6 +29,10 @@ export interface PluginSettingsProps {
         readonly value: JsonValue;
         save(value: JsonValue): Promise<void>;
     };
+    readonly videoConfig?: {
+        readonly value: JsonValue;
+        save(value: JsonValue): Promise<void>;
+    };
     readonly syncConfig?: {
         readonly value: JsonValue;
         save(value: JsonValue): Promise<void>;
@@ -35,7 +43,7 @@ export interface PluginSettingsDefinition {
     title: string;
     description?: string;
     /** 提供方配置表单挂载到对应宿主设置；普通插件设置省略。 */
-    target?: "sync" | "upload" | "tts" | "images";
+    target?: "sync" | "upload" | "tts" | "images" | "video" | "publish";
     component: ComponentType<PluginSettingsProps>;
 }
 export interface PluginSettingsHandle extends Disposable {

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

@@ -0,0 +1,58 @@
+import type { Disposable, JsonValue } from "./contract";
+/**
+ * 插件私有的视频引用，宿主原样写入文档与数据库；必须可长期保存，不放会过期的直链。
+ * 宿主在元数据中占用 type / title / thumbnail 三个键，引用不得使用。
+ */
+export type VideoRef = {
+    readonly [key: string]: JsonValue;
+};
+export interface VideoStream {
+    url: string;
+    /** 宿主下载时附带的请求头（如 Referer、Cookie），不写入文档或缓存索引。 */
+    headers?: Record<string, string>;
+}
+/** 播放源描述：插件只说明流在哪里，下载、合并、缓存与播放由宿主完成。 */
+export type VideoPlaybackSource = {
+    kind: "file";
+    stream: VideoStream;
+} | {
+    kind: "split";
+    video: VideoStream;
+    audio: VideoStream;
+} | {
+    kind: "extract";
+    /** 交给宿主视频解析服务的页面地址。 */
+    url: string;
+    videoFormat?: string;
+    audioFormat?: string;
+    proxy?: string;
+};
+export interface VideoVariant {
+    label: string;
+    hint?: string;
+    ref: VideoRef;
+}
+export interface ResolvedVideo {
+    title: string;
+    cover?: string;
+    /** 可选清晰度等变体，至少一项；用户选中项的 ref 被保存。 */
+    variants: readonly VideoVariant[];
+    defaultVariant?: number;
+}
+export interface VideoInstance {
+    /** 同步识别链接是否属于本提供方，不发网络请求。 */
+    matches(url: string): boolean;
+    resolve(url: string, signal: AbortSignal): Promise<ResolvedVideo>;
+    /** 稳定的缓存身份（应包含清晰度）；已缓存时宿主不再调用 getPlayback。 */
+    cacheKey(ref: VideoRef): string;
+    getPlayback(ref: VideoRef, signal: AbortSignal): Promise<VideoPlaybackSource>;
+}
+export interface VideoProviderDefinition {
+    id: string;
+    name: string;
+    /** 按当前插件配置同步创建实例，不发网络请求。 */
+    create(config: JsonValue): VideoInstance;
+}
+export interface PluginVideo {
+    register(definition: VideoProviderDefinition): Disposable;
+}