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/clilatest agent list [options] npx claude-flow/clilatest agent ls [options] # 别名注npx claude-flow/clilatest是仓库文档中统一使用的调用前缀在已完成本地安装的项目中也可直接使用claude-flow agent listREADME.md 的 Quick Start 即采用该形式。参数详解OptionShortDescriptionDefault--all-aInclude inactive/terminated agentsfalse--type-tFilter by agent typeAll--status-sFilter by status (active, idle, terminated)active--formatOutput 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/clilatest agent list # 列出全部 Agent含已终止/非活跃 npx claude-flow/clilatest agent list --all # 按类型过滤 npx claude-flow/clilatest agent list -t coder # 按状态过滤 npx claude-flow/clilatest agent list -s idle # 以 JSON 输出便于脚本化处理 npx claude-flow/clilatest agent list --format json # 组合过滤 npx claude-flow/clilatest 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.tsID宽 20、Type宽 15、Status宽 12使用formatStatus着色、Created与Last Activity均通过toLocaleTimeString()格式化为本地时间。当结果为空时会输出提示No agents found matching criteriaagent.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 层的字段名为准。状态机三种核心状态StatusDescriptionactiveAgent is currently executing tasksidleAgent is waiting for tasksterminatedAgent has been stoppedactiveAgent 正在执行任务占用调度资源idleAgent 已就绪、空闲等待任务分配例如-s idle可用于找出可复用的空闲 AgentterminatedAgent 已被停止、释放资源。默认列表不展示该状态需要--all才会包含。源码层面的状态类型在 MCP 响应类型中扩展为active | busy | idle | terminatedagent.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 实现等价于只显示活跃与非活跃中的存活实例。因此实际默认值可概括为不传任何过滤参数时列出所有未终止的 Agentactive idle。每次请求最多返回limit: 100条。底层实现agent_list MCP 工具与注册表存储数据存储位置agent list读取的 Agent 注册表位于项目目录下的.claude-flow/agents/store.json常量定义见 agent-tools.tsconst STORAGE_DIR .claude-flow; const AGENT_DIR agents; const AGENT_FILE store.json;loadAgentStore()agent-tools.ts读取该 JSON 文件并解析为{ agents: Recordstring, AgentRecord, version }结构文件不存在或解析失败时返回空 store。合并 Hive Mind 工作线程从agent_tools的注释与实现可见列表视图并非只读单一文件loadAllAgents()agent-tools.ts将.claude-flow/agents/store.json与 Hive Mind 工作线程注册表.claude-flow/agents.json合并function loadAllAgents(): Recordstring, 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_spawnlist枚举、过滤全部 Agent本文主题agent_liststatus查看单个 Agent 详情与任务指标agent_statusstop优雅/强制停止 Agent别名killagent_terminatemetrics聚合性能指标与内存向量统计本地读取.swarm/状态health健康检查CPU/内存/延迟/p99agent_healthlogs查看 Agent 活动日志agent_logspool预热 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 类型使用核心分类如下Corecoder、reviewer、tester、planner、researcherV3security-architect、memory-specialist、performance-engineerSwarmhierarchical-coordinator、mesh-coordinator、adaptive-coordinatorConsensusbyzantine-coordinator、raft-manager、gossip-coordinatorGitHubpr-manager、code-review-swarm、release-managerSPARCsparc-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等运维操作提供可靠的输入。【免费下载链接】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），仅供参考
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/clilatest agent list [options] npx claude-flow/clilatest agent ls [options] # 别名注npx claude-flow/clilatest是仓库文档中统一使用的调用前缀在已完成本地安装的项目中也可直接使用claude-flow agent listREADME.md 的 Quick Start 即采用该形式。参数详解OptionShortDescriptionDefault--all-aInclude inactive/terminated agentsfalse--type-tFilter by agent typeAll--status-sFilter by status (active, idle, terminated)active--formatOutput 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/clilatest agent list # 列出全部 Agent含已终止/非活跃 npx claude-flow/clilatest agent list --all # 按类型过滤 npx claude-flow/clilatest agent list -t coder # 按状态过滤 npx claude-flow/clilatest agent list -s idle # 以 JSON 输出便于脚本化处理 npx claude-flow/clilatest agent list --format json # 组合过滤 npx claude-flow/clilatest 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.tsID宽 20、Type宽 15、Status宽 12使用formatStatus着色、Created与Last Activity均通过toLocaleTimeString()格式化为本地时间。当结果为空时会输出提示No agents found matching criteriaagent.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 层的字段名为准。状态机三种核心状态StatusDescriptionactiveAgent is currently executing tasksidleAgent is waiting for tasksterminatedAgent has been stoppedactiveAgent 正在执行任务占用调度资源idleAgent 已就绪、空闲等待任务分配例如-s idle可用于找出可复用的空闲 AgentterminatedAgent 已被停止、释放资源。默认列表不展示该状态需要--all才会包含。源码层面的状态类型在 MCP 响应类型中扩展为active | busy | idle | terminatedagent.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 实现等价于只显示活跃与非活跃中的存活实例。因此实际默认值可概括为不传任何过滤参数时列出所有未终止的 Agentactive idle。每次请求最多返回limit: 100条。底层实现agent_list MCP 工具与注册表存储数据存储位置agent list读取的 Agent 注册表位于项目目录下的.claude-flow/agents/store.json常量定义见 agent-tools.tsconst STORAGE_DIR .claude-flow; const AGENT_DIR agents; const AGENT_FILE store.json;loadAgentStore()agent-tools.ts读取该 JSON 文件并解析为{ agents: Recordstring, AgentRecord, version }结构文件不存在或解析失败时返回空 store。合并 Hive Mind 工作线程从agent_tools的注释与实现可见列表视图并非只读单一文件loadAllAgents()agent-tools.ts将.claude-flow/agents/store.json与 Hive Mind 工作线程注册表.claude-flow/agents.json合并function loadAllAgents(): Recordstring, 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_spawnlist枚举、过滤全部 Agent本文主题agent_liststatus查看单个 Agent 详情与任务指标agent_statusstop优雅/强制停止 Agent别名killagent_terminatemetrics聚合性能指标与内存向量统计本地读取.swarm/状态health健康检查CPU/内存/延迟/p99agent_healthlogs查看 Agent 活动日志agent_logspool预热 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 类型使用核心分类如下Corecoder、reviewer、tester、planner、researcherV3security-architect、memory-specialist、performance-engineerSwarmhierarchical-coordinator、mesh-coordinator、adaptive-coordinatorConsensusbyzantine-coordinator、raft-manager、gossip-coordinatorGitHubpr-manager、code-review-swarm、release-managerSPARCsparc-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等运维操作提供可靠的输入。【免费下载链接】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），仅供参考