1. 为什么我要自己搭一个 CI 故障处理 Agent
CI 挂了，你打开 GitHub Actions 的日志页面，翻了 3000 行输出，最后发现是一个依赖包的版本号写错了。这种事我每个月至少遇到三四次。更烦的是，团队里每个人遇到 CI 挂掉都要重复这个流程：打开日志、定位报错、判断是环境问题还是代码问题、修、推、等结果。整个过程平均耗时 15 到 30 分钟，而且大部分时间花在“找问题”而不是“修问题”上。
所以我花了两个周末，搭了一个 DevOps AI Agent，专门干一件事：自动捕获 CI 故障、分析根因、给出修复建议，甚至直接提 PR。整套东西跑在 GitHub Actions 上，用 FastAPI 做服务层，Python 写核心逻辑，不依赖任何闭源平台。你把它挂到自己的仓库里，CI 一挂，它就开始干活。
这篇文章我会把整个搭建过程拆开讲清楚。从架构设计、日志捕获、错误分类、AI 分析、修复策略，到部署和踩坑记录，全部是实际跑过的方案。适合有一定 Python 基础、用过 GitHub Actions、想把手动运维变成自动化的开发者。不需要你之前搞过 AI Agent，但需要你愿意动手配环境。
先说清楚这个 Agent 能做什么、不能做什么。它能处理的是有明确报错信息的 CI 故障，比如依赖安装失败、测试断言失败、构建超时、环境变量缺失、语法错误。它不能处理的是基础设施层面的问题，比如 runner 挂了、网络抖动、GitHub 服务端故障。后面这类问题它会识别出来并告诉你“这不是代码问题，别瞎修”。
2. 整体架构设计与技术选型思路
2.1 为什么选 GitHub Actions + FastAPI + Python 这套组合
技术选型这件事，我的原则是：离 CI 系统越近越好，离开发者日常工具链越近越好。GitHub Actions 本身就是 CI 的执行环境，Agent 直接跑在里面，不需要额外维护一台服务器去轮询 CI 状态。FastAPI 负责提供一个轻量 HTTP 接口，用来接收 webhook、触发分析流程、返回结果。Python 则是 AI 生态最成熟的语言，调模型、做文本处理、写脚本都方便。
有人问为什么不用 Rust 写 Agent。Rust 确实性能好，但对于这种 IO 密集、逻辑不复杂的场景，Python 的开发效率优势太明显了。而且你调 AI 模型的时候，瓶颈在模型推理，不在你的代码执行速度。用 Rust 写只会让你多花三天调编译错误，少睡六个小时。
FastAPI 在这里的角色可能有人觉得多余——为什么不直接在 GitHub Actions 的 step 里跑 Python 脚本？原因是：你需要一个常驻服务来接收 webhook 并做异步处理。GitHub Actions 的 job 是临时的，跑完就没了。如果 CI 挂了之后你想让 Agent 自动分析，最优雅的方式是 CI 失败时触发一个 webhook，FastAPI 服务收到后启动分析流程，分析完再回调 GitHub API 提 comment 或 PR。这样 Agent 和 CI 解耦，不会因为 Agent 本身的问题影响 CI 执行。
2.2 Agent 的核心工作流拆解
整个 Agent 的工作流分四个阶段：
捕获阶段：CI job 失败时，GitHub Actions 触发一个workflow_run事件，把失败的 run_id、repo、branch、commit 信息发给 FastAPI 服务。服务收到后，调用 GitHub API 拉取失败 job 的完整日志。
分析阶段：日志拿到后，先做预处理——去掉 ANSI 颜色码、截断超长行、提取关键段落。然后做错误分类，判断是依赖问题、测试问题、构建问题还是环境问题。分类完成后，把相关日志片段和上下文一起发给 AI 模型，让它给出根因分析和修复建议。
修复阶段：根据 AI 的输出，Agent 判断是否可以自动修复。如果是依赖版本问题，直接改 requirements.txt 或 package.json；如果是环境变量缺失，生成配置建议；如果是代码逻辑问题，生成 patch 文件。能自动修的就提 PR，不能自动修的就在 PR 上留 comment 说明原因和建议。
反馈阶段：修复 PR 创建后，Agent 会监听后续 CI 结果。如果修复成功，标记问题已解决；如果失败，把新的错误信息追加到分析上下文，重新走一遍流程。这个循环最多跑三次，避免无限重试。
2.3 目录结构设计：FastAPI 项目怎么组织才不乱
FastAPI 项目最容易犯的错是把所有东西塞进一个main.py。我一开始也这么干，写到 800 行的时候自己都找不到函数在哪。后来改成模块化结构，清晰很多：
devops-agent/ ├── app/ │ ├── main.py # FastAPI 入口，注册路由 │ ├── config.py # 环境变量、常量配置 │ ├── models/ │ │ ├── request.py # webhook 请求体模型 │ │ └── response.py # API 响应模型 │ ├── services/ │ │ ├── github.py # GitHub API 封装 │ │ ├── log_parser.py # 日志预处理与错误分类 │ │ ├── ai_analyzer.py # AI 模型调用与分析 │ │ └── fixer.py # 修复策略执行 │ ├── core/ │ │ ├── workflow.py # 主流程编排 │ │ └── exceptions.py # 自定义异常 │ └── utils/ │ ├── text.py # 文本处理工具 │ └── retry.py # 重试装饰器 ├── tests/ ├── requirements.txt └── Dockerfile这个结构的好处是：每个模块职责单一，services下面每个文件对应一个外部依赖或核心能力，core/workflow.py负责把它们串起来。你改 GitHub API 调用不会影响到日志解析逻辑，换 AI 模型也不会动到修复策略。
2.4 AI 模型选型：本地模型还是 API 调用
这是很多人纠结的点。我的建议是：先用 API，跑通流程后再考虑本地化。原因很简单，你搭这个 Agent 的核心目的是验证“自动分析 CI 故障”这件事能不能跑通，而不是一开始就追求数据不出本地。API 调用开发成本低，模型能力强，适合快速迭代。
如果你确实需要本地跑模型，可以用 Ollama 加载开源模型。FastAPI 调 Ollama 的方式很简单，它兼容 OpenAI 的接口格式，你只需要把 base_url 改成http://localhost:11434/v1，api_key 随便填一个非空字符串就行。但要注意，本地模型的推理能力跟云端大模型有差距，对于复杂的 CI 错误分析，可能需要更精细的 prompt 工程来弥补。
我目前的方案是混合模式：简单错误分类用本地小模型，复杂根因分析走 API。这样既控制了成本，又保证了分析质量。
3. 核心细节解析与实操要点
3.1 日志捕获：怎么从 GitHub Actions 拿到完整日志
GitHub Actions 的日志获取有两个坑。第一个坑是日志是分 job 和 step 存储的，你需要先调/repos/{owner}/{repo}/actions/runs/{run_id}/jobs拿到所有 job，再对每个失败的 job 调/repos/{owner}/{repo}/actions/jobs/{job_id}/logs拿日志。第二个坑是日志返回的是重定向链接，需要跟随重定向才能拿到实际内容。
我用httpx写了一个封装：
import httpx async def fetch_job_logs(owner: str, repo: str, job_id: int, token: str) -> str: url = f"https://api.github.com/repos/{owner}/{repo}/actions/jobs/{job_id}/logs" headers = { "Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json" } async with httpx.AsyncClient(follow_redirects=True) as client: resp = await client.get(url, headers=headers) resp.raise_for_status() return resp.text注意follow_redirects=True这个参数，不加的话你拿到的是一个 302 响应，里面只有重定向地址，没有日志内容。我第一次调的时候没加，debug 了半小时才发现问题。
日志拿到后不能直接丢给 AI 模型，因为太长了。一个失败的 CI job 日志动辄几千行，直接塞给模型会超出 token 限制，而且大部分内容是无用的。我的做法是：先按行分割，找到包含error、failed、exception、Error:、FAILED等关键词的行，然后以这些行为中心，向上向下各取 20 行作为上下文。这样能把日志压缩到原来的 5% 到 10%，同时保留关键信息。
3.2 错误分类：让 Agent 知道自己在处理什么问题
错误分类是整个 Agent 最核心的逻辑之一。分类做不准，后面的 AI 分析和修复策略都会跑偏。我把 CI 故障分成六大类：
| 错误类型 | 典型特征 | 处理策略 |
|---|---|---|
| 依赖问题 | ModuleNotFoundError、Could not find a version、npm ERR! | 自动修复，更新依赖文件 |
| 测试失败 | AssertionError、FAILED tests/、Expected | 生成分析报告，人工确认 |
| 构建错误 | SyntaxError、Compilation failed、error TS | 生成 patch，提 PR |
| 环境问题 | command not found、Permission denied、No such file | 生成配置建议 |
| 超时问题 | Timeout、exceeded the maximum | 调整超时配置或优化建议 |
| 基础设施 | runner、network、503、rate limit | 标记为非代码问题，不修复 |
分类的实现方式我用的是规则匹配 + 模型兜底。先用正则和关键词做快速分类，如果匹配不到任何规则，再把日志片段发给 AI 模型做分类。这样大部分常见错误不需要调模型就能识别，省时省钱。
import re ERROR_PATTERNS = { "dependency": [ r"ModuleNotFoundError", r"Could not find a version", r"npm ERR!", r"Package .* not found" ], "test_failure": [ r"AssertionError", r"FAILED tests/", r"Expected .* but got" ], "build_error": [ r"SyntaxError", r"Compilation failed", r"error TS\d+" ], "environment": [ r"command not found", r"Permission denied", r"No such file or directory" ], "timeout": [ r"Timeout", r"exceeded the maximum" ], "infrastructure": [ r"runner", r"rate limit", r"503 Service Unavailable" ] } def classify_error(log_snippet: str) -> str: for category, patterns in ERROR_PATTERNS.items(): for pattern in patterns: if re.search(pattern, log_snippet, re.IGNORECASE): return category return "unknown"这个分类器不是百分百准确，但覆盖了 80% 以上的常见场景。对于unknown类型，我会把日志发给 AI 模型做二次分类，同时在 prompt 里明确告诉它“只返回类别名称，不要解释”。
3.3 AI 分析 Prompt 的设计要点
Prompt 设计直接决定分析质量。我试过很多版本，最后稳定下来的结构是这样的：
你是一个资深 DevOps 工程师，正在分析 CI 故障日志。 仓库：{repo} 分支：{branch} 触发事件：{event} 失败 job：{job_name} 以下是日志中的关键片段： {log_snippet} 请按以下格式输出： 1. 根因：一句话说明失败原因 2. 详细分析：解释为什么会出现这个问题 3. 修复建议：给出具体的修复步骤或代码修改 4. 是否可自动修复：yes/no 5. 置信度：0-100 注意： - 如果日志信息不足以判断根因，明确说"信息不足" - 不要猜测，只基于日志内容分析 - 修复建议要具体到文件和行号（如果可能）这个 prompt 的关键在于结构化输出和置信度评估。结构化输出让后续的修复模块可以直接解析，置信度则用来决定是否自动提 PR。我设定的阈值是：置信度大于 80 且可自动修复为 yes 时，才自动提 PR；否则只留 comment。
还有一个细节：我会在 prompt 里附上最近三次成功 CI 的日志摘要作为对比。这样模型能判断“这次失败是不是因为跟上次成功相比多了什么”。这个对比信息对分析环境类问题特别有用。
3.4 修复策略：哪些能自动修，哪些不能
自动修复这件事要非常克制。我的原则是：只自动修复那些“修复方式确定且风险可控”的问题。具体来说：
依赖版本问题可以自动修。比如日志显示ModuleNotFoundError: No module named 'requests'，Agent 会检查 requirements.txt 里有没有 requests，没有就加上，有但版本不对就调整版本号。这种修复是确定性的，不会引入新问题。
环境变量缺失可以自动修，但只生成建议不直接改。因为环境变量可能涉及敏感信息，Agent 会输出“需要在 GitHub Secrets 中添加 XXX”的提示，让人来操作。
代码逻辑错误不自动修。虽然 AI 可以生成 patch，但代码逻辑的修改需要人工 review。Agent 会生成一个 patch 文件作为 PR comment 的附件，开发者可以一键应用，但不会自动提交。
超时问题不自动修。超时通常是资源不足或代码效率问题，Agent 会分析超时发生在哪个 step，给出“增加 timeout 配置”或“优化测试用例”的建议，但不直接改配置。
基础设施问题直接跳过。Agent 会标记“非代码问题，建议重试”，然后结束流程。
4. 实操过程与核心环节实现
4.1 环境准备与依赖安装
先在你的开发机上把项目跑起来。Python 版本建议 3.11 以上，FastAPI 和 httpx 对新版本 Python 支持更好。
python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install fastapi uvicorn httpx pydantic python-dotenv如果你要用 Ollama 做本地模型，再装一个openai包，因为 Ollama 兼容 OpenAI 接口：
pip install openaiWindows 上打包 FastAPI 项目有个坑：uvicorn在 Windows 下默认用proactor事件循环，某些异步库会报错。解决办法是在启动时指定loop="asyncio"：
if __name__ == "__main__": import uvicorn uvicorn.run("app.main:app", host="0.0.0.0", port=8000, loop="asyncio")另外，uvicorn的日志在 Windows 下有时候会丢失，原因是它默认的日志配置跟 Windows 控制台不兼容。我一般会在main.py里显式配置 logging：
import logging logging.basicConfig( level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s" )4.2 FastAPI 服务端核心代码实现
服务端需要三个核心接口：接收 webhook、查询分析状态、手动触发分析。
from fastapi import FastAPI, BackgroundTasks, HTTPException from pydantic import BaseModel from app.services.github import fetch_failed_jobs, fetch_job_logs from app.services.log_parser import extract_error_snippet, classify_error from app.services.ai_analyzer import analyze_with_ai from app.services.fixer import apply_fix from app.core.workflow import run_analysis_pipeline app = FastAPI(title="DevOps AI Agent") class WebhookPayload(BaseModel): action: str workflow_run: dict @app.post("/webhook/ci-failure") async def handle_ci_failure(payload: WebhookPayload, background_tasks: BackgroundTasks): if payload.action != "completed": return {"status": "ignored"} run = payload.workflow_run if run.get("conclusion") != "failure": return {"status": "ignored"} background_tasks.add_task( run_analysis_pipeline, repo=run["repository"]["full_name"], run_id=run["id"], branch=run["head_branch"], commit=run["head_sha"] ) return {"status": "accepted", "run_id": run["id"]} @app.get("/analysis/{run_id}") async def get_analysis(run_id: int): result = await get_cached_analysis(run_id) if not result: raise HTTPException(status_code=404, detail="Analysis not found") return result这里用BackgroundTasks是因为日志拉取和 AI 分析可能耗时几十秒，不能让 webhook 请求一直等着。GitHub 的 webhook 超时时间很短，必须立即返回 200。
4.3 日志预处理与错误片段提取
日志预处理的目标是：把 5000 行日志压缩成 200 行以内的关键片段。我的做法分三步：
第一步，去掉 ANSI 颜色码和 GitHub Actions 的时间戳前缀。这些内容对分析没用，但会占用大量 token。
import re ANSI_ESCAPE = re.compile(r'\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])') TIMESTAMP_PREFIX = re.compile(r'^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z\s*') def clean_log(raw: str) -> str: lines = raw.splitlines() cleaned = [] for line in lines: line = ANSI_ESCAPE.sub('', line) line = TIMESTAMP_PREFIX.sub('', line) if line.strip(): cleaned.append(line) return '\n'.join(cleaned)第二步，定位错误行。我用一个关键词列表来匹配，包括error、failed、exception、traceback、fatal、cannot、unable to等。匹配到之后，以该行为中心，上下各扩展 20 行。
第三步，合并重叠的片段。如果两个错误片段之间有重叠，合并成一个大的片段，避免重复内容。
def extract_error_snippet(cleaned_log: str, context_lines: int = 20) -> str: lines = cleaned_log.splitlines() error_indices = [] keywords = ["error", "failed", "exception", "traceback", "fatal", "cannot", "unable to"] for i, line in enumerate(lines): if any(kw in line.lower() for kw in keywords): error_indices.append(i) if not error_indices: return cleaned_log[-3000:] # 没找到错误行就返回最后3000字符 ranges = [] for idx in error_indices: start = max(0, idx - context_lines) end = min(len(lines), idx + context_lines + 1) ranges.append((start, end)) # 合并重叠区间 merged = [] for start, end in sorted(ranges): if merged and start <= merged[-1][1]: merged[-1] = (merged[-1][0], max(merged[-1][1], end)) else: merged.append((start, end)) snippets = [] for start, end in merged: snippets.append('\n'.join(lines[start:end])) return '\n---\n'.join(snippets)这个提取逻辑实测能把 5000 行日志压缩到 150 到 300 行，同时保留所有关键错误信息。
4.4 AI 分析模块的完整实现
AI 分析模块负责调模型、解析输出、缓存结果。我用的是 OpenAI 兼容接口，这样换模型只需要改 base_url 和 model 名称。
import json from openai import AsyncOpenAI from app.config import settings client = AsyncOpenAI( base_url=settings.AI_BASE_URL, api_key=settings.AI_API_KEY ) ANALYSIS_PROMPT = """你是一个资深 DevOps 工程师，正在分析 CI 故障日志。 仓库：{repo} 分支：{branch} 失败 job：{job_name} 日志关键片段： {log_snippet} 请严格按以下 JSON 格式输出，不要添加任何其他内容： {{ "root_cause": "一句话根因", "detail": "详细分析", "fix_suggestion": "具体修复步骤", "auto_fixable": true/false, "confidence": 0-100, "error_category": "dependency/test_failure/build_error/environment/timeout/infrastructure/unknown" }} """ async def analyze_with_ai(repo: str, branch: str, job_name: str, log_snippet: str) -> dict: prompt = ANALYSIS_PROMPT.format( repo=repo, branch=branch, job_name=job_name, log_snippet=log_snippet[:8000] # 控制 token 长度 ) response = await client.chat.completions.create( model=settings.AI_MODEL, messages=[{"role": "user", "content": prompt}], temperature=0.1, response_format={"type": "json_object"} ) content = response.choices[0].message.content try: return json.loads(content) except json.JSONDecodeError: return { "root_cause": "AI 输出解析失败", "detail": content, "auto_fixable": False, "confidence": 0, "error_category": "unknown" }temperature=0.1是为了让输出更稳定，减少随机性。response_format={"type": "json_object"}强制模型输出 JSON，省去了解析自然语言的麻烦。但要注意，不是所有模型都支持这个参数，如果你用的模型不支持，就去掉这行，然后在 prompt 里更强调“只输出 JSON”。
4.5 自动修复与 PR 创建
修复模块根据 AI 的分析结果决定动作。我实现了一个简单的策略模式：
async def apply_fix(analysis: dict, repo: str, branch: str, token: str) -> dict: if not analysis.get("auto_fixable"): return {"action": "comment_only", "reason": "AI 判断不可自动修复"} if analysis["confidence"] < 80: return {"action": "comment_only", "reason": "置信度不足"} category = analysis.get("error_category") if category == "dependency": return await fix_dependency(analysis, repo, branch, token) elif category == "build_error": return await create_patch_pr(analysis, repo, branch, token) else: return {"action": "comment_only", "reason": f"暂不支持自动修复 {category}"}fix_dependency的逻辑是：解析 AI 给出的修复建议，提取包名和版本号，然后修改 requirements.txt 或 package.json，创建一个新分支，提交 PR。create_patch_pr类似，但生成的是代码 patch。
创建 PR 用 GitHub API 的/repos/{owner}/{repo}/pulls接口，注意要先创建分支和提交文件，再创建 PR。提交文件用/repos/{owner}/{repo}/contents/{path}接口，需要提供 base64 编码的文件内容。
4.6 GitHub Actions 侧的配置
在仓库里加一个 workflow 文件，监听 CI 失败事件：
name: CI Failure Agent on: workflow_run: workflows: ["CI"] types: [completed] jobs: notify-agent: if: ${{ github.event.workflow_run.conclusion == 'failure' }} runs-on: ubuntu-latest steps: - name: Notify DevOps Agent run: | curl -X POST ${{ secrets.AGENT_ENDPOINT }}/webhook/ci-failure \ -H "Content-Type: application/json" \ -d '{ "action": "${{ github.event.action }}", "workflow_run": ${{ toJson(github.event.workflow_run) }} }'AGENT_ENDPOINT是你 FastAPI 服务的地址。如果你部署在本地，需要有一个公网可访问的地址，或者用内网穿透工具。部署到云服务器的话，直接填服务器 IP 或域名。
5. 常见问题与排查技巧实录
5.1 日志拉取失败或返回空内容
这是最常见的问题。排查顺序如下：
先检查 token 权限。GitHub token 需要actions:read和repo权限。如果是 fine-grained token，确保勾选了 Actions 的读取权限。
再检查 job_id 是否正确。有时候 workflow_run 的 id 和 job 的 id 不是一回事，你需要先调/actions/runs/{run_id}/jobs拿到 job 列表，再用 job 的 id 去拉日志。
如果日志返回空字符串，可能是日志还没生成完。GitHub 的日志有延迟，CI 失败后立即拉取可能拿不到。我的做法是加一个 30 秒的延迟再拉，或者重试三次，每次间隔 10 秒。
5.2 AI 分析结果不准确或答非所问
先检查日志片段是否包含了足够的错误信息。如果提取的片段里只有Error: Process completed with exit code 1这种没有上下文的行，模型也没法分析。解决办法是扩大上下文行数，或者把整个失败 step 的日志都传进去。
再检查 prompt 是否清晰。我试过把 prompt 写得太复杂，模型反而不知道重点在哪。后来简化成“根因、详细分析、修复建议、是否可自动修复、置信度”五个字段，准确率明显提升。
如果模型经常输出“信息不足”，说明日志确实不够。这时候 Agent 应该输出“需要人工介入”，而不是强行给一个不靠谱的分析。
5.3 自动修复 PR 被 CI 再次拒绝
这种情况通常是因为修复不完整。比如依赖问题只修了一个包，但还有另一个包也缺失。解决办法是：在修复 PR 创建后，Agent 继续监听新的 CI 结果，如果再次失败，把新的错误信息追加到分析上下文，重新分析并生成补充修复。
我设置的最大重试次数是 3 次。超过 3 次就停止自动修复，留 comment 说明“自动修复未能解决，建议人工排查”。
5.4 FastAPI 服务在 Windows 下启动报错
Windows 下最常见的报错是NotImplementedError，原因是uvicorn默认用了proactor事件循环，而某些异步库不支持。解决办法是在启动命令里指定--loop asyncio：
uvicorn app.main:app --host 0.0.0.0 --port 8000 --loop asyncio另一个常见问题是端口被占用。用netstat -ano | findstr :8000找到占用进程，kill 掉再启动。
5.5 常见问题速查表
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 日志拉取返回 302 | 没跟随重定向 | httpx 加follow_redirects=True |
| AI 输出不是 JSON | 模型不支持 json_object | 去掉 response_format，强化 prompt |
| PR 创建失败 403 | token 权限不足 | 确保 token 有repo和workflow权限 |
| 分析结果缓存不生效 | 缓存 key 冲突 | 用 run_id + job_id 做唯一 key |
| Windows 下日志丢失 | uvicorn 日志配置问题 | 显式配置 logging.basicConfig |
| 修复 PR 反复失败 | 修复不完整 | 限制重试次数，超过后转人工 |
5.6 几个我踩过的坑和对应技巧
第一个坑：不要把整个日志传给 AI 模型。我一开始图省事，直接把 5000 行日志塞进去，结果 token 超限不说，模型还被无关信息干扰，分析质量很差。后来改成提取关键片段，准确率反而提升了。
第二个坑：置信度阈值不要设太低。我一开始设 60，结果 Agent 经常自动提一些不靠谱的 PR，反而增加了 review 负担。后来调到 80，自动修复的准确率明显提高，虽然自动修复的数量少了，但每个 PR 的质量都值得看。
第三个坑：缓存分析结果。同一个 run_id 可能会被多次查询，每次都调 AI 模型太浪费。我用 Redis 做缓存，key 是analysis:{run_id}，过期时间设 24 小时。没有 Redis 的话用内存字典也行，但服务重启就丢了。
第四个坑：处理 GitHub API 的 rate limit。GitHub API 对未认证请求限制很严，认证请求也有每小时 5000 次的限制。如果你的仓库 CI 很频繁，可能会触发限流。解决办法是加一个简单的令牌桶限流器，或者在请求头里带上If-None-Match做条件请求。
6. 部署方案与扩展思路
6.1 本地部署与云服务器部署的取舍
本地部署适合开发和调试阶段。你可以在自己电脑上跑 FastAPI 服务，用内网穿透工具暴露一个公网地址给 GitHub webhook 调用。好处是调试方便，改代码立即生效。坏处是电脑关机服务就挂了，不适合生产环境。
云服务器部署适合正式使用。一台 1 核 2G 的轻量服务器就够跑 FastAPI 和 Redis。部署方式我用的是 Docker + docker-compose，把 FastAPI 服务和 Redis 打包在一起，一条命令启动：
version: '3.8' services: agent: build: . ports: - "8000:8000" environment: - AI_API_KEY=${AI_API_KEY} - GITHUB_TOKEN=${GITHUB_TOKEN} depends_on: - redis redis: image: redis:7-alpine ports: - "6379:6379"Dockerfile 用 python:3.11-slim 做基础镜像，装依赖、拷贝代码、启动 uvicorn。注意要把--loop asyncio写进启动命令，避免在容器里也遇到事件循环问题。
6.2 后续可以扩展的方向
这个 Agent 目前只处理 CI 失败，但同样的架构可以扩展到更多场景。比如 CD 部署失败分析、代码 review 自动建议、issue 自动分类和打标签。核心逻辑都是“捕获事件 → 提取关键信息 → AI 分析 → 执行动作”，换的是输入源和输出动作。
另一个扩展方向是多仓库支持。目前的实现是单仓库单服务，如果你有多个仓库，可以做一个仓库注册表，webhook 里带上仓库标识，服务端根据标识路由到不同的配置。这样一套 Agent 可以服务整个团队的所有项目。
还有一个有意思的方向是故障知识库。每次分析的结果都存下来，形成一个“错误特征 → 根因 → 修复方案”的知识库。下次遇到类似错误时，先查知识库，命中就直接用历史方案，没命中再调 AI 模型。这样随着使用时间增长，Agent 的分析速度和准确率都会提升。
6.3 成本控制与性能优化
AI 模型的调用成本是主要开销。我的优化策略是：简单错误分类用规则匹配，不调模型；复杂分析才调模型；相同错误特征的结果缓存复用。实测下来，一个中等规模的仓库（每天 20 到 30 次 CI），每月 AI 调用成本控制在很低的水平。
性能方面，日志拉取和 AI 分析是主要耗时环节。日志拉取可以并行化，多个失败 job 同时拉。AI 分析是串行的，因为要控制并发避免触发 rate limit。整体从 webhook 触发到 PR 创建，平均耗时 40 到 60 秒，完全可以接受。
6.4 安全注意事项
GitHub token 和 AI API key 必须放在环境变量里，不能硬编码在代码中。GitHub Actions 侧用 secrets 存储，FastAPI 服务侧用.env文件或容器环境变量。
日志内容可能包含敏感信息，比如数据库连接串、内部 API 地址。在把日志发给 AI 模型之前，建议做一次脱敏处理，用正则替换掉密码、token、IP 地址等敏感字段。我实现了一个简单的脱敏函数，匹配password=xxx、token=xxx、\d+\.\d+\.\d+\.\d+等模式并替换成***。
webhook 接口要做签名验证，防止伪造请求。GitHub 的 webhook 支持 secret 签名，在 FastAPI 里验证X-Hub-Signature-256头，不匹配的直接拒绝。
这套东西我跑了三个月，处理了 200 多次 CI 故障，自动修复成功率大概在 65% 左右。剩下的 35% 里，大部分是代码逻辑问题需要人工判断，少部分是基础设施问题 Agent 直接跳过。最明显的收益是：团队里没人再花时间翻 CI 日志了，打开 PR 就能看到 Agent 的分析 comment，直接决定是点“应用修复”还是自己改。
