第六课 TriliumAI Agent：让个体掌控OpenClaw

上一课我们深入探讨了TriliumAI Chat——那座架在AI模型与个人知识库之间的桥梁。你了解了它如何让AI拥有"记忆"、如何将对话沉淀为知识资产、如何通过Gutenberg提示词块让普通人也能设计AI工作流。

但如果你实际使用过TriliumAI Chat，可能会发现一个问题：AI确实可以"读"你的Trilium笔记了，但这个"读"的方式还比较间接——你需要手动告诉AI去查哪些笔记、需要在聊天框里调用命令、需要自己判断应该把哪些知识喂给AI。

TriliumAI Agent解决的正是这个"最后一公里"的问题。

如果说TriliumAI Chat是一条"道路"——连通了AI与知识库两端，那么TriliumAI Agent就是在这条道路上行驶的“智能车辆”和多智能体Hub。它不只是让你手动搬运知识给AI，而是提供了一套完整的工具来——搜索笔记、浏览知识树、批量导出、一键注入AI记忆、甚至用一条命令完成"搜索→导出→喂给AI"的全自动流水线。

更关键的是，它引入了"多智能体"（Multi-Agent）架构——你可以配置多个AI Agent，每个Agent连接不同的知识库、使用不同的AI模型、存储不同的记忆。这意味着你可以拥有一个"研究助手Agent"、一个"编程伙伴Agent"、一个"写作顾问Agent"，它们各自拥有与角色匹配的知识背景和能力配置。

本课将延续上一课确立的双维度分析框架：先从开发视角理解架构思想和关键技术选择，再从使用视角掌握全部功能的实战操作。同样，我们的核心关注点不是代码本身，而是：这些设计决策背后的思考，以及它们如何改变一个人与知识和AI协作的方式。

第一部分：开发视角——Agent的架构哲学与技术选择

一、母女插件架构：一种值得深思的生态设计

1. 三代同堂：从Trilium WP到AI Agent 🏛️

在上一课中，我们讨论了Trilium WP → TriliumAI Chat的两层架构。现在，随着TriliumAI Agent的加入，这个生态形成了更完整的三代关系：

Trilium WP（祖父辈）—— 基础数据通道
    └── TriliumAI Chat（母插件）—— AI对话界面与工作流编排
          └── TriliumAI Agent（子插件）—— 知识操作引擎与整合了OpenCode和OpenClaw的多智能体系统

每一代都严格遵循"只做自己该做的事"原则：

• Trilium WP负责最底层的"管道铺设"——让WordPress能够通过ETAPI与Trilium Notes双向通信
• TriliumAI Chat负责"交互界面"——提供浮动聊天窗口、消息渲染、流式输出、提示词管理、Gutenberg工作流编排
• TriliumAI Agent负责"执行能力"——提供笔记搜索与浏览、内容导出与格式转换、多AI后端接入（OpenCode和OpenClaw）、多智能体管理、记忆注入系统

这三层之间的依赖关系是单向的：Agent依赖Chat，Chat依赖WP，但反过来不成立。这意味着你可以只安装Trilium WP（纯数据通道）、或者安装WP+Chat（数据通道+AI对话）、或者安装全部三个（完整的AI知识工作台）。每多安装一层，能力就多一层，但上层的存在不影响下层的正常运行。

2. "母女"而非"依赖"：一种更准确的理解 👩‍👧

代码中将TriliumAI Chat称为"母插件"、Agent称为"女儿插件"，这个比喻比"主从关系"更准确。母亲提供了基础的生存环境（聊天界面、钩子系统、用户交互），女儿在此基础上发展出自己的独立能力（知识操作、多智能体、协议桥接），但女儿的能力反过来也极大地丰富了母亲能做的事情。

技术上，这种关系通过WordPress的过滤器钩子实现：

• 母插件定义了 trilium_ai_chat_providers 过滤器——"谁想注册AI提供者，来报名"
• Agent通过这个过滤器注册了OpenCode和OpenClaw两个新的AI后端——"我带来了两个新的AI引擎"
• 母插件定义了 trilium_ai_chat_register_commands 过滤器——"谁想注册聊天命令，来报名"
• Agent注册了 /oc、/send、/prompt 三套命令——"我带来了知识操作、快速保存和提示词管理的能力"

注册完成后，母插件的聊天界面自动出现了新的AI提供者选项和新的命令。母插件的代码没有修改一行——它甚至不"知道"Agent的存在，只是遵循自己的过滤器约定接纳了新的能力。

这种设计的深远意义在于：生态的扩展不需要修改已有代码。 未来任何开发者都可以用同样的方式——通过注册提供者和命令——为这个生态添加新的AI后端或新的知识操作能力。这不是一个封闭的"产品"，而是一个开放的"平台"。

3. 启动时序：为什么Agent在母插件之后加载？ ⏱️

一个看似微小但至关重要的细节：Agent注册在WordPress的 plugins_loaded 钩子上，优先级设为20——而WordPress的默认优先级是10。这意味着Agent总是在母插件加载完毕之后才初始化。

为什么这很重要？因为Agent在初始化时需要使用母插件提供的过滤器。如果Agent比母插件先加载，它注册提供者和命令时母插件还不存在，过滤器还没有被定义——注册就会失败。

Agent在初始化前还会检查母插件是否已激活——如果母插件缺失，Agent不会报错崩溃，而是在后台显示一条友好的管理员通知，然后安静地退出。这种"优雅降级"的思维确保了即使用户不小心只安装了Agent而没装Chat，WordPress也不会出现白屏或报错。

二、多智能体系统：为不同的"你"配备不同的AI

1. 为什么需要多个Agent？ 🤔

想象一下你的日常工作场景：

早上你在做学术研究，需要AI帮你分析文献——你希望AI连接到你的"学术笔记库"，使用推理能力最强的模型，拥有关于你研究方向的长期记忆。

下午你在写代码，需要AI帮你调试——你希望AI连接到你的"项目文档库"，使用编程专用的模型，能直接读取你的代码仓库文件。

晚上你在整理每日见闻，需要AI帮你总结——你希望AI连接到你的"日常笔记库"，使用快速廉价的模型，只保留今天的上下文。

如果只有一个全局配置，你每次切换场景都要去后台修改设置——换知识库地址、换API密钥、换模型选择。这不仅麻烦，而且容易出错（忘了切回来怎么办？）。

TriliumAI Agent的多智能体系统让你一次性配置好多个Agent，每个Agent都是一个完整的"角色配置档案"——包含它连接的Trilium实例、使用的AI后端和模型、文件存储位置、认证凭据等。切换Agent就像切换用户身份一样简单。

2. 配置继承：只记录"差异" 📐

多智能体系统在配置管理上采用了一个精巧的设计——配置继承。

系统先有一套"全局默认配置"，包含所有设置项的默认值。每个Agent只需要存储与全局不同的部分——比如"研究Agent"可能只覆盖了Trilium Token和知识库地址两个字段，其他所有设置（OpenCode端口、文件浏览器路径等）都直接继承全局值。

当系统需要获取某个Agent的完整配置时，它先加载全局默认值，然后把Agent的覆盖项叠加上去——Agent定义了的字段用Agent的值，没定义的字段用全局值。

这种设计的好处是双重的：

存储效率。 十个Agent如果每个都存储全部配置，就是十份完整拷贝。使用继承后，如果十个Agent只是OpenClaw的Agent ID不同，那总共只多存储十个字段而非十套完整配置。

维护便利。 当你修改全局的Trilium服务器地址时（比如服务器迁移了），所有没有单独覆盖这个字段的Agent都自动更新。你不需要逐个修改十个Agent的配置。

这个思路在软件工程中有一个正式名称——原型继承（Prototypal Inheritance）。JavaScript的对象系统就是基于同样的原理。但在这里，它被巧妙地用一个简单的数组合并（array_merge）实现，不需要任何类层次结构——这是"用最简单的工具解决真实问题"的范例。

3. Agent切换：从技术到体验 🔄

在聊天界面上，切换Agent只是一个下拉菜单的操作。但在幕后，这个操作触发了一系列精心编排的动作：

1. 前端向WordPress后端发送切换请求，携带新Agent的ID
2. 后端查找新Agent的配置（合并全局默认值和Agent覆盖项）
3. 后端返回新Agent的完整连接参数——包括AI网关地址、认证令牌等
4. 前端检查：如果新Agent的网关地址与当前Agent不同，需要断开现有连接并重新连接到新的地址；如果地址相同，只需在现有连接上切换Agent身份
5. 切换完成后广播一个事件，所有相关模块（工作区、会话列表、记忆面板等）同步更新自己的状态

在这个过程中，有一个经过多次迭代才解决的状态管理问题值得关注——"谁是Agent ID的权威来源？"。

早期版本中，多个JavaScript模块各自维护了一份Agent ID的副本。当用户快速切换Agent时，不同模块更新的时间差会导致"A模块以为当前是Agent-1，B模块以为是Agent-2"的状态不一致问题。

最终的解决方案是建立"唯一真相来源"（Single Source of Truth）原则——只有一个核心模块存储Agent ID，其他所有模块需要Agent ID时都去问这个核心模块，而不是使用自己的副本。代码中保留了版本演进的注释记录，从v2.7.0的多源混乱到v2.7.3的单源统一，这段演进本身就是一堂生动的状态管理课。

三、协议桥接：让不同语言的AI"说同一种话"

1. 问题的本质 🌐

TriliumAI Agent需要接入两个截然不同的AI后端：

• OpenCode：使用Server-Sent Events（SSE）——一种基于HTTP的单向实时通信协议
• OpenClaw：使用WebSocket——一种全双工的实时通信协议

而母插件TriliumAI Chat的聊天界面只"听得懂"一种语言——SSE格式的HTTP响应（这是OpenAI等主流AI API的标准格式）。

如果没有翻译层，OpenClaw的WebSocket消息就无法在母插件的聊天界面中显示。而修改母插件来支持WebSocket不仅工程量大，还破坏了母女插件之间的独立性原则。

Agent的解决方案是：不改变任何一方的"语言"，而是在中间做实时翻译。

2. OpenCode路径：独立的SSE代理 📡

OpenCode使用SSE，母插件也期望SSE——看起来不需要翻译？问题在于WordPress本身。

WordPress的请求处理机制本质上是"接收请求→处理→一次性返回完整响应"。但SSE要求服务器保持连接不断开，逐步推送数据。WordPress的输出缓冲、插件系统和各种中间件都会干扰这个过程，导致数据被缓存后一股脑发出，而非逐字流式推送。

Agent的做法非常果断——绕过WordPress。 它创建了一个独立的PHP脚本（SSE代理），这个脚本不走WordPress的正常请求流程，只加载最基本的数据库访问能力。它做的事情很纯粹：接收前端的请求，转发给OpenCode，然后把OpenCode返回的SSE事件逐条实时透传给前端浏览器。

但绕过WordPress意味着失去了WordPress的安全保护（登录验证、Nonce令牌等）。为此，代理实现了自己的安全机制——基于HMAC-SHA256的加密令牌。在WordPress正常页面加载时生成令牌并存储，代理脚本在接收请求时验证令牌的有效性和用户身份。令牌有时效性（一小时过期），绑定用户身份，使用WordPress的加密盐作为密钥——在WordPress框架之外复制了等效的安全保障。

这个"跳出框架"的设计决策体现了一个重要的工程判断：当框架的设计约束与你的需求根本冲突时，绕过框架可能是比硬塞进去更正确的选择。 框架是工具，不是信仰。

3. OpenClaw路径：TransformStream协议桥接 🌉

如果说SSE代理是"绕过障碍"，那么OpenClaw的协议桥接就是真正的"翻译"——而且是一种极其精巧的翻译。

问题回顾：母插件通过 fetch() 发送HTTP请求，期望收到一个SSE格式的HTTP响应。OpenClaw通过WebSocket通信，完全不走HTTP。

Agent的解决方案利用了浏览器的TransformStream API——一种可以创建"管道"的现代Web技术。这个管道有两端：一端可以写入数据，另一端可以读取数据。

当母插件发起聊天请求时：

1. Agent的拦截器在请求到达网络之前截获它
2. 创建一个TransformStream管道
3. 用管道的可读端构造一个伪造的HTTP Response对象，Content-Type设为 text/event-stream（SSE格式）
4. 把这个伪造的Response立即返回给母插件——母插件开始从中读取数据
5. 同时，通过WebSocket把用户消息发送给OpenClaw
6. 当OpenClaw的回复通过WebSocket逐块到达时，将每一块翻译成SSE格式，写入管道的可写端
7. 写入的数据自动通过管道流到可读端——母插件读到了"SSE事件"
8. 母插件完全不知道这些"SSE事件"其实来自WebSocket

这就像一个同声传译——发言者说的是WebSocket方言，听众期望的是SSE方言，翻译者实时把每一句话从一种方言转换为另一种方言。母插件（听众）始终以为自己在听SSE，OpenClaw（发言者）始终以为自己在说WebSocket。双方都不需要改变任何东西。

从工程角度看，这个设计的价值在于它实现了"透明代理"——母插件的代码、OpenClaw的协议、整个系统的其他部分都不需要做任何调整。新的AI后端通过翻译层无缝接入了现有的聊天界面。这种能力意味着未来任何新的AI服务——无论它使用什么通信协议——都可以通过编写一个类似的翻译层接入系统。

4. 三重拦截：防御性的集成思维 🛡️

为了实现上述协议桥接，Agent需要在母插件的HTTP请求发出之前拦截它们。但母插件可能使用jQuery的 $.ajax、$.post，或者浏览器原生的 fetch() 来发送请求——三种不同的接口。

Agent的做法是同时拦截这三种接口。每种接口被拦截后，首先检查这个请求是否是聊天请求且目标是OpenClaw——如果是，走WebSocket翻译路径；如果不是，原样放行不做任何干预。

为什么要同时拦截三种？因为母插件的实现细节可能随版本更新而改变——今天它用 $.ajax，明天的更新可能改用 fetch()。如果Agent只拦截了其中一种，母插件一旦切换就会导致集成断裂。三重拦截提供了"防御性兼容"——无论母插件怎么改变HTTP发送方式，Agent都能正确拦截。

这是"面向变化编程"的实际范例：不要假设你依赖的代码永远不变，而是为它可能的变化预留容错空间。

四、记忆系统：三种时间尺度的知识注入

1. 为什么AI需要三种"记忆"？ 🧠

人类的记忆并非铁板一块——我们有工作记忆（正在思考的内容）、长期记忆（沉淀的知识和经验）和情景记忆（与特定时间地点关联的记忆）。TriliumAI Agent的三层记忆系统几乎是对这个结构的直接映射。

会话记忆（Session Memory）——对应工作记忆 💭

范围：仅限当前对话。对话结束即消失。 方式：将选中的Trilium笔记格式化为上下文文本，注入聊天输入框。用户可以在发送前审查和编辑。 适用场景：一次性的、针对特定问题的知识补充。比如"我现在要问AI关于这篇论文的问题，让我先把论文内容作为上下文给它看。"

长期记忆（Long-Term Memory）——对应沉淀的知识 📚

范围：跨所有对话持续存在，直到手动清除。 方式：将笔记内容写入AI Agent的一个持久化文件（如 MEMORY.md）。AI在每次对话开始时都会自动读取这个文件。 适用场景：Agent角色的"基础知识"。比如"我的研究Agent应该始终了解我的研究领域、方法论偏好和已有成果"，或者"我的编程Agent应该始终遵循我们团队的代码规范"。

每日记忆（Daily Memory）——对应情景记忆 📅

范围：持续一个日历日。每天自动产生独立的记忆文件（memory/YYYY-MM-DD.md）。 方式：与长期记忆相同的文件写入机制，但存储在按日期命名的文件中。 适用场景：与特定时间相关的上下文。比如"今天的会议纪要"、"今天的研究进展"、"今天需要处理的待办事项"。

2. 一个关键的设计洞察：零AI消耗的知识注入 ⚡

长期记忆和每日记忆的写入操作直接通过文件API完成——不经过AI模型处理，不消耗任何AI推理资源。 这是一个刻意的设计决策（代码中有明确的版本注释标注）。

为什么这很重要？因为向AI注入大量上下文（比如一次性注入十篇笔记的内容）可能消耗大量的Token（AI按处理的文本量计费）。如果每次注入都要经过AI"消化"，成本会迅速攀升。

通过直接操作文件系统绕过AI推理层，记忆注入变成了一个几乎免费的操作——你可以把整个项目文档、一学期的学习笔记、或者一个领域的全部积累一股脑注入Agent的记忆中，而不用担心AI账单。AI只有在你真正提问时才开始"思考"和计费。

3. 记忆管理：可查、可清、可重置 🗂️

记忆不是"注入了就不管了"。工作区模块提供了完整的记忆管理面板：

这种"可管理的记忆"与大多数AI产品的"黑箱记忆"形成了鲜明对比。你不仅可以控制AI记住什么，还可以随时查看它记住了多少、主动让它忘掉过时的内容。这是"主权个人"理念在AI记忆管理上的体现——你对AI的认知状态拥有完全的控制权。

五、笔记导出管道：从HTML到AI可用的知识

1. 为什么需要格式转换？ 🔄

Trilium Notes存储笔记内容为HTML格式——这在浏览器中显示很好，但对AI来说并不理想。HTML中充满了标签、样式属性和结构代码，这些在AI眼中都是"噪音"，会占用宝贵的上下文窗口而不提供有价值的信息。

Markdown则是AI最喜欢的格式之一——简洁、结构清晰、几乎没有格式噪音。同样的内容，Markdown表示通常只有HTML的三分之一到一半大小。

Agent内置了一个完整的HTML到Markdown转换器，能够正确处理：标题层级、段落和换行、粗体/斜体/删除线/行内代码等行内格式、带语言标注的代码块、有序和无序列表（包括嵌套）、链接和图片、表格（包括对齐方式）、引用块和水平分隔线。

2. 完整的导出流水线 🏭

转换只是导出流程的一个环节。完整的管道是：

Trilium笔记 → 获取HTML内容 → 转换为Markdown → 添加元数据头
    → 上传到FileBrowser → 返回文件路径 → 路径注入AI聊天输入

元数据头包含笔记标题、原始笔记ID和导出时间戳，让AI知道这段内容来自哪里、什么时候导出的。

FileBrowser是一个Web端的文件管理器，充当了"AI可以读取的文件柜"。OpenCode等AI编程助手就是通过文件系统来获取上下文的——它们能读取指定路径的文件内容。把Trilium笔记导出为文件并上传到FileBrowser，就相当于把知识放到了AI"伸手就能拿到"的位置。

这条流水线的每一步都可能失败（Trilium不可达、转换出错、FileBrowser认证过期等），因此插件在每一步都做了独立的错误处理。当批量导出多篇笔记时，即使其中某些笔记导出失败，其余的仍然继续处理——最终报告成功和失败的明细，而不是"一个失败全部中止"。这种"部分成功"的容错策略在处理外部服务时是更务实的做法。

3. FileBrowser认证的精巧缓存 ⚡

FileBrowser使用JWT（JSON Web Token）认证。每次调用FileBrowser的API前，都需要先登录获取Token。如果每次导出每篇笔记都重新登录一次，不仅浪费时间，还可能触发限流。

Agent将JWT Token缓存在WordPress的临时存储（Transient）中，有效期一小时。缓存键包含了FileBrowser的URL和用户名的哈希——这意味着当不同的Agent配置了不同的FileBrowser实例时，它们各自拥有独立的Token缓存，互不干扰。一小时后Token过期，下次请求会自动重新登录，对用户完全透明。

六、工作流自动化：从手动操作到一条命令

1. /oc workflow：搜索、导出、注入一气呵成 🚀

让我们对比一下手动操作和自动化工作流的区别：

手动方式（5~10分钟）：

1. 在工作区搜索关键词
2. 浏览搜索结果，选中需要的笔记
3. 点击"导出"，等待每篇笔记转换和上传
4. 复制导出的文件路径
5. 粘贴到聊天输入框
6. 编写提示词并发送

自动化方式（10秒）：

/oc workflow 人工智能伦理

一条命令——搜索Trilium中所有关于"人工智能伦理"的笔记，导出每一篇，收集文件路径，格式化为AI可以引用的文本。整个流水线自动执行，失败的笔记被跳过并报告。

这看起来只是节省了几分钟时间。但真正的价值在于降低了认知负荷——你不需要记住"先搜索、再选择、再导出、再复制路径"这一串操作步骤。一条命令就表达了完整的意图："把我知识库中关于这个主题的内容给AI看"。

2. /send：灵感即刻捕捉 💾

在与AI对话的过程中，AI可能产出一段你想保存的分析、一个你想记住的洞见、或者一个值得后续跟进的思路。传统做法是：复制内容 → 打开Trilium → 新建笔记 → 粘贴 → 回到聊天窗口。

现在只需：

/send 关于DAO治理的新洞见 | AI刚才提出了一个有趣的观点：去中心化治理的核心矛盾不在于效率与公平的平衡，而在于...

管道符前是标题，管道符后是内容。一条命令，笔记直接创建在Trilium中你配置的目标文件夹下。如果你连标题都懒得想，可以省略管道符——系统会自动生成一个包含日期的标题。

这个功能的意义在于：它把"保存到知识库"的摩擦力降到了接近于零。 当保存变得几乎不费力气时，你会更愿意去保存那些"可能有价值"的内容——而恰恰是这些看似不起眼的片段，日后可能成为重要洞见的种子。

3. /prompt：提示词的组织化管理 📋

如果你经常使用某些提示词模板（比如"帮我对比分析以下两种观点的优劣"、"把以下内容改写为适合公开发表的版本"），可以通过 /prompt 命令将它们组织化：

• /prompt add 观点对比 请帮我对比分析以下两种观点... —— 保存
• /prompt use 观点对比 —— 调用（自动填入输入框，你可以修改后再发送）
• /prompt list —— 列出所有已保存的提示词
• /prompt delete 观点对比 —— 删除

上限50条，足够覆盖大多数人的常用提示词库。

七、开发者需要的知识清单（概要）

如果你想构建类似的系统，以下是核心知识领域的概要（上一课已详细讨论了基础部分，此处聚焦Agent特有的技术需求）：

第二部分：使用篇——构建你的AI知识工作台

八、安装与配置

1. 安装前提 📋

必需项：

• WordPress 5.0+（使用Gutenberg功能需5.8+），PHP 7.4+
• TriliumAI Chat母插件已安装并启用
• 至少一个AI后端：OpenCode实例 或 OpenClaw账户

推荐项（解锁全部能力）：

• Trilium Notes实例（通过ETAPI进行知识操作）
• FileBrowser实例（用于笔记导出——仅OpenCode路径需要）
• TriliumAI Agent子插件本身（你正在学习的这个）

2. 安装步骤 📥

1. 确保TriliumAI Chat母插件已安装且处于启用状态
2. 登录WordPress后台 → 插件 → 安装插件 → 上传插件
3. 选择 trilium-ai-agent-2.8.1.zip，点击安装
4. 安装完成后点击"启用"

启用后，WordPress后台侧边栏会出现"TriliumAI Agent"菜单项，同时母插件的聊天界面中会出现新的AI提供者选项。

3. 配置详解 🔧

进入"TriliumAI Agent"设置页面，你会看到两个标签页。

标签页一："通用设置"——全局默认配置

这里配置的是所有Agent共享的默认值。如果你只使用一套服务，只需要配置这里即可。

Trilium Notes连接 🗃️：

• Trilium URL：你的Trilium服务器地址（如 https://trilium.example.com）
• ETAPI Token：在Trilium中生成的API访问令牌（Trilium设置→ETAPI→生成Token）
• 父笔记ID：新建笔记（如 /send 命令创建的笔记）存放的默认位置。填入目标文件夹的Note ID

OpenCode连接 💻：

• Host：OpenCode服务器地址（如 localhost）
• Port：端口号（默认 3000）
• Username / Password：OpenCode的Basic Auth认证凭据

FileBrowser连接 📁：

• URL：FileBrowser服务器地址
• Username / Password：登录凭据
• Upload Path：导出的笔记文件存放在FileBrowser上的哪个目录

OpenClaw连接 🤖：

• Gateway URL：WebSocket网关地址（如 wss://gateway.example.com）
• Auth Token：认证令牌
• Agent ID：默认使用的Agent标识

标签页二："Agents"——多智能体管理

在这里创建和管理你的多个Agent配置。

创建新Agent：

1. 输入Agent ID（唯一标识，用英文，如 research、coder、daily）
2. 输入显示名称（可中文，如"研究助手"、"编程伙伴"）
3. 只填写需要覆盖全局默认值的字段——留空的字段自动继承全局值
4. 点击保存

示例——三个Agent的配置策略：

你还可以指定一个Agent为"默认Agent"——打开聊天窗口时自动激活的那个。

九、知识操作：搜索、浏览、导出、注入

1. 工作区界面概览 🖥️

启用Agent后，母插件的聊天窗口旁边会出现一个扩展的工作区面板。这个面板分为左侧（会话管理区）和右侧（知识操作区），在窄屏幕上自动变为上下堆叠。

知识操作区提供两种浏览模式，通过顶部的切换按钮选择：

搜索模式 🔎 —— 输入关键词，在整个Trilium笔记库中全文搜索。搜索结果显示为带勾选框的列表，每条显示笔记标题、类型和ID。

浏览模式 📂 —— 从根笔记开始，以文件夹树的方式逐级浏览。点击文件夹笔记进入下一级，顶部的面包屑导航显示当前路径，点击面包屑可快速返回上级。

两种模式殊途同归——最终都是让你选中一组笔记，然后对它们执行操作。

2. 选择并操作笔记 ✅

找到你需要的笔记后，勾选它们（支持全选/全不选切换），然后根据当前使用的AI提供者，可用的操作不同：

当使用OpenCode时：

点击"导出"按钮 → 选中的笔记逐一经过导出管道（HTML→Markdown→上传到FileBrowser）→ 完成后，导出的文件路径自动以 @路径 的格式追加到聊天输入框 → 你可以在路径后面添加你的提问，然后发送。

界面会显示实时的进度指示：导出笔记 1/5...、导出笔记 2/5......导出完成！

当使用OpenClaw时：

界面会显示三个记忆模式的选择按钮，你选择一种后点击"注入"：

3. 记忆管理面板 🗂️

在OpenClaw模式下，工作区底部有一个记忆管理区域。四个操作按钮：

• 查看状态：显示各级记忆文件是否存在、文件大小
• 重置会话：清除当前对话的上下文（不影响长期和每日记忆）
• 清除长期记忆：删除持久化记忆文件
• 清除每日记忆：删除今天的记忆文件

建议定期查看记忆状态，确保Agent的"认知"是最新的。如果你更新了某个领域的笔记，记得重新注入长期记忆以覆盖旧版本。

十、AI后端的使用

1. OpenCode：编程与文件导向的AI 💻

OpenCode是一个面向编程的AI助手服务，它的核心特点是"基于文件系统工作"。你给它文件路径，它读取文件内容并分析。

会话管理

左侧面板显示所有OpenCode会话，每个会话是一个独立的对话上下文。你可以：

• 创建新会话：为新项目或新主题开一个干净的对话空间
• 切换会话：在不同对话间跳转
• 查看消息历史：包含完整的消息线程、工具调用详情和文件附件
• 删除会话：清理不再需要的对话

消息历史详情

消息历史的展示比一般的聊天记录更丰富：

• 用户消息和AI回复有不同的视觉标记（蓝色和绿色左边框）
• AI执行的工具调用（如读取文件、搜索代码）以可展开的折叠区域显示，包含工具名称、输入参数和输出结果
• 文件附件根据MIME类型显示不同的图标（代码文件、图片、文档等）
• 支持全屏查看模式（ESC键退出），适合审阅长消息
• 每条消息有复制按钮，方便提取内容

流式聊天

通过SSE代理实现的实时聊天体验：

• AI回复逐字出现，附带状态指示（连接中/已连接/已断开，以不同颜色的圆点表示）
• 内置心跳检测——每60秒检查一次连接状态，20分钟无活动自动重连
• 支持基础Markdown渲染——代码块、粗体、斜体在流式输出中即时格式化

2. OpenClaw：多智能体对话平台 🤖

OpenClaw是一个支持多Agent架构的AI对话服务。每个Agent可以有不同的模型、指令和记忆。

Agent切换

聊天界面上方出现Agent选择下拉菜单。选择不同的Agent后：

• 如果新Agent在同一个网关上：在现有WebSocket连接上切换身份
• 如果新Agent在不同网关上：断开当前连接，重连到新网关

切换后，所有相关模块自动更新——工作区、记忆面板、导出路径都会适配新Agent的配置。

对话保存

OpenClaw模式下的对话可以保存回Trilium Notes。系统实现了带回退的保存策略——如果主要的保存方法失败（比如Trilium临时不可达），会自动尝试备用方法。确保你珍贵的对话不会因为临时的网络问题而丢失。

3. 在两个后端之间切换 🔄

母插件的提供者选择器现在包含了"OpenCode"和"OpenClaw"选项。切换后，整个工作区UI自动适配——OpenCode模式显示会话管理和文件导出功能，OpenClaw模式显示记忆注入和Agent选择功能。

选择策略建议：

十一、命令系统完全指南

1. /oc 命令族——OpenCode操作 ⌨️

2. /send 命令——快速保存 💾

3. /prompt 命令——提示词管理 📋

十二、故障排查

常见问题速查 🛠️

内置诊断工具

Agent提供了两层诊断能力：

浏览器控制台诊断（按F12打开控制台，输入）：

TriliumAgentSession.diagnose('测试用的笔记ID')

会逐项测试AJAX连通性、Trilium笔记获取、会话列表等功能，输出详细的诊断报告。

后端诊断（OpenClaw专用）： 通过REST API测试网关可达性、Token格式有效性和Agent配置完整性。

十三、进阶实践与更大的图景

1. 构建你的多Agent工作台 🏗️

建议从三个基础Agent开始：

"研究者"Agent——连接你的学术/研究笔记库，使用推理能力强的AI模型，长期记忆中注入你的研究方向和方法论偏好。

"实践者"Agent——连接你的项目/工作笔记库，使用编程/实务导向的AI模型，每日记忆中注入当天的任务清单和进展。

"整理者"Agent——连接你的综合笔记库，使用快速廉价的模型，主要用于整理、摘要和归档工作。

随着使用深入，你会自然地发现更多适合拆分为独立Agent的场景——某个特定的客户项目、某门正在学习的课程、某个长期追踪的研究主题。

2. 知识循环的完整闭环 🔄

当TriliumAI Agent与Chat配合使用时，一个完整的知识循环建立起来了：

        Trilium Notes（知识库）
          ↗ /send保存     ↘ 搜索/浏览/导出
        AI对话产出     →  注入AI记忆
          ↖ 流式回复     ↙ AI生成回复
        AI引擎（OpenCode / OpenClaw）

知识从Trilium流向AI（通过搜索、导出、记忆注入），AI基于这些知识产出新的洞见，新洞见通过 /send 或对话保存流回Trilium。每一次循环都让知识库更丰富，而更丰富的知识库又让AI的下一次回答更有深度。这是一个真正的知识增长飞轮。

3. 与上一课的联动 🔗

TriliumAI Agent并不替代Chat——它们是互补的：

• Chat的Gutenberg提示词块定义了"做什么"（工作流结构）
• Agent的知识操作能力提供了"用什么做"（知识素材）
• Chat的上下文功能让AI拥有"短期记忆"（过去几次对话）
• Agent的三层记忆系统让AI拥有"长期认知"（持久化的知识背景）

一个典型的深度工作场景可能是：你在Chat中设计了一套"文献分析"的Gutenberg工作流页面（上一课学到的），然后通过Agent的 /oc workflow 命令把相关笔记批量导出给AI（这一课学到的），最后AI基于你的工作流步骤和你的笔记内容产出深度分析，而分析结果通过 /send 保存回Trilium等待下次被引用。

4. 回到"主权个人" 👤

从Brave基地的愿景来看，TriliumAI Agent在整个生态中扮演的角色是"执行引擎"——它让"拥有私有知识库"和"使用AI"这两件事之间不再有鸿沟。

在当前主流的AI使用方式中，你的知识库是你的，AI是平台的，两者之间隔着一道围墙。你只能手动翻墙搬运知识。TriliumAI Agent拆掉了这道墙——或者更准确地说，它在墙上开了很多门：搜索门、浏览门、导出门、记忆注入门、命令门、工作流自动化门。

更重要的是，多智能体系统意味着你不只有一把钥匙。你可以为不同的知识领域配备不同的AI"专家"，每个专家拥有与其角色匹配的知识背景和工具配置。这是对"人机协同"的一种更精细、更个性化的探索。

正如Brave基地在《主权个人的十倍效率时代》中所提出的——"主权个人掌控AI"的核心含义不是让每个人都去训练自己的AI模型，而是探索一种由个人主导的、深度融合的人机协同模式。TriliumAI Agent正是这种模式的一块关键拼图——它让你的知识库不再是静态的仓库，而是AI可以主动读取、分析和增强的活知识系统。

结语：知识的最后一公里

TriliumAI Chat架起了桥，TriliumAI Agent让车开上了桥。

如果说Chat回答的是"AI怎么知道我的知识"的问题，那么Agent回答的是"AI怎么高效地使用我的知识"的问题。从搜索到浏览到导出到记忆注入，从单次对话到多智能体协作，从手动操作到一条命令的自动化流水线——Agent在每一个环节都在降低"知识到达AI"的摩擦力。

而摩擦力的降低不是一个技术问题——它是一个人文问题。当把知识喂给AI需要五分钟十步操作时，你只会在"非常重要"的时候才这样做。但当同样的事情只需要一条命令时，你会在"可能有用"的时候也这样做。这个行为差异日积月累，会导致截然不同的知识利用深度。

Agent在技术实现上的一些选择——绕过WordPress做独立SSE代理、用TransformStream桥接WebSocket与SSE、记忆写入绕过AI推理层直接操作文件系统——都体现了同一个工程哲学：为了让用户的核心体验更流畅，愿意在底层承担更高的复杂度。

复杂度没有消失，它只是从用户侧转移到了系统侧。而这，正是好工具应该做的事情。

Sources:

• Trilium AI Chat：智能化知识管理与内容创作的全能助手
• 构建高效的个人知识管理系统：Brave的AI赋能工作流
• 主权个人的十倍效率时代，从Prompt管理到人机协同的流水线革命
• 为啥聪明人都离不开Trilium，《智识的生产技术》告诉你答案
• 被低估的宝藏Trilium Notes与社区驱动的Trilium Next
• 主权个人的AI入门课