# aquatask **Repository Path**: chenyus66/aquatask ## Basic Information - **Project Name**: aquatask - **Description**: 思源插件:个人智能化任务管理 - **Primary Language**: TypeScript - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-09-12 - **Last Updated**: 2025-09-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README [English](https://github.com/siyuan-note/plugin-sample/blob/main/README.md) # 思源笔记插件示例 ## 开始 * 通过 Use this template 按钮将该库文件复制到你自己的库中,请注意库名必须和插件名称一致,默认分支必须为 `main` * 将你的库克隆到本地开发文件夹中,为了方便可以直接将开发文件夹放置在 `{工作空间}/data/plugins/` 下 * 安装 [NodeJS](https://nodejs.org/en/download) 和 [pnpm](https://pnpm.io/installation),然后在开发文件夹下执行 `pnpm i` * 执行 `pnpm run dev` 进行实时编译 * 在思源中打开集市并在下载选项卡中启用插件 ## 开发 * i18n/* * icon.png (160*160) * index.css * index.js * plugin.json * preview.png (1024*768) * README*.md * [前端 API](https://github.com/siyuan-note/petal) * [后端 API](https://github.com/siyuan-note/siyuan/blob/master/API_zh_CN.md) ## 国际化 国际化方面我们主要考虑的是支持多语言,具体需要完成以下工作: * 插件自身的元信息,比如插件描述和自述文件 * plugin.json 中的 `description` 和 `readme` 字段,以及对应的 README*.md 文件 * 插件中使用的文本,比如按钮文字和提示信息 * src/i18n/*.json 语言配置文件 * 代码中使用 `this.i18.key` 获取文本 * 最后在 plugin.json 中的 `i18n` 字段中声明该插件支持的语言 建议插件至少支持英文和简体中文,这样可以方便更多人使用。 ## plugin.json ```json { "name": "plugin-sample", "author": "Vanessa", "url": "https://github.com/siyuan-note/plugin-sample", "version": "0.1.3", "minAppVersion": "2.8.8", "backends": ["windows", "linux", "darwin"], "frontends": ["desktop"], "displayName": { "default": "Plugin Sample", "zh_CN": "插件示例" }, "description": { "default": "This is a plugin sample", "zh_CN": "这是一个插件示例" }, "readme": { "default": "README.md", "zh_CN": "README_zh_CN.md" }, "funding": { "openCollective": "", "patreon": "", "github": "", "custom": [ "https://ld246.com/sponsor" ] }, "keywords": [ "sample", "示例" ] } ``` * `name`:插件名称,必须和库名一致,且全局唯一(集市中不能有重名插件) * `author`:插件作者名 * `url`:插件仓库地址 * `version`:插件版本号,建议遵循 [semver](https://semver.org/lang/zh-CN/) 规范 * `minAppVersion`:插件支持的最低思源笔记版本号 * `disabledInPublish`:使用发布服务时是否禁用该插件,默认为 false * `backends`:插件需要的后端环境,可选值为 `windows`, `linux`, `darwin`, `docker`, `android`, `ios`, `harmony` and `all` * `windows`:Windows 桌面端 * `linux`:Linux 桌面端 * `darwin`:macOS 桌面端 * `docker`:Docker 端 * `android`:Android 端 * `ios`:iOS 端 * `harmony`:鸿蒙端 * `all`:所有环境 * `frontends`:插件需要的前端环境,可选值为 `desktop`, `desktop-window`, `mobile`, `browser-desktop`, `browser-mobile` and `all` * `desktop`:桌面端 * `desktop-window`:桌面端页签转换的独立窗口 * `mobile`:移动端 * `browser-desktop`:桌面端浏览器 * `browser-mobile`:移动端浏览器 * `all`:所有环境 * `displayName`:模板显示名称,主要用于模板集市列表中显示,支持多语言 * `default`:默认语言,必须存在 * `zh_CN`、`en_US` 等其他语言:可选,建议至少提供中文和英文 * `description`:插件描述,主要用于插件集市列表中显示,支持多语言 * `default`:默认语言,必须存在 * `zh_CN`、`en_US` 等其他语言:可选,建议至少提供中文和英文 * `readme`:自述文件名,主要用于插件集市详情页中显示,支持多语言 * `default`:默认语言,必须存在 * `zh_CN`、`en_US` 等其他语言:可选,建议至少提供中文和英文 * `funding`:插件赞助信息 * `openCollective`:Open Collective 名称 * `patreon`:Patreon 名称 * `github`:GitHub 登录名 * `custom`:自定义赞助链接列表 * `keywords`:搜索关键字列表,用于集市搜索功能 ## 打包 无论使用何种方式编译打包,我们最终需要生成一个 package.zip,它至少包含如下文件: * i18n/* * icon.png (160*160) * index.css * index.js * plugin.json * preview.png (1024*768) * README*.md ## 上架集市 * 执行 `pnpm run build` 生成 package.zip * 在 GitHub 上创建一个新的发布,使用插件版本号作为 “Tag version”,示例 https://github.com/siyuan-note/plugin-sample/releases * 上传 package.zip 作为二进制附件 * 提交发布 如果是第一次发布版本,还需要创建一个 PR 到 [Community Bazaar](https://github.com/siyuan-note/bazaar) 社区集市仓库,修改该库的 plugins.json。该文件是所有社区插件库的索引,格式为: ```json { "repos": [ "username/reponame" ] } ``` PR 被合并以后集市会通过 GitHub Actions 自动更新索引并部署。后续发布新版本插件时只需要按照上述步骤创建新的发布即可,不需要再 PR 社区集市仓库。 正常情况下,社区集市仓库每隔 1 小时会自动更新索引并部署,可在 https://github.com/siyuan-note/bazaar/actions 查看部署状态。 ## 开发者须知 开发者需注意以下规范。 ### 1. 读写文件规范 插件或者外部扩展如果有直接读取或者写入 data 下文件的需求,请通过调用内核 API 来实现,**不要自行调用 `fs` 或者其他 electron、nodejs API**,否则可能会导致数据同步时分块丢失,造成云端数据损坏。 相关 API 见 `/api/file/*`(例如 `/api/file/getFile` 等)。 ### 2. Daily Note 属性规范 思源在创建日记的时候会自动为文档添加 custom-dailynote-yyyymmdd 属性,以方便将日记文档同普通文档区分。 > 详情请见 [Github Issue #9807](https://github.com/siyuan-note/siyuan/issues/9807)。 开发者在开发手动创建 Daily Note 的功能时请注意: * 如果调用了 `/api/filetree/createDailyNote` 创建日记,那么文档会自动添加这个属性,无需开发者特别处理 * 如果是开发者代码手动创建文档(例如使用 `createDocWithMd` API 创建日记),请手动为文档添加该属性