最近团队里CI的失败有一半是重复问题依赖lockfile没更新、临时文件里漏了个import、环境变量少配置了。每次都要人打开日志翻半天很烦。我就用了一个周末搭了个DevOps AI Agent出来让它自动接住CI失败事件分析日志然后按预设规则直接开一个修复PR。这篇文章就围绕这个Agent的实际搭建过程来写核心是三个动作捕获、分析、修复技术栈是Webhook 大模型API 一点常规脚本。适合已经在维护CI、但还没开始把AI加进来的DevOps工程师参考也适合想给自家CI“找个机器人助理”的团队。1. 先想清楚这个Agent到底要解决什么问题1.1 解决的是“救火式”处理故障的效率问题很多团队的CI流程其实已经很完善了lint、单测、集成测试、镜像构建全都有可一旦有任务失败后续流程基本靠人肉。值班同学收到一个失败通知先打开Actions页面再翻日志找到报错然后决定是重跑、改代码还是去问写那个模块的同事。整个过程视复杂程度而定短则十分钟长则一下午。Agent并不是要把所有故障都自动修好这不现实。它真正能解决的是那些“重复出现的高频问题”比如依赖安装失败、TypeScript类型导出缺失、文件路径大小写敏感、格式检查不过等等。这些问题的日志特征鲜明处理方式也高度标准化非常适合写成规则或者让大模型快速识别。所以这个Agent的定位不是替代工程师而是把“重复劳动”先消化掉让真正需要人来判断的异常能更快被转交上去。1.2 为什么把流程切成捕获、分析、修复三段我一开始也想做成一个大而全的Agent后来发现越大的闭环越难调试。最稳妥的做法是把流程拆成三个独立的阶段捕获、分析、修复。捕获负责从CI平台拿到失败事件分析负责从日志中找出根因修复负责产出diff并提交PR。每个阶段都有清晰的输入输出后续想升级其中一环不会影响另外两环。另外三个阶段解耦之后可以分别做安全控制。捕获阶段只需要仓库读取权限分析阶段可以不碰真实代码修复阶段单独使用一个受限Token。这样的话即使Agent某个环节被攻击或者误触发影响面也是可控的。边界其实就是安全边界我第一次上线时就是因为没有分开权限管理结果一个越权调用导致Agent能动生产仓库现在想想都后怕。2. 方案选型如何搭出可落地的Agent主骨架2.1 事件驱动是Agent的命脉Agent不一定要是一个常驻后台的“超级循环”。对于CI运维这个场景最优雅的做法是事件驱动CI失败时平台发一个Webhook过来Agent收到事件后开始干活没事件时完全不消耗资源。这跟人类工作的模式很像没有人会24小时不停刷新CI状态都是等通知来了再处理。我选了GitHub Actions作为第一个接入对象因为它的Webhook事件很成熟。比如workflow_run事件会在工作流完成或失败时触发check_suite事件能覆盖更细的检查状态。接收端也不需要刻意轮询REST API省掉了大量无效请求。如果你的CI平台是GitLab CI也可以直接看pipeline事件的statusfailed原理一致。2.2 核心工具链怎么选实际动手前需要确定一套顺手的技术栈。我使用的是Python生态理由很简单生态丰富写原型快团队里后续想改也容易招人。接收端用FastAPI轻量且天然支持异步日志分析和修复建议调用支持OpenAI兼容协议的大模型API这样以后想换本地模型或者商业模型都只需要改配置仓库操作用Git CLI加GitHub CLI因为它的REST API封装得很完整。有人可能会问为什么不直接用某种Agent框架。说实话这个场景里Agent框架带来的复杂度大于收益。框架帮你编排多Agent协作但我们这里其实只需要一个能跑通“日志输入到PR输出”的流水线自己写用不了多少代码而且每个环节都能肉眼Debug。等将来需要多个Agent协同分析、互相复核时再考虑框架也不迟。2.3 为什么要用“LLM 规则”双引擎这是整个项目里我最坚持的设计。只用LLM模型有时候会一本正经地给出一个完全错误的修复建议尤其在日志上下文被截断的时候。只用规则又覆盖不了那些描述清楚但格式不固定的编译报错。我的做法是让规则先跑一遍用正则锁定能明确识别的错误类型比如Cannot find module、SyntaxError、ESLint格式错误等如果规则匹配不到再交给LLM做自由分析。这样做的好处很直接常见的错误零成本秒回不用烧token复杂的错误交给大模型时我们还可以把规则已识别出的“非匹配特征”一起放进Prompt帮它缩小分析范围。在成本和准确率之间这个双引擎组合是我目前试过最均衡的方案。3. 实操一步一步构建第一个AI Agent3.1 先搭一个能跑起来的最小骨架建议不要一上来就做全自动修复先跑通接事件、取日志、吐建议这条链路。项目结构可以这样组织agent/ ├── webhook_server.py # 接收CI平台事件 ├── analyzer.py # 规则LLM分析日志 ├── fixer.py # 生成修复PR ├── config.yaml # 模型、仓库、权限配置 └── requirements.txt我用的依赖只有fastapi、uvicorn、requests、openai、PyGithub。GitHub CLI是外部命令直接调用这比在Python里封装所有API要省事得多。实际写代码时我发现把Git操作交给CLI能让Agent更容易被其他人理解和维护毕竟大家平时敲命令都敲熟了。3.2 第一步接收CI失败事件FastAPI写Webhook入口非常简单。核心点在于接收事件后先确认事件类型是CI失败再拿到仓库名和运行ID最后丢给分析模块。from fastapi import FastAPI, Request, Header import logging app FastAPI() app.post(/webhook/ci) async def receive_ci_event(request: Request, x_github_event: str Header(None)): payload await request.json() if x_github_event workflow_run and payload.get(action) completed: run payload[workflow_run] if run[conclusion] failure: logging.info(captured failed run %s, run[id]) # 交给下一步分析 analyze(run[id], run[head_branch]) return {ok: True} return {ok: True}生产环境不要漏掉签名校验。GitHub的Webhook会在请求头里带X-Hub-Signature-256你需要在本地用Webhook Secret对请求体算HMAC然后比对。别图省事跳过这一步不然任何人都能伪造一个失败事件来触发你的Agent干活。3.3 第二步缩小故障范围CI日志动辄几十万行直接扔给大模型又贵又超上下文。必须先做一次裁剪。我按失败步骤切出日志块再去找错误标记。GitHub Actions的日志里失败步骤通常以##[error]开头只要定位到第一个错误标记把前后各100行取出来就够用了。def extract_failure_snippet(log_text: str, window: int 100) - str: lines log_text.splitlines() for idx, line in enumerate(lines): if ##[error] in line or Error: in line: start max(0, idx - window) end min(len(lines), idx window) return \n.join(lines[start:end]) return \n.join(lines[-200:])这个步骤的原理是大多数错误的原因都聚集在标志点附近不需要看整个工作流过程。如果你发现某个错误标志点前后信息不够再考虑扩大窗口。实测下来200行上下文能覆盖九成以上的编译错误和依赖问题。3.4 第三步让Agent按结构化格式分析日志拿到日志片段后就要构建Prompt。为了让后续自动化链路稳定我让大模型必须输出JSON而不是自由文本。结构是这样{ error_type: missing_dependency, confidence: 0.9, root_cause: npm install之后package-lock.json未同步提交, suggestion: 运行npm install并提交package-lock.json }Prompt我写得很直白没有绕弯子。比如你是CI故障分析助手。下面是一段来自GitHub Actions的失败日志。 请判断失败原因并严格按JSON格式返回。 字段包括error_type, confidence, root_cause, suggestion。 不要输出额外解释。调用时把temperature设为0.2max_tokens限制在500以内。温度太高会让模型发挥不稳定我见过一次它分析出完全不存在的依赖问题就是因为参数没控住。结构化输出可以直接被下一阶段的修复逻辑消费省去了写一堆正则解析自然语言的麻烦。3.5 第四步把分析结果变成修复动作从JSON里拿到error_type后Agent需要调用“工具”来执行修复。我实现的方式很简单定义一组函数比如update_dependency_versions()、fix_typing_import()、generate_auth_config()然后根据错误类型路由到对应函数。这里的关键是“工具是可控的”不要让模型自己随便选函数执行而是由我们的规则层决定允许哪些工具。还有一个原则不是所有错误都该自动修复。比如测试断言失败、业务逻辑错误Agent只能标记出来转人工坚决不生成改动。因为自动改逻辑风险极高很可能修了一个bug又引入另一个bug。我们做的是CI故障自愈不是代码生成器必须克制。3.6 第五步自动提交修复PR确认修复内容没问题后Agent的工作是创建分支、提交改动、开PR。我直接用GitHub CLI代码里就是顺序执行几个命令git checkout -b fix/ci-$RUN_ID git add package-lock.json git commit -m fix: sync package-lock.json after npm install git push origin fix/ci-$RUN_ID gh pr create --base main --title fix: sync package-lock.json --body agent auto-generated这里要特别强调不要让Agent直接合并PR。只创建PR然后通知群里的同事来review这个默认行为能帮你挡掉绝大多数事故。我在PR标题上加了[agent]前缀这样同事一看就知道这活是机器人干的review时会更留个心眼不会因为“看起来很简单”就随手合掉。3.7 预留一份最小配置所有可变参数我统一放到config.yaml里不让代码里到处是硬编码ci_platform: github repository: owner: my-team name: my-service llm: base_url: https://api.openai.com/v1 model: gpt-4o-mini temperature: 0.2 max_tokens: 500 fix_rules: enable_typescript_import_fix: true enable_lockfile_fix: true max_retries: 1 safe_paths: - src/**/auth/** - deploy/** - .env*环境变量用来存放密钥比如GITHUB_TOKEN、WEBHOOK_SECRET、LLM_API_KEY坚决不写进配置文件。这样在服务器上部署时开发环境、测试环境、生产环境之间切换只需要透传不同的环境变量代码不用改。4. 故障演练从一个真实失败的GitHub Actions日志走一遍流程4.1 日志输入样例为了演示Agent怎么工作我拿一个实际的报错当样本。假设我们的仓库用TypeScript某次CI出现这样的日志片段Error: Cannot find module undici Require stack: - /home/runner/work/app/app/node_modules/octokit/request/dist-node/index.js ... at Object.anonymous (/home/runner/work/app/app/node_modules/octokit/request/dist-node/index.js:96:17)只看这段日志第一反应是“某个依赖没装齐”。但具体是package-lock.json没更新还是node_modules缓存坏了需要进一步分析。4.2 Agent的完整推理过程我的Agent会先走规则引擎。规则里有一条当日志中出现Cannot find module并且匹配到node_modules路径时直接归类为missing_dependency置信度设为0.95。规则条件满足Agent就不会再调用LLM节省了时间和费用。拿到missing_dependency之后修复函数先检查package.json和package-lock.json的diff确认是否有依赖版本不一致如果有不一致Agent自动运行一次npm install --package-lock-only把生成的lockfile变化提交然后推送分支开PR。这整个过程不需要大模型参与靠规则就能完成。4.3 上下文与参数细节如果规则没命中才把裁剪后的日志片段交给LLM。此时参数是这样设置的日志片段最大长度6000字符温度0.2最多返回500个token的JSON。为什么是6000因为我用的模型上下文窗口完全够但再长的话日志里不相关的步骤会导致模型注意力分散。要是发现错误段落在很后面的位置我会提高窗口长度而不是直接截开头。模型返回JSON后有一个“置信度门禁”。confidence低于0.8时不自动提PR而是给值守群发送一条待处理消息附上分析结果只有置信度高于0.8时agent才真正去创建PR。这个门禁帮我挡住了几次离谱建议其中包括一次让模型把正常日志错误地解释为“数据库连接池耗尽”。5. 常见问题与排查技巧5.1 日志被截断了怎么办最常用的日志裁剪方法是取错误标记前后N行但有些错误触发点不在终端输出里而在后面的构建步骤里。比如Docker构建失败时最终的异常信息可能离最初失败点很远。我踩过这个坑。解决办法是在裁剪函数里增加一个“尾部兜底”策略如果日志中没有匹配到##[error]就返回最后300行如果匹配到了但后面的行中包含诸如exit code 2这样的结束标记就把结束标记之前的500行一起带上。实测下来这样能保证Docker构建、增强型检测等场景下的错误上下文不丢。5.2 模型产生幻觉改错了代码最开始我让Agent直接在修复PR里提供“建议代码”结果有一次它给了一个完全不存在的API调用理由是根据文档“猜测的”。这让我意识到大模型在生成代码这个场景里风险很高。后来我改成不让模型直接写大段代码只允许模型做三件事判断错误类型、给修复方向、评估置信度真正的diff由我们预先写好的修复函数生成。宁可让修复手段更保守也不要让模型撒欢。对于需要复杂代码改动的错误Agent会生成一个详细分析Issue并负责该模块的同事。这样既保留了大模型的分析能力又避免了它无中生有地改代码。5.3 重试风暴这是自动化系统最容易踩的坑。Agent创建PR后PR本身会触发CI如果修得不对CI会再次失败然后Agent再次收到Webhook再去创建新的修复PR。我亲眼见过一个仓库半小时内被Agent开了6个PR全是同一个问题的不同修法。解决办法是幂等控制。我维护了一张Redis表以CI run ID为key只有第一次遇到该ID才执行修复后续相同ID的事件直接忽略。另外设置max_retries: 1同一分支如果已经存在自动创建的PR就不会再创建第二个。现在即使又遇到失败最差情况也就是多跑一次不会刷屏。5.4 API成本与速率限制如果不做规则引擎每次CI失败都调大模型一个月账单会很难看。我的规则引擎命中率大概在60%左右也就是说六成错误不花一分token就能处理。剩下的四成会调用大模型但也要做两层缓存第一层把日志的hash和结果存下来同样日志不再重复请求第二层按错误类型和仓库名做缓存如果同一个仓库一周内反复出现同类型错误第二次就直接用缓存结果。速率限制方面大模型API会返回429状态我的重试策略是等1秒、2秒、4秒指数退避最多试3次。不建议无限重试因为很多CI失败不是一次请求就能解决的重试太多次只会拖垮流程。6. 安全基线权限控制与人在回路6.1 最小权限原则Agent用的Token绝对不能是仓库管理员Token。我单独建了一个机器人账号给它只授予目标仓库的pull requests: write和contents: write权限但不给checks: write和actions: write也不给secrets读取权限。这意味着Agent可以推分支、开PR但无法修改分支保护规则也无法读取安全配置。权限控制的核心逻辑是Agent的所有行为都只能创建“可审查的变更”不能直接造成不可逆影响。例如它不能关闭某个环境、不能签发新密钥、不能调整仓库设置。如果业务上确实需要Agent执行更高风险的动作那也应该通过人工确认的另外一条通道去做而不是放在Agent主流程里。6.2 审计与回滚我在项目里加了一个审计动作Agent每执行一步操作都会往单独的ops-audit仓库提交一条记录内容包括触发时间、CI run ID、错误类型、生成的PR号、使用的模型和上下文摘要。这个审计日志对后续排查问题非常有帮助。比如遇到一个奇怪PR翻审计日志就知道当时Agent看到了什么日志、为什么提了这段改动。回滚策略相对简单每个由Agent生成的PR都必须基于一个干净分支走常规GitHub合并流程如果合入后有问题直接在GitHub上revert那个PR即可。Agent自己不做revert因为revert属于高风险操作需要在有人确认的情况下执行。6.3 “人在回路”怎么落地才不形同虚设很多人把“人工审批”写在PR流程里但实践里容易变成“PR合并前点一下批准”没人真的看。我比较有效的做法是设置“敏感路径保护”。在config.yaml里维护一个列表比如src/auth/**、deploy/**、.env*、package.json中的依赖大版本变更。一旦Agent生成的diff触碰这些路径自动状态就从“可创建PR”变成“创建Issue并通知管理员”不会自动创建PR。这样做相当于把人类的精力集中在真正的风险点上而不是让所有人每天审一堆无意义的lockfile更新。安全的自动化系统不是完全无人值守而是知道什么时候该喊人什么时候可以自己干活。这一点比所有技术细节都重要。最后再分享一个我自己的习惯我会定期回看Agent生成的PR挑几个被同事直接批准的看diff确认没有“看着能过但实际上把约束改松了”的情况。这个习惯已经帮我发现了两次模型分析偏乐观、导致修复不彻底的案例。你如果也打算搭类似的东西建议从一开始就把“人工抽检”写进日常流程别等出了问题再补。