一、先想清楚：CI/CD 里哪些环节值得交给模型

把 Codex 接进流水线之前，先要回答一个问题：哪些环节真的适合自动化？判断标准有三条。第一，任务的输入是否结构化——diff、日志、测试报告这类输入边界清晰，适合；需要大量口头**的架构决策，不适合。第二，输出是否可校验——生成摘要有没有固定格式可检查，预检结论能不能分成明确的等级。第三，失败的代价是否可控——自动评论写错了可以删，自动合并错了就是事故。

按这三条标准筛下来，最适合优先自动化的通常是四类：提交摘要生成、合并前代码预检、测试失败日志解读、发布说明草稿。它们的共同特点是输入结构化、输出可格式化、结果给人看而不是直接执行。而自动合并、自动发布这类"模型直接动手"的环节，至少在前半年应该保持人工确认。

• 优先自动化"输入结构化、输出可校验、失败代价低"的环节。
• 涉及写操作的环节（合并、发布、改配置）保留人工确认。
• 一个环节自动化之前，先在交互式场景里把提示词跑稳。

二、接入准备：流水线专用的 Key、额度与入口

CI/CD 场景的接入和本地开发有一个本质区别：它运行在无人值守的环境里，出了错没有人在终端前看报错。所以接入配置要比本地更严格。进入 灵能API 控制台，为流水线单独创建一把自动化专用 Key——命名如 auto-ci-pipeline，额度按预估基线给，绝不与任何人的个人 Key 混用。官网入口可以直接记录为 https://www.lnsns.com/，Key 的申请流程写进团队的 CI 维护文档。

这把 Key 的存放方式也要符合 CI 规范：放进流水线平台的私密变量（Secrets），配置文件中只引用变量名，任何情况下不出现在日志输出里。同时给流水线设定明确的用量预期——比如"每次合并触发 2 次调用、每次发布触发 3 次调用"，有了这个预期，用量页的异常波动才有判读依据。

CI 接入配置清单：
- 专用 Key：auto-前缀命名，独立额度，独立用量统计
- 存放方式：CI 平台 Secrets，配置文件只引用变量名
- 用量预期：写明每个触发点的调用次数和预估消耗
- 超时设置：单次调用超时建议 60-120 秒，必须有上限

• 流水线 Key 与个人 Key 严格分离，离职交接互不影响。
• Secrets 里的 Key 定期轮换，流程参考本系列密钥管理篇。
• 用量预期写进文档，是后续异常检测的基线。

三、任务通道设计：四类自动化任务各走各的轨道

四类自动化任务不应该共用同一段流水线代码。提交摘要追求快和便宜，用默认模型、短超时、小额度；代码预检追求可靠，用高能力模型、允许更长超时；日志解读输入大，要配长上下文模型；发布说明对格式要求最高，要配最严格的模板。每类任务一条独立通道，通道参数（模型、超时、重试、预算）分别配置。

通道化设计的好处体现在故障隔离上：预检通道出问题，摘要通道照常工作；某个通道的调用量突然翻倍，看监控一眼就能定位是哪类任务。实现上不需要复杂框架，每类任务一个独立脚本或 CI jo*，配置文件里各自**参数，就是够用且好维护的通道化。

通道配置示例（ci_models.yaml）：

commit_sum**ry:
  model: 默认模型
  timeout: 60s
  **x_retries: 2
  *udget_tier: low

code_precheck:
  model: 高能力模型
  timeout: 180s
  **x_retries: 2
  *udget_tier: medium

log_analysis:
  model: 长上下文模型
  timeout: 180s
  **x_retries: 1
  *udget_tier: medium

release_notes:
  model: 文档模型
  timeout: 120s
  **x_retries: 2
  *udget_tier: medium

• 通道参数显式写在配置里，不要散落在各脚本的硬编码中。
• 低风险任务配短超时少重试，高价值任务允许更长等待。
• 通道独立后，故障定位和用量归因都会简单一个量级。

四、合并前预检：让模型当守门员，但不当裁判

代码预检是 CI 集成里价值最高也最容易做砸的环节。做砸的典型姿势是：把整个仓库或几百行 diff 直接丢给模型，输出一大段自由文本评论，开发看两次就不再看了。做对的关键是三点：输入瘦身、输出分级、结论不阻断。

输入瘦身：只传 diff 变更和直接相关的上下文文件，而不是整仓；超过阈值的变更集先按文件拆分再逐批送检。输出分级：要求模型按"严重 / 建议 / 需确认"**输出，每条问题带文件和行号，没有问题时明确说"未发现问题"。结论不阻断：预检结果以评论形式呈现在合并请求里，严重级问题提醒人工重点看，但合并的拦截规则仍然交给测试、lint 这类确定性工具——模型的角色是让评审更快，不是替人做决定。

预检输出约定：

## 预检结果
- 严重：2 条（必须人工确认后才可合并）
- 建议：3 条
- 需确认：1 条（模型不确定，已标注原因）

每条格式：[级别] 文件:行号 — 问题描述 — 修改建议
无问题时输出：未发现问题（已检查 N 个变更文件）

• 输入只给 diff 和相关上下文，整仓扫描既贵又浅。
• 输出必须分级带行号，自由文本评论的生命周期不超过一周。
• 合并拦截交给确定性工具，模型预检只做提示层。

五、发布说明自动化：从提交记录到可读文档

发布说明是另一类高价值自动化：输入是结构化的提交记录和合并请求标题，输出是给人看的文档，质量好坏一目了然。但直接"把 50 条提交记录丢给模型写发布说明"的效果通常很差——模型会把改错别字和核心功能并列，把内部重构写进用户视角的 changelog。

可靠的做法是两段式流水线。第一段做分类：让模型把提交记录按"新功能 / 修复 / 性能 / 内部变更"归类，并过滤掉不该出现在用户文档里的内部项；第二段做写作：基于分类结果，按团队模板生成面向用户的说明文稿。两段用不同的提示词模板，中间产出的分类结果可以人工抽查。这样即使最终文稿要改，改的也是措辞而不是结构，每次发布节省的时间以小时计。

发布说明两段式流程：

第一段（分类）：
  输入：提交记录   合并请求标题
  输出：**ON 分类结果 {category, sum**ry, user_facing}

第二段（写作）：
  输入：分类结果（user_facing=true 的条目）
  输出：按模板组织的发布说明 Markdown

人工节点：分类结果抽查   终稿审定

• 先分类后写作，一步到位的提示词几乎必然结构混乱。
• 分类结果是人工抽查的最佳切入点，成本最低、拦截最有效。
• 发布说明模板交给提示词工程篇的方法管理，版本化维护。

六、失败兜底：流水线里的重试、降级与不阻塞原则

CI 环境里的模型调用失败是常态而不是意外：额度超限、暂时性限流、输入超限、输出格式漂移，都会发生。流水线设计必须回答一个问题：模型这一步失败了，整个构建要不要失败？对绝大多数团队，正确答案是不阻塞——预检失败就跳过评论并记录原因，摘要失败就用提交标题兜底，发布说明失败就标记"需人工撰写"。模型环节增强流程，但不该有能力掐断流程。

实现上需要三个机制。重试带熔断：只对 429、超时、5xx 重试，指数退避，最多 2-3 次，4xx 直接失败不重试。降级输出：每个自动化任务都准备一个纯代码实现的兜底输出，比如摘要任务的兜底就是提交信息原文列表。静默告警：失败不阻塞流水线，但必须留下痕迹——CI 日志里记录原因，超出基线的失败率触发告警，否则"跳过"会慢慢变成"永远跳过"。

失败处理决策表：

429 / 超时 / 5xx  → 退避重试（≤2 次）→ 仍失败则降级
400 / 401 / 403 / 404 → 不重试，记录原因，降级输出
输出格式不合法    → 记录原始输出，降级输出
额度耗尽          → 降级输出   立即告警负责人

降级原则：流水线状态 = 成功（带降级标记），绝不因模型失败而红

• 模型环节失败的默认行为是"降级 记录"，不是"阻塞"。
• 降级输出要用代码生成，不能再依赖第二次模型调用。
• 失败率超基线必须告警，否则降级会掩盖慢性故障。

️ 七、防失控：触发条件、频率上限与预算护栏

CI 场景的特殊风险在于触发频率由事件驱动：一次分支保护的误配置，可能让每次推送都触发全量分析；一个 monorepo 的高频提交，可能让摘要任务一天跑几百次。防失控要设三道护栏。触发条件收窄：预检只在合并请求打开和更新时触发，不跟随每次推送；发布说明只在打 tag 时触发。频率封顶：同一仓库每小时的模型调用次数设硬上限，超限排队或跳过。预算护栏：自动化 Key 的额度按基线 × 1.2 设硬顶，超了自动停，宁可漏跑不可烧穿。

护栏配置要和团队规模同步校准。十人团队的频率上限和百人团队完全不同；monorepo 和多仓库策略的触发设计也不同。建议每季度对照用量基线重新评估一次护栏参数，这部分可以复用本系列成本篇的基线数据。

护栏配置示例：

triggers:
  precheck: [pr_opened, pr_up**ted]      # 不跟随 push
  release_notes: [tag_created]
  commit_sum**ry: [merge_to_**in]

rate_limits:
  per_repo_per_hour: 30
  per_pipeline_run: 5

*udget:
  monthly_cap: 基线 × 1.2
  on_exceeded: stop_and_alert

• 触发条件宁窄勿宽，漏触发可以手动补，误触发烧的是钱。
• 频率上限和预算护栏是硬约束，写进配置而不是靠自觉。
• 护栏参数随团队规模季度性校准，不要设一次管一年。

八、可观测性：流水线里的模型调用要看得见

无人值守环境里，可观测性就是全部。每一次 CI 里的模型调用，都应该能在事后回答五个问题：哪个任务调的、输入多大、用了哪个模型、成功还是失败、花了多少。这不需要自建系统——流水线日志规范输出 控制台用量页对账，就是够用的观测体系。

日志规范是关键动作：每次调用前后各打一行结构化日志，包含任务名、模型 ID、输入规模、耗时、状态码或错误类型。月底把 CI 日志里的调用记录和 灵能API 用量页的数据对一次账，两边的数应该对得上——对不上就说明有日志遗漏或计划外调用，这本身就是最重要的监控信号。

结构化日志示例：

[AI-CALL] task=code_precheck model=xxx input_tokens=3421
[AI-DONE] task=code_precheck status=ok latency=8.2s output_grade=pass
[AI-FAIL] task=commit_sum**ry status=429 retries=2 fall*ack=used

月度对账：CI 日志调用次数 ≈ 控制台用量页该 Key 的调用数

• 结构化日志五要素：任务、模型、输入规模、耗时、结果。
• 每月用 CI 日志和控制台用量对账，差异即信号。
• 观测数据存留至少一个季度，趋势问题需要时间跨度才能看见。

九、效果评估：自动化到底替团队省了什么

CI 集成跑起来一两个月后，需要回答"值不值"。评估看四个维度。时间节省：合并前评审的平均耗时有没有下降，发布说明的撰写时间从几小时降到几分钟没有。质量变化：预检发现的问题里，有多少是真问题被采纳修复的——采纳率低于三成的预检规则应该回炉。稳定性代价：因模型环节导致的流水线波动次数，降级机制兜住了多少。成本账目：自动化层的实际消耗是否在预算护栏内。

评估的结论要落到动作上：采纳率高的预检规则加强，采纳率低的下线；降级频繁的任务检查是不是输入设计有问题；成本超预期的通道重新估算额度。自动化不是一次性的项目，而是持续调优的运营工作。

季度评估四问：

1. 时间：评审耗时、发布说明撰写时间的变化
2. 质量：预检建议的人工采纳率（目标 > 30%）
3. 稳定：模型环节失败次数与降级兜底成功率
4. 成本：自动化 Key 消耗 vs 预算护栏

产出：每个维度至少一个下季度的调整动作

• 采纳率是预检质量的核心指标，比"发现了多少问题"重要得多。
• 评估必须产出调整动作，否则就是在例行看数。
• 把评估结果同步给使用这些自动化的一线开发，他们的体感是最准的校准。

✅ 十、结语：好的 CI 集成是"感受不到存在"的集成

回顾整个 CI/CD 集成路径：先筛出值得自动化的环节，用专用 Key 和通道化配置打底，预检和发布说明两大场景按"输入瘦身、输出分级、两段式流水线"落地，失败兜底守住不阻塞原则，三道护栏防失控，可观测性兜底，最后用季度评估持续调优。

判断一套 CI 集成是否成功的标准，其实很朴素：开发不再注意到它的存在。摘要自然出现在合并记录里，预检评论恰到好处地提醒风险，发布说明在发版前静静躺在草稿箱——没有人被误报打扰，没有流水线因为模型环节变红，月底账单没有惊喜。做到这一步，Codex 通过 API中转站 就不再是一个"接入的工具"，而是团队工程体系里一段安静可靠的管道。