Claude Flow V3 agent list 命令完全指南：从 MCP 调用到 Agent 状态机-育师

Claude Flow V3 agent list 命令完全指南：从 MCP 调用到 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 list（别名ls）是 Claude Flow V3 CLI 中用于枚举、过滤当前系统中全部 Agent 实例的核心命令。本文以该命令为入口，完整梳理其用法、参数、表格与 JSON 输出，并深入对应源码揭示其底层实现：list子命令如何通过 MCP 工具agent_list读取.claude-flow/agents/store.json注册表，以及它如何与spawn、status、stop等兄弟命令共同构成 Agent 生命周期管理闭环。读完本文，你将能熟练地在多 Agent 工作流中实时盘点、按类型/状态过滤 Agent，并理解其状态数据的存储与合并原理。

命令概览与两种等价写法

agent list用于列出 Claude Flow 系统中当前活跃的 Agent，支持按类型、状态过滤以及表格/JSON 两种输出格式。由于命令注册了别名ls（见 agent.ts 中aliases: ['ls']），以下两种写法完全等价：

npx @claude-flow/cli@latest agent list [options] npx @claude-flow/cli@latest agent ls [options] # 别名

注：npx @claude-flow/cli@latest是仓库文档中统一使用的调用前缀；在已完成本地安装的项目中，也可直接使用claude-flow agent list（README.md 的 Quick Start 即采用该形式）。

参数详解

Option	Short	Description	Default
`--all`	`-a`	Include inactive/terminated agents	false
`--type`	`-t`	Filter by agent type	All
`--status`	`-s`	Filter by status (active, idle, terminated)	active
`--format`	Output format (table, json)	table

结合源码（agent.ts）可以进一步理解每个参数的语义：

--all/-a：布尔开关，默认false。开启后向 MCP 层传入status: 'all'，等效于不过滤状态，把已终止（terminated）的 Agent 一并展示。
--type/-t：字符串过滤条件，对应 MCP 请求中的agentType字段，只保留指定类型的 Agent（如coder、researcher）。
--status/-s：状态过滤，对应 MCP 请求中的status字段。文档默认值为active，但实现上只有当--all未开启且显式传入--status时才按此过滤（见下文"过滤逻辑"）。
--format：输出格式，table（默认）或json。JSON 模式直接透传 MCP 返回的原始数据结构，便于脚本消费。

常用示例

# 列出所有活跃 Agent npx @claude-flow/cli@latest agent list # 列出全部 Agent（含已终止/非活跃） npx @claude-flow/cli@latest agent list --all # 按类型过滤 npx @claude-flow/cli@latest agent list -t coder # 按状态过滤 npx @claude-flow/cli@latest agent list -s idle # 以 JSON 输出，便于脚本化处理 npx @claude-flow/cli@latest agent list --format json # 组合过滤 npx @claude-flow/cli@latest agent list -t researcher -s active

输出格式解读

表格输出（默认）

Active Agents +--------------------+-----------+--------+----------+---------------+ | ID | Type | Status | Created | Last Activity | +--------------------+-----------+--------+----------+---------------+ | coder-lx7m9k2 | coder | active | 10:30:15 | 10:45:23 | | researcher-abc123 | researcher| idle | 09:15:00 | 10:20:45 | | tester-def456 | tester | active | 11:00:00 | 11:12:30 | +--------------------+-----------+--------+----------+---------------+ Total: 3 agents

该表格的列定义与渲染逻辑对应源码中的printTable调用（agent.ts）：ID（宽 20）、Type（宽 15）、Status（宽 12，使用formatStatus着色）、Created与Last Activity均通过toLocaleTimeString()格式化为本地时间。当结果为空时，会输出提示No agents found matching criteria（agent.ts）而非渲染空表。

JSON 输出

{ "agents": [ { "id": "coder-lx7m9k2", "agentType": "coder", "status": "active", "createdAt": "2026-01-08T10:30:15.000Z", "lastActivityAt": "2026-01-08T10:45:23.000Z" } ], "total": 3 }

注意 JSON 模式返回的是 MCP 层agent_list工具的原始结构（字段名为agentId、agentType、createdAt、lastActivityAt），由 agent.ts 直接printJson(result)输出，未做字段重命名，因此脚本解析时应以 MCP 层的字段名为准。

状态机：三种核心状态

Status	Description
`active`	Agent is currently executing tasks
`idle`	Agent is waiting for tasks
`terminated`	Agent has been stopped

active：Agent 正在执行任务，占用调度资源；
idle：Agent 已就绪、空闲等待任务分配（例如-s idle可用于找出可复用的空闲 Agent）；
terminated：Agent 已被停止、释放资源。默认列表不展示该状态，需要--all才会包含。

源码层面的状态类型在 MCP 响应类型中扩展为'active' | 'busy' | 'idle' | 'terminated'（agent.ts），而status子命令与文档表格仅取active / idle / terminated三类——busy可视为活跃执行中的中间态。

过滤逻辑与默认行为（源码级）

list子命令的过滤语义在 agent.ts 中体现：

const result = await callMCPTool<...>('agent_list', { status: ctx.flags.all ? 'all' : ctx.flags.status || undefined, agentType: ctx.flags.type || undefined, limit: 100, });

开启--all时强制传status: 'all'，--status参数被忽略；
未开启--all且传了--status时按指定状态过滤；
两者都未传时status为undefined，此时 MCP 端默认排除 terminated的 Agent（见下文 MCP 实现），等价于只显示活跃与非活跃中的存活实例。

因此实际默认值可概括为：不传任何过滤参数时，列出所有未终止的 Agent（active + idle）。每次请求最多返回limit: 100条。

底层实现：agent_list MCP 工具与注册表存储

数据存储位置

agent list读取的 Agent 注册表位于项目目录下的.claude-flow/agents/store.json（常量定义见 agent-tools.ts）：

const STORAGE_DIR = '.claude-flow'; const AGENT_DIR = 'agents'; const AGENT_FILE = 'store.json';

loadAgentStore()（agent-tools.ts）读取该 JSON 文件并解析为{ agents: Record<string, AgentRecord>, version }结构；文件不存在或解析失败时返回空 store。

合并 Hive Mind 工作线程

从agent_tools的注释与实现可见，列表视图并非只读单一文件：loadAllAgents()（agent-tools.ts）将.claude-flow/agents/store.json与 Hive Mind 工作线程注册表.claude-flow/agents.json合并：

function loadAllAgents(): Record<string, AgentRecord> { return { ...loadHiveAgents(), ...loadAgentStore().agents }; }

当两个来源出现 ID 冲突时，规范注册表（canonical store）中的记录优先，因为它携带了模型路由与 lastResult 等信息。这意味着agent list的"全部 Agent"视图同时涵盖常规 spawn 与 Hive Mind 产生的 worker（见 agent-tools.ts 的注释#1916: includes hive-mind-spawned workers）。

MCP 层过滤与校验

agent_list工具本体（agent-tools.ts）接收status、domain、includeTerminated三个入参，执行以下逻辑：

对status与domain调用validateIdentifier做输入校验，非法输入直接返回{ agents: [], total: 0, error: ... }；
合并两份注册表得到全量 Agent；
显式传入status时精确匹配该状态；否则默认排除terminated（除非includeTerminated: true）——这正是文档中"默认只看活跃"行为的实现来源；
支持额外的domain维度过滤（文档参数表中未列出，属于源码能力）；
返回每个 Agent 的agentId / agentType / status / health / taskCount / createdAt / domain字段，以及total与回显的filters。

与兄弟命令协同：Agent 生命周期闭环

agent list位于 .claude/commands/agents 命令族中，与以下命令构成完整的管理闭环：

命令	职责	对应 MCP 工具
spawn	创建新 Agent（`-t`指定类型，默认生成`类型-时间戳`命名）	`agent_spawn`
list	枚举、过滤全部 Agent（本文主题）	`agent_list`
status	查看单个 Agent 详情与任务指标	`agent_status`
stop	优雅/强制停止 Agent（别名`kill`）	`agent_terminate`
metrics	聚合性能指标与内存向量统计	本地读取`.swarm/`状态
health	健康检查（CPU/内存/延迟/p99）	`agent_health`
logs	查看 Agent 活动日志	`agent_logs`
pool	预热 Agent 池与自动伸缩	`agent_pool`

典型排查流程：用agent list盘点当前活跃 Agent 与类型分布 → 用agent status <id>深入单个 Agent 的指标（tasksCompleted、uptime 等）→ 用agent stop <id>释放资源。spawn与stop还会通过updateSwarmActivityMetrics()（agent.ts）同步更新.claude-flow/metrics/swarm-activity.json中的agent_count，供状态栏实时展示 Agent 数量——这也是list中"活跃 Agent"数量的写入源头之一。

测试覆盖：命令注册与参数路由

agent list的测试用例位于 commands.test.ts，验证了：

子命令list已正确注册在agentCommand.subcommands下；
无参数调用返回success: true，且结果包含agents数组与total字段；
--type coder、--status active、--all三种过滤路径均能正常执行。

这些用例因依赖实时 MCP 上下文而被it.skip跳过（注释标明// Skip: requires live MCP context），但spawn等不依赖外部上下文的用例会真实执行，可运行npx vitest run __tests__/commands.test.ts在本地验证命令框架层面的行为。

Agent 类型分类速查

--type过滤可配合 agent-types.md 中收录的全部 87 种 Agent 类型使用，核心分类如下：

Core：coder、reviewer、tester、planner、researcher
V3：security-architect、memory-specialist、performance-engineer
Swarm：hierarchical-coordinator、mesh-coordinator、adaptive-coordinator
Consensus：byzantine-coordinator、raft-manager、gossip-coordinator
GitHub：pr-manager、code-review-swarm、release-manager
SPARC：sparc-coordinator、specification、architecture

在 CLI 交互模式下，spawn的-t参数还会提供带描述的交互选择列表（AGENT_TYPES常量，见 agent.ts）。由于list与spawn共用同一套 Agent 类型标识，你可以先用agent spawn -t <type>按需创建、再用agent list -t <type>校验其是否成功注册。

小结

agent list虽只是 CLI 的一个子命令，却串联起 Claude Flow V3 的 Agent 注册表（.claude-flow/agents/store.json）、MCP 工具层（agent_list）与展示层（表格/JSON）三层架构。理解其默认过滤语义（排除 terminated）、--all的覆盖规则、JSON 输出的原始字段命名，以及 Hive Mind 注册表合并机制，能帮助你在多 Agent 编排场景下准确地盘点资源、定位问题，并为后续status/stop/metrics等运维操作提供可靠的输入。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考