附录 D：常见问题
本附录列出 OpenMatrix 的常见问题及解答。
D.1 安装问题
Q: npm install openmatrix 失败？
A: 检查以下几点：
- Node.js 版本 >= 18.0.0
- npm 版本 >= 9.0.0
- 网络连接正常
# 检查版本
node --version
npm --version
# 清除缓存后重试
npm cache clean --force
npm install openmatrix
Q: Skills 安装失败？
A: 确保 ~/.claude/commands/ 目录存在：
mkdir -p ~/.claude/commands/om
openmatrix install-skills --force
D.2 使用问题
Q: /om:start 没有反应？
A: 检查以下几点：
- Skills 是否正确安装
- 当前目录是否正确
- 查看错误日志
# 验证 Skills 安装
ls ~/.claude/commands/om/
# 查看帮助
openmatrix --help
Q: 任务一直处于 pending 状态？
A: 可能原因：
- 依赖任务未完成
- 调度器问题
# 查看状态
/om:status --detailed
# 手动调度
openmatrix step --json
Q: Context 压缩后状态丢失？
A: 使用 resume 恢复：
/om:resume
D.3 质量门禁问题
Q: Coverage 检查失败？
A: 常见原因和解决方案：
| 原因 | 解决方案 |
|---|---|
| 测试不足 | 添加更多测试用例 |
| 排除配置错误 | 检查 coverage.exclude 配置 |
| 阈值过高 | 降低 minCoverage 配置 |
Q: Lint 检查失败？
A: 常见原因：
# 查看 lint 错误
npm run lint
# 自动修复
npm run lint -- --fix
Q: Security 扫描发现漏洞？
A: 处理步骤：
# 查看漏洞详情
npm audit
# 自动修复
npm audit fix
# 强制修复（可能 breaking changes）
npm audit fix --force
D.4 Meeting 问题
Q: 如何减少 Meeting 数量？
A: 提供更详细的任务指令：
# 不好的指令
做一个用户系统
# 好的指令
实现用户认证系统：
- 使用 JWT token
- bcrypt 加密密码
- 支持 remember me
Q: Meeting 无法解决？
A: 检查问题类型：
| 类型 | 解决方案 |
|---|---|
| information | 提供详细信息 |
| decision | 选择一个方案 |
| approval | 确认批准 |
| dependency | 解决外部依赖 |
D.5 性能问题
Q: 执行速度慢？
A: 优化建议：
- 使用 fast 模式原型开发
- 拆分大任务为小任务
- 减少 E2E 测试
# 使用 fast 模式
/om:start --quality fast
Q: 磁盘空间不足？
A: 清理旧数据：
# 查看存储大小
du -sh .openmatrix/
# 清理旧执行记录
rm -rf .openmatrix/tasks/TASK-*
D.6 集成问题
Q: CI/CD 中如何使用？
A: 使用 full-auto 模式：
- name: Run OpenMatrix
run: openmatrix auto --quality strict --bypass-approvals
Q: 与现有测试框架冲突？
A: 配置忽略：
{
"gates": {
"test": {
"framework": "vitest",
"config": "vitest.config.ts"
}
}
}
D.7 调试问题
Q: 如何查看详细日志？
A: 查看日志文件：
# 执行日志
cat .openmatrix/logs/execution.log
# 错误日志
cat .openmatrix/logs/errors.log
# Agent 上下文
cat .openmatrix/context.md
Q: 如何重置状态？
A: 删除状态目录：
# 警告：这将清除所有状态
rm -rf .openmatrix/
# 重新开始
/om:start
D.8 其他问题
Q: 支持哪些测试框架？
A: 支持：
- Vitest
- Jest
- Mocha
- 其他（自定义配置）
Q: 支持哪些 Lint 工具？
A: 支持：
- ESLint
- Biome
- Standard
- 其他（自定义配置）
Q: 如何贡献代码？
A: 步骤：
- Fork 项目
- 创建特性分支
- 提交 PR
- 等待 Code Review
Q: 如何报告 Bug？
A: 提交 Issue：
- 描述问题
- 复现步骤
- 期望行为
- 实际行为
- 环境信息