Question 1

如何修复 ruflo 或 Claude Flow CLI 的 --version 命令在首次运行时挂起 60 秒以上并以退出码 143 退出的问题？

Accepted Answer

升级到 v3.10.33 或更高版本,在该版本中 `--version`/`-V` 会在加载 ONNX 嵌入模型之前退出:

```bash
npx -y ruflo@3.10.33 --version
npx -y @claude-flow/cli@3.10.33 --version
```

该挂起问题发生在冷缓存状态下,因为 CLI 初始化时会先从 HuggingFace 下载 23 MB 的 `all-MiniLM-L6-v2` ONNX 模型,然后才打印版本号。在 v3.10.33 中,`ruflo` 和 `@claude-flow/cli` 都会直接从 `package.json` 读取版本号并立即退出,将启动时间从超过 60 秒缩短至约 33 ms。

如果必须使用较旧的版本,可以使用更长的超时时间预热一次模型缓存:

```bash
timeout 180 npx -y ruflo@alpha --version
```

下载完成后,后续调用将使用磁盘缓存并快速启动。更广泛的 lazy-loading/cli-core 拆分工作仍在 ADR-100/#1760 下跟踪。

Question 2

如何修复 verify.mjs 因报错 "Cannot find module '@noble/ed25519'" 而失败并跳过见证验证的问题？

Accepted Answer

在运行验证之前，先安装声明的 npm 依赖。从仓库根目录运行：

```bash
npm ci && npm run build
```

然后再次调用验证器，例如：

```bash
node plugins/ruflo-core/scripts/witness/verify.mjs --manifest verification/linux/manifest.md.json
```

对于本地非干净的检出（checkout），从仓库根目录运行 `npm install` 也可以安装缺失的 `@noble/ed25519` 依赖。将 `npm ci && npm run build` 添加到仅源码验证运行器的预检（pre-flight）步骤中。当输出显示 Ed25519 检查被跳过时，不要将退出码 0 视为成功；成功的验证必须打印签名验证结果以及 pass/drift/regressed/missing 计数。

Question 3

如何修复 memory_search_unified 只搜索六个默认命名空间并遗漏记忆条目的问题？

Accepted Answer

升级到 ruflo 3.10.33 或更高版本（npm install -g ruflo@3.10.33）。在 ruflo 3.10.13 / @claude-flow/cli 3.10.22 等受影响版本中，memory_search_unified 在未指定命名空间过滤器时使用了硬编码的六个命名空间列表，因此 knowledge-graph、causal-edges、brain-system 等命名空间或自定义命名空间中的条目会被静默遗漏。该修复默认改用动态命名空间枚举，并新增了：namespaces: string[]、CSV 环境变量 CLAUDE_FLOW_MEMORY_SEARCH_NAMESPACES，以及响应中的 namespaceSource。解析优先级为：显式 namespace → 显式 namespaces → 环境变量覆盖 → 动态枚举 → 旧版回退。在旧版本上，请显式传入目标命名空间，例如 memory_search_unified({ query: "needle", namespace: "brain-system" })，或者直接升级。不要依赖对 dist/ 目录下内容的修改；npm 升级会将其覆盖。

Question 4

如何修复 Ruflo MCP 服务器因非 JSON stdout 日志或 initialize 超时导致在 Codex 中无法加载的问题？

Accepted Answer

将 Ruflo 升级到 **v3.10.33 或更高版本**，该版本会将第三方嵌入/模型加载的进度日志从 `stdout` 重定向到 `stderr`，使 `stdout` 专用于 MCP JSON-RPC 帧。

更新你的 Codex MCP 配置，将版本固定为已修复的版本：

```toml
[mcp_servers.ruflo]
command = "npx"
args = ["-y", "ruflo@3.10.33", "mcp", "start"]
enabled = true
```

然后重启 Codex 或 MCP 服务器。v3.10.30 中受影响的日志包括：

```text
Disk cache hit: all-MiniLM-L6-v2
🚀 Initializing 19 worker threads...
Loading model: all-MiniLM-L6-v2 (23MB)
  Downloading: ...
```

这些日志会导致 Codex 等严格的 MCP 客户端无法解析 `initialize` 响应，因此 `mcp__ruflo...` 工具不会出现。仅增大启动超时时间无法修复旧版本，因为 `stdout` 流已经被非 JSON 文本污染。升级后，仅当首次模型下载/初始化运行仍然缓慢时，才需要增大客户端超时时间。

Question 5

为什么 ruflo-console 将成功的安全威胁检测报告为失败，并显示 '[WARN] Skipped helper auto-refresh' 而不是真正的错误信息？

Accepted Answer

将 `ruflo-console` 升级到 **0.40.5 或更高版本**；修复位于 PR #3934（合并提交 `767f7a689`）中。0.40.3 版本错误地将所有非零 CLI 退出码都视为失败。判定（verdict）命令使用非零退出码来表示检测结果——例如，`security defend`/`security scan` 在发现威胁时以退出码 1 退出，`channel-scan`/`scan-plan` 在门禁触发时以退出码 2 退出，而 metaharness 告警脚本在出现告警时以退出码 1 退出、在实际失败时以退出码 2 退出。修复后的运行器会解析完整的 JSON 响应，当 JSON 确认存在检测结果且未另行报告失败时，会将声明的非零退出码接受为有效的判定结果。它还使用共享的 `failureReason` 辅助函数，该函数会选取实际的 `[ERROR]` 行，而不是 stderr 的第一行（后者可能只是 `[WARN]` 提示）。升级后请重启 console/MCP 服务。如果暂时无法升级，请直接检查并解析命令的 stdout JSON，并在 stderr 中搜索 `[ERROR]`，而不要依赖 console 的 `ok:false` 状态或 stderr 的第一行。

ruflo

项目简介

README 预览

常见问题 (5)

同类型项目

tensorflow

superpowers

everything-claude-code

flutter