trilium

name	trilium
description	Search, read, create, update and organize notes in a Trilium Notes instance through the official ETAPI, including revisions, branches, attributes, attachments, calendar notes and explicitly confirmed destructive operations.
version	1.0.0

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 时会被替换为 <redacted>。
• 单次响应限制为 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。