1. 项目概述一个能带“同事”的AI开发工具箱如果你用过Cursor、Claude Code这类AI编程工具肯定有过这样的体验你让它帮你写一个完整的全栈应用从数据库设计到前端页面。它一开始可能干得不错但写着写着就开始“精神分裂”——前脚刚用React写了个组件后脚可能就把状态管理逻辑塞进了同一个文件或者把本应放在后端的认证逻辑混进了前端代码。这不是AI笨而是让它一个“大脑”同时处理架构、前后端、数据库、安全等所有领域的知识负担太重难免顾此失彼。oh-my-agent简称OMA解决的就是这个问题。它的核心思想很简单让专业的人做专业的事。它不是一个单一的、试图理解一切的“超级AI”而是一个可移植的多智能体协作框架。你可以把它想象成一个为你配备的微型开发团队有专门负责拆解需求的“项目经理”oma-pm有精通React和Tailwind的“前端工程师”oma-frontend有擅长设计API和数据库的“后端架构师”oma-backend和oma-db还有一丝不苟的“测试工程师”oma-qa和“运维专家”oma-tf-infra。这个团队的所有“成员”——也就是各种专业智能体Agent——都封装在一个名为.agents/的目录里。这个目录可以跟着你的项目代码一起走放进Git仓库。这意味着无论你是在Cursor里、Claude Code中还是直接在终端使用Codex CLI只要你把这个目录放到项目根目录你就拥有了一个随时待命、分工明确的AI开发团队。这种与项目绑定而非与特定IDE绑定的设计是OMA“可移植性”的精髓也是它区别于其他单点AI工具的最大优势。2. 核心设计思路从“万能助手”到“专业团队”2.1 角色化智能体告别“精神分裂”的AI传统AI编码助手就像一个全栈通才什么都要懂一点但深度有限。当你提出一个复杂需求时它需要在同一个上下文里不断切换思维模式这极易导致上下文污染和逻辑混乱。OMA的设计哲学是解耦与专精。每个智能体都被设计成一个高度专业化的角色拥有自己独立的“知识库”技能定义和“工作流程”检查清单。例如oma-architecture它的思维模式是权衡利弊。当被激活时它不会直接写代码而是思考“微服务 vs 单体”、“SQL vs NoSQL”、“缓存策略选型”这类架构级问题并可能生成类似ADR架构决策记录的文档。oma-qa它的核心是“挑刺”。它的技能列表里写满了OWASP Top 10安全漏洞检查项、Lighthouse性能审计要点、WCAG无障碍访问标准。它看待代码的视角和oma-frontend完全不同。oma-db它只关心数据。给定需求它会专注于设计规范的ER图、编写可回滚的迁移脚本、考虑索引优化和向量数据库的特殊需求。这种角色化设计带来了两个直接好处更高的输出质量和更低的Token消耗。因为每个智能体只需加载与自身领域高度相关的指令和上下文无需携带无关的“知识包袱”在同样长度的上下文窗口内它能进行更深度的思考。2.2 双层技能系统效率与灵活性的平衡OMA在实现智能体专精时采用了一个非常巧妙的两层技能设计这是其“Token高效”宣称背后的技术关键。核心技能层Core Skills位于.agents/skills/目录下。这里定义了每个智能体的“宪法”和“核心能力”。比如oma-backend的核心技能文件里会写明它的职责范围“负责构建RESTful或GraphQL API”、首选技术栈“Python/Node.js/Rust”、代码规范“必须包含错误处理和输入验证”等原则性、通用性的指令。这部分内容相对稳定是智能体的“人格”基础。供应商原生层Vendor-Native Agents当你在特定IDE如Claude Code中使用OMA时CLI工具通过oma link命令会根据核心技能自动生成一份针对该IDE优化过的智能体定义文件。例如为Claude Code生成.claude/agents/oma-backend.md。这个文件是核心技能在特定平台下的“翻译”和“实例化”格式、提示词结构都完全适配目标IDE的原生语法从而获得最好的兼容性和性能。为什么这么设计假设没有这个分层每次调用智能体都需要把完整的核心技能描述作为提示词发送这会产生大量重复的Token开销。而分层之后在Claude Code中工作时IDE直接读取的是精简、优化过的.claude/agents/文件。只有当进行跨供应商调度比如在终端用OMA CLI协调一个Claude智能体和一个Gemini智能体时系统才会回退到使用核心技能层来生成统一的指令。实测下来这种设计大约能节省70%-75%的冗余Token让宝贵的上下文窗口更多地用于任务本身而不是重复的“角色介绍”。2.3 工作流与编排智能体如何协同工作智能体各司其职是基础但让它们有序协作才能完成复杂任务。OMA提供了两种主要的协作模式对话驱动和命令驱动。对话驱动自然语言触发这是最“无感”的使用方式。你只需要像平时一样跟AI聊天。OMA内置了一个意图识别层能理解11种语言中的关键词。例如你在描述需求时说“我们需要一个用户认证系统架构上要考虑可扩展性之后让前端做个登录页最后别忘了安全评审。” 这句话里的“架构”、“前端”、“安全评审”会被自动识别从而在后台依次激活oma-architecture、oma-frontend和oma-qa智能体参与对话或执行任务。你感觉是在和一个AI对话背后却是一个团队在接力服务。命令驱动结构化工作流对于有明确流程的项目OMA提供了一系列类似Slack斜杠命令的工作流。这就像你为项目启动了一个标准化的流水线/plan呼叫PM智能体将模糊的需求拆解成具体的、可执行的任务清单。/work根据PM的清单按顺序调度相关智能体如后端、前端、数据库逐步执行。/orchestrate更高级的并行编排。例如你可以让后端智能体设计API的同时让前端智能体并行设计UI组件前提是两者依赖的接口契约由PM或架构师提前定义已明确。/ultrawork这是OMA的“旗舰”工作流包含5个阶段和多达11个质量门禁。从需求澄清、架构评审到编码、多轮测试单元、集成、安全、性能再到最终提交前的SCM软件配置管理检查它模拟了一个严谨的企业级开发流程确保产出物的高质量。3. 核心智能体详解与实战配置3.1 架构师与PM项目的“大脑”与“调度中心”一个项目的成功始于清晰的蓝图和合理的计划。oma-architecture和oma-pm就是为你绘制这张蓝图的核心。oma-architecture实战要点 这个智能体不会产出任何一行业务代码。它的价值在于提前规避技术风险。当你向它描述一个系统例如“一个支持多租户的SaaS内容管理平台”时它会从以下几个维度发起追问或给出分析边界与上下文明确系统与外部系统的界限定义核心领域。架构风格会分析单体、微服务、事件驱动等模式的利弊并结合你的团队规模、部署环境给出建议。关键技术选型数据库关系型 vs 文档型 vs 图数据库、缓存策略Redis位置、缓存穿透/击穿/雪崩应对、消息队列选型等。非功能性需求它会特别关注可扩展性、可用性、可维护性和安全性如数据隔离如何实现。实操心得不要一次性给它过于庞大的需求。最好是分阶段咨询。比如先问“整体架构风格选择”得到结论后再针对性地问“鉴权与多租户数据隔离的详细设计”。这样交互更高效输出也更聚焦。oma-pm实战要点 PM智能体是将产品需求翻译成技术任务的关键。它的输出通常是一个结构化的任务列表每个任务都包含Who哪个智能体负责、What具体做什么、Input依赖什么、Output产出物是什么。 例如对于“构建用户认证系统”的需求oma-pm可能输出任务设计用户表及认证流程API接口。负责人oma-backend输入用户故事注册、登录、JWT刷新输出auth_schema.sqlauth_api_spec.yamluser_controller.py任务基于API Spec实现前端登录/注册页面。负责人oma-frontend输入auth_api_spec.yaml输出LoginForm.tsxRegisterForm.tsx 相关的状态管理逻辑任务对认证API进行安全审计。负责人oma-qa输入auth_api_spec.yamluser_controller.py输出安全审计报告检查SQL注入、XSS、JWT实现安全性等。这个任务列表是后续/work或/orchestrate工作流执行的直接依据。3.2 前后端与数据库核心领域的“执行者”oma-frontend深度解析 这个智能体是目前社区中认为“手感”最好的之一因为它对现代前端技术栈的把握非常精准。它默认且深度集成了以下技术React/Next.js不仅会写组件更懂App Router与Pages Router的差异、服务端组件RSC的应用场景、以及如何组织项目结构。TypeScript类型定义严谨会充分利用泛型、Utility Types来提升代码健壮性。Tailwind CSS v4熟悉最新的v4特性能高效实现响应式设计和精细的样式控制。shadcn/ui倾向于使用这个底层组件库来构建可访问的UI而不是直接生成复杂的自定义CSS。注意事项虽然它很强但你需要明确设计约束。比如如果你不想用shadcn/ui需要在对话开始时明确告知“请使用纯Tailwind实现不使用任何组件库”。否则它可能会默认采用自己最熟悉的模式。oma-backend与oma-db的协作 这两个智能体通常结对出现。oma-backend专注于业务逻辑层和控制层而oma-db专注于数据持久层。典型工作流当你要求“创建一个博客发布系统”时oma-db会首先行动设计出包含posts、users、tags、comments的表结构并考虑索引如在posts(published_at)上创建降序索引和约束外键、非空。然后oma-backend会基于这个Schema创建对应的ORM模型如Prisma、SQLAlchemy和CRUD API端点。高级特性oma-db对向量数据库如PgVector, Pinecone也有支持这意味着你可以让它设计AI应用所需的数据存储方案。3.3 质量守护神QA与Debugoma-qa你的自动化安全与质量审计员。 它的检查清单是其核心资产。当你把一段代码尤其是后端API和前端表单交给它评审时它会系统性地扫描安全检查输入验证、SQL/NoSQL注入、XSS、CSRF防护、敏感信息泄露、JWT实现缺陷等。性能分析潜在的N1查询问题、内存泄漏、未优化的循环、大文件处理等。无障碍访问审查前端组件的ARIA属性、颜色对比度、键盘导航支持等。 它的输出不是简单的“看起来不错”而是一份带有严重性分级高危、中危、低危的问题列表和修复建议。oma-debug结构化的问题诊断专家。 当你的程序出现bug时不要只是把错误日志丢给AI。激活oma-debug它会引导你进行结构化排查现象定位错误发生的环境、触发条件、报错信息全文。根因假设它会根据现象提出几种最可能的假设例如空指针、异步操作未等待、环境变量缺失。验证与排查它会给出具体的验证步骤比如“在XX行添加console.log查看变量值”或者“检查YYY配置文件是否存在”。修复与回归提供修复方案并建议添加相应的单元测试或集成测试以防止回归。 这个过程比单纯让AI“猜”错误原因要可靠得多因为它模拟了资深工程师的调试思维。4. 从零开始安装、配置与第一个工作流4.1 环境准备与一键安装OMA的运行依赖于两个现代JavaScript运行时Bun和UVPython包管理器。前者用于执行OMA自身的CLI后者用于管理可能用到的Python工具链部分智能体如oma-tf-infra会用到。对于macOS和Linux用户最快捷的方式是使用官方提供的一键安装脚本curl -fsSL https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.sh | bash这个脚本会自动检测并安装缺失的Bun和UV然后全局安装oh-my-agentCLI。安装完成后在终端输入oma即可验证。对于Windows用户需要手动完成前置步骤安装Bun访问 bun.sh 下载安装程序。安装UV在PowerShell中运行pip install uv或使用其他包管理器。安装OMAbun install --global oh-my-agent踩坑记录在一台全新的Linux服务器上执行一键脚本时可能会因为缺少curl或wget而失败。最稳妥的方法是先手动安装Bun和UV再通过Bun安装OMA。另外确保你的网络环境能够顺畅访问GitHub和npm仓库。4.2 项目初始化与预设选择安装好CLI后进入你的项目目录或新建一个运行初始化命令oma init这时CLI会引导你选择一个预设Preset。这个选择至关重要它决定了哪些智能体会被初始化到你的.agents/目录中直接影响后续可用的功能。预设包含的智能体团队适用场景✨ All全部智能体探索所有功能或不确定项目方向 Fullstack架构、前后端、DB、PM、QA、Debug、Brainstorm、SCM全栈Web应用开发最常用 Frontend架构、前端、PM、QA、Debug、Brainstorm、SCM纯前端项目或前端主导的重构⚙️ Backend架构、后端、DB、PM、QA、Debug、Brainstorm、SCMAPI服务、微服务开发 Mobile架构、移动端、PM、QA、Debug、Brainstorm、SCM使用Flutter的跨平台移动应用 DevOps架构、Terraform基础设施、开发工作流、PM、QA、Debug、Brainstorm、SCM基础设施即代码、CI/CD流水线搭建如何选择如果你是全栈开发者正在启动一个全新的Web项目Fullstack预设是不二之选它提供了从设计到部署的完整工具链。如果你主要做前端但需要与后端API协作Frontend预设足够其中的oma-architecture和oma-pm能帮你更好地理解与规划对接工作。All预设虽然全面但也会初始化一些你可能用不到的智能体如oma-hwp用于处理韩文文档会略微增加.agents/目录的体积。建议按需选择。初始化完成后你的项目根目录下会出现一个.agents/文件夹里面就是你的专属AI团队。同时如果你在支持原生集成的IDE如Cursor中运行oma link命令它会在IDE的配置目录如.cursor/agents中创建对应的智能体快捷方式实现无缝调用。4.3 实战构建一个待办应用TODO App让我们用一个经典案例来串联整个工作流。目标构建一个带有用户认证的TODO应用。第1步需求澄清与规划在IDE的聊天框中直接输入我需要一个带用户认证的TODO应用。用户能注册、登录登录后可以创建、查看、完成和删除自己的待办事项。由于语句中包含了“应用”和“认证”等关键词OMA可能会自动建议或你可以手动触发/plan工作流。oma-pm智能体会介入将需求拆解。你可能会得到类似这样的任务列表简化版设计数据库Schema用户表、待办事项表。实现用户认证相关API注册、登录、登出、刷新令牌。实现待办事项的CRUD API。实现前端用户界面登录/注册页、待办事项列表页。进行安全与代码质量评审。第2步架构与数据库设计针对任务1你可以说“请为这个TODO应用设计数据库Schema。” 这会激活oma-db智能体。它会输出一个规范的SQL创建语句包含users表和todos表并建立外键关联同时考虑索引如在todos(user_id)上建索引。第3步后端API实现现在将oma-db输出的Schema和任务2、3交给oma-backend。你可以这样引导 “基于以下Schema使用Node.js (Express) 和 Prisma ORM 实现用户认证和待办事项的RESTful API。请包含输入验证、错误处理和JWT认证中间件。”oma-backend会生成完整的prisma/schema.prisma文件、auth.js和todos.js路由控制器以及一个配置了认证中间件的app.js主文件。第4步前端界面实现将上一步生成的API接口文档或直接告诉它API的端点地址和格式交给oma-frontend “请使用Next.js 15 (App Router)、TypeScript和Tailwind CSS为上述API实现前端界面。需要登录/注册页面以及一个登录后的主页面展示待办事项列表支持增删改查操作。” 它会生成相应的React组件、页面文件并处理好状态管理可能会建议使用Zustand或Context API和API调用逻辑。第5步质量评审在代码编写完毕后你可以将关键文件如认证API、前端表单组件提交给oma-qa进行评审。它会检查常见的安全漏洞比如密码是否以明文传输、JWT令牌是否安全存储、前端有无XSS风险等。第6步集成与调试如果在集成前后端时遇到问题比如CORS错误或API调用失败激活oma-debug。它会引导你检查网络请求、服务器日志、环境配置快速定位问题。第7步代码管理最后可以使用oma-scm来帮助你生成符合Conventional Commits规范的提交信息管理分支策略。整个过程中你无需手动切换不同的AI模型或编写复杂的提示词OMA的智能体团队在后台自动协作而你始终在一个连贯的对话上下文中进行。5. 高级特性与深度使用技巧5.1 多供应商混用与编排OMA的强大之处在于它不绑定于单一的AI模型供应商。你可以在一个项目里让不同的智能体使用不同供应商的最强模型。配置原理 在.agents/skills/oma-orchestrator/config/cli-config.yaml文件中你可以为每个智能体指定默认的AI供应商和模型。例如agents: oma-architecture: vendor: claude # 使用Claude模型 model: claude-3-5-sonnet-20241022 oma-frontend: vendor: gemini # 前端任务使用Gemini model: gemini-2.0-flash-exp oma-qa: vendor: openai # 安全评审使用OpenAI model: gpt-4ooma-orchestrator的威力 这个智能体是并行执行的指挥官。通过CLI你可以发起并行任务oma agent:parallel -i backend:实现用户API frontend:实现登录UI -s session_01这条命令会同时启动oma-backend和oma-frontend智能体分别处理各自的任务并将输出汇总到session_01这个会话中。这极大地加快了开发速度尤其适用于前后端分离、任务间依赖清晰的项目阶段。5.2 自定义智能体与技能扩展OMA的.agents/目录结构是开放的这意味着你可以对其进行深度定制。自定义技能 如果你觉得默认的oma-backend总是用Express而你的团队更倾向于Fastify或NestJS你可以修改.agents/skills/oma-backend/skill.md文件。在这个文件里你可以重写它的“职责描述”和“偏好设置”例如将“首选Node.js框架”从Express改为Fastify并附上你团队的代码规范链接。创建专属智能体 你甚至可以创建全新的智能体。假设你的项目大量使用GraphQL你可以创建一个oma-graphql智能体。在.agents/skills/下创建oma-graphql文件夹。在里面创建skill.md详细定义这个智能体的角色“GraphQL API专家”、职责“设计Schema、解析器、优化DataLoader、处理N1问题”、技术栈“Apollo Server, Pothos, GraphQL Codegen”。运行oma link命令为你的IDE生成对应的原生智能体文件。现在你就可以在对话中通过关键词“graphql”来调用它或者在/plan工作流中让它负责GraphQL相关的任务。5.3 可观测性与调试当多个智能体并行工作时如何了解它们的状态和进度OMA提供了两种方式终端仪表盘运行oma dashboard命令会在终端打开一个实时监控界面。你可以看到各个智能体的活动状态、最近执行的任务、Token消耗估算等信息。这对于调试复杂的并行工作流非常有用。Web仪表盘OMA还支持启动一个本地Web服务器提供更丰富的图形化监控界面通常通过oma dashboard --web启动。你可以更直观地看到工作流的执行图谱、智能体间的调用关系。健康检查在任何时候你都可以运行oma doctor命令。它会检查你的.agents/目录结构是否完整、CLI工具版本、依赖的运行时Bun, UV状态并给出修复建议是排查环境问题的第一选择。6. 常见问题与避坑指南在实际使用中我遇到并总结了一些典型问题希望能帮你少走弯路。6.1 安装与环境问题问题1一键安装脚本在特定Linux发行版上失败。原因脚本可能依赖的包管理器如apt,yum或工具curl,git未安装。解决先手动安装基础工具包再分别安装Bun和UV。# Ubuntu/Debian sudo apt update sudo apt install -y curl git # 然后参考Bun和UV官方文档安装问题2在IDE如Cursor中无法识别OMA智能体。原因未在项目根目录运行oma link命令或者IDE的智能体目录路径未正确配置。解决确保在项目根目录有.agents/文件夹执行oma link。检查你的IDE设置。例如在Cursor中确认设置里的“Agent Directories”包含了~/.cursor/agents这是oma link默认生成的路径。重启IDE。6.2 使用与工作流问题问题3智能体没有按预期被触发或者输出了无关内容。原因意图识别可能被干扰或者智能体的核心技能定义与当前任务不匹配。解决使用明确指令如果自动识别不准直接使用斜杠命令如/work来强制启动结构化工作流。检查上下文确保你的对话历史清晰。有时之前的对话内容会干扰后续的智能体判断。可以尝试开启一个新的聊天会话。精简需求描述过于冗长或模糊的描述可能导致智能体困惑。尝试用更结构化、分点的方式描述需求。问题4/orchestrate并行任务时智能体间出现协作问题如前端等后端接口。原因并行执行的前提是任务间依赖已明确。如果前端依赖的API契约接口规范尚未由后端或PM定义并行就会出问题。解决先定义契约在并行执行前务必先使用/plan或单独与oma-pm/oma-architecture沟通明确产出物之间的接口如API的URL、请求/响应格式。将这个契约文档作为两个并行任务的共同输入。使用同步点对于强依赖的任务不要强行并行。使用/work进行顺序执行更可靠。问题5生成的代码风格或技术栈不符合团队要求。原因智能体基于其默认技能生成代码。解决定制化是必须的。花时间修改对应智能体的skill.md文件将你团队的编码规范、首选库、项目结构范例写进去。这是将OMA从“好用的工具”升级为“得力的团队成员”的关键一步。6.3 性能与成本优化问题6处理复杂任务时响应慢或提示“上下文过长”。原因智能体加载了过长的技能描述和历史对话。解决利用分层技能确保你主要在支持原生集成的IDE中使用这样调用的是精简后的供应商原生文件Token消耗最低。分而治之将大任务拆分成多个子任务分别在不同的聊天会话中完成。使用oma-recap智能体来总结之前的会话然后将摘要而非完整历史带入新会话。清理历史定期开始新的聊天会话避免过长的对话历史累积。问题7如何控制使用不同AI模型带来的API成本原因在cli-config.yaml中配置了多个付费模型。解决统一供应商在项目初期或预算有限时可以为所有智能体配置同一个供应商的性价比模型例如全部使用Claude Haiku或Gemini Flash。按需分配只为计算密集型或要求极高的智能体如oma-architecture,oma-qa配置高级模型如Claude Sonnet, GPT-4为执行类智能体如oma-frontend,oma-backend配置轻量模型。监控用量关注各AI供应商控制台的使用量和费用报表及时调整配置。OMA不是一个“魔法黑箱”而是一个高度可配置、遵循明确规则的系统。理解其背后“角色化智能体”和“双层技能”的设计理念积极进行定制才能让它真正融入你的工作流成为提升研发效能和代码质量的强大助力。从用一个简单的/plan开始感受这个“AI团队”如何有条不紊地将你的想法一步步变为现实这个过程本身就是一种全新的、高效的开发体验。