Super Productivity 插件开发指南从零构建、打包、发布到 i18n 国际化【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity本指南以packages/plugin-dev/README.md为主体结合仓库内plugin-api类型定义、vite-plugin构建工具、示例插件与源码实现系统讲解如何在 Super Productivity高级待办清单 时间追踪应用中开发插件从脚手架搭建、PluginAPI能力矩阵、生命周期 Hooks到plugin.zip打包、大小限制、GitHub Actions 发布以及基于i18n/目录的完整国际化方案。读完你将能够独立创建一个可安装、可分发、支持多语言的 Super Productivity 插件。目录插件开发环境与工作区快速上手三种起步方式插件项目结构与构建产物PluginAPI插件能力全景生命周期 Hooks订阅应用事件清单文件 manifest.json 详解构建与打包从源码到 plugin.zip发布插件GitHub Release 与 npm本地测试与调试TypeScript 开发与类型安全插件国际化i18n完整指南最佳实践与疑难排查仓库内示例插件一览插件开发环境与工作区Super Productivity 的插件开发工作区位于仓库的packages/plugin-dev/目录其package.json将super-productivity/plugin-api作为本地依赖并通过 npm workspaces 把example-plugin、simple-typescript-plugin、procrastination-buster等示例纳入统一管理。前置条件Node.js 18 或更高版本npm 或 yarnTypeScript 基础推荐非必需工作区统一命令在packages/plugin-dev/下执行# 构建所有插件 npm run build # 为所有插件安装依赖 npm run install:all # 清理构建产物删除所有插件的 dist 目录 npm run clean:dist # 列出当前可用的插件目录 npm run listlist命令在 package.json 中的实现为ls -d */ | grep -v node_modules | grep -v scripts可以快速查看仓库中已有哪些插件可作为参考。开发期常用的模式是在某个具体插件目录内单独执行npm install、npm run build而不是每次都全量构建。快速上手三种起步方式QUICK_START.md 为开发者提供了三种渐进式起步方案按复杂度递增方案一纯 JavaScript最简单cd minimal-plugin # 编辑 plugin.js # 打成 zip 后上传即可优点无构建步骤改完即生效反馈最快缺点没有 TypeScript 类型检查和打包能力。方案二简易 TypeScript推荐入门cd simple-typescript-plugin npm install npm run build # 构建产物 plugin.zip 位于 dist/优点具备 TypeScript 类型支持构建流程简单缺点仅适合单文件插件。方案三完整 TypeScript Webpack/Vite进阶cd example-plugin npm install npm run build npm run package优点支持多源文件、完整构建工具链缺点工程配置更复杂。如何选择只是想快速验证 API → 使用minimal-plugin需要类型安全 → 使用simple-typescript-plugin构建复杂插件 → 使用example-plugin或仓库内更现代的 boilerplate-solid-jsSolidJS Vite自带 i18n 支持。也可以手动搭建复制示例插件并重命名修改manifest.json元数据与package.json名称描述然后npm install、npm run dev开发、npm run build构建。插件项目结构与构建产物一个典型的插件项目结构如下my-plugin/ ├── package.json # NPM 包配置 ├── tsconfig.json # TypeScript 配置 ├── webpack.config.js # 构建配置Webpack 方案 ├── manifest.json # 插件清单元数据 ├── src/ │ └── index.ts # 插件主代码 ├── assets/ │ ├── index.html # 可选 UIiframe 插件 │ └── icon.svg # 插件图标 ├── scripts/ │ └── package.js # 生成 plugin.zip 的脚本 └── dist/ # 构建输出 ├── plugin.js # 编译后的插件代码纯 iframe 插件可省略 ├── manifest.json # 复制过来的清单 └── plugin.zip # 打包产物如果使用仓库提供的 Vite 插件方案见packages/vite-plugin/构建输出在dist/其中manifest.json从src/manifest.json复制icon.svg从src/assets/icon.svg复制i18n/*.json从插件根目录的i18n/复制index.html中的 JS/CSS 会被内联为单文件并可配置copyTo选项把产物自动拷贝到 Super Productivity 的src/assets/下实现热更新开发见 vite-plugin 源码。PluginAPI插件能力全景插件运行时接收一个全局PluginAPI对象类型定义见 packages/plugin-api/src/types.ts。按能力维度可划分为以下几类配置读取cfg当前应用配置包括themelight | dark、appVersion、platformweb | desktop | android | ios、isDev及lang语言信息。UI 集成registerMenuEntry()在应用菜单中添加条目registerHeaderButton()在顶部标题栏添加按钮registerSidePanelButton()在侧边面板添加按钮registerWorkContextHeaderButton()注册仅当活跃工作上下文项目/标签/Today匹配时才显示的标题按钮回调会收到上下文快照registerShortcut()注册键盘快捷键unregisterShortcut(id)按 id 注销已注册的快捷键用户在键盘设置中的绑定会被保留重新注册同名 id 即可恢复showIndexHtmlAsView()在应用视图中展示插件 UIshowInWorkContext()将插件index.html嵌入工作视图主体替代任务列表仅在项目或 Today 上下文生效closeWorkContextView()恢复为正常任务列表视图openDialog()打开自定义对话框。数据访问getTasks()获取全部任务getArchivedTasks()获取已归档任务getCurrentContextTasks()获取当前项目/标签下的任务getSelectedTask()/getFocusedTask()读取详情面板中选中的任务 / 当前获得焦点的任务行getAppState()获取包含任务、项目、标签、笔记、重复任务配置、简单计数器与全局配置的只读应用快照PluginAppStateupdateTask(taskId, updates)更新任务addTask(taskData)创建任务返回新任务 iddeleteTask(taskId)删除任务batchUpdateForProject()在单个项目中批量执行创建/更新/删除/重排操作支持临时 id 引用见 BatchUpdateRequestgetAllProjects()/addProject()/updateProject()/deleteProject()项目读写其中删除项目会级联删除其包含的任务与 UI 行为一致且拒绝删除收件箱getAllTags()/addTag()/updateTag()标签读写reorderTasks()重排任务顺序selectTask(taskId)打开指定任务的详情面板。用户交互showSnack()显示 snack 条通知type支持SUCCESS | ERROR | WARNING | INFOnotify()显示系统级通知NotifyCfgopenDialog()打开自定义对话框HTML 内容会被宿主白名单清洗脚本、事件处理器属性与危险 URL 均会被移除见 DialogCfg 注释。数据持久化persistDataSynced(dataStr, key?)保存插件数据可选key参数可将同步数据拆分为多个独立解析的条目loadSyncedData(key?)加载已保存的数据getConfig()读取插件配置setSecret(key, value)/getSecret(key)/deleteSecret(key)本地专用的密钥存储绝不进入同步、导出或备份适合存放密码、API Token 等敏感信息。网络与系统能力request(url, options)通过宿主受保护的 HTTP 桥发出请求需要同时在permissions中声明http能力、在allowedHosts中声明目标主机缺一即被拒绝fail-closeddownloadFile(filename, data)触发文件下载startOAuthFlow(config)/getOAuthToken()/clearOAuthToken()OAuth 流程与令牌管理executeNodeScript(request)Electron 桌面端执行 Node 脚本需主进程用户授权仅内置插件可授予dispatchAction(action)派发受限的 NgRx actionisWindowFocused()/onWindowFocusChange(handler)窗口焦点状态简单计数器setCounter/getCounter/incrementCounter/decrementCounter/deleteCounter/getAllCounterslog分级日志对象critical/err/error/warn/normal/info/verbose/debug。生命周期与通信onReady(fn)应用确认所有声明能力就绪后回调把启动初始化代码放在这里而不是plugin.js顶层onUnload(fn)插件被禁用/重载/卸载时回调用于清理定时器与事件监听器iframe 插件中为 no-op因为 iframe 卸载时会随之销毁onMessage(handler)跨进程消息通信插件 iframe 与宿主之间见 PluginIframeMessageType。生命周期 Hooks订阅应用事件通过registerHook(hook, handler)订阅应用生命周期事件完整枚举见 PluginHooksHook触发时机载荷要点taskCreated任务被创建taskIdtasktaskComplete任务被标记完成taskIdtasktaskUpdate任务被修改taskIdtaskchangestaskDelete任务被删除taskIdcurrentTaskChange活跃任务切换currentprevious可为 nullfinishDay一天结束datelanguageChange应用语言切换code/newLanguagepersistedDataChanged本插件持久化数据变化含远端同步送达与批量导入无载荷需重新loadSyncedData()action自定义 action 分发actionpayloadanyTaskUpdate任意任务任意更新actiontaskId?task?changes?projectListUpdate项目列表变化actionprojectId?project?changes?workContextChange活跃工作上下文切换上下文快照ActiveWorkContextregisterHook是泛型方法处理器会收到与 hook 一一对应的强类型载荷映射见 HookPayloadMap。例如// 注册任务完成处理器 PluginAPI.registerHook(taskComplete, async (task) { console.log(Task completed:, task); PluginAPI.showSnack({ msg: Great job completing: ${task.title}, type: SUCCESS, }); }); // 注册键盘快捷键 PluginAPI.registerShortcut({ id: my-action, label: My Plugin Action, onExec: async () { const tasks await PluginAPI.getTasks(); console.log(You have ${tasks.length} tasks); }, });关于workContextChange有一个值得注意的细节载荷中的taskIds是发出时刻的快照而非实时视图任务增删移动后会过期需要当前顺序时应随时调用getActiveWorkContext()或getTasks()重新读取见 ActiveWorkContext 的注释说明。清单文件 manifest.json 详解manifest.json是插件的元数据核心完整字段定义见 PluginManifest{ name: My Awesome Plugin, id: my-awesome-plugin, manifestVersion: 1, version: 1.0.0, minSupVersion: 13.0.0, description: An awesome plugin for Super Productivity, hooks: [taskComplete, taskUpdate], permissions: [showSnack, getTasks, addTask, showIndexHtmlAsView], allowedHosts: [api.example.com], iFrame: true, uiKit: true, sidePanel: false, icon: icon.svg, i18n: { languages: [en, de, fr] } }关键字段说明id全局唯一插件标识manifestVersion清单格式版本号minSupVersion兼容的最低 Super Productivity 版本hooks插件声明使用的事件列表permissions权限声明最小权限原则。常用权限见 plugin-api READMEshowSnack、notify、showIndexHtmlAsView、openDialog、getTasks、getArchivedTasks、getCurrentContextTasks、getSelectedTask、getFocusedTask、addTask、getAllProjects、addProject、deleteProject、getAllTags、addTag、persistDataSynced、getAppState等allowedHosts允许PluginAPI.request访问的精确主机名列表host-only、精确匹配、无通配符、忽略端口。列表为空或省略时request被禁用fail-closed同时还必须在permissions中声明http能力见 types.ts 注释。安装时该列表会展示给用户以便审查插件的出网范围iFrametrue表示该插件通过index.html提供 UIuiKit是否注入 UI Kit CSS reset默认truesidePaneltrue时插件加载到右侧面板而非路由iconSVG 图标路径相对插件根目录jsonSchemaCfg插件配置的 JSON Schema 文件路径i18n.languages插件支持的语言代码数组详见下文国际化章节。构建与打包从源码到 plugin.zip打包命令npm run build npm run package产物为dist/plugin.zip可直接分发。文件大小限制以下限制来自 plugin.const.ts是宿主端实际执行的校验值注意与文档中列出的上限相比当前源码中的 ZIP 与代码限制更为严格文件源码实际限制当前仓库插件 ZIPMAX_PLUGIN_ZIP_SIZE 10MB插件代码plugin.jsMAX_PLUGIN_CODE_SIZE 5MB清单manifest.jsonMAX_PLUGIN_MANIFEST_SIZE 100KB全部翻译文件合计MAX_PLUGIN_TRANSLATIONS_TOTAL_SIZE 5MB开发时请以源码常量 plugin.const.ts 为准并预留余量。必选与可选文件plugin.zip必须包含manifest.json— 插件元数据plugin.js— 插件主代码除非是iFrame: true且带index.html的纯 iframe 插件。可选文件index.html— iframe 插件的 UIicon.svg— 插件图标i18n/*.json— 多语言翻译文件。发布插件GitHub Release 与 npmGitHub Release推荐方式为插件创建 GitHub 仓库使用 GitHub Actions 在发布时自动构建参考 workflowname: Build Plugin on: release: types: [created] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - uses: actions/setup-nodev3 with: node-version: 18 - run: npm ci - run: npm run build - run: npm run package - uses: softprops/action-gh-releasev1 with: files: dist/plugin.zip用户即可从 Releases 下载.zip文件安装。NPM 包也可以将插件源码发布到 npm在package.json中配置 npm scopenpm run build构建npm publish发布。用户可自行构建或由你在包中包含构建产物。本地测试与调试开发模式测试# 构建插件 npm run build # 复制到 Super Productivity 的资源目录 npm run install-local # 该命令将构建产物复制到 ../../../src/assets/my-plugin/ # 在开发模式下启动 Super Productivity cd ../../.. npm start此外若使用super-productivity/vite-plugin可在 vite 配置中设置copyTo指向 Super Productivity 的src/assets/构建时自动拷贝实现热更新见 vite-plugin 源码 的copyTo选项。生产构建测试npm run package打包打开 Super Productivity进入Settings → Plugins点击Upload Plugin选择你的plugin.zip。调试技巧打开浏览器 DevTools 查看控制台日志插件在主窗口上下文中运行console.log()直接可见插件错误会在 Console 中输出可利用宿主提供的PluginAPI.log分级日志debug/info/warn/error等。TypeScript 开发与类型安全收益类型安全完整的 IntelliSense 与编译期检查API 发现所有PluginAPI方法自动补全重构安全TypeScript 保证重构不破坏接口内联文档IDE 中直接查看类型注释例如getAppState()的快照语义、request()的 fail-closed 行为都有详细 JSDoc。安装类型包npm install super-productivity/plugin-api带类型的示例import type { TaskData, ProjectData } from super-productivity/plugin-api; // 类型安全的任务处理 async function processTask(task: TaskData): Promisevoid { if (task.projectId) { const projects await PluginAPI.getAllProjects(); const project projects.find((p) p.id task.projectId); if (project) { console.log(Task ${task.title} belongs to project ${project.title}); } } } // 类型安全的 hook 注册 PluginAPI.registerHook(taskUpdate, (data: unknown) { const task data as TaskData; processTask(task); });类型包还导出了PluginHooks枚举、PluginManifest、PluginBaseCfg、SnackCfg、DialogCfg、Task/Project/Tag等数据与 UI 类型plugin-api README。注意TaskData、ProjectData、TagData已被标记为deprecated新代码建议直接使用Task、Project、Tag。插件国际化i18n完整指南完整规范见 PLUGIN_I18N.md这里汇总核心要点。目录结构与清单声明my-plugin/ ├── manifest.json # 声明支持的语言 ├── plugin.js └── i18n/ # 翻译文件 ├── en.json # 必选 — 英文 ├── de.json # 可选 — 德语 └── fr.json # 可选 — 法语{ id: my-plugin, name: My Plugin, version: 1.0.0, i18n: { languages: [en, de, fr] } }规则要点languages必填且必须至少包含en英文是兜底语言使用标准小写语言代码en、de、fr、es、ja、zh等语言代码必须与 Super Productivity 自身的代码匹配且全小写pt-br有效pt-BR无效会被忽略翻译文件必须是UTF-8编码的 JSON旧式 8 位编码Latin-1/CP1252的文件会被直接拒绝已声明但缺少对应i18n/lang.json的语言会被跳过并在控制台输出警告不支持的代码统一输出Unsupported language codes: …警告上传的插件 ZIP 中所有翻译文件合计不得超过 5MB源码常量MAX_PLUGIN_TRANSLATIONS_TOTAL_SIZE见 plugin.const.ts。翻译文件格式使用层级化 JSON 组织{ MESSAGES: { WELCOME: Welcome to the plugin!, ERROR: An error occurred: {{error}} }, BUTTONS: { SAVE: Save, CANCEL: Cancel } }最佳实践键名统一大写相关翻译分组层级保持在 23 层以内使用描述性键名BUTTONS.SAVE_TASK优于BTN1。API 方法translate(key, params?)按当前语言翻译键支持{{param}}参数插值。兜底顺序当前应用语言 → 英文 → 找不到则返回键本身。api.translate(MESSAGES.WELCOME); // → Welcome to the plugin! (en) api.translate(MESSAGES.ERROR, { error: Network timeout }); // → An error occurred: Network timeout api.translate(BUTTONS.SAVE); // → Speichern (de) / Save (en 兜底) api.translate(BUTTONS.DELETE); // → BUTTONS.DELETE都找不到则返回键formatDate(date, format)按当前语言环境格式化日期输入支持Date对象、ISO 8601 字符串、毫秒时间戳。预定义格式short、medium、long、time、datetime。api.formatDate(new Date(), short); // → 1/16/26 (en-US) / 16.1.26 (de) api.formatDate(2026-01-16T14:30:00Z, datetime); // → 1/16/26, 2:30 PM (en)getCurrentLanguage()返回当前应用语言代码如en、de、fr可据此做条件逻辑如 CJK 字体处理。语言切换 Hookapi.registerHook(languageChange, ({ newLanguage }) { console.log(Language changed to: ${newLanguage}); // 插件翻译会自动重载此处只需处理额外 UI 更新 updatePluginUI(); });注意语言切换时插件翻译会自动重新加载只有需要额外 UI 更新的场景才需注册此 hook。支持的语言代码Super Productivity 官方支持的语言完整表格en、de、es、fr、it、pt、pt-br、ru、zh、zh-tw、ja、ko、ar、fa、tr、pl、nl、nb、sv、fi、cs、sk、hr、uk、id、ro、ro-md。插件只需声明自己实际翻译了的语言其余用户自动回退到英文。复数与参数插值翻译键中不含复数逻辑推荐用参数动态选择键{ TASK_COUNT_SINGULAR: {{count}} task remaining, TASK_COUNT_PLURAL: {{count}} tasks remaining }const key count 1 ? TASK_COUNT_SINGULAR : TASK_COUNT_PLURAL; const msg api.translate(key, { count });参数插值失败的两类常见错误缺少花括号语法$name不生效需{{name}}参数名不匹配传{ user: John }无法替换{{name}}。性能与缓存语义翻译文件在插件激活时加载一次翻译结果在内存中缓存频繁调用translate()无性能影响语言切换复用已加载的翻译因此不要在插件里自行缓存翻译结果每次都调用api.translate()即可。最佳实践与疑难排查最佳实践错误处理异步操作始终用 try-catch 包裹性能不要在主线线程执行重型计算状态管理插件状态使用persistDataSynced()敏感信息改用setSecret()避免进入同步/导出/备份用户体验用 snack 消息提供清晰反馈权限只申请实际需要的权限版本兼容正确设置minSupVersion国际化始终附带en.json为插件添加 i18n 支持以触达更多用户启动/卸载初始化代码放进onReady()清理代码放进onUnload()网络访问使用request()时必须同时声明http权限与allowedHosts白名单。疑难排查插件未加载检查浏览器控制台错误确认manifest.json是合法 JSON确认必填字段齐全id、manifestVersion、version、minSupVersion等检查文件大小是否超过 plugin.const.ts 中的限制。TypeScript 报错运行npm run typecheck查看全部错误确认安装了super-productivity/plugin-api检查tsconfig.json配置。构建问题删除dist/后重新构建检查 webpack/vite 配置确认所有依赖已安装。翻译显示为键名而非译文检查i18n/目录存在于插件 ZIP 根目录与manifest.json同级验证 JSON 文件有效且为 UTF-8确认键名大小写完全一致区分大小写查看浏览器控制台中的警告日志。仓库内示例插件一览packages/plugin-dev/下提供了丰富的示例插件npm run list可查看完整列表minimal-plugin— 最简单的插件约 10 行代码simple-typescript-plugin— 带 TypeScript 的最小工程example-plugin— 功能完整的 Webpack 示例覆盖全部 API、iframe UI、状态持久化、Hook 处理、构建配置boilerplate-solid-js— 现代 SolidJS 样板SolidJS 响应式 UI、Vite 快速构建、i18n 支持示例翻译、插件与 iframe 通信其 manifest.json 与 plugin.ts 是上手参考的绝佳模板procrastination-buster— 真实业务场景的 SolidJS 插件此外还有brain-dump、doc-mode、sync-md、todoist-import、voice-reminder、yesterday-tasks-plugin以及github-issue-provider、gitlab/gitea/azure-devops/clickup/linear/trello-issue-provider、caldav-calendar-provider、google-calendar-provider等 Issue/日历集成示例可分别作为标准插件与issueProvider类型插件的参考实现。建议的开发路线先用minimal-plugin理解 API需要类型安全时迁移到 TypeScript构建复杂插件时再引入 Webpack 或 Vite全程参考 plugin-api 类型定义 中的 JSDoc 注释它是插件 API 最权威的行为契约。【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考