桌面应用【免费下载链接】QOwnNotesQOwnNotes is a plain-text file notepad and todo-list manager with Markdown support and Nextcloud / ownCloud integration.项目地址https://gitcode.com/gh_mirrors/qo/QOwnNotes点击查看免费下载QOwnNotes 内置了一个面向 Homepage 仪表盘的本地 HTTP 建议接口Bookmark Suggestion API它复用 Web Companion 浏览器扩展同款的书签解析与索引逻辑让 Homepage 的搜索框可以直接从你本地笔记中的书签生成联想建议。本文将从启用配置、HTTP 端点协议、书签匹配算法、Homepage 配置到仓库自带的custom.js/custom.css前端整合方案给出完整可落地的接入教程。功能概述一条命令连通「本地书签」与「Homepage 搜索」QOwnNotes 以纯文本 Markdown 文件存储笔记而书签正是以 Markdown 链接形式存在于笔记中。Homepage Suggestion API 的核心思路是QOwnNotes 在本地启动一个仅绑定127.0.0.1的 HTTP 服务Homepage或其custom.js前端脚本向该服务请求GET /suggest?q关键字QOwnNotes 扫描带bookmarks标签的笔记、名为Bookmarks的笔记以及当前打开的笔记解析出书签后返回 JSON 建议列表Homepage 将建议合并进自己的搜索联想框点击后可直接打开书签 URL而不是交给搜索引擎。这意味着你的 Homepage 搜索框从此拥有了「个人书签搜索引擎」能力数据完全保留在本机无需上传任何云端。在 QOwnNotes 中启用 Bookmark Suggestion API设置入口打开 QOwnNotes 的Settings - Browser extension / command snippetsWeb Companion 设置页按以下步骤操作勾选Enable socket server启用 Socket 服务这是 Suggestion API 生效的前置开关——未启用时整个浏览器扩展框架区都是灰的在Bookmark suggestion API分组框中勾选Enable Homepage-compatible bookmark suggestions API设置一个监听端口默认为22224可选设置一个安全令牌Security token。对应界面定义可以在 webcompanionsettingswidget.ui 中看到端口使用QSpinBox取值范围 1~65535默认 22224令牌使用QLineEditechoMode为 Password最大长度 32并附带三个工具按钮显示令牌、复制到剪贴板、重新生成令牌。设置读取/存储逻辑位于 webcompanionsettingswidget.cpp。底层参数说明这些设置最终映射到SettingsService的配置键由 websocketserverservice.cpp 读取配置键默认值说明webSocketServerService/bookmarkSuggestionApiEnabledfalse是否启用建议 API对应 isBookmarkSuggestionApiEnabled()webSocketServerService/bookmarkSuggestionApiPort22224Debug 构建为22225监听端口对应 getBookmarkSuggestionApiDefaultPort()webSocketServerService/bookmarkSuggestionApiToken自动生成 32 位随机串访问令牌通过CryptoService加密存储见 getOrGenerateBookmarkSuggestionApiToken()几个值得注意的实现细节仅绑定本机回环地址HTTP 服务通过m_pHttpServer-listen(QHostAddress::LocalHost, port)启动startSuggestionHttpServer()不会暴露到局域网外部机器无法直接访问。令牌自动生成与加密保存设置时若令牌为空会自动生成一个 32 位随机字符串令牌在设置文件中以加密形式保存见 webcompanionsettingswidget.cpp。同时代码保留了对旧版明文值的兼容回退逻辑读取时会自动迁移为加密存储。服务联动refreshServers()会在启用开关打开时启动 HTTP 服务、关闭时停止websocketserverservice.cpp与 WebSocket 服务相互独立、互不影响。HTTP 端点协议详解请求格式端点GET /suggest查询参数参数必选说明q是搜索关键字URL 编码后传入limit否返回建议条数上限默认10最小1最大50token否安全令牌仅在 QOwnNotes 中配置了令牌后必须携带响应格式响应为 JSON 数组第一个元素是原始查询字符串第二个元素是建议字符串数组[home, [Homepage, https://example.com/home, Some Home Link]]该结构的序列化逻辑在 Bookmark::homepageSuggestionResponseJson() 中实现数组第一个元素为查询词第二个元素为建议列表。错误状态码与请求处理流程请求处理在 processHttpRequest() 中完成顺序如下请求行解析失败 → 返回400 Bad Request非GET方法 → 返回405 Method Not Allowed路径不是/suggest→ 返回404 Not Foundtoken参数与配置的令牌不一致 → 返回401 Unauthorized未配置令牌时则跳过该校验limit参数非法时回退为10超出 1~50 范围时被强制收敛到边界正常时返回200 OK与 JSON 响应体。此外所有响应都带有 CORS 头Access-Control-Allow-Origin: *、Cache-Control: no-store与Connection: close见 httpResponse()方便浏览器端脚本跨域请求。性能优化双层缓存服务端实现了两级缓存homepageSuggestionResponse()书签缓存书签列表缓存 2500ms2.5 秒后失效重建避免每次请求都重新解析所有笔记建议结果缓存以查询词|limit为键缓存生成好的 JSON 响应缓存上限 200 条超出后按插入顺序淘汰最旧条目。书签来源与匹配算法源码级解析书签从哪里来getBookmarksForSuggestions()websocketserverservice.cpp按以下顺序汇总书签所有带有bookmarks标签的笔记标签名可在设置中修改默认bookmarks见 getBookmarksTag()所有名为Bookmarks的笔记笔记名同样可配置默认Bookmarks见 getBookmarksNoteName()当前正在编辑的笔记中的所有链接。汇总前会做去重合并相同 URL 的书签合并标签、名称与描述然后整体缓存。书签如何解析Bookmark::parseBookmarks() 使用正则解析笔记文本支持三类 Markdown 链接标准书签格式- [名称](http://链接) #标签1 #标签2 描述文字行首为-或*普通命名链接[名称](http://链接)尖括号链接http://链接。其中 URL 必须以协议://形式出现如https://、http://。建议匹配与排序Bookmark::suggestionStrings() 实现了完整的匹配算法大小写不敏感查询词与书签的名称、URL、标签、描述、原始 Markdown 文本统一转为小写后比较多词 token 匹配查询词按空格拆分为多个 token书签必须包含所有token 才算命中token 顺序无关前缀优先排序名称或 URL 以查询词/任一 token 开头的书签排在前面其次才是仅包含子串的书签输出配对命中书签会先输出名称、再输出 URL测试用例 testBookmarkSuggestionsKeepNameUrlPairing 明确验证了「名称索引 URL 索引」的顺序这正是custom.js建立「名称→URL」映射的前提去重大小写折叠后相同的建议只保留一条testBookmarkSuggestionsDeduplication。仓库单元测试 test_notes.cpp 覆盖了前缀/子串匹配、去重、多 token 顺序无关、名称-URL 配对、元数据标签/描述参与匹配、空查询、limit 收敛limit100时强制为 50以及响应 JSON 结构等全部关键行为可作为你理解算法边界的参考。配置 Homepage让搜索框接收本地建议搜索配置示例在 Homepage 的配置中为search块指定provider: custom并将suggestionUrl指向本地 QOwnNotes 建议接口search: provider: custom url: https://example.com/search?q suggestionUrl: http://127.0.0.1:22224/suggest?q showSearchSuggestions: trueprovider: custom告诉 Homepage 使用自定义搜索提供方suggestionUrlHomepage 会向该地址追加用户输入的查询词并发起联想请求showSearchSuggestions: true启用联想框显示若你在 QOwnNotes 中配置了安全令牌请保持suggestionUrl不变改由custom.js中的QON_TOKEN变量在请求时自动追加token...见下文。需要修改哪个 Homepage 文件在标准 Homepage 安装中将search块加入以下任一文件settings.yamlHomepage 全局设置settings.yml同上取决于你的安装命名容器中挂载为/app/config/settings.yaml的文件如果你的 Homepage 部署把配置拆分到多个文件请编辑已经包含searchprovider 设置的那个文件而不要新建重复配置。自定义 Homepage 前端资源合并建议与直接打开书签仅配置suggestionUrl时Homepage 会把建议当作普通搜索词。若希望建议直接打开书签 URL而非跳转搜索引擎需要使用仓库自带的定制前端资源。资源位置仓库在 docs/homepage 目录下提供了现成的定制示例custom.js核心整合脚本custom.css为 QOwnNotes 建议条目提供视觉区分样式README.md整合说明文档。当你的 Homepage 部署支持加载custom.js与custom.css时将这两个文件放入对应目录即可。custom.js 的工作原理custom.js是一个立即执行的前端脚本逐条完成了以下工作对应 docs/homepage/README.md 的说明拦截建议请求重写window.fetch拦截 Homepage 的/api/search/searchSuggestion端点请求合并建议额外向 QOwnNotes 的http://127.0.0.1:22224/suggest?q查询limitQON_LIMIT发起请求并把返回的建议与 Homepage 原生建议合并去重后返回QOwnNotes 建议排前标记来源为每条 QOwnNotes 建议添加[QON]前缀QON_LABEL在界面上一眼可辨建立名称→URL 映射将「名称 URL」成对出现的建议存入suggestionToUrl映射表拦截新窗口打开重写window.open识别搜索引擎跳转 URL 并解码出原始书签地址若命中映射表则直接以书签 URL 打开新标签页避免把书签文本交给搜索引擎带[QON]前缀的文本会被彻底拦截绝不外泄给搜索服务破除 4 条截断通过改写Response.prototype.json拦截 Homepage 对建议列表「前 4 条」的客户端裁剪逻辑让合并后的完整建议列表得以展示DOM 标记通过MutationObserver为匹配行添加qon-suggestionCSS 类并处理键盘导航、滚动定位、URL 提示行等细节。可调参数custom.js顶部的常量即全部配置开关常量默认值说明QON_URLhttp://127.0.0.1:22224/suggest?qQOwnNotes 建议接口地址QON_TOKEN与 QOwnNotes 设置中相同的安全令牌配置后请求会自动追加token...QON_LIMIT20向 QOwnNotes 请求的建议条数上限受服务端 50 限制QON_LABEL[QON] 显示在建议前的标记文本DEBUGfalse设为true可输出[QON-MERGE]调试日志custom.css 的样式效果custom.css 为button.qon-suggestion添加绿色#2f855a左边框和文字颜色并针对映射到 URL 的建议行li.qon-li-has-url在下方渲染一个小字号 URL 提示.qon-url-hint方便你确认即将打开的地址。外部主机部署时的注意点如果你的 Homepage 运行在与 QOwnNotes 不同的机器/容器上必须将custom.js与custom.css部署到承载 Homepage 的那台主机上它才能跨机查询 QOwnNotes 的建议接口使用 QOwnNotes 安全令牌时确保custom.js内的QON_TOKEN与 QOwnNotes 设置中的令牌一致。安全边界与生产建议由于书签数据可能包含敏感 URL官方文档明确提示了以下安全边界默认仅限本机访问服务只绑定127.0.0.1外部网络无法直接触达必须使用安全令牌令牌校验失败返回401未配置令牌时接口对所有本机进程开放建议始终配置令牌如需跨机访问应在 QOwnNotes 之前放置反向代理并用防火墙规则或 IP 白名单限制访问来源不要直接将端口暴露到公网令牌加密存储令牌通过CryptoService加密后写入设置避免明文落盘相关键也被纳入 misc.cpp 的敏感键清单。验证与排错启用并配置完成后你可以直接在本机用curl验证接口# 不带令牌 curl http://127.0.0.1:22224/suggest?qhomelimit10 # 带令牌替换为你的实际令牌 curl http://127.0.0.1:22224/suggest?qhomelimit10tokenYOUR_TOKEN期望返回形如[home,[Homepage,https://example.com/home]]的 JSON。若返回401请核对custom.js中的QON_TOKEN与 QOwnNotes 设置中的令牌是否一致若返回404请确认请求路径为/suggest且 QOwnNotes 的启用开关与 Socket server 开关均已打开。更新custom.js/custom.css后请对 Homepage 页面执行硬刷新确保浏览器加载新版本脚本。至此你的 Homepage 搜索框已经与本地书签笔记打通输入关键字即可获得来自 QOwnNotes 笔记的个人化联想建议并直接打开对应书签全程数据不出本机。赞分享桌面应用【免费下载链接】QOwnNotesQOwnNotes is a plain-text file notepad and todo-list manager with Markdown support and Nextcloud / ownCloud integration.项目地址https://gitcode.com/gh_mirrors/qo/QOwnNotes点击查看免费下载相关推荐QOwnNotes Homepage 书签建议 API为 Homepage 搜索框接入本地书签自动补全QOwnNotes Homepage 书签建议 API为 Homepage 搜索框接入本地书签自动补全 QOwnNotes 提供了一个本地 HTTP 端点把桌面应用QOwnNotes Homepage 书签建议 API 接入指南将本地书签注入 Homepage 搜索建议QOwnNotes Homepage 书签建议 API 接入指南将本地书签注入 Homepage 搜索建议 QOwnNotes 内置了一个仅绑定本机回环地址的桌面应用QOwnNotes Homepage 书签建议 API 实战:把本地书签接入 Homepage 搜索建议QOwnNotes Homepage 书签建议 API 实战:把本地书签接入 Homepage 搜索建议 QOwnNotes 除了常见的笔记与 Markdown桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考