ruflo agent status 命令实战指南深入解析 Agent 状态查询与指标解读【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo导读agent status是 ruflo 项目Claude Flow V3 命令行体系中用于查看单个 Agent 全量运行状态的核心命令。它通过 MCP 工具agent_status读取 Agent 注册表的生命周期快照一次调用即可获得 Agent 类型、运行状态、创建时间、最近活跃时间、任务完成/失败/进行中数量、平均执行时长与总运行时长uptime等关键信息。读完本文你将掌握agent status的完整用法、JSON 结构化输出、底层数据来源与调用链以及如何与agent list、agent metrics、agent health等兄弟命令组合成一套可落地的 Agent 巡检流程。命令概览一条命令读懂 Agent 全貌在 ruflo 的 Claude Flow V3 体系中Agent 是承载长期任务、跨轮次状态与 swarm 协作调度的核心实体。与一次性的 Task 工具调用不同Agent 拥有跨对话轮次累积的生命周期状态状态、任务计数、最近结果、健康分因此需要专门的状态查询入口。agent status正是为此设计文档定义见 status.md其声明信息如下name: statusdescription: Show detailed status of an agenttype: command支持的两种调用方式# 方式一位置参数传入 Agent ID npx claude-flow/clilatest agent status agent-id # 方式二使用 --id 标志显式指定 npx claude-flow/clilatest agent status --id agent-id命令选项选项说明默认值--idAgent ID可作为位置参数的替代必填--format输出格式table/jsontable典型使用示例# 按 ID 查询状态 npx claude-flow/clilatest agent status coder-lx7m9k2 # 使用 --id 标志 npx claude-flow/clilatest agent status --id researcher-abc123 # JSON 结构化输出 npx claude-flow/clilatest agent status coder-lx7m9k2 --format json从源码看命令执行链路命令的落地实现位于 v3/claude-flow/cli/src/commands/agent.ts 的statusCommand定义中。其执行流程可以概括为五个关键步骤参数解析优先取位置参数ctx.args[0]其次取--id标志若两者皆缺且处于交互模式会弹出Enter agent ID:输入提示并要求非空校验源码第 316-323 行。缺失校验若最终仍未获得 Agent ID打印Agent ID is required错误并以exitCode: 1退出。调用 MCP 工具通过callMCPTool(agent_status, { agentId, includeMetrics: true, includeHistory: false })发起底层查询。格式化输出--format json时直接output.printJson(status)默认table模式下用printBox绘制 Agent 信息卡片、用printTable渲染指标表格。错误处理区分MCPClientError与未知异常分别输出Failed to get agent status: ...与Unexpected error: ...。值得注意的细节avgExecTime与uptime在表格输出前会经过格式化——平均执行时间保留两位小数并附加ms单位uptime 则从毫秒换算为分钟(uptime / 1000 / 60).toFixed(1)这正是文档示例中245.5ms与15.3m两个数值的来源。状态颜色语义表格输出中的状态字段并非纯文本而是经过 formatStatus 着色active/running→ 绿色output.successidle→ 黄色output.warningsuspended→ 灰色output.dimterminated/failed→ 红色output.error这让运维人员在终端里可以一眼定位异常 Agent。表格输出Agent 信息卡片与指标面板当未指定--format json时命令输出分为上下两部分基本信息卡片与 Metrics 指标表。基本信息卡片-------------------------------------------------- | Agent: coder-lx7m9k2 | -------------------------------------------------- | Type: coder | | Status: active | | Created: 1/8/2026, 10:30:15 AM | | Last Activity: 1/8/2026, 10:45:23 AM | --------------------------------------------------对应源码中printBox渲染的四行内容源码第 358-366 行Agent 类型、当前状态、创建时间、最近活跃时间。其中Last Activity字段在无数据时显示N/A。指标面板Metrics ----------------------------------- | Metric | Value | ----------------------------------- | Tasks Completed | 12 | | Tasks In Progress | 1 | | Tasks Failed | 0 | | Avg Execution Time | 245.5ms | | Uptime | 15.3m | -----------------------------------表格列宽固定Metric 列 25 字符、Value 列 15 字符右对齐五个指标依次来自metrics.tasksCompleted、metrics.tasksInProgress、metrics.tasksFailed、metrics.averageExecutionTime、metrics.uptime缺失字段按 0 兜底。输出字段详解基础信息Basic InfoAgent IDAgent 在注册表中的唯一标识例如coder-lx7m9k2跨轮次稳定供成本追踪与 swarm 拓扑引用。Agent 类型如coder、researcher、architect等决定默认模型映射见下文模型路由。当前状态active/idle/terminated源码类型定义还包含busy、running、suspended等状态位见agent list的过滤逻辑。创建时间戳Agent 注册到 store 的时刻。最近活跃时间戳最后一次任务执行的时间无记录时为N/A。性能指标Performance MetricsTasks Completed成功完成的任务数反映 Agent 的历史产出量。Tasks In Progress正在执行中的任务数。Tasks Failed失败任务计数是判断 Agent 是否需要介入的首要信号。Average Execution Time平均执行时长毫秒用于评估任务效率基线。Total Uptime总运行时长表格模式以分钟展示JSON 模式以毫秒展示。配置信息Configuration视情况出现当 Agent 携带配置时状态查询可返回Provider 与 model如anthropicclaude-3-5-sonnet-20241022Timeout 设置示例中为300单位为秒Auto-tools 是否启用autoTools: true自定义能力集Custom capabilitiesJSON 输出面向自动化的结构化数据指定--format json后命令直接透传 MCP 工具返回的原始结构便于脚本解析与下游告警系统消费{ id: coder-lx7m9k2, agentType: coder, status: active, createdAt: 2026-01-08T10:30:15.000Z, lastActivityAt: 2026-01-08T10:45:23.000Z, config: { provider: anthropic, model: claude-3-5-sonnet-20241022, timeout: 300, autoTools: true }, metrics: { tasksCompleted: 12, tasksInProgress: 1, tasksFailed: 0, averageExecutionTime: 245.5, uptime: 918000 } }注意 JSON 模式下字段为原始命名camelCase且agentType而非Typeuptime单位为毫秒918000毫秒 918 秒 15.3 分钟与表格模式的显示换算完全对应这是两套输出格式相互验证的绝佳切入点。底层实现agent_status MCP 工具与 Agent 注册表agent status命令本身是一个薄封装真正的状态读取发生在 MCP 工具agent_status中其实现位于 v3/claude-flow/cli/src/mcp-tools/agent-tools.ts。工具语义工具描述明确说明了适用场景读取单个被追踪 Agent 的生命周期状态idle/running/stopped、当前 taskCount、lastResult、model、health score。当原生 Task 工具不适用时使用——因为你需要的是 Agent 级状态跨轮次状态、累积 taskCount、最近错误、swarm 协调而非一次性响应。请先配合 agent_list 找到 agentId。这意味着agent status与一次性的 Task 工具形成互补Task 适合跑一次拿结果agent status适合看一个长期运行 Agent 的健康全貌。调用流程入参校验validateIdentifier(input.agentId, agentId)校验 ID 合法性失败返回not_found与错误信息。数据加载调用loadAllAgents()[agentId]读取合并后的 Agent 注册表。命中返回输出agentId、agentType、status、health、taskCount、createdAt、domain、lastResult等字段。未命中返回{ agentId, status: not_found, error: Agent not found }。数据来源合并的双注册表loadAllAgents()agent-tools.ts返回的是规范 Agent store 与 hive-mind 派生 worker 的合并视图主 storeloadAgentStore()从项目存储目录读取agents.json路径由getAgentDir()与AGENT_FILE拼接文件损坏时回退为空 store{ agents: {}, version: 3.0.0 }。Hive-mind 派生 worker#1916 起hive-mind 生成的 worker 记录在.claude-flow/agents.jsongetHiveAgentPath()为 best-effort 读取失败静默返回空对象。冲突策略ID 冲突时主 store 记录优先因为其携带 hive store 缺失的 model-routing 与 lastResult 字段。也就是说你在 swarm / hive-mind 场景下 spawn 出的工作 Agent同样可以通过agent status查询到状态前提是它写入了上述任一注册表。模型路由对Type字段的影响Agent 类型并非随意字符串它与模型路由强绑定。源码中维护了AGENT_TYPE_MODEL_DEFAULTS映射agent-tools.ts复杂型 Agent →opusarchitect、security-architect、system-architect、core-architect中型 Agent →sonnetcoder、reviewer、researcher、tester、analyst轻量 Agent →haikuformatter、linter、documenter状态输出中的Type: coder与config.model字段正是这套路由的可见体现。模型决策优先级determineAgentModel显式 config 指定 → 增强任务路由ADR-026 三层路由需真实 embedding依赖共享 MiniLM 管道→ 类型默认值 → 兜底sonnet。与相关命令的组合使用agent status通常不是孤立使用的文档给出的相关命令构成了完整的 Agent 运维闭环命令用途与 status 的配合npx claude-flow/clilatest agent list查找 Agent ID先 list 拿 ID再 status 看细节npx claude-flow/clilatest agent metrics聚合指标status 看单 Agentmetrics 看全局趋势npx claude-flow/clilatest agent health健康检查status 看静态状态health 看 0-1 健康分npx claude-flow/clilatest agent logs id活动日志status 定位异常后用 logs 追溯根因从源码看agent list支持按status、domain过滤并默认排除terminatedAgent见 agent-tools.ts非常适合先筛出可疑状态再逐一下钻agent status。而agent health关联的滚动健康分由任务成功率 响应延迟 p50/p95 错误率综合计算可以配合status的tasksFailed字段交叉验证 Agent 是否处于劣化前兆。典型巡检流程示例# 1. 列出所有非终止 Agent找到需要关注的 ID npx claude-flow/clilatest agent list --status active # 2. 深挖单个 Agent 的详细状态表格模式 npx claude-flow/clilatest agent status coder-lx7m9k2 # 3. 输出结构化 JSON 交给脚本/告警系统 npx claude-flow/clilatest agent status coder-lx7m9k2 --format json # 4. 确认失败任务是否伴随健康分下降 npx claude-flow/clilatest agent health --id coder-lx7m9k2 # 5. 回溯失败根因 npx claude-flow/clilatest agent logs coder-lx7m9k2该组合既覆盖了是什么状态status也覆盖了表现如何metrics/health与为什么logs可用于 daily 巡检与故障定位。适用前提与限制ID 必须存在于注册表agent status只读取已被追踪写入 agent store 或 hive store的 Agent一次性 Task 调用产生的临时任务不在其列返回Agent not found。指标为累积值tasksCompleted等指标是 Agent 生命周期内的累计值非时间窗口切片需要时间维度分析时使用agent metrics --period。配置字段视情况返回config仅当 Agent 携带配置时出现JSON 输出中可能缺省。命令名需要agent前缀完整命令为npx claude-flow/clilatest agent status根命令下的claude-flow status是不同的全局状态命令见 src/commands/status.ts不要混淆。扩展阅读Agent 命令总览spawn / list / stop / metrics / pool / health / logs 全部命令索引agent list 命令批量发现 Agent 与状态过滤agent health 命令滚动健康分解读Agent 类型文档全部可用 Agent 类型清单MCP 工具实现agent_status/agent_list/agent_pool/agent_health等底层实现【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考