Yoda for Obsidian

Yoda 把 Obsidian 编辑器里的 @ 变成一个统一对象入口：既能像 Mention Path 一样引用文件路径，也能选择预配置 Agent、继续输入指令，并在回车后把任务交给本机 Agent Client 执行。

当前版本是可安装的桌面端 MVP（0.1.16）。它已经实现完整主链路，但尚未提交 Obsidian 官方社区插件目录。

核心概念

• Agent Client / Runtime：需要安装在电脑上的完整 Agent 软件，例如 Codex CLI、Claude Code（cc）。
• Agent：Client + 模型 + 推理深度 + 使用速度 + 角色定义，再加上昵称、头像和一句话说明组成的调用主体。
• Task：一次具体的 @Agent 指令。Task 有自己的状态、日志、笔记锚点和版本历史。

已实现

• 在行首或空白后输入 @，同一悬浮窗列出 Agent、文件和目录。
• 文件引用支持 ../、~/、目录下钻、递归搜索与相对路径插入。
• 选择 Agent 后继续在原文内输入指令；回车触发任务。
• 输入位置生成可点击锚点：[◐ @Yoda：把这一段写清楚…](obsidian://yoda?task=...)，只用图标表示状态，并保留缩略问题。
• 点击锚点打开右侧 Yoda 任务视图，并定位到对应任务。
• 侧栏输入框可直接 @Agent 发起任务，支持键盘选择、图片选择、粘贴与拖入；任务仍锚定当前文档光标和附近上下文。
• 侧栏一级页面包括文件对话、独立版本管理与设置；Agent 管理收进设置，每次对话的运行记录作为可返回的二级详情打开。
• “清屏”会把当前文件的对话移入归档而不是删除；归档作为二级页面查看，并支持逐条恢复。
• 运行页把不同 Client 的原始事件统一为用户提问、Agent 过程、连续工具活动、最终答复和待确认动作；工具与原始 transcript 默认折叠，需要诊断时再展开。
• 实时输出只在视图接近底部时自动跟随；向上阅读时保留当前位置，并提供“跳到最新”。
• 侧栏遵循 Obsidian 的紧凑工具栏与扁平列表样式；版本历史使用短动作标题并在当前条目下展开 diff。
• 点击侧栏标题可在主编辑区定位当前文档；标题旁的历史菜单可切换所有已有 Yoda 对话的文档。
• Codex、Claude Code 和自定义 CLI runtime；模型、推理深度、速度、角色、昵称、头像、说明均可配置。
• Agent 以只读权限运行，结合锚点附近上下文返回结构化改写；插件只在包含锚点的目标原文唯一匹配时写入，并在成功后消费锚点。
• 每次锚点插入、Agent 写回、状态写回和用户回退都保存完整前后快照。
• 任意版本可一键回退；回退本身也会先保存版本，因此不会形成不可逆覆盖。

安装

1. 安装 Agent Client

至少安装一个：

# 验证 Codex
codex --version

# 验证 Claude Code
claude --version

并按各 Client 的方式完成登录。Yoda 不保存 API Key，也不会绕过 Client 自己的认证。

2. 安装插件

仓库地址：lovstudio/obsidian-yoda。可通过 BRAT 添加该仓库，或使用下面的手动安装方式。

运行：

npm install
npm run build

把下列文件复制到 vault：

<vault>/.obsidian/plugins/yoda-agent/
├── main.js
├── manifest.json
└── styles.css

重新加载 Obsidian，在“设置 → 第三方插件”中启用 Yoda。

3. 配置 Agent

打开“设置 → Yoda”：

1. 在 Agent Clients / Runtimes 检查 codex 或 claude 是否可用。
2. 在 Agents 修改昵称、头像、说明、Client、模型、推理深度、速度和角色定义。
3. 默认开启“自动应用安全改写”。关闭后，所有改写都会先停在侧栏等待手动应用。

使用

在笔记里输入：

@Yoda 把下面两段合并，保留事实和我的语气

选择“交给 @Yoda”并回车。原输入被替换为任务锚点，右侧栏立即显示运行状态。Agent 完成后：

• 如果返回的目标原文仍在锚点附近且只出现一次，Yoda 自动融合上下文改写，并移除已经完成使命的锚点。
• 如果只是纯问答，回答只进入群聊，不会机械追加到文章正文。
• 如果用户已经改过原文、锚点被删除、目标重复或输出格式不安全，任务进入“等待输入”，不会强行覆盖。
• 独立“版本”页面可逐行 review before/after diff，并回退到任意一次改动发生前。

文件路径行为与 obsidian-mention-path 的主要交互保持一致：

@../
@~/Projects/
@meeting-notes

版本与安全边界

版本快照默认保存在：

<vault>/.obsidian/yoda/history/<task-id>/

这个目录不会放在插件安装目录内，升级或重装插件不会顺带删除历史。当前版本保存的是相关笔记的完整前后文本，便于可靠回退；它不会扫描或复制整个 vault。

Codex 固定使用 --sandbox read-only；Claude Code 固定使用 --permission-mode plan 且只开放 Read / Glob / Grep。自定义 CLI 是否严格只读取决于该 Client 自身，建议在额外参数中明确配置只读模式。

开发与验证

npm run typecheck
npm run test
npm run build
# 或一次运行全部
npm run verify

开发构建已接入 lovinsp。运行 npm run dev 后，在 macOS 按住 Option + Shift 点击 Yoda UI 可复制源码位置；再加 Command 可直接在 IDE 打开。npm run dev 会持续监听并同步到 .env 指定的 Vault；只需恢复一次 开发安装时可运行 npm run build:dev。不要将 npm run build 生成的 Release bundle 安装到开发 Vault，因为 Release 构建不会包含调试器或源码定位属性。

架构

EditorSuggest (@)
  ├─ File / Folder → 相对路径
  └─ Agent + 指令
       ├─ 插入 obsidian://yoda 锚点
       ├─ 保存触发前后快照
       ├─ 只读启动 Codex / Claude / Custom CLI
       ├─ 解析 <yoda-result> JSON
       ├─ 校验包含锚点的唯一上下文
       ├─ 插件受控写回、消费锚点、保存前后快照
       └─ 群聊输入 / 版本 Review / 会话式运行记录 / 归档 / 设置

致谢

文件路径交互参考了 MIT 许可的 MarkShawn2020/obsidian-mention-path。Yoda 的 Agent / Runtime 分层沿用 LovStudio Yoda 产品中的同名概念，但本插件独立运行，不要求安装 Yoda 桌面应用。

License

MIT