项目简介 Pullfrog GitHub Action 是一款强大的工具，它通过托管一个内部的 Model Context Protocol (MCP) 服务器，作为 GitHub 事件与多种 AI 编码代理之间的桥梁。它允许您在 GitHub 仓库中，通过评论、Web 界面或自动化触发器，调用 AI 代理执行复杂的编码任务、进行代码审查、自动响应 Issue 或其他自定义操作。Pullfrog 旨在提升开发效率，自动化重复性工作，并将上下文感知的 AI 能力无缝融入您的开发流程。

主要功能点

AI 代理集成： 支持 Anthropic Claude、OpenAI Codex、Cursor、Google Gemini 等主流 AI 编码代理。
自动化工作流： 响应 GitHub 事件（如 Issue 创建、PR 提交、评论标记等）自动触发 AI 代理运行。
上下文感知： 通过内置 MCP 服务器为 AI 代理提供丰富的 GitHub 仓库上下文（代码、Issue、PR、评论、CI 日志等）。
任务自动化： AI 代理可自动执行编码、创建 PR、修复 CI 失败、回复审查意见等。
灵活的交互模式： 支持通过 GitHub 评论、Pullfrog Web Dashboard 进行手动触发和配置。
多种操作工具： MCP 服务器提供了丰富的工具，如创建/编辑 Issue/PR/评论、获取 Issue/PR 信息、获取 CI 检查套件日志、文件列表等，供 AI 代理调用。
可定制的提示模板： 支持通过“模式选择”工具，为 AI 代理提供特定的任务指令（如“构建”、“审查”、“规划”等）。

安装步骤 Pullfrog 通常作为 GitHub App 安装，但在本仓库中，我们关注其作为 GitHub Action 的使用。您可以手动配置 GitHub Actions 工作流来运行 Pullfrog。

创建 'pullfrog.yml' 工作流文件： 在您的仓库 '.github/workflows/' 目录下创建 'pullfrog.yml' 文件。这是一个可复用工作流，用于实际运行 Pullfrog Action。

name: Pullfrog
on:
  workflow_dispatch:
    inputs:
      prompt:
        type: string
        description: "Agent prompt"
  workflow_call:
    inputs:
      prompt:
        description: "Agent prompt"
        type: string

permissions:
  id-token: write
  contents: read

jobs:
  pullfrog:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 1
      - name: Run agent
        uses: pullfrog/action@main # 建议使用特定版本标签，例如 v1.0.0
        with:
          prompt: ${{ inputs.prompt }}
          # 根据您选择的AI代理，提供相应的API密钥。
          # 例如，如果您使用 Claude：
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # 或者 OpenAI：
          # openai_api_key: ${{ secrets.OPENAI_API_KEY }}
          # 或者 Gemini：
          # google_api_key: ${{ secrets.GOOGLE_API_KEY }}
          # gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
          # 或者 Cursor：
          # cursor_api_key: ${{ secrets.CURSOR_API_KEY }}

重要提示： 请确保将所需的 API 密钥存储为 GitHub 仓库 Secrets (例如 'ANTHROPIC_API_KEY')，以保证安全。

创建 'triggers.yml' 工作流文件（可选，用于自动化触发）： 在您的仓库 '.github/workflows/' 目录下创建 'triggers.yml' 文件。此工作流监听 GitHub 事件并调用 'pullfrog.yml'。

name: Agent Triggers

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]
  pull_request_review:
    types: [submitted]
  # 添加其他您需要的触发器，例如 pull_request: [opened, labeled]

jobs:
  pullfrog:
    # 触发条件：例如，仅当评论内容包含 '@pullfrog' 时运行
    if: contains(github.event.comment.body, '@pullfrog') || contains(github.event.issue.body, '@pullfrog')

    permissions:
      id-token: write
      contents: write
      issues: write
      pull-requests: write
      actions: read
      checks: read
    uses: ./.github/workflows/pullfrog.yml
    with:
      # 将完整的 GitHub 事件 Payload 作为 Prompt 传递给 Pullfrog
      prompt: ${{ toJSON(github.event) }}
    secrets: inherit

服务器配置 Pullfrog 在 GitHub Actions 运行时会启动一个内部的 MCP HTTP 服务器。AI 代理（MCP 客户端）将连接到这个服务器来调用 GitHub 操作工具。

服务器名称 (Server Name): 'gh_pullfrog' 这个名称是 Pullfrog 内部硬编码的，用于标识其提供的 GitHub 相关工具集。
传输协议 (Transport Protocol): HTTP Stream Pullfrog 的 MCP 服务器通过 HTTP Stream 方式提供服务。
MCP 客户端的连接方式： 在标准的 GitHub Actions 运行中，Pullfrog Action 会自动启动其内部的 MCP 服务器。它会设置一系列环境变量（例如 'PULLFROG_MCP_SERVER_URL'），使集成的 AI 代理（如 Claude Agent CLI, Gemini CLI）能够自动发现并连接到这个服务器。因此，AI 代理作为 MCP 客户端通常不需要手动配置启动命令，而是由 Pullfrog Action 负责初始化和连接。

如果一个通用 MCP 客户端需要在 GitHub Actions 外部启动 Pullfrog 作为其 MCP 服务器，它将需要运行 Pullfrog GitHub Action 的编译入口点 ('entry' 文件)，并模拟 GitHub Actions 运行时环境。这通常是一个复杂且不常见的场景，但理论上其启动命令和参数大致如下：
- 命令 (Command): 'node'
- 参数 (Args):
  - 'path/to/pullfrog/action/dist/entry' (这是 Pullfrog GitHub Action 编译后的主执行文件路径)
  - '--prompt "<YOUR_INITIAL_PROMPT_OR_PAYLOAD_JSON>"' (AI 代理的初始提示或结构化输入)
  - '--anthropic_api_key "<YOUR_ANTHROPIC_API_KEY>"' (如果使用 Claude，请提供 Anthropic API 密钥，根据选择的代理提供相应密钥)
  - '--openai_api_key "<YOUR_OPENAI_API_KEY>"' (如果使用 OpenAI 代理)
  - '--google_api_key "<YOUR_GOOGLE_API_KEY>"' / '--gemini_api_key "<YOUR_GEMINI_API_KEY>"' (如果使用 Gemini 代理)
  - '--cursor_api_key "<YOUR_CURSOR_API_KEY>"' (如果使用 Cursor 代理)
- 环境变量 (Environment Variables): MCP 客户端在启动 Pullfrog 服务器进程时，需要设置以下环境变量以提供必要的上下文：
  - 'GITHUB_REPOSITORY': 格式为 'owner/repo' (例如: 'myorg/myrepo')，指示当前操作的 GitHub 仓库。
  - 'GITHUB_RUN_ID': GitHub 工作流运行的唯一 ID。
  - 'PULLFROG_PAYLOAD': 一个 JSON 字符串，包含 Pullfrog 内部的 'Payload' 结构，描述了触发事件、选定代理、Prompt 等信息。这个 Payload 是 MCP 服务器理解上下文的关键。
  - 'PULLFROG_MODES': 一个 JSON 字符串，包含所有可用的“模式”定义（名称、描述和详细提示）。
  - 'API_URL': Pullfrog 后端服务的 API 地址，默认为 'https://pullfrog.ai'。
  - 'LOG_LEVEL': 日志级别 (例如: 'info', 'debug')。
  - 'HOME': 用户主目录路径，用于某些代理的配置或临时文件。
  - 'PATH': 系统可执行文件路径，确保 'node' 和其他工具可用。
- MCP 服务器 URL 发现： Pullfrog 服务器启动后，会监听一个随机端口（通常从 3764 开始）。其完整的 URL (例如 'http://127.0.0.1:3764/mcp') 会通过标准输出或特定环境变量（但实际 Pullfrog 内部是直接传给代理 SDK 的）提供给连接的客户端。通用 MCP 客户端需要解析这个 URL 来建立连接。

基本使用方法 一旦您按照上述步骤设置了 GitHub Actions，您就可以开始使用 Pullfrog 了：

手动触发：
- 在 GitHub 仓库中，导航到 “Actions” 选项卡。
- 选择 “Pullfrog” 工作流 (如果创建了 'pullfrog.yml')。
- 点击 “Run workflow” 按钮，并填写 'prompt' 输入框，例如：“实现一个新功能：创建一个名为 'hello.txt' 的文件，内容为 'Hello Pullfrog!'”。
- 点击 “Run workflow” 开始执行。
通过评论触发（需要 'triggers.yml'）：
- 在您的 GitHub 仓库的 Issue 或 Pull Request 评论中，提及 '@pullfrog' 并附上您的指令，例如： '@pullfrog 请审查这个 PR 的代码质量。'
- 'triggers.yml' 将会检测到这条评论，并触发 'pullfrog.yml' 工作流运行，将评论内容作为 Prompt 传递给 AI 代理。
自动化触发（需要 'triggers.yml' 及配置）：
- 您可以配置 'triggers.yml' 监听各种 GitHub 事件，例如当一个 Issue 被创建时，或者一个 PR 提交时。
- 在 'triggers.yml' 中，您可以定义不同的 'prompt' 逻辑来响应这些事件。例如，当 PR 创建时，自动触发 AI 代理进行代码审查。

Pullfrog 将会启动选定的 AI 代理，该代理将通过 Pullfrog 的 MCP 服务器调用 GitHub API 工具来执行任务，并在 GitHub 上留下相应的评论、创建 PR 或 Issue。

关键词

信息