基于AI代理与Obsidian构建自动化知识工作流实战

1. 项目概述：一个为思考者打造的AI代理操作系统

如果你和我一样，每天在Obsidian里记录会议纪要、整理待办事项、追踪项目进展，同时又在Cursor、Claude Code这些AI编码工具里来回切换，那你一定体会过这种割裂感：想法散落在各处，操作需要手动重复，信息无法自动流转。最近，我在GitHub上发现了一个名为ObsidianOS: Work的开源项目，它精准地击中了这个痛点。这本质上是一个“预装”了AI代理技能的Obsidian知识库模板，你可以把它理解为一个专为知识工作者设计的“代理操作系统”。

它的核心思路非常巧妙：将你日常工作中那些重复、琐碎的信息处理流程——比如从日历创建会议笔记、从邮件提取周报素材、从对话记录中提取待办事项——封装成一个个可被AI代理直接调用的“技能”（Skills）。你不再需要手动复制粘贴，或者对着AI一遍遍描述操作步骤；只需要在Cursor的命令行里输入/meeting，它就能自动读取你今天的Google日历，在Obsidian的Meetings/文件夹下生成格式规范的笔记草稿。

我花了几天时间深度配置和使用了这个系统，它彻底改变了我管理每日信息流的方式。现在，我的Obsidian库不再是一个被动的存储仓库，而是一个能通过AI代理主动“工作”的智能中枢。无论是用Cursor、Claude Code还是OpenCode，这些代理都能基于同一套技能集，在我的知识库上执行标准化操作。这篇文章，我将为你完整拆解ObsidianOS: Work的配置逻辑、核心技能的使用细节，以及我在实际部署中踩过的坑和总结出的高效工作流。如果你是一名重度依赖Obsidian进行知识管理，并希望用AI代理提升信息处理效率的开发者、项目经理或任何知识型工作者，这套系统值得你投入时间研究。

2. 核心设计理念与架构解析

2.1 为什么是“代理操作系统”？

传统的笔记软件或任务管理工具，其自动化能力往往依赖于内置插件或复杂的IFTTT式联动，扩展性和灵活性有限。ObsidianOS: Work选择了一条更“底层”也更开放的路径：它不尝试改造Obsidian本身，而是将Obsidian库（Vault）作为一个数据层和呈现层，在其之上构建了一个由命令行工具和AI代理驱动的执行层。

这个设计的精妙之处在于“关注点分离”。Obsidian继续完美地履行它作为双向链接笔记软件和知识图谱可视化工具的职责，提供优秀的编辑体验和本地数据安全。而所有“动”的操作——获取外部数据（日历、邮件）、处理内容（提取待办、总结周报）、执行命令（Git提交）——都交给在终端或AI IDE中运行的代理技能。这些技能通过标准的文件系统接口与Obsidian库交互，读写Markdown文件。这意味着，任何能执行Shell命令、读取JSON/Markdown文件的AI代理，理论上都能驱动这个系统。项目将其称为“Agent-agnostic”（代理无关），正是基于此。

2.2 核心组件与数据流

要理解这个系统如何运作，我们需要拆解它的几个核心组件及其交互关系：

1. 技能定义层（.agents/skills/）：这是整个系统的“指令集”。每个技能（如/meeting、/recap）都对应一个Markdown文件（如meeting.md），里面用自然语言详细描述了该技能的功能、所需参数、执行步骤以及预期的输出格式。这些文件是AI代理的“说明书”。项目通过符号链接（Symlink），将同一个技能目录同时映射到.cursor/skills/、.claude/skills/等位置，确保不同代理都能发现并使用同一套技能。

2. 代理配置层（各Agent的配置文件）：这是让AI代理“认识”这个系统的桥梁。对于Cursor，项目提供了.cursor/rules/目录和.cursor/mcp.json文件。Rules文件定义了在这个项目上下文中的通用行为规范（如“优先使用技能”），而MCP（Model Context Protocol）配置则告诉Cursor如何连接到一个本地的QMD搜索服务器，以实现对知识库内容的语义检索。

3. 身份与配置层（USER.md与环境变量）：这是系统的“个性化中枢”。USER.md文件要求你填写姓名、邮箱、时区等个人信息。所有技能在执行时，都会引用这个文件中的信息。例如，/fill-participants技能在解析会议参与者时，会跳过USER.md中定义的“我”的别名，避免将“我”也链接成一个人物文件。这种设计保证了个人隐私，你只需要维护这一个文件。

4. 外部工具层（Google Workspace CLI, QMD, Obsidian CLI）：技能本身不直接实现复杂逻辑，而是调用成熟的外部命令行工具。

   • gws(Google Workspace CLI)：用于以只读方式安全访问你的日历、Gmail和Google Docs，是/meeting、/cache-notes、/recap等技能的数据来源。
   • qmd：一个本地搜索和嵌入工具，为/recap技能提供基于语义的库内信息检索能力。
   • obsidian命令行工具：由Obsidian官方提供，允许从命令行打开笔记、搜索等，被obsidian-cli技能调用。

整个数据流可以概括为：AI代理读取技能描述 → 理解用户意图 → 调用相应的外部CLI工具获取数据或执行操作 → 按照预定模板将结果写入Obsidian库的特定位置 → 用户在Obsidian中查看和进一步编辑结果。这个流程将人的创造性思考（在Obsidian中关联、深化想法）和AI的自动化处理（收集、格式化、提取信息）完美地结合了起来。

2.3 技能列表深度解读

官方列出了9个核心技能，但每个技能背后都有一系列子命令和逻辑。理解它们能解决的具体场景，比记住命令更重要：

• /meeting：这不仅是创建一个空白笔记。它的理想工作流是：早上，你运行/meeting today，它调用gws读取你Google日历中今天的会议，为每个会议生成一个包含标题、时间、参与者、Google Meet链接和空白议程区的Markdown文件，并保存到Meetings/下的对应子文件夹（如Meetings/Eng/）。会后，你可以运行/meeting wrap-up <note-path>，它会根据笔记内容，提示你补充会议结论和下一步行动。
• /cache-notes与/fill-participants：这是一对组合拳。很多线上会议会有AI生成的转录稿（如Google Meet的转录）。/cache-notes技能可以找到这些转录稿的Google Doc，将其内容以“引用块”的形式嵌入到会议笔记的末尾，作为原始记录。接着，/fill-participants会扫描整篇笔记（包括嵌入的转录稿），找出所有人名，并自动将它们转换成Obsidian的内部链接[[@人名]]。点击这些链接，就能跳转到Teams/People/目录下对应的人物档案页，极大地增强了笔记的互联性。
• /followup-todos：这个技能的设计体现了克制。它不像一些任务插件那样添加复杂的复选框语法，而是单纯地将笔记中像“Alice需要在下周五前提交方案”这样的句子，提取成普通的Markdown列表项- Alice需要在下周五前提交方案，并汇总到一个名为ToDo‘s.md的文件中。这样做的好处是，输出结果干净、可读，并且可以利用Obsidian强大的查询插件（如Dataview）进行二次处理，灵活性极高。
• /recap：这是最体现“智能助理”价值的技能。运行/recap last-week，它会做以下几件事：1) 通过gws获取上周的日历事件和邮件主题；2) 通过qmd在你的Obsidian库中进行语义搜索，找出上周创建或修改的相关笔记；3) 综合所有这些信息，生成一份结构化的周报草稿，总结关键会议、邮件讨论和笔记进展。这为你写周报节省了大量收集和回忆的时间。
• /commit：这是一个“有头脑”的Git提交。你不仅可以指定文件，还可以用自然语言描述提交意图，如/commit Meetings/Eng/ “更新了与设计团队的评审纪要”。代理会根据你修改的文件内容，结合你的描述，生成一条清晰的提交信息。它封装了git add和git commit的步骤，让版本管理更无缝。

3. 从零开始的完整配置与部署指南

纸上得来终觉浅，绝知此事要躬行。下面我将结合自己的实操经验，带你一步步搭建起一个可用的ObsidianOS: Work环境。我会假设你使用的是macOS或Linux系统，Windows用户可能需要稍作调整（主要在于环境变量和路径）。

3.1 基础环境准备

首先，我们需要确保所有依赖的基础软件就位。

1. 安装Node.js和包管理器系统需要Node.js 20或更高版本来运行一些脚本。建议使用Node版本管理器（如nvm）进行安装，这样可以轻松切换版本。

# 安装nvm（如果尚未安装） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 重新打开终端或运行 source ~/.zshrc (或 ~/.bashrc) # 安装并使用Node.js 20 nvm install 20 nvm use 20

验证安装：node --version应输出 v20.x.x。

2. 获取ObsidianOS: Work仓库不建议直接克隆原仓库，因为你需要将其作为自己私人笔记库的起点。更好的方式是Fork到自己的GitHub账户，然后克隆Fork后的版本。

# 1. 在GitHub上Fork https://github.com/benoror/obsidianos_work 仓库 # 2. 克隆你自己的Fork git clone https://github.com/<你的用户名>/obsidianos_work.git my-obsidian-work-vault cd my-obsidian-work-vault

这样，你既拥有了一个干净的起点，又方便未来通过设置上游仓库来同步模板的结构性更新。

3. 安装项目依赖进入项目目录后，安装所需的npm包。

npm install

这个命令会根据package.json安装必要的依赖，主要是用于本地搜索的qmd和一些工具脚本。

3.2 核心身份与配置

1. 编辑USER.md文件这是整个系统最重要的个人配置文件。用你喜欢的文本编辑器打开它，填写所有必填项。

# USER.md 示例 name: 张三 email: zhangsan@example.com timezone: Asia/Shanghai # 你的名字可能在不同场合以不同形式出现，在这里列出所有变体 aliases: - 张三 - 张老三 - San Zhang - zhangsan

aliases字段至关重要。在后续的/fill-participants等技能中，系统会识别这些别名，并避免为“你自己”创建人物链接。请务必仔细填写，包括中英文名、昵称、邮箱前缀等所有可能出现在笔记中的指代。

2. （可选）配置环境变量复制环境变量示例文件，并根据需要修改。大部分配置与Google Workspace CLI (gws) 相关。

cp .env.example .env # 编辑 .env 文件，通常你可能需要设置Google Cloud项目ID或调整缓存路径

3.3 关键外部服务集成

1. 安装并配置 Google Workspace CLI (gws)这是实现日历、邮件、文档自动化的核心。gws是一个官方工具，允许你在命令行安全地访问Google API。

• 安装：选择最适合你的方式。我推荐使用Homebrew（macOS）或直接从GitHub下载预编译二进制文件。

  # macOS 使用 Homebrew brew install googleworkspace-cli # 或者使用npm全局安装 # npm install -g @googleworkspace/cli

• 授权登录：这是最关键的一步。运行登录命令，它会打开浏览器让你授权。

  gws auth login

  在授权页面，你需要选择一个Google账号，并同意其请求的权限范围。这里有一个重要技巧：为了最小化权限，你可以使用--scopes参数指定仅需要的只读权限。例如，如果只用日历和Gmail，可以这样：

  gws auth login --scopes https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/gmail.readonly

  授权成功后，凭证会保存在~/.config/gws/目录下。之后技能就能用它来读取你的数据了。

• 实操心得：第一次运行/meeting技能时，可能会因为gws的缓存或权限问题失败。建议先手动在终端测试一个gws命令，如gws calendar events list --time-min="2024-01-01T00:00:00Z" --max-results=1，确保CLI本身工作正常。

2. 设置QMD本地搜索索引QMD为你的知识库提供快速的语义搜索能力，是/recap技能能“回忆”起相关笔记的关键。

• 创建索引：

  # 将当前仓库添加为一个名为“my_vault”的集合 npx qmd collection add . --name my_vault # 为所有Markdown文件创建嵌入向量（这可能需要一些时间，取决于库的大小） npx qmd embed

• 启动MCP服务器（供Cursor等连接）：项目已经在.cursor/mcp.json中配置好了QMD服务器。当你使用Cursor打开这个项目时，它会自动读取这个配置并建立连接。你可以手动测试服务器是否正常：

  npx qmd mcp # 保持这个终端运行，在另一个终端测试搜索 # npx qmd query "上周的会议纪要"

3.4 关联Obsidian与AI代理

1. 用Obsidian打开仓库直接将整个项目文件夹作为Obsidian的库打开。打开Obsidian，选择“打开文件夹为库”，然后选中你的my-obsidian-work-vault目录。

• 重要设置：为了避免Obsidian的文件管理器被node_modules等工程文件夹干扰，需要将其排除。
  • 在Obsidian中，进入设置 -> 文件与链接 -> 排除的文件。
  • 添加以下模式：node_modules,.git,.cursor。这样界面会更清爽。

2. 配置你的AI代理这里以最常用的Cursor为例。

• 用Cursor IDE打开同一个项目文件夹。
• Cursor会自动加载项目根目录下的.cursor文件夹中的配置。这意味着.cursor/rules/下的所有规则文件都会生效，告诉Cursor在这个项目中应该如何行为（例如，优先使用预定义的技能）。同时，.cursor/mcp.json中配置的QMD MCP服务器也会被连接。
• 验证：在Cursor的聊天面板或命令行中，尝试输入/，你应该能看到弹出的技能列表，如/meeting、/recap等。如果没出现，可以尝试重启Cursor或检查.cursor目录的权限。

对于Claude Code或OpenCode，你需要参考项目中的CLAUDE.md或OpenCode.md文件进行类似的配置，主要是确保它们能正确链接到.claude/skills/或.opencode/skills/（这些目录都是指向.agents/skills/的符号链接）。

4. 核心技能实战演练与避坑指南

配置完成只是开始，真正发挥威力在于日常使用。下面我以几个最常用的技能为例，展示完整的工作流，并分享我遇到的典型问题及解决方案。

4.1 会议管理全自动化 (/meeting&/cache-notes&/fill-participants)

场景：你每天有多个线上会议，希望会后能自动生成包含转录稿和参与者链接的完整笔记。

标准化操作流：

1. 会前生成笔记框架：每天早上一到工位，在Cursor中运行/meeting today。代理会调用gws读取你今天的日历，然后为你每个会议生成一个笔记文件，保存在Meetings/目录下（你可以根据项目在USER.md中配置默认子目录）。生成的文件已经包含了会议标题、时间、Google Meet链接和预设的议程、结论、行动项板块。
2. 会中记录：在生成的笔记中，直接在“议程”部分用 bullets 记录讨论要点。
3. 会后补充转录稿：会议结束后（通常几分钟后AI转录稿会生成），在Cursor中运行/cache-notes <你的会议笔记文件路径>。例如/cache-notes Meetings/Eng/2024-05-20-项目周会.md。技能会自动查找关联的Google Docs转录稿，并将其内容作为一个折叠的“引用块”添加到笔记末尾。
4. 自动链接人物：接着运行/fill-participants <同一笔记路径>。技能会扫描整篇笔记（包括刚嵌入的转录稿），识别出所有提到的人名（如“张三”、“李四”、“王工”），并将它们替换为Obsidian内部链接[[@张三]]、[[@李四]]。如果Teams/People/目录下没有对应的人物文件，技能会提示你创建。
5. 提取行动项：最后运行/followup-todos <同一笔记路径>。技能会解析笔记文本，找出所有指派了任务或带有时间暗示的句子（如“李四下周提交报告”、“需要王工确认API设计”），将它们以普通列表项的形式提取出来，并汇总追加到库根目录的ToDo‘s.md文件中。

避坑技巧与心得：

• /fill-participants的别名匹配：这个技能依赖一个简单的名字词典。如果同事在笔记中被称呼为“老王”，但人物文件叫@王伟.md，那么链接会失败。你需要在@王伟.md文件的frontmatter或别名中，加入“老王”这个别名。系统设计是，先匹配USER.md中你的别名来排除自己，然后匹配已有@Person文件中的名字和别名，最后才提示创建新文件。
• 转录稿的定位：/cache-notes技能默认会寻找与会议标题或时间匹配的Google Doc。有时匹配可能不准。我的经验是，在Google Calendar中创建会议时，如果使用了“添加转录”功能，最好在会议描述或标题中留下一个容易搜索的关键词。技能的逻辑是优先搜索“会议标题 + transcript”相关的文档。
• 人物文件的维护：初期需要手动创建一些核心同事的人物文件。可以在Teams/People/目录下新建@姓名.md，在文件里用YAML frontmatter记录其部门、职位，并在正文中记录与其相关的关键项目、沟通习惯等。这不仅是链接，更是构建你的人际知识网络。

4.2 智能周报生成 (/recap)

场景：每周五下午，你需要花一小时从零开始拼凑周报，回忆这周开了什么会、讨论了什么、邮件里说了啥。

自动化工作流： 在周五下午，运行命令/recap last-week。接下来，观察代理的工作：

1. 数据收集阶段：代理会并行执行多个查询。
   • 通过gws获取过去7天你日历中的所有事件（标题、时间、参与者）。
   • 通过gws获取过去7天你Gmail收件箱和发件箱的邮件主题和发件人（不获取正文，保护隐私）。
   • 通过qmd的MCP服务器，在你的Obsidian库中执行语义搜索，查找过去一周创建或修改的、可能与“周报”、“总结”、“进展”相关的笔记。
2. 分析与生成阶段：代理收到所有数据后，会尝试进行整合分析。
   • 它将日历事件按天分组，形成“周一至周五”的时间线。
   • 它将相关的邮件主题与日历事件进行关联（例如，某次会议后的邮件往来）。
   • 它从你的Obsidian笔记中提取关键更新和结论。
   • 最后，它生成一份结构化的Markdown周报草稿，通常包含“本周会议”、“关键讨论与决策”、“邮件往来摘要”、“笔记更新亮点”和“下周初步安排”等部分，并保存到Recaps/目录下，以当前日期命名。

避坑技巧与心得：

• qmd索引的更新：/recap技能的效果严重依赖qmd索引的质量和新鲜度。如果你这一周写了大量新笔记，但没更新索引，那么技能就“看不到”这些新内容。养成习惯：在运行/recap前，先执行一下npx qmd embed来更新索引。你可以考虑设置一个简单的cron任务或使用Obsidian Git插件在提交时自动触发。
• 生成内容的准确性：AI生成的总结是基于它“看到”的文本进行的概括，可能遗漏细节或产生误解。切记：/recap生成的是“草稿”，而不是最终成品。它的价值在于为你完成了80%的信息收集和初步整理工作，你必须亲自审阅、修正和补充剩下的20%，尤其是关键数据和决策点。
• 隐私边界：这个技能只读取邮件主题和日历事件，不读取邮件正文，这是一个很好的隐私设计。但如果你对日历事件的标题敏感（例如包含客户名称或机密项目代号），可以在创建日历时使用更通用的标题，或在USER.md中配置某些关键词过滤（如果技能支持的话，可能需要修改技能脚本）。

4.3 版本控制与上游同步 (/commit&/sync-upstream-obsidianos)

场景：你既想用Git管理笔记版本，又觉得写提交信息麻烦；同时，你希望自己的笔记库能持续获得模板本身的功能更新。

自动化工作流：

1. 智能提交：完成一批笔记的编辑后，在项目根目录运行/commit . “更新了本周项目会议纪要和行动项”。代理会执行git add .，然后结合你提供的描述和它分析出的文件变更内容（通过git diff），生成一条更丰富的提交信息，例如“更新了本周项目会议纪要和行动项\n\n- 补充了与后端关于API设计的结论\n- 明确了前端交付时间点”，然后执行git commit -m “...”。
2. 同步模板更新：每隔一段时间（比如一个月），运行/sync-upstream-obsidianos。这个技能会检查上游仓库（即你最初Fork的那个benoror/obsidianos_work）是否有更新。它会以“预览”模式展示即将合并的更改（主要是技能定义、规则、脚本等结构性文件），并询问你是否确认合并。它通过.gitattributes文件的配置，确保合并过程不会覆盖你的个人数据（如USER.md、Meetings/、Teams/等目录）。

避坑技巧与心得：

• /commit的意图理解：代理生成的提交信息质量，取决于你提供的自由文本描述和实际变更的关联度。描述越具体越好。例如，“修复了人物链接错误”就比“更新笔记”要好得多。如果对生成的描述不满意，你可以随时用/commit . --amend来修改上一条提交信息。
• 同步冲突处理：/sync-upstream-obsidianos脚本使用了git merge策略。如果上游的某个脚本文件（如.agents/skills/meeting.md）和你本地修改过的版本冲突了，合并会暂停，需要你手动解决冲突。最佳实践是：尽量不要修改.agents/、.cursor/rules/等核心模板文件。如果你有自定义需求，应该复制一份到个人目录，或者通过USER.md和.env中的配置项来调整行为。这样在同步时就能平滑合并。
• 个人数据的保护：仔细检查项目根目录下的.gitattributes文件。它定义了哪些文件在合并时被视为“我们的”（即保留你的版本）。默认配置已经保护了关键个人目录。如果你在Templates/目录下创建了自己的模板，建议也将它们加入保护列表，例如添加一行Templates/* merge=ours。

5. 高级技巧、问题排查与个性化定制

5.1 性能优化与日常维护

• QMD索引速度：如果库内笔记超过上千篇，npx qmd embed可能会比较慢。可以考虑在package.json中添加一个脚本，只索引新增或修改的文件（如果qmd支持增量更新）。或者，将其设置为夜间自动运行的系统任务。
• Obsidian启动速度：安装了较多社区插件后，Obsidian启动可能会变慢。ObsidianOS: Work推荐的插件都是精挑细选的，但如果你添加了大量其他插件，可能会影响体验。定期检查并禁用不常用的插件。
• gws凭证过期：Google OAuth凭证通常有较长的有效期，但也可能过期。如果技能突然无法访问Google服务，并报权限错误，尝试运行gws auth login --force重新授权。

5.2 常见问题排查速查表

5.3 个性化扩展你的技能库

ObsidianOS: Work的真正强大之处在于它的可扩展性。.agents/skills/目录下的每个.md文件都是一个技能定义。你可以模仿现有技能，创建属于自己的自动化流程。

举例：创建一个/log-work技能假设你想每天下班前快速记录当天的工作日志。

1. 创建技能文件：在.agents/skills/目录下创建log-work.md。
2. 编写技能描述：用自然语言清晰描述这个技能。

   # Skill: /log-work **Description**: Create or append to a daily work log note. **Usage**: `/log-work [optional-note]` **Steps**: 1. Determine today‘s date in YYYY-MM-DD format. 2. Check if a file named `Logs/YYYY-MM-DD.md` exists. If not, create it using the template `Templates/DailyLog.md`. 3. If the user provided an optional note (e.g., “Finished the API design document”), append it as a bullet point under a “## Evening Log” section in the note. 4. If no note was provided, simply open the file in Obsidian for manual editing. 5. Output the path to the created/updated note. **Template Reference**: `Templates/DailyLog.md` should contain frontmatter and headings like `## Morning Plan`, `## Evening Log`.

3. 创建模板：在Templates/目录下创建DailyLog.md模板文件。
4. 测试：在Cursor中，现在输入/log-work，它应该能理解并执行这个新技能。你可以进一步复杂化它，比如让它从时间追踪工具中拉取数据。

通过这种方式，你可以将任何重复的、基于文本的工作流封装成技能，让AI代理成为你的专属自动化助手。这套系统的边界，只取决于你的想象力和对命令行工具的熟悉程度。它不是一个封闭的软件，而是一个开放的、鼓励你动手改造的自动化工作台。