BIZ-17: QMD和Wiki工具链测试报告与检索指南

- docs/qmd-verification-report.md: QMD功能验证（技能可用，CLI需修复Node.js原生模块兼容性）
- docs/wiki-toolchain-test-report.md: Wiki 5工具完整测试（4通过/1需注意前置条件）
- docs/agent-kb-retrieval-guide.md: Agent知识库检索决策指南（含工具选择/查询构造/缺口上报）
- scripts/wiki-lint-check.sh: Wiki质量自动化检查脚本

Co-authored-by: multica-agent <github@multica.ai>

docs/qmd-verification-report.md

@@ -0,0 +1,112 @@
+# 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 提权重建