用途
该技能用于为文档语料库建立语义搜索索引，帮助用户搭建知识库、从 Markdown 文档创建可搜索索引，并启用语义检索能力。索引基于 qmd 工具完成。
前置条件
需要先安装 qmd：
bun install -g @tobilu/qmd
安装后验证：
qmd --version
文档必须为 Markdown 格式。若为 PDF/DOCX，需先使用 /parse 进行转换。
主要能力与工作流程
-
验证 qmd：运行
qmd --version，若未安装参见前置条件。 -
创建集合：
qmd collection add <path> --name <name>
参数说明：path 为文档目录路径（必填）；name 为集合名称（默认取目录名）。示例：
qmd collection add ./docs --name my-project
qmd collection add ~/Documents/api-docs --name api-docs
- 添加上下文（可选）：为提升检索效果，可添加语义上下文描述：
qmd context add qmd://<name> "<description>"
示例：
qmd context add qmd://api-docs "API documentation for the project"
qmd context add qmd://contracts "Legal contracts and agreements"
- 生成嵌入：
qmd embed
该命令为集合中所有文档创建向量嵌入。
- 验证设置：
qmd status
应显示集合及文档数量。
完整示例：
# Create collection
qmd collection add ./docs --name my-project
# Add context
qmd context add qmd://my-project "Project documentation and guides"
# Generate embeddings
qmd embed
# Verify
qmd status
响应要求
使用该技能时，最终回答中始终需包含：将创建/使用的集合名称（如 my-project）、被索引的源文档路径（如 ./docs）、索引/集合的存储位置（qmd 集合位置）以及验证命令（qmd status）。不得省略存储位置信息。
适用场景
适合中小型语料库、离线使用场景。设置完成后，可使用 /search 搜索文档。
限制与故障排查
若出现 “sqlite-vec is not available”，说明 qmd 需要支持扩展加载的 SQLite。解决方案：macOS 使用 brew install sqlite；Linux 从源码构建 sqlite-vec；Docker 使用官方 qmd Docker 镜像。详见 docs/qmd-setup.md。
若嵌入失败，可检查：qmd status、确认文档存在（ls -la <path>）、检查空文件（find <path> -empty）。
提供方说明
qmd（当前）：存储为本地 SQLite（含 sqlite-vec 扩展）；嵌入使用本地模型（无需 API 密钥）；适合中小型语料库与离线使用。
pinecone（计划中）：存储为 Pinecone 云端；嵌入使用 OpenAI 或自定义嵌入；适合大规模生产部署；设置需 PINECONE_API_KEY 环境变量。
weaviate（计划中）：存储为 Weaviate 实例（自托管或云端）；嵌入可配置；适合需要混合搜索的企业部署；设置需 WEAVIATE_URL，可选 WEAVIATE_API_KEY。