关键词

AI代理编排LLM上下文服务开发助手会话管理自动化开发

项目简介

Automagik Genie 是您的通用AI开发伴侣，旨在简化AI代理在任何代码库中的初始化、更新和编排。它提供了一个持久的对话式开发环境，让您可以像与人类伙伴交流一样与AI代理协作。Genie 的核心是一个MCP（Model Context Protocol）服务器，它允许LLM客户端发现和调用工具、访问项目资源并使用Prompt模板，从而实现AI代理对代码库的深度理解和功能扩展。它支持多种主流AI编程工具，并集成了智能更新、版本追踪和会话管理功能，确保AI代理始终与您的项目保持同步。

主要功能点

  • AI代理编排： 自动化初始化、更新和协调AI代理，使其能够跨任何代码库高效运行。
  • 持久会话管理： 维护AI代理的上下文，支持长时间、迭代式的开发对话，无需重复提供背景信息。
  • MCP服务器： 提供标准的Model Context Protocol (MCP) 接口，允许LLM客户端通过JSON-RPC协议调用Genie的内置工具、访问项目资源和利用预定义的Prompt模板。
  • 上下文感知： 托管和管理代码库中的资源（如文件、代码片段、文档），确保AI代理对当前项目拥有全面而准确的理解。
  • 工具调用： 允许LLM通过Genie的MCP工具执行外部功能，例如运行代码、查询项目状态、管理Git仓库等。
  • Prompt模板： 支持定义和渲染可定制的Prompt模板，用于指导LLM以特定模式进行交互，例如规划、实现、审查等。
  • 性能优化： 针对快速启动和高效执行进行了优化，减少AI代理的等待时间。
  • 自更新生态： 包含一套Git Hook自动化系统，自动维护文档、验证代码变更并强制执行质量标准。

安装步骤

在开始之前，请确保您的系统已满足以下前置条件：

  • Node.js 18+ (推荐使用 pnpm 10+ 进行测试)
  • Git (用于快照创建和版本控制)

1. 快速运行（无需永久安装 - 推荐用于测试）：

如果您只想快速体验Genie而不想在系统上进行永久安装：

  • Linux / macOS 用户请在终端运行： 
    curl -fsSL https://raw.githubusercontent.com/namastexlabs/automagik-genie/main/run.sh -o /tmp/genie-run.sh && bash /tmp/genie-run.sh
  • Windows 用户请在 PowerShell 运行： 
    $script = irm https://raw.githubusercontent.com/namastexlabs/automagik-genie/main/run.ps1; powershell -Command $script
    此命令会通过 'pnpm dlx' 运行Genie，不会在本地留下永久安装文件，适合快速测试。

2. 完整设置（永久安装 - 推荐用于长期使用）：

如果您希望在本地永久安装Genie及其所有依赖项：

  • Linux / macOS 用户请在终端运行： 
    curl -fsSL https://raw.githubusercontent.com/namastexlabs/automagik-genie/main/setup.sh -o /tmp/genie-setup.sh && bash /tmp/genie-setup.sh
  • Windows 用户请以 管理员身份 在 PowerShell 运行： 
    $script = irm https://raw.githubusercontent.com/namastexlabs/automagik-genie/main/setup.ps1; powershell -Command $script
    这些脚本会自动安装 Node.js 22、npm (如果需要) 和 pnpm 包管理器，并运行Genie的初始化流程。

3. 初始化您的项目：

在您的代码仓库目录中运行以下命令，为Genie创建一个 '.genie/' 工作区：

npx automagik-genie init

此命令将设置Genie所需的文件夹结构，包括代理定义和状态文件。

服务器配置（MCP客户端连接）

Genie 内置的MCP服务器是专门为LLM客户端设计的后端，用于提供上下文和工具能力。MCP客户端需要通过JSON-RPC协议与Genie MCP服务器通信。以下是几种典型的MCP客户端连接Genie MCP服务器的配置示例。

Genie MCP服务器支持多种传输协议，最常见的是 'stdio'（用于本地桌面应用，如Claude Desktop）和 'httpStream'/'sse'（用于远程或Web客户端）。

1. Claude Desktop 配置示例 ('~/.config/Claude/claude_desktop_config.json' 或 '%APPDATA%\Claude\claude_desktop_config.json')：

为了让 Claude Desktop 能够连接到 Genie MCP 服务器，您需要在其配置文件中添加以下 JSON 片段。通常，Claude Desktop 会通过 'stdio' 传输协议与本地 MCP 服务器通信。

{
  "mcpServers": {
    "automagik-genie": {
      "command": "npx",
      "args": ["automagik-genie", "mcp", "-t", "stdio"]
    }
  }
}
  • '"automagik-genie"'： 这是一个用户定义的MCP服务器名称，用于在Claude Desktop中识别该服务器。
  • '"command": "npx"'： 指定了用于启动Genie MCP服务器的系统命令是 'npx'。'npx' 会查找并执行已安装的 'automagik-genie' 包。
  • '"args": ["automagik-genie", "mcp", "-t", "stdio"]'： 这是传递给 'npx' 命令的参数列表。
    • '"automagik-genie"'：调用 'automagik-genie' 这个CLI工具。
    • '"mcp"'：指定运行Genie的MCP服务器模式。
    • '"-t", "stdio"'：指定 MCP 服务器使用标准输入输出（'stdio'）作为传输协议。

2. 其他MCP客户端（HTTP 或 SSE 传输）配置示例：

如果您的MCP客户端支持通过 HTTP 或 SSE（Server-Sent Events）进行通信，您可以配置Genie MCP服务器以这些模式启动，并为客户端提供相应的连接信息。

  • 启动 Genie MCP 服务器的命令示例：

    • HTTP Streaming 模式： 'npx automagik-genie mcp -t http -p 8080' （此命令会在本地端口 '8080' 上启动一个支持 HTTP Streaming 的 MCP 服务器。）
    • SSE (Server-Sent Events) 模式： 'npx automagik-genie mcp -t sse -p 8080' （此命令会在本地端口 '8080' 上启动一个支持 SSE 的 MCP 服务器。）

  • MCP 客户端的配置示例（假设 Genie MCP 服务器运行在 'http://localhost:8080'）：

    {
  "mcpServers": {
    "genie-http-stream": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    },
    "genie-sse": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}
    • '"genie-http-stream"' / '"genie-sse"'： 用户定义的MCP服务器名称。
    • '"type": "http"' / '"type": "sse"'： 指定MCP客户端期望的传输类型，需与服务器启动模式匹配。
    • '"url": "http://localhost:8080/mcp"' / '"url": "http://localhost:8080/sse"'： MCP 服务器的访问地址。

基本使用方法

配置好MCP客户端后，您可以通过客户端发送JSON-RPC请求来与Genie MCP服务器交互：

  1. 启动 Genie 服务器 (Forge 后端 + MCP 服务器)： 在您的项目根目录运行 'npx automagik-genie'。这将自动启动所有必要的后端服务，并提供一个实时的健康监控仪表盘。

  2. 列出可用的 AI 代理 ('list_agents')： 通过您的MCP客户端调用 'list_agents' 工具，获取Genie中所有AI代理的列表、它们的功能和描述。

    JSON-RPC 请求示例：

    {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_agents",
    "arguments": {}
  }
}

  3. 运行 AI 代理 ('run')： 使用MCP客户端调用 'run' 工具，指定代理ID（例如 '"plan"' 或 '"implementor"'）和详细的Prompt，AI代理将开始执行任务。

    JSON-RPC 请求示例：

    {
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "run",
    "arguments": {
      "agent": "plan",
      "prompt": "分析用户认证模块的现有架构，找出潜在的安全漏洞，并制定一个详细的改进计划。"
    }
  }
}

  4. 查看会话记录 ('list_sessions', 'view')： 首先调用 'list_sessions' 工具查看当前活动和最近的AI会话，以获取会话ID。然后，使用 'view' 工具和会话ID来查看会话的完整对话记录或最新消息。

    JSON-RPC 请求示例（列出会话）：

    { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "list_sessions", "arguments": {} } }

    JSON-RPC 请求示例（查看会话）：

    {
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "view",
    "arguments": {
      "sessionId": "您的会话ID，例如 'plan-2310171530'",
      "full": true
    }
  }
}

  5. 继续会话 ('resume')： 使用 'resume' 工具和会话ID，提供新的Prompt，继续与AI代理的对话，进行迭代式开发或提供额外上下文。

    JSON-RPC 请求示例：

    {
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "resume",
    "arguments": {
      "sessionId": "您的会话ID",
      "prompt": "针对上一步的计划，请详细说明如何实现其中的数据库迁移部分。"
    }
  }
}

  6. 停止会话 ('stop')： 使用 'stop' 工具和会话ID，终止正在运行的AI会话。会话状态会保留，以便后续查看。

    JSON-RPC 请求示例：

    {
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "stop",
    "arguments": {
      "sessionId": "您的会话ID"
    }
  }
}

Genie 还提供了多个预定义的 Prompt 模板，例如 'plan', 'wish', 'forge', 'review'，可以通过MCP客户端的 'prompts/list' 方法发现。这些模板能帮助LLM更好地理解并执行复杂的开发工作流。

信息

分类

开发者工具

访问项目