企业官网建设流程全解析

• AI 应用
• 人工智能
• AI Agent
• 本地部署
• 前端
• 后端
• 工作流自动化

导读

本文围绕 Ekko Agent（Ekko Studio 的本地优先多智能体工作台）内置的obsidian技能展开，讲解如何通过 Obsidian 官方命令行接口（CLI）完成 Vault 笔记的读取、搜索、创建、编辑、移动、删除、任务处理与属性/链接维护。读完本文，你将掌握obsidian <command> [name=value] [flag]的完整命令范式与安全边界，并理解 Ekko Agent 的技能加载、Frontmatter 校验与关键词路由机制如何在底层支撑这份指令文档生效。

技能文档在仓库中的位置与定位

该技能的指令文档位于 packages/ekko-agent/skills/obsidian/SKILL.md。它的 YAML Frontmatter 声明了技能名称与用途：

--- name: obsidian description: Read, search, create, edit, organize, and inspect Obsidian vault notes, tasks, links, properties, and plugins with the official CLI. metadata: keywords: - obsidian vault - obsidian cli - obsidian notes ---

其中metadata.keywords并非装饰性字段。从 技能路由实现 的resolveSkillRouting可以看出，Ekko Agent 会基于用户消息与技能名称、名称变形（连字符/下划线替换为空格）以及显式声明的keywords做确定性匹配，长描述与技能正文不参与自动选择。也就是说，当用户提到 "obsidian vault"、"obsidian cli" 等关键词时，本技能才会被路由命中并注入指令。

每个技能本质上是一个实现了AgentSkill接口的对象，其instructions字段承载这份 SKILL.md 文本，定义见 packages/ekko-agent/src/skills/types.ts。技能按 Profile 注册与隔离，通过EkkoSkillManager（packages/ekko-agent/src/skills/manager.ts）暴露skill_list、skill_view、skill_manage等工具；本技能属于随包发布的只读内置技能，Agent 通过skill_view name=obsidian即可加载其完整指令。

前置条件：让 CLI 可用且可验证

使用obsidian技能前需满足四个前提，缺一不可：

1. Obsidian 1.12.7 或更新版本已安装——官方 CLI 自该版本起随桌面应用提供。
2. Settings > General > Command line interface开关已启用——CLI 是可选能力，默认关闭。
3. obsidian命令已注册到PATH——安装器通常自动完成，但需以obsidian version实测确认。
4. Obsidian 桌面应用正在运行——CLI 通过连接桌面应用进程工作，不直接操作文件系统。

在不改动 Vault 的前提下，可用下面两条命令做连通性检查：

obsidian version obsidian help

技能文档明确了一条纪律：若 CLI 缺失，应解释如何在 Obsidian 中启用官方 CLI，而不是静默安装第三方obsidian-cli包。这避免了向用户环境引入来源不明的二进制，属于技能的安全底线。

Vault 选择：显式优于猜测

Obsidian 用户常同时打开多个 Vault，因此目标不明确时必须显式指定：

• vault="<name>"：在多个 Vault 之间指定目标，名称有歧义时应询问用户，而不是猜测。
• path="Folder/Note.md"：使用 Vault 内相对路径做精确解析，优先推荐。
• file=<name>：使用 Obsidian 基于名称的解析，适合名称唯一且路径未知的场景。

同时文档划定了两条隐私与配置红线：

• 不要编辑.obsidian/配置，除非用户明确要求修改设置或插件；
• 避免读取或暴露私人 Vault 中与任务无关的笔记。

命令模式：统一的 name=value 语法

所有 CLI 操作遵循同一范式：

obsidian <command> [name=value] [flag] obsidian vault="Notes" search query="meeting notes" format=json

要点：

• 参数采用name=value形式，含空格的值必须加引号；
• 优先使用结构化输出，例如format=json，便于程序解析；
• 支持flag形式的开关（如newtab、verbose、counts、all、todo、done等）。

打开与读取：在 Obsidian 中定位笔记

obsidian open file=Recipe obsidian open path="Inbox/Idea.md" newtab obsidian read obsidian read file=Recipe

• open在 Obsidian 中打开指定笔记；file=按名称解析，path=按 Vault 相对路径精确解析；追加newtab可在新标签页打开。
• read读取当前活动笔记；带file=时读取指定笔记。

由于 Vault 笔记本质是 Markdown，文档也给出了补充策略：当已知精确的 Vault 路径、且操作不需要 Obsidian 更新链接或元数据时，可以直接用文件工具读写笔记内容。

搜索：查询与结构化结果

obsidian search query="TODO" matches obsidian search query="status::active" format=json obsidian search:open query="project notes"

• search query="..."执行 Vault 内全文搜索；matches输出匹配位置，format=json输出结构化结果。
• search:open在 Obsidian 界面中打开搜索结果视图，适合需要人机协作确认的场景。

搜索同样遵循name=value参数规范，多词查询务必整体加引号。

创建与修改：受控的写操作

obsidian create name="New Note" obsidian create path="Inbox/Idea.md" content="# Idea" obsidian append file=Note content="New line" obsidian prepend file=Note content="After frontmatter"

• create新建笔记：可用name=（由 Obsidian 决定存放位置）或path=（指定 Vault 内完整路径）并附带content=初始正文。
• append/prepend在既有笔记末尾或 Frontmatter 之后追加内容。

技能文档对写操作给出两条强约束：

1. 仅当用户提出要求时才创建或修改笔记——技能不主动产生写入副作用。
2. 多行或用户提供的内容要避免脆弱的 Shell 插值——优先采用基于文件的安全工作流，或在解析出精确 Vault 路径后使用 Agent 的文件工具完成。

移动与删除：交给 Obsidian 维护链接

obsidian move file=Note to=Archive/ obsidian move path="Inbox/Old.md" to="Projects/New.md" obsidian delete file=Note

• move支持file=（按名称）或path=（按路径）指定源，to=指定目标目录或完整新路径。优先使用 Obsidian 的移动命令，以便其同步更新笔记间的引用链接。
• 执行前必须核对确切的源与目标，避免误移。
• delete会永久移除笔记；若删除目标并非用户请求中已明确的对象，删除前必须向用户确认。

日记与任务：高频个人知识管理场景

obsidian daily obsidian daily:read obsidian daily:append content="- [ ] Review inbox" obsidian tasks all todo obsidian task file=Note line=8 done

• daily/daily:read/daily:append分别用于打开、读取、追加今日日记（日记模板由 Obsidian 日记插件配置决定）。
• tasks all todo列出所有未完成任务；task file=Note line=8 done将指定笔记第 8 行的任务标记为完成。

文档特别提醒：完成任务会修改笔记内容，因此应用更改前必须先解析确切的文件与任务行号，防止改错目标。

属性与链接：Frontmatter 与双向链接运维

obsidian tags all counts obsidian property:read file=Note name=status obsidian property:set file=Note name=status value=done obsidian backlinks file=Note obsidian unresolved verbose counts

• tags all counts统计全部标签及其出现次数。
• property:read/property:set读取/写入笔记属性（对应笔记 Frontmatter 字段），是批量维护元数据的安全途径——例如把任务状态status从todo更新为done。
• backlinks file=Note查询反向链接；unresolved verbose counts定位未被解析的链接（悬空链接），便于清理断链。

插件与开发者命令：诊断与插件开发专用

obsidian plugin:reload my-plugin obsidian dev:errors obsidian dev:screenshot file=shot.png obsidian eval "app.vault.getFiles().length"

• plugin:reload重载指定插件，适合插件开发调试。
• dev:errors查看应用运行时错误日志，dev:screenshot对当前窗口截图。
• eval在应用上下文执行 JavaScript 表达式（如统计 Vault 文件数）。

技能文档对这类命令划出明确边界：插件重载与eval可能改变或窥探大范围应用状态，仅限明确的插件开发或诊断任务使用；对于用户提供的任意 JavaScript，未经审查其影响前不得通过obsidian eval执行——这是本文档中仅次于删除确认的又一道安全闸门。

文件模型：Vault 的构成与操作选择

Vault 内部存在多种文件类型，操作方式应区别对待：

据此形成操作分派原则：

• 有界的批量文本修改：定位正确 Vault 后，可直接进行 Markdown 编辑；
• 需要 Obsidian 感知的行为（链接维护、属性变更、任务勾选、移动删除）：一律走 CLI 的move、delete、property、task等命令。

源码视角：这份指令如何被校验、路由与执行

Frontmatter 校验约束

Ekko Agent 对每个技能的 SKILL.md 有严格的 Frontmatter 校验，见 packages/ekko-agent/src/tools/skills.ts 中的validateSkillContent：

• 必须以 YAML Frontmatter 开头，且name必须与目录名一致；
• 必须提供非空description；
• metadata.keywords至少 1 条、最多 8 条，每条不超过 80 字符，且必须为英文 ASCII 文本或技术标识符；
• Frontmatter 之后必须存在 Markdown 正文。

本技能文档完全满足上述约束（3 条关键词、紧凑的英文描述、完整的 Markdown 正文），因此校验状态为valid，可被纳入关键词路由。校验失败的技能会被标记为needs_metadata或invalid，从而被排除在自动路由之外（相关行为可参考 tests/ekko-agent/skill-tools.test.ts 中无 Frontmatter 技能被判invalid的用例）。

从发现到注入的调用链

obsidian技能从磁盘到模型上下文经过以下链路：

1. discoverSkills递归扫描技能目录，读取每个目录下的SKILL.md，解析出name、description、keywords、category、来源（local/external/builtin）与校验状态；
2. listSkillNames/matchSkillsForUserMessage依据用户消息与关键词做确定性匹配（resolveSkillRouting），命中后把技能名注入系统提示；
3. Agent 在运行中通过skill_view name=obsidian加载完整指令正文——工具返回内容同时携带baseDirectory、字符数与 sha256 指纹，便于后续校验与审计；
4. 若用户需要观察 CLI 输出，Agent 依据指令文档执行obsidian命令并解析format=json等结构化结果。

外部技能目录（如团队共享的~/shared-skills）同样受支持：配置解析见 packages/ekko-agent/src/skills/external-directories.ts，支持~、~/...与环境变量（$VAR/${VAR}）展开；外部目录被视为只读来源，不会被skill_manage修改。内置技能（含obsidian）通过.ekko-builtin-skills.json清单标识，不能被删除，修改内置技能会被拒绝，这是保护随包技能完整性的机制。

安全边界小结

• 不安装第三方obsidian-cli，CLI 缺失时引导用户启用官方 CLI；
• Vault 歧义时询问用户，不猜测；
• 不碰.obsidian/配置，不读无关私有笔记；
• 写操作仅在用户要求时执行，多行内容避免 Shell 插值；
• 删除前确认、移动前核对源与目标；
• 插件重载与eval仅在明确任务下使用，用户提供的脚本需先审查影响。

这些边界与 Ekko Agent 技能体系的设计一脉相承：技能既是能力的注入，也是行为约束的载体——obsidian技能用一份 120 余行的指令文档，把「读取、搜索、创建、编辑、组织、检视」Vault 的能力与「不越权、不猜测、先确认」的执行纪律同时固化下来。

• AI 应用
• 人工智能
• AI Agent
• 本地部署
• 前端
• 后端
• 工作流自动化