EnterpriseArchitect/docs/qmd-verification-report.md

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 安装检查

$ which qmd
/usr/bin/qmd

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

---

2. CLI 运行状态

问题发现

$ 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 提权重建