AgentCrew

一个面向 macOS 的万物编排工作台（Universal CLI Orchestration Workbench）

不仅能将 Codex、Claude、Cursor-Agent 等多种 AI 工具无缝组织成可视化工作流，还能混合编排任意传统 CLI 命令（如 git、npm、docker、ffmpeg 等），在本地完成研发、测试、部署与自动化运维的完整闭环。

简体中文 | English

✨ 核心亮点 (Key Features)

AgentCrew 并非要替代某一个具体的 AI 聊天工具，而是提供一个统一的 Orchestration Layer，让多种 AI CLI 能以更稳定、可复用、可观察的方式协作。

💻 极致的 macOS 原生体验

基于 SwiftUI 构建，运行轻量、流畅。
可视化 Flowchart、全链路执行监控、本地系统通知。

🔄 独创双引擎驱动：Pipeline 与 Agent 模式并存

同一任务可自由在两种模式间切换，兼顾执行效率与智能闭环：

⚡️ Pipeline 模式：基于静态 DAG 工作流，执行路径极短。适合目标明确、步骤固定、追求速度与成本控制的标准化任务。
🧠 Agent 模式：基于多轮动态执行（Plan -> Execute -> Evaluate -> Replan）。支持自动诊断失败原因、自动补齐修复步骤，并在高风险操作前（如删除、大规模重构）挂起等待人工审批 (Human-in-the-loop)。

🌊 DAG 波次调度与并发执行

摒弃死板的全串行执行。AgentCrew 自动解析任务步骤之间的显式依赖（Run After）与隐式依赖（Sequential Stage），将可并行的步骤打包成「Wave (波次)」，最大化利用并发性能，大幅缩短长链路任务的等待时间。

🪄 AI 自动生成工作流 (Auto-Planner)

只需输入一句话自然语言（如：“给项目新增 JWT 用户认证与单测”），系统会自动为你拆解出 Implement -> Review -> Fix -> Verify 的结构化步骤，并自动分配合适的底层 AI 工具。

🛠️ 多模型 & 多 CLI 混合编排

深度兼容 AI 工具：原生支持 Cursor/cursor-agent、Claude、Codex 等大模型 CLI。
极简 CLI Environment 配置：提供一键切换标准 / Internal 命令模式；当前主要影响 Codex 与 Claude，Cursor 保持固定命令模式，内置环境探针自动完成路径解析。

🔌 万物编排：原生支持任意传统 CLI

打破“仅限 AI 工具”的局限，AgentCrew 底层拥有强大的通用执行器，通过以下架构机制实现万物编排：

无缝接入现有工具链：完美支持 git、npm、python、docker、ffmpeg 等任意能在 macOS 终端运行的命令。
与大模型互通：支持将提示词以占位符（{{prompt}}）或标准输入（stdin）安全传导给 Shell 脚本；同时支持在 Step Prompt 中引用前序依赖步骤上下文（如 {{step:Design.summary}}）。
结构化上下文传递：不是简单把 stdout 串给下一个 Step，而是基于结构化记忆与共享状态做按需注入，兼顾可读性、成本与可控性。
无限混合编排：例如用 Cursor 编写代码，跑 npm run test 验证，失败时由 Agent 自动抓取报错让 Claude 分析并生成 Patch，最后由自定义 Shell 脚本完成部署。

📊 模式洞察与智能推荐 (Mode Insights & Recommendation)

智能模式推荐：在任务创建前，根据任务复杂度、风险等级、多工具协作需求等维度进行评分，自动为你推荐最合适的执行模式（Agent 或 Pipeline），并在执行中提供动态切换建议。
Mode Insights 分析大盘：内置运行数据分析看板，可视化展示推荐采纳率、模式分布与 7 日趋势。支持导出详细日志，辅助团队复盘与引擎调优。

🧠 结构化记忆与共享状态

AgentCrew 不会把前一个 Step 的完整 stdout 机械塞给下一个 Step，而是把运行结果沉淀为结构化上下文，只把真正有价值的部分注入后续 Prompt。

两层机制

RunContext：负责单轮执行内的依赖链传值。后续 Step 可读取前序依赖 Step 的 summary、decisions、artifacts、output.tail、error.tail 等字段。
SharedState：负责跨 Step / 跨 Stage / 跨 Round 的可复用状态沉淀。同一 rootSessionID 下，仍然有效的 decision / fact / artifactRef / issue / resource 可被后续执行继续复用。

对用户有什么用

Prompt 更干净：默认传递的是摘要、决策和关键产物，而不是冗长过程日志。
依赖边界更清晰：{{step:...}} 只允许读取依赖链上的 Step，上下文不会无边界扩散。
多轮执行更稳：Agent 模式下，同一 root session 的共享状态可以跨 round 继承，避免每轮都从零开始理解问题。
调试更方便：运行时会生成 .agentcrew/context.md，共享状态会落盘到 .agentcrew/runs/<rootSessionID>/shared-state.json，并同步生成 shared-state.md 镜像。

怎么使用

在 Step Prompt 中引用结构化上下文：{{step:Design.summary}}、{{step:Review.output.tail:500}}
读取 pipeline 级运行态：{{pipeline.failed_steps}}、{{pipeline.last_failed.summary}}
需要显式上报可复用状态时，让 Step 写出 step-outbox JSON，由调度器在 wave 结束后统一 merge

更完整的设计说明可见：docs/shared-state-overview.md

🎯 典型使用场景 (Use Cases)

打破“仅限 AI 工具”的局限，AgentCrew 也是一个带可视化界面、支持大模型动态规划、且具备状态管理的加强版 Make 或本地化 Jenkins。

🤖 AI 研发提效闭环

自动化工作台：把团队常用的 “实现代码 -> 代码 Review -> 修复问题 -> 跑通验证” 固化为可复用的标准 Pipeline。
长链路协作：在同一个项目中，让 Claude 负责写文档，Cursor 负责写代码，自动化脚本负责构建，一步到位。
局部重试：当长达几十步的 Pipeline 在最后一步失败时，无需从头再来，支持按 Stage 或单 Step 原地重跑。

⚡️ 通用任务与万物编排 (自行探索)

轻量级本地 CI/CD (DevOps)：利用波次 (Wave) 并发执行 lint 和 test，成功后串行执行 build，最后调用 AI 自动生成 CHANGELOG，并在推送到云端前挂起等待人工（waitingHuman）审批。
多媒体/数据批处理：利用 DAG 的最大化并发性能，同时启动数十个进程（如 ffmpeg）处理耗时任务，或并发抓取数据后交由大模型清洗、分析并自动发送邮件周报。
智能运维与故障自愈：并发巡检本地或远程服务，当指标异常导致 Step 失败时，触发 Agent 机制。自动将报错丢给 AI 生成诊断报告及修复命令（Patch Step），人工审批通过后执行恢复。

🆚 运行模式对比

维度	⚡️ Pipeline 模式	🧠 Agent 模式
适用场景	任务明确、步骤固定、追求速度与确定性	需求模糊、需要反复“实现-审查-修复”的探索任务
计划生成	一次性固定生成	每轮动态重规划 (Re-planning)
失败处理	任务中止，需人工修改流程后重跑	自动诊断并动态生成补救 (Patch) 与验证任务
协作方式	显式依赖的串行/并行执行	多角色协作 (Coder/Reviewer/Fixer) + 评估驱动
人工介入	失败中止后排查	支持中途状态拦截 (ask_human) 审批高危操作
成本/速度	🚀 更快、Token 消耗更低	🛡 更稳健、成功率更高 (相对耗时)

📊 执行流程图

⚡️ Pipeline 模式（单次固定计划）

flowchart TD
    %% 定义高颜值样式类
    classDef start_end fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#01579b,rx:10px,ry:10px
    classDef process fill:#f5f5f5,stroke:#9e9e9e,stroke-width:2px,color:#424242,rx:5px,ry:5px
    classDef decision fill:#fff8e1,stroke:#ffb300,stroke-width:2px,color:#f57f17
    classDef success fill:#e8f5e9,stroke:#388e3c,stroke-width:2px,color:#1b5e20,rx:10px,ry:10px
    classDef fail fill:#ffebee,stroke:#d32f2f,stroke-width:2px,color:#b71c1c,rx:10px,ry:10px
    classDef manual fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px,color:#4a148c,rx:5px,ry:5px

    %% 节点定义
    A(["用户输入 / 设定目标"]):::start_end
    B["Planner 一次性生成<br/>固定 DAG Pipeline"]:::process
    C["调度引擎：解析依赖<br/>并按 Wave 划分"]:::process
    D["执行当前 Wave：<br/>并发 / 串行运行 Steps"]:::process
    E{"Wave 执行结果"}:::decision
    
    G(["结束 Completed"]):::success
    H["任务中止 Failed"]:::fail
    I["用户手工介入检查 / 修改"]:::manual
    J["从失败节点发起<br/>局部重跑 Retry"]:::manual

    %% 连接关系
    A --> B
    B --> C
    C --> D
    D --> E
    
    E -- "成功：仍有后续 Wave" --> C
    E -- "成功：所有 Wave 完毕" --> G
    E -- "失败：触发 Fail-Fast" --> H
    
    H --> I
    I --> J

Pipeline 执行机制说明：

固定生成：由 Planner 根据目标一次性生成所有 Stage 及其依赖关系的静态 DAG 图。
波次调度 (Wave)：系统自动解析任务依赖，将互不阻塞的任务打包为 Wave，从而最大化并发执行效率。
提早失败 (Fail-Fast)：一旦某个 Wave 发生严重错误，任务便提早中断，避免后续执行导致资源浪费。
局部重试：如果任务中止，用户可在排查修正错误后，直接从失败节点或 Stage 重新发起局部重跑，无需从头开始。

🧠 Agent 模式（多轮智能闭环）

flowchart TD
    %% 定义高颜值样式类
    classDef start_end fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#01579b,rx:10px,ry:10px
    classDef process fill:#f5f5f5,stroke:#9e9e9e,stroke-width:2px,color:#424242,rx:5px,ry:5px
    classDef decision fill:#fff8e1,stroke:#ffb300,stroke-width:2px,color:#f57f17
    classDef success fill:#e8f5e9,stroke:#388e3c,stroke-width:2px,color:#1b5e20,rx:10px,ry:10px
    classDef fail fill:#ffebee,stroke:#d32f2f,stroke-width:2px,color:#b71c1c,rx:10px,ry:10px
    classDef manual fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px,color:#4a148c,rx:5px,ry:5px
    classDef strategy fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px,color:#1a237e,rx:5px,ry:5px

    A(["用户输入目标"]):::start_end --> P["Planning: 生成初始 Pipeline"]:::process
    P --> C["Execution: 调度运行当前计划"]:::process
    C --> D["Evaluation: 评估执行结果"]:::process
    
    D --> E{"动态决策与<br/>轮次判断"}:::decision
    
    E -- "成功" --> G(["结束 Completed"]):::success
    E -- "触发高危操作" --> H["挂起: 等待人工干预"]:::manual
    H -. "审批通过" .-> C
    
    E -- "失败: 策略 1" --> S1["Retry:<br/>原路径重试失败与跳过的 Step"]:::strategy
    E -- "失败: 策略 2" --> S2["Local Patch:<br/>失败处插入前置修复 Step"]:::strategy
    E -- "失败: 策略 3" --> S3["Global Replan:<br/>LLM 全局重规划兜底"]:::strategy
    
    S1 --> C
    S2 --> C
    S3 --> C
    
    E -- "失败: 超过 max_rounds" --> X["任务中止 Failed"]:::fail

Agent 渐进式故障恢复与自愈策略（基于代码实现的真实流转）：

第一轮 (Strategy: originalPipeline)：运行最初规划的 Pipeline。
第二轮 (Strategy: retryFailedStage)：如果在第一轮失败，评估器并不会立刻大动干戈，而是生成一个只包含未通过或跳过 Step 的新 Stage 沿原路径重试（Retry）。
第三轮 (Strategy: localPatchInsert)：如果重跑依然失败，系统会触发 Local Patch 机制，提取失败报错并构建一个专门用于修复该前置问题的 Patch Step，将其安插在原失败 Step 的前面，确保其通过后再往下走。
第四轮/兜底 (Strategy: globalReplan)：如果局部 Patch 还搞不定，这时候才会触发基于 LLM 的 Global Replan，全局重新审视上下文进行大重构。
彻底中止：如果以上招数用尽且超过最大允许轮次（maxRounds），才会彻底 Abort 结束。

🚀 快速开始

1. 环境要求

macOS 14.0+
Swift 5.9+
已在终端中登录并配置好至少一种受支持的 AI CLI（如 Cursor, Claude, Codex）

你可以通过以下命令验证环境：

cursor-agent --version
claude --version
codex --version

2. 编译与运行

AgentCrew 是标准的 Swift Package 项目，你可以直接通过命令行启动，或使用 Xcode 打开。

通过命令行：

git clone https://github.com/YourUsername/AgentCrew.git
cd AgentCrew
swift run AgentCrew

(或者使用 swift build 进行构建)

通过 Xcode： 双击 Package.swift 打开项目，选择你的 Mac 作为运行目标，点击 Run (Cmd + R)。

3. 使用指南

启动 App 后，前往 Settings 确认已正确检测到本机的 CLI Environment，并按需切换标准 / Internal 命令模式（主要影响 Codex 与 Claude）。
点击侧边栏底部的 + 选择一个本地代码仓库。
点击 AI Pipeline Generator，输入你的任务需求，或手动创建 Pipeline。
在 Pipeline 编辑器中检查各个 Step 的 Tool 和 Prompt（命令会根据环境自动生成，也可在 Advanced 中手写覆盖）。
在右上角选择 Pipeline 或 Agent 模式。
点击 Run 开始见证奇迹！📈

🏗️ 项目架构

本项目采用 SwiftUI 编写，分层架构设计如下：

flowchart TB
    %% 定义高颜值样式类
    classDef layer_ui fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#0d47a1,rx:5px,ry:5px
    classDef layer_vm fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c,rx:5px,ry:5px
    classDef layer_core fill:#e8f5e9,stroke:#388e3c,stroke-width:2px,color:#1b5e20,rx:5px,ry:5px
    classDef layer_runner fill:#fff8e1,stroke:#ffa000,stroke-width:2px,color:#ff6f00,rx:5px,ry:5px
    classDef layer_runner_base fill:#ffecb3,stroke:#f57f17,stroke-width:2px,color:#bf360c,rx:5px,ry:5px
    classDef layer_data fill:#e0f7fa,stroke:#0097a7,stroke-width:2px,color:#006064,rx:5px,ry:5px

    subgraph UI ["表现层 (SwiftUI)"]
        direction LR
        ContentView["主视图"]:::layer_ui
        PipelineEditor["Pipeline 编辑器"]:::layer_ui
        Flowchart["可视化 DAG 树"]:::layer_ui
        Monitor["执行监控台"]:::layer_ui
    end

    subgraph VM ["视图模型层 (ViewModels)"]
        AppViewModel["AppViewModel<br/>全局状态管理 & 生命周期监控"]:::layer_vm
    end

    subgraph Core ["核心编排层 (Orchestration)"]
        DAGScheduler["DAGScheduler<br/>依赖解析与波次并发调度"]:::layer_core
        AIPlanner["AIPlanner<br/>自然语言转结构化 Pipeline"]:::layer_core
        CLIProfileManager["CLIProfileManager<br/>环境探针与参数装配"]:::layer_core
    end

    subgraph Runners ["执行层 (CLI Runners)"]
        CLIRunner["CLIRunner<br/>底层进程执行器"]:::layer_runner_base
        CommandRunner["CommandRunner<br/>自定义命令解析"]:::layer_runner
        ToolRunner["ToolRunner<br/>预设工具路由"]:::layer_runner
        
        Cursor["CursorRunner"]:::layer_runner
        Claude["ClaudeRunner"]:::layer_runner
        Codex["CodexRunner"]:::layer_runner
        
        ToolRunner --> Cursor
        ToolRunner --> Claude
        ToolRunner --> Codex
        
        CommandRunner --> CLIRunner
        Cursor --> CLIRunner
        Claude --> CLIRunner
        Codex --> CLIRunner
    end

    subgraph Models ["数据模型层 (Models)"]
        Data["PipelineModels / AgentModels / CLIProfile"]:::layer_data
    end

    %% 模块间交互连线
    UI -- "User Action" --> VM
    VM -. "State Binding" .-> UI
    
    VM -- "Plan / Execute" --> Core
    Core -- "Dispatch" --> Runners
    
    Runners -- "Progress / Result" --> VM
    
    %% 数据层依赖连线
    UI -.-> Data
    VM -.-> Data
    Core -.-> Data
    Runners -.-> Data

    %% Subgraph 背景框样式
    style UI fill:#f8f9fa,stroke:#c5cae9,stroke-width:2px,rx:10px,ry:10px,stroke-dasharray: 5 5,color:#333333
    style VM fill:#f8f9fa,stroke:#c5cae9,stroke-width:2px,rx:10px,ry:10px,stroke-dasharray: 5 5,color:#333333
    style Core fill:#f8f9fa,stroke:#c5cae9,stroke-width:2px,rx:10px,ry:10px,stroke-dasharray: 5 5,color:#333333
    style Runners fill:#f8f9fa,stroke:#c5cae9,stroke-width:2px,rx:10px,ry:10px,stroke-dasharray: 5 5,color:#333333
    style Models fill:#f8f9fa,stroke:#c5cae9,stroke-width:2px,rx:10px,ry:10px,stroke-dasharray: 5 5,color:#333333

核心模块说明：

Services/DAGScheduler.swift: 负责解析依赖关系与波次 (Wave) 并行调度。
Services/AIPlanner.swift: 负责与大模型交互，将自然语言转化为结构化执行步骤。
Services/CLIProfileManager.swift: 负责不同环境 CLI 命令参数的自适应装配。
Services/RunContextStore.swift: 负责依赖链范围内的 {{step:...}} 模板解析、摘要 / decisions / artifacts 提取，以及 .agentcrew/context.md 镜像。
Services/SharedStateStore.swift: 负责 wave snapshot、共享状态 brief 注入、step-outbox merge，以及同一 rootSessionID 下的跨 round 结构化状态持久化。
ViewModels/AppViewModel.swift: 全局状态管理、会话生命周期与模式回退分析。

🔌 万物皆可编排：支持任意传统 CLI 的底层架构揭秘

触发机制：动态路由 在 DAGScheduler 中，系统会根据节点是否配置了自定义命令进行动态路由，跳过 AI Runner，直接交给 CommandRunner 执行：
```
if step.hasCustomCommand {
    return try await CommandRunner().execute(...)
}
// 否则才走常规的 Claude / Cursor 等 AI 工具
```
执行机制：纯正的 Zsh 子进程 CommandRunner 底层使用 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
)
```
数据传导：安全转义与 Stdin 系统支持 {{prompt}} 占位符内联替换，自动对其进行安全的 Shell 转义（shellQuote）；若命令中没有写占位符，则只会将当前 Step 的 Prompt 作为标准输入流 (stdin) 传给该命令。前序依赖步骤上下文不会自动拼进 stdin，而是通过 {{step:...}} 与共享状态注入到 Prompt。

🤝 参与贡献

欢迎提交 Issue 和 Pull Request！AgentCrew 仍处于快速演进阶段。如果你希望增加新的 AI CLI 支持，或者改进 DAG 调度引擎，欢迎直接阅读源码或发起 Issue 与我们讨论。

📄 许可证 (License)

本项目采用 Apache License 2.0 开源。

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
Images		Images
Sources/AgentCrew		Sources/AgentCrew
docs		docs
.gitignore		.gitignore
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
README_EN.md		README_EN.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

AgentCrew

✨ 核心亮点 (Key Features)

💻 极致的 macOS 原生体验

🔄 独创双引擎驱动：Pipeline 与 Agent 模式并存

🌊 DAG 波次调度与并发执行

🪄 AI 自动生成工作流 (Auto-Planner)

🛠️ 多模型 & 多 CLI 混合编排

🔌 万物编排：原生支持任意传统 CLI

📊 模式洞察与智能推荐 (Mode Insights & Recommendation)

🧠 结构化记忆与共享状态

两层机制

对用户有什么用

怎么使用

🎯 典型使用场景 (Use Cases)

🤖 AI 研发提效闭环

⚡️ 通用任务与万物编排 (自行探索)

🆚 运行模式对比

📊 执行流程图

⚡️ Pipeline 模式（单次固定计划）

🧠 Agent 模式（多轮智能闭环）

🚀 快速开始

1. 环境要求

2. 编译与运行

3. 使用指南

🏗️ 项目架构

🔌 万物皆可编排：支持任意传统 CLI 的底层架构揭秘

🤝 参与贡献

📄 许可证 (License)

About

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

AgentCrew

✨ 核心亮点 (Key Features)

💻 极致的 macOS 原生体验

🔄 独创双引擎驱动：Pipeline 与 Agent 模式并存

🌊 DAG 波次调度与并发执行

🪄 AI 自动生成工作流 (Auto-Planner)

🛠️ 多模型 & 多 CLI 混合编排

🔌 万物编排：原生支持任意传统 CLI

📊 模式洞察与智能推荐 (Mode Insights & Recommendation)

🧠 结构化记忆与共享状态

两层机制

对用户有什么用

怎么使用

🎯 典型使用场景 (Use Cases)

🤖 AI 研发提效闭环

⚡️ 通用任务与万物编排 (自行探索)

🆚 运行模式对比

📊 执行流程图

⚡️ Pipeline 模式（单次固定计划）

🧠 Agent 模式（多轮智能闭环）

🚀 快速开始

1. 环境要求

2. 编译与运行

3. 使用指南

🏗️ 项目架构

🔌 万物皆可编排：支持任意传统 CLI 的底层架构揭秘

🤝 参与贡献

📄 许可证 (License)

About

Topics

Resources

Stars

Watchers

Forks

Packages

Contributors

Languages