关键词

AI 编码代理Git 工作流代码审查多代理编排任务规划

项目简介

Schaltwerk 是一款专为 AI 编码代理设计的桌面应用，它提供了一个直观的界面，用于管理和协调多个 AI 代理在 Git 项目中的开发工作流。通过利用 Git worktree 进行任务隔离和规范驱动的开发模式，Schaltwerk 能够高效地支持并发任务和实时代码审查。其内置的 Model Context Protocol (MCP) 服务器使得外部 LLM 客户端（如编排器代理）能够以标准化的方式与 Schaltwerk 进行交互，调用其提供的工具和访问资源，从而实现更高级别的 AI 代理自动化和编排能力。

主要功能点

  • AI 代理会话管理: 全面控制 AI 编码代理（例如 GitHub Copilot CLI、Claude Code 等）的生命周期。您可以创建、列出、启动、取消、暂停和恢复独立的开发会话，每个会话都拥有自己的隔离环境。
  • 规范 (Spec) 管理: 将 AI 代理的任务或指令以 Markdown 格式的“规范”进行定义和管理。支持创建、编辑、读取和删除这些规范，并能直接从规范启动 AI 代理，实现任务的规划与执行解耦。
  • Git 工作流集成: 为每个 AI 代理会话自动创建和管理独立的 Git 工作区及分支，确保代码更改的隔离性。提供查看代码变更摘要、详细差异，以及将已审查的会话合并到主分支或创建 Pull Request 的功能。
  • 多代理编排: 作为 MCP 服务器，允许一个 LLM 代理（编排器）通过调用 Schaltwerk 的工具来控制和协调其他多个 AI 编码代理，实现复杂的自动化开发流程。
  • 代码审查与会话状态: 支持对 AI 代理生成的代码进行 GitHub 风格的实时差异审查。会话可以被标记为“已审查”，表示其代码已准备好进行合并，并能在“活跃”和“规范”状态之间进行转换。

安装步骤

Schaltwerk 应用（包含 MCP 服务器）主要通过 Homebrew 进行安装。

  1. 系统要求: 确保您的系统满足以下条件：

    • macOS 11+ (Big Sur 或更高版本)
    • Git 2.30+
    • 至少安装一个您想使用的 AI 编码命令行工具，例如 GitHub Copilot CLI, Claude Code, OpenCode, Qwen, Amp 等。

  2. 安装命令: 打开终端，运行以下 Homebrew 命令：

    brew install --cask 2mawi2/tap/schaltwerk && open -a Schaltwerk

  3. 首次启动: 首次启动 Schaltwerk 时，macOS 可能会因为应用未经过 Apple 开发者认证而显示安全警告。请按照以下步骤解除阻止：

    • 尝试打开 Schaltwerk 应用程序（系统将阻止其运行）。
    • 打开“系统设置”→“隐私与安全性”。
    • 在窗口底部找到“Schaltwerk 已被阻止使用”或类似的消息。
    • 点击旁边的“仍要打开”按钮，并根据提示确认。 此操作仅需执行一次，之后应用即可正常启动。

服务器配置（供 MCP 客户端使用）

MCP 客户端需要配置以下信息才能连接到 Schaltwerk MCP 服务器。Schaltwerk 服务器会根据项目路径自动计算并尝试多个端口。

{
  "server_name": "schaltwerk-mcp-server",
  "command": "node",
  "args": [
    "/Applications/Schaltwerk.app/Contents/Resources/app.asar.unpacked/mcp-server/src/schaltwerk-mcp-server.ts"
  ],
  "env": {
    "SCHALTWERK_PROJECT_PATH": "/Users/youruser/Projects/my_project_repo"
  },
  "description": "连接到 Schaltwerk 应用程序的 Model Context Protocol (MCP) 服务器，用于管理 AI 代理会话和代码工作流。"
}

配置信息注释:

  • 'server_name': MCP 服务器的唯一标识符。
  • 'command': 启动 MCP 服务器的命令，这里是 'node'。
  • 'args': 传递给 'command' 的参数。'schaltwerk-mcp-server.ts' 是实际 MCP 服务器脚本的路径。请将上述示例路径 '/Applications/Schaltwerk.app/Contents/Resources/app.asar.unpacked/mcp-server/src/schaltwerk-mcp-server.ts' 替换为您实际 Schaltwerk 应用安装后该文件的准确路径。通常，它位于 'Schaltwerk.app' 应用程序包内部的 'Contents/Resources/app.asar.unpacked/mcp-server/src/' 目录。
  • 'env': 环境变量，用于向服务器传递上下文信息。'SCHALTWERK_PROJECT_PATH' 必须 设置为您希望 Schaltwerk 管理的 Git 项目的根目录（例如，您的代码仓库的顶层目录）。这有助于服务器正确识别项目并管理相关的 AI 代理会话。
  • 'description': 服务器功能的简要描述。

基本使用方法

一旦 MCP 客户端成功连接到 Schaltwerk MCP 服务器，您就可以通过调用服务器注册的工具和访问其资源来编排 AI 代理的工作流：

  1. 列出当前所有 AI 代理会话: 调用 'schaltwerk_list' 工具。例如，您可以通过 JSON 格式获取会话详情：

    // LLM 客户端调用
call_tool("schaltwerk_list", {"json": true, "filter": "all"})

  2. 创建一个新的 AI 代理任务 (会话): 使用 'schaltwerk_create' 工具，为 AI 代理分配一个具体的开发任务。

    // LLM 客户端调用
call_tool("schaltwerk_create", {
    "name": "implement-user-auth",
    "prompt": "实现一个基于 OAuth2 的用户身份验证模块，包括前端登录页面和后端 API 接口。",
    "agent_type": "claude",
    "base_branch": "main"
})

  3. 创建并完善任务规范 (Spec): 在启动代理前，您可以先创建和修改一个 Markdown 格式的“规范”来详细规划任务。

    • 创建规范： 
      // LLM 客户端调用
call_tool("schaltwerk_spec_create", {
    "name": "refactor-api-errors",
    "content": "# Refactor API Error Handling\n\n- Standardize error response format.\n- Implement centralized error logging."
})
    • 更新规范内容（追加或替换）： 
      // LLM 客户端调用
call_tool("schaltwerk_draft_update", {
    "session_name": "refactor-api-errors",
    "content": "\n- Add specific error codes for common scenarios.",
    "append": true
})

  4. 从规范启动 AI 代理: 当任务规范已准备就绪时，将其转换为一个活跃的 AI 代理会话。

    // LLM 客户端调用
call_tool("schaltwerk_draft_start", {
    "session_name": "refactor-api-errors",
    "agent_type": "opencode"
})

  5. 查看代码差异: 获取 AI 代理所做代码更改的摘要和详细差异，以便进行审查。

    • 获取文件更改摘要： 
      // LLM 客户端调用
call_tool("schaltwerk_diff_summary", {"session": "implement-user-auth"})
    • 获取特定文件的详细差异： 
      // LLM 客户端调用
call_tool("schaltwerk_diff_chunk", {"session": "implement-user-auth", "path": "src/auth_service.py"})

  6. 标记会话为已审查: 在代码审查并确认更改无误后，将任务会话标记为“已审查”，表示它已准备好合并。

    // LLM 客户端调用
call_tool("schaltwerk_mark_session_reviewed", {"session_name": "implement-user-auth"})

  7. 合并代码或创建 Pull Request: 将审查后的代码合并到父分支，或创建一个 GitHub Pull Request。

    • 合并会话： 
      // LLM 客户端调用 (例如，执行 squash 合并)
call_tool("schaltwerk_merge_session", {
    "session_name": "implement-user-auth",
    "mode": "squash",
    "commit_message": "feat: implement user authentication via OAuth2"
})
    • 创建 Pull Request： 
      // LLM 客户端调用
call_tool("schaltwerk_create_pr", {
    "session_name": "implement-user-auth",
    "options": {
        "default_branch": "develop",
        "commit_message": "feat: initial user auth",
        "cancel_after_pr": true
    }
})

  8. 取消会话: 如果任务不再需要，删除会话及其 Git 工作区和分支。对于包含未提交更改的会话，需要谨慎操作。

    // LLM 客户端调用 (强制取消，会丢失未提交工作)
call_tool("schaltwerk_cancel", {"session_name": "stale-feature-branch", "force": true})

信息

分类

开发者工具

访问项目