vincent
dc00661a34
- 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>
112 lines
3.3 KiB
Markdown
112 lines
3.3 KiB
Markdown
# 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 提权重建 |