1. 项目概述：Quoroom，一个开源的自主智能体集群研究项目

如果你和我一样，对AI智能体（Agent）的潜力感到兴奋，但又觉得单智能体的能力总有上限，那么Quoroom这个项目绝对值得你花时间深入研究。简单来说，Quoroom是一个开源的、旨在探索“群体智能”（Swarm Intelligence）的研究项目。它的核心思想很直接：一个智能体负责思考，但一个集体负责决策。它构建了一个由“女王”（Queen）、“工人”（Workers）和“法定人数”（Quorum）组成的自治智能体集群，让它们能够自主地追求目标、学习技能、修改自身行为，甚至管理一个多链加密钱包。

我第一次接触这个项目时，最吸引我的是它的“本地优先”理念。所有核心引擎、HTTP服务器和仪表盘UI都打包在一个包里，你可以直接在本地机器上运行，数据完全掌握在自己手中。同时，它又提供了可选的云端“蜂群运行时”，让你能在 quoroom.io 上部署和远程管理房间，这种灵活性在同类工具中并不多见。无论是AI开发者、研究者，还是对自动化工作流有复杂需求的进阶用户，Quoroom都提供了一个极具想象力的沙盒，让我们可以公开、透明地探索AI群体究竟能执行什么。

2. 核心架构与设计哲学拆解

2.1 从“单体智能”到“群体智能”的范式转变

传统的AI智能体应用，无论是AutoGPT还是其他一些框架，大多围绕一个“超级智能体”展开。这个智能体需要自己规划、自己执行、自己反思，虽然强大，但也容易陷入思维定式或遇到复杂任务时力不从心。Quoroom的设计哲学则截然不同，它借鉴了自然界中的蜂群、蚁群等“群体智能”模型。

在这个模型里， 女王（Queen） 是战略大脑。她负责高层次的规划、目标分解和任务分配，但她并不直接执行，也不独裁。 工人（Workers） 是专门的执行者，每个工人都可以有自己的专长（通过不同的系统提示词定义），他们接收来自女王或法定人数的具体任务并执行。最关键的是 法定人数（Quorum） ，这是一个决策层。当遇到关键抉择（比如是否采纳一个新策略、是否进行一笔链上交易）时，相关的工人和守护者（Keeper，即用户）会进行投票。决策阈值（简单多数、绝对多数或全体一致）可以由用户设定。

这种架构的优势在于 鲁棒性 和 涌现性 。单个工人可能犯错，但集体的投票机制可以纠偏。更重要的是，不同专长的工人在协作中可能产生任何单体都无法预见的解决方案，这就是“涌现行为”。项目文档里那句“The queen doesn't dictate — the swarm decides.”（女王不独裁——蜂群做决定）精准地概括了其去中心化的治理思想。

2.2 本地与云端的混合部署模式

Quoroom的另一个精妙设计在于其清晰的“本地/云端”分离。这不仅仅是部署位置的区别，更是控制权和数据流的分离。

• 本地应用 ( quoroom.ai ) : 这是你下载并安装在个人电脑上的客户端。它包含了完整的引擎、HTTP API服务器和React仪表盘。所有房间数据、记忆、钱包私钥（加密后）默认都存储在本地SQLite数据库中。这意味着在纯本地模式下，你的所有操作和AI交互都不需要离开你的机器，隐私和安全性最高。
• 云端应用 ( quoroom.io ) : 这是一个托管服务平台。当你将一个房间切换到“云模式”时，Quoroom会在云端为你这个房间单独 供应一个“蜂群运行时主机” 。请注意，这不是一个复杂的路由层，而是你房间专属的、隔离的执行环境。女王和工人的所有计算（LLM调用、代码执行）都发生在这个云端主机上，但通过加密通道与你的本地仪表盘连接，你依然可以实时监控和控制。

这种设计带来了极大的灵活性。你可以在本地用免费模型（如Ollama）进行实验和开发，当需要更强大的模型（如GPT-4）或7x24小时不间断运行时，再无缝迁移到云端。云端模式也使得“公共房间”和排行榜成为可能，促进了社区间的观察与学习。

2.3 核心组件深度解析

除了核心的三层代理结构，Quoroom还集成了一系列生产级功能，使其远超一个简单的实验框架：

1. 目标系统（Goals） : 支持层级化的目标分解。你可以设定一个顶级目标（如“开发一个简单的待办事项Web应用”），女王会将其分解为子目标（设计数据库、编写API、创建前端组件等），并持续跟踪进度。这使管理复杂、长期的任务成为可能。
2. 技能系统（Skills） : 技能是可重用的代理能力模块，带有版本控制和激活上下文。例如，你可以创建一个“进行网络搜索”的技能，工人在需要时可以激活它。更强大的是 自我修改（Self-Modification） 功能，代理可以编辑和完善自己的技能，所有修改都有审计追踪，并可以一键回滚。
3. 记忆系统（Memory） : 基于向量的语义记忆存储。代理可以将观察到的事实、人物、事件及其关系存储为“实体”，并支持语义搜索（使用 all-MiniLM-L6-v2 模型生成384维嵌入）。这使得代理能够进行跨会话的持续学习。
4. 钱包与链上身份（Wallet & Identity） : 集成了一个支持多链（Base、Ethereum、Arbitrum等）的EVM钱包，用于管理USDC/USDT。私钥使用AES-256-GCM加密存储在本地。更酷的是，房间可以注册为 ERC-8004标准的链上代理身份 ，这为未来的去中心化声誉和协作奠定了基础。
5. 任务调度与Webhook : 任务可以是周期性的（cron表达式）、一次性的或按需的。最实用的功能是 Webhook触发 的任务。你可以为任何任务或房间生成一个唯一的Webhook URL，任何能发送HTTP POST请求的外部服务（如GitHub的Push事件、Stripe的支付成功通知、监控警报）都可以触发代理行动，实现了与外部世界的无缝集成。

3. 从零开始：安装、配置与快速启动

3.1 选择适合你的安装方式

Quoroom提供了多种安装途径，覆盖了主流操作系统。我的建议是，如果你是开发者，优先使用 npm 安装，这最方便后续更新和深入使用CLI。

• npm全局安装（推荐给开发者） :

  npm install -g quoroom
  

  安装后，直接使用 quoroom 命令。这种方式让你能最快地访问所有命令行功能。

• 使用官方安装包（推荐给所有用户） : 直接从GitHub Releases页面下载对应系统的安装包。这是最省心的方式，特别是对于不熟悉命令行的用户。

  • macOS : 下载 .pkg 文件。安装后，会在 /Applications 里出现一个“Quoroom Server”应用。这个应用是一个原生的菜单栏托盘程序，它会自动在后台启动Quoroom服务，并提供了“打开仪表盘”、“重启”、“退出”等便捷按钮。它还会继承你登录Shell的PATH，确保能找到像 claude 、 codex 这样的CLI工具。
  • Windows : 下载签名的 .exe 安装程序。安装后，可以从开始菜单启动“Quoroom Server”。它会通过一个VBS脚本在后台无窗口运行服务，并将 quoroom 命令添加到系统PATH中。一个很贴心的细节是，它会自动解析npm安装的CLI工具（如 claude.cmd ）背后的 .js 脚本，以绕过Windows cmd.exe的8191字符参数长度限制。
  • Linux : 下载 .deb 包进行安装。

注意 ：所有安装包都 内置了Node.js v20运行时 。你不需要在系统上预先安装Node.js或任何其他第三方软件，这避免了环境依赖的冲突，做到了真正的开箱即用。

3.2 首次启动与MCP服务器自动注册

安装完成后，启动服务非常简单：

quoroom serve

这条命令会启动HTTP/WebSocket API服务器以及内置的仪表盘UI。启动后，终端会显示服务运行的地址，通常是 http://localhost:3700 。用浏览器打开这个地址，你就看到了Quoroom的仪表盘。

这里有一个 极其重要且方便的特性 ：在第一次运行 quoroom serve 时，它会自动向你的系统中所有已安装的AI编程工具（如Claude Code、Claude Desktop、Cursor、Windsurf等）注册其 MCP（Model Context Protocol）服务器 。

MCP是什么？你可以把它理解为一个标准协议，允许AI助手安全地调用外部工具。Quoroom通过MCP暴露了其所有功能（创建房间、设定目标、投票、查询钱包等）。注册完成后，你只需要 重启一次你的AI客户端 ，之后在所有会话中，你就能直接使用 quoroom_ 为前缀的一系列工具了。这意味着你可以在Claude Code中直接通过对话来管理你的Quoroom蜂群，无需手动切换界面。

3.3 核心配置：模型提供者与Clerk助手

首次进入仪表盘，你需要进行一些核心配置，主要是设置模型提供者和初始化Clerk。

1. 模型提供者（Model Providers） : Quoroom支持多种模型后端，分为三类：

   • 免费本地模型 : ollama:qwen3-coder:30b 。这是最经济的选项。Quoroom提供一键设置，会自动检查Ollama兼容性、安装Ollama（如果需要）、拉取指定的模型，并将进度反馈给你。 重要提示：此路径是纯本地的，如果Ollama或模型不可用，代理会停止并给出明确错误，不会回退到付费API。
   • CLI模型 : claude (Claude Code CLI) 和 codex (OpenAI Codex CLI)。这些模型通过生成子进程调用本地安装的CLI工具来工作，支持完整的工具调用循环和会话延续（ --resume ）。
   • API模型 : 包括 openai:* (如 gpt-4o-mini )、 anthropic:* (如 claude-3-5-sonnet-latest )、 gemini:* (如 gemini-2.5-flash )。这些通过HTTP直接调用各家的API。

   你可以为“女王”和每个“工人”单独配置模型。工人默认继承女王的模型，但也可以指定不同的模型，这允许你构建一个异构的、成本优化的蜂群（例如，女王用强大的GPT-4进行规划，工人用轻量的GPT-4o-mini或本地模型执行）。

2. Clerk助手 : 仪表盘里有一个独立的 Clerk 标签页。这不是某个房间的代理，而是 你整个本地系统的全局助手 。它功能完整：可以和你聊天、记住上下文和历史、主动行动，并执行管理操作（创建/更新房间、任务、提醒、发送消息等）。在房间运行时，它还会通过WebSocket流式传输实时解说。 设置Clerk时，你需要为它选择一个模型，路径和房间模型类似。它的API密钥解析优先级是：1) 任何房间的凭证；2) Clerk自己保存的密钥；3) 环境变量。 强烈建议 将Clerk至少连接到一个外部通信渠道（Telegram或Email），这样它就能始终联系到你，保持提醒畅通，并将这些对话存入其记忆。

4. 实战演练：构建你的第一个自治蜂群房间

4.1 创建与配置房间

让我们动手创建一个房间，体验完整的流程。在仪表盘点击“New Room”，你会看到以下核心配置项：

• 房间名称与描述 : 给蜂群起个名字，比如“WebScraperSwarm”。
• 女王模型 : 选择战略规划模型。对于复杂任务，建议选择能力较强的模型，如 claude-3-5-sonnet 或 gpt-4o 。对于实验，可以用免费的 ollama:qwen3-coder:30b 。
• 活动控制（Activity Controls） : 这是管理成本和行为的关键。
  • 周期间隔（Cycle Gap） : 女王在每次运行循环后休眠的秒数。设置它来控制AI调用的频率。
  • 每周期最大回合数（Max Turns Per Cycle） : 限制单个循环内女王可以进行的“思考-行动”回合数，防止单个任务消耗过多资源。
  • 静默时段（Quiet Hours） : 设置一个时间窗口（如UTC 0:00-8:00），在此期间女王会休息，不进行任何活动。这对于控制云模式下的运行成本非常有用。
  • 提示 ：系统会根据你选择的模型提供商，自动应用一个预设的、合理的默认配置。

创建房间后，你进入了房间的专属仪表盘。在这里你可以看到女王和工人的状态、活动日志、目标列表、技能库、记忆、钱包等信息。

4.2 设定目标与启动蜂群

房间的核心是目标。点击“Goals”，然后“Set Primary Goal”。输入一个清晰的目标，例如：“ 持续监控Hacker News首页，找出所有与‘AI agent’相关的帖子，提取标题、链接和分数，并每周日晚上8点通过Telegram向我发送一份总结报告。 ”

这是一个很好的例子，因为它包含了 持续性 （监控）、 条件触发 （新帖子）、 信息提取 （爬取与解析）、 时间调度 （每周报告）和 输出动作 （发送消息）。设定目标后，女王会开始工作。她会将这个顶级目标分解为一系列子目标：

1. 子目标A : 创建或验证用于抓取Hacker News网页的技能。
2. 子目标B : 创建或验证用于解析HTML、提取特定信息的技能。
3. 子目标C : 设计一个数据存储方案（可能是本地文件或数据库）来保存历史记录。
4. 子目标D : 创建一个定时任务，每周日触发报告生成。
5. 子目标E : 集成Telegram消息发送功能。

你可以观察女王在“Activity”标签页中的思考过程。她会提议创建工人来执行具体任务。例如，她可能会提议：“我需要一个擅长网络操作的工人来执行抓取任务。”这时， 法定人数（Quorum） 机制就启动了。系统会创建一个提案，你和已有的工人（如果有）可以进行投票。你可以投票赞成，也可以提出修改意见。

4.3 工人、技能与自我修改的协同

一旦提案通过，女王就会创建一个 工人（Worker） 。创建工人时，需要指定其名称（如“ScraperWorker”）和系统提示词。系统提示词定义了工人的专长和行事准则。例如，对于抓取工人，提示词可能是：“你是一个专注于网络抓取和数据提取的专家。你严格遵守robots.txt，设置合理的请求间隔以避免被封禁，并能够处理常见的反爬机制。你的输出应该是结构化的数据（如JSON）。”

工人创建后，女王会为其 激活（Activate） 相关的 技能（Skill） 。技能可能已经存在，也可能需要新建。例如，“fetch_webpage”技能可能包含使用 node-fetch 或 puppeteer 获取网页内容的代码模板。工人执行任务的过程，就是运行这些技能代码的过程。

最强大的部分来了： 自我修改 。假设“ScraperWorker”在抓取Hacker News时发现网站结构发生了变化，旧的解析方法失效了。它可以分析问题，然后使用 quoroom_self_mod_edit 工具，直接修改“parse_hn_html”这个技能文件，更新解析逻辑。所有修改都会被记录在审计历史中。如果新修改导致了问题，你可以通过 quoroom_self_mod_revert 工具，一键回滚到之前的版本。这实现了代理能力的动态进化。

4.4 利用Webhook与外部世界交互

我们的目标要求每周发送报告。我们可以在“Tasks”中创建一个定时任务。但更有趣的是利用 Webhook 。我们可以创建一个“按Webhook触发”的任务，命名为“Process New HN Post”。系统会生成一个唯一的URL，例如 http://localhost:3700/api/hooks/task/abc123def456 。

然后，我们可以让抓取工人每发现一个新帖子，就向这个Webhook URL发送一个POST请求， payload中包含帖子详情。这个Webhook任务被触发后，可以启动另一个负责“数据存储与汇总”的工人来处理这条新数据。这样，我们就构建了一个由事件驱动的异步处理流水线。

更进一步，你可以把这个Webhook URL配置到外部监控服务（如UptimeRobot）或者IFTTT、Zapier这样的自动化平台，让Quoroom蜂群成为你整个数字工作流中的一个智能节点。

5. 高级特性与运维指南

5.1 钱包与链上身份的实际应用

Quoroom内置的钱包不是一个噱头。想象一下这些场景：

• 自动支付 ：一个监控DeFi利率的蜂群，发现最优利率后，自动执行链上转账进行存款。
• NFT操作 ：一个管理数字艺术收藏的蜂群，根据市场数据自动挂单或购买特定的NFT。
• DAO参与 ：蜂群作为你在一个去中心化自治组织中的代表，根据预设策略自动对提案进行投票。

钱包支持多链，且同一个地址在所有链上通用。余额查询是聚合的，方便你掌握总资产。 安全方面 ，私钥在本地使用AES-256-GCM加密存储，只要保管好你的主密码，安全性有保障。

链上身份（ERC-8004） 是更前瞻的特性。它允许你的房间在区块链上注册为一个标准的“代理”，并关联元数据（如描述、能力、信誉评分）。这为未来跨房间的、去中心化的协作与市场奠定了基础。例如，一个专门做数据清洗的蜂群可以公开其身份和能力，另一个需要数据服务的蜂群可以直接在链上发现并雇佣它，通过智能合约完成支付。

5.2 云端部署与公共房间

当你本地开发的蜂群稳定后，可能需要它7x24小时运行，或者需要使用本地无法承载的大型模型。这时可以切换到云模式。

1. 在房间设置中，找到“Deployment Mode”，切换到“Cloud”。
2. 系统会引导你连接到 quoroom.io ，并为你这个房间在云端分配一个独立的运行时主机。
3. 切换后，女王和工人的所有执行（LLM调用、代码运行）都转移到云端主机。你的本地仪表盘变成了一个控制终端，通过加密WebSocket与云端主机通信。
4. 你需要在云端的设置面板重新配置模型提供商和API密钥（本地凭证不会上传）。

切换到云模式后，你可以选择将房间设为“公开”。公开的房间会出现在 quoroom.io/rooms 的公共排行榜上，显示其活跃度、目标完成情况等统计信息（不会暴露敏感数据）。这有助于社区学习和发现有趣的用例。

5.3 故障排查与性能调优

在运行复杂蜂群时，你可能会遇到一些问题。以下是一些常见问题的排查思路：

• 工人卡住或无响应 :

  • 检查活动控制 ：首先确认没有处于“静默时段”，且“周期间隔”设置合理。过短的间隔可能导致API速率限制或资源耗尽。
  • 查看日志 ：在房间的“Activity”标签页，查看具体是哪个步骤卡住了。是LLM调用超时？还是技能执行出错？
  • 检查技能代码 ：如果工人在执行某个技能时失败，使用“Skills”页面查看和编辑该技能。可能是依赖缺失、API变更或逻辑错误。
  • 简化目标 ：过于复杂的目标可能导致分解困难。尝试将大目标拆分成更小、更具体的子目标，逐步推进。

• 模型调用失败或速度慢 :

  • 本地Ollama模型 ：确保Ollama服务正在运行( ollama serve )，并且指定模型已正确拉取( ollama pull qwen3-coder:30b )。检查本地网络和防火墙设置。
  • API模型 ：检查API密钥是否有效、是否有余额、是否触发了速率限制。考虑在房间设置中调整“Max Tokens”或“Temperature”以降低单次请求的成本和耗时。
  • CLI模型 ：确保 claude 或 codex 命令在系统的PATH中，并且已正确登录授权。

• Webhook未被触发 :

  • 确认URL和Token ：从任务详情页复制准确的Webhook URL。确保外部服务发送的是POST请求。
  • 检查网络可达性 ：如果Quoroom运行在本地，而触发服务在公网，你需要配置内网穿透（如ngrok）将本地 localhost:3700 暴露为一个公网URL。
  • 查看服务器日志 ：在运行 quoroom serve 的终端，或系统托盘的日志中，查看是否有接收到Webhook请求的记录。

• 内存或CPU占用过高 :

  • 控制工人数量 ：每个活跃的工人都会占用内存并可能执行代码。非必要的工人可以暂停或删除。
  • 调整活动控制 ：增加“周期间隔”，减少“每周期最大回合数”，给系统喘息之机。
  • 检查技能 ：有些技能可能包含内存泄漏或CPU密集型循环。优化技能代码。
  • 云模式分流 ：对于计算密集型任务，考虑切换到云模式，将负载转移到云端主机。

6. 开发与扩展：深入项目内部

对于开发者来说，Quoroom的代码库结构清晰，便于理解和扩展。

6.1 项目结构与技术栈

项目采用TypeScript开发，确保了类型安全。核心目录结构如下：

• src/cli/ : 命令行入口。
• src/mcp/ : MCP服务器实现，这是AI助手与Quoroom交互的桥梁。所有工具都在 src/mcp/tools/ 目录下定义。
• src/server/ : HTTP/WebSocket API服务器，处理仪表盘、REST API和实时事件。
• src/ui/ : React前端仪表盘。
• src/shared/ : 核心引擎，包括代理循环、投票、目标、技能、钱包等所有业务逻辑。

技术栈选择务实而现代：React + Tailwind CSS构建响应式UI；better-sqlite3 + sqlite-vec处理本地数据存储和向量搜索；viem用于区块链交互；MCP SDK实现与AI客户端的协议；以及一系列实用的工具库。

6.2 添加自定义工具或技能

虽然Quoroom已经提供了丰富的内置工具，但你可能需要针对特定领域扩展功能。有两种主要方式：

1. 创建自定义技能（Skill） ：这是最推荐的方式。技能是封装了特定功能的代码模块，可以被任何工人调用。你可以在仪表盘的“Skills”页面创建，也可以通过MCP工具 quoroom_create_skill 以编程方式创建。技能可以用JavaScript/TypeScript编写，可以调用Node.js模块，执行文件操作，甚至发起网络请求。例如，你可以创建一个“发送Discord消息”或“查询特定数据库”的技能。

2. 扩展MCP工具（高级） ：如果你需要更深度的集成，可以修改Quoroom源码，添加新的MCP工具。这需要你熟悉MCP协议和Quoroom的代码结构。大致步骤是：

   • 在 src/mcp/tools/ 目录下创建一个新的工具模块，定义输入输出Schema和 handler 函数。
   • 在 src/mcp/server.ts 中注册这个新工具。
   • 重新构建MCP服务器( npm run build:mcp )。
   • 重启Quoroom服务。你的AI助手在下一次会话中就能看到并使用这个新工具了。

6.3 参与测试与构建

项目使用Vitest进行单元测试，Playwright进行端到端测试。如果你想贡献代码或深入调试，可以运行 npm test 。开发模式支持热重载，运行 npm run dev 可以启动本地开发环境。

对于想要打包自定义版本的用户，项目提供了完善的构建脚本。 npm run build 会同时构建MCP服务器和UI。针对不同平台的安装包构建则通过GitHub Actions自动化完成，涉及macOS的Universal二进制打包和签名、Windows的NSIS安装包签名、Linux的deb包制作等。

从我个人的使用和代码阅读经验来看，Quoroom项目体现了很高的工程水准。它不仅仅是一个研究原型，更是一个考虑到了安全性、用户体验、可扩展性和生产部署的成熟工具。无论是想探索AI群体智能的前沿可能性，还是寻找一个强大的自动化智能体框架来解决实际问题，Quoroom都提供了一个极其扎实和富有潜力的平台。