文档创建

人工智能 社区

技能解读

当前原文的自动摘译,尚未人工审校。

何时使用

“搜索我的笔记/文档/知识库”“查找相关笔记”“查找匹配[模式]的文件”——使用而不是find以避免在大目录上挂起“我们对X做了什么决定?”

默认行为(重要)

更喜欢qmd search(BM25)——它是即时的,应该是默认的。仅当关键字搜索失败并且需要语义相似性时才使用qmd vsearch。避免使用qmd query,除非用户明确想要最高质量的混合结果并且可以容忍较长的运行时间。从代理调用时,始终使用 --json 标志进行结构化输出。

搜索模式选择

模式 · 速度 · 质量 · 最适合 search · 快 · 好 · 精确的关键字、已知术语 vsearch · 中等 · 更好 · 概念性查询、同义词 query · 慢 · 最好 · 复杂问题、不确定术语

搜索选项

选项 · 描述 -n NUM · 结果数量(默认:5、20,带 --json) -c, --collection · 范围到特定集合 --min-score NUM · 最低分数阈值 --full · 返回完整的文档内容

输出格式

--files — 路径 + 分数(用于文件发现) --json — 由片段构成 --md — 降价格式 -n 10 — 限制结果

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
人工智能
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@diegosouzapw · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
macOS · Linux · Windows
运行环境要求
Bun
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 读取环境变量
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# qmd - Local Markdown Search

Local search engine for Markdown notes, docs, and knowledge bases. Index once, search fast. Use instead of `find` for file discovery across large directories.

## Installation

```bash
bun install -g https://github.com/tobi/qmd
```

## Setup

```bash
# Add a collection
qmd collection add /path/to/your/notes --name notes --mask "**/*.md"

# Generate embeddings (required for vsearch/query)
qmd embed

# List your collections
qmd collection list
```

## When to Use

- "search my notes / docs / knowledge base"
- "find related notes"
- "find files matching [pattern]" — use instead of `find` to avoid hangs on large directories
- "what did we decide about X?"

## Default Behavior (important)

- Prefer `qmd search` (BM25) — it's instant and should be the default.
- Use `qmd vsearch` only when keyword search fails and you need semantic similarity.
- Avoid `qmd query` unless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes.
- **Always use `--json` flag** for structured output when invoking from an agent.

## Search Commands

```bash
# Fast keyword search (default)
qmd search "authentication flow" --json
qmd search "config" --json -c notes

# Semantic search (slower, for conceptual queries)
qmd vsearch "how does login work" --json
qmd vsearch "best practices for error handling" --json -n 20

# Combined with reranking (best quality, slowest)
qmd query "implementing user auth" --json
qmd query "deployment process" --json --min-score 0.5
```

### Search Mode Selection

| Mode | Speed | Quality | Best For |
|------|-------|---------|----------|
| `search` | Fast | Good | Exact keywords, known terms |
| `vsearch` | Medium | Better | Conceptual queries, synonyms |
| `query` | Slow | Best | Complex questions, uncertain terms |

### Search Options

| Option | Description |
|--------|-------------|
| `-n NUM` | Number of results (default: 5, 20 with --json) |
| `-c, --collection` | Scope to specific collection |
| `--min-score NUM` | Minimum score threshold |
| `--full` | Return complete document content |
| `--json` | Structured JSON output (agent-friendly) |
| `--files` | File paths only (fast discovery) |
| `--all` | Return all matches |

## Retrieve Documents

```bash
# Get full file
qmd get docs/guide.md --json

# Get by document hash ID
qmd get "#a1b2c3" --json

# Get specific lines
qmd get notes/meeting.md:50 -l 30 --json

# Get multiple files by glob
qmd multi-get "docs/*.md" --json
qmd multi-get "*.yaml" -l 50 --max-bytes 10240
```

## Output Formats

- `--files` — paths + scores (for file discovery)
- `--json` — structured with snippets
- `--md` — markdown formatted
- `-n 10` — limit results

## Maintenance

```bash
qmd update              # Re-index changed files
qmd status              # Check index health
qmd collection list     # List all collections
```

## Keeping Index Fresh

```bash
# Hourly incremental updates (BM25):
0 * * * * export PATH="$HOME/.bun/bin:$PATH" && qmd update

# Optional: nightly embedding refresh:
0 5 * * * export PATH="$HOME/.bun/bin:$PATH" && qmd embed
```

## MCP Server

qmd can run as an MCP server for direct agent integration:

```bash
qmd mcp
```

Exposes tools: `qmd_search`, `qmd_vsearch`, `qmd_query`, `qmd_get`, `qmd_multi_get`, `qmd_status`

## Performance

- `qmd search` is typically instant.
- `qmd vsearch` can take ~1 minute on first run (loads local LLM).
- `qmd query` adds LLM reranking — can be slow, avoid for interactive use.

## Models (auto-downloaded)

All run locally — no API keys needed.

- Embedding: embeddinggemma-300M
- Reranking: qwen3-reranker-0.6b
- Generation: Qwen3-0.6B
- Cache location: `~/.cache/qmd/models/`
- Override with `XDG_CACHE_HOME` environment variable.

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。