💡 一、开发背景：从一个真实的痛点说起
在日常的 AI 辅助编程中，相信很多深度使用 Cursor、Codebuddy 等工具的开发者都有这样的体会：不同的 AI 模型有着完全不同的“脾气”和专长。
经过我们实际落地编写代码的测试，发现了一个很有意思的现象：
- 写代码时：
Codex模型往往更遵守“最小化改动”的原则，指哪打哪，非常克制。 - Review/解 Bug 时：如果让
Claude 3 Opus去解一个小 Bug，它可能会为了这一个点，给你大范围地重构和改动代码。
因此，理想的代码生成工作流应该是：采用 Codex 来编写/修改代码，采用 Opus 来进行 Code Review 和纠错。（当然，反过来也是可以的～）
但随之而来的致命痛点是： 在当前的 Cursor 或 Codebuddy 等 IDE 中，无法自动化地完成这种跨模型的协作。在 IDE 里，切换模型是一个纯手动操作，你没法把“用模型A写代码 -> 用模型B做检查 -> 用脚本跑测试”这个过程固化成自动化的流水线。
为了打破这种“单点对话”的限制，让不同的 AI 模型能够像流水线工人一样自动打配合，同时还能把传统终端命令（Git、npm、测试脚本等）也加进来，我开发了这款面向 macOS 的原生应用 —— AgentCrew。
✨ 二、AgentCrew 是什么？
AgentCrew 并非要替代某一个具体的 AI 聊天工具，而是提供一个统一的 Orchestration Layer（编排层），让多种 AI CLI 能以更稳定、可复用、可观察的方式协作。
简单来说，它是一个面向 macOS 的万物编排工作台。不仅能将 Codex、Claude、Cursor-Agent 等多种 AI 工具无缝组织成可视化工作流，还能混合编排任意传统 CLI 命令（如 git、npm、docker、ffmpeg 等），在本地完成研发、测试、部署与自动化运维的完整闭环。
它具有以下核心亮点：
- 💻 极致的 macOS 原生体验：基于 SwiftUI 构建，运行轻量、流畅，自带可视化 Flowchart 与全链路执行监控。
- 🌊 DAG 波次调度：摒弃死板的全串行执行，自动解析任务依赖，最大化并发执行。
- 🪄 Auto-Planner：一句话自然语言，自动生成结构化任务流。
- 🔌 万物皆可编排：打破“仅限 AI”的局限，无缝衔接本地 Shell 脚本与大模型输入输出。
🆚 三、核心设计：独创的双引擎驱动
为了适应不同的任务诉求（追求速度 vs 追求稳定性），AgentCrew 在底层设计了两种截然不同的运行模式：Pipeline 模式与 Agent 模式。
| 维度 | ⚡️ Pipeline 模式 | 🧠 Agent 模式 |
|---|---|---|
| 适用场景 | 任务明确、步骤固定、追求速度与确定性 | 需求模糊、需要反复“实现-审查-修复”的探索任务 |
| 计划生成 | 一次性固定生成 | 每轮动态重规划 (Re-planning) |
| 失败处理 | 任务中止，需人工修改流程后重跑 (Fail-Fast) | 自动诊断并动态生成补救 (Patch) 与验证任务 |
| 协作方式 | 显式依赖的串行/并行执行 (Wave 调度) | 多角色协作 (Coder/Reviewer/Fixer) + 评估驱动 |
| 人工介入 | 失败中止后排查 | 支持中途状态拦截 (ask_human) 审批高危操作 |
1. ⚡️ Pipeline 模式（静态并发调度）
Pipeline 模式强调的是快和确定性。由 Planner 一次性根据目标生成所有 Stage 及其依赖关系的静态 DAG 图后，调度引擎会自动解析依赖，将互不阻塞的任务打包为 Wave（波次），从而最大化并发执行效率。
如果遇到错误，则触发 Fail-Fast（提早失败）机制提前中止，避免后续执行导致资源浪费。 特别痛点解决：如果任务中止，用户可在排查修正错误后，直接从失败节点或 Stage 重新发起局部重跑，无需从头开始！
2. 🧠 Agent 模式（多轮智能闭环与自愈）
这是 AgentCrew 最硬核的部分。当任务需要反复横跳验证时（比如写代码 -> 编译报错 -> 修 Bug -> 再编译），Agent 模式会引入渐进式故障恢复与自愈策略：
自愈策略揭秘（基于代码实现的真实流转）：
- 第一轮 (Strategy:
originalPipeline)：运行最初规划的 Pipeline。 - 第二轮 (Strategy:
retryFailedStage)：如果在第一轮失败，评估器并不会立刻大动干戈，而是生成一个只包含未通过或跳过 Step 的新 Stage 沿原路径重试（Retry）。 - 第三轮 (Strategy:
localPatchInsert)：如果重跑依然失败，系统会触发 Local Patch 机制，提取失败报错并构建一个专门用于修复该前置问题的 Patch Step，将其安插在原失败 Step 的前面，确保其通过后再往下走。 - 第四轮/兜底 (Strategy:
globalReplan)：如果局部 Patch 还搞不定，这时候才会触发基于 LLM 的 Global Replan，全局重新审视上下文进行大重构。 - 彻底中止：如果以上招数用尽且超过最大允许轮次（
maxRounds），才会彻底 Abort 结束。
🏗️ 四、万物皆可编排：底层架构与源码解析
AgentCrew 是如何做到既能跑 AI 模型，又能跑原生 Shell 命令的？来看一下它的核心分层架构：
痛点攻克：支持任意传统 CLI 的底层机制
要在 macOS 原生应用里跑好 Shell 脚本，其实有很多坑（比如环境变量丢失、路径找不到等）。AgentCrew 做了三层处理：
1. 触发机制：动态路由
在 DAGScheduler 中，系统会根据节点是否配置了自定义命令进行动态路由，跳过 AI Runner，直接交给 CommandRunner 执行：
if step.hasCustomCommand {
return try await CommandRunner().execute(...)
}
// 否则才走常规的 Claude / Cursor 等 AI 工具
2. 执行机制：纯正的 Zsh 子进程唤起
底层拒绝使用简单的 Process() 裸跑，而是使用 zsh -lc 唤起子进程，完美保留了开发者原汁原味的环境变量（加载 .zprofile / .zshrc）。并且在执行前通过 command -v 寻找真实绝对路径，极大避免了恶心的 "command not found" 报错：
let result = try await cli.run(
command: "zsh",
arguments: ["-lc", resolution.commandLine],
workingDirectory: workingDirectory,
stdinData: stdinData
)
3. 数据传导：安全转义与 Stdin 桥接
系统支持 {{prompt}} 占位符内联替换，并自动对其进行安全的 Shell 转义（shellQuote）。如果命令中没有写占位符，系统会自动将提示词和前序输出作为标准输入流 (stdin) 直接喂给该命令。这就真正打通了 AI 与传统脚本的数据流传导！
🎯 五、典型落地场景：它能干什么？
AgentCrew 也是一个带可视化界面、支持大模型动态规划、且具备状态管理的加强版本地 Jenkins。
🤖 AI 研发提效闭环
- 解决开篇痛点：AI 研发提效闭环：把团队常用的流派固化下来：创建一个 Pipeline，节点 A 调用
Codex写代码 -> 节点 B 调用Opus做 Review -> 节点 C 跑npm run test-> 节点 D 负责 Fix。长链路协作一步到位。 - 局部重试：当长达几十步的 Pipeline 在最后一步失败时，无需从头再来，支持按 Stage 或单 Step 原地重跑。
⚡️ 通用任务与万物编排 (自行探索)
- 轻量级本地 CI/CD (DevOps)：利用波次 (Wave) 并发执行
lint和test，成功后串行执行build，最后调用 AI 自动生成CHANGELOG，并在推送到云端前挂起等待人工（waitingHuman）审批。 - 多媒体/数据批处理：利用 DAG 的最大化并发性能，同时启动数十个进程（如
ffmpeg）处理耗时任务，或并发抓取数据后交由大模型清洗、分析并自动发送邮件周报。 - 智能运维与故障自愈：并发巡检本地或远程服务，当指标异常导致 Step 失败时，触发 Agent 机制。自动将报错丢给 AI 生成诊断报告及修复命令（Patch Step），人工审批通过后执行恢复。
📊 六、最后：关于复盘与开源
为了让整个调度系统的表现可度量，我还顺手在 App 里内置了一个 Mode Insights (模式洞察与分析大盘)，可视化展示 Pipeline/Agent 的推荐采纳率、模式分布与 7 日执行趋势，辅助团队复盘与引擎调优。
这个项目源自我个人对“更自由、更开放的 AI 编程工作流”的渴望。目前 AgentCrew 已经基于 MIT 协议开源，完全可以自由使用和魔改。
如果你也想要一个能够随意组合 Claude、Cursor 以及本地 Shell 脚本的可视化工作台，欢迎来把玩一下！
🔗 GitHub 仓库地址：[github.com/qingni/Agen…]
如果觉得这个架构设计和思路对你有启发，欢迎去 GitHub 点个 ⭐ Star，或者在评论区一起交流探讨你理想中的 AI 工作流！
