@xiongtao.xt/tau-plugins 0.28.0 → 0.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/AI.md +116 -116
  2. package/API.md +65 -44
  3. package/BACKEND.md +68 -68
  4. package/CHANGELOG.md +6 -0
  5. package/DEVELOPMENT.md +6 -5
  6. package/EDITOR.md +192 -192
  7. package/FLASHCARDS.md +92 -92
  8. package/IMAGES.md +16 -16
  9. package/LICENSE +21 -21
  10. package/MCP.md +2 -0
  11. package/NOTIFICATIONS.md +48 -46
  12. package/PUBLISH-DATA.md +47 -47
  13. package/PUBLISH.md +48 -48
  14. package/SERVICES.md +119 -119
  15. package/SYNC.md +37 -37
  16. package/TTS.md +20 -20
  17. package/UPLOAD.md +35 -35
  18. package/VIDEO.md +65 -65
  19. package/WHITEBOARD.md +115 -115
  20. package/package.json +1 -1
  21. package/types/packages/editor/source-contracts.d.ts +0 -1
  22. package/types/packages/plugins/src/index.d.ts +1 -1
  23. package/types/packages/plugins/src/pages.d.ts +6 -0
  24. package/types/packages/plugins/src/publish-data.d.ts +12 -0
  25. package/types/packages/ui/src/index.d.ts +2 -0
  26. package/types/packages/ui/src/patterns/SettingRow.d.ts +14 -0
  27. package/types/packages/ui/src/primitives/DocumentCard.d.ts +11 -0
package/AI.md CHANGED
@@ -1,116 +1,116 @@
1
- # AI 服务
2
-
3
- 自定义 AI 功能需要 SDK 0.7.0；申请应用已有的模型分配需要 SDK 0.27.0。两者都需要包含对应实现的 Tau 客户端。
4
-
5
- 自定义 AI 功能由插件声明，用户在插件详情的「设置 → AI 配置」分配已有模型并开启授权。全局「大语言模型」设置管理服务商和密钥；这类功能通过 `ctx.ai` 请求模型，接口不返回密钥、连接地址或用户的聊天历史。
6
-
7
- ## 使用应用已有模型分配
8
-
9
- 无需声明 `ai.features` 或另配模型。先在 manifest 中声明 `ai:<能力名>` 权限，再申请对应客户端：
10
-
11
- ```json
12
- { "permissions": ["ai:titleSummary"] }
13
- ```
14
-
15
- ```ts
16
- const model = await context.ai.requestCapability("titleSummary");
17
- const result = await model.chat({
18
- messages: [{ role: "user", content: "为这段文字拟一个简短标题：……" }],
19
- });
20
- console.log(result.text);
21
- ```
22
-
23
- 申请时由用户选择允许或拒绝；能力分别授权，未声明的申请会被拒绝。返回客户端提供 `chat(request)` 和 `stream(request)`，参数与下文自定义 AI 相同，但不传 `feature`。每次调用复核权限，撤权、停用或切库取消在途生成；额度、并发和用量审计按插件统计。缺少应用模型分配时明确失败，不自动选择其他模型。
24
-
25
- 当前全部 12 项大模型功能分配均可申请，能力清单也可从 `PLUGIN_AI_CAPABILITIES` 导入：
26
-
27
- | 能力名 | 沿用的应用分配 |
28
- | ------------------------------ | -------------- |
29
- | `chat` | 对话功能 |
30
- | `titleSummary` | 标题总结 |
31
- | `webClip` | 网页剪藏 |
32
- | `podcastGeneration` | 播客生成 |
33
- | `flashcardGeneration` | 闪卡生成 |
34
- | `aiJudgement` | 答案评判 |
35
- | `transcriptionOptimization` | 转录断句优化 |
36
- | `videoSummary` | 视频总结 |
37
- | `videoEbookRewrite` | 视频电子书重写 |
38
- | `vibeLearningImageDescription` | 图片理解 |
39
- | `contentMetadata` | 笔记元信息 |
40
- | `contentInsights` | AI 洞见 |
41
-
42
- 这里复用模型分配，不自动执行宿主的业务流程或读取业务数据；插件传入自己的消息。已有闪卡业务流程由 `context.flashcards` 提供，它内部调用同一通用机制，需声明 `ai:flashcardGeneration`，详见 [FLASHCARDS.md](FLASHCARDS.md)。
43
-
44
- 图片理解可在 user 消息中传入 `images: [{ data: imageBase64, mimeType: "image/png" }]`。`data` 不带 data: 前缀；支持 PNG、JPEG、WebP、GIF，每条消息最多 10 张，整次请求的 Base64 总长最多 20 MiB，模型须支持图片。图片与消息正文不会写入用量审计。
45
-
46
- ## 声明自定义 AI 功能
47
-
48
- ```ts
49
- import { definePlugin } from "@tau/plugins";
50
-
51
- declare const __PLUGIN_META__: { id: string; name: string; version: string };
52
-
53
- export default definePlugin({
54
- ...__PLUGIN_META__,
55
- ai: {
56
- features: [{ id: "summary", name: "文章摘要", description: "概括用户选择的文章" }],
57
- },
58
- create: () => ({
59
- activate(ctx) {
60
- ctx.commands.register({
61
- id: "summary",
62
- title: "生成摘要",
63
- async run(input) {
64
- const status = await ctx.ai.getStatus("summary");
65
- if (!status.configured || !status.enabled) {
66
- ctx.ai.openSettings("summary");
67
- return null;
68
- }
69
- const result = await ctx.ai.chat({
70
- feature: "summary",
71
- messages: [
72
- { role: "system", content: "概括主要内容，不添加原文以外的信息。" },
73
- { role: "user", content: typeof input === "string" ? input : "请先选择正文。" },
74
- ],
75
- maxOutputTokens: 1024,
76
- });
77
- return result.text;
78
- },
79
- });
80
- },
81
- }),
82
- });
83
- ```
84
-
85
- ## 接口
86
-
87
- | 接口 | 返回与用途 |
88
- | ------------------------ | ----------------------------------------------------------------------------------- |
89
- | `getStatus(feature)` | `{ configured, enabled }`；模型被删除也视为未配置 |
90
- | `openSettings(feature?)` | 打开当前插件设置，由用户分配模型、管理授权 |
91
- | `chat(request)` | `{ text, usage }`；usage 未知时为 null |
92
- | `stream(request)` | 异步迭代器，依次产生 `{ type: "text", delta }`，最后产生 `{ type: "done", result }` |
93
-
94
- 请求字段：`feature` 必须是插件声明的功能 ID；`messages` 为 system/user/assistant 文本消息数组；`maxOutputTokens` 是可选的最大输出 Token；`signal` 为可选的取消信号。多轮历史由插件传入。多个 system 消息合并为系统提示，不提供工具调用或自动代理执行。
95
-
96
- ```ts
97
- const controller = new AbortController();
98
- for await (const event of ctx.ai.stream({
99
- feature: "summary",
100
- messages: [{ role: "user", content: article }],
101
- signal: controller.signal,
102
- })) {
103
- if (event.type === "text") appendText(event.delta);
104
- else showUsage(event.result.usage);
105
- }
106
- ```
107
-
108
- 退出迭代、取消 signal、停用插件或用户撤销 AI 授权都会请求取消。不要在模块顶层调用 AI，也不要在遇到额度不足或拒绝授权后自动循环重试。
109
-
110
- ## 审计与额度
111
-
112
- 所有模型调用由宿主归属到插件及功能，进入「大语言模型 → 用量统计」，插件设置的「查看用量」会跳转并筛选本插件。记录包含时间、模型、状态、Token、估算费用和耗时，不保存提示词或回复正文。运行中的请求可取消，也可一次关闭插件的 AI 授权。
113
-
114
- 额度按本机自然日统计，所有窗口共用，并在重启后保留。每日请求次数、每日 Token 和并发限制由用户设置；并发达到上限直接拒绝，不排队。宿主按模型上下文容量加输出上限保守预占 Token，结束后按实际已知用量结算；未知用量保留预占。供应商未报告用量时不能当作零消费；费用为估算，不替代账单。取消无法撤销已经产生的消费。
115
-
116
- 错误消息以稳定代码开头：`AI_NOT_CONFIGURED`（未配置）、`AI_DISABLED`（未授权或插件已停用）、`AI_UNDECLARED_FEATURE`（未声明）、`AI_QUOTA_EXCEEDED`（每日额度不足）、`AI_CONCURRENCY_LIMIT`（并发已满）、`AI_CONFIG_CHANGED`（模型分配变化）、`AI_ABORTED`（取消）、`AI_REQUEST_FAILED`（模型或审计失败）。本地 AbortSignal 取消也可能抛出标准 AbortError。
1
+ # AI 服务
2
+
3
+ 自定义 AI 功能需要 SDK 0.7.0；申请应用已有的模型分配需要 SDK 0.27.0。两者都需要包含对应实现的 Tau 客户端。
4
+
5
+ 自定义 AI 功能由插件声明，用户在插件详情的「设置 → AI 配置」分配已有模型并开启授权。全局「大语言模型」设置管理服务商和密钥；这类功能通过 `ctx.ai` 请求模型，接口不返回密钥、连接地址或用户的聊天历史。
6
+
7
+ ## 使用应用已有模型分配
8
+
9
+ 无需声明 `ai.features` 或另配模型。先在 manifest 中声明 `ai:<能力名>` 权限，再申请对应客户端：
10
+
11
+ ```json
12
+ { "permissions": ["ai:titleSummary"] }
13
+ ```
14
+
15
+ ```ts
16
+ const model = await context.ai.requestCapability("titleSummary");
17
+ const result = await model.chat({
18
+ messages: [{ role: "user", content: "为这段文字拟一个简短标题：……" }],
19
+ });
20
+ console.log(result.text);
21
+ ```
22
+
23
+ 申请时由用户选择允许或拒绝；能力分别授权，未声明的申请会被拒绝。返回客户端提供 `chat(request)` 和 `stream(request)`，参数与下文自定义 AI 相同，但不传 `feature`。每次调用复核权限，撤权、停用或切库取消在途生成；额度、并发和用量审计按插件统计。缺少应用模型分配时明确失败，不自动选择其他模型。
24
+
25
+ 当前全部 12 项大模型功能分配均可申请，能力清单也可从 `PLUGIN_AI_CAPABILITIES` 导入：
26
+
27
+ | 能力名 | 沿用的应用分配 |
28
+ | ------------------------------ | -------------- |
29
+ | `chat` | 对话功能 |
30
+ | `titleSummary` | 标题总结 |
31
+ | `webClip` | 网页剪藏 |
32
+ | `podcastGeneration` | 播客生成 |
33
+ | `flashcardGeneration` | 闪卡生成 |
34
+ | `aiJudgement` | 答案评判 |
35
+ | `transcriptionOptimization` | 转录断句优化 |
36
+ | `videoSummary` | 视频总结 |
37
+ | `videoEbookRewrite` | 视频电子书重写 |
38
+ | `vibeLearningImageDescription` | 图片理解 |
39
+ | `contentMetadata` | 笔记元信息 |
40
+ | `contentInsights` | AI 洞见 |
41
+
42
+ 这里复用模型分配，不自动执行宿主的业务流程或读取业务数据；插件传入自己的消息。已有闪卡业务流程由 `context.flashcards` 提供，它内部调用同一通用机制，需声明 `ai:flashcardGeneration`，详见 [FLASHCARDS.md](FLASHCARDS.md)。
43
+
44
+ 图片理解可在 user 消息中传入 `images: [{ data: imageBase64, mimeType: "image/png" }]`。`data` 不带 data: 前缀；支持 PNG、JPEG、WebP、GIF，每条消息最多 10 张，整次请求的 Base64 总长最多 20 MiB，模型须支持图片。图片与消息正文不会写入用量审计。
45
+
46
+ ## 声明自定义 AI 功能
47
+
48
+ ```ts
49
+ import { definePlugin } from "@tau/plugins";
50
+
51
+ declare const __PLUGIN_META__: { id: string; name: string; version: string };
52
+
53
+ export default definePlugin({
54
+ ...__PLUGIN_META__,
55
+ ai: {
56
+ features: [{ id: "summary", name: "文章摘要", description: "概括用户选择的文章" }],
57
+ },
58
+ create: () => ({
59
+ activate(ctx) {
60
+ ctx.commands.register({
61
+ id: "summary",
62
+ title: "生成摘要",
63
+ async run(input) {
64
+ const status = await ctx.ai.getStatus("summary");
65
+ if (!status.configured || !status.enabled) {
66
+ ctx.ai.openSettings("summary");
67
+ return null;
68
+ }
69
+ const result = await ctx.ai.chat({
70
+ feature: "summary",
71
+ messages: [
72
+ { role: "system", content: "概括主要内容，不添加原文以外的信息。" },
73
+ { role: "user", content: typeof input === "string" ? input : "请先选择正文。" },
74
+ ],
75
+ maxOutputTokens: 1024,
76
+ });
77
+ return result.text;
78
+ },
79
+ });
80
+ },
81
+ }),
82
+ });
83
+ ```
84
+
85
+ ## 接口
86
+
87
+ | 接口 | 返回与用途 |
88
+ | ------------------------ | ----------------------------------------------------------------------------------- |
89
+ | `getStatus(feature)` | `{ configured, enabled }`；模型被删除也视为未配置 |
90
+ | `openSettings(feature?)` | 打开当前插件设置，由用户分配模型、管理授权 |
91
+ | `chat(request)` | `{ text, usage }`；usage 未知时为 null |
92
+ | `stream(request)` | 异步迭代器，依次产生 `{ type: "text", delta }`，最后产生 `{ type: "done", result }` |
93
+
94
+ 请求字段：`feature` 必须是插件声明的功能 ID；`messages` 为 system/user/assistant 文本消息数组；`maxOutputTokens` 是可选的最大输出 Token；`signal` 为可选的取消信号。多轮历史由插件传入。多个 system 消息合并为系统提示，不提供工具调用或自动代理执行。
95
+
96
+ ```ts
97
+ const controller = new AbortController();
98
+ for await (const event of ctx.ai.stream({
99
+ feature: "summary",
100
+ messages: [{ role: "user", content: article }],
101
+ signal: controller.signal,
102
+ })) {
103
+ if (event.type === "text") appendText(event.delta);
104
+ else showUsage(event.result.usage);
105
+ }
106
+ ```
107
+
108
+ 退出迭代、取消 signal、停用插件或用户撤销 AI 授权都会请求取消。不要在模块顶层调用 AI，也不要在遇到额度不足或拒绝授权后自动循环重试。
109
+
110
+ ## 审计与额度
111
+
112
+ 所有模型调用由宿主归属到插件及功能，进入「大语言模型 → 用量统计」，插件设置的「查看用量」会跳转并筛选本插件。记录包含时间、模型、状态、Token、估算费用和耗时，不保存提示词或回复正文。运行中的请求可取消，也可一次关闭插件的 AI 授权。
113
+
114
+ 额度按本机自然日统计，所有窗口共用，并在重启后保留。每日请求次数、每日 Token 和并发限制由用户设置；并发达到上限直接拒绝，不排队。宿主按模型上下文容量加输出上限保守预占 Token，结束后按实际已知用量结算；未知用量保留预占。供应商未报告用量时不能当作零消费；费用为估算，不替代账单。取消无法撤销已经产生的消费。
115
+
116
+ 错误消息以稳定代码开头：`AI_NOT_CONFIGURED`（未配置）、`AI_DISABLED`（未授权或插件已停用）、`AI_UNDECLARED_FEATURE`（未声明）、`AI_QUOTA_EXCEEDED`（每日额度不足）、`AI_CONCURRENCY_LIMIT`（并发已满）、`AI_CONFIG_CHANGED`（模型分配变化）、`AI_ABORTED`（取消）、`AI_REQUEST_FAILED`（模型或审计失败）。本地 AbortSignal 取消也可能抛出标准 AbortError。
package/API.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  本文介绍编写命令、页面、侧边栏、设置、数据存储、网络请求和摘录所需的接口。插件接口从 `@tau/plugins` 导入，界面组件从 `@tau/ui` 导入。所述能力需要 Tau 0.59.0 或更高版本。
4
4
 
5
- 本文对应 SDK 0.28.0；最低客户端版本只负责版本门槛，使用新领域接口时仍需包含对应实现的客户端构建。SDK 升级步骤见 [DEVELOPMENT.md](DEVELOPMENT.md#升级-sdk-与同步旧模板)。独立后台与双入口构建见 [BACKEND.md](BACKEND.md)。
5
+ 本文对应 SDK 0.29.0；最低客户端版本只负责版本门槛，使用新领域接口时仍需包含对应实现的客户端构建。SDK 升级步骤见 [DEVELOPMENT.md](DEVELOPMENT.md#升级-sdk-与同步旧模板)。独立后台与双入口构建见 [BACKEND.md](BACKEND.md)。
6
6
 
7
7
  发送应用内或独立窗口通知见[通知](#通知)与 [NOTIFICATIONS.md](NOTIFICATIONS.md)，需要 SDK 0.28.0 和包含通知接口的客户端构建。
8
8
 
@@ -101,40 +101,40 @@ export default definePlugin({
101
101
 
102
102
  `activate` 以及页面、设置组件都会收到 `PluginContext`。
103
103
 
104
- | 属性 | 类型 | 用途 |
105
- | ------------- | -------------------------------------- | ------------------------------------------------ |
106
- | `pluginId` | `string` | 当前插件标识 |
107
- | `workspaceId` | `string` | 当前工作区标识；不要解析它的内部格式 |
108
- | `signal` | `AbortSignal` | 本次运行结束时中止，可用于停止异步工作 |
109
- | `commands` | `PluginContext["commands"]` | 注册命令 |
110
- | `storage` | `PluginStorage` | 保存当前插件在当前工作区的数据 |
111
- | `permissions` | `PluginPermissions` | 查询与申请业务数据权限 |
112
- | `flashcards` | `PluginFlashcards` | 闪卡创建与 AI 制卡，见 FLASHCARDS.md |
113
- | `data` | `PluginData` | 读取与修改卡片、文章、项目文档、待办和日程 |
114
- | `content` | `PluginContent` | 读取与修改正文 |
115
- | `events` | `PluginEvents` | 订阅业务数据变化 |
116
- | `notifications` | `PluginNotifications` | 发送应用内或独立窗口通知，默认按来源窗口焦点分流 |
117
- | `app` | `PluginApp` | 选择、打开已有内容，执行导出、演示和共享 |
118
- | `entities` | `PluginOwnEntities` | 管理插件自有内容、类型和反链 |
119
- | `backend` | `PluginBackendClient` | 调用与订阅本机后台，见 BACKEND.md |
120
- | `pages` | `PluginPages` | 注册并打开页面 |
121
- | `settings` | `PluginSettings` | 注册并打开设置区域 |
122
- | `editor` | `PluginEditor` | 开发台编辑器贡献；正文使用静态扩展，见 EDITOR.md |
123
- | `sync` | `PluginSync` | 注册同步存储提供方，见 SYNC.md |
124
- | `upload` | `PluginUpload` | 资源上传与上传提供方，见 UPLOAD.md |
125
- | `tts` | `PluginTTS` | 语音合成与音色复刻提供方，见 TTS.md |
126
- | `images` | `PluginImages` | 图片生成与编辑提供方，见 IMAGES.md |
127
- | `video` | `PluginVideo` | 视频来源与播放源提供方，见 VIDEO.md |
128
- | `publish` | `PluginPublish` | 博客发布提供方，见 PUBLISH.md |
129
- | `sidebar` | `PluginSidebar` | 创建侧边栏分组、注册页面入口 |
130
- | `fetch` | `typeof fetch` | 发起与插件生命周期关联的网络请求 |
131
- | `services` | `PluginServices` | 编译与转换服务，见 SERVICES.md |
132
- | `ai` | `PluginAI` | 使用用户分配的模型，见 AI.md |
133
- | `mcp` | `PluginMCP` | 注册 MCP，本地工具或外部服务器，见 MCP.md |
134
- | `chat` | `PluginChat` | 注册 MCP 工具结果渲染器，见 MCP.md |
135
- | `excerpts` | `PluginExcerpts` | 把外部划线、标注写为 Tau 摘录 |
136
- | `materials` | `PluginMaterials` | 获取「转为卡片」等材料动作 |
137
- | `register` | `(resource: Disposable) => Disposable` | 托管需要清理的资源 |
104
+ | 属性 | 类型 | 用途 |
105
+ | --------------- | -------------------------------------- | ------------------------------------------------ |
106
+ | `pluginId` | `string` | 当前插件标识 |
107
+ | `workspaceId` | `string` | 当前工作区标识；不要解析它的内部格式 |
108
+ | `signal` | `AbortSignal` | 本次运行结束时中止，可用于停止异步工作 |
109
+ | `commands` | `PluginContext["commands"]` | 注册命令 |
110
+ | `storage` | `PluginStorage` | 保存当前插件在当前工作区的数据 |
111
+ | `permissions` | `PluginPermissions` | 查询与申请业务数据权限 |
112
+ | `flashcards` | `PluginFlashcards` | 闪卡创建与 AI 制卡，见 FLASHCARDS.md |
113
+ | `data` | `PluginData` | 读取与修改卡片、文章、项目文档、待办和日程 |
114
+ | `content` | `PluginContent` | 读取与修改正文 |
115
+ | `events` | `PluginEvents` | 订阅业务数据变化 |
116
+ | `notifications` | `PluginNotifications` | 发送应用内或独立窗口通知，默认按来源窗口焦点分流 |
117
+ | `app` | `PluginApp` | 选择、打开已有内容，执行导出、演示和共享 |
118
+ | `entities` | `PluginOwnEntities` | 管理插件自有内容、类型和反链 |
119
+ | `backend` | `PluginBackendClient` | 调用与订阅本机后台，见 BACKEND.md |
120
+ | `pages` | `PluginPages` | 注册并打开页面 |
121
+ | `settings` | `PluginSettings` | 注册并打开设置区域 |
122
+ | `editor` | `PluginEditor` | 开发台编辑器贡献；正文使用静态扩展，见 EDITOR.md |
123
+ | `sync` | `PluginSync` | 注册同步存储提供方，见 SYNC.md |
124
+ | `upload` | `PluginUpload` | 资源上传与上传提供方，见 UPLOAD.md |
125
+ | `tts` | `PluginTTS` | 语音合成与音色复刻提供方，见 TTS.md |
126
+ | `images` | `PluginImages` | 图片生成与编辑提供方，见 IMAGES.md |
127
+ | `video` | `PluginVideo` | 视频来源与播放源提供方，见 VIDEO.md |
128
+ | `publish` | `PluginPublish` | 博客发布提供方，见 PUBLISH.md |
129
+ | `sidebar` | `PluginSidebar` | 创建侧边栏分组、注册页面入口 |
130
+ | `fetch` | `typeof fetch` | 发起与插件生命周期关联的网络请求 |
131
+ | `services` | `PluginServices` | 编译与转换服务，见 SERVICES.md |
132
+ | `ai` | `PluginAI` | 使用用户分配的模型，见 AI.md |
133
+ | `mcp` | `PluginMCP` | 注册 MCP，本地工具或外部服务器，见 MCP.md |
134
+ | `chat` | `PluginChat` | 注册 MCP 工具结果渲染器，见 MCP.md |
135
+ | `excerpts` | `PluginExcerpts` | 把外部划线、标注写为 Tau 摘录 |
136
+ | `materials` | `PluginMaterials` | 获取「转为卡片」等材料动作 |
137
+ | `register` | `(resource: Disposable) => Disposable` | 托管需要清理的资源 |
138
138
 
139
139
  不要缓存上下文供下次启用使用。旧上下文失效后调用 storage、注册功能或打开页面会报错。
140
140
 
@@ -179,14 +179,14 @@ const notification = context.notifications.send({
179
179
  // 需要提前撤销时：await notification.dispose();
180
180
  ```
181
181
 
182
- | 参数 | 类型 | 说明 |
183
- | --- | --- | --- |
184
- | `title` | `string` | 必填，非空，最多 200 字符 |
185
- | `body` | `string`，可选 | 非空，最多 5000 字符 |
186
- | `mode` | `"auto" \| "in-app" \| "system"` | 默认 auto：来源窗口聚焦时应用内展示，否则进入独立通知窗口 |
187
- | `tone` | `"neutral" \| "ok" \| "danger"` | 默认 neutral |
188
- | `sticky` | `boolean`，可选 | 为 true 时保持显示直到用户处理、关闭或插件撤销 |
189
- | `actions` | `readonly PluginNotificationAction[]`，可选 | 最多两个按钮，最多一个主按钮 |
182
+ | 参数 | 类型 | 说明 |
183
+ | --------- | ------------------------------------------- | --------------------------------------------------------- |
184
+ | `title` | `string` | 必填，非空，最多 200 字符 |
185
+ | `body` | `string`，可选 | 非空，最多 5000 字符 |
186
+ | `mode` | `"auto" \| "in-app" \| "system"` | 默认 auto：来源窗口聚焦时应用内展示，否则进入独立通知窗口 |
187
+ | `tone` | `"neutral" \| "ok" \| "danger"` | 默认 neutral |
188
+ | `sticky` | `boolean`，可选 | 为 true 时保持显示直到用户处理、关闭或插件撤销 |
189
+ | `actions` | `readonly PluginNotificationAction[]`，可选 | 最多两个按钮，最多一个主按钮 |
190
190
 
191
191
  `in-app` 固定进入插件所在窗口，不主动聚焦；`system` 固定使用 Tau 的独立通知窗口。通知发送后不会随焦点变化搬移。来源标签固定为插件名称，ID 由宿主生成；不接受自定义全局 ID、HTML 或 React 内容。
192
192
 
@@ -228,7 +228,7 @@ await context.storage.set("count", count + 1);
228
228
 
229
229
  句柄提供只读 `id`、`open(params?): Promise<void>` 和 `dispose()`。`open()` 负责导航，不要自行操作浏览器地址或历史。重复打开单实例页面会复用该页面身份；句柄注销或插件停用后不能再打开。
230
230
 
231
- 组件收到 `context` 和只读 `params`。参数仅支持字符串、有限数字、布尔值组成的对象，不接受数组、嵌套对象或 `null`。
231
+ 组件收到 `context`、只读 `params` 和实例级 `pageContext`。参数仅支持字符串、有限数字、布尔值组成的对象，不接受数组、嵌套对象或 `null`。
232
232
 
233
233
  下面的完整示例注册一个按条目 ID 区分的页面，以及打开页面的命令：
234
234
 
@@ -265,6 +265,27 @@ export default definePlugin({
265
265
  });
266
266
  ```
267
267
 
268
+ ### 提供当前页面上下文
269
+
270
+ SDK 0.29.0 与包含此能力的客户端构建提供 `PluginPageProps.pageContext.register(provider)`。旧客户端可能没有该接口，依赖此能力时检查 `pageContext?.register` 并提示升级；仅提高 SDK 版本不能替代客户端能力检查。
271
+
272
+ 在组件的 `useEffect` 中注册一个同步提供器，并在清理时注销：
273
+
274
+ ```tsx
275
+ useEffect(() => {
276
+ const registration = pageContext.register(() => currentValue);
277
+ return () => {
278
+ registration.dispose();
279
+ };
280
+ }, [pageContext, currentValue]);
281
+ ```
282
+
283
+ 此片段放在页面组件内，从 React 导入 useEffect；currentValue 是作者自行选择的页面状态。返回值可以是任意 `JsonValue`，包括字符串、数字、布尔值、数组、对象或 null；宿主不规定任何业务字段或形状。状态变化时按示例重新登记，或通过最新状态引用读取；不要只捕获首次渲染的旧值。提供器只读已有状态，不发起异步请求或写入。
284
+
285
+ 现有 `get_current_context` 工具会把当前插件页面的返回值直接放入 `page.pluginContext`。同一页面多开时仅读取当前实例；未注册、返回 null、异常或不符合 JSON 要求时为 null，其他上下文仍正常返回。每个实例同时只允许一个提供器；隐藏时注销，恢复时 effect 重跑重新登记，卸载、停用和切库由宿主兜底清理。
286
+
287
+ 页面操作继续使用现有 `context.mcp.register()`。AI 可将页面上下文中的信息传给作者的 MCP，具体参数和业务校验由作者定义；注册上下文不会自动注册任何操作或授予额外权限。
288
+
268
289
  ## 侧边栏
269
290
 
270
291
  `context.sidebar` 为页面添加侧边栏入口。条目关联已有页面，点击自动打开并随当前页面高亮；停用后入口消失，恢复启用时重新注册。
package/BACKEND.md CHANGED
@@ -1,68 +1,68 @@
1
- # 本机后台开发
2
-
3
- 后台入口需要 SDK 0.25.0 及支持包格式 2 的客户端构建。不要只修改版本号就认为客户端已经具备运行能力。普通渲染插件仍使用格式 1。使用 Node 内置模块前执行 `pnpm add -D @types/node@24.0.0 --save-exact` 安装类型声明。
4
-
5
- 仓库提供完整双入口样本：`scripts/plugins/fixtures/backend-system.tsx` 为界面，`backend-system.ts` 为后台。在宿主仓库运行 `node scripts/plugins/verify-backend-author.mjs`，会打包 SDK，在仓库外安装 tarball、类型检查、构建双入口 ZIP，并用真实 Electron utilityProcess 调用样本。结果位于 `output/plugin-backend-sdk/`；该命令不安装到用户目录、不发布到市场。
6
-
7
- 在 manifest.json 中将 formatVersion 设为 2，保留 main.js，并增加 backend：
8
-
9
- ```json
10
- {
11
- "entry": "backend.js",
12
- "runtime": "node",
13
- "apiVersion": 1,
14
- "scope": "application",
15
- "activation": "app-ready",
16
- "lifetime": "persistent",
17
- "reason": "连接本机设备并向插件页面提供设备状态",
18
- "systemAccess": ["network"]
19
- }
20
- ```
21
-
22
- 模板从 src/backend.ts 构建独立的 backend.js。Node 内置模块可直接引用，第三方 JS 依赖打入 bundle；仅 @tau/plugins/backend 由宿主提供。不打包 node_modules，不运行安装脚本，不让前端入口引用后台文件。main、后台及样式的摘要由构建生成。
23
-
24
- application 作用域支持 on-demand、app-ready；workspace 支持 on-demand、workspace-ready。lifetime 为 idle 或 persistent，常驻直到所属作用域结束。安装不等于启用，声明不等于授权；无授权的自动启动进入等待处理状态。系统用途字段用于用户知情和审核，不是操作系统沙箱。
25
-
26
- pnpm build 生成整包 ZIP，pnpm install:local 仍只用于首次开发安装且拒绝覆盖既有目录。后台新版本与界面同包更新，不能只替换 backend.js。
27
-
28
- ## 定义后台方法
29
-
30
- ```ts
31
- import { defineBackend } from "@tau/plugins/backend";
32
- import { platform } from "node:os";
33
-
34
- export default defineBackend({
35
- create() {
36
- return {
37
- activate(ctx) {
38
- ctx.rpc.register(
39
- "system.platform",
40
- {
41
- input: {
42
- parse(value: unknown) {
43
- if (value !== null) throw new Error("此方法不接受参数");
44
- return null;
45
- },
46
- },
47
- output: {
48
- parse(value: unknown) {
49
- if (typeof value !== "string") throw new Error("平台结果无效");
50
- return value;
51
- },
52
- },
53
- },
54
- () => platform()
55
- );
56
- },
57
- };
58
- },
59
- });
60
- ```
61
-
62
- 渲染入口通过 `await ctx.backend.call("system.platform", null, { signal })` 调用。请求和结果必须为有限 JSON，普通消息最多 1 MiB。后台必须提供输入、输出解析器，异常返回调用方。`ctx.rpc.emit(name, value)` 与 `ctx.backend.subscribe(name, listener)` 用于事件；订阅返回可回收句柄。停用或切库后旧连接失效。
63
-
64
- 外部程序通过 `ctx.process.run(toolId, args, { signal })` 执行，返回 exitCode/stdout/stderr。同时在 backend.systemAccess 声明 process，并以 backend.tools 列出 `{ id, command, args? }`。参数以数组传递，不自动经过 Shell；stdout/stderr 合计最多 512 KiB，单次执行 30 秒。Windows 只接受可解析到唯一 EXE 的工具，使用宿主 Job Object；Unix 使用进程组监督。需要取消时把 RPC 的 request.signal 继续传给工具。
65
-
66
- 不要在模块顶层启动任务。计时器、订阅等使用 `ctx.register` 清理；后台长期任务应响应 `ctx.signal`。主进程扫描不会执行后台，客户端会在首次运行前要求本机代码执行授权。独立进程不会限制 Node 对本机文件、网络的实际权限。
67
-
68
- 插件中心每个后台版本都需人工重点审核，审核者本人的 CI 提交也不自动批准。更新后本机授权重新确认；有在途任务、订阅或插件 MCP 连接时先结束这些工作。已知撤回的中心版本禁止执行；离线只能依据上次已获取的发布状态。原始 stdout/stderr 不写宿主日志，管理页展示有界错误、启动耗时、失败/超时次数及进程资源采样。
1
+ # 本机后台开发
2
+
3
+ 后台入口需要 SDK 0.25.0 及支持包格式 2 的客户端构建。不要只修改版本号就认为客户端已经具备运行能力。普通渲染插件仍使用格式 1。使用 Node 内置模块前执行 `pnpm add -D @types/node@24.0.0 --save-exact` 安装类型声明。
4
+
5
+ 仓库提供完整双入口样本：`scripts/plugins/fixtures/backend-system.tsx` 为界面，`backend-system.ts` 为后台。在宿主仓库运行 `node scripts/plugins/verify-backend-author.mjs`，会打包 SDK，在仓库外安装 tarball、类型检查、构建双入口 ZIP，并用真实 Electron utilityProcess 调用样本。结果位于 `output/plugin-backend-sdk/`；该命令不安装到用户目录、不发布到市场。
6
+
7
+ 在 manifest.json 中将 formatVersion 设为 2，保留 main.js，并增加 backend：
8
+
9
+ ```json
10
+ {
11
+ "entry": "backend.js",
12
+ "runtime": "node",
13
+ "apiVersion": 1,
14
+ "scope": "application",
15
+ "activation": "app-ready",
16
+ "lifetime": "persistent",
17
+ "reason": "连接本机设备并向插件页面提供设备状态",
18
+ "systemAccess": ["network"]
19
+ }
20
+ ```
21
+
22
+ 模板从 src/backend.ts 构建独立的 backend.js。Node 内置模块可直接引用，第三方 JS 依赖打入 bundle；仅 @tau/plugins/backend 由宿主提供。不打包 node_modules，不运行安装脚本，不让前端入口引用后台文件。main、后台及样式的摘要由构建生成。
23
+
24
+ application 作用域支持 on-demand、app-ready；workspace 支持 on-demand、workspace-ready。lifetime 为 idle 或 persistent，常驻直到所属作用域结束。安装不等于启用，声明不等于授权；无授权的自动启动进入等待处理状态。系统用途字段用于用户知情和审核，不是操作系统沙箱。
25
+
26
+ pnpm build 生成整包 ZIP，pnpm install:local 仍只用于首次开发安装且拒绝覆盖既有目录。后台新版本与界面同包更新，不能只替换 backend.js。
27
+
28
+ ## 定义后台方法
29
+
30
+ ```ts
31
+ import { defineBackend } from "@tau/plugins/backend";
32
+ import { platform } from "node:os";
33
+
34
+ export default defineBackend({
35
+ create() {
36
+ return {
37
+ activate(ctx) {
38
+ ctx.rpc.register(
39
+ "system.platform",
40
+ {
41
+ input: {
42
+ parse(value: unknown) {
43
+ if (value !== null) throw new Error("此方法不接受参数");
44
+ return null;
45
+ },
46
+ },
47
+ output: {
48
+ parse(value: unknown) {
49
+ if (typeof value !== "string") throw new Error("平台结果无效");
50
+ return value;
51
+ },
52
+ },
53
+ },
54
+ () => platform()
55
+ );
56
+ },
57
+ };
58
+ },
59
+ });
60
+ ```
61
+
62
+ 渲染入口通过 `await ctx.backend.call("system.platform", null, { signal })` 调用。请求和结果必须为有限 JSON，普通消息最多 1 MiB。后台必须提供输入、输出解析器，异常返回调用方。`ctx.rpc.emit(name, value)` 与 `ctx.backend.subscribe(name, listener)` 用于事件；订阅返回可回收句柄。停用或切库后旧连接失效。
63
+
64
+ 外部程序通过 `ctx.process.run(toolId, args, { signal })` 执行，返回 exitCode/stdout/stderr。同时在 backend.systemAccess 声明 process，并以 backend.tools 列出 `{ id, command, args? }`。参数以数组传递，不自动经过 Shell；stdout/stderr 合计最多 512 KiB，单次执行 30 秒。Windows 只接受可解析到唯一 EXE 的工具，使用宿主 Job Object；Unix 使用进程组监督。需要取消时把 RPC 的 request.signal 继续传给工具。
65
+
66
+ 不要在模块顶层启动任务。计时器、订阅等使用 `ctx.register` 清理；后台长期任务应响应 `ctx.signal`。主进程扫描不会执行后台，客户端会在首次运行前要求本机代码执行授权。独立进程不会限制 Node 对本机文件、网络的实际权限。
67
+
68
+ 插件中心每个后台版本都需人工重点审核，审核者本人的 CI 提交也不自动批准。更新后本机授权重新确认；有在途任务、订阅或插件 MCP 连接时先结束这些工作。已知撤回的中心版本禁止执行；离线只能依据上次已获取的发布状态。原始 stdout/stderr 不写宿主日志，管理页展示有界错误、启动耗时、失败/超时次数及进程资源采样。
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # 更新记录
2
2
 
3
+ ## 0.29.0
4
+
5
+ - 页面组件新增 `pageContext.register(provider)`：通过现有 `get_current_context` 向 AI 提供当前页面状态，返回任意有限 JSON，业务内容与形状完全由作者决定。
6
+ - 只读取当前页面实例，支持状态更新、保活恢复和注销；停用、卸载及切库时自动清理，提供器异常不影响其他上下文。
7
+ - 页面操作继续由作者通过已有 MCP 注册能力提供，通知等已发布能力保持可用。
8
+
3
9
  ## 0.28.0
4
10
 
5
11
  - 新增 `context.notifications.send`：发送应用内通知、独立窗口通知，或默认按来源窗口焦点自动分流。
package/DEVELOPMENT.md CHANGED
@@ -8,7 +8,7 @@
8
8
  - pnpm 11.9.0
9
9
  - Tau 桌面客户端 0.59.0 或更高版本
10
10
 
11
- 模板锁定公开 SDK `@xiongtao.xt/tau-plugins@0.28.0` 和 UI `@xiongtao.xt/tau-ui@0.1.1`，通过 npm 别名安装为 `@tau/plugins`、`@tau/ui`。SDK 提供类型契约，运行实现由 Tau 注入；新领域能力还需包含相应实现的客户端构建，不能只依据客户端版本号判断。
11
+ 模板锁定公开 SDK `@xiongtao.xt/tau-plugins@0.29.0` 和 UI `@xiongtao.xt/tau-ui@0.1.1`，通过 npm 别名安装为 `@tau/plugins`、`@tau/ui`。SDK 提供类型契约，运行实现由 Tau 注入；新领域能力还需包含相应实现的客户端构建，不能只依据客户端版本号判断。
12
12
 
13
13
  ## 跑通示例
14
14
 
@@ -45,7 +45,7 @@ pnpm install:local
45
45
  | `MCP.md` | 注册 MCP、聊天工具渲染，复用工具开关与服务器管理 |
46
46
  | `BACKEND.md` | 显式声明本机后台、启动策略与独立产物构建 |
47
47
  | `FLASHCARDS.md` | 闪卡读写权限、宿主制卡窗口、插件 AI 与正文来源引用 |
48
- | `NOTIFICATIONS.md` | 应用内、独立窗口通知、自动分流与生命周期清理 |
48
+ | `NOTIFICATIONS.md` | 应用内、独立窗口通知、自动分流与生命周期清理 |
49
49
  | `WHITEBOARD.md` | 静态白板扩展、工具与发布边界 |
50
50
  | `SYNC.md` | 同步存储提供方、配置视图与取消 |
51
51
  | `UPLOAD.md` | 图片与附件上传、上传提供方与配置 |
@@ -64,10 +64,10 @@ pnpm install:local
64
64
 
65
65
  GitHub 模板创建的仓库不会自动跟随模板更新。已有项目先提交或备份自己的改动，再按需同步 [上游模板](https://github.com/LastKnightCoder/tau-plugin-template) 的构建脚本、开发文档和 `.github/workflows/release.yml`，保留自己的插件 ID、入口、用户说明与版本记录。
66
66
 
67
- 先在 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` 中增加新 SDK 的精确例外 `@xiongtao.xt/tau-plugins@0.28.0`，暂时保留旧锁文件所需的已核实例外，再更新依赖及锁文件：
67
+ 先在 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` 中增加新 SDK 的精确例外 `@xiongtao.xt/tau-plugins@0.29.0`，暂时保留旧锁文件所需的已核实例外，再更新依赖及锁文件：
68
68
 
69
69
  ```sh
70
- pnpm add @tau/plugins@npm:@xiongtao.xt/tau-plugins@0.28.0 --save-exact
70
+ pnpm add @tau/plugins@npm:@xiongtao.xt/tau-plugins@0.29.0 --save-exact
71
71
  pnpm install --frozen-lockfile
72
72
  pnpm build
73
73
  ```
@@ -88,7 +88,8 @@ pnpm build
88
88
  | 0.25.0 | 数据读写与权限、正文组件、插件实体、宿主动作、存储随库同步，见 API.md；本机后台双入口见 BACKEND.md |
89
89
  | 0.26.0 | 闪卡创建、读写授权、插件 AI 制卡与 contentRef 来源引用，见 FLASHCARDS.md |
90
90
  | 0.27.0 | 通用 requestCapability 开放全部内置大模型功能分配，分别以 ai:<能力名> 授权；闪卡复用同一机制，见 AI.md |
91
- | 0.28.0 | 通知发送、应用内或独立窗口展示、焦点自动分流与生命周期清理，见 NOTIFICATIONS.md |
91
+ | 0.28.0 | 通知发送、应用内或独立窗口展示、焦点自动分流与生命周期清理，见 NOTIFICATIONS.md |
92
+ | 0.29.0 | 页面通过 pageContext.register 提供任意 JSON 上下文，现有 get_current_context 读取，见 API.md |
92
93
 
93
94
  更早版本的完整变更见已安装包的 `node_modules/@tau/plugins/CHANGELOG.md`。需要本地媒体元数据时自行实现，不能把视频页面解析当作本地文件探测。SDK 根入口、白板/同步契约、UI 和 React 由 Tau 提供，保持模板的 external 配置；普通第三方库由构建打入 ZIP。独立站点数据子入口的用途另见 PUBLISH-DATA.md。
94
95