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 时会被替换为 <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。