Back to Details

secondbrain-search-init

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Initialize Semantic Search

初始化语义搜索

Set up qmd semantic search for an existing secondbrain project.
为现有的secondbrain项目设置qmd语义搜索。

Prerequisites

前提条件

  1. Secondbrain project exists: Check for 
    .claude/data/config.yaml
  2. qmd installed: Check with 
    which qmd
  1. 已存在secondbrain项目：检查是否存在
    .claude/data/config.yaml
    文件
  2. 已安装qmd：使用
    which qmd
    命令检查

Workflow

工作流程

Step 1: Validate Environment

步骤1：验证环境

bash
undefined
bash
undefined

Check secondbrain exists

检查secondbrain是否存在

ls .claude/data/config.yaml
ls .claude/data/config.yaml

Check qmd installation

检查qmd安装情况

which qmd

If secondbrain not found:
No secondbrain project found in current directory. Run 
/secondbrain-init
to create a new project first.

If qmd not installed:
which qmd

如果未找到secondbrain：
当前目录下未找到secondbrain项目。 请先运行
/secondbrain-init
创建新项目。

如果未安装qmd：

qmd Not Installed

qmd未安装

qmd is required for semantic search. Install it:
语义搜索需要依赖qmd。请按照以下方式安装：

Using Bun (Recommended)

使用Bun（推荐）

bun install -g qmd
bun install -g qmd

Using npm

使用npm

npm install -g qmd
After installation, run this skill again.
Note: First run will download ~1.5GB of embedding models.
undefined
npm install -g qmd
安装完成后，请重新运行此技能。
注意：首次运行会下载约1.5GB的嵌入模型。
undefined

Step 2: Check Existing Search

步骤2：检查现有搜索设置

bash
ls .claude/search/ 2>/dev/null
If search already initialized:
undefined
bash
ls .claude/search/ 2>/dev/null
如果搜索已初始化：
undefined

Search Already Initialized

搜索已初始化

Search is already configured for this project.
Index location: .claude/search/ Last indexed: 2026-01-15 10:30
当前项目已配置搜索功能。
索引位置：.claude/search/ 最后索引时间：2026-01-15 10:30

Options

可选操作

  1. Rebuild index — Re-index all documents 
    /secondbrain-search-init --rebuild
  2. Search now — Start searching 
    /secondbrain-search "your query"
  3. Check status — View index statistics 
    qmd status
undefined
  1. 重建索引 — 重新索引所有文档 
    /secondbrain-search-init --rebuild
  2. 立即搜索 — 开始搜索 
    /secondbrain-search "your query"
  3. 检查状态 — 查看索引统计信息 
    qmd status
undefined

Step 3: Create Search Configuration

步骤3：创建搜索配置

Create 
.claude/search/
directory and qmd config:
bash
mkdir -p .claude/search
Generate 
qmd.config.json
in project root:
json
{
  "name": "{{project_name}}-secondbrain",
  "paths": ["docs"],
  "ignore": [
    "**/node_modules/**",
    "**/.vitepress/cache/**",
    "**/.vitepress/dist/**",
    "**/TEMPLATE.md"
  ],
  "indexDir": ".claude/search",
  "chunk": {
    "size": 800,
    "overlap": 0.15
  },
  "metadata": {
    "extractFrontmatter": true,
    "includeFileMetadata": true
  }
}
创建
.claude/search/
目录和qmd配置文件：
bash
mkdir -p .claude/search
在项目根目录生成
qmd.config.json
：
json
{
  "name": "{{project_name}}-secondbrain",
  "paths": ["docs"],
  "ignore": [
    "**/node_modules/**",
    "**/.vitepress/cache/**",
    "**/.vitepress/dist/**",
    "**/TEMPLATE.md"
  ],
  "indexDir": ".claude/search",
  "chunk": {
    "size": 800,
    "overlap": 0.15
  },
  "metadata": {
    "extractFrontmatter": true,
    "includeFileMetadata": true
  }
}

Step 4: Update .gitignore

步骤4：更新.gitignore

Add search index to 
.gitignore
(index should not be committed):
undefined
将搜索索引添加到
.gitignore
（索引文件不应提交）：
undefined

Semantic search index (regenerate with /secondbrain-search-init)

语义搜索索引（可通过/secondbrain-search-init重新生成）

.claude/search/ qmd.config.json
undefined
.claude/search/ qmd.config.json
undefined

Step 5: Build Initial Index

步骤5：构建初始索引

Run initial indexing:
bash
qmd index
Show progress:
undefined
运行初始索引构建：
bash
qmd index
进度展示：
undefined

Building Search Index

正在构建搜索索引

Scanning docs/... Found 47 documents
Indexing: [████████████████████░░░░░░░░░░] 35/47 documents
Downloading models (first run only):
  • embedding-gemma-300M... done
  • qwen3-reranker... done
Building embeddings: [██████████████████████████████] 47/47 documents
Index built successfully!
  • Documents: 47
  • Chunks: 312
  • Index size: 2.4 MB
  • Location: .claude/search/
undefined
扫描docs/目录... 找到47份文档
索引中： [████████████████████░░░░░░░░░░] 35/47 份文档
下载模型（仅首次运行）：
  • embedding-gemma-300M... 完成
  • qwen3-reranker... 完成
构建嵌入向量： [██████████████████████████████] 47/47 份文档
索引构建成功！
  • 文档数量：47
  • 分片数量：312
  • 索引大小：2.4 MB
  • 存储位置：.claude/search/
undefined

Step 6: Register Hook (Optional)

步骤6：注册钩子（可选）

Ask user if they want automatic index updates:
undefined
询问用户是否需要自动更新索引：
undefined

Automatic Index Updates

自动索引更新

Would you like to automatically update the search index when documents are modified?
[x] Yes, add PostToolUse hook (Recommended) - Updates index incrementally on file changes - Adds ~0.5s to Write/Edit operations
[ ] No, I'll rebuild manually - Run 
qmd index
or 
/secondbrain-search-init --rebuild

If yes, add hook to `.claude/settings.local.json`:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"${CLAUDE_PROJECT_DIR}/.claude/hooks/search-index-update.py\"",
            "timeout": 30000
          }
        ]
      }
    ]
  }
}
Copy hook script:
bash
cp "${CLAUDE_PLUGIN_ROOT}/hooks/search-index-update.py" .claude/hooks/
当文档被修改时，是否需要自动更新搜索索引？
[x] 是，添加PostToolUse钩子（推荐） - 文件变更时增量更新索引 - 会为写入/编辑操作增加约0.5秒耗时
[ ] 否，我将手动重建 - 运行
qmd index
或
/secondbrain-search-init --rebuild

如果用户选择是，将钩子添加到`.claude/settings.local.json`：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"${CLAUDE_PROJECT_DIR}/.claude/hooks/search-index-update.py\"",
            "timeout": 30000
          }
        ]
      }
    ]
  }
}
复制钩子脚本：
bash
cp "${CLAUDE_PLUGIN_ROOT}/hooks/search-index-update.py" .claude/hooks/

Step 7: Show Summary

步骤7：显示总结

undefined
undefined

Search Initialized Successfully!

搜索初始化成功！

Project: my-knowledge-base Documents indexed: 47 Index location: .claude/search/
项目名称：my-knowledge-base 已索引文档数量：47 索引存储位置：.claude/search/

Quick Start

快速开始

Search your knowledge base: /secondbrain-search "kubernetes deployment strategies"
Search with filters: /secondbrain-search --entity=adrs "database" /secondbrain-search --recent=30d "authentication"
搜索你的知识库： /secondbrain-search "kubernetes deployment strategies"
带过滤条件的搜索： /secondbrain-search --entity=adrs "database" /secondbrain-search --recent=30d "authentication"

Index Management

索引管理

Rebuild index: qmd index --rebuild
Check status: qmd status
View recent searches: qmd history
重建索引： qmd index --rebuild
检查状态： qmd status
查看最近搜索记录： qmd history

Automatic Updates

自动更新

Index updates: Enabled (PostToolUse hook) Documents in docs/ will be re-indexed on save.
undefined
索引更新：已启用（PostToolUse钩子） docs/目录中的文档在保存时会自动重新索引。
undefined

Options

可选参数

--rebuild

--rebuild

Force rebuild of entire index:
bash
qmd index --rebuild
强制重建整个索引：
bash
qmd index --rebuild

--no-hook

--no-hook

Skip adding the automatic update hook:
/secondbrain-search-init --no-hook
跳过添加自动更新钩子：
/secondbrain-search-init --no-hook

Troubleshooting

故障排除

Models Download Stuck

模型下载卡住

If model download hangs:
bash
undefined
如果模型下载停滞：
bash
undefined

Clear cache and retry

清除缓存并重试

rm -rf ~/.cache/qmd/models/ qmd index
undefined
rm -rf ~/.cache/qmd/models/ qmd index
undefined

Index Corruption

索引损坏

If search returns errors:
bash
undefined
如果搜索返回错误：
bash
undefined

Remove and rebuild

删除现有索引并重建

rm -rf .claude/search/ qmd index
undefined
rm -rf .claude/search/ qmd index
undefined

Slow Indexing

索引速度慢

For large document sets (>500 docs):
  • Initial indexing may take several minutes
  • Consider using 
    --batch-size=50
    for progress visibility
对于大型文档集（>500份文档）：
  • 初始索引可能需要几分钟
  • 建议使用
    --batch-size=50
    参数以查看进度

Related Skills

相关技能

  • secondbrain-search — Search your knowledge base
  • secondbrain-init — Create new secondbrain project
  • secondbrain-search — 搜索你的知识库
  • secondbrain-init — 创建新的secondbrain项目