@xiongtao.xt/tau-plugins 0.27.0 → 0.28.0

package/API.md

@@ -2,7 +2,9 @@
 
 本文介绍编写命令、页面、侧边栏、设置、数据存储、网络请求和摘录所需的接口。插件接口从 `@tau/plugins` 导入，界面组件从 `@tau/ui` 导入。所述能力需要 Tau 0.59.0 或更高版本。
 
-本文对应 SDK 0.27.0；最低客户端版本只负责版本门槛，使用新领域接口时仍需包含对应实现的客户端构建。SDK 升级步骤见 [DEVELOPMENT.md](DEVELOPMENT.md#升级-sdk-与同步旧模板)。独立后台与双入口构建见 [BACKEND.md](BACKEND.md)。
+本文对应 SDK 0.28.0；最低客户端版本只负责版本门槛，使用新领域接口时仍需包含对应实现的客户端构建。SDK 升级步骤见 [DEVELOPMENT.md](DEVELOPMENT.md#升级-sdk-与同步旧模板)。独立后台与双入口构建见 [BACKEND.md](BACKEND.md)。
+
+发送应用内或独立窗口通知见[通知](#通知)与 [NOTIFICATIONS.md](NOTIFICATIONS.md)，需要 SDK 0.28.0 和包含通知接口的客户端构建。
 
 博客发布提供方见 [PUBLISH.md](PUBLISH.md)，需要 SDK 0.21.0 和包含该能力的客户端；独立博客站点读取数据见 [PUBLISH-DATA.md](PUBLISH-DATA.md)。
 
@@ -111,6 +113,7 @@ export default definePlugin({
 | `data`        | `PluginData`                           | 读取与修改卡片、文章、项目文档、待办和日程       |
 | `content`     | `PluginContent`                        | 读取与修改正文                                   |
 | `events`      | `PluginEvents`                         | 订阅业务数据变化                                 |
+| `notifications` | `PluginNotifications`                | 发送应用内或独立窗口通知，默认按来源窗口焦点分流 |
 | `app`         | `PluginApp`                            | 选择、打开已有内容，执行导出、演示和共享         |
 | `entities`    | `PluginOwnEntities`                    | 管理插件自有内容、类型和反链                     |
 | `backend`     | `PluginBackendClient`                  | 调用与订阅本机后台，见 BACKEND.md                |
@@ -162,6 +165,35 @@ context.commands.register({
 
 命令、页面、设置的局部 ID 和 storage key 均为 1–128 个字符，以字母或数字开头，后续允许字母、数字、点、横线和下划线。
 
+## 通知
+
+`context.notifications.send(options): Disposable` 发送通知，返回句柄的 `dispose()` 只撤销本条。停用、激活失败或切库时宿主自动清理，无需再次 `context.register`。
+
+```ts
+const notification = context.notifications.send({
+  title: "处理完成",
+  body: "本次更新了 12 条内容。",
+  mode: "auto",
+  tone: "ok",
+});
+// 需要提前撤销时：await notification.dispose();
+```
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `title` | `string` | 必填，非空，最多 200 字符 |
+| `body` | `string`，可选 | 非空，最多 5000 字符 |
+| `mode` | `"auto" \| "in-app" \| "system"` | 默认 auto：来源窗口聚焦时应用内展示，否则进入独立通知窗口 |
+| `tone` | `"neutral" \| "ok" \| "danger"` | 默认 neutral |
+| `sticky` | `boolean`，可选 | 为 true 时保持显示直到用户处理、关闭或插件撤销 |
+| `actions` | `readonly PluginNotificationAction[]`，可选 | 最多两个按钮，最多一个主按钮 |
+
+`in-app` 固定进入插件所在窗口，不主动聚焦；`system` 固定使用 Tau 的独立通知窗口。通知发送后不会随焦点变化搬移。来源标签固定为插件名称，ID 由宿主生成；不接受自定义全局 ID、HTML 或 React 内容。
+
+按钮字段为 `label`（非空，最多 100 字符）、`primary?`、`resolvedText?`（非空，最多 500 字符）与必填 `onClick(): void | Promise<void>`。回调在来源窗口执行；Promise 未完成时显示忙态，失败在卡片内显示，成功后退场或展示结果文案。旧激活或已撤销通知的按钮不能再执行；已启动的异步业务应响应 `context.signal`。
+
+该接口不要求业务数据权限或即时用户手势，但只属于渲染端 `PluginContext`。旧客户端先检查 `context.notifications`；独立后台通过事件通知渲染插件后再发送。句柄不代表用户已经看到通知，路由不可用时按宿主策略放弃推送；Web 预览退化为应用内展示。完整示例见 [NOTIFICATIONS.md](NOTIFICATIONS.md)。
+
 ## 私有存储
 
 | 方法                      | 返回值                            | 说明                     |

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 更新记录
 
+## 0.28.0
+
+- 新增 `context.notifications.send`：发送应用内通知、独立窗口通知，或默认按来源窗口焦点自动分流。
+- 支持标题、正文、语义、常驻与最多两个操作按钮；来源显示插件名称。
+- 返回 `Disposable` 撤销单条通知，停用、激活失败及切库时自动回收，旧按钮回调失效。
+
 ## 0.27.0
 
 - 新增通用 `context.ai.requestCapability(name)`，开放应用全部 12 项大模型功能分配。每项声明 `ai:<能力名>` 并由用户独立授权，返回 `chat/stream` 客户端，不需要另配模型或声明自定义 AI 功能。

package/DEVELOPMENT.md

@@ -8,7 +8,7 @@
 - pnpm 11.9.0
 - Tau 桌面客户端 0.59.0 或更高版本
 
-模板锁定公开 SDK `@xiongtao.xt/tau-plugins@0.27.0` 和 UI `@xiongtao.xt/tau-ui@0.1.1`，通过 npm 别名安装为 `@tau/plugins`、`@tau/ui`。SDK 提供类型契约，运行实现由 Tau 注入；新领域能力还需包含相应实现的客户端构建，不能只依据客户端版本号判断。
+模板锁定公开 SDK `@xiongtao.xt/tau-plugins@0.28.0` 和 UI `@xiongtao.xt/tau-ui@0.1.1`，通过 npm 别名安装为 `@tau/plugins`、`@tau/ui`。SDK 提供类型契约，运行实现由 Tau 注入；新领域能力还需包含相应实现的客户端构建，不能只依据客户端版本号判断。
 
 ## 跑通示例
 
@@ -45,6 +45,7 @@ pnpm install:local
 | `MCP.md`                          | 注册 MCP、聊天工具渲染，复用工具开关与服务器管理     |
 | `BACKEND.md`                      | 显式声明本机后台、启动策略与独立产物构建             |
 | `FLASHCARDS.md`                   | 闪卡读写权限、宿主制卡窗口、插件 AI 与正文来源引用   |
+| `NOTIFICATIONS.md`                | 应用内、独立窗口通知、自动分流与生命周期清理       |
 | `WHITEBOARD.md`                   | 静态白板扩展、工具与发布边界                         |
 | `SYNC.md`                         | 同步存储提供方、配置视图与取消                       |
 | `UPLOAD.md`                       | 图片与附件上传、上传提供方与配置                     |
@@ -63,10 +64,10 @@ pnpm install:local
 
 GitHub 模板创建的仓库不会自动跟随模板更新。已有项目先提交或备份自己的改动，再按需同步 [上游模板](https://github.com/LastKnightCoder/tau-plugin-template) 的构建脚本、开发文档和 `.github/workflows/release.yml`，保留自己的插件 ID、入口、用户说明与版本记录。
 
-先在 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` 中增加新 SDK 的精确例外 `@xiongtao.xt/tau-plugins@0.27.0`，暂时保留旧锁文件所需的已核实例外，再更新依赖及锁文件：
+先在 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` 中增加新 SDK 的精确例外 `@xiongtao.xt/tau-plugins@0.28.0`，暂时保留旧锁文件所需的已核实例外，再更新依赖及锁文件：
 
 ```sh
-pnpm add @tau/plugins@npm:@xiongtao.xt/tau-plugins@0.27.0 --save-exact
+pnpm add @tau/plugins@npm:@xiongtao.xt/tau-plugins@0.28.0 --save-exact
 pnpm install --frozen-lockfile
 pnpm build
 ```
@@ -87,6 +88,7 @@ pnpm build
 | 0.25.0        | 数据读写与权限、正文组件、插件实体、宿主动作、存储随库同步，见 API.md；本机后台双入口见 BACKEND.md     |
 | 0.26.0        | 闪卡创建、读写授权、插件 AI 制卡与 contentRef 来源引用，见 FLASHCARDS.md                               |
 | 0.27.0        | 通用 requestCapability 开放全部内置大模型功能分配，分别以 ai:<能力名> 授权；闪卡复用同一机制，见 AI.md |
+| 0.28.0        | 通知发送、应用内或独立窗口展示、焦点自动分流与生命周期清理，见 NOTIFICATIONS.md |
 
 更早版本的完整变更见已安装包的 `node_modules/@tau/plugins/CHANGELOG.md`。需要本地媒体元数据时自行实现，不能把视频页面解析当作本地文件探测。SDK 根入口、白板/同步契约、UI 和 React 由 Tau 提供，保持模板的 external 配置；普通第三方库由构建打入 ZIP。独立站点数据子入口的用途另见 PUBLISH-DATA.md。
 

package/NOTIFICATIONS.md

@@ -0,0 +1,46 @@
+# 插件通知能力
+
+SDK 0.28.0 与包含此接口的客户端通过激活上下文提供 `context.notifications`，旧客户端可先检查该属性是否存在。本接口属于渲染端 `PluginContext`，独立后台可经既有后台事件通知渲染插件，再由渲染插件调用；应用退出后不会继续发送。
+
+```ts
+const notification = context.notifications.send({
+  title: "同步完成",
+  body: "本次更新了 12 条内容。",
+  mode: "auto",
+  tone: "ok",
+});
+
+// 需要提前撤销时调用；停用或切库时宿主也会自动回收。
+await notification.dispose();
+```
+
+| mode | 行为 |
+| --- | --- |
+| `auto`（默认） | 插件所在窗口聚焦时进入应用内通知栈，失焦时进入独立通知窗口 |
+| `in-app` | 固定进入插件所在窗口的通知栈，不主动聚焦窗口 |
+| `system` | 固定进入 Tau 独立通知窗口，不使用操作系统原生通知 |
+
+分流发生在发送时；发送后切换窗口焦点不会搬移通知。Web 预览没有独立窗口，沿平台既有规则退化为应用内展示。
+
+标题必填，最多 200 字符；正文可选，最多 5000 字符。`tone` 支持 `neutral`、`ok`、`danger`，默认 `neutral`。`sticky: true` 保持显示直到用户处理、关闭或插件撤销。来源标签固定为插件名称，不接受插件伪造来源或指定全局通知 ID。
+
+可传 `actions`（最多两个按钮，最多一个 `primary: true`）：
+
+```ts
+context.notifications.send({
+  title: "扫描完成",
+  body: "点击查看结果。",
+  sticky: true,
+  actions: [{
+    label: "查看结果",
+    primary: true,
+    onClick: async () => {
+      await resultsPage.open();
+    },
+  }],
+});
+```
+
+按钮回调返回 Promise 时显示执行中状态，失败在通知内展示；可用 `resolvedText` 指定成功后的结果文案。独立通知窗口通过现有桥接在来源窗口执行回调。通知撤销或插件失活后，旧回调拒绝执行；已经开始的异步业务仍应遵循 `context.signal`。
+
+发送不需要业务数据权限或即时用户手势，适用于异步任务完成提示。`send` 返回的是已提交给通知路由的句柄，不是用户已看到通知的回执；主进程不可用时沿 `appNotify` 的既有策略放弃推送。

package/package.json

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

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

@@ -24,6 +24,7 @@ import type { PluginEvents } from "./events";
 import type { PluginApp } from "./app";
 import type { PluginOwnEntities } from "./entities";
 import type { PluginFlashcards } from "./flashcards";
+import type { PluginNotifications } from "./notifications";
 import type { JsonValue } from "./json";
 export type { JsonValue } from "./json";
 export interface Disposable {
@@ -79,6 +80,7 @@ export interface PluginContext {
     /** 插件自建、各带一份正文的内容；读写自己的内容不需要业务数据权限 */
     readonly entities: PluginOwnEntities;
     readonly flashcards: PluginFlashcards;
+    readonly notifications: PluginNotifications;
     /** 将订阅等资源交给宿主，在停用或激活失败时逆序回收。 */
     register(resource: Disposable): Disposable;
 }

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

@@ -20,6 +20,7 @@ export type * from "./data";
 export type * from "./entities";
 export { PluginConflictError } from "./errors";
 export { PLUGIN_ENTITY_KINDS, PLUGIN_APP_ACTIONS, PLUGIN_EXPORT_FORMATS } from "./app";
+export type { PluginNotifications, PluginNotificationOptions, PluginNotificationMode, PluginNotificationAction, } from "./notifications";
 export type { PluginApp, PluginAppAction, PluginAppActions, PluginExportFormat, PluginEntityKind, PluginEntityRef, PluginPickOptions, PluginPickedEntity, } from "./app";
 export { PLUGIN_EVENT_TYPES } from "./events";
 export type { PluginDomainEvent, PluginEventOrigin, PluginEventType, PluginEvents } from "./events";

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

@@ -0,0 +1,25 @@
+import type { Disposable } from "./contract";
+export type PluginNotificationMode = "auto" | "in-app" | "system";
+export interface PluginNotificationAction {
+    label: string;
+    primary?: boolean;
+    resolvedText?: string;
+    onClick(): void | Promise<void>;
+}
+export interface PluginNotificationOptions {
+    title: string;
+    body?: string;
+    /** 默认 auto：插件所在窗口聚焦时应用内展示，否则进入独立通知窗口。 */
+    mode?: PluginNotificationMode;
+    tone?: "neutral" | "ok" | "danger";
+    /** 常驻到用户处理或关闭，默认 false。 */
+    sticky?: boolean;
+    /** 最多两个按钮，最多一个主按钮；回调在插件所在窗口执行。 */
+    actions?: readonly PluginNotificationAction[];
+}
+export interface PluginNotifications {
+    /** 发送通知，dispose 撤销这一条；停用、激活失败或切库时自动撤销。 */
+    send(options: PluginNotificationOptions): Disposable;
+}
+/** 只复制公开字段，避免插件对象或回调进入跨进程载荷。 */
+export declare function readNotificationOptions(input: PluginNotificationOptions): PluginNotificationOptions;