Trilium MCP 知识库组件

1. Trilium 自身的权限链路架构

1.1 同步机制

• Trilium 支持自托管服务器，数据存储于 SQLite 数据库
• 前端（Web/桌面）与后端通过 REST API 通信，后端直接读写 SQLite
• 多设备同步通过 Sync Server 实现：设备 A 的变更 → Sync Server → 设备 B 拉取
• 同步基于 变更日志（Sync Log），增量传输，冲突时按时间戳合并
• 每个笔记/分支有 utcDateModified 作为冲突解决依据
• 同步协议加密：端到端加密（E2EE）可选，启用后同步数据在服务端不可读

1.2 ETAPI 接口

• Trilium 提供 ETAPI（External Triggered API），位于 /etapi/ 路径
• 鉴权方式：HTTP Header Authorization: <token>，token 在 Trilium 设置页面生成
• 核心接口：

• 注意：PUT content 需用 Content-Type: text/plain，而非 text/html

2. AI 应用"安装"Trilium ETAPI 的 4 种存在形态

ETAPI 本身只是 Trilium 服务端的 HTTP 接口。AI 应用要使用它，根据"封装/安装"程度有 4 种存在形态：

2.1 形态 A：裸 HTTP（零安装，临时使用）

• 是什么：AI 在对话中口头或上下文获得 URL + token 后，现场用 curl / fetch 构造请求
• 不持久化：URL、token、路由、参数格式完全依赖对话上下文，换 session 即丢失
• 链路：

  AI 在对话中敲 curl → shell 执行 → HTTP → ETAPI → SQLite

• 适用：临时调试、一次性操作

2.2 形态 B：Skill 封装

• 是什么：将 ETAPI 调用说明、URL、参数格式等写入 opencode Skill（SKILL.md），通过 skill 工具加载到上下文
• token 传递：Skill 中写 {env:TRILIUM_ETAPI_TOKEN} 引用环境变量，不暴露明文
• 链路：

  AI → skill 加载注入知识 → AI 理解后自行构造 HTTP → shell 执行 → ETAPI → SQLite

• 谁在干活：AI 仍然是对话中敲命令的人，Skill 只是提供"操作说明书"，没有自动化调用层
• 适用：需要持久化 knowledge 但无 MCP 部署权限时

2.3 形态 C：MCP Server（推荐）

• 是什么：一个 node.js 本地子进程，通过 opencode 的 mcp 段注册运行
• 不是 AI 应用：这个子进程是 协议适配层，它将 HTTP API 包装成 AI 可以直接调用的结构化 Tool
• 配置：opencode.jsonc 中加一条 mcp.trilium 记录，子进程通过同目录 .env 加载 URL + token
• 链路：

  AI (opencode LLM) → MCP CallTool (stdio) → trilium-mcp 子进程 → HTTP → ETAPI → SQLite

• AI 做什么：AI 只需要说"读取笔记 XXX"，opencode 自动匹配到 read_note 工具，MCP 子进程代为构造 HTTP 请求
• 优点：工具发现（ListTools）、参数校验、类型安全、opencode 管理生命周期

2.4 形态 D：Plugin（未来可能）

• 是什么：opencode 支持 opencode plugin 安装插件，插件运行在 opencode 进程内
• 链路：

  AI → opencode plugin 内部调用 axios → HTTP → ETAPI → SQLite

• 比 MCP 短：无子进程开销，插件内直发 HTTP
• 现状：trilium 尚未封装为 plugin

3. AI 应用安装 Trilium MCP 的存在形态与链路机制

3.1 存在形态

• MCP 是一个 本地子进程（stdio 通信），由 opencode 自动管理生命周期
• 物理文件：~/opencode-mcp/trilium/dist/index.js
• 配置方式：在 opencode.jsonc 的 mcp 段注册：

{
  "mcp": {
    "trilium": {
      "type": "local",
      "command": ["node", "C:\\Users\\cat\\opencode-mcp\\trilium\\dist\\index.js"],
      "enabled": true
    }
  }
}

• 子进程通过 .env（与 index.js 同目录）加载 ETAPI URL 和 token

3.2 链路机制

AI (opencode LLM) → MCP 协议 (stdio) → trilium-mcp 子进程 → HTTP → Trilium ETAPI → SQLite

• opencode 启动时 spawn 子进程，调用 ListTools 获取 11 个工具
• AI 在对话中识别到 trilium 操作需求时，通过 MCP 协议发送 CallTool 请求
• 子进程将请求转为 HTTP 请求发往 ETAPI，结果通过 stdio 回传
• 工具包括：search_notes、read_note、update_note、create_note、delete_note、move_note、batch_create_notes、batch_move_notes、list_children、get_note_metadata、manage_attributes
• opencode 退出时自动终止子进程

3.3 MCP vs 直连 ETAPI 对比

4. 最佳 AI 操作 Trilium 实践

4.1 方案选择：用 MCP

• 尽管 MCP 链路较长（多一跳进程间通信），但 工具发现 + 结构化参数校验 大幅降低了 AI 调用出错的概率
• 直连 ETAPI 要求 AI 准确记忆 URL 路径、请求方法、HTTP Header、JSON 结构等细节，实际出错率更高

4.2 对话成本最低

• 使用 3 个核心工具即可覆盖 90% 场景：search_notes → read_note → update_note
• 避免跨工具链式调用（如 read 后自行拼接 URL 再 curl），一次 MCP CallTool 直达
• 批量操作使用 batch_create_notes / batch_move_notes，减少往返次数

4.3 AI 识别最好

• 工具名称和参数名使用完整英文短语（非缩写），AI 能自然理解语义
• 在 opencode.jsonc 中为特定 agent 启用 trilium 工具，避免工具列表膨胀干扰 AI 选择

4.4 操作链路最短

• 单个笔记操作（读/写/搜索）：1 次 MCP CallTool → 直达 ETAPI
• 注意：update_note 传完整 HTML 内容时，务必读原内容后追加修改，而非重写整个笔记

4.5 效率最高

• 内容编辑规范：严格遵循 CKEditor 5 HTML（h2~h6、p、ul/ol、pre code、figure table），避免非标准标签被过滤
• "发布到 XX 笔记的 YY 标题下"：用 read_note 读父笔记完整内容 → 找到对应标题位置 → update_note 更新父笔记内容，不创建子笔记
• 搜索优先：需要查找内容时先用 search_notes 找到 noteId，再用 read_note 读取，避免目录遍历
• 避免高频小操作：合并多个原子的操作为一次批量调用