zag 是一款用 Rust 编写的 CLI 工具，它将 Claude、Codex、Gemini、Copilot 和 Ollama 五大 AI 编程代理整合到单一命令行界面中，让开发者无需学习五种不同的 CLI 即可自由切换使用。

zag：一个统一多平台AI编程代理的命令行工具\n\n在 AI 辅助编程工具百花齐放的今天，开发者往往面临一个尴尬的局面：Claude Code、OpenAI Codex、Google Gemini CLI、GitHub Copilot CLI 以及 Ollama 各有千秋，但每个工具都有自己独特的命令语法和工作流程。频繁切换不仅浪费时间，还增加了认知负担。zag 项目正是为解决这一痛点而生，它用一个统一的命令行界面封装了五大主流 AI 编程代理，让开发者可以专注于编程本身，而非记忆各种 CLI 的差异。\n\n## 项目背景与设计初衷\n\nAI 编程代理的生态系统正在快速演进，几乎每周都有新功能、新模型发布。然而，开发者的工作流程不应该随着代理的更迭而频繁改变。zag 的核心设计理念是"代理会变，你的工作流不变"。通过提供一个与底层代理无关的抽象层，zag 让用户可以用一致的命令与不同的 AI 代理交互，同时保留了各平台的独特能力。\n\n这个项目采用 Rust 编写（要求 Rust 1.85+，使用 2024 Edition），充分利用了 Rust 的性能优势和现代语言特性。项目还提供了丰富的多语言 SDK，包括 TypeScript、Python、C#、Swift、Java 和 Kotlin，方便集成到各种开发环境中。\n\n## 核心功能特性\n\n### 统一命令接口\n\nzag 最大的价值在于统一。无论你偏好哪个 AI 代理，都可以用相同的命令模式操作：\n\n- zag run —— 启动交互式会话（默认使用 Claude）\n- zag exec \"prompt\" —— 非交互式执行，输出结果后直接退出\n- zag -p gemini run —— 切换不同提供商\n- zag -p auto -m auto exec \"task\" —— 让 AI 自动选择最适合的提供商和模型\n\n这种统一不仅体现在基本命令上，还包括跨平台的增强功能。\n\n### 模型大小别名系统\n\nzag 引入了一套智能的模型大小别名机制，让用户无需记忆各平台复杂的模型命名规则。通过 -m small|medium|large 参数，zag 会自动映射到当前提供商对应的最佳模型：\n\n| 提供商 | small | medium | large |\n|--------|-------|--------|-------|\n| Claude | haiku | sonnet | default |\n| Codex | gpt-5.4-mini | gpt-5.3-codex | gpt-5.4 |\n| Gemini | gemini-3.1-flash-lite | gemini-2.5-flash | gemini-3.1-pro |\n| Copilot | claude-haiku-4.5 | claude-sonnet-4.6 | claude-opus-4.6 |\n| Ollama | 2b | 9b | 35b |\n\n这套别名系统让脚本编写更加可移植——你可以编写 zag -m large exec \"...\"，而不必关心底层实际调用的是 Claude Opus 还是 GPT-5.4。\n\n### 跨平台增强功能\n\nzag 不仅封装了现有代理的功能，还添加了许多原生代理不具备的跨平台特性：\n\n- Git 工作区隔离：通过 --worktree 参数，每次会话都在独立的 Git 工作区中运行，避免污染主分支\n- Docker 沙箱：--sandbox 参数提供容器化隔离，增强安全性\n- 结构化 JSON 输出：支持 JSON Schema 验证的统一输出格式\n- 统一会话日志：无论使用哪个代理，日志格式一致，便于追踪和审计\n\n### 多代理编排能力\n\nzag 提供了一套原语（primitives）用于在 shell 脚本中编排多代理工作流：\n\n- zag spawn —— 后台启动代理，返回会话 ID\n- zag wait —— 阻塞等待会话完成\n- zag pipe —— 将会话结果链式传递给新会话\n- zag collect —— 聚合多个会话的结果\n- zag broadcast —— 向项目中所有会话广播消息\n\n这些工具让复杂的 multi-agent 工作流变得简单可控。例如，你可以先用 Gemini 进行代码审查，再将结果管道给 Claude 进行重构，最后用 Codex 生成测试用例——全部在一个 shell 脚本中完成。\n\n### 远程访问与集群支持\n\nzag 内置 HTTP/WebSocket 服务器，支持远程连接和集群部署：\n\n- zag serve —— 启动远程访问服务器\n- zag connect —— 连接到远程 zag 服务器\n- 支持会话的远程管理和监控\n\n这对于团队环境或 CI/CD 集成特别有用。\n\n## 安装与使用\n\n安装 zag 有多种方式：\n\nbash\n# 通过 cargo 安装\ncargo install zag-cli\n\n# 从源码构建\ngit clone https://github.com/niclaslindstedt/zag.git\ncd zag\ncargo install --path zag-cli\n\n# 作为库依赖\ncargo add zag\n\n\n使用前需要至少安装一个底层代理 CLI，zag 会在运行时检查并给出安装提示。\n\n## 实际应用场景\n\n### 场景一：多代理代码审查\n\nbash\n# 使用不同代理进行多维度审查\nzag -p claude review --uncommitted\nzag -p gemini review --uncommitted\nzag -p codex review --uncommitted\n\n\n### 场景二：自动化重构流水线\n\nbash\n# 生成重构任务\nID1=$(zag -p gemini spawn \"分析 src/auth.rs 的问题\")\nzag wait $ID1\n\n# 基于分析结果进行重构\nID2=$(zag pipe $ID1 -- -p claude spawn \"重构上述代码\")\nzag wait $ID2\n\n# 生成测试\nzag pipe $ID2 -- -p codex spawn \"为重构后的代码生成单元测试\"\n\n\n### 场景三：团队标准化工作流\n\n通过 zag config 可以设置团队统一的默认行为，确保所有成员使用一致的模型选择和输出格式。\n\n## 技术亮点与架构思考\n\nzag 的架构设计体现了几个值得关注的工程实践：\n\n1. 适配器模式：每个 AI 提供商都有独立的适配器实现，统一接口背后是各自的原生调用\n2. 插件化技能系统：zag skills 命令支持跨提供商的技能管理，实现可复用的 AI 工作流组件\n3. MCP 服务器集成：支持 Model Context Protocol，可以统一管理和切换不同的上下文提供源\n4. 事件驱动日志：所有会话产生结构化事件日志，便于后续分析和自动化处理\n\n## 适用人群与使用建议\n\nzag 特别适合以下用户：\n\n- 多代理用户：已经在使用或计划尝试多个 AI 编程代理的开发者\n- 团队技术负责人：需要为团队标准化 AI 工具链的决策者\n- 自动化爱好者：希望将 AI 代理集成到 shell 脚本和 CI/CD 流程中的工程师\n- 多语言开发者：需要在不同语言 SDK 中使用统一 AI 接口的项目\n\n对于刚开始接触 AI 编程代理的新手，建议先熟悉至少一个原生代理（如 Claude Code），再引入 zag 进行多代理管理。\n\n## 总结与展望\n\nzag 代表了 AI 工具链向标准化、统一化演进的趋势。随着 AI 编程代理生态的成熟，类似 zag 这样的抽象层工具将变得越来越重要。它不仅简化了多代理管理，更重要的是提供了一种"面向未来"的工作方式——当新的 AI 代理出现时，只需添加新的适配器，现有的工作流脚本无需修改即可使用新能力。\n\n项目的 Rust 实现保证了性能和可靠性，丰富的多语言 SDK 扩展了应用场景，而内置的编排和远程访问能力则为团队级部署奠定了基础。对于希望在 AI 辅助编程领域保持灵活性和前瞻性的开发者来说，zag 是一个值得关注的工具。

zag：一个统一多平台AI编程代理的命令行工具\n\n在 AI 辅助编程工具百花齐放的今天，开发者往往面临一个尴尬的局面：Claude Code、OpenAI Codex、Google Gemini CLI、GitHub Copilot CLI 以及 Ollama 各有千秋，但每个工具都有自己独特的命令语法和工作流程。频繁切换不仅浪费时间，还增加了认知负担。zag 项目正是为解决这一痛点而生，它用一个统一的命令行界面封装了五大主流 AI 编程代理，让开发者可以专注于编程本身，而非记忆各种 CLI 的差异。\n\n项目背景与设计初衷\n\nAI 编程代理的生态系统正在快速演进，几乎每周都有新功能、新模型发布。然而，开发者的工作流程不应该随着代理的更迭而频繁改变。zag 的核心设计理念是"代理会变，你的工作流不变"。通过提供一个与底层代理无关的抽象层，zag 让用户可以用一致的命令与不同的 AI 代理交互，同时保留了各平台的独特能力。\n\n这个项目采用 Rust 编写（要求 Rust 1.85+，使用 2024 Edition），充分利用了 Rust 的性能优势和现代语言特性。项目还提供了丰富的多语言 SDK，包括 TypeScript、Python、C#、Swift、Java 和 Kotlin，方便集成到各种开发环境中。\n\n核心功能特性\n\n统一命令接口\n\nzag 最大的价值在于统一。无论你偏好哪个 AI 代理，都可以用相同的命令模式操作：\n\n- zag run —— 启动交互式会话（默认使用 Claude）\n- zag exec \"prompt\" —— 非交互式执行，输出结果后直接退出\n- zag -p gemini run —— 切换不同提供商\n- zag -p auto -m auto exec \"task\" —— 让 AI 自动选择最适合的提供商和模型\n\n这种统一不仅体现在基本命令上，还包括跨平台的增强功能。\n\n模型大小别名系统\n\nzag 引入了一套智能的模型大小别名机制，让用户无需记忆各平台复杂的模型命名规则。通过 -m small|medium|large 参数，zag 会自动映射到当前提供商对应的最佳模型：\n\n| 提供商 | small | medium | large |\n|--------|-------|--------|-------|\n| Claude | haiku | sonnet | default |\n| Codex | gpt-5.4-mini | gpt-5.3-codex | gpt-5.4 |\n| Gemini | gemini-3.1-flash-lite | gemini-2.5-flash | gemini-3.1-pro |\n| Copilot | claude-haiku-4.5 | claude-sonnet-4.6 | claude-opus-4.6 |\n| Ollama | 2b | 9b | 35b |\n\n这套别名系统让脚本编写更加可移植——你可以编写 zag -m large exec \"...\"，而不必关心底层实际调用的是 Claude Opus 还是 GPT-5.4。\n\n跨平台增强功能\n\nzag 不仅封装了现有代理的功能，还添加了许多原生代理不具备的跨平台特性：\n\n- Git 工作区隔离：通过 --worktree 参数，每次会话都在独立的 Git 工作区中运行，避免污染主分支\n- Docker 沙箱：--sandbox 参数提供容器化隔离，增强安全性\n- 结构化 JSON 输出：支持 JSON Schema 验证的统一输出格式\n- 统一会话日志：无论使用哪个代理，日志格式一致，便于追踪和审计\n\n多代理编排能力\n\nzag 提供了一套原语（primitives）用于在 shell 脚本中编排多代理工作流：\n\n- zag spawn —— 后台启动代理，返回会话 ID\n- zag wait —— 阻塞等待会话完成\n- zag pipe —— 将会话结果链式传递给新会话\n- zag collect —— 聚合多个会话的结果\n- zag broadcast —— 向项目中所有会话广播消息\n\n这些工具让复杂的 multi-agent 工作流变得简单可控。例如，你可以先用 Gemini 进行代码审查，再将结果管道给 Claude 进行重构，最后用 Codex 生成测试用例——全部在一个 shell 脚本中完成。\n\n远程访问与集群支持\n\nzag 内置 HTTP/WebSocket 服务器，支持远程连接和集群部署：\n\n- zag serve —— 启动远程访问服务器\n- zag connect —— 连接到远程 zag 服务器\n- 支持会话的远程管理和监控\n\n这对于团队环境或 CI/CD 集成特别有用。\n\n安装与使用\n\n安装 zag 有多种方式：\n\nbash\n通过 cargo 安装\ncargo install zag-cli\n\n从源码构建\ngit clone https://github.com/niclaslindstedt/zag.git\ncd zag\ncargo install --path zag-cli\n\n作为库依赖\ncargo add zag\n\n\n使用前需要至少安装一个底层代理 CLI，zag 会在运行时检查并给出安装提示。\n\n实际应用场景\n\n场景一：多代理代码审查\n\nbash\n使用不同代理进行多维度审查\nzag -p claude review --uncommitted\nzag -p gemini review --uncommitted\nzag -p codex review --uncommitted\n\n\n场景二：自动化重构流水线\n\nbash\n生成重构任务\nID1=$(zag -p gemini spawn \"分析 src/auth.rs 的问题\")\nzag wait $ID1\n\n基于分析结果进行重构\nID2=$(zag pipe $ID1 -- -p claude spawn \"重构上述代码\")\nzag wait $ID2\n\n生成测试\nzag pipe $ID2 -- -p codex spawn \"为重构后的代码生成单元测试\"\n\n\n场景三：团队标准化工作流\n\n通过 zag config 可以设置团队统一的默认行为，确保所有成员使用一致的模型选择和输出格式。\n\n技术亮点与架构思考\n\nzag 的架构设计体现了几个值得关注的工程实践：\n\n1. 适配器模式：每个 AI 提供商都有独立的适配器实现，统一接口背后是各自的原生调用\n2. 插件化技能系统：zag skills 命令支持跨提供商的技能管理，实现可复用的 AI 工作流组件\n3. MCP 服务器集成：支持 Model Context Protocol，可以统一管理和切换不同的上下文提供源\n4. 事件驱动日志：所有会话产生结构化事件日志，便于后续分析和自动化处理\n\n适用人群与使用建议\n\nzag 特别适合以下用户：\n\n- 多代理用户：已经在使用或计划尝试多个 AI 编程代理的开发者\n- 团队技术负责人：需要为团队标准化 AI 工具链的决策者\n- 自动化爱好者：希望将 AI 代理集成到 shell 脚本和 CI/CD 流程中的工程师\n- 多语言开发者：需要在不同语言 SDK 中使用统一 AI 接口的项目\n\n对于刚开始接触 AI 编程代理的新手，建议先熟悉至少一个原生代理（如 Claude Code），再引入 zag 进行多代理管理。\n\n总结与展望\n\nzag 代表了 AI 工具链向标准化、统一化演进的趋势。随着 AI 编程代理生态的成熟，类似 zag 这样的抽象层工具将变得越来越重要。它不仅简化了多代理管理，更重要的是提供了一种"面向未来"的工作方式——当新的 AI 代理出现时，只需添加新的适配器，现有的工作流脚本无需修改即可使用新能力。\n\n项目的 Rust 实现保证了性能和可靠性，丰富的多语言 SDK 扩展了应用场景，而内置的编排和远程访问能力则为团队级部署奠定了基础。对于希望在 AI 辅助编程领域保持灵活性和前瞻性的开发者来说，zag 是一个值得关注的工具。