1. 项目概述：从单点助手到结构化工程工作流

如果你和我一样，日常重度依赖 Gemini CLI 来辅助编码、文档撰写或者项目规划，那你肯定也遇到过类似的瓶颈：当任务稍微复杂一点，需要规划、执行、评审多个环节时，单次对话的上下文很快就会变得混乱不堪。规划时的假设，执行时被遗忘；评审发现的问题，又得从头解释一遍。整个过程就像在一条拥挤的单行道上反复掉头，效率低下，还容易出错。

oh-my-gemini-cli （简称 OmG）正是为了解决这个问题而生。它不是一个全新的 AI 工具，而是 Gemini CLI 的一个官方扩展（Extension）。它的核心思想，是把原本单一、线性的 AI 对话，升级为一个由多个“角色”（Agent）协同工作的结构化工程工作流。你可以把它想象成一个微型的、AI 驱动的项目团队：有负责规划的“产品经理”（ omg-planner ），有专注实现的“工程师”（ omg-executor ），还有严格把关的“测试与评审”（ omg-reviewer , omg-verifier ）。OmG 通过一套清晰的命令和状态管理机制，让这些角色各司其职，有序推进任务。

这个项目最初源于一个有趣的观察：Claude Code 的核心竞争力并非仅仅是其强大的模型，更在于其精心设计的“工作台”本身。OmG 的创建者受到启发，思考“如果为 Gemini CLI 也装上这样一个工作台会怎样？”。于是，OmG 应运而生，它通过引入“上下文工程”（Context-engineering）驱动的多智能体工作流，将 Gemini CLI 从一个优秀的单会话助手，转变为一个能够处理复杂、多阶段任务的工程协作平台。

对于开发者、技术写作者或任何需要处理复杂逻辑任务的用户来说，OmG 的价值在于它提供了一种“可重复、可审计、可管理”的工作方式。它通过 /omg:workspace 和 /omg:taskboard 管理任务状态，用 /omg:team-assemble 动态组建团队，并通过 team-plan -> team-exec -> team-verify -> team-fix 的循环，确保交付物的质量。接下来，我将带你深入拆解它的设计思路、核心用法以及我在实际使用中积累的一系列实战技巧。

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

2.1 为什么是“多智能体”而非“复杂提示词”？

在接触 OmG 之前，很多人（包括我自己）尝试解决复杂任务的方式，是编写越来越长、越来越精细的提示词（Prompt），试图在一个对话中让模型扮演所有角色。这种方法很快会碰到天花板：上下文长度限制、角色指令冲突、以及难以维护的历史对话混乱。

OmG 选择了一条不同的路： 角色分离与状态外置 。

• 角色分离 ：OmG 预定义了十多个具有明确职责的智能体（Agent），如 omg-architect （架构师）、 omg-planner （规划师）、 omg-executor （执行者）等。每个智能体都有其专属的提示词（位于 agents/ 目录），专注于一个特定的任务领域。当需要执行某项任务时，OmG 会调用最合适的智能体，并为其提供精确的上下文。
• 状态外置 ：OmG 不依赖冗长的对话历史来维持项目状态。相反，它将关键状态（如任务清单、工作区配置、检查点）持久化到项目目录下的 .omg/state/ 文件中。这带来了几个巨大优势：
  1. 上下文精简 ：每次与智能体交互，只需传递与当前任务最相关的状态片段，极大节省了 Token。
  2. 状态持久化 ：即使关闭 CLI 会话，项目进度依然得以保存，下次可以无缝衔接。
  3. 可审计性 ：所有决策、任务状态变更都有文件记录，便于回顾和调试。

这种设计哲学的本质，是将 AI 协作“工程化”。它借鉴了软件工程中的模块化、关注点分离和状态管理思想，使得利用 AI 完成复杂任务的过程变得可预测、可管理。

2.2 核心组件如何协同工作？

OmG 的扩展结构清晰，每个目录都有其明确的职责：

1. GEMINI.md 与 context/ ：这是项目的“宪法”和“知识库”。 GEMINI.md 定义了最高级别的行为准则和系统约束。 context/ 目录下的文件（如 omg-core.md ）则提供了更具体的操作指南和共享上下文。它们共同构成了智能体行为的稳定基础，避免了每次都需要重复灌输基本原则。
2. agents/ ：这里是所有智能体的“大脑”。每个 .md 文件定义了一个角色的核心指令、职责边界和输出格式。例如， omg-executor.md 会强调“一次只修改一个任务”、“产出可运行的代码”，而 omg-reviewer.md 则聚焦于“代码风格”、“潜在缺陷”和“与规划的符合度”。
3. commands/ ：所有以 /omg: 开头的命令的实现逻辑都存放在这里（ commands/omg/*.toml ）。这些命令是用户与 OmG 工作流交互的主要接口，负责解析参数、调用智能体、更新状态文件。
4. skills/ ：保留的深度工作技能（如 $plan , $execute ）。这些是可以在 Gemini CLI 中直接调用的“快捷方式”，它们封装了常用的复杂操作。值得注意的是，OmG 特意将技能集保持得小而精，以减少扩展加载时的元数据开销。
5. .omg/state/ ：这是 OmG 的“工作记忆”中心。所有运行时状态都存储于此：
   • workspace.json : 定义主工作根目录以及可能的并行工作路径（lanes）。
   • taskboard.md : 任务看板，记录所有任务的 ID、状态、负责人、依赖关系和验证证据。
   • session-lock.json : 会话锁，确保在共享工作流状态下，同一时间只有一个“编排会话”可以写入，防止状态冲突。
   • interviews/ : 存储深度需求访谈的会话状态。
   • sessions/ : 非主编排会话的本地草稿存储位置。

实操心得：理解状态文件是高效使用 OmG 的关键 。我经常在开始一个复杂任务前，先手动查看或编辑 taskboard.md ，以确保我对任务分解的理解与系统一致。在遇到问题时，检查 .omg/state/ 下的相关文件往往是最快的调试手段。

3. 完整工作流实战：从零构建一个微服务模块

理论说得再多，不如动手实践。让我们以一个具体的场景为例： 为一个现有的 Node.js 后端项目添加一个用户认证微服务模块 。我们将完整走一遍 OmG 的标准化工作流。

3.1 环境准备与项目初始化

首先，确保你已安装最新版的 Gemini CLI，并且拥有有效的 API 密钥。然后，在终端中安装 OmG 扩展：

# 安装 OmG 扩展
gemini extensions install https://github.com/Joonghyun-Lee-Frieren/oh-my-gemini-cli

# 验证安装
gemini extensions list
# 你应该能看到 `oh-my-gemini-cli` 在列表中

# 进入你的项目目录
cd /path/to/your/nodejs-project

# 启动 Gemini CLI 交互模式
gemini

进入交互模式后，首先运行一个烟雾测试，确认 OmG 已正确加载：

/omg:status

如果一切正常，你会看到 OmG 的欢迎信息、当前状态概览以及可用的命令列表。

3.2 阶段一：需求澄清与规划 ( /omg:intent -> /omg:team-plan )

面对一个模糊的需求（“添加用户认证”），直接开始编码是危险的。OmG 建议我们从意图分析开始。

/omg:intent 为我们的Node.js后端项目添加一个用户认证微服务模块，支持JWT令牌、密码哈希存储和基本的角色权限控制。

/omg:intent 命令会分析你的请求，将其分类并路由到合适的工作流阶段。对于这种明显的“构建类”任务，它通常会建议进入团队规划流程。

接下来，我们为这个任务初始化一个工作区，并开始规划：

/omg:workspace set .
/omg:team-assemble “实现用户认证微服务模块”

/omg:team-assemble 是 OmG 工作流中非常强大的一环。它会根据任务描述，动态提议一个最适合的“团队”组成。对于“认证微服务”这种涉及架构、产品定义和实现的任务，它很可能会提议包含 omg-architect （架构师）、 omg-planner （规划师）、 omg-product （产品经理）和 omg-executor （执行者）等角色。

系统会输出一个团队提案，并等待你的批准：

Proposed team for “实现用户认证微服务模块”:
- omg-architect (系统边界与接口设计)
- omg-planner (任务分解与排序)
- omg-product (验收标准与范围锁定)
- omg-executor (核心实现)
- omg-reviewer (代码审查)

Proceed with this team? (yes/no)

输入 yes 或 approve 批准。批准后，OmG 会自动触发 team-plan 阶段。

在 team-plan 阶段， omg-planner 会主导工作，与其他智能体协作，产出任务分解图。这个过程是自动的，你可以在终端看到它们的“讨论”和输出。最终，你会得到一个结构化的计划，可能包括：

• 里程碑1 ：设计认证服务API接口（RESTful endpoints）。
• 里程碑2 ：实现用户模型与数据库模式（使用Prisma/SQL）。
• 里程碑3 ：实现密码哈希与JWT生成/验证逻辑。
• 里程碑4 ：实现基于角色的权限中间件。
• 里程碑5 ：编写单元与集成测试。
• 风险 ：JWT密钥管理、密码哈希算法选择、与现有用户模型的集成。

同时， .omg/state/taskboard.md 文件会被创建并填充初始任务。你可以随时用 /omg:taskboard 命令查看。

3.3 阶段二：定义产品需求 ( /omg:team-prd )

规划完成后， omg-product 智能体会自动接手，执行 team-prd 阶段。这个阶段的目标是将相对技术性的规划，转化为可衡量的、非技术背景利益相关者也能理解的“产品需求文档”式输出。

它会明确：

• 验收标准（Acceptance Criteria） ：例如，“POST /api/auth/register 接口应能成功创建用户，并返回201状态码和JWT令牌”，“用户密码必须以 bcrypt 哈希存储，明文绝不落盘”。
• 非目标（Non-goals） ：例如，“本次迭代不实现OAuth第三方登录”，“不提供管理员用户管理界面”。
• 约束（Constraints） ：例如，“必须与现有的 PostgreSQL 数据库集成”，“API 响应格式需遵循项目既定的 JSON 规范”。

这个阶段产出的 PRD 是后续 team-verify （验证）阶段的唯一标准。明确它，能极大减少后续的返工和歧义。

3.4 阶段三：循环执行与验证 ( team-exec -> team-verify -> team-fix )

这是核心的开发循环。OmG 的 team-exec 命令不会一次性完成所有任务，而是采用“切片执行”策略。

1. 执行切片 ：运行 /omg:team-exec 。 omg-director （导演）会从 taskboard.md 中挑选优先级最高且处于“ready”状态的任务切片，分配给 omg-executor 执行。例如，第一个切片可能是“创建 auth 目录结构，初始化 package.json 和 index.js ”。
2. 智能体工作 ： omg-executor 会获得该任务的详细上下文（来自 taskboard.md 和项目文件），然后开始编写代码。你会在终端看到它的思考过程和代码输出。
3. 自动验证 ：一个执行切片完成后， omg-director 会自动调用 team-verify 。在这个阶段， omg-reviewer 和 omg-verifier 会登场。
   • omg-reviewer ：检查代码质量、风格、潜在 bug。
   • omg-verifier ：严格对照 team-prd 阶段定义的验收标准，验证功能是否达标。
4. 问题处理 ：如果验证失败， team-verify 会生成一个优先级排序的“修复待办列表”。此时， omg-director 会调用 team-fix ，可能指派 omg-debugger 分析根本原因，然后再次由 omg-executor 进行修复。
5. 循环推进 ：验证通过的任务会被标记为“verified”。然后， /omg:team-exec 会自动选取下一个就绪任务切片，重复此循环。

你可以通过 /omg:status 随时查看整体进度，或通过 /omg:taskboard 查看每个任务的具体状态。

注意事项： team-exec 的“一次一任务”特性 。这是 OmG 保证可控性的关键设计。不要指望它一次写完整个服务。这种小步快跑、即时验证的方式，虽然看起来步骤多，但实际成功率更高，也更容易定位问题。如果任务卡住，检查 taskboard.md 中当前任务的状态和描述是否清晰。

3.5 阶段四：交付与收尾

当所有任务在 taskboard.md 中都标记为“verified”后，工作流即告完成。 omg-director 会调用 omg-editor 来整理最终交付物，可能生成一份汇总的 README 或变更日志。

在整个过程中，你可以使用 /omg:checkpoint 来保存进度。这个命令会创建一个紧凑的检查点文件，并给出恢复提示。这对于需要中断工作（如下班）的场景非常有用。恢复时，只需根据提示加载检查点，OmG 就能回到之前的状态。

4. 高级特性与实战技巧

4.1 工作区（Workspace）与多任务并行

OmG 的 /omg:workspace 命令是管理复杂、多模块项目的利器。假设你的项目有 backend/ 和 frontend/ 两个目录，你可以这样设置：

/omg:workspace set .  # 设置当前目录为主根目录
/omg:workspace add ./backend omg-executor  # 添加后端路径，指定默认执行代理
/omg:workspace add ./frontend omg-executor  # 添加前端路径
/omg:workspace audit  # 审计所有路径的“健康度”（如Git状态）

这样，在执行 team-exec 时，OmG 能理解不同任务属于不同的代码路径。 /omg:workspace audit 命令尤其有用，它能在并行执行或评审前，检查各个路径是否有未提交的更改、是否在正确的分支上，避免工作互相覆盖。

4.2 通知（Notify）与无人值守运行

对于需要长时间运行的任务（如重构一个大型目录），你可以利用 OmG 的通知系统，在关键节点获得提醒。

/omg:notify profile watchdog
/omg:notify channel desktop,terminal-bell

这将启用“看门狗”模式，OmG 会在需要批准、验证失败、遇到阻塞或会话停止时，通过桌面通知和终端响铃提醒你。结合 /omg:autopilot 模式，你可以在启动一个复杂任务后暂时离开，让 OmG 自主运行，并在关键时刻通知你介入决策。

4.3 模型策略与成本控制 ( /omg:model )

OmG 内置了智能的模型路由策略，这直接关系到使用成本和效果。通过 /omg:model 命令可以查看和调整：

• balanced (默认) ：这是最推荐的策略。OmG 会根据任务类型自动选择模型：
  • 规划/评审 ( omg-planner , omg-reviewer 等)：使用 gemini-3.1-pro-preview ，追求深度思考和高质量分析。
  • 执行 ( omg-executor )：使用 gemini-3-flash-preview ，在保证代码生成质量的同时，追求速度和较低成本。
  • 快速编辑 ( omg-quick )：使用 gemini-3.1-flash-lite-preview ，用于小修小改，成本最低。
• auto ：将模型选择完全交给 Gemini CLI 运行时决定。
• custom ：允许你为每个智能体单独指定模型。

我的经验是，对于绝大多数开发任务，保持 balanced 策略是最优的。 它很好地在质量、速度和成本之间取得了平衡。只有在你有非常明确的偏好或预算限制时，才需要切换到 custom 模式进行微调。

4.4 钩子（Hooks）与自动化监控

OmG 扩展内置了两个非常实用的钩子（Hook），它们在后台默默工作，提升体验：

1. 用量监控钩子（AfterAgent Hook） ：在每个智能体回合结束后，自动在终端打印一行简洁的 Token 使用情况，包括本次消耗和会话累计消耗。这让你对 API 成本心中有数。你可以通过环境变量 OMG_HOOK_PROFILE=minimal 来关闭输出（但仍记录状态）。
2. 学习信号安全过滤器（AfterAgent Hook） ：这个钩子会智能判断当前会话是否处于“深度访谈”或“信息查询”状态，并抑制 Gemini CLI 原生的 /omg:learn 建议提示的弹出。这避免了在深度思考或执行关键任务时被不相关的建议打扰，保持了工作流的专注。

如果遇到钩子行为异常，可以使用 /omg:hooks-validate 进行检查。

5. 常见问题排查与优化心得

在实际使用中，你可能会遇到一些典型问题。以下是我总结的排查清单和优化建议：

现象	可能原因	解决方案
安装时出现 settings.filter is not a function 错误	Gemini CLI 运行时版本过旧，或扩展元数据缓存损坏。	1. 升级 Gemini CLI 到最新稳定版（v0.37.0+）。 2. 运行 gemini extensions uninstall oh-my-gemini-cli 卸载。 3. 重新从仓库 URL 安装。
输入 /omg:status 等命令无反应	OmG 扩展未在当前会话中成功加载。	1. 在终端模式运行 gemini extensions list 确认已安装。 2. 完全退出并重新启动 Gemini CLI 交互会话。
team-assemble 一直提议团队但不开始执行	缺少明确的批准指令。	在系统询问 “Proceed with this team? (yes/no)” 时，必须回复 yes , approve , go 或 run 等明确批准词。简单的 “y” 或 “ok” 可能不被解析。
并行执行时任务混乱或文件冲突	工作区（Workspace）未正确设置，或多个会话同时写入共享状态。	1. 使用 /omg:workspace audit 检查各路径状态。 2. 确保只有一个主编排会话（持有 session-lock.json ）。 3. 对于并行工作，考虑使用 Git worktree 创建独立的工作树，并将其添加为不同的 lane。
任务在 team-verify 阶段反复失败	验收标准（AC）定义不明确，或 omg-executor 输出的代码与 AC 存在理解偏差。	1. 回顾 /omg:team-prd 阶段产出的验收标准，确保其具体、可测量。 2. 使用 /omg:recall “验收标准” 命令快速找回之前的决策。 3. 考虑手动编辑 taskboard.md ，为失败的任务添加更详细的步骤说明或示例代码。
感觉响应速度慢，Token 消耗快	可能处于“深度思考”模式，或上下文携带了过多历史。	1. 检查当前模式： /omg:mode 。对于编码任务， balanced 或 speed 模式通常比 deep 模式更高效。 2. 利用 OmG 的状态外置优势，确保智能体每次只获得必要上下文。冗长的原始对话历史是 Token 消耗的主因。 3. 定期使用 /omg:cache 查看上下文使用情况。

最后，分享一个我的核心工作习惯：善用 /omg:recall 命令。 在长时间、多步骤的任务中，我们经常会忘记之前为什么做出某个技术决定。与其在浩如烟海的对话历史中翻找，不如直接使用 /omg:recall “为什么选择 bcrypt 而不是 argon2” 。这个命令会优先从结构化的状态文件（如 taskboard.md , checkpoint.md ）中搜索相关信息，如果找不到，再执行有范围限制的历史搜索。这能极大提升信息检索的效率，让你始终保持对项目脉络的清晰把握。

OmG 将 Gemini CLI 从一个出色的对话伙伴，提升为了一个真正的工程协作者。它需要一点学习成本来适应其结构化的思维方式，但一旦掌握，你将发现处理复杂任务变得前所未有的条理清晰和高效可控。