用途:面向 Obsidian 库的文件系统优先操作,包括读取笔记、列出笔记、搜索笔记文件、创建笔记、追加内容以及添加 wikilink。
库路径:调用文件工具前需先确定或解析库路径。约定使用 OBSIDIAN_VAULT_PATH 环境变量,例如来自 ${HERMES_HOME:-~/.hermes}/.env;若未设置,则使用 ~/Documents/Obsidian Vault。文件工具不会展开 shell 变量,不要把含 $OBSIDIAN_VAULT_PATH 的路径传给 read_file、write_file、patch 或 search_files,应先解析为具体绝对路径。库路径可能含空格,这也是优先用文件工具而非 shell 命令的原因。若路径未知,可用 terminal 解析 OBSIDIAN_VAULT_PATH 或检查回退路径是否存在,确定后切回文件工具。
读取笔记:用 read_file 传入解析后的笔记绝对路径,优于 cat,因为提供行号和分页。
列出笔记:用 search_files,target 设为 "files",传入解析后的库路径,优于 find 或 ls。列出全部 Markdown 笔记用 pattern: "*.md";列出子文件夹则在该子文件夹绝对路径下搜索。
搜索:文件名和内容搜索都用 search_files,优于 grep、find、ls。文件名用 target: "files" 加文件名模式;内容用 target: "content",pattern 为内容正则,并可用 file_glob: "*.md" 限定 Markdown 笔记。
创建笔记:用 write_file 传入解析后的绝对路径和完整 Markdown 内容,优于 shell heredoc 或 echo,可避免引号问题并返回结构化结果。
追加内容:优先原生文件工具流程。先用 read_file 读取目标笔记;有稳定上下文时用 patch 做锚定追加,例如在已有标题后加章节或在已知尾部块前追加;若整体重写更清晰,则用 write_file。锚定追加时把锚点替换为锚点加新内容。无稳定上下文的简单追加,若 terminal 是最清晰安全的选择也可接受。
定向编辑:当前内容提供稳定上下文时,用 patch 做聚焦修改,优于 shell 文本重写。
Wikilink:Obsidian 用 [[Note Name]] 语法链接笔记,创建笔记时可用其关联相关内容。
限制:文件工具不展开 shell 变量;路径需先解析为绝对路径;未提供具体安装命令、收费或平台信息。