# QMD 功能验证报告

> **任务**: BIZ-17 (BIZ-14-2)  
> **测试人**: 严维序 (opengineer)  
> **测试日期**: 2026-06-22  
> **版本**: v1.0

---

## 1. 技能安装状态

### 技能文件检查

| 检查项 | 路径 | 状态 |
|--------|------|------|
| SKILL.md | `~/.agents/skills/qmd/SKILL.md` | ✅ 存在 |
| references/ | `~/.agents/skills/qmd/references/` | ✅ 存在 |
| 版本 | SKILL.md 元数据 | `2.0.0` |

### CLI 安装检查

```bash
$ which qmd
/usr/bin/qmd
```

✅ QMD CLI 已全局安装（npm global）。

---

## 2. CLI 运行状态

### 问题发现

```bash
$ qmd status
Error: The module 'better_sqlite3.node'
was compiled against a different Node.js version using
NODE_MODULE_VERSION 127. This version of Node.js requires
NODE_MODULE_VERSION 137.
```

### 根因分析

| 项目 | 说明 |
|------|------|
| 当前 Node.js | v24.16.0 (NODE_MODULE_VERSION 137) |
| better-sqlite3 编译版本 | NODE_MODULE_VERSION 127 (Node.js v22.x) |
| 影响 | QMD 所有命令不可用（search/query/get/status） |
| 修复方案 | `sudo npm rebuild -g @tobilu/qmd` 或 `sudo npx node-gyp rebuild` 在 better-sqlite3 目录 |

### 修复尝试记录

| 尝试 | 命令 | 结果 |
|------|------|------|
| 1 | `npm rebuild -g @tobilu/qmd` | ❌ 超时被 SIGTERM |
| 2 | `npx node-gyp rebuild` (better-sqlite3 目录) | ❌ 权限不足 (EACCES: rmdir 'build') |
| 3 (推荐) | `sudo npm rebuild -g @tobilu/qmd` | ⏳ 待执行（需提权） |

---

## 3. QMD 功能能力（基于 SKILL.md 文档）

### 支持的搜索类型

| 类型 | 方法 | 输入示例 |
|------|------|----------|
| `lex` | BM25 关键词 | `"connection pool" -deprecated` |
| `vec` | 向量语义 | `"how does the rate limiter handle burst traffic"` |
| `hyde` | 假设文档 | 50-100 字的假设答案文本 |
| `expand` | 自动扩展 | 单行问题，由本地 LLM 生成多类型查询 |

### CLI 命令参考（待验证）

| 命令 | 用途 |
|------|------|
| `qmd status` | 集合与健康状态 |
| `qmd query "问题"` | 自动扩展 + 重排序 |
| `qmd query --json --explain "问题"` | 带评分追踪的结构化输出 |
| `qmd search "关键词"` | BM25 纯关键词搜索 |
| `qmd get "#docid"` | 按文档 ID 获取 |
| `qmd multi-get "glob/**/*.md"` | 批量获取 |
| `qmd collection add <dir> --name <name>` | 添加集合 |
| `qmd embed` | 生成嵌入向量 |

### MCP 工具（Agent 侧可用）

| 工具 | 用途 |
|------|------|
| `qmd.query` | 结构化搜索（支持 lex/vec/hyde） |
| `qmd.get` | 按路径或 #docid 获取文档 |
| `qmd.multi_get` | 按 glob/列表批量获取 |
| `qmd.status` | 集合和健康状态 |

---

## 4. 建议

1. **立即修复**: 在全局 npm 目录执行 `sudo npm rebuild -g @tobilu/qmd`
2. **集合配置**: 修复后执行 `qmd collection add ~/notes --name notes && qmd embed`
3. **知识库集成**: 将 `EnterpriseArchitect/knowledge/` 目录注册为 QMD 集合
4. **定期维护**: 知识库更新后重新执行 `qmd embed`

---

## 5. 结论

- **技能文件**: ✅ 完整可用（SKILL.md + references）
- **CLI 运行**: ❌ 需修复 Node.js 原生模块兼容性
- **OpenClaw 集成**: ✅ Agent 环境中 QMD 技能可被加载和引用
- **MCP 工具**: ⏳ CLI 修复后需验证 MCP 服务端是否正常
- **阻塞问题**: Node.js v24 与 better-sqlite3 v12.8.0 编译版本不兼容，需 sudo 提权重建