1. 项目概述在笔记软件里塞进一个AI助手如果你和我一样是个重度笔记软件用户尤其是Trilium的爱好者那你肯定有过这样的体验正在整理笔记、构思文章突然需要一个AI助手来帮忙润色、翻译或者解答一个技术问题。这时候你不得不离开笔记界面打开浏览器登录某个AI服务把内容复制过去再把结果复制回来。这个过程不仅打断了思路还让信息流变得支离破碎。soulsands/trilium-chat这个项目就是为了解决这个痛点而生的。它是一个纯前端插件能让你在Trilium笔记软件内部直接呼出一个侧边栏聊天窗口无缝对接ChatGPT或者你自己本地部署的Ollama大语言模型。简单来说它把你的笔记软件变成了一个集成了强大AI能力的“智能工作台”。想象一下你正在写一篇技术博客选中一段代码按个快捷键AI就能帮你解释逻辑或者你正在整理外文资料选中文本AI就能帮你翻译并总结。这种“所想即所得”的流畅感正是这个插件带来的核心价值。作为一个在笔记管理和知识整合领域折腾了十多年的老用户我深知工具链的顺畅对工作效率和创作心流的影响有多大。这个插件将AI能力深度嵌入到笔记的上下文中而不是作为一个孤立的工具存在这个设计理念非常打动我。接下来我将从设计思路、安装配置、深度使用到问题排查为你完整拆解这个插件并分享我在实际使用中积累的经验和踩过的坑。2. 核心设计思路与架构解析2.1 为什么是“纯前端”插件看到项目介绍里强调“This project is written in vanilla JavaScript, and is a frontend-only project”时很多开发者可能会好奇一个需要调用外部API如OpenAI或本地Ollama的功能如何能仅靠前端实现这恰恰是这个插件设计巧妙的地方。它的核心原理是利用了现代浏览器提供的fetchAPI和Trilium Notes自身强大的前端扩展能力。插件本身不包含任何后端服务器代码它只是一个运行在你浏览器Trilium实例中的JavaScript脚本。当你发起对话时这个脚本会直接从前端也就是你的浏览器向配置好的API端点比如api.openai.com或你本地的ollama.internal.network发起HTTPS请求。这意味着所有的API密钥和通信数据都只在你本地浏览器和AI服务提供商之间流动插件脚本只是一个“信使”。这种设计带来了几个显著优势极致轻量无需部署额外的服务安装即用对Trilium服务端零侵入。隐私可控你的对话数据不会经过任何第三方中转服务器当然如果你使用OpenAI官方API数据会经过OpenAI的服务器这是服务本身的性质决定的。如果你使用本地Ollama那么所有数据完全在本地局域网内。配置灵活你可以轻松切换不同的AI后端只需修改API地址和密钥无需改动插件代码。注意这种纯前端调用API的方式也意味着你必须确保你的Trilium实例通常是浏览器页面能够访问你配置的API端点。如果你将Trilium部署在服务器上并通过浏览器远程访问那么API请求是从你的浏览器发出的所以你的浏览器所在网络必须能访问OpenAI或你的本地Ollama。这是一个常见的配置误区。2.2 深度集成不只是弹个聊天窗市面上有很多浏览器插件也能在任意页面侧边栏呼出ChatGPT那trilium-chat的独特性在哪里答案是与Trilium数据模型的深度集成。它不仅仅是悬浮在页面上而是能够读取和操作你当前的笔记内容。插件通过Trilium提供的frontendAPI可以获取到当前激活的笔记activeNote的全部内容。这使得“自定义提示词Prompt”功能变得无比强大。你可以在提示词模板中插入{{activeNote}}变量AI在回答时就能基于你正在编辑的笔记内容进行上下文理解。例如你可以创建一个“总结”提示词“请用中文总结以下笔记的核心观点{{activeNote}}”。当你在这个笔记中激活该提示词AI就能直接对笔记内容进行总结。此外对话历史History的保存、将AI回复保存为笔记子项Save to new child note、或直接插入Insert到当前笔记光标处这些操作都直接与Trilium的笔记树、属性系统交互。这种集成度让AI从“外部顾问”变成了“内部协作者”真正融入了你的知识生产流程。2.3 可扩展的提示词引擎插件的提示词系统支持Mustache语法这提供了一个简单的模板渲染能力。比如{{language:English|Chinese|French}}会在界面上渲染成一个下拉选择框。这看似是个小功能实则极大地提升了高频任务的效率。你不用每次都手动输入“请翻译成中文”而是可以创建一个名为“翻译”的提示词内容为“将以下文本翻译成{{language:English|Chinese|French}}{{message}}”。使用时只需选择目标语言即可。这种设计鼓励用户建立自己的提示词库将常用的、结构化的AI指令模板化、资产化沉淀在Trilium中成为个人知识库的一部分。这也是我强烈推荐的使用方式不要只把它当聊天机器人而是把它当作一个可编程的智能文本处理管道。3. 从零开始的完整安装与配置指南3.1 环境准备与插件安装首先你需要一个正在运行的Trilium实例。无论是桌面版还是自部署的服务器版均可。安装过程非常简单但有几个细节需要注意。获取插件文件访问项目的GitHub Release页面下载最新的trilium-chat.js文件。或者你也可以直接复制该文件的内容。创建前端笔记在Trilium中新建一个笔记。笔记类型选择“JavaScript前端”JS frontend。这是关键一步因为只有这种类型的笔记才能在浏览器前端执行代码。粘贴代码并设置属性将trilium-chat.js文件的全部内容粘贴到这个新建的笔记中。然后为该笔记添加一个属性Attribute。属性名称:#run属性值:frontendStartup这个属性告诉Trilium在每次前端界面加载时自动执行这个笔记里的JavaScript代码。示意图在笔记属性面板中添加#runfrontendStartup重启前端保存笔记后你需要刷新Trilium的浏览器页面按F5或点击刷新按钮。这是必须的步骤因为插件需要在Trilium启动时被加载。实操心得刷新后你应该立即检查。如果安装成功你会在Trilium主界面的右上角看到一个聊天图标通常是一个笑脸或对话气泡。同时在刚刚创建的脚本笔记下会自动生成两个子笔记一个标签为#CHAT_OPTIONS配置选项一个标签为#CHAT_PROMPTS提示词库。如果没看到请检查浏览器控制台F12是否有JavaScript错误并确认#run属性设置正确。3.2 核心配置详解连接你的AI大脑插件安装成功后下一步就是告诉它去哪里找AI。点击右上角的聊天图标或按默认快捷键AltQ呼出侧边栏第一次使用会提示你需要配置API密钥。配置OpenAI ChatGPT API打开自动生成的#CHAT_OPTIONS子笔记。其内容是一个JSON对象。找到apiKey字段将你的OpenAI API密钥填入其中。密钥需要到 OpenAI平台 申请。其他关键参数在engineOptions里model: 模型名称如gpt-3.5-turbo或gpt-4。根据你的API权限选择。max_tokens: 单次回复的最大令牌数影响回复长度。注意这个数字加上你提问的令牌数不能超过模型上下文上限如gpt-3.5-turbo是4096。temperature: 温度参数控制随机性0-2。值越低如0.3回答越确定、保守值越高回答越随机、有创造性。对于笔记辅助、代码生成等任务建议设置在0.1-0.5之间以保证输出的稳定性。stream: 是否启用流式输出。设为true时回复会像打字一样逐字显示体验更好。建议保持开启。一个典型的OpenAI配置片段如下{ apiKey: sk-你的真实API密钥, engineOptions: { model: gpt-3.5-turbo, max_tokens: 2000, temperature: 0.3, stream: true } }配置本地Ollama 如果你在本地或内网部署了Ollama希望获得完全私密的AI体验配置会稍有不同。修改requestUrls.completion将其值从OpenAI的端点改为你的Ollama服务的聊天API地址例如http://localhost:11434/api/chat或https://your-ollama-server.com/api/chat。修改engineOptions.model改为你Ollama中拉取的模型名如llama3、qwen2.5:7b或mistral。关键一步将engineOptions.stream设置为false。截至我测试时插件对Ollama的流式响应支持可能有问题关闭流式可以保证稳定通信。apiKey字段对于Ollama通常不是必须的可以留空或随意填写但字段需存在。不过如果Ollama服务设置了认证则需要填写相应的密钥。一个典型的Ollama配置示例如下{ apiKey: ollama-not-needed-but-keep-field, // 可留空但字段建议保留 requestUrls: { completion: http://192.168.1.100:11434/api/chat // 你的Ollama服务器地址 }, engineOptions: { model: llama3:8b, // Ollama中的模型名称 max_tokens: 2500, temperature: 0.3, stream: false // 使用Ollama时建议先关闭流式 } }配置完成后同样需要刷新Trilium页面以使新配置生效。3.3 解决Ollama的CORS与网络问题配置本地Ollama时90%的问题都出在网络和CORS跨域资源共享上。浏览器的安全策略禁止前端页面向不同域名或同域名不同端口随意发送请求除非对方服务器明确允许。问题现象在Trilium中配置好Ollama后发送消息出现网络错误浏览器控制台F12 - Console显示类似Access-Control-Allow-Origin的错误。解决方案 你需要让Ollama服务器在响应中添加允许跨域的头部。有以下几种方法启动Ollama时设置环境变量推荐最简单 在启动Ollama服务前设置OLLAMA_ORIGINS环境变量。在Linux/macOS的终端或Windows的PowerShell中# Linux/macOS export OLLAMA_ORIGINS* ollama serve # 或者在一行内完成 OLLAMA_ORIGINS* ollama serve # Windows (PowerShell) $env:OLLAMA_ORIGINS* ollama.exe serve*表示允许所有来源对于本地开发测试最方便。在生产环境或对安全有要求时可以替换为具体的Trilium访问地址如http://localhost:8080。通过Nginx反向代理适合已部署Web服务的用户 如果你通过Nginx将Ollama暴露在互联网或局域网内可以在Nginx配置中添加CORS头部。server { listen 80; server_name ollama.your-domain.com; # 你的域名或IP location / { proxy_pass http://localhost:11434; # 转发到Ollama本地端口 proxy_set_header Host $host; # 关键添加CORS头部 add_header Access-Control-Allow-Origin *; add_header Access-Control-Allow-Methods GET, POST, OPTIONS; add_header Access-Control-Allow-Headers Authorization, Content-Type; # 处理OPTIONS预检请求 if ($request_method OPTIONS) { add_header Access-Control-Allow-Origin *; add_header Access-Control-Allow-Methods GET, POST, OPTIONS; add_header Access-Control-Allow-Headers Authorization, Content-Type; return 204; } } }修改配置后记得重启Nginx (sudo nginx -s reload)。踩坑记录我最初在Docker中运行Ollama并通过另一个容器中的Nginx代理。当时只配置了proxy_pass忘了加CORS头部导致一直连接失败。在浏览器开发者工具的“网络(Network)”选项卡中看到OPTIONS请求返回404或没有CORS头部才定位到问题。所以遇到网络问题首先打开浏览器开发者工具查看网络请求和响应头这是最直接的排查手段。4. 高效使用技巧与场景实战4.1 自定义提示词打造你的AI流水线插件的提示词功能是其精髓。不要满足于简单的问答试着构建一个属于你自己的“智能指令集”。创建提示词点击聊天界面顶部的提示词按钮或按/p快捷键打开提示词面板。点击“新建”或直接在#CHAT_PROMPTS笔记下创建子笔记。笔记的标题就是提示词名称内容就是提示词模板。在模板中使用变量{{message}} 代表你在输入框中输入的问题。{{activeNote}} 代表当前激活的笔记的全部内容。{{optionName:Choice1|Choice2|Choice3}} 创建一个下拉选择框。例如{{tone:专业|口语化|幽默}}。实战案例1笔记智能总结提示词标题总结核心观点提示词内容你是一名专业的文本分析助手。请阅读以下笔记内容提取并列出3-5个最核心的观点或事实要求表述简洁、准确。 笔记内容 {{activeNote}} 核心观点总结使用方法当你阅读一篇长文笔记时直接激活此提示词AI会自动分析当前笔记并输出总结无需你复制粘贴任何内容。实战案例2代码审查与解释提示词标题解释代码逻辑提示词内容你是一名资深{{language:Python|JavaScript|Go|Java}}开发者。请分析以下代码片段逐行解释其核心逻辑、关键函数/方法的作用并指出任何潜在的改进点或可能的风险。 代码 {{language}} {{activeNote}}分析报告使用方法在Trilium中编写或粘贴一段代码选中该笔记然后使用此提示词。你可以通过下拉框选择编程语言AI会给出针对性的分析。实操心得将{{activeNote}}用于代码笔记时AI接收到的实际上是笔记的HTML源码。这对于简单的代码片段没问题但如果笔记中包含复杂的Trilium特有格式如加密区块、关系图可能会干扰AI的理解。最佳实践是为AI交互创建专门的、格式纯净的文本或代码笔记或者使用“仅发送选中文本”的功能如果插件后续支持。4.2 命令系统让AI输出融入知识库AI的回复不是终点如何将其沉淀到你的知识体系中才是关键。插件的命令系统提供了多种保存方式。命令触发位置功能描述适用场景Copy消息/会话复制单条消息或整个会话到剪贴板临时需要将内容粘贴到其他地方Save to history会话将当前会话保存到聊天历史默认自动开启手动备份重要对话Favor会话收藏当前会话在历史中置顶并标记标记有价值的对话便于快速找回Save to active note消息覆盖式保存用AI回复完全替换当前激活笔记的内容用AI生成的内容直接作为笔记终稿谨慎使用Append to active note消息追加式保存将AI回复添加到当前激活笔记的末尾将AI的补充说明、翻译结果附加到原笔记后面Save to new child note消息/会话将AI回复或整个会话保存为当前激活笔记的子笔记最推荐的方式保持原笔记不变生成关联的新知识节点Insert消息插入式保存将AI回复插入到当前激活笔记的光标所在位置在编辑笔记时让AI在指定位置补充内容体验最流畅最佳实践工作流收集与提问在笔记A中记录原始信息或问题。AI处理使用{{activeNote}}变量调用提示词让AI基于笔记A的内容进行处理。保存结果对AI的回复使用“Save to new child note”命令。这会在笔记A下创建一个子笔记B内容就是AI的回复。建立关联这样笔记A原始材料和笔记BAI加工成果就形成了清晰的父子关系在你的知识图谱中结构完整溯源方便。重要提醒慎用“Save to active note”覆盖保存除非你确定要丢弃原内容。我曾在一次翻译任务中误操作导致原始英文笔记被翻译后的中文直接覆盖无法找回。对于任何有价值的原始材料先备份或确保使用“子笔记”模式进行保存。4.3 快捷键与界面定制熟练使用快捷键能极大提升效率。插件默认提供了几个AltQ显示/隐藏聊天侧边栏。Esc隐藏聊天侧边栏。在输入框内输入/p快速打开提示词选择面板。输入/c快速打开命令面板针对当前会话或消息。输入/h快速打开历史记录面板。你可以在#CHAT_OPTIONS的shortcut配置项中修改这些快捷键。例如如果AltQ与其他软件冲突可以改为CtrlShiftC。shortcut: { toggle: CtrlShiftC, hide: Escape }侧边栏的宽度可以通过拖动其左侧边缘实时调整调整后的宽度会自动保存在配置中viewWidth项。5. 常见问题排查与故障解决即使配置正确在实际使用中也可能遇到各种问题。下面是我遇到的一些典型情况及其解决方法。5.1 插件未加载或图标不显示症状刷新Trilium后右上角没有出现聊天图标按AltQ也无反应。检查1脚本属性确认存放插件代码的笔记其#run属性的值是否为frontendStartup注意拼写。检查2笔记类型确认该笔记的类型是“JavaScript前端”JS frontend而不是普通的文本或代码笔记。检查3浏览器控制台按F12打开开发者工具查看“控制台(Console)”是否有红色错误信息。常见的错误包括JS语法错误、Trilium API调用失败等。根据错误信息进行搜索或排查。检查4多次刷新有时Trilium前端加载需要时间尝试刷新1-2次。5.2 发送消息失败提示API错误症状能打开聊天界面但发送消息后收到错误提示如“Network Error”、“API key invalid”或“Failed to fetch”。针对OpenAI错误401或Invalid API Key检查apiKey是否正确是否包含多余的引号或空格。确保你的OpenAI账户有余额并且API密钥未被禁用。错误429或Rate limit exceeded请求过于频繁免费额度用完或达到速率限制。需要等待或升级账户。错误404或Model not found检查engineOptions.model名称是否正确例如gpt-3.5-turbo不能写成gpt-3.5。针对Ollama错误Failed to fetch或Network Error检查地址和端口确认requestUrls.completion中的IP和端口号默认11434是否正确Ollama服务是否正在运行ollama serve。检查CORS这是最常见的问题。务必按照前文【3.3】节配置Ollama的CORS。在浏览器开发者工具的“网络(Network)”选项卡中查看对Ollama的请求通常是/api/chat检查响应头是否包含Access-Control-Allow-Origin: *。检查流式设置尝试将engineOptions.stream设置为false。错误Model xxx not found检查engineOptions.model名称是否与Ollama中拉取的模型名完全一致。使用ollama list命令查看本地模型列表。5.3 提示词变量{{activeNote}}工作不正常症状使用包含{{activeNote}}的提示词时AI似乎没有接收到笔记内容或接收到的是乱码。原因1笔记格式{{activeNote}}发送的是笔记的HTML源码。如果笔记是富文本格式且非常复杂可能会包含大量HTML标签干扰AI。解决尝试将笔记类型改为“纯文本(Text)”或“代码(Code)”再试一次。对于AI处理纯文本往往是最干净的。原因2空笔记或未激活确保你当前确实有一个笔记窗口处于激活选中状态。原因3插件缓存尝试完全重启Trilium桌面版退出重开网页版刷新并清除缓存。5.4 对话历史丢失或无法保存症状关闭聊天窗口或刷新后之前的对话记录不见了。检查自动保存确认#CHAT_OPTIONS中的autoSave设置为true。检查历史存储位置历史记录默认保存在标签为#CHAT_HISTORY_HOME的笔记下。如果该笔记被意外删除或移动插件可能无法保存。检查脚本笔记下是否存在该笔记。手动保存如果自动保存失效对于重要的会话记得在关闭前使用“Save to history”命令进行手动保存。5.5 性能问题与优化建议响应慢网络问题如果使用远程OpenAI API速度取决于你的网络和OpenAI的服务状态。可尝试切换时段。模型过大如果使用本地Ollama且模型参数很大如70B模型响应速度取决于你的硬件。考虑使用量化后的较小模型如llama3:8b-instruct-q4_K_M。流式输出延迟确保stream设置为trueOpenAI或falseOllama以获得最佳体验。Trilium卡顿如果对话历史非常长可能会轻微影响Trilium性能。定期清理不必要的历史记录。可以将重要的对话通过“Save to new child note”保存为正式笔记然后从历史中删除。经过一段时间的深度使用trilium-chat插件已经成了我在Trilium中不可或缺的“副驾驶”。它成功地将生成式AI的“灵光一现”与笔记软件的“沉淀积累”这两个环节无缝衔接了起来。最大的体会是工具的价值不在于功能多炫酷而在于它是否能嵌入到你现有的工作流中减少摩擦提升心流。这个插件做到了。从最初的简单问答到后来构建起一套自己的提示词库用于翻译、总结、代码审查和头脑风暴它让我处理信息和创作内容的方式发生了细微但深刻的变化。如果你也生活在Trilium里强烈建议花点时间配置和调教它这可能是对你笔记工作流一次极有效率的小小升级。