name: enable-semantic-search description: 启用本地AI驱动的语义搜索，带有智能集合发现
启用语义搜索
为您的保管库设置本地AI驱动的语义搜索。这是一个礼宾服务体验 — 它分析您的保管库，发现合理的集合，并创建定制的搜索设置。
您要启用的功能
语义搜索通过含义查找内容，而不仅仅是关键词：
- 搜索“产品主导增长” → 找到提到“PLG”、“自助服务”、“免费增值采用”的笔记
- 搜索“客户流失” → 找到关于“留存问题”、“用户离开”、“取消模式”的笔记
您的技能（如/daily-plan、/meeting-prep、/triage等）在可用时自动使用语义搜索，找到比仅关键词匹配更相关的上下文。
预检查
继续前运行这些检查：
# 检查是否已安装qmd
which qmd
# 检查Bun是否可用（必需）
which bun
# 仅macOS：通过Homebrew检查SQLite
brew list sqlite 2>/dev/null && echo "SQLite OK" || echo "需要：brew install sqlite"
# 检查可用磁盘空间（需要约2.5GB）
df -h ~ | tail -1
如果qmd已安装，运行qmd status检查现有设置。如果集合已存在，跳到底部的集合健康检查部分。
第1步：解释我们将安装什么
向用户展示：
═══════════════════════════════════════════════════════════════════════
为您的保管库启用语义搜索
═══════════════════════════════════════════════════════════════════════
这是什么？
─────────────
现在，查找笔记需要知道确切的用词。
搜索“产品主导增长” — 不会找到提到“PLG”或“自助服务”的笔记。
语义搜索理解含义，而不仅仅是关键词。它查找概念上相关的内容，即使术语不同。
它是如何工作的？
─────────────────
您的笔记被转换为“嵌入” — 含义的数学表示。当您搜索时，您的查询也变为嵌入。系统查找含义接近您查询含义的笔记。
想象一下：我们不是在匹配字母，而是在匹配想法。
我们将安装什么？
────────────────────
三个小型AI模型在您的本地机器上运行：
模型 目的 大小
─────────────────────────────────────────────────────────────
EmbeddingGemma-300M 将文本转换为含义向量 约300MB
核心“理解”模型。
Qwen3-Reranker-0.6b 按真实相关性重新排序结果 约640MB
提高结果质量。
QMD-Query-Expansion-1.7B 扩展搜索以包含相关术语 约1.1GB
“PLG” → 也搜索“产品主导”、“免费增值”
总计：约2GB一次性下载
隐私与安全
──────────────────
- 一切都在本地运行 — 您的笔记从不离开您的机器
- 无需API密钥
- 无需云服务
- 模型从HuggingFace下载（开源）
- 索引存储在~/.cache/qmd/（不在您的保管库中）
工作流程有何变化？
──────────────────────────────
启用语义搜索会静默升级这些技能：
/daily-plan — 用主题相关的过去讨论丰富会议准备
/meeting-prep — 通过含义发现过去讨论，而不仅仅是名称匹配
/triage — 通过含义匹配收件箱项与目标，捕获语义重复项
人员查找 — 查找“提到的销售副总裁...”即使没有名字
搜索与回忆 — 所有保管库搜索使用混合检索（BM25 + 向量 + LLM重新排序）
系统要求
───────────────────
约2.5GB磁盘空间（用于模型 + 索引）
macOS：需要Homebrew SQLite（brew install sqlite）
Bun运行时（如果缺失将安装）
第2步：获取用户同意
问：“准备启用语义搜索吗？这将下载约2GB的模型。[Y/n]”
如果否，优雅退出：“没问题。随时运行/enable-semantic-search。”
第3步：安装依赖项
# 如果缺失则安装Bun
if ! command -v bun &> /dev/null; then
echo "安装Bun运行时..."
curl -fsSL https://bun.sh/install | bash
fi
# macOS：如果缺失则安装SQLite
if [[ "$OSTYPE" == "darwin"* ]]; then
if ! brew list sqlite &> /dev/null; then
echo "通过Homebrew安装SQLite..."
brew install sqlite
fi
fi
# 全局安装qmd
echo "安装qmd..."
bun install -g github:tobi/qmd
第4步：下载模型
echo "下载AI模型（约2GB）..."
echo "这是一次性操作。未来搜索即时完成。"
echo ""
echo "正在下载的模型："
echo " EmbeddingGemma-300M — 将文本转换为含义向量"
echo " Qwen3-Reranker-0.6b — 提高结果相关性"
echo " QMD-Query-Expansion — 扩展搜索以包含相关术语"
echo ""
# 通过简单嵌入操作触发模型下载
cd "$VAULT_PATH" && qmd embed --help 2>/dev/null || true
第5步：智能集合发现（礼宾服务）
这使得Dex的语义搜索比通用索引更好。我们分析保管库并创建专为用途的集合，而不是将所有内容转储到一个块中。
运行保管库扫描器
执行保管库扫描器脚本以发现集合候选：
node "$VAULT_PATH/.scripts/semantic-search/scan-vault.cjs"
扫描器返回类似JSON结构：
{
"candidates": [
{
"name": "people",
"path": "05-Areas/People",
"glob": "**/*.md",
"fileCount": 23,
"context": "带会议历史、关系笔记、行动项和角色上下文的人员页面",
"benefit": "人员查找按角色/标题查找引用，而不仅仅是名字",
"example": "搜索‘销售副总裁’即使未提到名字也能找到该人"
},
{
"name": "accounts",
"path": "05-Areas/Companies",
"glob": "**/*.md",
"fileCount": 8,
"context": "带交易状态、关系笔记和交互历史的企业和账户页面",
"benefit": "交易准备提取账户特定上下文，无需收件箱噪音",
"example": "搜索‘续订风险’查找有流失信号的账户"
}
],
"skipped": [
{
"name": "career",
"reason": "文件夹未设置（运行 /career-setup）",
"path": "05-Areas/Career"
}
],
"totalFiles": 156,
"totalCandidates": 6
}
展示发现结果
将扫描器输出格式化为礼宾推荐：
我扫描了您的保管库，发现了[N]个智能集合的候选：
集合 文件数 它启用的功能
─────────────────────────────────────────────────────────────────
people 23 人员查找按角色/标题查找引用，
而不仅仅是名字。搜索“销售副总裁”
即使未提到名字也能找到该人。
meetings 47 “关于X讨论了什么？”搜索
专门查找会议笔记，而不是您的
整个保管库。
tasks 1 智能任务匹配用于分类。捕获
语义重复项，如“审查指标”≈
“检查季度数字”。
projects 8 项目健康提取相关文档
而无需收件箱噪音。
goals 1 目标对齐查找保管库中主题
相关的工作。
priorities 1 每周计划发现过去优先级选择
的模式。
跳过（内容不足）：
- accounts — 未找到企业页面（先创建一些）
- content — 尚无内容文件
- career — 职业文件夹未设置（运行 /career-setup）
创建所有[N]个集合？ [Y]
选择特定集合？ [P]
仅创建基本索引？ [B]
处理用户选择
如果[Y] - 创建所有：
使用上下文，通过qmd collection add创建每个候选集合。
如果[P] - 选择特定： 单独展示每个候选，带Y/N切换。仅创建选定的。
如果[B] - 基本索引： 创建单个“保管库”集合，索引所有内容。这有效，但错过了目标集合的精确性。
创建集合
对于每个接受的候选，运行：
# 创建集合
qmd collection add "$VAULT_PATH/<路径>" --name <名称> --mask "<glob>"
# 添加上下文（帮助重新排序器理解集合内容）
qmd context add <名称> "<上下文描述>"
集合定义（完整列表）：
| 名称 | 路径 | Glob | 上下文 | 最小文件数 |
|---|---|---|---|---|
people |
05-Areas/People |
**/*.md |
带会议历史、关系笔记、行动项和角色上下文的人员页面 | 3 |
accounts |
05-Areas/Companies |
**/*.md |
带交易状态、关系笔记和交互历史的企业和账户页面 | 1 |
accounts （备用） |
05-Areas/Relationships/Key_Accounts |
**/*.md |
带交易状态、MEDDPICC和参与历史的关键账户页面 | 1 |
meetings |
00-Inbox/Meetings |
**/*.md |
带参与者、关键讨论点、决策和行动项的会议笔记 | 5 |
tasks |
03-Tasks |
**/*.md |
带优先级（P0-P3）、支柱对齐、状态跟踪和链接目标的任务积压 | 1 |
projects |
04-Projects |
**/*.md |
带状态、利益相关者、时间线和相关决策的活跃项目跟踪 | 1 |
goals |
01-Quarter_Goals |
**/*.md |
带成功标准、里程碑和进展跟踪的季度战略目标 | 1 |
priorities |
02-Week_Priorities |
**/*.md |
链接到季度目标，带完成跟踪的每周优先级 | 1 |
content |
05-Areas/Content |
**/*.md |
内容想法、文章、LinkedIn帖子和思想领导材料 | 1 |
career |
05-Areas/Career |
**/*.md |
职业发展证据、收到的反馈、技能跟踪和增长目标 | 1 |
prds |
System/PRDs |
**/*.md |
产品需求文档、功能规格和技术设计文档 | 1 |
resources |
06-Resources |
**/*.md |
参考材料、学习、系统文档和指南 | 5 |
所有集合创建后，嵌入向量：
echo "为所有集合创建嵌入..."
qmd embed
向用户展示进度 — 对于较大的保管库，这可能需要几分钟。
第6步：配置MCP服务器
将qmd MCP服务器添加到用户的Claude/Cursor配置。
对于Claude Code（~/.claude.json）：
{
"mcpServers": {
"qmd": {
"type": "stdio",
"command": "qmd",
"args": ["mcp"]
}
}
}
对于Cursor（在保管库根目录的.cursor/mcp.json）：
{
"mcpServers": {
"qmd": {
"command": "qmd",
"args": ["mcp"]
}
}
}
告诉用户：“您需要重新启动编辑器以使MCP服务器可用。重启后，我可以自动使用语义搜索。”
第7步：创建可用性检查
创建.scripts/semantic-search/check-availability.cjs（参见配套文件）。这让其他技能在使用前检查语义搜索是否可用。
第8步：显示成功摘要
═══════════════════════════════════════════════════════════════════════
语义搜索已启用
═══════════════════════════════════════════════════════════════════════
您的保管库现在具有智能、含义感知的搜索。
创建的集合：
[列出每个集合及其文件数]
尝试：
qmd query "产品主导增长策略"
qmd query "客户流失模式" -c accounts
qmd search "与Sarah的会议" -c meetings
现在有何不同：
/daily-plan — 会议上下文通过主题连接丰富
/meeting-prep — 参与者查找按角色/标题引用查找
/triage — 语义路由带目标感知匹配
人员查找 — 查找“销售副总裁”无需名字
搜索与回忆 — 混合检索（BM25 + 向量 + 重新排序）
索引自动更新当您运行：qmd update
随时检查状态： qmd status
强制完全重建： qmd embed -f
随着保管库增长，当有足够内容受益时，我会建议新集合。
随时再次运行此技能检查。
集合健康检查（返回用户）
如果用户已安装qmd且集合存在，此技能切换到健康检查模式。
运行健康检查
node "$VAULT_PATH/.scripts/semantic-search/scan-vault.cjs" --health-check
这将比较现有集合与当前保管库状态，并返回：
{
"existing": ["people", "meetings", "tasks"],
"newCandidates": [
{
"name": "accounts",
"path": "05-Areas/Companies",
"fileCount": 5,
"reason": "您自上次检查后创建了5个企业页面"
}
],
"staleCollections": [
{
"name": "meetings",
"lastUpdated": "12天前",
"currentFiles": 52,
"indexedFiles": 47,
"drift": 5
}
],
"pendingEmbeddings": 8,
"suggestions": [
"运行‘qmd update’重新索引更改的文件",
"运行‘qmd embed’嵌入8个待处理文档"
]
}
展示健康报告
语义搜索健康检查
─────────────────────────────────────────────────────────────────
活跃集合：
people 54文件 2小时前更新 健康
meetings 47文件 12天前更新 ⚠陈旧（5个新文件）
tasks 4文件 1天前更新 健康
新集合候选：
accounts 5文件 您已建立足够的企业页面，
适合专用集合。这意味着交易
准备将专门提取账户上下文。
→ 创建accounts集合？ [Y/n]
维护：
8个文档需要嵌入（运行‘qmd embed’）
meetings集合已陈旧12天（运行‘qmd update’）
快速修复：qmd update && qmd embed
处理新候选
对于每个新候选：
- 解释它启用的功能（使用扫描器中的益处文本）
- 询问是否要创建它
- 如果是，创建集合 + 上下文 + 嵌入
增长建议（由其他技能调用）
其他技能可以在工作流中调用扫描器建议模式：
在/daily-plan期间：
node "$VAULT_PATH/.scripts/semantic-search/scan-vault.cjs" --suggestions-only
如果找到新候选，附加到每日计划：
💡 语义搜索建议：您现在有5个企业页面。
要我创建‘accounts’集合吗？这意味着交易
准备将专门搜索账户上下文。
运行 /enable-semantic-search 设置它。
对于技能作者：使用语义搜索
技能应使用前检查可用性：
// 在您的技能或钩子中
const { execSync } = require('child_process');
function isSemanticSearchAvailable() {
try {
execSync('which qmd', { stdio: 'pipe' });
const status = execSync('qmd status', { stdio: 'pipe' }).toString();
return status.includes('Documents');
} catch {
return false;
}
}
// 在搜索逻辑中使用
if (isSemanticSearchAvailable()) {
// 使用qmd query进行语义搜索
const results = execSync(`qmd query "${query}" -c people`, { stdio: 'pipe' });
} else {
// 回退到grep/文件搜索
}
或使用检查可用性脚本：
const { checkSemanticSearch } = require('.scripts/semantic-search/check-availability.cjs');
const status = checkSemanticSearch();
if (status.available) {
// 使用语义搜索
}
故障排除
如果设置失败：
- Bun安装失败：尝试
npm install -g bun或从bun.sh下载 - SQLite缺失（macOS）：运行
brew install sqlite - 模型下载失败：检查互联网，重试
qmd embed -f - 索引耗时太长：大型保管库（5000+文件）首次可能需要10+分钟
- 集合为空：检查路径是否匹配您的保管库结构 — 运行扫描器验证
- MCP未连接：添加配置后重新启动编辑器
禁用
要移除语义搜索：
# 移除索引
qmd cleanup
# 移除qmd二进制文件
bun remove -g qmd
# 移除MCP配置（手动 — 从配置中删除“qmd”条目）
您的保管库文件从不修改 — 移除qmd只是移除搜索索引。