Ruflo 系统健康诊断与状态监控实战:ruflo-status 命令、doctor 检查项与 MCP/Swarm 运行态解读

原创2026-09-09 17:44:441,726 阅读
文章标签:人工智能大模型AI AgentAgent 编排多智能体工具调用MCP 服务Agent 记忆Agent 工作流代码智能体AI 技能CLI插件系统浏览器控制提示词注入防护向量数据库模型评测

Ruflo 系统健康诊断与状态监控实战:ruflo-status 命令、doctor 检查项与 MCP/Swarm 运行态解读

ruflo-status 是 ruflo-core 基础插件提供的一条系统诊断命令,用于展示 Ruflo 运行健康度、MCP Server 状态与活跃 Agent 情况。它并非一条独立的魔法命令,而是对 @claude-flow/cli 的 doctor 与 status 两条 CLI 命令的有序封装:doctor 负责体检、status 负责展示运行态。读完本文,你将掌握 Ruflo 标准诊断工作流的正确姿势——何时用只读检查、何时才该显式授权 doctor --fix,并能读懂 doctor 的 28 项健康检查与 status 的 Swarm / Agents / Tasks / Memory / MCP 五个状态区块,必要时还可以深入源码按组件定位问题。

ruflo-status 是什么:命令契约与技能双通道

在仓库中,ruflo-status 以两种形态存在,且行为高度一致:

  • Claude 命令:plugins/ruflo-core/commands/ruflo-status.md 定义了名为 ruflo-status 的斜杠命令,frontmatter 中明确其用途为 "Show Ruflo system health, MCP server status, and active agents"(展示 Ruflo 系统健康、MCP 服务器状态与活跃 Agent);
  • Codex 技能:plugins/ruflo-core/skills/ruflo-status/SKILL.md 提供同名的 Bash 技能,允许工具 Bash(npx *),并额外给出了完整的只读工作流与显式修复工作流说明。

这条命令的契约由 plugins/ruflo-core/scripts/smoke.sh 的第 9 步固化:只要命令文件同时包含 doctor 与 status 两个关键字即视为通过(grep -q "doctor" && grep -q "status")。也就是说,ruflo-status = doctor(诊断)+ status(状态)的固定组合是受冒烟测试保护的结构性约定。

默认只读诊断工作流:先体检、再展示

命令主体只有两行,按顺序执行:

npx @claude-flow/cli@latest doctor
npx @claude-flow/cli@latest status

第一条 doctor 运行系统诊断与健康检查(下文详述),第二条 status 展示当前系统状态。技能文档 SKILL.md 对此有明确约束:

默认工作流中,将诊断与状态合并汇总,但不得修复、重置、启动、停止、安装或以任何方式改动安装。仅当用户明确要求修复时,才允许切换到修复工作流。

这是一个刻意设计的"只读"边界:ruflo-status 的默认行为是纯观测,任何变更都必须由用户显式触发,绝不从"检查/诊断"的请求中推断修复授权。

显式修复工作流:doctor --fix 的授权边界

仅当用户明确要求修复(fix / auto-repair)时,将第一条命令替换为:

npx @claude-flow/cli@latest doctor --fix
npx @claude-flow/cli@latest status

即:修复动作收敛到 doctor --fix,随后照常执行 status 汇报修复后的结果。技能文档要求 Agent 汇报"修复改了什么 + 修复后的状态",并且绝不允许从一次普通的检查/诊断请求中推断出对 doctor --fix 的授权。

一个值得注意的细节是:--fix 的实际语义在源码中写得非常克制。查看 v3/@claude-flow/cli/src/commands/doctor.ts 中 fix 选项的描述:

Print suggested fix commands (does not auto-apply — copy/paste them yourself)

--fix 并不会自动应用修复,它只是把每条 warn/fail 检查项对应的修复命令打印出来(源码 doctor.ts 中输出区以 "Suggested commands (run them yourself)" 为标题列出),由用户自行复制执行。真正的自动安装行为属于独立的 --install 标志(仅自动安装缺失的 Claude Code CLI,见 installClaudeCode)。明确这一点,可以避免误以为 --fix 会"一键修好一切"。

唯一的例外是 Learning Bridge 检查:当 --fix / --install 存在且该检查失败时,doctor 会自动写入 .claude-flow/memory-package.json sidecar 记录内存包解析路径(见 doctor.ts 中的自愈逻辑,对应 issue #2599)。

doctor 深度解析:28 项并行健康检查

doctor 命令定义于 v3/@claude-flow/cli/src/commands/doctor.ts,其 allChecks 数组(doctor.ts)按序注册了 28 项检查,全部通过 Promise.allSettled 并行执行以换取 3~5 倍的速度提升(见 doctor.ts)。每一项检查返回统一的 HealthCheck 结构:{ name, status: 'pass'|'warn'|'fail', message, fix? },汇总后按 ✓ / ⚠ / ✗ 三态渲染,并统计 passed / warnings / failed 三栏摘要。

检查项 检查内容 关键阈值 / 判定
Version Freshness 对比本地版本与 npm 上 @claude-flow/cli@alpha 最新版,识别 npx 缓存陈旧 陈旧则 warn,提示清 npx 缓存
Node.js Version 检查 Node 大版本 < 18 fail;18~19 warn;≥ 20 pass
npm Version 检查 npm 版本 ≥ 9 pass,否则 warn
Claude Code CLI claude --version 未安装 warn
Git git --version 未安装 warn
Git Repository git rev-parse + .git 目录向上回退探测 非仓库 warn
Config File 同时收集旧 JSON 与新版 YAML 配置,检测"配置冲突" JSON 语法错 fail;JSON+YAML 并存 warn(issue #1798)
Stale npx@latest in settings 扫描 .claude/settings.json 中残留的 npx @claude-flow/cli@latest 逃逸命令 命中即 CRITICAL fail(issue #2448/#2677)
Daemon Status 读 .claude-flow/daemon.pid 做信号 0 存活探测 陈旧 PID warn
Memory Database Presence 探测多个候选路径下 memory.db 的存在与体积 未初始化 warn
Memory Structural Integrity 用 better-sqlite3 跑 PRAGMA quick_check(默认每次运行都执行) 打开失败/quick_check 异常 fail(#2737)
Memory Persistence Driver 区分原生 better-sqlite3(WAL 持久)与 sql.js WASM 回退(非持久) 原生表约 47 张、sql.js 约 10 张,低于阈值 warn(#2968)
Learning Bridge 校验 .claude/helpers/auto-memory-hook.mjs 能否按 SessionStart 方式解析 @claude-flow/memory 解析失败 fail(#2545)
API Keys 探测 ANTHROPIC_API_KEY / CLAUDE_API_KEY / OPENAI_API_KEY 或 Claude Code 托管环境 缺失 warn
MCP Servers 扫描 4 处 MCP 配置,识别 ruflo 系列注册与重复/遗留注册 重复注册 warn,并给出规范 key 修复命令(#2206/#2612)
MCP Schema Overhead 估算 tools/list 的固定提示开销占上下文窗口比例 高开销 warn(#2726)
AIDefence 动态 import('@claude-flow/aidefence') 验证 aidefence_* MCP 工具可用 不可加载 warn(#1807)
Disk Space df -Ph 解析可用空间与使用率 > 90% fail;> 80% warn
TypeScript npx tsc --version 未本地安装 warn
agentic-flow 探测可选依赖 agentic-flow 及其 exports 能力 未安装 warn
Encryption at Rest ADR-096:加密开关、密钥解析、指纹、RFE1 魔数探测 门开启但密钥缺失 fail(fail-closed)
Federation Breaker ADR-097:探测 federation 插件与 breaker 实体层 未安装视为"未配置 pass"(可选)
MetaHarness ×3 ADR-150:上游包、声明的 optionalDependencies、ruflo 侧集成层完整性 声明的可选依赖缺失 fail
Funnel ADR-305:报告启停状态与裁决来源(env>enterprise>user>default) 信息性,通常 pass
Meta LLM Proxy ×2 ADR-313/ADR-307:赞助停机健康、二进制校验(sha256 对照 manifest)、进程存活、绑定地址 非 loopback 绑定 warn
Auth ADR-306:Cognitum 身份 profile 与 scope→consent 收据一致性 scope 无收据 fail(fail-closed)

从源码结构看,这些检查遵循几条明确的设计原则(见 doctor.ts 的注释):

  • "A check that cannot fail protects nothing"——每项检查都有可演示的红色状态;
  • "UNKNOWN is never PASS"——检查无法运行时报告 warn/fail,绝不给出令人安心的 pass;
  • "Print the measurement, not a checkmark"——消息中包含实测比值(如 embedded 3/11133 (0.03%)),让运维人员直接看到问题形态;
  • fail-closed——加密门开启而密钥缺失、scope 授予而无 consent 收据这类安全不变量直接判 fail 而非 warn。

按组件定向检查:--component

如果不想跑完整 28 项,可用 -c / --component 只查指定组件。完整取值清单见 doctor.ts 的 componentMap:

npx @claude-flow/cli@latest doctor -c version          # 仅查 npx 缓存陈旧
npx @claude-flow/cli@latest doctor -c claude           # 仅查 Claude Code CLI
npx @claude-flow/cli@latest doctor -c memory           # 运行整套内存健康套件
npx @claude-flow/cli@latest doctor -c mcp              # 仅查 MCP 注册
npx @claude-flow/cli@latest doctor -c mcp-overhead     # 仅查 MCP schema 提示开销
npx @claude-flow/cli@latest doctor -c proxy            # ADR-307 代理深挖套件
npx @claude-flow/cli@latest doctor -c metaharness      # MetaHarness 上游+依赖+集成三连
npx @claude-flow/cli@latest doctor -c encryption       # ADR-096 静态加密
npx @claude-flow/cli@latest doctor -c federation       # ADR-097 联邦 breaker
npx @claude-flow/cli@latest doctor -c auth             # ADR-306 Cognitum 身份
npx @claude-flow/cli@latest doctor -c funnel           # ADR-305 漏斗状态

注意 -c memory 并非常规的单项检查,而是一个 7 项检查的深挖套件(doctor.ts):

  1. checkMemoryDatabase——存在性与体积(仅 stat);
  2. checkMemoryIntegrity——sql.js / better-sqlite3 打开 + PRAGMA integrity_check;
  3. checkMemoryPersistenceDriver——原生 vs WASM 回退;
  4. checkMemoryContent——memory_entries 非空内容占比,95% 下限,低于即 fail;
  5. checkMemoryEmbeddingCoverage——有内容的行携带向量占比,同样 95% 下限(无向量的行既不可召回也不可蒸馏,对应 ADR-174);
  6. checkMemoryReflexionCoverage——episodes 与 episode_embeddings 的 INNER JOIN 可召回性;
  7. checkMemoryCritiqueCoverage——执行层反馈 episode 是否携带真实 critique/lesson。

这组套件针对的是真实线上事故:存在性检查曾对"99.97% 为空"甚至 SQLite 损坏的库报告 PASS。因此新套件要求"第一个红色永远是用户最先看到的那条链路中断",顺序即优先级。

其他 doctor 标志

  • --fix / -f:打印建议的修复命令(不自动应用);
  • --install / -i:自动安装缺失依赖(Claude Code CLI);
  • --verbose / -v:详细输出;
  • --fix-handles:Windows 专属,清理 Claude Code 会话泄漏的孤儿 conhost.exe(对应 anthropics/claude-code#67888 的缓解方案),单独运行、不参与健康检查流程。

status 深度解析:五区块运行态总览

status 命令定义于 v3/@claude-flow/cli/src/commands/status.ts,其数据并非凭空生成,而是通过 MCP 客户端串行调用多个运行时工具汇聚而成(getSystemStatus):

展示区块 底层 MCP 工具调用 关键字段
Swarm swarm_status (includeMetrics: true) swarmId、topology、health、uptime
Agents swarm_status 返回的 agents 计数 total / active / idle
Tasks task_summary pending / running / completed / failed / total
Memory memory_stats entries、size、backend、avgSearchTime、cacheHitRate
MCP Server mcp_status running、port、transport(stdio 或端口)

displayStatus(status.ts)渲染时以 [RUNNING] / [STOPPED] 总开关为头部,随后依次输出 Swarm、Agents、Tasks、Memory、MCP 五个表格,并在运行态下追加 V3 性能项(CPU / 内存占用)。MCP 调用失败时整体降级为 stopped 态数据,不会崩溃。

运行前置条件:初始化判定

status 执行前会先做初始化判定(isInitialized),命中以下任一信号即视为已初始化:

  • .claude-flow/config.yaml(ruflo init 的标准产物)
  • .claude-flow/config.json(同义格式)
  • .swarm/memory.db(ruflo memory init 的产物)
  • .claude/settings.json(Claude Code hook 表面)

未初始化则输出 RuFlo is not initialized in this directory 并提示先运行 ruflo init,退出码 1。这一宽松判定的背景是 issue #2120:旧逻辑只认 config.yaml,导致仅通过 ruflo memory init 初始化(只写 .swarm/memory.db)的合法项目被误报为未初始化。

status 子命令与标志

npx @claude-flow/cli@latest status                     # 展示完整状态
npx @claude-flow/cli@latest status --watch             # 看板模式,持续刷新(默认 2s)
npx @claude-flow/cli@latest status --watch -i 5        # 每 5 秒刷新
npx @claude-flow/cli@latest status --health-check      # 只跑健康检查并退出
npx @claude-flow/cli@latest status --json              # JSON 输出(便于脚本消费)
npx @claude-flow/cli@latest status agents              # 详细 Agent 状态
npx @claude-flow/cli@latest status tasks               # 详细任务状态
npx @claude-flow/cli@latest status memory              # 详细内存状态
  • agents 子命令(status.ts):调用 agent_list(includeMetrics + status: all),渲染 ID / Type / Status / Current Task / Uptime / Success 表格;
  • tasks 子命令(status.ts):调用 task_list(limit 50),渲染任务类型、状态、优先级、负责 Agent 与进度百分比;
  • memory 子命令(status.ts):调用 memory_detailed-stats,额外展示命名空间条目数、HNSW 索引开关、平均写入时间与 V3 性能增益说明。

--health-check 的判定阈值

performHealthCheck(status.ts)将运行态转化为 6 项 pass/warn/fail 判定,阈值如下:

  • System Running:未运行即 fail;
  • Swarm Health:healthy→pass,degraded→warn,其余→fail;
  • Agents Available:active > 0→pass;active = 0 但 idle > 0→warn;否则 fail;
  • MCP Server:运行中→pass,否则 warn;
  • Memory Backend:backend 非 none→pass,否则 fail;
  • Task Success Rate:失败率 < 5%→pass;< 20%→warn;否则 fail。

典型排障路径:把两条命令串成一次诊断

结合 doctor 与 status 的分工,一次标准的 Ruflo 体检可以这样串起来:

  1. 只读体检:npx @claude-flow/cli@latest doctor——先看 28 项检查的三态摘要,重点看是否有 ✗(fail)与 ⚠(warn);
  2. 定位子系统:若内存相关红/黄灯,跑 doctor -c memory 深挖 7 项套件,按"先看最早的链路断裂"原则从上往下读;若 MCP 异常,跑 doctor -c mcp 检查 ~/.claude.json / .mcp.json 中的注册与重复项;
  3. 查看运行态:npx @claude-flow/cli@latest status 确认 Swarm 拓扑、Agent 活跃数、任务队列、内存后端与 MCP 传输模式;需要持续观察时加 --watch;
  4. 需要脚本化:status --json 导出结构化数据;
  5. 显式修复:仅在确认要动手时,doctor --fix 查看建议命令(自行复制执行),或对缺失的 Claude Code CLI 用 doctor --install。

验证与契约:冒烟测试如何守护这条命令

ruflo-core 以"冒烟测试即契约"著称(见 plugins/ruflo-core/README.md)。运行:

bash plugins/ruflo-core/scripts/smoke.sh
# Expected: "10 passed, 0 failed"

其中第 9 步专门守护 ruflo-status 命令的 doctor + status 组合契约,第 4 步守护 ruflo-status 技能具备 name / description / allowed-tools 三要素 frontmatter,第 10 步则禁止技能使用通配符工具授权(allowed-tools: *),保证 ruflo-status 这类命令只能通过 Bash(npx *) 白名单路径执行。插件级的架构决策完整记录于 ADR-0001 — ruflo-core plugin contract。

小结

ruflo-status 用两条命令完成了"体检 + 状态"的组合观测:doctor 以 28 项并行检查覆盖 Node/npm/Claude Code/Git/配置/守护进程/内存/MCP/AIDefence/磁盘/静态加密/联邦/MetaHarness/代理/身份等维度,并支持 --component 定向深挖与 --fix 建议式修复;status 则通过 swarm_status、mcp_status、memory_stats、task_summary 等 MCP 工具汇聚 Swarm、Agents、Tasks、Memory、MCP 五区块运行态,并提供 --watch 看板与 agents / tasks / memory 三个详情子命令。理解这两条命令的边界——默认只读、修复必须显式授权、--fix 只打印建议不自动应用——是安全运维 Ruflo 安装的第一步。

登录后查看全文
ruflo