Trilium笔记集成AI对话侧边栏：本地部署与高效知识管理实践

1. 项目概述在Trilium笔记中集成AI对话侧边栏如果你和我一样是Trilium笔记的重度用户同时又经常需要借助ChatGPT来辅助写作、翻译或者整理思路那么来回切换浏览器标签和笔记软件的过程绝对称得上是一种“生产力割裂”。每次都要复制、粘贴对话上下文还容易丢失体验非常碎片化。今天要聊的这个项目——trilium-chat就完美地解决了这个痛点。它是一个纯前端插件能直接在Trilium笔记的界面里嵌入一个功能完整的ChatGPT聊天侧边栏。简单来说它把你的私人知识库Trilium和强大的AI大脑ChatGPT或本地Ollama无缝连接在了一起。你可以在编写笔记时随时按AltQ调出聊天窗口让AI帮你润色段落、解释概念、生成代码甚至基于当前笔记内容进行深度问答和扩展。更棒的是它并非一个简单的API调用封装而是深度集成了Trilium的笔记管理能力支持将对话历史、AI回复一键保存为笔记或者插入到当前光标位置真正实现了“所思即所得所得即所存”。这个项目由soulsands开发代码基于原生JavaScript结构清晰对于想学习Trilium插件开发的朋友来说也是一个很好的参考案例。接下来我会从设计思路、安装配置、核心功能使用到高级玩法和避坑指南为你完整拆解这个插件的方方面面。2. 核心设计思路与架构解析2.1 为什么是“前端插件”trilium-chat被设计成一个前端插件这是理解其所有特性的关键。在Trilium的架构中前端插件通过#runfrontendStartup属性标记的JavaScript笔记会在用户浏览器中加载并执行。这意味着数据安全与隐私你的OpenAI API密钥或与本地Ollama的通信完全发生在你的浏览器与相应的API服务器之间。对话数据不会经过任何第三方服务器。插件本身只是一个“中介”负责组织请求和渲染界面。深度集成UI作为前端代码它可以自由操作Trilium的DOM创建浮动窗口、侧边栏、按钮并监听全局快捷键实现与Trilium原生界面无缝融合的体验。依赖Trilium环境插件能直接调用Trilium提供的内部API如api对象来获取当前活动笔记、创建子笔记、读写属性等。这也是其“保存到笔记”、“插入内容”等核心功能得以实现的基础。这种设计在灵活性和安全性上取得了很好的平衡。开发者无需搭建后端服务用户也无需担心数据泄露。2.2 插件运行机制与数据流理解插件如何工作有助于你在遇到问题时快速定位。其核心数据流可以概括为以下几步初始化当你为JS笔记添加#runfrontendStartup属性并刷新Trilium后该脚本自动执行。它会创建两个子笔记一个用于存放配置#CHAT_OPTIONS一个用于存放提示词模板#CHAT_PROMPTS并在Trilium界面右上角注入一个聊天图标按钮。用户交互点击按钮或按下快捷键默认AltQ会触发聊天窗口的显示/隐藏。你在输入框中的内容结合可能选中的提示词模板会被组装成符合OpenAI或Ollama API格式的请求消息。API请求插件使用浏览器原生的fetchAPI将请求发送到你配置的requestUrls.completion地址默认是OpenAI官方接口。如果你的API密钥已配置请求头中会包含Authorization: Bearer your-api-key。流式响应处理当engineOptions.stream设置为true时默认插件会处理服务器返回的SSEServer-Sent Events流实现打字机式的逐字输出效果体验更佳。数据持久化对话记录可以根据设置自动或手动保存。插件会调用Trilium API在指定的历史笔记#CHAT_HISTORY_HOME下以笔记树的形式存储完整的对话上下文包括时间、角色和内容。整个过程中插件像一个智能的“粘合剂”将Trilium的笔记操作、前端的用户界面、以及远程或本地的AI服务连接成一个流畅的工作闭环。3. 详细安装与初始化配置3.1 插件安装的两种方式安装trilium-chat非常简单本质上就是往你的Trilium笔记库中添加一个特殊的JavaScript笔记。方法一直接创建JS笔记推荐这是最清晰的方式便于日后查看和管理插件代码。在Trilium中在你希望放置插件的地方例如“脚本”目录下新建一个笔记。将笔记的**类型Type**设置为“JavaScript”。打开项目的GitHub Release页面例如https://github.com/soulsands/trilium-chat/releases找到最新版本的trilium-chat.js文件用文本编辑器打开复制其全部内容。回到Trilium将复制的内容粘贴到这个JS笔记的内容区。给这个笔记添加一个属性Attribute。键为#run值为frontendStartup。注意#号是属性标签的一部分表示这是一个“标签”类型的属性。方法二导入JS文件如果你已经下载了trilium-chat.js文件到本地可以直接在Trilium中使用“文件 - 导入 - 导入Trilium .tar文件”功能。但需要注意的是.js文件本身不是.tar格式此方法通常用于导入由Trilium导出的完整笔记子树。因此对于单个插件文件方法一更为直接可靠。注意添加#runfrontendStartup属性是最关键的一步。没有这个属性Trilium不会在启动时执行这段前端脚本插件也就不会加载。添加属性后图标通常不会立即出现需要刷新一次Trilium页面F5。3.2 初始配置与API密钥设置刷新页面后插件会自动进行初始化你会观察到两个变化在刚创建的JS笔记下会自动生成两个子笔记分别名为“trilium-chat-options”和“trilium-chat-prompts”。这说明插件已成功加载。Trilium界面右上角会出现一个聊天气泡图标。接下来配置API密钥点击打开“trilium-chat-options”这个笔记。它的内容是一个JSON对象这就是插件的配置文件。找到apiKey这一项其默认值为空字符串。你需要将你的OpenAI API密钥填写在这里格式为apiKey: sk-你的实际密钥。如何获取API密钥访问 OpenAI平台 登录后即可创建。安全提醒这个密钥保存在你的本地Trilium数据库中。只要你保管好数据库文件.db文件密钥就是安全的。但切勿将此笔记内容分享给他人。保存这个选项笔记CtrlS然后再次刷新Trilium页面。至此基础配置完成。现在你可以点击右上角的聊天图标或者按下AltQ快捷键唤出聊天侧边栏开始与ChatGPT对话了。3.3 界面与基础操作速览首次打开侧边栏你会看到一个简洁的界面左上角一个随机变换的表情图标增加趣味性。顶部输入框用于输入你的问题或指令。输入框右侧按钮分别是“提示词选择”、“命令菜单”和“历史记录”。中部区域对话内容显示区用户消息居右AI回复居左支持Markdown渲染如代码块、粗体等。底部状态显示当前使用的模型和令牌消耗情况。几个高效快捷键AltQ显示/隐藏聊天侧边栏。Esc快速隐藏侧边栏。在输入框中输入/p 空格快速打开提示词选择列表。/c 空格快速打开命令菜单。/h 空格快速打开历史记录面板。在历史或提示词面板中Tab/ShiftTab切换选项Enter确认选择。4. 核心功能深度使用指南4.1 提示词模板打造你的AI指令库这是trilium-chat最具威力的功能之一。它允许你将常用的、复杂的指令保存为模板并通过变量实现动态交互。模板存储与结构所有提示词模板都保存在自动生成的“trilium-chat-prompts”笔记中。每个子笔记就是一个模板笔记的标题就是模板的名称笔记的内容就是模板的正文。Mustache语法与动态变量模板使用双花括号{{}}来定义变量这借鉴了Mustache模板语法但在此处有特定的含义和渲染方式。选项变量{{variableName:Option1|Option2|Option3}}例如一个翻译模板的内容可以是将以下文本翻译成 {{targetLang:英文|中文|日文|法文}}\n\n{{message}}当你使用这个模板时聊天界面会渲染出一个下拉选择框让你动态选择要翻译成的语言。{{message}}则是一个占位符会自动替换成你在输入框中实际输入的内容。活动笔记变量{{activeNote}}这是一个特殊变量它会获取你当前在Trilium中选中或正在编辑的笔记的全部内容。例如你可以创建一个“总结”模板请用简洁的语言总结以下笔记的核心内容\n\n{{activeNote}}。当你选中一篇长笔记后调用此模板AI就会基于该笔记内容进行总结。实战应用创建自定义模板假设我想创建一个“代码审查”模板在“trilium-chat-prompts”笔记下新建一个子笔记。将标题命名为“代码审查”。在内容区写入请以资深开发者的身份审查以下 {{language:Python|JavaScript|Go|Java}} 代码 1. 指出潜在的bug或逻辑错误。 2. 评估代码风格和可读性。 3. 提出性能优化建议如有必要。 4. 输出格式请使用Markdown列表。 代码 {{language}} {{activeNote}}保存笔记。 现在当我在Trilium中查看一段代码笔记时只需在聊天侧边栏输入/p选择“代码审查”模板再选择代码语言插件就会自动将当前代码笔记的内容填入并发送给AI进行审查。这极大地提升了重复性工作的效率。重要提示由于Trilium内部以HTML格式存储富文本笔记当{{activeNote}}变量被替换时发送给AI的实际上是HTML代码。这为AI提供了更多格式信息如加粗、标题等但有时也可能引入干扰。对于纯代码笔记建议使用Trilium的“代码”类型笔记这样获取到的内容是纯净的代码文本。4.2 命令系统打通笔记与对话的桥梁命令系统定义了如何将对话内容“沉淀”到你的Trilium知识库中这是实现“对话即生产”的关键。对话线程Thread命令这些命令作用于整个对话会话即从你打开侧边栏开始到关闭或新建对话为止的所有消息交换。复制将整个对话的文本内容复制到系统剪贴板。保存到历史将当前对话保存为历史记录。如果开启了autoSave默认开启此过程会自动进行。手动执行此命令会强制保存一次。收藏为当前对话打上“收藏”标记。被收藏的对话会在历史记录中优先显示并有一个旗帜图标。保存到活动笔记用当前对话的完整内容替换当前活动笔记的原有内容。此操作不可逆请谨慎使用。追加到活动笔记将当前对话的完整内容添加到当前活动笔记的末尾。保存为新子笔记在当前活动笔记下创建一个新的子笔记并将对话内容存入其中。这是最安全、最常用的归档方式。单条消息Message命令这些命令作用于AI回复的某一条具体消息。复制复制该条消息内容。插入这是极其高效的功能。它会将这条AI回复的内容插入到你当前活动笔记的光标所在位置。想象一下你让AI生成一段代码解释然后直接将其插入到你正在编写的技术文档中无需任何复制粘贴操作。保存到活动笔记/追加到活动笔记与线程命令类似但仅针对单条消息操作。操作路径在聊天界面点击输入框右侧的“命令”图标或按/c即可根据当前上下文是在查看整个对话还是选中了某条消息看到相应的命令菜单。4.3 历史记录管理构建可追溯的AI协作日志所有保存的对话都会存储在历史记录中。插件会寻找带有#CHAT_HISTORY_HOME标签的笔记作为历史记录的“家”。如果没找到则使用默认的“trilium-chat”笔记。历史记录的结构每一条保存的对话都会在历史记录主页下创建一个子笔记。笔记的标题通常是对话的第一条用户消息或时间戳笔记内容则完整记录了该次对话的所有回合User和Assistant交替。这种以笔记树的形式保存历史让你可以利用Trilium全文搜索快速找到过去就某个话题的讨论。建立链接将重要的AI对话笔记链接到相关的项目或知识笔记中。重构与合并像管理普通笔记一样对历史对话进行整理、重命名、移动。高效检索打开历史面板/h输入框会自动聚焦。你可以输入关键词进行过滤用键盘上下键或Tab键选择Enter键即可加载该历史对话到当前聊天窗口实现对话的延续或复盘。5. 高级配置连接本地Ollama模型对于注重隐私、希望完全本地运行或想试用开源大模型的用户trilium-chat支持连接到本地部署的Ollama服务。这需要一些额外的配置步骤。5.1 配置插件指向Ollama首先确保你已在本地安装并运行了Ollama例如运行了ollama run llama3命令模型已拉取并服务在http://localhost:11434。然后修改“trilium-chat-options”笔记中的配置修改requestUrls.completion将其值从OpenAI的端点改为你Ollama服务的聊天API端点。例如https://localhost:11434/api/chat。如果你通过局域网IP或域名访问则替换为对应的地址。修改engineOptionsmodel改为你在Ollama中使用的模型名如llama3、qwen2.5:7b等。stream必须设置为false。因为Ollama的流式响应格式与OpenAI不完全兼容关闭流式可以保证稳定通信。apiKey这个字段在连接本地Ollama时通常不需要但插件可能仍会发送一个空或随机的字符串。你可以将其留空或者填入任意字符因为本地服务一般不验证。其他参数temperature、max_tokens等参数依然有效可以根据Ollama模型的特点进行调整。一个连接本地Ollama的配置示例如下{ viewWidth: 400, engine: ChatGpt, // 这个字段名称可以保留不影响功能 apiKey: ollama-local-no-need-key, // 可填任意值或留空 requestUrls: { completion: http://localhost:11434/api/chat // Ollama本地API地址 }, engineOptions: { model: llama3.2, // Ollama中的模型名称 max_tokens: 2048, temperature: 0.7, top_p: 1, presence_penalty: 0, frequency_penalty: 0, stream: false, // 关键必须设为false n: 1 }, shortcut: { toggle: AltQ, hide: Esc }, autoSave: true, systemPrompt: , checkUpdates: true }5.2 解决跨域CORS问题当你将Trilium通常通过浏览器访问如http://localhost:8080连接到localhost:11434的Ollama服务时浏览器会因同源策略而阻止请求并在控制台报CORS错误。解决方案一配置Ollama服务推荐这是最根本的解决方法。通过设置环境变量让Ollama服务端允许来自Trilium前端的请求。Linux/macOS在启动Ollama前设置环境变量。export OLLAMA_ORIGINShttp://localhost:8080 ollama serve或者如果你使用systemd服务可以修改服务文件如/etc/systemd/system/ollama.service在[Service]部分添加EnvironmentOLLAMA_ORIGINShttp://localhost:8080然后重启服务。Windows在PowerShell中设置环境变量后启动。$env:OLLAMA_ORIGINShttp://localhost:8080 ollama serve你也可以在系统环境变量中永久添加OLLAMA_ORIGINS值为http://localhost:8080。通配符不推荐用于生产如果你图省事可以设置为*来允许所有来源但这会降低安全性。export OLLAMA_ORIGINS*解决方案二使用Nginx反向代理适用于复杂网络环境如果你通过Nginx将Ollama暴露在网络上例如https://ollama.your-domain.com则需要在Nginx配置中添加CORS响应头。server { listen 80; server_name ollama.your-domain.com; location / { proxy_pass http://localhost:11434; proxy_set_header Host $host; # 关键添加CORS头 add_header Access-Control-Allow-Origin http://localhost:8080 always; add_header Access-Control-Allow-Methods GET, POST, OPTIONS always; add_header Access-Control-Allow-Headers DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization always; # 处理OPTIONS预检请求 if ($request_method OPTIONS) { add_header Access-Control-Allow-Origin http://localhost:8080; add_header Access-Control-Allow-Methods GET, POST, OPTIONS; add_header Access-Control-Allow-Headers DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization; add_header Access-Control-Max-Age 1728000; add_header Content-Type text/plain; charsetutf-8; add_header Content-Length 0; return 204; } } }配置完成后重启Nginx并将插件配置中的requestUrls.completion改为你的Nginx代理地址如https://ollama.your-domain.com/api/chat。5.3 验证连接与调试完成配置后刷新Trilium页面尝试在聊天侧边栏中发送一条消息。成功你会看到来自本地模型的回复响应速度通常很快取决于你的硬件。失败打开浏览器的开发者工具F12切换到“网络Network”选项卡查看发送到Ollama端点的请求。重点关注CORS错误如前所述检查响应头是否包含Access-Control-Allow-Origin。404错误检查API端点路径是否正确Ollama的聊天接口是/api/chat。401/403错误检查是否错误地配置了apiKey或者Ollama服务端有额外的认证要求默认没有。6. 配置项详解与个性化定制“trilium-chat-options”笔记中的JSON配置提供了丰富的个性化选项。我们来逐一拆解其含义和调整建议。配置项描述默认值调整建议与说明viewWidth聊天侧边栏的宽度像素。400可以直接在界面上拖动侧边栏左边缘调整调整后会自动更新此配置。engineAI提供商。目前UI上固定但配置可改。chatGpt连接Ollama时也可保留此值不影响功能。apiKeyOpenAI API密钥。必填项如果用OpenAI。连接本地Ollama时可填任意值或留空。requestUrls请求URL。目前仅completion有效。OpenAI端点连接Ollama时修改为http(s)://你的地址/api/chat。engineOptions发送给AI服务的请求参数。见下方详表这是调优AI行为的核心。不同模型支持的参数可能不同。shortcut控制聊天界面的键盘快捷键。{toggle: AltQ, hide: Esc}可按喜好修改但需确保不与Trilium或系统快捷键冲突。faces左上角随机显示的表情图标类名。一组BoxIcon类名可自定义需使用Trilium内置的图标库类名。增加更多类名让表情更丰富。colors表情图标的颜色。[var(--muted-text-color)]可使用CSS变量或具体颜色值如[#ff6b6b, #4ecdc4]。autoSave是否在对话结束后自动保存历史。true设为false可完全手动控制保存适合临时性对话。systemPrompt系统提示词用于设定AI的角色和行为。例如设为你是一位严谨的科技文档编辑。可让AI回复风格更统一。checkUpdates是否自动检查插件更新。true开启后当GitHub有新版时表情图标上会显示一个小圆点提示。engineOptions参数深度解析model: 指定使用的模型。对于OpenAI可以是gpt-3.5-turbo,gpt-4等对于Ollama是你本地拉取的模型名。max_tokens: 限制AI单次回复的最大令牌数。需注意这包括输入和输出的总和。设置过低可能导致回复被截断。对于长文写作可适当调高如4000。本地模型需根据其上下文长度调整。temperature(0~2):控制创造性与随机性。值越低如0.1回复越确定、保守值越高如0.8、1.2回复越多样、有创意。对于代码生成、事实问答建议较低0.1-0.3对于创意写作、头脑风暴可调高0.7-0.9。top_p(0~1):另一种控制随机性的方式称为核采样。通常与temperature二选一进行调整。top_p0.1意味着AI只从概率最高的前10%的令牌中选择。一般保持默认值1即可。presence_penalty(-2~2):控制话题的新颖度。正值会降低模型重复之前出现过的词语的概率有助于避免车轱辘话。对于长对话或摘要可设为0.5-1.0。frequency_penalty(-2~2):控制用词的重复度。正值会降低模型重复使用高频词的概率。与presence_penalty类似但更侧重于词频。通常两者设置相同值。stream:是否使用流式响应。true时回复会逐字显示体验好false时需等待完整生成后才显示。连接Ollama时建议设为false。n: 每次请求生成几条备选回复。通常为1。7. 常见问题排查与实战技巧7.1 安装与基础问题问题1插件安装后右上角没有出现聊天图标。检查步骤确认JS笔记的#run属性是否正确设置为frontendStartup注意拼写和大小写。确认是否已经刷新了Trilium页面F5。添加属性后必须刷新才能加载。打开浏览器开发者工具F12查看“控制台Console”是否有JavaScript错误。常见的错误可能是脚本语法错误导致加载失败。检查JS笔记的内容是否完整粘贴没有缺失或多余字符。问题2配置了API密钥但发送消息时提示“Error”或没有反应。检查步骤检查API密钥确认在选项笔记中填写的密钥是否正确是否包含多余的引号或空格。OpenAI密钥以sk-开头。检查网络确认你的网络环境可以访问api.openai.com如果使用OpenAI。可以尝试在浏览器中直接打开该地址看是否被屏蔽。查看开发者工具打开“网络Network”选项卡查看发送到OpenAI的请求状态。如果返回401是密钥错误429是额度不足或速率限制403可能是区域限制。检查额度登录OpenAI平台查看API使用额度和账单是否正常。7.2 功能使用问题问题3使用{{activeNote}}变量时AI回复的内容格式混乱包含很多HTML标签。原因Trilium的文本笔记以HTML格式存储。当插件获取活动笔记内容时拿到的是包含p,strong等标签的HTML源码。AI在理解了这些HTML后有时会模仿HTML格式进行回复。解决方案在提示词中明确要求在提示词模板末尾加上一句“请用纯文本格式回复不要包含任何HTML或Markdown格式标记。”使用代码类型笔记对于希望AI处理的纯文本或代码尽量在Trilium中使用“代码”类型的笔记来存放。插件获取代码笔记内容时得到的是纯净的文本。后期处理对于AI回复中偶尔出现的Markdown或HTML可以利用Trilium的“编辑”-“格式化”功能进行清理。问题4历史记录保存的位置不对或者我想更改保存位置。方法插件默认寻找带有#CHAT_HISTORY_HOME标签的笔记作为历史库。你可以在任意笔记上添加此标签键为#CHAT_HISTORY_HOME值可以为空之后所有新的对话历史都会保存到这个笔记之下。你可以将其放在一个专门的“AI对话存档”目录中方便管理。问题5快捷键AltQ与系统或其他软件冲突。修改方法直接编辑“trilium-chat-options”笔记中的shortcut.toggle值。例如可以改为CtrlShiftC。修改后保存并刷新页面即可生效。注意快捷键格式需符合规范且避免与Trilium内置快捷键冲突。7.3 连接Ollama专属问题问题6配置了Ollama但出现CORS错误。解决方案这是最常见的问题。请严格按照第5.2节的步骤配置Ollama服务的OLLAMA_ORIGINS环境变量。配置后需要重启Ollama服务ollama serve进程。在浏览器中检查网络请求的响应头确认包含了Access-Control-Allow-Origin: http://localhost:8080。问题7连接Ollama时请求长时间无响应或超时。检查步骤确认Ollama服务正在运行。在终端执行ollama list看是否有输出。确认API地址和端口正确。默认是http://localhost:11434。确认模型已成功拉取并加载。尝试在命令行直接运行ollama run llama3看是否能正常对话。检查浏览器网络请求看是否发送成功。如果Ollama服务端处理慢尤其是首次加载大模型可能会导致超时。可以尝试在插件配置中增加max_tokens限制或使用更小的模型。问题8Ollama回复的内容是乱码或格式异常。可能原因某些模型特别是早期或小众模型的输出格式可能不太稳定或者对系统提示词的处理与ChatGPT不同。尝试解决在systemPrompt中明确指定输出格式例如“请始终使用中文回复并以清晰、有条理的段落呈现。”调整temperature参数将其调低如0.1减少随机性。在提示词模板中更详细地约束输出格式例如“请按以下结构回复首先给出结论然后分点列出原因最后提供示例。不要使用Markdown标题符号。”7.4 性能与优化技巧技巧1管理对话历史体积长时间使用后历史记录笔记可能会变得很大影响Trilium的启动和搜索速度。建议定期归档旧对话将不常访问的历史对话子树移动到归档目录或导出为文件后删除。选择性保存关闭autoSave只对有价值的对话手动执行“保存到历史”。清理测试记录定期检查历史库删除无意义的测试对话。技巧2为不同场景创建提示词文件夹“trilium-chat-prompts”本身也是一个笔记你可以在其下创建子笔记来分类管理提示词。例如创建“写作”子笔记存放“润色”、“扩写”、“总结”等模板。创建“编程”子笔记存放“代码解释”、“生成单元测试”、“SQL转换”等模板。 这样在使用/p调用时结构更清晰。技巧3利用系统提示词systemPrompt设定AI角色systemPrompt会影响整个对话上下文中AI的底层行为。你可以将其设置为“你是一位乐于助人且言简意赅的助手。”通用“你是一位技术文档专家擅长将复杂概念用通俗易懂的语言解释。”技术问答“你是一位严格的校对员专注于纠正语法、拼写和标点错误并优化句子流畅度。”文本校对 设置后无需在每个用户消息中重复角色指令AI会始终保持该角色设定。