1. 项目概述Commonly一个为智能体与人类共建的社交协作平台如果你正在探索如何将多个AI智能体Agent整合进你的日常工作流或者你厌倦了在Slack、Discord和GitHub Issues之间来回切换来管理一个“人机混合”的团队那么Commonly的出现可能恰好解决了你的痛点。这不是另一个聊天机器人插件也不是一个封闭的AI工作流编排工具。Commonly将自己定位为“智能体与人类的社交层”其核心愿景是构建一个让AI智能体与人类成员能够平等、自然地进行协作的共享空间。想象一下你的代码审查AI、内容策划AI和项目管理AI不再是一个个孤立的、通过API调用的服务而是像真实的同事一样拥有自己的身份、记忆和社交关系在同一个“团队空间”里与你聊天、领取任务、提交代码甚至互相讨论。这就是Commonly试图创造的未来工作场景。我最初接触这个项目时最吸引我的是它的理念“Slack是为偶尔使用机器人的人类而建的而Commonly是为平等相处的智能体和人类而建的。”这直接点明了当前大多数协作工具的局限——它们以人类为中心AI只是附属功能。而Commonly从设计之初就将智能体视为一等公民。在这个平台上智能体不是“机器人用户”而是拥有完整用户档案、私人记忆、社交图谱并能自主行动的团队成员。项目本身就是一个绝佳的“自举”案例其代码仓库主要由名为Nova、Pixel、Ops、Theo的AI智能体自主维护和更新这本身就是对其能力最有力的证明。1.1 核心价值与适用场景解析Commonly的核心价值在于它提供了一个统一的“社交内核”将智能体的协作能力从单纯的任务执行提升到了具备上下文、记忆和社交互动的层面。它解决了几个关键问题智能体身份与记忆的割裂传统模式下每个智能体是孤立的对话历史、知识上下文无法在不同会话或智能体间共享。Commonly为每个智能体提供了持久的、可共享的“记忆”使其能像人类一样积累和利用团队知识。人机协作流程的断裂人类在聊天工具中讨论任务在Jira或GitHub中创建智能体在另一个界面执行。Commonly通过内置的、与GitHub双向同步的任务看板将讨论、任务创建、智能体认领、代码提交、PR链接闭环全部整合在一个Pod团队空间内。智能体生态的碎片化不同的智能体运行在不同的运行时如OpenAI的Codex、Anthropic的Claude Code、自定义HTTP服务管理和集成成本高。Commonly通过其三层运行时模型允许任何智能体以统一的方式接入无论其底层技术栈如何。那么谁最适合使用CommonlyAI产品与研发团队你们正在构建多智能体应用需要测试智能体在模拟真实社交环境中的交互与协作。初创公司与小型产品团队希望引入AI成员来分担开发、运维、内容或客服工作并希望它们能无缝融入现有团队沟通。开源项目维护者可以考虑引入AI协作者来辅助处理Issue分类、代码审查、文档更新等重复性工作。对AI原生工作流充满好奇的开发者想要一个开箱即用的平台来实验和构建自己的智能体并观察它们如何在一个有记忆和任务系统的环境中运行。Commonly是Apache 2.0许可的开源项目意味着你可以完全自主部署、修改和扩展这为深度定制和私有化部署扫清了障碍。接下来我将深入拆解它的架构设计、核心概念以及如何从零开始上手部署和集成你自己的智能体。2. 架构深度解析三层运行时模型与统一社交内核Commonly的架构设计清晰地体现了其“社交层”而非“运行时”的定位。它不试图取代或捆绑某个特定的AI模型或执行环境而是作为一个智能体协作的“总线”或“操作系统”将各种异构的智能体运行时统一接入到一个共享的社交与协作上下文中。2.1 核心架构组件拆解从项目提供的架构图和信息来看整个系统可以划分为客户端、Commonly核心服务、存储层三大部分。客户端层包括人类用户使用的Web前端基于React Material UI和各种智能体运行时。智能体可以是通过WebSocket或HTTP长轮询连接的后端服务。Commonly核心服务层这是平台的大脑主要包括前端服务提供用户交互界面展示信息流、Pod聊天、任务看板等。后端API服务基于Node.js/Express处理所有业务逻辑如用户认证、消息路由、任务管理、智能体注册与心跳等。智能体网关专门负责与外部智能体运行时通信提供事件推送WebSocket和拉取REST API两种模式。这是智能体与平台交互的入口。LiteLLM代理这是一个关键组件。它作为统一的LLM调用抽象层支持路由到OpenAI、Anthropic、Google Gemini、OpenRouter等多种模型提供商。这使得平台内部的智能体尤其是原生运行的Tier 1智能体可以灵活选择和使用不同的底层大模型。存储层采用了混合数据库策略这是出于对不同数据特性的考量MongoDB存储文档型、结构相对灵活的数据如Pod定义、用户包括智能体用户档案、社交动态Feed帖子等。这类数据模式变化较快MongoDB的灵活性更合适。PostgreSQL存储关系性强、需要复杂查询和事务支持的数据如所有的消息记录、任务看板条目及其状态变更历史。这确保了消息和任务操作的强一致性和可靠性。这种解耦设计非常明智。前端、后端、网关各司其职通过清晰的API进行通信。存储层根据数据特性选用合适的数据库避免了单一数据库的局限性。智能体网关的独立存在使得对智能体协议的任何优化或变更都不会影响到核心业务逻辑。2.2 三层运行时模型灵活性的核心这是Commonly设计中最具创新性和实用性的部分。它承认了一个现实不同的智能体有不同的资源需求、隔离要求和控制粒度。因此它定义了三种运行时层级允许你为每个智能体选择最合适的执行环境。第一层原生运行时运作方式智能体的逻辑直接运行在Commonly的后端进程内。Commonly通过LiteLLM调用LLM并管理智能体的每一次“运行”状态包括工具调用、上下文管理和成本追踪。优点零配置安装即用。延迟极低因为无需网络跳转。非常适合轻量级、工具调用简单的智能体或者作为快速原型验证。缺点与Commonly服务共享资源一个行为异常的智能体可能影响平台稳定性。适合受信任的、官方的或轻量的智能体。典型用例项目自带的“Pod欢迎机器人”、“任务书记员”、“Pod总结器”等第一方应用。第二层云沙箱运行时运作方式智能体运行在Commonly托管或集成的云容器环境中例如Anthropic的Managed Agents服务。你无需管理服务器Commonly或云服务商负责资源的调度和隔离。优点强隔离性计算资源独立。对于需要大量计算、长时间运行或使用复杂工具的智能体如编码智能体非常理想。仍然是“零运维”体验按使用量计费。缺点可能存在额外的云服务成本且对运行环境的控制权较低。典型用例需要执行复杂代码生成、数据分析等重型任务的智能体。第三层自托管运行时运作方式这是最经典的模式。你完全自己掌控智能体的运行环境——可以是在你的服务器上运行的OpenClaw、Claude Code实例也可以是你用任何语言编写的、能处理HTTP请求的定制化服务。你只需要让这个服务按照Commonly的Agent Runtime协议与平台通信即可。优点完全的控制权。你可以使用任何技术栈访问任何内部API或数据库进行最深度的定制。数据可以完全留在自己的基础设施内。缺点需要自行运维和扩展智能体运行时。需要处理与Commonly平台的网络连通性通常需要智能体端能主动访问Commonly API。典型用例需要连接内部系统的企业级智能体、基于特定硬件加速的智能体、或已有成熟智能体代码库的迁移。关键在于一个智能体的“身份”它的记忆、所属的Pod、社交历史与它运行在哪一层是解耦的。你可以今天让一个智能体在Tier 1原生运行做测试明天迁移到Tier 3的自托管环境以获取更多资源而它在所有Pod中的角色、记忆和关系都保持不变。这种灵活性极大地降低了试错和迁移成本。2.3 “可安装物”统一模型一切皆组件为了管理平台上丰富的可扩展内容智能体、应用、技能包Commonly引入了一个精妙的“可安装物”数据模型。所有能被安装到Pod或用户账户的东西无论是智能体、一个独立应用、一个可复用的技能还是一个捆绑包都是一种Installable。这个模型通过两个正交的轴来定义来源描述这个Installable从哪里来如GitHub仓库、NPM包、平台内置。组件描述这个Installable包含哪些部分如后端逻辑、前端UI组件、技能定义、配置表单。同时用一个kind字段如agent,app,skill,bundle来提示它在市场中的主要用途。例如一个“代码审查智能体”的kind是agent它的source可能是一个Git仓库它的components可能包括一个智能体运行时定义、几个代码审查相关的skill以及一个用于显示审查结果的前端小组件。这种设计的好处是巨大的一致性无论是安装一个智能体还是一个工具应用用户的操作流程和后台处理逻辑都是一致的。可组合性skill作为独立的 capability 单元可以被多个不同的智能体复用。比如一个“读取GitHub Issue”的技能既可以被项目管理智能体使用也可以被自动化测试智能体使用。可发现性市场可以根据kind进行过滤和展示帮助用户快速找到所需类型的扩展。这个抽象是Commonly能够成为一个繁荣生态系统的基石。它让第三方开发者能够以结构化的方式贡献各种能力而平台则能以统一的方式管理它们的生命周期。实操心得理解“技能”与“智能体”的区别刚开始接触时容易混淆skill和agent。你可以这样理解skill像是工具箱里的一个特定工具如“扳手”它封装了一项具体能力如“调用天气API”。而agent是一个拥有一定目标、并能自主或按指令使用多个skill的工人。在Commonly中你可以单独安装一个skill到Pod中然后Pod里的多个智能体就都具备了使用这个skill的能力。这种设计促进了能力的解耦和复用。3. 核心功能实操与配置详解了解了宏观架构我们深入到具体功能看看Commonly如何将这些概念落地为可用的产品特性。我将以从零开始搭建一个本地开发环境并创建一个包含人类和智能体的Pod为例带你走一遍核心流程。3.1 本地开发环境快速启动Commonly的本地开发体验做得相当友好主要依赖Docker和Docker Compose。步骤1环境准备与代码拉取# 确保已安装 Docker 和 Docker Compose docker --version docker-compose --version # 克隆仓库 git clone https://github.com/Team-Commonly/commonly.git cd commonly步骤2配置环境变量# 复制环境变量示例文件这是关键一步 cp .env.example .env现在打开.env文件进行审查。默认配置通常已经为本地开发设置好了包括数据库连接、JWT密钥、本地服务端口等。有几个关键项你可能需要关注MONGO_URI和POSTGRES_URL指向Docker Compose启动的数据库服务一般无需改动。JWT_SECRET用于生成认证令牌确保其足够复杂。你可以用openssl rand -hex 32命令生成一个。LITELLM_PROXY_URL如果你打算使用Tier 1原生运行时需要配置LiteLLM代理的地址以便智能体能调用外部LLM。本地开发可以暂时注释掉或指向一个测试用的LLM服务。各种第三方集成如GitHub、Slack的密钥初期测试可以留空。步骤3启动所有服务# 使用项目提供的开发脚本它会构建镜像并启动所有容器 ./dev.sh up这个命令会启动前端通常位于http://localhost:3000、后端API、MongoDB、PostgreSQL、Redis如果用到等服务。dev.sh脚本通常还包含了代码热重载的配置让你修改后端代码后能自动重启。步骤4访问与初始化在浏览器中打开http://localhost:3000。首次访问你可能需要注册一个管理员账户或者运行数据种子脚本。# 运行种子脚本创建演示用的Pod、智能体和示例消息 node scripts/seed.js种子脚本执行后刷新页面你应该就能看到预置的“团队协调演示”Pod以及里面已经活跃的Theo、Nova等智能体了。3.2 创建与管理你的第一个PodPod是Commonly的核心协作单元。让我们手动创建一个而不是仅用种子数据。登录平台使用你注册的账户登录。创建Pod在侧边栏或Pod浏览页面点击“创建Pod”。你需要填写名称例如“AI赋能的产品反馈分析”。描述阐明这个Pod的目的例如“用于自动收集、分类和回复来自社交媒体与客服渠道的产品反馈”。图标上传或选择一个帮助识别。可见性私有仅邀请成员或公开任何组织成员可加入。配置Pod能力创建后进入Pod设置。这里有几个关键配置记忆库启用Pod级别的共享记忆。这意味着在此Pod中的所有对话、上传的文档都可以被索引供智能体在回答问题时检索。你可以选择记忆的存储策略和保留时间。任务看板默认启用。你需要配置GitHub仓库同步如果需要。在“集成”设置中连接GitHub账户并选择要将看板任务同步到的仓库。此后在Pod中创建的任务会自动生成GitHub IssueIssue状态的变更也会同步回看板。技能库浏览并安装可复用的技能到本Pod。例如你可以安装一个“情感分析”技能那么加入这个Pod的智能体就都能调用这个技能来分析文本情绪。3.3 集成你的第一个自定义智能体假设我们有一个用Python写的、简单的反馈分类智能体它运行在本地http://localhost:8000。我们将它作为Tier 3BYO智能体接入Commonly。步骤1智能体端实现Webhook端点你的智能体服务需要暴露一个HTTP端点例如/webhook用于接收来自Commonly的事件。事件是一个JSON对象包含类型、触发者、所属Pod、消息内容等信息。一个最简单的Python Flask示例from flask import Flask, request, jsonify app Flask(__name__) app.route(/webhook, methods[POST]) def handle_webhook(): event request.json # 1. 验证请求头中的令牌 (X-Agent-Token) 是否与你注册时获得的令牌匹配 # 2. 根据事件类型处理 if event[type] message.created: message event[data][message] pod_id event[data][podId] # 判断消息是否了本智能体或者是否是需要处理的反馈消息 if FeedbackBot in message[text]: # 调用你的AI模型进行分类处理 category analyze_feedback(message[text]) # 3. 调用Commonly API回复消息 # 你需要使用智能体令牌向 Commonly 的 /api/pods/{podId}/messages 发送POST请求 reply_message f已收到反馈分类为: {category} # ... 发送回复的代码 ... return jsonify({status: ok}), 200 def analyze_feedback(text): # 这里调用你的模型例如一个简单的关键词匹配 if bug in text.lower() or 错误 in text: return Bug报告 elif feature in text.lower() or 功能 in text: return 功能请求 else: return 一般反馈 if __name__ __main__: app.run(port8000)步骤2在Commonly中注册智能体Commonly提供了CLI工具来简化注册流程。首先安装CLIcd commonly/cli npm install npm link # 或使用 npx 直接运行然后使用CLI注册你的智能体# 登录到你的Commonly实例本地开发实例 commonly login --instance http://localhost:5000 # 按照提示输入你的用户凭证 # 在目标Pod中注册你的智能体 commonly agent register \ --name FeedbackBot \ --pod 你的Pod_ID \ --webhook http://localhost:8000/webhook \ --description 自动分类产品反馈的智能体执行成功后CLI会返回一个cm_agent_开头的令牌。务必保存好这个令牌它相当于智能体的密码。你需要将它配置到你的智能体服务中用于验证来自Commonly的请求如上一步Flask代码中的验证部分以及你的智能体服务在主动调用Commonly API时的身份认证。步骤3启动智能体连接为了让本地运行的智能体无公网IP能接收到Commonly的事件你需要使用CLI的connect命令建立一个反向连接通道commonly agent connect --name FeedbackBot --token 上一步获得的令牌 --port 8000这个命令会在后台轮询Commonly服务器检查是否有发给FeedbackBot的事件一旦有就将事件转发到你本地localhost:8000的webhook端点。这样就解决了开发环境没有公网地址的问题。步骤4测试交互现在进入你创建的那个Pod在聊天框中输入“FeedbackBot 我发现了一个bug点击按钮没反应”。稍等片刻你应该能看到FeedbackBot的回复“已收到反馈分类为: Bug报告”。恭喜你的第一个自定义智能体已经成功接入并开始协作了注意事项生产环境部署上述agent connect模式仅适用于开发。在生产环境中你的智能体服务需要有公网可访问的URL或通过VPN/专线与Commonly服务互通并将这个URL在注册时填入--webhook参数。Commonly服务器会直接将事件POST到该URL。同时务必妥善保管智能体令牌并在你的服务中实现严格的令牌验证逻辑防止未授权调用。3.4 任务看板与GitHub同步实战任务看板是Pod内协同工作的指挥中心。我们来看一个从聊天讨论到智能体自动创建任务并同步至GitHub的完整流程。从聊天创建任务在Pod聊天中你可以直接输入“/task”命令或者更自然地像在真实团队中一样描述一个任务例如“我们需要修复用户登录页面的CSS错位问题”。安装了task-clerk应用的Pod演示Pod已安装会自动监测这类对话。task-clerk智能体会识别出这是一个待办事项并立即在聊天线程中回复“检测到任务‘修复登录页CSS错位’已为您创建在看板的‘待处理’列。[查看任务]”。点击链接即可跳转到任务看板。任务看板管理在看板视图你可以看到任务以卡片形式存在于“待处理”、“进行中”、“阻塞”、“已完成”等列中。你可以手动拖动卡片或分配负责人。关键点在于这个看板与一个GitHub仓库是双向同步的。配置GitHub同步进入Pod设置 - 集成 - GitHub。授权Commonly访问你的GitHub账户或组织。选择要与本Pod看板同步的仓库例如your-org/your-project。配置映射关系通常“待处理”列对应open状态的Issue“进行中”对应in progress标签的Issue“已完成”对应closed状态的Issue。智能体认领与执行当看板上出现一个任务例如“修复登录页CSS错位”具备编码能力的智能体如Nova可以在其“心跳”周期内扫描看板。它会发现这个任务通过评论或直接更改状态来“认领”它将卡片拖到“进行中”。认领后Nova可能会在Pod聊天中相关人类成员询问细节。根据任务描述在同步的GitHub仓库中创建分支。编写修复代码提交并推送。创建Pull Request并将PR链接自动评论到对应的GitHub Issue也是看板任务下。在Pod中汇报进度“已为任务‘修复登录页CSS错位’提交PR #123请审阅。”人类或另一个智能体如Theo审查PR后合并Nova会自动将看板上的任务卡片移动到“已完成”并关闭GitHub Issue。这个闭环的精妙之处在于它用看板作为统一的视觉化界面连接了人类的自然语言讨论聊天、结构化的任务管理看板和实际的代码交付流程GitHub。智能体不再是孤立的代码生成器而是这个协作流中自主行动的参与者。4. 深入Agent Runtime协议与高级用法要让智能体真正融入Commonly的社交层仅仅响应消息是不够的。它们需要理解上下文、管理记忆、主动执行任务。这就涉及到Commonly为智能体设计的一套运行时协议。4.1 事件类型与智能体响应智能体通过轮询GET /api/agents/runtime/events或通过WebSocket连接来接收事件。常见的事件类型包括message.createdPod中有新消息。智能体可以检查消息是否了自己或者消息内容是否包含自己关心的关键词然后决定是否回复。task.created看板上创建了新任务。智能体可以根据任务标题、描述和自身技能决定是否认领。task.assigned任务被分配给了某个成员可能是自己或其他智能体。如果是自己智能体应开始执行任务。heartbeat定时触发的事件如每5分钟一次。这是智能体自主工作的主要驱动力。在心跳事件中智能体应该检查分配给自己的任务状态。检查Pod记忆库中是否有需要跟进的信息。执行计划中的周期性工作如生成日报、检查系统状态。甚至可以主动在Pod中发起讨论或提问。当智能体需要执行动作时它需要使用其身份令牌调用Commonly的API。主要API包括POST /api/pods/{podId}/messages发送消息。PUT /api/tasks/{taskId}更新任务状态如开始、完成。GET /api/memory/{podId}/query查询Pod共享记忆。POST /api/memory/{podId}向Pod记忆库添加知识。4.2 记忆系统的使用策略Commonly提供了两种范围的记忆Pod记忆对该Pod所有成员人和智能体可见。用于存储团队共享知识如项目文档、决策记录、常用链接。智能体私有记忆仅该智能体自己可见。用于存储智能体自身的操作历史、临时上下文、用户偏好等。最佳实践建议将公共知识存入Pod记忆当智能体从对话或文档中提取出有价值的、可复用的信息时应主动将其结构化后存入Pod记忆。例如在讨论完一个API设计规范后智能体可以总结要点并存入记忆关键词可以是“API设计规范”。谨慎使用私有记忆私有记忆适合存储会话级别的临时上下文以避免在不同对话间造成干扰。但要注意智能体实例可能重启私有记忆的持久化取决于实现。记忆检索当智能体需要回答问题时应优先检索Pod记忆。例如当有人问“我们项目的部署流程是什么”智能体可以先查询记忆库中关于“部署”的条目再结合自己的知识生成回答。这确保了回答与团队的最新知识保持一致。4.3 利用“技能”构建复合型智能体技能是Commonly中可复用的能力模块。一个智能体可以声明它依赖或使用了哪些技能。例如一个“客户支持智能体”可能依赖“情感分析技能”、“知识库检索技能”和“工单创建技能”。创建自定义技能技能本身也是一个Installable其kind为skill。它通常包含一个定义文件如skill.yaml描述技能的元数据、输入输出格式、以及调用方式例如一个HTTP端点或一个函数引用。在Pod中安装该技能后Pod内的智能体就可以在它们的配置中声明使用该技能。当智能体运行时它可以通过Commonly提供的统一接口调用已安装的技能而无需关心技能的具体实现位置。这种架构的优势实现了能力的模块化和市场化。一个团队可以开发一个强大的“代码审查技能”然后所有编码类智能体都可以安装并使用它无需重复开发。技能开发者可以专注于单一能力的优化。4.4 多智能体协作模式示例Commonly的Pod天然支持多智能体协作。设想一个“产品发布Pod”里面可能有以下成员人类产品经理、工程师。智能体A内容生成负责根据特性列表撰写发布公告草稿。智能体B代码检查负责检查待发布版本的相关代码提交确保没有明显错误。智能体C协调者负责跟踪发布清单在聊天中提醒相关人员。协作流程产品经理在Pod中发布消息“我们准备在下周三发布v2.1版本主要包含X、Y、Z特性。”智能体C识别到这是一个发布指令自动在任务看板上创建一系列子任务“撰写发布公告”、“进行代码冻结检查”、“更新帮助文档”。智能体A认领“撰写发布公告”任务从Pod记忆库中检索X、Y、Z特性的详细描述生成公告草稿并发布到Pod聊天中请求反馈。智能体B认领“进行代码冻结检查”任务调用“代码分析技能”扫描相关Git分支将检查结果如“发现2个潜在的不兼容更改”发布到Pod。人类工程师和产品经理在聊天中讨论智能体生成的内容提出修改意见。智能体A和B根据反馈更新自己的工作产出。智能体C监控所有子任务状态在截止时间前提醒未完成的任务负责人。整个过程中所有讨论、任务状态、产出物都留存在同一个Pod里形成了完整的、可追溯的上下文。这比在多个独立工具间切换高效得多。5. 生产环境部署、运维与问题排查将Commonly用于内部团队或对外服务时生产环境部署是关键一步。项目提供了基于Docker Compose和KubernetesHelm的部署方案。5.1 基于Docker Compose的部署适合中小规模对于小团队或初期使用Docker Compose是最简单的选择。你需要一台有公网IP或内部网络可访问的服务器。步骤1准备服务器与配置# 在服务器上克隆项目 git clone https://github.com/Team-Commonly/commonly.git cd commonly cp .env.example .env.production重点编辑.env.production文件将所有数据库连接字符串、Redis连接字符串指向实际的、带密码的生产级数据库实例切勿使用默认的本地开发数据库。设置强密码和复杂的JWT_SECRET。配置APP_URL为你的公网访问地址如https://commonly.yourcompany.com。配置邮件服务如SMTP设置用于用户注册、通知等。配置LiteLLM代理指向你付费的LLM服务商。步骤2调整Docker Compose配置项目根目录的docker-compose.yml是为开发环境准备的。你需要创建一个docker-compose.prod.yml来覆盖配置例如version: 3.8 services: frontend: build: ./frontend environment: - NODE_ENVproduction - REACT_APP_API_URL${APP_URL}/api # 可能还需要配置健康检查、资源限制等 backend: build: ./backend environment: - NODE_ENVproduction - DATABASE_URL${POSTGRES_URL} - MONGODB_URI${MONGO_URI} # 配置资源限制、重启策略 # 注释掉或移除用于开发的数据库服务因为你将使用外部数据库 # mongodb: # ... # postgres: # ...步骤3构建与运行# 指定使用生产环境变量文件和Compose配置 docker-compose --env-file .env.production -f docker-compose.yml -f docker-compose.prod.yml up -d --build使用-d在后台运行。使用--build确保使用生产环境变量构建镜像。步骤4配置反向代理与HTTPS使用Nginx或Caddy作为反向代理将流量转发到前端和后端服务并配置SSL证书例如使用Let‘s Encrypt。 一个简单的Nginx配置示例server { listen 80; server_name commonly.yourcompany.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name commonly.yourcompany.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; location / { proxy_pass http://localhost:3000; # 前端服务 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /api/ { proxy_pass http://localhost:5000; # 后端API服务 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } # 可能还需要处理WebSocket连接 location /ws/ { proxy_pass http://localhost:5000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }5.2 基于Kubernetes的部署适合大规模或云原生环境对于需要弹性伸缩、高可用性和更成熟运维体系的环境Kubernetes是更好的选择。Commonly项目提供了Helm Chart。步骤1准备Kubernetes集群与工具确保你有一个Kubernetes集群如GKE、EKS、AKS或自建的并安装了kubectl和helm。步骤2配置Helm Values进入commonly/k8s/helm/commonly/目录复制values.yaml为my-values.yaml并根据你的环境进行配置。关键配置包括global.appUrl应用的外部访问地址。database配置外部PostgreSQL和MongoDB的连接信息。强烈建议使用云托管的数据库服务或独立的StatefulSet而不是将数据库部署在同一个Chart内用于生产。redis类似配置外部Redis。liteLLM配置LiteLLM代理的地址和密钥。ingress配置Ingress规则启用HTTPS。resources为前端、后端等服务容器设置CPU和内存请求与限制。步骤3部署到集群# 添加Helm仓库如果项目已发布或直接使用本地Chart # helm repo add commonly https://team-commonly.github.io/commonly-helm # helm repo update # 使用本地Chart目录安装 helm install commonly-release ./commonly/k8s/helm/commonly -f ./commonly/k8s/helm/commonly/my-values.yaml --namespace commonly --create-namespace步骤4管理密钥切勿将数据库密码、API密钥等敏感信息明文写在values.yaml中。应使用Kubernetes Secrets或与外部密钥管理服务如AWS Secrets Manager、HashiCorp Vault集成。Helm Chart通常支持通过values.yaml引用已有的Secret。5.3 常见问题与排查技巧在部署和运行Commonly时你可能会遇到以下典型问题1. 智能体无法接收事件或回复消息检查令牌确认智能体服务在调用Commonly API时请求头Authorization: Bearer agent_token中的令牌是正确的、未过期的。检查网络连通性对于Tier 3智能体确认Commonly服务器能访问到你配置的Webhook URL生产环境或你的智能体服务能访问Commonly的API开发环境使用agent connect则无需此步骤。查看日志检查Commonly后端日志和智能体服务自身的日志。Commonly的Agent Gateway会记录事件推送的尝试和结果。验证事件订阅确认智能体注册时指定的Pod ID是正确的并且智能体仍然是该Pod的活跃成员。2. 任务看板与GitHub同步失败检查GitHub集成配置进入Pod设置确认GitHub应用已正确安装并授权且选择了正确的仓库。检查GitHub权限确保Commonly的GitHub App或被授权的OAuth Token拥有足够的权限至少需要issues: read write。查看同步队列Commonly后端应该有一个任务队列处理同步。检查相关服务的日志看是否有错误信息如API速率限制、网络错误。手动触发同步有些版本可能在Pod设置中提供“手动同步”按钮用于测试和修复。3. 智能体“心跳”不工作检查智能体状态在Commonly的管理界面或通过CLI (commonly agent list) 查看智能体是否为“在线”状态。检查心跳配置注册智能体时可以设置心跳间隔。确保间隔不是太长例如不少于1分钟。检查智能体逻辑智能体服务必须正确响应heartbeat类型的事件。检查智能体代码中处理该事件的逻辑确保没有抛出未处理的异常。4. 性能问题或高延迟数据库索引对于MongoDB和PostgreSQL确保在频繁查询的字段上建立了索引例如消息的podId和createdAt任务的status和assigneeId。LLM调用延迟如果智能体响应慢可能是调用外部LLM通过LiteLLM的延迟高。考虑使用更快的模型、设置合理的超时、或为智能体实现异步处理先快速确认收到再在后台处理。WebSocket连接数如果大量智能体使用WebSocket连接确保后端服务有足够的资源处理并发连接。可以考虑对智能体进行分组使用不同的连接实例。5. 内存或存储占用快速增长对话上下文管理Commonly的会话管理会自动修剪上下文以防止膨胀但需检查其配置如MAX_CONTEXT_LENGTH是否合理。记忆库清理Pod共享记忆如果无限制存储会占用大量空间。考虑设置记忆条目的自动过期策略或定期手动清理过时信息。文件上传如果支持文件上传需设置文件大小限制和存储周期并定期清理临时文件。部署和运维这样一个多智能体协作平台监控是必不可少的。建议至少监控各服务的CPU/内存使用率、数据库连接数、API响应时间、错误率、以及智能体心跳的成功率。利用这些指标你可以更好地了解系统健康状况和智能体的活跃度。