name: knowledge-obsidian description: 通用知识库查询与更新技能，支持向量库语义检索和增量更新。触发词包括：知识库查询、查询知识库、搜索知识库、知识库问答、更新知识库、初始化知识库、向量库查询、语义搜索。

Knowledge-Obsidian 知识库查询技能

通用的Obsidian知识库查询与更新技能，基于向量库实现语义检索，支持增量更新和混合检索（向量+BM25）。

快速开始

1. 首次使用 - 初始化向量库

Windows PowerShell：

cd {{skillpath}}\scripts
.\.venv\Scripts\python.exe init_vector_db.py

Linux/Mac：

cd {{skillpath}}/scripts
python init_vector_db.py

2. 查询知识库

Windows PowerShell：

cd {{skillpath}}\scripts
.\.venv\Scripts\python.exe query_vector_db.py "查询关键词" 5

Linux/Mac：

python /path/to/knowledge-obsidian/scripts/query_vector_db.py "查询关键词" 5

3. 更新向量库

当知识库文档发生变化后，执行增量更新：

Windows PowerShell：

cd {{skillpath}}\scripts
.\.venv\Scripts\python.exe update_vector_db.py

Linux/Mac：

python update_vector_db.py

配置说明

知识库路径配置

编辑 scripts/config.py 文件，修改以下配置：

# 知识库根路径（修改为您的知识库路径）
_WINDOWS_KB_PATH = r"D:\path\to\your\knowledge_base"

# 知识库模块列表（根据实际目录结构修改）
MODULES = ["模块1", "模块2", "模块3"]

# 文档类型（根据实际分类修改）
DOC_TYPES = ["design", "prd", "doc"]

其他可配置项

# 嵌入模型配置
EMBEDDING_MODEL = "jinaai/jina-embeddings-v2-base-zh"  # 中文专用模型
EMBEDDING_DIMENSION = 768  # 向量维度

# 文档切分配置
CHUNK_SIZE = 800  # 每个chunk的最大字符数
CHUNK_OVERLAP = 100  # chunk之间的重叠字符数

# 向量检索配置
TOP_K = 5  # 默认返回结果数量

# 混合检索权重
BM25_WEIGHT = 0.3  # BM25关键词检索权重
VECTOR_WEIGHT = 0.7  # 向量检索权重

功能特性

1. 向量库查询

功能优势： - Token消耗减少60-80% - 支持语义相似度搜索，更智能 - 查询速度提升3-5倍 - 使用本地开源嵌入模型，无需API密钥

查询参数： - 第一个参数：查询关键词（必填） - 第二个参数：返回结果数量（可选，默认5）

查询结果格式：

================================================================================
查询结果
================================================================================

【结果 1】
综合分数: 0.4493
模块: 模块1
文档类型: design
文件名: 示例文档.md

关键内容:
--------------------------------------------------------------------------------
1. 这是示例文档的关键内容
2. 用于演示查询结果格式
--------------------------------------------------------------------------------

[SUCCESS] 查询成功，共返回 3 条结果

2. 向量库初始化

首次使用时，需要初始化向量库：

初始化流程： 1. 扫描知识库目录下的所有md文件 2. 按标题层级智能切分文档 3. 保护表格和代码块的完整性 4. 为每个文档片段生成向量嵌入 5. 存储到本地向量数据库

初始化时间： - 约100个文档：1-2分钟 - 约500个文档：5-10分钟

3. 向量库增量更新

当知识库文档发生变化后，执行增量更新：

更新策略： - 检测新增文件 → 添加向量 - 检测修改文件 → 删除旧向量 + 添加新向量 - 检测删除文件 → 删除对应向量 - 无变化 → 跳过更新

更新时间： - 增量更新通常只需几秒到几十秒

技术方案

嵌入模型

模型：jinaai/jina-embeddings-v2-base-zh - 中文专用模型，768维向量 - 无需API密钥，完全本地运行 - 使用 ONNX Runtime，不需要 PyTorch - 模型自动下载到 {{notepath}}/models/ 目录

向量数据库

数据库：ChromaDB 0.5.0 - 本地存储，无需外部服务 - 支持持久化和增量更新 - 状态文件：{{notepath}}/.vector_db/status.json

文档切分策略

智能切分： - 按标题层级切分（H1、H2、H3） - 保护表格完整性（不切分表格） - 保护代码块完整性（不切分代码块） - 保护YAML frontmatter完整性 - chunk之间有重叠，保持语义连贯性

混合检索

检索策略： - 向量检索（语义相似度）：权重 0.7 - BM25检索（关键词匹配）：权重 0.3 - 综合评分 = 向量分数 × 0.7 + BM25分数 × 0.3

使用约束

重要约束

1. 环境要求：根据运行环境选择正确的执行方式
2. Windows：使用PowerShell执行Python脚本

3. Linux/Mac：直接执行Python脚本

4. 禁止绕过：向量库查询报错时，不允许绕过向量库直接使用grep等其他方式查询，必须先修复向量库环境问题

5. 查询失败处理：如果向量库查询失败，应向用户报告错误信息并请求协助修复，不得切换到其他查询方式

6. 定期更新：知识库内容更新后，需要手动触发向量库增量更新

7. 依赖版本：确保使用正确的依赖版本

8. chromadb==0.5.0
9. fastembed>=0.8.0
10. onnxruntime==1.17.1
11. numpy<2.0

查询脚本执行标记

查询脚本会在输出末尾显示执行状态： - [SUCCESS] 查询成功，共返回 N 条结果 - 查询成功 - [ERROR] 查询失败: 错误信息 - 查询失败

即使输出被截断，也能通过末尾标记判断查询是否成功。

安装与部署

方式1：使用 uv（推荐）

cd knowledge-obsidian/scripts
uv venv
uv pip install -r requirements.txt

方式2：使用 pip

cd knowledge-obsidian/scripts
python -m venv .venv
.\.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/Mac
pip install -r requirements.txt

方式3：使用已有的虚拟环境

如果已有相同依赖的虚拟环境，可以直接使用：

.\.venv\Scripts\python.exe init_vector_db.py
.\.venv\Scripts\python.exe query_vector_db.py "测试" 5
.\.venv\Scripts\python.exe update_vector_db.py

文件结构

knowledge-obsidian/
├── SKILL.md                      # 技能说明文档（本文件）
├── scripts/                      # 脚本目录
│   ├── config.py                 # 配置文件
│   ├── init_vector_db.py         # 初始化向量库
│   ├── update_vector_db.py       # 更新向量库
│   ├── query_vector_db.py        # 查询向量库
│   ├── requirements.txt          # 依赖列表
│   └── __init__.py               # Python包初始化
└── .venv/                        # 虚拟环境目录（首次部署时创建）

故障排查

问题1：ONNX Runtime DLL 加载失败

• 确保使用 onnxruntime==1.17.1 版本
• 检查是否有其他版本的 onnxruntime 冲突

问题2：向量库初始化失败

• 检查知识库路径是否正确
• 检查是否有足够的磁盘空间
• 检查文档格式是否符合规范（UTF-8编码的Markdown文件）

问题3：查询结果不准确

• 尝试调整TOP_K参数（在 config.py 中）
• 检查文档切分是否合理
• 考虑使用更大的嵌入模型

问题4：NumPy 版本冲突

• 确保使用 numpy<2.0 版本
• ChromaDB 0.5.0 不兼容 NumPy 2.x

问题5：路径转换错误

• 检查 config.py 中的 _convert_path() 函数
• Windows路径使用 r"D:\path\to\kb" 格式
• Linux/Mac会自动转换为 /d/path/to/kb 格式

问题6：查询超时或输出被截断

• 查看输出末尾是否有 [SUCCESS] 或 [ERROR] 标记
• 减少返回结果数量（如从10改为5）
• 查看截断提示中的完整输出文件路径

更新日志

v1.0.0 (2026-06-11)

• 初始版本
• 支持向量库查询、初始化、增量更新
• 支持混合检索（向量+BM25）
• 支持智能文档切分
• 支持跨平台路径转换
• 添加查询成功/失败标记

常见问题

Q: 如何判断向量库是否需要更新？

A: 当知识库目录下的md文件有新增、修改或删除时，需要执行增量更新。建议每次修改知识库后都执行一次 update_vector_db.py。

Q: 初始化向量库需要多长时间？

A: 取决于文档数量。约100个文档需要1-2分钟，约500个文档需要5-10分钟。首次初始化后，后续增量更新只需几秒到几十秒。

Q: 可以使用其他嵌入模型吗？

A: 可以。修改 config.py 中的 EMBEDDING_MODEL 参数。推荐使用fastembed支持的模型，如： - jinaai/jina-embeddings-v2-base-zh（中文，768维） - BAAI/bge-small-en-v1.5（英文，384维） - BAAI/bge-base-en-v1.5（英文，768维）

Q: 向量库占用多少磁盘空间？

A: 取决于文档数量和嵌入维度。约500个文档（768维向量）约占用100-200MB空间。

Q: 如何备份向量库？

A: 直接复制 {{notepath}}/.vector_db/ 目录即可。包含： - chroma.sqlite3 - 向量数据库 - status.json - 文件状态记录

Q: 支持哪些文档格式？

A: 目前仅支持Markdown（.md）格式的文档。文档应使用UTF-8编码，支持YAML frontmatter元数据。

这是一款实用的知识库检索工具，能在 Obsidian 笔记中快速找到相关内容，比普通搜索更智能。优点是检索准确、支持中文、无需付费；不足是初次配置需要手动改设置，更新索引要手动操作，对新手不太友好。质量属于中上水平，功能完整但入门门槛略高。