RuView 仓库 Claude Flow Swarm 监控命令实战指南：从 swarm-monitor 到 agent-metrics 的实时观测体系

本文面向在 RuView 仓库中使用 Claude Code + Claude Flow（Claude 多终端编排平台）的开发者，系统讲解 .claude/commands/monitoring/ 目录下定义的监控命令族——swarm-monitor、agent-metrics、real-time-view 的完整用法、选项语义与真实示例，并结合仓库内落地实现的 swarm-monitor.sh、metrics-db.mjs、health-monitor.sh 等脚本，把“命令文档”还原为可运行的观测链路。读完你将掌握：如何以秒级/毫秒级间隔持续观察 swarm 活动、如何按 Agent 维度拉取性能指标、如何以流式视图实时过滤与高亮事件，以及这些数据最终沉淀到哪些 JSON / SQLite 指标文件中。

一、监控命令在仓库中的定位与前置条件

.claude/commands/monitoring/README.md 是一份面向 Claude Code 的“监控命令索引”，它把监控类操作收敛为三个可被 Claude 直接引用的命令文件：

命令	对应文档	职责
swarm-monitor	swarm-monitor.md	实时 swarm 监控
agent-metrics	agent-metrics.md	查看 Agent 性能指标
real-time-view	real-time-view.md	swarm 活动实时视图

同目录下的 agents.md（列出活跃模式 / Agent）与 status.md（检查协调状态）可视为同一能力的“状态快照”补充。

在 RuView 仓库中，这三份命令描述的是 Claude Flow 的 CLI / MCP 双通道观测方式：

• CLI 通道：通过 npx claude-flow 或初始化后生成的 ./claude-flow 可执行脚本运行。完整命令集见 claude-flow-help.md（如 ./claude-flow status、./claude-flow monitor、./claude-flow agent list/info、./claude-flow swarm ... --monitor）。
• MCP 通道：在 Claude Code 中直接调用 mcp__claude-flow__* 工具，例如 agent_list、agent_metrics、swarm_monitor、swarm_status、health_check（见 agents.md 与 status.md）。文档特别强调该层“只做协调与结构，不写代码、不直接访问文件、不执行命令”，真正的实现仍由 Claude Code 完成。

运行前提：仓库根目录存在 Claude Flow V3 运行时目录 .claude-flow/（含 config.yaml），其中声明了 swarm 拓扑 hierarchical-mesh、最大 Agent 数 maxAgents: 15、协调策略 coordinationStrategy: consensus，以及记忆与指标后端等参数——这些就是监控数据所描述的对象。

二、swarm-monitor：实时 swarm 活动监控

命令文档定义在 swarm-monitor.md，CLI 形式为：

npx claude-flow swarm monitor [options]

2.1 选项语义

选项	类型/示例	作用
--interval <ms>	如 5000	刷新（更新）间隔，单位毫秒
--metrics	布尔开关	展示详细指标
--export	布尔开关	导出监控数据

2.2 文档示例

# 启动监控
npx claude-flow swarm monitor

# 自定义间隔：每 5000ms 刷新一次
npx claude-flow swarm monitor --interval 5000

# 附带详细指标
npx claude-flow swarm monitor --metrics

--interval 与 status.md 中 MCP 用法 mcp__claude-flow__swarm_monitor 的参数 {"interval": 1000}（毫秒级）语义一致，说明该间隔参数在 CLI 与 MCP 两条通道间保持贯通。

2.3 仓库中的真实实现：swarm-monitor.sh

命令文档背后，仓库给出了更贴近操作系统层的落地实现 swarm-monitor.sh。该脚本支持四种子命令，可视为对 CLI 抽象的具体化：

# 单次活动检测并写入指标
.claude/helpers/swarm-monitor.sh check

# 每 N 秒连续监控（默认 5 秒，等价于文档 --interval 的“秒级”形态）
.claude/helpers/swarm-monitor.sh monitor 3

# 打印当前活动状态
.claude/helpers/swarm-monitor.sh status

其核心检测逻辑说明了“swarm 活动”在仓库里究竟被如何量化：

• 统计进程：通过 ps aux 过滤 agentic-flow 进程、mcp.*start（MCP server 进程）以及 (agent|swarm|coordinator) 关键词进程，并排除自身与 grep 进程干扰；
• 估算 Agent 数：当检测到 agentic-flow 进程但无精确 agent 计数时，采用启发式 agentic_flow_count / 2（至少为 1）进行估算；
• 写指标文件：状态变化时向 .claude-flow/metrics/swarm-activity.json 写入 processes.{agentic_flow,mcp_server,estimated_agents}、swarm.{active,agent_count,coordination_active}、integration.* 等结构化字段；
• 分级日志：脚本内置 log/warn/error/success 四个带颜色的日志函数，仅在状态发生变更时输出，避免无意义刷屏——这与文档中“持续监控 + Ctrl+C 退出”的交互模型保持一致。

仓库中已有的一帧真实数据（swarm-activity.json）表明该文件结构包含 timestamp、processes、swarm、integration、_initialized 字段，是校验 --export 输出格式与后续分析的上手样例。

三、agent-metrics：查看 Agent 性能指标

定义见 agent-metrics.md，CLI 形式：

npx claude-flow agent metrics [options]

3.1 选项语义

选项	类型/示例	作用
--agent-id <id>	如 agent-001	指定具体 Agent（不传则覆盖全部）
--period <time>	如 1h	时间窗口
--format <type>	如 json	输出格式

3.2 文档示例

# 全部 Agent 的指标
npx claude-flow agent metrics

# 指定 Agent
npx claude-flow agent metrics --agent-id agent-001

# 最近一小时
npx claude-flow agent metrics --period 1h

与之对应的 MCP 通道是 mcp__claude-flow__agent_metrics，其参数 {"agentId": "coder-123"}（见 agents.md）表明：Agent 标识既可以是 agent-001 这类通用编号，也可以是 coder-123 这类按角色命名的实例。--format 选项用于切换输出序列化形态，便于直接对接脚本或下游 JSON 消费方。

3.3 指标的数据底座：metrics-db.mjs 与 daemon-state

仓库将 Agent/任务的运行指标持久化在 SQLite 与 JSON 两个层面：

• metrics-db.mjs 基于 sql.js 维护单文件数据库 .claude-flow/metrics.db，建表即含 v3_progress、swarm_activity、performance_metrics、module_status、cve_status、security_audit 六张表，其中 swarm_activity 表的列 agentic_flow_processes / mcp_server_processes / estimated_agents / swarm_active / coordination_active 与 swarm-monitor.sh 的检测口径一一对应；
• 它提供四种运行模式：sync（扫描代码并同步全部指标）、export（导出 JSON）、status（打印当前指标）、daemon [interval]（按秒周期持续同步），后三者尤其适合 agent metrics --period 这类时间窗口查询的后台数据源；
• daemon-state.json 记录了 8 个后台 worker（map、audit、optimize、consolidate、testgaps、predict、document 等）的运行计数、成功/失败数、平均耗时（averageDurationMs）与下次运行时间——这些才是“Agent 性能指标”在仓库中的可观测事实来源。例如其中 map worker 记录了 64 次运行 64 次成功、平均耗时约 136ms，audit worker 则记录了 72 次运行 45 次失败、平均耗时约 26s，可直接支撑 --agent-id + --period 维度的排查。

四、real-time-view：swarm 活动的实时视图

定义见 real-time-view.md，CLI 形式：

npx claude-flow monitoring real-time-view [options]

注意：该命令的子命令层级与另外两个不同，位于 monitoring 命名空间下。

4.1 选项语义

选项	类型/示例	作用
--filter <type>	如 errors	过滤视图事件类型
--highlight <pattern>	如 "API"	高亮匹配指定模式的事件
--tail <n>	如 50	只显示最近 N 条事件

4.2 文档示例

# 启动实时视图
npx claude-flow monitoring real-time-view

# 只过滤错误事件
npx claude-flow monitoring real-time-view --filter errors

# 高亮包含 "API" 的事件
npx claude-flow monitoring real-time-view --highlight "API"

4.3 与“健康监控”侧写的关系

实时视图本质上消费的是持续落盘的活动事件流。仓库侧对应的“持续采集者”是 health-monitor.sh，它每 5 分钟（节流）采集一次以下系统级健康指标并写入 .claude-flow/metrics/health.json：

• 磁盘：对项目根目录执行 df -h，读取使用率百分比与剩余空间；
• 内存：读取 free -m，计算已用百分比；
• 进程：统计 node 进程数与 agentic-flow 进程数；
• CPU 负载：读取 /proc/loadavg 的一分钟均值；
• 健康判定：磁盘/内存使用 >80% 判为 warning、>90% 判为 critical，健康时返回退出码 0，否则非 0。

该脚本支持 run（强制执行）、check（节流检查）、force（重置节流强制运行）、status（从 health.json 打印一行摘要）四个子命令。这些系统指标与 swarm 活动指标共同构成了 real-time-view --filter / --highlight 背后的事件类型来源：既有 errors 这类由健康告警派生的异常事件，也有以 agentic-flow、mcp、swarm、coordinator 为关键词的活动事件（口径见 swarm-monitor.sh 的进程匹配逻辑）。

五、把三条命令串成一条可落地的观测工作流

结合 config.yaml（hooks.autoExecute: true、mcp.autoStart: false、mcp.port: 3000）与上述实现，推荐在 Claude Code 会话中按以下顺序组合使用：

1. 先看全局状态：执行 swarm-status / mcp__claude-flow__swarm_status，确认 coordination_active 与整体健康度（对应 status.md 中的拓扑、认知模式、任务分解与资源占用）；
2. 拉起持续观测：运行 swarm monitor --interval 5000 --metrics 保持 5 秒粒度的 swarm 活动刷新，或将后台采集交给 swarm-monitor.sh monitor 3 / health-monitor.sh；
3. 按 Agent 下钻：发现异常后，用 agent metrics --agent-id agent-001 --period 1h --format json 定位具体 Agent 在时间窗口内的表现，必要时查阅 daemon-state.json 中对应 worker 的成功/失败计数与平均耗时；
4. 流式收敛证据：用 monitoring real-time-view --filter errors --highlight "agentic" --tail 50 只看最近 50 条错误并高亮关键模式；
5. 导出留档：对需要归档的观测结论执行带 --export 的监控命令，或直接调用 metrics-db.mjs export，将指标从 SQLite 导出为 swarm-activity.json 等 JSON 文件供后续对比。

六、使用要点与事实边界

• 命令文档（swarm-monitor.md、agent-metrics.md、real-time-view.md）描述的是 Claude Flow 的标准 CLI 抽象；仓库内能直接运行的是 .claude/helpers/ 下的实现脚本，二者在“间隔”“Agent 维度”“事件流”等概念上口径一致。
• --interval 的文档单位为毫秒（如 5000），而 helper 脚本 swarm-monitor.sh 的 monitor [N] 参数单位为秒（默认 5），使用前请留意单位换算。
• Agent 计数在无精确来源时使用启发式估算（见 swarm-monitor.sh 的 /2 逻辑），因此 agent metrics 输出中的估算类字段在只有 agentic-flow 进程而无精确计数时应谨慎解读。
• daemon-state.json 中记录的 logDir/stateFile 指向 wifi-densepose 项目路径，属历史运行环境痕迹，不代表当前仓库布局；真正可复现的路径均以 .claude-flow/ 目录下实际文件为准。
• 需要了解监控之外的系统管理、Agent 管理、记忆操作与 SPARC 工作流时，可返回入口文档 claude-flow-help.md 按需查询。