@xiongtao.xt/tau-plugins 0.29.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 (6) hide show
  1. package/API.md +881 -881
  2. package/CHANGELOG.md +114 -114
  3. package/DEVELOPMENT.md +173 -173
  4. package/package.json +1 -1
  5. package/types/packages/ui/src/index.d.ts +1 -0
  6. package/types/packages/ui/src/patterns/SettingRow.d.ts +14 -0
package/CHANGELOG.md CHANGED
@@ -1,114 +1,114 @@
1
- # 更新记录
2
-
3
- ## 0.29.0
4
-
5
- - 页面组件新增 `pageContext.register(provider)`：通过现有 `get_current_context` 向 AI 提供当前页面状态，返回任意有限 JSON，业务内容与形状完全由作者决定。
6
- - 只读取当前页面实例，支持状态更新、保活恢复和注销；停用、卸载及切库时自动清理，提供器异常不影响其他上下文。
7
- - 页面操作继续由作者通过已有 MCP 注册能力提供，通知等已发布能力保持可用。
8
-
9
- ## 0.28.0
10
-
11
- - 新增 `context.notifications.send`：发送应用内通知、独立窗口通知，或默认按来源窗口焦点自动分流。
12
- - 支持标题、正文、语义、常驻与最多两个操作按钮；来源显示插件名称。
13
- - 返回 `Disposable` 撤销单条通知，停用、激活失败及切库时自动回收，旧按钮回调失效。
14
-
15
- ## 0.27.0
16
-
17
- - 新增通用 `context.ai.requestCapability(name)`，开放应用全部 12 项大模型功能分配。每项声明 `ai:<能力名>` 并由用户独立授权，返回 `chat/stream` 客户端，不需要另配模型或声明自定义 AI 功能。
18
- - 闪卡 AI 制作使用此通用入口，权限为 `ai:flashcardGeneration`；不再要求传入 `feature`。支持在 user 消息中附带图片，图片不进入用量审计。
19
- - 宿主模型仍经插件额度、并发限制与用量审计执行；撤销闪卡 AI 权限会取消在途请求，应用未配模型或分配变化时明确失败。
20
- - 插件自定义 AI 的原有声明、授权与模型分配保持独立；闪卡读写权限和 `contentRef` 来源校验沿用 0.26.0。
21
-
22
- ## 0.26.0
23
-
24
- - 新增 `context.flashcards`：查询与创建卡组、创建闪卡、宿主制卡窗口、AI 草稿与自动保存；直接读写经 `flashcards:read/write` 授权。
25
- - 插件 AI 制卡使用声明的 AI 功能及用户分配的模型，受插件授权、额度与用量审计约束。宿主制卡窗口要求用户操作，保存由用户确认。
26
- - 现有正文引用使用不透明 `contentRef`，校验正文身份及读取权限；停用、切库取消在途任务，自动保存保留已提交结果。
27
-
28
- ## 0.25.0
29
-
30
- - 新增独立本机后台：格式 2 插件声明 `backend`，通过 `@tau/plugins/backend` 的 `defineBackend` 注册方法，界面经 `context.backend.call/subscribe` 调用与订阅。支持按需或随作用域启动、取消、受监督的外部工具与本机执行授权；构建脚本生成双入口及完整性摘要，详见 BACKEND.md。普通插件继续使用格式 1。
31
- - 新增业务数据只读接口：`context.data` 读取卡片、文章、项目文档、待办与日程，`context.content.read` 按 `contentRef` 读取正文（Markdown 或编辑器节点）。查询按时间范围、标签筛选并分页。
32
- - 新增权限：manifest `permissions` 声明可申请的上限（`cards:read`、`articles:read`、`documents:read`、`todos:read`、`calendar:read`），首次调用时由用户选择「仅这次」「始终允许」或「拒绝」。未获准时抛出 `PluginPermissionError`；`context.permissions` 可查询状态与一次申请多项。
33
- - 新增 `context.events.on`：卡片、文章、项目文档的创建 / 更新 / 删除，待办与日程的集合级变化，以及同步下载后的 `workspace.reset`。事件不携带数据，需要对应读取权限才会送达。
34
- - 新增写入：卡片与文章的新建、修改、删除，项目文档的标题与标签，待办与日程的新建、修改、完成、删除；`context.content.edit` 追加、插入或替换正文。修改与删除需传入读取时的 `revision`，数据已被别处修改时抛出 `PluginConflictError`。插件删除的内容用户可在 7 天内恢复。
35
- - 权限词表增加 `*:write` 与 `*:delete`；事件增加 `origin`，可识别由插件写入的变化。
36
- - 新增 `context.app.pick` 与 `context.app.open`：用 Tau 的搜索窗口让用户选择卡片、文章、项目文档、日记、白板、待办或日程，并打开它们的页面。用户亲手选择即可引用，不需要数据权限；只能在用户操作后调用。
37
- - 新增正文组件 `ContentEditor` 与 `ContentPreview`：在插件页面嵌入与卡片详情相同的编辑器（协作、已安装的编辑器扩展、文档待办都生效），或只读显示正文开头几块。按所属内容的读取 / 写入权限放行，未授权时由用户点击「允许访问」后再询问。
38
- - 新增 `context.app.run`：把卡片、文章、项目文档的正文交给 Tau 导出（Markdown、图片、PDF、EPUB）、全屏演示或发起协作共享，界面与卡片详情中的相同。只能在用户操作后调用，不需要数据权限。
39
- - 新增 `context.entities`：插件创建自己的内容（如周记），每项带一份正文，用 `ContentEditor` 编辑或 `context.content` 读写，不需要业务数据权限。卸载插件后内容保留 7 天，期间重新安装可找回。插件内容可被全局搜索与 AI 检索找到，点击结果按 `registerKind` 声明的 `open` 打开插件页面；`ContentEditor` 增加 `at`，打开到命中处。声明 `mentionable` 的类型可在正文中用 @ 引用；`context.entities.backlinks` 列出引用了它的卡片、文章与项目文档（只含已获准读取的类型）。
40
- - `context.entities.registerKind` 增加 `icon`，与侧边栏图标同一写法；新增 `PluginIcon` / `PluginIconProps`，`PluginSidebarIcon` / `PluginSidebarIconProps` 保留为同义名。插件内容在搜索、@ 面板、正文中的引用、脉络与漫步里按声明的类型名与图标显示，插件停用或卸载后的 7 天内同样如此。
41
- - 新增 `context.entities.delete`：删除插件自己的内容及正文，用户可在插件详情页 7 天内恢复，恢复后 ID 与正文不变。
42
- - `context.storage` 的数据改为保存在笔记库里，随云同步；升级后首次启动自动迁移本机已有的数据，单个值不超过 1 MB。
43
- - 权限约束的是 SDK 接口；插件仍与应用运行在同一环境，不提供安全隔离。
44
-
45
- ## 0.24.0
46
-
47
- - 移除 `PluginServices.typst`：宿主不再内置 Typst 编译服务（原生二进制约 37 MB/平台随之从安装包移除）。Typst 排版由 `tau.typst` 插件 v0.2.0 以 WebAssembly 引擎在渲染进程本地完成，首次使用联网下载编译组件与字体并长期缓存。
48
- - 旧版 `tau.typst` 插件（0.1.x）在新宿主上不再能实时编译，已保存的排版缓存与源码照常显示。
49
-
50
- ## 0.23.1
51
-
52
- - 修正 FFprobe 升级说明中已删除类型的名称为 `MediaInfo`，接口与 0.23.0 相同。
53
-
54
- ## 0.23.0
55
-
56
- - 移除 `PluginServices.ffmpeg.probe` 及其媒体信息类型，宿主不再随包分发 FFprobe；`ffmpeg.run` 保留。
57
- - 视频页面标题、时长和格式查询继续使用 `services.videoExtractor.probe`，该接口由宿主视频解析器提供，不是本地媒体探测接口的替代品。
58
- - 作者模板升级到本版 SDK，补齐博客发布、独立站点数据接入与升级说明，并修正服务文档中的已移除接口。
59
-
60
- ## 0.22.0
61
-
62
- - 新增 `context.video.register`，接入视频来源（视频网站、自建服务器等）：插件识别链接、解析标题与清晰度，返回播放源描述（单文件、音视频分离或交给宿主解析器），下载、缓存与播放由宿主完成。
63
- - 视频账号与代理配置通过 `settings.register({ target: "video" })` 注册，接收每个插件一份的 `videoConfig`。
64
- - 新增 `services.videoExtractor.probe`，查询视频页面的标题与可下载格式；新增插件分类 `video`（在线视频）。
65
-
66
- ## 0.21.0
67
-
68
- - 新增 context.publish 发布提供方、publishConfig 配置表单和文件式／快照式提交协议，本地导出仍由宿主提供。
69
- - 新增受控 Git 快照发布与缓存目录选择服务，插件不获得任意命令或宿主文件访问。
70
- - 插件分类新增博客发布。
71
-
72
- ## 0.20.0
73
-
74
- - manifest 支持 `categories`（插件中心分类）与 `keywords`（目录搜索），门户上传严格校验，客户端忽略未知值。
75
- - 博客模板包（`template` 分支）同样支持分类与关键词，只含静态站点产物，不能同时声明代码插件入口。
76
- - publish-data：站点级数据（`settings`、`collections`、`cardTagTree`、`projectTrees`）改为只在清单中出现；内容文件新增 `links`，只含本文用到且已发布的站内链接目标。
77
- - publish-client：`readData` 随正文带回清单的 `settings`；检索引擎按索引缓存，不再每次查询重建。
78
-
79
- ## 0.19.0
80
-
81
- - 补齐 publish-data 类型、publish-client 纯数据客户端及 publish-artifacts 协议校验/定义求值入口；数据与产物声明不连带载入 Editor/React/UI 类型。
82
- - 普通 SDK/UI 根入口保持类型与 Tau 注入约定；通用源码组件契约与实现由 Editor 公开入口维护，既有源码宿主适配只负责接线。
83
- - 保留 master 0.18.0 的图片插件及全部已插件化接口。
84
-
85
- ## 0.18.0
86
-
87
- - 新增 `context.images.register`，按账号配置与模型创建图片生成或编辑实例，返回图片字节和实际 MIME。
88
- - 图片配置视图通过 `settings.register({ target: "images" })` 注册，接收当前账号的 `imageConfig`；保存按实例隔离，不使用共享凭据。
89
- - 图片插件在主窗口渲染进程执行，跨窗口调用、上传、取消和停用共用任务生命周期；保留 TTS 与上传等既有接口。
90
-
91
- ## 0.17.0
92
-
93
- - 新增通用行内源码 API：useInlineSource、insertInlineSource 和 InlineSourceBoundary，复用宿主 Slate 实例与浏览器行内边界处理。
94
- - 行内源码更新和删除遵守只读、卸载/停驻、目标替换及编辑器提交守卫；不修改 useSourceBlock、EditorKit 或已有节点格式。
95
- - 保留已有 TTS、上传、聊天、独立服务入口与 TikZ 服务移除边界；客户端版本不变。
96
-
97
- ## 0.16.0
98
-
99
- - 新增独立 `usePluginServices()`，由插件渲染运行时提供已有编译与转换服务；博客及无服务的宿主返回 undefined。
100
- - 服务按当前窗口和工作区绑定取消与失效保护，静态编辑器组件无需调用 activate；原有 context.services 保持不变。
101
- - 不修改 useSourceBlock、EditorKit、文档节点协议或编译接口；保留 TTS、上传、聊天工具展示及 TikZ 服务删除边界。
102
-
103
- ## 0.15.0
104
-
105
- - 新增 `context.chat.registerToolRenderer`，按本插件 MCP ID 与原始工具名异步登记 React 工具渲染器，激活成功后发布，停用、重载或切库时回收。
106
- - 本地工具支持 `{ content, render: { version, data } }`，展示数据沿 pi 会话保存并支持历史回放；保留默认展示、宿主审批及失败/取消语义。
107
- - 渲染器仅匹配绑定工具，组件接收独立执行快照；修复异常订阅中断回收及审批/重试恢复状态的终态收敛。
108
- - 保留 0.13.0 的 TTS、资源上传接口及 0.14.0 移除 TikZ 服务的边界；UI 包无需升级。
109
-
110
- ## 0.14.0
111
-
112
- - 移除 `PluginServices.tikz` 和 `context.services.tikz.compile`。TikZ 编译、字体与文档块由独立插件 tau.tikz 提供，宿主不再保留编译实现或转发入口。
113
- - 插件作者如需 TikZ 绘图，应由自己的插件携带实现；其他宿主编译与转换服务保持不变。
114
- - 保留 0.13.0 的 TTS、资源上传及其生命周期接口。
1
+ # 更新记录
2
+
3
+ ## 0.29.0
4
+
5
+ - 页面组件新增 `pageContext.register(provider)`：通过现有 `get_current_context` 向 AI 提供当前页面状态，返回任意有限 JSON，业务内容与形状完全由作者决定。
6
+ - 只读取当前页面实例，支持状态更新、保活恢复和注销；停用、卸载及切库时自动清理，提供器异常不影响其他上下文。
7
+ - 页面操作继续由作者通过已有 MCP 注册能力提供，通知等已发布能力保持可用。
8
+
9
+ ## 0.28.0
10
+
11
+ - 新增 `context.notifications.send`：发送应用内通知、独立窗口通知，或默认按来源窗口焦点自动分流。
12
+ - 支持标题、正文、语义、常驻与最多两个操作按钮；来源显示插件名称。
13
+ - 返回 `Disposable` 撤销单条通知，停用、激活失败及切库时自动回收，旧按钮回调失效。
14
+
15
+ ## 0.27.0
16
+
17
+ - 新增通用 `context.ai.requestCapability(name)`，开放应用全部 12 项大模型功能分配。每项声明 `ai:<能力名>` 并由用户独立授权，返回 `chat/stream` 客户端，不需要另配模型或声明自定义 AI 功能。
18
+ - 闪卡 AI 制作使用此通用入口，权限为 `ai:flashcardGeneration`；不再要求传入 `feature`。支持在 user 消息中附带图片，图片不进入用量审计。
19
+ - 宿主模型仍经插件额度、并发限制与用量审计执行；撤销闪卡 AI 权限会取消在途请求，应用未配模型或分配变化时明确失败。
20
+ - 插件自定义 AI 的原有声明、授权与模型分配保持独立；闪卡读写权限和 `contentRef` 来源校验沿用 0.26.0。
21
+
22
+ ## 0.26.0
23
+
24
+ - 新增 `context.flashcards`：查询与创建卡组、创建闪卡、宿主制卡窗口、AI 草稿与自动保存；直接读写经 `flashcards:read/write` 授权。
25
+ - 插件 AI 制卡使用声明的 AI 功能及用户分配的模型，受插件授权、额度与用量审计约束。宿主制卡窗口要求用户操作，保存由用户确认。
26
+ - 现有正文引用使用不透明 `contentRef`，校验正文身份及读取权限；停用、切库取消在途任务，自动保存保留已提交结果。
27
+
28
+ ## 0.25.0
29
+
30
+ - 新增独立本机后台：格式 2 插件声明 `backend`，通过 `@tau/plugins/backend` 的 `defineBackend` 注册方法，界面经 `context.backend.call/subscribe` 调用与订阅。支持按需或随作用域启动、取消、受监督的外部工具与本机执行授权；构建脚本生成双入口及完整性摘要，详见 BACKEND.md。普通插件继续使用格式 1。
31
+ - 新增业务数据只读接口：`context.data` 读取卡片、文章、项目文档、待办与日程，`context.content.read` 按 `contentRef` 读取正文（Markdown 或编辑器节点）。查询按时间范围、标签筛选并分页。
32
+ - 新增权限：manifest `permissions` 声明可申请的上限（`cards:read`、`articles:read`、`documents:read`、`todos:read`、`calendar:read`），首次调用时由用户选择「仅这次」「始终允许」或「拒绝」。未获准时抛出 `PluginPermissionError`；`context.permissions` 可查询状态与一次申请多项。
33
+ - 新增 `context.events.on`：卡片、文章、项目文档的创建 / 更新 / 删除，待办与日程的集合级变化，以及同步下载后的 `workspace.reset`。事件不携带数据，需要对应读取权限才会送达。
34
+ - 新增写入：卡片与文章的新建、修改、删除，项目文档的标题与标签，待办与日程的新建、修改、完成、删除；`context.content.edit` 追加、插入或替换正文。修改与删除需传入读取时的 `revision`，数据已被别处修改时抛出 `PluginConflictError`。插件删除的内容用户可在 7 天内恢复。
35
+ - 权限词表增加 `*:write` 与 `*:delete`；事件增加 `origin`，可识别由插件写入的变化。
36
+ - 新增 `context.app.pick` 与 `context.app.open`：用 Tau 的搜索窗口让用户选择卡片、文章、项目文档、日记、白板、待办或日程，并打开它们的页面。用户亲手选择即可引用，不需要数据权限；只能在用户操作后调用。
37
+ - 新增正文组件 `ContentEditor` 与 `ContentPreview`：在插件页面嵌入与卡片详情相同的编辑器（协作、已安装的编辑器扩展、文档待办都生效），或只读显示正文开头几块。按所属内容的读取 / 写入权限放行，未授权时由用户点击「允许访问」后再询问。
38
+ - 新增 `context.app.run`：把卡片、文章、项目文档的正文交给 Tau 导出（Markdown、图片、PDF、EPUB）、全屏演示或发起协作共享，界面与卡片详情中的相同。只能在用户操作后调用，不需要数据权限。
39
+ - 新增 `context.entities`：插件创建自己的内容（如周记），每项带一份正文，用 `ContentEditor` 编辑或 `context.content` 读写，不需要业务数据权限。卸载插件后内容保留 7 天，期间重新安装可找回。插件内容可被全局搜索与 AI 检索找到，点击结果按 `registerKind` 声明的 `open` 打开插件页面；`ContentEditor` 增加 `at`，打开到命中处。声明 `mentionable` 的类型可在正文中用 @ 引用；`context.entities.backlinks` 列出引用了它的卡片、文章与项目文档（只含已获准读取的类型）。
40
+ - `context.entities.registerKind` 增加 `icon`，与侧边栏图标同一写法；新增 `PluginIcon` / `PluginIconProps`，`PluginSidebarIcon` / `PluginSidebarIconProps` 保留为同义名。插件内容在搜索、@ 面板、正文中的引用、脉络与漫步里按声明的类型名与图标显示，插件停用或卸载后的 7 天内同样如此。
41
+ - 新增 `context.entities.delete`：删除插件自己的内容及正文，用户可在插件详情页 7 天内恢复，恢复后 ID 与正文不变。
42
+ - `context.storage` 的数据改为保存在笔记库里，随云同步；升级后首次启动自动迁移本机已有的数据，单个值不超过 1 MB。
43
+ - 权限约束的是 SDK 接口；插件仍与应用运行在同一环境，不提供安全隔离。
44
+
45
+ ## 0.24.0
46
+
47
+ - 移除 `PluginServices.typst`：宿主不再内置 Typst 编译服务（原生二进制约 37 MB/平台随之从安装包移除）。Typst 排版由 `tau.typst` 插件 v0.2.0 以 WebAssembly 引擎在渲染进程本地完成，首次使用联网下载编译组件与字体并长期缓存。
48
+ - 旧版 `tau.typst` 插件（0.1.x）在新宿主上不再能实时编译，已保存的排版缓存与源码照常显示。
49
+
50
+ ## 0.23.1
51
+
52
+ - 修正 FFprobe 升级说明中已删除类型的名称为 `MediaInfo`，接口与 0.23.0 相同。
53
+
54
+ ## 0.23.0
55
+
56
+ - 移除 `PluginServices.ffmpeg.probe` 及其媒体信息类型，宿主不再随包分发 FFprobe；`ffmpeg.run` 保留。
57
+ - 视频页面标题、时长和格式查询继续使用 `services.videoExtractor.probe`，该接口由宿主视频解析器提供，不是本地媒体探测接口的替代品。
58
+ - 作者模板升级到本版 SDK，补齐博客发布、独立站点数据接入与升级说明，并修正服务文档中的已移除接口。
59
+
60
+ ## 0.22.0
61
+
62
+ - 新增 `context.video.register`，接入视频来源（视频网站、自建服务器等）：插件识别链接、解析标题与清晰度，返回播放源描述（单文件、音视频分离或交给宿主解析器），下载、缓存与播放由宿主完成。
63
+ - 视频账号与代理配置通过 `settings.register({ target: "video" })` 注册，接收每个插件一份的 `videoConfig`。
64
+ - 新增 `services.videoExtractor.probe`，查询视频页面的标题与可下载格式；新增插件分类 `video`（在线视频）。
65
+
66
+ ## 0.21.0
67
+
68
+ - 新增 context.publish 发布提供方、publishConfig 配置表单和文件式／快照式提交协议，本地导出仍由宿主提供。
69
+ - 新增受控 Git 快照发布与缓存目录选择服务，插件不获得任意命令或宿主文件访问。
70
+ - 插件分类新增博客发布。
71
+
72
+ ## 0.20.0
73
+
74
+ - manifest 支持 `categories`（插件中心分类）与 `keywords`（目录搜索），门户上传严格校验，客户端忽略未知值。
75
+ - 博客模板包（`template` 分支）同样支持分类与关键词，只含静态站点产物，不能同时声明代码插件入口。
76
+ - publish-data：站点级数据（`settings`、`collections`、`cardTagTree`、`projectTrees`）改为只在清单中出现；内容文件新增 `links`，只含本文用到且已发布的站内链接目标。
77
+ - publish-client：`readData` 随正文带回清单的 `settings`；检索引擎按索引缓存，不再每次查询重建。
78
+
79
+ ## 0.19.0
80
+
81
+ - 补齐 publish-data 类型、publish-client 纯数据客户端及 publish-artifacts 协议校验/定义求值入口；数据与产物声明不连带载入 Editor/React/UI 类型。
82
+ - 普通 SDK/UI 根入口保持类型与 Tau 注入约定；通用源码组件契约与实现由 Editor 公开入口维护，既有源码宿主适配只负责接线。
83
+ - 保留 master 0.18.0 的图片插件及全部已插件化接口。
84
+
85
+ ## 0.18.0
86
+
87
+ - 新增 `context.images.register`，按账号配置与模型创建图片生成或编辑实例，返回图片字节和实际 MIME。
88
+ - 图片配置视图通过 `settings.register({ target: "images" })` 注册，接收当前账号的 `imageConfig`；保存按实例隔离，不使用共享凭据。
89
+ - 图片插件在主窗口渲染进程执行，跨窗口调用、上传、取消和停用共用任务生命周期；保留 TTS 与上传等既有接口。
90
+
91
+ ## 0.17.0
92
+
93
+ - 新增通用行内源码 API：useInlineSource、insertInlineSource 和 InlineSourceBoundary，复用宿主 Slate 实例与浏览器行内边界处理。
94
+ - 行内源码更新和删除遵守只读、卸载/停驻、目标替换及编辑器提交守卫；不修改 useSourceBlock、EditorKit 或已有节点格式。
95
+ - 保留已有 TTS、上传、聊天、独立服务入口与 TikZ 服务移除边界；客户端版本不变。
96
+
97
+ ## 0.16.0
98
+
99
+ - 新增独立 `usePluginServices()`，由插件渲染运行时提供已有编译与转换服务；博客及无服务的宿主返回 undefined。
100
+ - 服务按当前窗口和工作区绑定取消与失效保护，静态编辑器组件无需调用 activate；原有 context.services 保持不变。
101
+ - 不修改 useSourceBlock、EditorKit、文档节点协议或编译接口；保留 TTS、上传、聊天工具展示及 TikZ 服务删除边界。
102
+
103
+ ## 0.15.0
104
+
105
+ - 新增 `context.chat.registerToolRenderer`，按本插件 MCP ID 与原始工具名异步登记 React 工具渲染器，激活成功后发布，停用、重载或切库时回收。
106
+ - 本地工具支持 `{ content, render: { version, data } }`，展示数据沿 pi 会话保存并支持历史回放；保留默认展示、宿主审批及失败/取消语义。
107
+ - 渲染器仅匹配绑定工具，组件接收独立执行快照；修复异常订阅中断回收及审批/重试恢复状态的终态收敛。
108
+ - 保留 0.13.0 的 TTS、资源上传接口及 0.14.0 移除 TikZ 服务的边界；UI 包无需升级。
109
+
110
+ ## 0.14.0
111
+
112
+ - 移除 `PluginServices.tikz` 和 `context.services.tikz.compile`。TikZ 编译、字体与文档块由独立插件 tau.tikz 提供，宿主不再保留编译实现或转发入口。
113
+ - 插件作者如需 TikZ 绘图，应由自己的插件携带实现；其他宿主编译与转换服务保持不变。
114
+ - 保留 0.13.0 的 TTS、资源上传及其生命周期接口。
package/DEVELOPMENT.md CHANGED
@@ -1,173 +1,173 @@
1
- # Tau 插件开发指南
2
-
3
- 用 TypeScript 和 React 为 Tau 桌面端开发插件。模板自带一个可运行的计数器，演示命令、页面、侧边栏入口、设置和数据保存，可以在它的基础上改出自己的插件。
4
-
5
- ## 准备
6
-
7
- - Node.js 22 或更高版本
8
- - pnpm 11.9.0
9
- - Tau 桌面客户端 0.59.0 或更高版本
10
-
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
-
13
- ## 跑通示例
14
-
15
- 在 GitHub 点击 **Use this template** 创建自己的仓库，克隆后在项目目录执行：
16
-
17
- ```sh
18
- pnpm install
19
- pnpm build
20
- pnpm install:local
21
- ```
22
-
23
- 打开 Tau 的插件管理，点击「刷新列表」，启用「计数器示例」。然后点击侧边栏「日常」分组下的「计数器」，或按 Ctrl+K 执行「打开计数器」，点「增加并保存」。重启客户端后再打开，计数仍然保留。
24
-
25
- ## 改成自己的插件
26
-
27
- 1. 修改 `manifest.json` 的 `id`、`name`、`version`、`description`。`id` 用你自己的唯一名称，例如 `yourname.counter`。
28
- - `categories` 决定插件在插件中心出现在哪些分类下，可多选，也可不填：`sync` 同步、`upload` 资源上传、`editor` 编辑器、`whiteboard` 白板、`blog-template` 博客模板、`blog-publish` 博客发布、`ai` AI（Skill、MCP、聊天工具渲染、AI 功能、图片）、`voice` 语音、`video` 在线视频、`page` 页面（页面与侧边栏入口）。只提供命令或设置的插件可以不填。
29
- - `keywords` 最多 5 个、每个不超过 20 字，只用于插件中心搜索，例如 S3 插件可写 `MinIO`、`R2`。
30
- 2. 修改 `package.json` 的项目名称和版本。
31
- 3. 在 `src/index.tsx` 中实现功能，在 `src/styles.css` 中编写样式。
32
- 4. 把 `README.md` 改成给用户看的介绍和使用步骤；需要版本记录时再加 `CHANGELOG.md`。
33
- 5. 执行 `pnpm build`，按下文的方法安装到 Tau 中测试。
34
-
35
- | 文件 | 用途 |
36
- | --------------------------------- | ---------------------------------------------------- |
37
- | `manifest.json` | 插件身份、版本和最低客户端版本 |
38
- | `README.md` / `CHANGELOG.md` | 随插件包发布，显示在插件详情的「说明」和「更新日志」 |
39
- | `src/index.tsx` | 插件入口，以及示例页面、设置与命令 |
40
- | `src/styles.css` | 插件样式 |
41
- | `src/CounterIcon.tsx` | 侧边栏 SVG 图标示例，使用 currentColor 跟随主题 |
42
- | `API.md` | 命令、页面、侧边栏、设置、存储、网络等接口 |
43
- | `EDITOR.md` | 在文档中添加自定义块、源码预览块和插件 Skill |
44
- | `AI.md` | AI 功能声明、用户模型分配、流式对话和统一用量审计 |
45
- | `MCP.md` | 注册 MCP、聊天工具渲染，复用工具开关与服务器管理 |
46
- | `BACKEND.md` | 显式声明本机后台、启动策略与独立产物构建 |
47
- | `FLASHCARDS.md` | 闪卡读写权限、宿主制卡窗口、插件 AI 与正文来源引用 |
48
- | `NOTIFICATIONS.md` | 应用内、独立窗口通知、自动分流与生命周期清理 |
49
- | `WHITEBOARD.md` | 静态白板扩展、工具与发布边界 |
50
- | `SYNC.md` | 同步存储提供方、配置视图与取消 |
51
- | `UPLOAD.md` | 图片与附件上传、上传提供方与配置 |
52
- | `TTS.md` | 语音合成、音色复刻与多账号配置 |
53
- | `IMAGES.md` | 图片生成、参考图编辑与插件账号配置视图 |
54
- | `VIDEO.md` | 视频来源的链接解析、播放源与账号配置视图 |
55
- | `PUBLISH.md` | 博客发布提供方、文件上传与 Git 快照 |
56
- | `PUBLISH-DATA.md` | 独立站点读取发布数据与公开子入口的构建边界 |
57
- | `SERVICES.md` | Tailwind、Markdown、FFmpeg 编译转换服务 |
58
- | `AGENTS.md` | 给 AI 编程助手的项目指引 |
59
- | `build.mjs` / `install-local.mjs` | 打包与本地安装脚本，日常开发通常不需要修改 |
60
-
61
- 插件详情页的名称、简介和版本取自 `manifest.json`，介绍取自 `README.md`，无需在网站上另外填写。`API.md`、`AGENTS.md` 等开发文档不会打进插件包。
62
-
63
- ## 升级 SDK 与同步旧模板
64
-
65
- GitHub 模板创建的仓库不会自动跟随模板更新。已有项目先提交或备份自己的改动，再按需同步 [上游模板](https://github.com/LastKnightCoder/tau-plugin-template) 的构建脚本、开发文档和 `.github/workflows/release.yml`，保留自己的插件 ID、入口、用户说明与版本记录。
66
-
67
- 先在 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` 中增加新 SDK 的精确例外 `@xiongtao.xt/tau-plugins@0.29.0`，暂时保留旧锁文件所需的已核实例外，再更新依赖及锁文件：
68
-
69
- ```sh
70
- pnpm add @tau/plugins@npm:@xiongtao.xt/tau-plugins@0.29.0 --save-exact
71
- pnpm install --frozen-lockfile
72
- pnpm build
73
- ```
74
-
75
- 成功后移除已不再使用的旧版例外，再运行一次 `pnpm install --frozen-lockfile`，提交 `package.json`、`pnpm-lock.yaml` 和 `pnpm-workspace.yaml`。先移除旧版例外会使 pnpm 在读取旧锁文件时拒绝升级。发布等待例外只针对已核实的 SDK/UI 版本，不关闭全部依赖的供应链策略；保留 `allowBuilds.esbuild: true`。React 继续使用模板锁定的版本，避免和宿主的共享实例不兼容。
76
-
77
- 从旧 SDK 升级时，重点核对：
78
-
79
- | 版本 | 变化与对应文档 |
80
- | ------------- | ------------------------------------------------------------------------------------------------------ |
81
- | 0.17.0 | 行内源码接口，见 EDITOR.md |
82
- | 0.18.0 | 图片生成与编辑提供方，见 IMAGES.md |
83
- | 0.19.0–0.20.0 | 发布数据子入口、站点级数据归清单、分类与关键词，见 PUBLISH-DATA.md 与 API.md |
84
- | 0.21.0 | 博客发布提供方、配置与 Git 快照服务，见 PUBLISH.md |
85
- | 0.22.0 | 视频提供方与视频页面信息查询，见 VIDEO.md |
86
- | 0.23.0 | 删除 `ffmpeg.probe` 与 `MediaInfo`；`ffmpeg.run` 保留，见 SERVICES.md |
87
- | 0.24.0 | 删除 `services.typst`；Typst 编译由独立插件实现，见 SERVICES.md |
88
- | 0.25.0 | 数据读写与权限、正文组件、插件实体、宿主动作、存储随库同步，见 API.md；本机后台双入口见 BACKEND.md |
89
- | 0.26.0 | 闪卡创建、读写授权、插件 AI 制卡与 contentRef 来源引用，见 FLASHCARDS.md |
90
- | 0.27.0 | 通用 requestCapability 开放全部内置大模型功能分配，分别以 ai:<能力名> 授权；闪卡复用同一机制，见 AI.md |
91
- | 0.28.0 | 通知发送、应用内或独立窗口展示、焦点自动分流与生命周期清理，见 NOTIFICATIONS.md |
92
- | 0.29.0 | 页面通过 pageContext.register 提供任意 JSON 上下文，现有 get_current_context 读取，见 API.md |
93
-
94
- 更早版本的完整变更见已安装包的 `node_modules/@tau/plugins/CHANGELOG.md`。需要本地媒体元数据时自行实现，不能把视频页面解析当作本地文件探测。SDK 根入口、白板/同步契约、UI 和 React 由 Tau 提供，保持模板的 external 配置；普通第三方库由构建打入 ZIP。独立站点数据子入口的用途另见 PUBLISH-DATA.md。
95
-
96
- 构建通过后，在对应客户端验证启用、功能执行、保存、停用与重启；涉及静态编辑器或白板扩展时也验证重启后的贡献，以及发布内容的回退。构建成功只证明类型和打包通过。
97
-
98
- ## 打包与安装
99
-
100
- `pnpm build` 先检查类型，再生成 `dist/<id>-<version>.zip`。这个 ZIP 就是完整的插件包，分享时不需要附带源码或 node_modules。
101
-
102
- **开发调试首次安装**：`pnpm install:local` 把 ZIP 解压到 `~/.editor/plugins/<id>/`。正式用户从插件中心安装；作者也可以手动解压调试，最终结构应为：
103
-
104
- ```text
105
- ~/.editor/plugins/yourname.counter/
106
- manifest.json
107
- main.js
108
- main.css # 使用 CSS 时生成
109
- ```
110
-
111
- **更新**：提高 `manifest.json` 的 `version` 并重新构建，正式版本提交插件中心审核后由用户更新；开发版客户端可从插件页的 ZIP 入口调试。新版本在下次完全退出并重新启动后生效，生效前可以「取消待更新」；新版本启用失败时可以「恢复上一版」。恢复只换回代码，不回退已保存的数据，所以存储结构变化时要让新旧版本都能读懂。
112
-
113
- `pnpm install:local` 只用于首次安装，目标目录已存在时会拒绝覆盖。插件 ID 不变，已保存的数据就会保留；改了 ID 会被当作另一个插件。
114
-
115
- ## 写更新日志
116
-
117
- `CHANGELOG.md` 显示在插件详情的「更新日志」里，发布时也会作为 GitHub Release 的说明，读者是使用插件的人，不是开发者。
118
-
119
- - 每个版本以 `## 1.2.0` 开头，下面逐条写；发布时取与 tag 版本相同的小节，找不到时才用 GitHub 自动生成的提交列表。
120
- - 写用户能感知的变化：新增了什么能力、修好了什么问题、升级后要注意什么。用界面上的叫法，比如「设置 → 同步」。
121
- - 不写 SDK 版本、构建方式、仓库迁移、测试或内部字段。确实没有可感知的变化，就写「维护更新，使用上没有变化」。
122
-
123
- ```markdown
124
- ## 1.2.0
125
-
126
- - 书架可以按「有笔记」筛选了。
127
- - 修复同步中途断网后，部分划线不显示的问题。
128
- ```
129
-
130
- ## 自动发布到 GitHub Release
131
-
132
- 模板内置 `.github/workflows/release.yml`。将版本 tag 推送到 GitHub 后，Actions 会冻结安装 pnpm 依赖、运行项目的 test 脚本（若已定义）、执行构建，再把 `dist/<id>-<version>.zip` 上传到对应 Release。
133
-
134
- 先同步修改 `manifest.json` 和 `package.json` 的版本并提交，再打 tag：
135
-
136
- ```sh
137
- git add manifest.json package.json
138
- git commit -m "chore: release 1.1.0"
139
- git tag v1.1.0
140
- git push origin HEAD
141
- git push origin v1.1.0
142
- ```
143
-
144
- tag 支持 `v1.1.0` 或 `1.1.0`，必须与两个文件的版本一致，否则发布失败。`v1.1.0-beta.1` 等预发布版本会自动标为 Pre-release。只在本机打 tag 不触发，必须推送到 GitHub。
145
-
146
- 无需配置额外密钥，工作流使用仓库自带的 GITHUB_TOKEN。仓库需启用 Actions，并允许工作流申请 contents:write 权限。发布结果和失败日志在 Actions 页面查看；修复临时错误后可重新运行失败任务，已有 Release 会更新同名 ZIP。代码修复应提高版本并发布新 tag，不移动已发布的版本 tag。
147
-
148
- Release 的说明取自 `CHANGELOG.md` 中对应版本的小节。Release 发布后，工作流会把同一个 ZIP 提交到插件中心：用 GitHub Actions 的短期身份令牌证明发布来自哪个仓库，不需要配置任何密钥。
149
-
150
- - **首次发布**仍需在 [插件中心](https://plugins.taunote.app) 网页上传并提交一次，用来把插件 ID 绑定到你的仓库。未绑定时这一步只给出提醒，不让工作流失败。
151
- - **之后每次推送 tag**，新版本自动进入审核队列，不用再打开网页；插件 ID 只接受来自已绑定仓库的提交，fork 无法冒充。
152
- - 预发布版本（如 `v1.1.0-beta.1`）只发 GitHub Release，不提交插件中心。
153
- - 同一 tag 重跑是安全的；同一版本号换了内容会被拒绝，需要提高版本号。
154
-
155
- 从旧模板创建的仓库不会自动获得新文件，需要同步该 workflow（包括 `id-token: write` 权限）。此流程不发布 npm 包。
156
-
157
- ## 常用命令
158
-
159
- | 命令 | 用途 |
160
- | -------------------- | ---------------------- |
161
- | `pnpm check` | 检查 TypeScript 类型 |
162
- | `pnpm build` | 检查类型并生成 ZIP |
163
- | `pnpm install:local` | 首次安装最近构建的 ZIP |
164
-
165
- ## 排错
166
-
167
- - **列表里没有插件**：点「刷新列表」，确认解压后没有多套一层目录，再看插件管理里的错误提示。
168
- - **提示目标已存在**：提高插件版本后，在开发版客户端使用 ZIP 更新；正式用户使用插件中心更新。
169
- - **修改没有生效**：重新构建并安装，然后刷新列表并启用。
170
- - **启用失败**：查看错误提示，检查 `activate` 是否抛出异常；客户端提示需要重启时先重启再启用。
171
- - **类型检查通过但功能异常**：类型检查不能代替实际测试，至少在 Tau 中试一遍启用、执行命令、保存数据、停用和重启。
172
-
173
- 本模板采用 [MIT 许可](LICENSE)。
1
+ # Tau 插件开发指南
2
+
3
+ 用 TypeScript 和 React 为 Tau 桌面端开发插件。模板自带一个可运行的计数器，演示命令、页面、侧边栏入口、设置和数据保存，可以在它的基础上改出自己的插件。
4
+
5
+ ## 准备
6
+
7
+ - Node.js 22 或更高版本
8
+ - pnpm 11.9.0
9
+ - Tau 桌面客户端 0.59.0 或更高版本
10
+
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
+
13
+ ## 跑通示例
14
+
15
+ 在 GitHub 点击 **Use this template** 创建自己的仓库，克隆后在项目目录执行：
16
+
17
+ ```sh
18
+ pnpm install
19
+ pnpm build
20
+ pnpm install:local
21
+ ```
22
+
23
+ 打开 Tau 的插件管理，点击「刷新列表」，启用「计数器示例」。然后点击侧边栏「日常」分组下的「计数器」，或按 Ctrl+K 执行「打开计数器」，点「增加并保存」。重启客户端后再打开，计数仍然保留。
24
+
25
+ ## 改成自己的插件
26
+
27
+ 1. 修改 `manifest.json` 的 `id`、`name`、`version`、`description`。`id` 用你自己的唯一名称，例如 `yourname.counter`。
28
+ - `categories` 决定插件在插件中心出现在哪些分类下，可多选，也可不填：`sync` 同步、`upload` 资源上传、`editor` 编辑器、`whiteboard` 白板、`blog-template` 博客模板、`blog-publish` 博客发布、`ai` AI（Skill、MCP、聊天工具渲染、AI 功能、图片）、`voice` 语音、`video` 在线视频、`page` 页面（页面与侧边栏入口）。只提供命令或设置的插件可以不填。
29
+ - `keywords` 最多 5 个、每个不超过 20 字，只用于插件中心搜索，例如 S3 插件可写 `MinIO`、`R2`。
30
+ 2. 修改 `package.json` 的项目名称和版本。
31
+ 3. 在 `src/index.tsx` 中实现功能，在 `src/styles.css` 中编写样式。
32
+ 4. 把 `README.md` 改成给用户看的介绍和使用步骤；需要版本记录时再加 `CHANGELOG.md`。
33
+ 5. 执行 `pnpm build`，按下文的方法安装到 Tau 中测试。
34
+
35
+ | 文件 | 用途 |
36
+ | --------------------------------- | ---------------------------------------------------- |
37
+ | `manifest.json` | 插件身份、版本和最低客户端版本 |
38
+ | `README.md` / `CHANGELOG.md` | 随插件包发布，显示在插件详情的「说明」和「更新日志」 |
39
+ | `src/index.tsx` | 插件入口，以及示例页面、设置与命令 |
40
+ | `src/styles.css` | 插件样式 |
41
+ | `src/CounterIcon.tsx` | 侧边栏 SVG 图标示例，使用 currentColor 跟随主题 |
42
+ | `API.md` | 命令、页面、侧边栏、设置、存储、网络等接口 |
43
+ | `EDITOR.md` | 在文档中添加自定义块、源码预览块和插件 Skill |
44
+ | `AI.md` | AI 功能声明、用户模型分配、流式对话和统一用量审计 |
45
+ | `MCP.md` | 注册 MCP、聊天工具渲染，复用工具开关与服务器管理 |
46
+ | `BACKEND.md` | 显式声明本机后台、启动策略与独立产物构建 |
47
+ | `FLASHCARDS.md` | 闪卡读写权限、宿主制卡窗口、插件 AI 与正文来源引用 |
48
+ | `NOTIFICATIONS.md` | 应用内、独立窗口通知、自动分流与生命周期清理 |
49
+ | `WHITEBOARD.md` | 静态白板扩展、工具与发布边界 |
50
+ | `SYNC.md` | 同步存储提供方、配置视图与取消 |
51
+ | `UPLOAD.md` | 图片与附件上传、上传提供方与配置 |
52
+ | `TTS.md` | 语音合成、音色复刻与多账号配置 |
53
+ | `IMAGES.md` | 图片生成、参考图编辑与插件账号配置视图 |
54
+ | `VIDEO.md` | 视频来源的链接解析、播放源与账号配置视图 |
55
+ | `PUBLISH.md` | 博客发布提供方、文件上传与 Git 快照 |
56
+ | `PUBLISH-DATA.md` | 独立站点读取发布数据与公开子入口的构建边界 |
57
+ | `SERVICES.md` | Tailwind、Markdown、FFmpeg 编译转换服务 |
58
+ | `AGENTS.md` | 给 AI 编程助手的项目指引 |
59
+ | `build.mjs` / `install-local.mjs` | 打包与本地安装脚本，日常开发通常不需要修改 |
60
+
61
+ 插件详情页的名称、简介和版本取自 `manifest.json`，介绍取自 `README.md`，无需在网站上另外填写。`API.md`、`AGENTS.md` 等开发文档不会打进插件包。
62
+
63
+ ## 升级 SDK 与同步旧模板
64
+
65
+ GitHub 模板创建的仓库不会自动跟随模板更新。已有项目先提交或备份自己的改动，再按需同步 [上游模板](https://github.com/LastKnightCoder/tau-plugin-template) 的构建脚本、开发文档和 `.github/workflows/release.yml`，保留自己的插件 ID、入口、用户说明与版本记录。
66
+
67
+ 先在 `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude` 中增加新 SDK 的精确例外 `@xiongtao.xt/tau-plugins@0.29.0`，暂时保留旧锁文件所需的已核实例外，再更新依赖及锁文件：
68
+
69
+ ```sh
70
+ pnpm add @tau/plugins@npm:@xiongtao.xt/tau-plugins@0.29.0 --save-exact
71
+ pnpm install --frozen-lockfile
72
+ pnpm build
73
+ ```
74
+
75
+ 成功后移除已不再使用的旧版例外，再运行一次 `pnpm install --frozen-lockfile`，提交 `package.json`、`pnpm-lock.yaml` 和 `pnpm-workspace.yaml`。先移除旧版例外会使 pnpm 在读取旧锁文件时拒绝升级。发布等待例外只针对已核实的 SDK/UI 版本，不关闭全部依赖的供应链策略；保留 `allowBuilds.esbuild: true`。React 继续使用模板锁定的版本，避免和宿主的共享实例不兼容。
76
+
77
+ 从旧 SDK 升级时，重点核对：
78
+
79
+ | 版本 | 变化与对应文档 |
80
+ | ------------- | ------------------------------------------------------------------------------------------------------ |
81
+ | 0.17.0 | 行内源码接口，见 EDITOR.md |
82
+ | 0.18.0 | 图片生成与编辑提供方，见 IMAGES.md |
83
+ | 0.19.0–0.20.0 | 发布数据子入口、站点级数据归清单、分类与关键词，见 PUBLISH-DATA.md 与 API.md |
84
+ | 0.21.0 | 博客发布提供方、配置与 Git 快照服务，见 PUBLISH.md |
85
+ | 0.22.0 | 视频提供方与视频页面信息查询，见 VIDEO.md |
86
+ | 0.23.0 | 删除 `ffmpeg.probe` 与 `MediaInfo`；`ffmpeg.run` 保留，见 SERVICES.md |
87
+ | 0.24.0 | 删除 `services.typst`；Typst 编译由独立插件实现，见 SERVICES.md |
88
+ | 0.25.0 | 数据读写与权限、正文组件、插件实体、宿主动作、存储随库同步，见 API.md；本机后台双入口见 BACKEND.md |
89
+ | 0.26.0 | 闪卡创建、读写授权、插件 AI 制卡与 contentRef 来源引用，见 FLASHCARDS.md |
90
+ | 0.27.0 | 通用 requestCapability 开放全部内置大模型功能分配，分别以 ai:<能力名> 授权；闪卡复用同一机制，见 AI.md |
91
+ | 0.28.0 | 通知发送、应用内或独立窗口展示、焦点自动分流与生命周期清理，见 NOTIFICATIONS.md |
92
+ | 0.29.0 | 页面通过 pageContext.register 提供任意 JSON 上下文，现有 get_current_context 读取，见 API.md |
93
+
94
+ 更早版本的完整变更见已安装包的 `node_modules/@tau/plugins/CHANGELOG.md`。需要本地媒体元数据时自行实现，不能把视频页面解析当作本地文件探测。SDK 根入口、白板/同步契约、UI 和 React 由 Tau 提供，保持模板的 external 配置；普通第三方库由构建打入 ZIP。独立站点数据子入口的用途另见 PUBLISH-DATA.md。
95
+
96
+ 构建通过后，在对应客户端验证启用、功能执行、保存、停用与重启；涉及静态编辑器或白板扩展时也验证重启后的贡献，以及发布内容的回退。构建成功只证明类型和打包通过。
97
+
98
+ ## 打包与安装
99
+
100
+ `pnpm build` 先检查类型，再生成 `dist/<id>-<version>.zip`。这个 ZIP 就是完整的插件包，分享时不需要附带源码或 node_modules。
101
+
102
+ **开发调试首次安装**：`pnpm install:local` 把 ZIP 解压到 `~/.editor/plugins/<id>/`。正式用户从插件中心安装；作者也可以手动解压调试，最终结构应为：
103
+
104
+ ```text
105
+ ~/.editor/plugins/yourname.counter/
106
+ manifest.json
107
+ main.js
108
+ main.css # 使用 CSS 时生成
109
+ ```
110
+
111
+ **更新**：提高 `manifest.json` 的 `version` 并重新构建，正式版本提交插件中心审核后由用户更新；开发版客户端可从插件页的 ZIP 入口调试。新版本在下次完全退出并重新启动后生效，生效前可以「取消待更新」；新版本启用失败时可以「恢复上一版」。恢复只换回代码，不回退已保存的数据，所以存储结构变化时要让新旧版本都能读懂。
112
+
113
+ `pnpm install:local` 只用于首次安装，目标目录已存在时会拒绝覆盖。插件 ID 不变，已保存的数据就会保留；改了 ID 会被当作另一个插件。
114
+
115
+ ## 写更新日志
116
+
117
+ `CHANGELOG.md` 显示在插件详情的「更新日志」里，发布时也会作为 GitHub Release 的说明，读者是使用插件的人，不是开发者。
118
+
119
+ - 每个版本以 `## 1.2.0` 开头，下面逐条写；发布时取与 tag 版本相同的小节，找不到时才用 GitHub 自动生成的提交列表。
120
+ - 写用户能感知的变化：新增了什么能力、修好了什么问题、升级后要注意什么。用界面上的叫法，比如「设置 → 同步」。
121
+ - 不写 SDK 版本、构建方式、仓库迁移、测试或内部字段。确实没有可感知的变化，就写「维护更新，使用上没有变化」。
122
+
123
+ ```markdown
124
+ ## 1.2.0
125
+
126
+ - 书架可以按「有笔记」筛选了。
127
+ - 修复同步中途断网后，部分划线不显示的问题。
128
+ ```
129
+
130
+ ## 自动发布到 GitHub Release
131
+
132
+ 模板内置 `.github/workflows/release.yml`。将版本 tag 推送到 GitHub 后，Actions 会冻结安装 pnpm 依赖、运行项目的 test 脚本（若已定义）、执行构建，再把 `dist/<id>-<version>.zip` 上传到对应 Release。
133
+
134
+ 先同步修改 `manifest.json` 和 `package.json` 的版本并提交，再打 tag：
135
+
136
+ ```sh
137
+ git add manifest.json package.json
138
+ git commit -m "chore: release 1.1.0"
139
+ git tag v1.1.0
140
+ git push origin HEAD
141
+ git push origin v1.1.0
142
+ ```
143
+
144
+ tag 支持 `v1.1.0` 或 `1.1.0`，必须与两个文件的版本一致，否则发布失败。`v1.1.0-beta.1` 等预发布版本会自动标为 Pre-release。只在本机打 tag 不触发，必须推送到 GitHub。
145
+
146
+ 无需配置额外密钥，工作流使用仓库自带的 GITHUB_TOKEN。仓库需启用 Actions，并允许工作流申请 contents:write 权限。发布结果和失败日志在 Actions 页面查看；修复临时错误后可重新运行失败任务，已有 Release 会更新同名 ZIP。代码修复应提高版本并发布新 tag，不移动已发布的版本 tag。
147
+
148
+ Release 的说明取自 `CHANGELOG.md` 中对应版本的小节。Release 发布后，工作流会把同一个 ZIP 提交到插件中心：用 GitHub Actions 的短期身份令牌证明发布来自哪个仓库，不需要配置任何密钥。
149
+
150
+ - **首次发布**仍需在 [插件中心](https://plugins.taunote.app) 网页上传并提交一次，用来把插件 ID 绑定到你的仓库。未绑定时这一步只给出提醒，不让工作流失败。
151
+ - **之后每次推送 tag**，新版本自动进入审核队列，不用再打开网页；插件 ID 只接受来自已绑定仓库的提交，fork 无法冒充。
152
+ - 预发布版本（如 `v1.1.0-beta.1`）只发 GitHub Release，不提交插件中心。
153
+ - 同一 tag 重跑是安全的；同一版本号换了内容会被拒绝，需要提高版本号。
154
+
155
+ 从旧模板创建的仓库不会自动获得新文件，需要同步该 workflow（包括 `id-token: write` 权限）。此流程不发布 npm 包。
156
+
157
+ ## 常用命令
158
+
159
+ | 命令 | 用途 |
160
+ | -------------------- | ---------------------- |
161
+ | `pnpm check` | 检查 TypeScript 类型 |
162
+ | `pnpm build` | 检查类型并生成 ZIP |
163
+ | `pnpm install:local` | 首次安装最近构建的 ZIP |
164
+
165
+ ## 排错
166
+
167
+ - **列表里没有插件**：点「刷新列表」，确认解压后没有多套一层目录，再看插件管理里的错误提示。
168
+ - **提示目标已存在**：提高插件版本后，在开发版客户端使用 ZIP 更新；正式用户使用插件中心更新。
169
+ - **修改没有生效**：重新构建并安装，然后刷新列表并启用。
170
+ - **启用失败**：查看错误提示，检查 `activate` 是否抛出异常；客户端提示需要重启时先重启再启用。
171
+ - **类型检查通过但功能异常**：类型检查不能代替实际测试，至少在 Tau 中试一遍启用、执行命令、保存数据、停用和重启。
172
+
173
+ 本模板采用 [MIT 许可](LICENSE)。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xiongtao.xt/tau-plugins",
3
- "version": "0.29.0",
3
+ "version": "0.30.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
package/types/packages/ui/src/index.d.ts CHANGED
@@ -29,6 +29,7 @@ export * from "./primitives/input/Input";
29
29
  export * from "./primitives/input/Textarea";
30
30
  export * from "./primitives/input/NumberInput";
31
31
  export * from "./patterns/FormRow";
32
+ export * from "./patterns/SettingRow";
32
33
  export * from "./primitives/Checkbox";
33
34
  export * from "./primitives/Switch";
34
35
  export * from "./primitives/RadioGroup";