企业官网建设流程全解析

• 人工智能
• 大模型
• AI 应用
• AI Agent
• RAG
• MCP Clients
• 交互助手
• 浏览器控制

Obsidian 的「库（vault）」本质就是一个磁盘上的普通文件夹，而 openagent 通过内置的obsidianSkill（见 SKILL.md）为 Agent 提供了基于obsidian-cli的自动化操作能力：从定位活跃 vault、搜索笔记，到带链接修复的安全重命名与创建删除。读完本文，你将掌握 Obsidian vault 的标准结构、通过obsidian.json或print-default精准定位仓库的两种方法、obsidian-cli全套核心命令，以及这些指令在 openagent 的 Skill 体系（SKILL.md front matter 解析、load_skill注入、按程序名做 shell 权限裁决）中如何被真正执行。

Obsidian vault：本质是一个普通文件夹

官方 Skill 文档开篇就点明了一个关键认知：Obsidian vault 就是磁盘上的一个普通文件夹（"a normal folder on disk"）。这意味着任何能读写文件的程序——包括 openagent 的 Agent——都可以直接操作它，而不必依赖 Obsidian 桌面应用本身。

一个典型的 vault 目录结构包含四类内容：

这个结构对 Agent 有两条重要含义：

• .md笔记是纯文本：Agent 可以直接打开、修改、追加内容，Obsidian 会自动拾取文件系统的变更，无需通过 URI 或 API 同步；
• .obsidian/是程序状态而非笔记：官方文档明确建议"usually don't touch from scripts"，脚本应避免写入该目录，以免破坏工作区布局或插件配置。

定位活跃 vault：读取权威配置，而不是靠猜

多 vault 是 Obsidian 的常态（iCloud 与~/Documents并存、工作库与个人库分离），因此在脚本或 Agent 中禁止硬编码 vault 路径，应当读取配置或使用 CLI 查询。

权威数据源：obsidian.json

Obsidian 桌面端把所有 vault 的注册信息记录在以下文件（源码视角的"single source of truth"）：

~/Library/Application Support/obsidian/obsidian.json

obsidian-cli正是从这个文件解析出 vault 列表。其中vault 名称通常就是文件夹名（路径的最后一段），而当前激活的 vault 由"open": true标记。定位活跃 vault 的标准做法：

1. 若已设置默认库，直接执行obsidian-cli print-default --path-only拿到路径；
2. 否则读取obsidian.json，找到"open": true的条目。

用 CLI 设置与查询默认 vault

首次使用只需设置一次默认库：

# 设置默认 vault（参数为文件夹名，例如 "work"） obsidian-cli set-default "<vault-folder-name>" # 查询默认库：名称 obsidian-cli print-default # 查询默认库：仅输出路径（适合脚本直接取用） obsidian-cli print-default --path-only

obsidian-cli 核心命令速查

搜索

# 按笔记名搜索 obsidian-cli search "query" # 在笔记内容中搜索（返回片段与行号） obsidian-cli search-content "query"

search适合快速定位笔记标题，search-content适合全文检索内容——两者结合可以覆盖"我记得标题"与"我只记得内容"两类检索需求。

创建笔记

obsidian-cli create "Folder/New note" --content "..." --open

创建笔记有两条硬性前提与注意事项：

• 依赖 Obsidian URI handler：create通过obsidian://…URI 完成，因此要求本机已安装 Obsidian 且 URI 协议可用；
• 避免在隐藏点目录下创建：不要在.something/...这类 dot 文件夹下通过 URI 建笔记，Obsidian 可能拒绝执行。

移动 / 重命名：安全的链接重构

obsidian-cli move "old/path/note" "new/path/note"

这是obsidian-cli相对mv的核心价值：move不仅移动文件，还会跨整个 vault 更新所有[[wikilinks]]以及常见的 Markdown 链接。直接使用mv会导致笔记间的双向链接悬空，而用move做重构是安全的。对 Agent 而言，这也是执行"整理笔记"类任务时的首选命令。

删除

obsidian-cli delete "path/note"

直接编辑优先

文档特别强调：只要合适，直接打开.md文件编辑即可，Obsidian 会自动拾取变更。CLI 的create/move/delete解决的是"需要 Obsidian 参与（URI、链接修复）"的场景，而内容层面的增删改，直接改文件更轻量、更可靠。

openagent 如何装载并执行这份 Skill

skills/obsidian/SKILL.md不是一段孤立文本，它遵循 openagent 的 Skill 规范，会被完整解析并注入到 Agent 的提示词上下文中。

SKILL.md 的 front matter 结构

SKILL.md 采用 YAML-ish 的 front matter 头部加 Markdown 正文的结构：

--- name: obsidian description: Work with Obsidian vaults (plain Markdown notes) and automate via obsidian-cli. homepage: https://help.obsidian.md metadata: { "openclaw": { "emoji": "💎", "requires": { "bins": ["obsidian-cli"] }, "install": [ { "id": "brew", "kind": "brew", "formula": "yakitrak/yakitrak/obsidian-cli", "bins": ["obsidian-cli"], "label": "Install obsidian-cli (brew)", }, ], }, } ---

其中metadata.openclaw.requires.bins声明了本 Skill 运行所需的可执行文件obsidian-cli，而metadata.openclaw.install给出了通过 Homebrew 安装的方式（formula 为yakitrak/yakitrak/obsidian-cli）。也就是说，在 Agent 调用任何 obsidian 命令之前，依赖检查会先确认obsidian-cli已存在于 PATH。

仓库侧的解析实现

openagent 在 skillmd/skillmd.go 中实现了独立的 front matter 解析器Parse，并在 LoadFolder 中读取{dir}/SKILL.md与同目录references/下的辅助文件。几个值得注意的实现细节：

• name/description/homepage支持裸值、单引号、双引号三种写法（见unquote）；
• emoji通过正则从metadata块中提取（skillmd.go）；
• 若 SKILL.md 缺少name字段，自动回退为文件夹名，确保 Skill 永不无名（由 skillmd_test.go 的TestLoadFolderNameFallsBackToDirectory验证）；
• references/下的文件按File{Name, Content}加载，子目录会被忽略（skillmd_test.go）。

从目录到 Agent 上下文：load_skill 注入链路

Skill 被装入后，openagent 会通过load_skill工具按需注入：

• tool/skill.go定义了SkillLoader接口与load_skill内置工具，参数为skill（技能名）与可选的reference（参考文件名，见 tool/skill.go）；
• object/skill.go的GetSkillsCatalog会把可用 Skill 的名、描述、references 列表生成提示词目录，并强制要求"用户明确提及某 Skill 时，必须先调用load_skill再回答"（object/skill.go）；
• LoadSkillPromptContent按需拼接正文与 references 内容（object/skill.go）；
• skillLoader.Load会先校验该 Skill 是否在当前 store 的启用名单内，未启用则拒绝加载（object/skill.go）。

此外，migration/source_openclaw.go在迁移第三方 Agent 数据时也会复用skillmd.LoadFolder读取其安装目录下的 Skill 文件夹（source_openclaw.go），这说明 SKILL.md 格式同时服务于存储、迁移、加载多条链路。

命令执行的权限裁决

Agent 执行obsidian-cli命令时，openagent 的 shell 权限层（shellcmd/shellcmd.go）会先把命令行解析为程序名列表（如obsidian-cli、move等参数不会误判为程序），再按程序名做 allow/deny 裁决，而不是对整条命令做脆弱的子串匹配。对动态变量（如$VAULT）等无法静态解析的写法，解析器会返回certain=false，权限检查按"未知即拒绝"的安全关闭原则处理。

典型自动化场景

结合以上能力，Agent 可以在 openagent 中完成如下任务闭环：

1. 定位：obsidian-cli print-default --path-only或读取obsidian.json确定目标 vault，绝不硬编码路径；
2. 检索：用search/search-content命中笔记；
3. 增改：优先直接编辑.md文件（Obsidian 自动拾取）；需要 Obsidian 参与的建库操作才用create（注意 URI handler 与 dot 文件夹限制）；
4. 重构：用move做重命名与移动，依靠其自动修复[[wikilinks]]的能力保持知识图谱完整；
5. 清理：用delete删除废弃笔记。

整套流程既保留了 Obsidian"本地优先、纯文本"的核心哲学，又通过obsidian-cli与 openagent 的 Skill 加载、依赖检查、权限裁决机制，把知识库管理变成了可审计、可复用的 Agent 技能。

• 人工智能
• 大模型
• AI 应用
• AI Agent
• RAG
• MCP Clients
• 交互助手
• 浏览器控制