贯穿案例：CI 失败分析 Agent

本案例用于贯穿《Anthropic Engineering 学习指南》全书。它不是完整 Java 示例工程，而是一个统一的业务场景、数据样例和架构映射，方便每章围绕同一问题展开。

1. 为什么选择 CI 失败分析 Agent

CI 失败分析是企业研发 Agent 的理想 MVP 场景。

原因：

1. 业务价值明确：CI 失败会阻塞研发交付，自动分析能直接节省工程师时间。
2. 风险相对可控：第一版可以只读分析，不自动修改代码。
3. 天然需要 Agent 能力：失败原因不确定，需要读取日志、搜索代码、查看 Git Diff、分析测试结果。
4. 容易验证：分析报告可以与真实失败原因、人工排查结论、后续修复结果对比。
5. 覆盖全书核心模块：Context、Tool、Skill、Harness、Memory、MCP、Runtime 都能在该场景中体现。

一句话定义：

CI 失败分析 Agent 接收一次失败构建事件，读取相关上下文和工具结果，输出失败原因、证据、可能影响文件、建议修复方向和置信度。

2. 虚构项目背景

为了全书案例一致，统一使用以下虚构项目。

项目名：order-service
技术栈：Java 21 + Spring Boot 3.x + Maven + JUnit 5 + Mockito
职责：订单管理服务
仓库：git://company/order-service
CI：GitLab CI
Issue 系统：Jira
文档：Confluence

核心模块：

src/main/java/com/company/order/
  controller/
  service/
  domain/
  repository/
  state/

src/test/java/com/company/order/
  service/
  state/
  fixtures/

核心业务规则：

OrderStatus 表示订单状态。
OrderStateMachine 负责状态流转校验。
新增订单状态时，必须同步更新状态机和相关测试。

3. 统一样例事件

全书统一使用以下 CI 失败事件。

Build ID：#4312
Pull Request：#882
Branch：feature/order-pending-review
Repository：order-service
Triggered By：developer Alice
CI Job：maven-test
Command：./mvnw test
Status：FAILED

用户任务：

请分析 build #4312 为什么失败。
只允许读取 CI 日志、代码、Git Diff 和项目文档，不要修改文件。
请输出失败原因、证据、可能相关文件、建议修复方向和置信度。

4. 模拟失败摘要

CI 失败摘要：

Module: order-service
Command: ./mvnw test
Failed Test: OrderServiceTest.shouldApprovePendingReviewOrder
Assertion: expected HTTP 200 but got HTTP 500
Exception: IllegalStateException: transition PENDING_REVIEW -> APPROVED is not allowed
Key Frame: OrderStateMachine.validate(OrderStateMachine.java:88)

最近 Git Diff 摘要：

OrderStatus 新增 PENDING_REVIEW。
OrderService 中新增 submitForReview()。
OrderController 新增 /orders/{id}/submit-review 接口。
OrderStateMachine.allowedTransitions 未更新。
OrderServiceTest 新增 shouldApprovePendingReviewOrder 测试。

初步根因：

PR #882 新增了订单状态 PENDING_REVIEW，但没有在 OrderStateMachine.allowedTransitions 中加入 PENDING_REVIEW -> APPROVED 的合法流转，导致测试执行审批流程时抛出 IllegalStateException。

5. Agent 输出目标

CI 失败分析 Agent 的最终输出应包括：

{
  "status": "ANALYZED",
  "rootCause": "PR #882 added OrderStatus.PENDING_REVIEW but did not update OrderStateMachine.allowedTransitions to allow PENDING_REVIEW -> APPROVED.",
  "evidence": [
    "Failed test: OrderServiceTest.shouldApprovePendingReviewOrder",
    "Exception: transition PENDING_REVIEW -> APPROVED is not allowed",
    "Key frame: OrderStateMachine.validate(OrderStateMachine.java:88)",
    "Git diff shows OrderStatus added PENDING_REVIEW"
  ],
  "suspectedFiles": [
    "src/main/java/com/company/order/domain/OrderStatus.java",
    "src/main/java/com/company/order/state/OrderStateMachine.java",
    "src/test/java/com/company/order/service/OrderServiceTest.java"
  ],
  "suggestedFix": "Update OrderStateMachine.allowedTransitions to include PENDING_REVIEW -> APPROVED and run ./mvnw -Dtest=OrderServiceTest test.",
  "confidence": 0.88,
  "limitations": [
    "Agent did not modify files in read-only mode.",
    "Only CI logs, Git diff, and relevant source snippets were analyzed."
  ]
}

6. 上下文设计

6.1 初始上下文

任务开始时加载：

6.2 按需上下文

不一开始加载全文，只保留引用：

6.3 不应进入上下文

第一版不应进入：

完整仓库代码
完整 CI 日志
无关模块代码
用户无权限项目内容
Secret / Token / 环境变量
其他项目历史失败

7. 工具设计

MVP 工具全部只读。

后续版本可以增加写工具：

apply_patch
run_test_command
create_pull_request
comment_on_jira_issue

但写工具需要审批和审计。

8. Harness 设计

CI 失败分析 Harness：

Initialize
  - 创建任务和 session
  - 读取用户权限
  - 加载 AGENTS.md 和 CI 摘要

Plan
  - 判断失败类型：test failure / build failure / infra failure
  - 选择只读工具计划

Act
  - 调用 summarize_ci_failure
  - 调用 get_git_diff
  - 调用 search_code
  - 按需读取相关文件片段

Verify
  - 检查报告是否包含 rootCause、evidence、suspectedFiles、suggestedFix、confidence
  - 检查是否违反只读约束
  - 检查每个关键结论是否有证据

Checkpoint
  - 保存工具调用摘要
  - 保存已验证事实
  - 保存未确认假设

Finish
  - 输出分析报告
  - 可选：创建 Jira 评论或 PR 评论

停止条件：

已生成合格报告
达到最大工具调用次数
关键日志不可访问
权限不足
需要人工判断

9. Skill 设计

Skill 名称：

ci-failure-analysis

目录结构：

skills/ci-failure-analysis/
  SKILL.md
  examples/
    test-failure-report.md
    infra-failure-report.md
  resources/
    failure-type-checklist.md

SKILL.md 核心内容：

---
name: ci-failure-analysis
description: Use when analyzing CI build failures from logs, Git diff, and project instructions. Produces root cause, evidence, suspected files, suggested fix, and confidence.
requiredTools:
  - summarize_ci_failure
  - read_ci_log_segment
  - get_git_diff
  - search_code
  - read_file_range
---

## Procedure

1. Read CI failure summary first.
2. Classify failure type: test, compile, dependency, infrastructure, lint.
3. For test failures, identify failed test, exception, key stack frame.
4. Compare failure with recent Git diff.
5. Read only relevant code and test snippets.
6. Produce evidence-backed report.
7. Do not claim code was fixed in read-only mode.

10. Memory 设计

可能写入的项目记忆：

{
  "type": "PROCEDURAL",
  "scope": "PROJECT",
  "scopeId": "order-service",
  "content": "When modifying OrderStatus, update OrderStateMachine.allowedTransitions and run OrderServiceTest.",
  "source": "CI build #4312 analysis",
  "confidence": 0.92
}

不应写入长期记忆：

完整 CI 日志
临时猜测
用户私密信息
未经验证的根因
一次性 build token

11. MCP 接入

可通过 MCP 接入：

Git MCP Server
CI MCP Server
Jira MCP Server
Confluence MCP Server

资源示例：

ci://build/4312/summary
ci://build/4312/log#L882-L940
git://repo/order-service/pr/882/diff
git://repo/order-service/file/src/main/java/.../OrderStateMachine.java
jira://issue/ORDER-2198

工具示例：

ci.getBuildSummary
git.getDiff
git.searchCode
git.readFileRange
jira.addComment

12. Multi-Agent 扩展

第一版使用单 Agent。

复杂场景可以扩展为多 Agent：

共享结果格式：

{
  "finding": "OrderStateMachine lacks transition PENDING_REVIEW -> APPROVED.",
  "evidence": ["OrderStateMachine.java:88", "CI log L912"],
  "confidence": 0.9,
  "agent": "CodeAnalysisAgent"
}

13. Runtime 映射

Runtime 流程：

CI 失败事件
  ↓
TaskManager 创建 AgentTask
  ↓
SessionManager 创建 AgentSession
  ↓
ContextManager 构建初始上下文
  ↓
SkillManager 加载 ci-failure-analysis Skill
  ↓
ToolOrchestrator 执行只读工具计划
  ↓
Harness 验证报告结构和证据
  ↓
EventStore 保存事件
  ↓
返回报告

关键事件：

TASK_CREATED
SESSION_STARTED
CONTEXT_BUILT
SKILL_LOADED
TOOL_CALLED
TOOL_RESULT_RECEIVED
REPORT_GENERATED
VERIFICATION_PASSED
TASK_COMPLETED

14. 各章节案例映射

15. 后续扩展方向

MVP 之后可以扩展：

自动生成修复建议 patch
自动运行局部测试
自动创建 PR 评论
自动关联历史类似失败
多 Agent 深度排障
引入生产监控和日志系统

但第一版建议保持只读分析，先把上下文、工具、证据和报告质量做好。