@xiongtao.xt/tau-plugins 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 更新记录
 
+## 0.22.0
+
+- 新增 `context.video.register`，接入视频来源（视频网站、自建服务器等）：插件识别链接、解析标题与清晰度，返回播放源描述（单文件、音视频分离或交给宿主解析器），下载、缓存与播放由宿主完成。
+- 视频账号与代理配置通过 `settings.register({ target: "video" })` 注册，接收每个插件一份的 `videoConfig`。
+- 新增 `services.videoExtractor.probe`，查询视频页面的标题与可下载格式；新增插件分类 `video`（在线视频）。
+
 ## 0.21.0
 
 - 新增 context.publish 发布提供方、publishConfig 配置表单和文件式／快照式提交协议，本地导出仍由宿主提供。

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.21.0",
+  "version": "0.22.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/publish-artifacts.js

@@ -46,6 +46,7 @@ var PLUGIN_CATEGORIES = [
   { 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

@@ -23,6 +23,9 @@ export declare const PLUGIN_CATEGORIES: readonly [{
 }, {
     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,7 @@ 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";
@@ -47,6 +48,7 @@ export interface PluginContext {
     readonly upload: PluginUpload;
     readonly tts: PluginTTS;
     readonly images: PluginImages;
+    readonly video: PluginVideo;
     readonly publish: PluginPublish;
     readonly sidebar: PluginSidebar;
     readonly excerpts: PluginExcerpts;

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

@@ -2,6 +2,7 @@ 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";

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

@@ -39,6 +39,26 @@ 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>;
@@ -96,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

@@ -29,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>;
@@ -39,7 +43,7 @@ export interface PluginSettingsDefinition {
     title: string;
     description?: string;
     /** 提供方配置表单挂载到对应宿主设置；普通插件设置省略。 */
-    target?: "sync" | "upload" | "tts" | "images" | "publish";
+    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;
+}