Trilium

Trilium Skill

通过 Trilium 官方 ETAPI 查询和管理个人知识库。Skill 只依赖 Python 标准库，不包含 Trilium 服务端，也不调用内部 /api/* 或任意自定义路径。

适用场景

使用本 Skill 处理：

• 检查 Trilium 实例版本、连通性和 ETAPI 鉴权；
• 使用 Trilium 搜索语法查询笔记；
• 读取、创建、修改和删除笔记；
• 读取或替换笔记正文；
• 查询最近变更和笔记版本，创建版本或恢复已删除笔记；
• 查询、创建和调整笔记树 Branch；
• 查询、创建和修改 Label / Relation 属性；
• 查询附件元数据并读取文本型附件内容；
• 获取 Inbox、日记、周记、月记和年记；
• 在明确确认后触发 Trilium 数据库备份。

不要使用本 Skill 处理用户密码登录、ETAPI Token 创建或吊销、内部 API、任意路径透传、批量删除、二进制上传、ZIP 导入导出或直接修改 Trilium 数据库。

环境变量

| 变量 | 类型 | 必填 | 说明 | |---|---|---:|---| | TRILIUM_URL | config | 是 | Trilium 实例根地址，例如 https://notes.example.com；也接受以 /etapi 结尾的地址 | | TRILIUM_ETAPI_TOKEN | secret | 是 | 在 Trilium Options → ETAPI 中创建的 Token | | TRILIUM_INSECURE_TLS | config | 否 | 仅自签名证书调试时设为 1；会跳过 TLS 证书校验 |

Token 只从当前进程环境读取，不支持通过输入 JSON 传递。缺少环境变量时只返回变量名，不读取浏览器 Cookie、配置文件或宿主私有目录。

重要内容格式

ETAPI 返回和接收的是 Trilium 实际存储格式：

• text 富文本笔记正文是 HTML，不是 Markdown；
• code、search、mermaid 等文本型笔记通常是原始文本；
• 图片、PDF 等二进制正文不会写入 JSON 输出，只返回 binary、content_type 和 size_bytes；
• 第一版不做 Markdown 与 HTML 转换，避免无损性和格式语义不明确。

替换正文前先读取笔记类型和当前正文。只修改标题时使用 update-note，不要重写正文。

执行方式

在 Skill 包根目录运行：

printf '%s' '{"skill_action":"status"}' | python3 run.py

输入必须是 JSON 对象，动作字段为 skill_action。输出始终为 JSON。除 status 可报告未配置状态外，其余动作均要求 URL 和 Token。

动作

笔记与正文

| 动作 | 类型 | 主要输入 | 说明 | |---|---|---|---| | status | 只读 | 无 | 检查配置并调用 /etapi/app-info | | search-notes | 只读 | query，以及可选搜索参数 | 使用 Trilium 搜索语法查询笔记 | | get-note | 只读 | note_id | 获取笔记元数据、Branch ID、属性等 | | get-note-content | 只读 | note_id | 获取笔记实际存储正文 | | create-note | 写入 | parent_note_id, title, type, content? | 在指定父笔记下创建笔记 | | update-note | 写入 | note_id 及需修改的字段 | 修改标题、类型、MIME 或创建时间 | | set-note-content | 写入 | note_id, content | 替换完整正文；允许空字符串 | | delete-note | 删除 | note_id, confirm: true, confirm_title | 读取当前标题并精确匹配后软删除 |

search-notes 可选参数：

fast_search
include_archived_notes
ancestor_note_id
ancestor_depth
order_by
order_direction
limit
debug

创建笔记的可选字段：

mime
note_position
prefix
is_expanded
note_id
date_created
utc_date_created

版本与恢复

| 动作 | 类型 | 主要输入 | 说明 | |---|---|---|---| | note-history | 只读 | ancestor_note_id? | 查询最近变更，可限定子树 | | list-note-revisions | 只读 | note_id | 查询一个笔记的版本列表 | | get-revision | 只读 | revision_id | 获取版本元数据 | | get-revision-content | 只读 | revision_id | 获取版本正文 | | create-revision | 写入 | note_id, description? | 手动保存当前版本 | | undelete-note | 恢复写入 | note_id, confirm: true, confirm_note_id | ID 精确匹配后恢复软删除笔记 |

树结构与属性

| 动作 | 类型 | 主要输入 | 说明 | |---|---|---|---| | get-branch | 只读 | branch_id | 获取 Branch | | create-branch | 写入 | note_id, parent_note_id | 把笔记放入另一个父节点；已有 Branch 时更新它 | | update-branch | 写入 | branch_id 及修改字段 | 修改位置、前缀或展开状态 | | delete-branch | 删除 | branch_id, confirm: true, confirm_branch_id | 精确匹配 ID 后删除 Branch | | refresh-note-ordering | 写入 | parent_note_id | 通知 Trilium 刷新该父节点排序 | | get-attribute | 只读 | attribute_id | 获取 Label 或 Relation | | create-attribute | 写入 | note_id, type, name, value? | 创建属性；未指定 attribute_id 时生成 12 位 ID | | update-attribute | 写入 | attribute_id, value?, position? | 修改属性值或位置 | | delete-attribute | 删除 | attribute_id, confirm: true, confirm_attribute_id | 精确匹配 ID 后删除属性 |

create-branch 和 update-branch 的可选字段是 note_position、prefix、is_expanded。type 只接受 label 或 relation；Relation 的 value 必须是目标笔记 ID。

删除 Branch 可能改变笔记在树中的可见位置；删除最后一个 Branch 的实际行为由 Trilium 服务端决定，因此操作前必须先读取 Branch 和目标笔记。

附件、日历与备份

| 动作 | 类型 | 主要输入 | 说明 | |---|---|---|---| | list-note-attachments | 只读 | note_id | 列出笔记附件 | | get-attachment | 只读 | attachment_id | 获取附件元数据 | | get-attachment-content | 只读 | attachment_id | 只直接返回文本内容；二进制仅返回元数据 | | get-inbox-note | 只读/按需创建 | date | 获取指定 YYYY-MM-DD 的 Inbox 笔记 | | get-day-note | 只读/按需创建 | date | 获取日记 | | get-week-note | 只读 | week | 获取 YYYY-Www 周记 | | get-month-note | 只读/按需创建 | month | 获取 YYYY-MM 月记 | | get-year-note | 只读/按需创建 | year | 获取 YYYY 年记 | | create-backup | 高影响写入 | backup_name, confirm: true, confirm_backup_name | 触发数据库备份 |

Trilium 的特殊笔记接口可能在笔记不存在时自动创建对应节点，因此日历类动作虽按查询使用，也可能造成服务端数据变化。

安全约束

• 服务地址只允许 http 或 https，禁止 URL 内嵌凭据、查询参数和片段。
• 所有请求路径均由固定动作生成，不开放任意 endpoint。
• Token 不通过输入参数、命令行或输出传递；服务端错误中出现 Token 时会被替换为 ``。
• 单次响应限制为 8 MiB，避免把大型附件直接装入模型上下文。
• delete-note 必须先读取目标并要求当前标题精确匹配。
• delete-branch、delete-attribute 和 undelete-note 必须额外匹配目标 ID。
• create-backup 必须匹配备份名，备份名仅允许字母、数字、点、下划线和连字符。
• 写操作后根据返回值或重新读取目标验证最终状态；失败时保留 HTTP 状态、固定 endpoint 和脱敏响应。
• Protected 笔记和附件是否允许读取或修改由 Trilium ETAPI 强制决定，Skill 不尝试绕过。

推荐操作流程

1. 首次使用先执行 status，确认实例、Token 和版本。
2. 搜索后使用 get-note 确认真实 note_id、标题、类型和父子关系。
3. 改正文前先执行 get-note-content；富文本必须按 HTML 处理。
4. 删除、恢复和备份前向用户复述目标，并只在确认信息完全匹配时执行。
5. 写入完成后读取目标或相关父节点验证，不用成功提示代替真实状态。

接口依据和字段映射见 references/etapi.md。

AgentDock 适配

在 AgentDock 中，把 URL 和 Token 配置到该 Skill 的独立环境，再通过绑定当前激活 Skill 的命令执行能力运行 python3 run.py。不要手工拼接已安装版本目录，也不要把真实 Token 写入 Skill 包、源码仓库或 Recall。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: uvwt
• Source: uvwt/agentdock
• License: Apache-2.0
• Homepage: https://uvwt.github.io/agentdock-docs/

Install and usage instructions live in the source repository linked above.