Hotdry.
归档
ai-systems

Superset-sh：多代理 IDE 运行多 Claude Code/Codex 代理的工程化实践

工程化本地 IDE 管理 Claude Code/Codex 等代理军队：工作区隔离、模型切换、工具执行与运行时编排的参数配置与落地清单。

在 AI 代理时代，开发人员常常需要同时运行多个编码代理（如 Claude Code 或 OpenAI Codex CLI）来加速任务，但传统终端难以处理上下文切换、隔离与监控。Superset-sh/superset 项目提供了一个 turbocharged 的终端 IDE，专为运行代理军队设计，支持并行执行 10+ 个代理，每个任务隔离在独立 git worktree 中，避免干扰，同时内置监控与 diff 查看器，实现高效的运行时编排。

核心机制：工作区隔离与并行执行

Superset 的工作区（workspace）隔离是其多代理运行的基础。每个代理任务分配到一个独立的 git worktree，这意味着代理不会相互污染代码库或依赖。例如，启动一个 Claude Code 代理处理前端任务，另一个 Codex 代理优化后端时，它们各自在分支化的目录中运行，共享主仓库根路径但互不影响。“Superset 使用 git worktree 为每个任务创建独立分支和工作目录。” 这确保了安全性与可回滚性。

并行执行支持 10+ 代理同时运行，无需上下文切换开销。通过 ⌘1-9 快捷键快速切换工作区，或 ⌘N 新建，开发者可像管理标签页一样编排代理。资源管理上，建议监控 CPU / 内存：每个 worktree 限 2GB RAM，代理并发上限设为机器核心数的 80%（如 8 核机设 6 个），避免 OOM。通过内置终端拆分（⌘D 右拆分，⌘⇧D 下拆分），可在单一视图执行工具链。

模型切换与工具执行参数

模型切换通过工作区预设（presets）实现，Ctrl+1-9 快捷键加载预配置环境。针对 Claude Code 和 Codex：

  • Claude Code 代理：预设命令 claude-code --model claude-3.5-sonnet --api-key $ANTHROPIC_API_KEY，结合工具如 git diff、npm install。
  • Codex CLI：codex-cli --model gpt-4o --prompt "refactor this module"，支持 OpenAI 兼容工具。

在 .superset/config.json 中定义：

{
  "setup": ["cp ../.env .env", "bun install", "echo 'Claude ready'"],
  "teardown": ["git worktree remove -f .", "rm -rf .env"]
}

setup 脚本访问环境变量如 $SUPERSET_WORKSPACE_NAME，便于注入不同 API key 实现模型切换。工具执行参数：超时阈值设 300s / 任务，最大 token 128k；失败重试 3 次，间隔 10s。内置终端支持 ⌘K 清屏、⌘F 搜索，确保工具如 gh pr create 或自定义脚本顺畅运行。

运行时编排与监控要点

Superset 的运行时编排体现在代理监控面板：实时追踪状态（running/idle/error），通知机制在代理需人工干预时弹窗（如 diff 待审）。变化面板（⌘L 切换）集成 diff viewer，直接编辑代理输出，避免外部 IDE 切换。外部集成：⌘O 一键打开 VS Code 等。

可落地监控参数：

  • 健康检查：每 30s ping 代理进程，超时 >60s 自动重启。
  • 资源阈值：CPU >80% 暂停低优先级代理；磁盘 >90% 清理旧 worktree。
  • 通知策略：Slack/Discord webhook on error，优先级：critical（OOM）立即，warning（slow）延时 5min。
  • 回滚清单：代理失败时 git checkout main && git worktree prune，保留主分支。

键盘导航优化效率：⌘⌥↑/↓ 前后工作区，⌘B 侧边栏侧边栏，确保 "workspace sharing" 通过共享监控视图实现多代理协同。

落地部署清单

  1. 环境准备（macOS）：

    • 安装 Bun v1.0+：curl -fsSL https://bun.sh/install | bash
    • Git 2.20+、GitHub CLI：brew install git gh
    • Caddy：brew install caddy，配置 Caddyfile 代理 Electric SQL。

  2. 克隆与构建：

    git clone https://github.com/superset-sh/superset.git
cd superset
cp .env.example .env  # 编辑 API keys
bun install
bun run build
open apps/desktop/release

  3. Claude Code 多代理示例：

    • 新建工作区 1：preset1，setup 跑 claude-code init frontend/
    • 工作区 2：preset2，claude-code refactor backend/
    • 监控：观察变化面板，审阅 diff 后 ⌘⇧C 复制路径提交。

  4. 优化参数：

    参数 推荐值 说明
    max_workspaces 12 依机器调整
    agent_timeout 5min 工具执行上限
    notify_threshold 80% 资源警报
    retry_count 3 失败重试

风险：仅 macOS 稳定，Windows 测试中；依赖 Caddy 若端口冲突改 8080。回滚：删除 .superset 目录重置。

此方案将多代理从混乱终端转向工程化 IDE，提升 5x 开发速度。

资料来源：

查看归档