科学工具
科学工具让世界更美好
让世界更美好

GitHub AI自动化开发代理 Cairn 安装配置和使用指南GitHub AI自动化开发代理 Cairn 安装配置和使用指南

Cairn是一个开源的、与GitHub深度集成的后台代理系统,能自动化端到端软件开发流程,通过一个分层且协作的智能代理架构来执行任务:Fullstack Planner代理负责将复杂的开发任务分解为可并行执行的子任务,并协调不同模块(如前端与后端)之间的沟通;Project Manager代理负责将特定指令委派给Software Engineer代理、审查其代码变更、追踪任务依赖并生成最终的拉取请求;而Software Engineer代理则专注于实际的代码修改和实现。

Cairn支持广泛的大型语言模型(包括OpenAI、Anthropic和Gemini),允许用户在本地环境中连接到自己的GitHub仓库,并以100%后台运行的方式自动完成全栈开发任务。Cairn提供可选的仓库分析功能,能够深入洞察贡献者活动、编程语言分布和代码所有权。Cairn具备持久化记忆和可定制规则的能力,通过本地的.cairn目录存储代理学习到的仓库结构记忆和用户定义的编码规范,以提高自动化效率和代码一致性。

Cairn 支持的模型

提供商 状态 模型
🟢 Anthropic ✅ 已支持 Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5 等
🟢 OpenAI ✅ 已支持 GPT-4.1、GPT-4o、GPT-4、GPT-3.5-Turbo 等
🟢 Gemini ✅ 已支持 Gemini 2.5 Flash、Gemini 2.5 Pro、Gemini 2.0 Flash、Gemini 1.5 Pro 等
🟡 Deepseek 🚧 即将推出 -
🟡 Llama 🚧 即将推出 -

Cairn 安装配置

安装步骤

1、克隆代码仓库

git clone [email protected]:cairn-dev/cairn.git
cd cairn

2、安装依赖(推荐使用虚拟环境)

python -m venv cairn-env
source cairn-env/bin/activate  # Windows 系统使用 cairn-env\Scripts\activate
pip install -r requirements.txt

配置 GitHub 访问

Cairn 使用自托管的 GitHub 应用,需要读写权限来编辑代码仓库。

第一步:创建 GitHub 应用

• 个人账号:前往GitHub Apps 设置 https://github.com/settings/apps,点击“新建 GitHub 应用”

• 组织账号:访问 https://github.com/organizations/YOUR-ORG-NAME/settings/apps(替换为实际组织名称),点击“新建 GitHub 应用”

应用配置:

• 应用名称:“Cairn Agent for [你的用户名]”(需全局唯一)

• 描述:“Cairn 自动化开发代理”

• 主页 URL:https://try-cairn.com(或留空)

• webhook URL:留空

• webhook 密钥:留空

• 取消勾选 Webhooks 下的“激活”复选框

仓库权限:

• 内容:读写 ✅

• 拉取请求:读写 ✅

• 元数据:读取 ✅(自动选中)

安装范围:选择“仅在此账号” ✅

点击“创建 GitHub 应用”完成创建。

第二步:获取凭证并安装应用(需要 3 个值)

• 应用 ID:从应用设置页面复制(显示在顶部)

• 私钥:生成并下载 .pem 文件,保存到 Cairn 项目根目录

• 安装 ID:点击“安装应用”,选择仓库后安装,然后查看浏览器 URL:https://github.com/settings/installations/[INSTALLATION_ID]

第三步:配置环境变量和仓库

复制示例环境文件:

cp .env.example .env

编辑 .env 文件,填入以下配置:

# GitHub 应用凭证
GITHUB_APP_ID=你的应用 ID
GITHUB_PRIVATE_KEY_PATH=你的私钥文件.pem

# GitHub 个人访问令牌(用于仓库分析,可选)
# 从 https://github.com/settings/tokens 获取
# 所需权限范围:repo(私有仓库)或 public_repo(仅公有仓库)
GITHUB_TOKEN=你的 GitHub 令牌

# 大语言模型 API 密钥(可选,添加需要使用的)
ANTHROPIC_API_KEY=你的 Anthropic API 密钥
OPENAI_API_KEY=你的 OpenAI API 密钥
GEMINI_API_KEY=你的 Gemini API 密钥

在项目根目录创建或修改 repos.json 文件,结构如下:

{
  "你的 GitHub 用户名或组织": {
    "connected_repos": ["你的仓库名", "另一个仓库"],
    "installation_id": 12345678
  },
  "另一个所有者": {
    "connected_repos": ["不同的仓库"],
    "installation_id": 87654321
  }
}

运行 Cairn

python fastapi_app/app.py

然后在浏览器中访问 http://0.0.0.0:8000

任务执行演示

启动新代理

1、选择代理类型(全栈规划器、项目经理或软件开发工程师)

• SWE:适合简单独立的子任务,输出为包含变更的分支

• PM:适合稍复杂的子任务,将软件开发工作委托给 SWE,输出为详细说明变更的拉取请求

• 全栈规划器:适合全栈或多步骤任务,输出可并行运行的子任务列表,并在跨子任务代码需要时协调沟通

2、从已连接的仓库中选择目标仓库

3、用自然语言描述任务

4、通过实时日志和状态更新监控进度

仓库分析功能(可选)

Cairn 包含强大的仓库分析功能,提供对已连接仓库的洞察,包括:

• 贡献者统计:查看贡献者活动、提交次数和贡献模式

• 语言分布:了解仓库中使用的编程语言分布

• 代码所有权:跟踪哪些文件主要由哪些贡献者维护

• 提交模式:按时间、星期和月份分析开发活动

启用分析功能

1、生成个人访问令牌:前往 GitHub 设置 > 令牌,点击“生成新令牌(经典)”

2、选择适当的权限范围:公有仓库选择 public_repo,私有仓库选择 repo

3、将生成的令牌添加到 .env 文件:GITHUB_TOKEN=你的 GitHub 令牌

4、访问分析功能:在 Cairn 界面的仓库管理页面,点击任意已连接的仓库查看详细分析

Cairn 的设置与记忆机制

Cairn 通过 .cairn/ 目录在本地维护配置和记忆,首次在本地运行任务时会自动在项目根目录创建该目录。

目录结构

.cairn/
├── settings.json          # 全局和仓库特定规则
└── memory/
    ├── repo1.json         # 仓库1的记忆
    ├── repo2.json         # 仓库2的记忆
    └── ..、               # 其他仓库记忆文件

设置配置

通过 .cairn/settings.json 可定义代理必须遵循的自定义规则:

{
    "general_rules": [
        "始终使用 TypeScript 而非 JavaScript",
        "遵循现有代码风格和模式",
        "添加全面的错误处理"
    ],
    "repo_specific_rules": {
        "我的前端仓库": [
            "使用 React 钩子而非类组件",
            "遵循 src/components/ 中的现有组件结构"
        ],
        "我的后端仓库": [
            "使用 FastAPI 异步模式",
            "始终验证输入参数"
        ]
    }
}

仓库记忆

.cairn/memory/ 下的 JSON 文件为每个仓库存储持久化记忆,由代理生成。实际使用中,这能节省成本和时间,避免代理重复执行用于了解仓库结构的工具调用。

架构概览

Cairn 使用三个简单(且分层)的代理来完成任务,分别是 SWE、PM 和全栈规划器:

• SWE:专门负责代码变更

• PM:专门负责向 SWE 委派具体指令、检查 SWE 变更、跟踪依赖关系并创建拉取请求

• 全栈规划器:专门负责将大型任务分解为可并行运行的多个子任务,并协调相关并行任务之间的通信

以“从 Supabase 后端获取用户指标,并在前端以图表形式显示”这样的任务为例,若分配给全栈规划器,单个代理可以自己实现两个部分,但这比让一个代理实现后端、另一个代理实现前端的方式更慢(且上下文处理更差)。Cairn 通过并行化这个过程,允许处理前端和后端的代理相互通信,确保 API 路由和数据格式的一致性!

技术实现上,Cairn 使用子进程生成多个并行进程,以 SQLite 作为持久化数据库,并通过 FastAPI 提供简单的前端界面。

架构流程图:

graph TB
    UI[Web 仪表盘] --> API[FastAPI 后端]
    API --> WM[工作管理器]
    WM --> FP["全栈规划器代理<br/>(规划长期任务,<br/>协调整体工作流程)"]

    subgraph PM_LEVEL[" "]
        direction LR
        PM1["项目经理 1<br/>(生成完整 PR)"]
        PM2["项目经理 2<br/>(生成完整 PR)"]
        PM_MORE["..."]
    end

    FP --> PM1
    FP --> PM2
    FP --> PM_MORE

    PM1 --> SWE1["SWE1<br/>"]
    PM2 --> SWE2["SWE2<br/>"]

    SWE1 <-.->|a2a 通信| SWE2

    WM --> DB[(SQLite 数据库)]
    WM --> LS[日志存储]

    style PM_LEVEL fill:transparent,stroke:transparent

项目结构

cairn/
├── agent_worker/              # 代理执行引擎
│   ├── worker.py             # 主工作器实现
│   └── __main__.py           # CLI 入口点
├── cairn_utils/              # 核心工具和库
│   ├── agents/               # 代理实现,包括提示词
│   ├── github_utils.py       # GitHub API 集成
│   ├── toolbox.py           # 代理工具和功能
│   ├── task_storage.py      # 数据库操作
│   └── agent_classes.py     # 代理基类
├── fastapi_app/              #  web 界面
│   └── app.py               # FastAPI 应用
├── static/                   #  web UI 资产
├── docs/                     # 文档
├── examples/                 # 使用示例
├── .github/                  # GitHub 模板和工作流
│   ├── ISSUE_TEMPLATE/       # 问题模板
│   └── pull_request_template.md # PR 模板
└── tests/                    # 测试套件