1. 项目概述从“截图即遗忘”到“截图即知识”作为一个常年与信息过载作斗争的笔记爱好者我一直在寻找一种更优雅、更智能的信息捕获方式。我们每天都会在手机和电脑上截取大量图片——可能是网页上的一段关键论述、会议白板上的一个流程图或是聊天记录里的一个地址。但问题在于截图之后呢它们通常就静静地躺在相册里直到存储空间告急时被批量删除或者彻底被遗忘里面的信息价值从未被真正释放。搜索除非你记得截图的大概日期和内容否则在成百上千张图片里大海捞针几乎是徒劳的。这正是QuickNote这个项目吸引我的地方。它不是一个全新的笔记应用而是一个精巧的“连接器”和“处理器”。它的核心思想非常清晰利用大语言模型LLM的视觉理解能力把你主动选择的屏幕内容瞬间转化为结构清晰、可搜索、可组织的文本笔记。你可以把它理解为一个高度自动化的“截图OCR”工作流但其背后是当前最前沿的多模态大模型Vision-Language Model在驱动理解能力远超传统的OCR。与某些系统级、持续录屏的“记忆”功能设计哲学截然相反QuickNote 强调“选择性记忆”和“用户主权”。你不是被动的被记录者而是主动的决策者。只有当你按下截图快捷键或触发快捷指令时信息才会被捕获和处理。这种设计在隐私日益重要的今天显得尤为可贵它把控制权完全交还给了用户。对于开发者、研究者、学生以及任何需要从数字环境中高效提取和沉淀知识的人来说这是一个能将碎片信息瞬间系统化的利器。接下来我将详细拆解如何从零开始搭建并深度定制属于你自己的 QuickNote 系统。2. 核心架构与设计哲学解析2.1 为什么是“客户端-服务器-存储”三层架构QuickNote 采用了经典的三层分离架构这种设计并非偶然而是为了在灵活性、隐私性和功能专精之间取得最佳平衡。客户端层iOS/macOS Shortcuts它的职责极其单一且轻量——捕获屏幕图像并发送。通过利用苹果生态内置的“快捷指令”应用QuickNote 无需开发独立的 App实现了零安装、跨设备iPhone, iPad, Mac的统一触发体验。快捷指令可以直接访问系统截图获取当前屏幕内容这比任何第三方应用都更底层、更可靠。这种设计也意味着客户端几乎不需要更新核心功能迭代全部集中在服务器端。服务器层Vision-Language Model 服务这是整个系统的大脑也是技术核心。它接收客户端发来的图片和用户可选的附加提示词调用多模态大模型 API 进行图像理解和内容提取并将结果格式化为 Markdown。将这部分逻辑放在独立的服务器上运行带来了几个关键优势模型灵活性你可以自由选择任何支持视觉能力的 API 提供商如 OpenAI 的 GPT-4V、Anthropic 的 Claude 3、Google 的 Gemini Pro Vision甚至是本地部署的开源模型如 LLaVA。更换模型只需修改服务器配置客户端无需任何改动。成本与密钥安全API 密钥只需保存在你自己的服务器上避免了在多个客户端设备上分发和管理密钥的风险和麻烦。逻辑集中所有关于提示词工程、后处理、错误重试的逻辑都在服务器端便于统一优化和维护。存储层Memos选择 Memos 作为存储后端是一个深思熟虑的选择。Memos 是一个开源、自托管的轻量级笔记服务其 API 友好支持 Markdown并且自带标签、搜索和简单的内容组织功能。它扮演了一个“收件箱”或“知识库”的角色。将 QuickNote 与 Memos 解耦意味着你的结构化笔记并非锁死在一个特定工具里。未来你可以通过 Memos 的 API 将这些笔记同步到 Obsidian、Logseq 或任何你喜欢的笔记系统中形成更强大的个人知识管理体系。设计哲学对比这里值得深入探讨一下与“持续记录”理念如曾引发热议的某些功能的根本区别。后者的出发点是“数字记忆体”试图记录一切操作以备回溯其挑战在于海量数据的管理、隐私的边界界定以及“有用信息”的提取效率。而 QuickNote 的哲学是“知识捕手”它假设用户有能力在信息洪流中识别出高价值片段并为其提供瞬间固化的工具。前者是“记录一切事后查找”后者是“主动捕获即时转化”。对于大多数知识工作者而言后者的心智负担更小信息密度和可用性也更高。2.2 技术栈选型背后的考量原项目给出了一个基于 Docker Compose 的快速启动方案但为了更深入的理解和后续定制我们有必要拆解其技术栈。服务器框架Node.js Express项目服务器端使用 Node.js这是处理此类轻量级、高 I/O、事件驱动型应用的合理选择。Express 框架足够简单直接能快速搭建起接收图片、调用外部 API、返回结果的 HTTP 端点。对于个人使用场景其性能完全绰绰有余。多模态模型 API 选择这是效果和成本的关键。不同的模型在图像理解、文字识别尤其是中文、格式遵从和推理能力上差异显著。GPT-4V综合能力最强对复杂图表、手写体的理解以及按照指令进行结构化输出的能力通常最好但价格最贵且 API 稳定性受地区影响。Claude 3 (Opus/Sonnet)在长文本理解和格式输出上非常出色安全性和“听话”程度高适合生成严谨的笔记。Gemini Pro Vision性价比可能是一个优势在某些基准测试中表现不俗是值得考虑的备选。开源模型如 LLaVA-Next如果你对数据隐私有极致要求或希望完全离线、零成本运行这是唯一选择。但需要较强的 GPU 硬件支持且效果尤其是对复杂版面的解析目前与顶级闭源模型仍有差距。部署与环境使用 Docker Compose 将服务器和 Memos 一起部署极大简化了环境配置和依赖管理。.env文件管理所有敏感信息和配置API密钥、Memos地址等符合十二要素应用的原则便于在不同环境间迁移。3. 从零开始部署与配置实战3.1 前置准备部署 Memos 笔记服务虽然 QuickNote 的 docker-compose 文件包含了 Memos但我强烈建议你先独立部署和熟悉 Memos这有助于理解数据流向和进行故障排查。方案A使用 Docker 独立部署推荐这是最干净的方式。在你的服务器可以是家里的 NAS、云服务器或本地电脑上执行# 创建一个目录存放 Memos 数据 mkdir -p /your/data/path/memos # 使用 Docker 运行 docker run -d \ --name memos \ --publish 5230:5230 \ --volume /your/data/path/memos:/var/opt/memos \ neosmemo/memos:latest运行后在浏览器访问http://你的服务器IP:5230即可完成 Memos 的初始设置创建管理员账号。记下你设置的账号密码。方案B使用项目内的 Docker Compose如果你打算快速体验可以按照项目说明在server目录下操作。但请注意项目内的docker-compose.yml可能将 Memos 的数据卷映射到相对路径长期使用前最好在docker-compose.yml文件中确认并修改数据卷的持久化路径。关键配置点端口默认 5230确保防火墙或安全组已放行。数据持久化务必通过-v参数将容器内的/var/opt/memos目录映射到宿主机路径防止容器重启后数据丢失。访问令牌在 Memos 网页端点击左下角用户名 -设置-权限-创建访问令牌。这个令牌将用于让 QuickNote 服务器代表你创建笔记请妥善保存。3.2 核心环节配置 QuickNote 服务器这是整个系统最核心的配置环节直接决定了笔记生成的质量和系统的稳定性。获取代码与基础配置git clone https://github.com/axhiao/QuickNote.git cd QuickNote/server cp .env.example .env现在用文本编辑器打开.env文件你将看到如下关键配置项配置模型 API以 OpenAI 为例# 选择你的模型提供商例如openai, anthropic, google, local VLM_PROVIDERopenai # OpenAI 配置 OPENAI_API_KEYsk-your-secret-key-here OPENAI_MODELgpt-4-vision-preview # 或 gpt-4o OPENAI_BASE_URLhttps://api.openai.com/v1 # 如果你使用第三方代理可修改此处OPENAI_API_KEY在 OpenAI Platform 创建。OPENAI_MODELgpt-4-vision-preview是专门的视觉模型但gpt-4o是最新且性价比更高的多模态模型通常推荐使用后者。成本提示视觉模型调用按输入图片的 Token 数计费。高分辨率、细节丰富的图片 Token 消耗很大。在服务器代码中通常会有对图片进行压缩或缩小的预处理逻辑以控制成本部署前建议阅读相关代码。配置 Memos 连接# Memos 配置 MEMOS_API_URLhttp://你的memos服务器IP:5230/api/v1 MEMOS_ACCESS_TOKEN你刚才在Memos中创建的令牌 MEMOS_VISIBILITYPRIVATE # 笔记可见性PRIVATE, PROTECTED, PUBLICMEMOS_API_URL确保此 URL 能从运行 QuickNote 服务器的容器或主机访问到。如果 Memos 和 QuickNote 服务器在同一台机器且使用 Docker Compose 一起启动可以使用服务名如http://memos:5230/api/v1。MEMOS_ACCESS_TOKEN填入上一步获取的令牌。MEMOS_VISIBILITY默认PRIVATE即可笔记仅自己可见。配置服务器行为SERVER_PORT3000 ENABLE_CORStrue # 如果客户端与服务器不在同一域名下需开启SERVER_PORT是 QuickNote 服务监听的端口。ENABLE_CORS如果设为true需要确保在生产环境中配置好安全的白名单避免成为开放接口。启动服务docker-compose up -d使用docker-compose logs -f server查看日志确认无报错。看到类似Server is running on port 3000的日志即表示成功。3.3 客户端配置打造无缝触发体验服务器就绪后我们需要在苹果设备上配置触发入口。导入并修改 iOS 快捷指令在 iPhone 或 iPad 的 Safari 浏览器中打开项目提供的 iCloud 快捷指令链接 。点击“获取快捷指令”然后在快捷指令 App 中打开它。这是最关键的一步点击快捷指令右上角的“...”进行编辑。找到名为“QuickNote Server”的“获取URL内容”操作。将其中的 URL 修改为你刚刚部署的服务器地址例如http://你的服务器IP:3000/upload。如果你的服务器配置了 HTTPS 和域名则使用https://yourdomain.com/upload。保存修改。为快捷指令分配合适的触发方式iPhone 15 Pro 系列或更新机型的操作按钮这是最优雅的方式。进入设置-操作按钮滑动到最右边的“快捷指令”然后选择你刚刚修改好的“QuickNote”指令。之后在任何界面长按操作按钮即可触发截图和上传。辅助触控小白点在设置-辅助功能-触控-辅助触控中可以为“单点”、“长按”等手势分配该快捷指令。背部轻点在设置-辅助功能-触控-轻点背面中设置。主屏幕小组件将快捷指令添加到主屏幕点击即可运行。在 macOS 上实现全局热键触发 macOS 本身没有独立的快捷指令应用但可以通过“Raycast”或“Alfred”这类效率工具完美解决。安装 Raycast免费版足够使用。打开 Raycast输入Import Extension选择Import from Clipboard。你需要一个将 iOS 快捷指令桥接到 macOS 的方法。一个常见的方案是在 macOS 的“快捷指令”App 中创建一个同名指令其内容是通过“Shell脚本”操作调用curl命令模拟向你的服务器发送图片。但更简单的方法是直接使用 Raycast 的 Script 命令。在 Raycast 中新建一个 Script Command脚本命令语言选择zsh或bash内容核心是#!/bin/bash # 1. 触发系统截图并保存图片到临时文件 screencapture -i /tmp/quickshot.png # 2. 使用 curl 将图片发送到你的 QuickNote 服务器 curl -X POST -F image/tmp/quickshot.png -F prompt http://你的服务器IP:3000/upload # 3. 清理临时文件可选 rm /tmp/quickshot.png保存该脚本然后在 Raycast 中为其设置一个全局热键例如CmdShiftQ。现在在任何界面按下这个热键就会触发截图并发送到你的服务器进行处理。4. 高级定制与优化技巧基础功能跑通后你可以根据个人需求对系统进行深度定制这是发挥其最大威力的关键。4.1 提示词工程教会模型如何做笔记服务器在调用模型时会发送一个系统提示词System Prompt和用户提示词User Prompt。系统提示词定义了模型的角色和任务通常在服务器代码中固定。而用户提示词则可以通过 iOS 快捷指令在截图时动态输入原快捷指令中有一个“询问每次运行”的文本框。默认提示词分析典型的系统提示词可能是“你是一个专业的笔记助手。请将用户提供的图片中的文字和信息清晰、有条理地提取出来并以 Markdown 格式组织。如果图片中包含代码请保留其格式。如果图片是图表或草图请描述其内容。”个性化定制方向领域特化如果你是程序员可以强化代码提取和解释“专注于提取图片中的代码片段确保语法正确并推断其可能的功能。如果是错误信息尝试分析原因。”输出结构化要求模型以固定模板输出便于后续自动化处理。例如“请以以下 YAML 格式总结图片内容然后附上详细说明title: , keywords: [], summary: , details:”结合上下文在快捷指令中可以设计在截图前先询问“这是什么场景”如“会议白板”、“论文段落”、“网页文章”然后将这个答案作为用户提示词的一部分发送帮助模型更好地理解意图。修改服务器提示词你需要找到服务器代码中构造请求给模型 API 的部分通常在server/index.js或类似文件中修改system或messages数组中的内容。修改后需要重启 Docker 容器 (docker-compose restart server)。4.2 存储后处理与现有知识系统联动Memos 是一个很好的收件箱但你可能希望将处理后的笔记自动同步到 Obsidian、Notion 或 Logseq 等更强大的知识管理工具中。方案一利用 Memos 的 Webhook 或 API如果支持。当 Memos 中创建了新笔记时触发一个自定义服务将笔记内容转发到其他平台。方案二定时同步脚本。这是更通用的方法。写一个简单的脚本Python/Node.js定期调用 Memos API (GET /api/v1/memo) 获取最新笔记然后通过 Obsidian 的第三方插件 API 或 Notion 的 API 创建页面。方案三推荐将 Memos 作为中转站直接修改 QuickNote 服务器代码。在服务器成功调用模型并生成 Markdown 后除了保存到 Memos可以同时调用另一个服务的 API如 Obsidian 的 REST 插件obsidian-remotely-save或 Notion API实现“一发双存”。这样更直接延迟更低。4.3 性能、成本与隐私优化图片压缩在服务器端在对图片进行 Base64 编码前先使用类似sharp的库进行压缩和缩放。将长边限制在 1024-2048 像素之间通常能在保持可读性的前提下将 API 调用的 Token 成本降低 70% 以上。模型降级与缓存对于简单的、以文字为主的截图如纯文本网页可以尝试使用更便宜的模型如gpt-3.5-turbo配合 OCR 服务但需要额外集成。或者对于完全相同的图片 URL比如你重复截了同一张图可以在服务器端增加一个简单的内存或 Redis 缓存直接返回之前的结果。完全离线部署这是隐私的终极方案。你需要在拥有 GPU 的机器上部署一个开源视觉语言模型如 LLaVA。这需要一定的技术能力和硬件资源。修改 QuickNote 服务器的代码将 API 调用指向本地模型的 HTTP 服务端点通常使用ollama或vLLM等框架部署。优点数据完全不出局域网零 API 成本。缺点初始化复杂模型效果和速度可能不及顶级商用 API。5. 常见问题排查与实战心得在实际搭建和使用过程中你几乎一定会遇到下面这些问题。这里是我踩过坑后总结的排查清单和解决方案。5.1 连接与服务器问题问题现象可能原因排查步骤与解决方案iOS 快捷指令运行后提示“无法连接到服务器”或超时。1. 服务器地址/端口错误。2. 服务器未运行。3. 防火墙/安全组阻止。4. 服务器内部错误。1.检查地址在手机浏览器访问http://你的服务器IP:3000/health如果服务器有健康检查端点或http://你的服务器IP:3000看是否有响应。2.检查日志docker-compose logs -f server查看服务器是否正常启动有无报错。3.检查网络确保手机和服务器在同一网络或服务器公网IP/域名可被访问。检查云服务器的安全组规则是否开放了3000端口。4.简化测试在电脑上用curl命令测试curl -X POST -F image/path/to/test.png http://服务器IP:3000/upload。服务器日志显示调用模型 API 失败如 401, 429。1. API 密钥错误或过期。2. 账单欠费或额度用尽。3. 请求速率超限。1.核对密钥检查.env文件中的OPENAI_API_KEY等密钥确保无误且未包含多余空格。2.检查账单登录对应 API 提供商的控制台查看额度和账单状态。3.降低频率如果是 429 错误说明请求太快需在代码中增加请求间隔或使用指数退避重试。笔记成功生成但未保存到 Memos。1. Memos API URL 或 Token 错误。2. Memos 服务不可访问。3. 笔记可见性设置冲突。1.检查 Memos 配置确认.env中的MEMOS_API_URL和MEMOS_ACCESS_TOKEN正确。可以在服务器所在容器内用curl测试 Memos APIcurl -H Authorization: Bearer $TOKEN $MEMOS_API_URL/memo。2.检查 Memos 运行状态docker-compose logs -f memos。3.检查网络连通性确保 QuickNote 服务器容器能访问到 Memos 容器的网络在 Docker Compose 中默认在同一网络下。5.2 模型与内容生成问题问题现象可能原因排查步骤与解决方案生成的 Markdown 格式混乱或包含大量无关描述。系统提示词不够精确模型“自由发挥”过度。优化提示词在系统提示词中加强指令。例如“请只提取图片中的文本内容不要添加任何解释性、描述性或总结性语句。如果图片是纯文本请直接输出文本。如果是混合内容以最简洁的列表或段落呈现。”中文内容识别错误率高或出现乱码。1. 模型对中文训练数据不足某些早期或特定模型。2. 图片分辨率或清晰度问题。1.切换模型尝试gpt-4o、claude-3-sonnet等对中文支持更好的模型。2.优化图片质量确保截图清晰避免背景过于复杂。在服务器端预处理时不要过度压缩导致文字模糊。3.在提示词中指定语言在系统提示词开头加入“请使用中文回复。”或“Please respond in Chinese.”。对于复杂图表、表格提取效果差。视觉模型对结构化数据的理解存在局限。1.分而治之对于复杂图表可以尝试先截图整体再对关键部分局部截图分别提取。2.使用专用工具对于表格可以配合使用专门的 OCR 表格提取工具如paddleocrtable-structure-recognition将结果作为文本输入给 LLM 进行整理。这需要修改服务器代码集成更多工具链。API 调用成本过高。图片尺寸过大Token 消耗剧增。强制压缩图片在服务器端代码中在处理图片前先将其长边缩放至固定值如 1024px并转换为 JPEG 格式降低质量如 80%。这能大幅减少 Token 数而对文字识别精度影响很小。5.3 实操心得与进阶建议从“截图”到“思考”的转变使用 QuickNote 的最佳状态不是机械地截取一切而是在按下快捷键前的那一秒快速思考“我想从这张图中提炼什么”。是保存一段代码记录一个想法还是归档一个网页参考这个短暂的思考能帮助你后续更好地利用生成的笔记。善用“提示词”字段iOS 快捷指令中那个可选的输入框非常强大。截图前花一秒钟输入“总结核心论点”、“提取代码中的函数签名”、“将会议要点整理为待办列表”模型生成的结果会精准得多。这相当于给 AI 一个明确的指令。建立定期回顾与整理习惯QuickNote 解决了“输入”的摩擦但“处理”和“内化”仍需人工。建议每周或每两周花一点时间浏览 Memos 中由 QuickNote 创建的笔记为其添加更详细的标签合并相关笔记或将精华部分转移到你的主力知识库。避免让 Memos 成为一个只进不出的“数字垃圾场”。备用方案与降级处理任何依赖外部 API 的服务都可能不稳定。可以在服务器代码中增加容错逻辑当主要模型 API 调用失败时自动降级到简单的 OCR 服务如 Tesseract.js提取文字虽然失去了理解和结构化能力但至少保留了文本内容保证工作流不中断。安全第一永远不要将你的服务器 API 地址和端口不加保护地暴露在公网。至少应该配置 Nginx 反向代理并设置 HTTPS甚至可以添加简单的 HTTP Basic Authentication 或通过防火墙限制仅允许来自你常用 IP 地址的请求。你的截图可能包含敏感信息。搭建并熟练使用 QuickNote 的过程本身就是一个极佳的学习项目。它让你亲身体验了如何将前沿的 AI 能力多模态大模型封装成一个解决具体日常痛点信息碎片化的实用工具。当你能够一键将屏幕上任何有价值的信息转化为可搜索、可连接的知识节点时那种流畅感和掌控感是任何现成的笔记软件都无法完全提供的。这不仅仅是安装了一个工具而是为你自己的数字工作流安装了一个“智能感官”。