Obsidian - read, search, write and edit direct to obsidian vault.

核心用法

Obsidian 技能将本地 Markdown 知识库转化为结构化数据源，通过 CLI 工具集实现：

• 智能检索：基于 ripgrep 的模糊搜索，支持俄英语音匹配与标题加权排序
• 笔记管理：创建/读取/编辑完整生命周期，自动识别最佳存放文件夹
• 元数据操作：Frontmatter 字段（created/modified/tags/aliases）的增删改查
• 链接网络：解析双向链接（wikilinks）与标签关系，维护知识图谱

显著优点

• 本地化优先：直接操作文件系统，无需云端同步，数据完全自主可控
• 生态兼容：原生支持 Obsidian 格式（[[wikilinks]]、YAML frontmatter、#标签）
• 检索智能：拼音/语音模糊匹配解决多语言输入偏差，上下文片段精准定位
• 工作流闭环：查询→引用→创建→链接的完整知识沉淀链条

潜在局限

• 单用户架构：Vault 路径硬编码为 /home/ruslan/webdav/...，缺乏多租户隔离
• 无版本控制：直接覆盖编辑，误操作不可逆（需外部 Git 备份）
• 性能边界：ripgrep 虽快，但超大库（10万+笔记）的模糊评分可能延迟
• 依赖本地环境：Python 脚本 + 特定路径，迁移需重新配置

适合人群

• Obsidian 重度用户寻求 AI 增强工作流
• 需要结构化长期记忆的个人知识管理者
• 研究/写作场景要求溯源引用（[[Note Name]]）的学术用户

常规风险

| 风险类型 | 说明 | 缓释建议 |

|---------|------|---------|

| 数据覆盖 | `replace`/`replace-section` 直接改写文件 | 关键笔记先 `read` 备份 |

| 路径遍历 | `--vault` 参数若注入可能越权 | 校验路径前缀白名单 |

| 编码问题 | 俄英混排内容可能 frontmatter 解析异常 | 强制 UTF-8 处理 |

| 隐私泄露 | 搜索内容可能含敏感信息进入 LLM 上下文 | 本地处理优先，避免上传全文 |

核心功能

Obsidian Knowledge Base Skill 是一套用于管理本地 Obsidian 笔记库的 CLI 工具集，基于 Python 标准库构建，提供完整的知识库操作能力。

搜索能力：采用 ripgrep 实现高速模糊搜索，支持俄英音译匹配、标题权重排序、标签匹配，返回带评分的上下文片段。当 ripgrep 不可用时自动降级至系统 grep。

笔记管理：支持创建（含自动文件夹检测）、读取、编辑（追加/前置/全文替换/区块替换）四种操作模式，自动维护 frontmatter 时间戳。支持 Obsidian 原生语法：wikilinks [[Note]]、别名链接 [[Note|显示文本]]、区块锚点 [[Note#标题]]。

元数据处理：完整支持 YAML frontmatter 的解析与生成，包括 created、modified、tags、aliases 等标准字段。

显著优势

• 零依赖架构：仅使用 Python 标准库（argparse、subprocess、pathlib、datetime、re），供应链攻击面为零
• 性能优化：ripgrep 底层保障大库搜索速度，10-30 秒超时控制防止资源耗尽
• 智能分类：suggest-folder 与 --auto-folder 基于内容自动推荐存储位置，降低认知负担
• 隐私优先：纯本地运行，无网络外联，数据不出境

局限性与风险

• 来源可信度 T3：ClawHub 社区项目，无 GitHub 开源仓库验证，代码历史审计缺失
• Subprocess 依赖：搜索功能依赖外部 ripgrep/grep 进程，虽经输入转义（re.escape）和超时控制，仍存在理论上的命令注入风险（当前评估为低风险）
• 路径硬编码：文档示例包含特定用户路径（/home/ruslan/...），需用户手动配置环境变量
• 无单元测试：缺少自动化测试覆盖，边界行为（超大文件、特殊字符）未验证

适合人群

• 已使用 Obsidian 作为主力笔记工具的个人用户
• 对数据隐私敏感、拒绝云端同步的本地优先主义者
• 需要通过 AI 助手自动化知识库整理、摘要、链接维护的效率用户
• 具备基础 Linux/终端操作能力的用户

使用建议

部署前请：1）修改 OBSIDIAN_VAULT 环境变量指向实际库路径；2）确认系统已安装 ripgrep（rg）以获得最佳性能；3）首次使用前审查 obsidian_search.py 中的正则转义逻辑；4）考虑在 GitHub 上开源此 Skill 以提升可信度和社区审计。