# self-healing-agent

**Repository Path**: michelle33/self-healing-agent

## Basic Information

- **Project Name**: self-healing-agent
- **Description**:  UI 自动化测试失败自愈 Agent 脚手架 — 多源证据融合 + 知识库驱动的根因自治
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-18
- **Last Updated**: 2026-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UI 自动化自愈 Agent 脚手架

> 配套文章：《UI 自动化自愈 Agent：从定位修复到根因自治》
> 
> 关注公众号「智测开发手记」

## 这是什么

一个 UI 自动化测试失败自愈 Agent 的 Python 脚手架，实现文章中拆解的 6 层架构：

```
测试失败 → 证据采集 → 证据融合 → RAG检索 → AI推理 → 自动修复 → 知识积累
           Layer1     Layer2     Layer3    Layer4    Layer5     Layer6
```

与 Healenium/Mabl 等定位器修复工具不同，本脚手架做的是**根因级自治**：不只修定位器，还处理蒙层遮挡、XPath 宽匹配、多弹框叠加、执行时序等 10 类失败场景。

## 快速开始

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 配置 LLM 和向量数据库
cp config.yaml.example config.yaml
# 编辑 config.yaml 填入你的 LLM API Key 和向量库地址
# 也可以用环境变量：export LLM_API_KEY=sk-xxx （config.yaml 中 ${LLM_API_KEY} 会自动展开）

# 3. 初始化知识库（用历史修复案例做种子数据）
python main.py --init-kb examples/sample_fix_cases.json

# 4. 对一次失败执行自愈（dry-run 模式只诊断不修复，推荐先用这个）
python main.py --dry-run --test-case "TC_LOGIN_001" --driver-session $SESSION_ID

# 5. 查看最近一次诊断报告
python main.py --report --last
```

> ⚠️ 注意：`--heal` 自动修复模式依赖 `core/auto_fixer.py` 中的 `_rerun_test`，
> 该方法在脚手架中是 TODO 桩（写死返回失败），导致 `--heal` 模式目前会走到回滚分支。
> 要让 `--heal` 真正可用，请按 `GUIDE.md` 第 6.3 节接入你的测试运行器（pytest 等）。
> 在补全之前，请先用 `--dry-run` 模式做诊断建议。

## 目录结构

```
self-healing-agent-starter/
├── README.md                       # 本文件
├── requirements.txt                # Python 依赖
├── config.yaml.example             # 配置模板（LLM/向量库/日志路径）
├── main.py                         # 入口：CLI 命令路由
├── core/
│   ├── evidence_collector.py       # Layer 1: DOM/截图/日志采集
│   ├── evidence_fusion.py          # Layer 2: DOM Diff + 视觉分析 + 日志模式提取
│   ├── rag_retriever.py            # Layer 3: 历史案例向量检索
│   ├── ai_reasoner.py              # Layer 4: LLM 失败分类 + 根因推理
│   ├── auto_fixer.py               # Layer 5: 修复执行（定位器/脚本/等待策略/蒙层/XPath）
│   └── knowledge_accumulator.py    # Layer 6: 成功修复入库
├── templates/
│   ├── diagnostic_rules.yaml      # 10 类失败场景诊断规则
│   └── business_kb_template.md     # 业务知识库模板
└── examples/
    ├── sample_failure_case.json    # 示例失败案例
    └── sample_fix_cases.json       # 示例修复案例（种子数据）
```

## 10 类失败场景覆盖

| failure_type | 场景描述 | fix_action |
|---|---|---|
| locator_change | 元素改名/移位 | update_locator |
| dom_restructure | DOM 结构重构 | update_locator + modify_script_logic |
| logic_change | 业务逻辑变更 | modify_script_logic |
| data_issue | 测试数据异常 | adjust_wait_strategy |
| env_issue | 环境问题 | escalate_human |
| modal_overlay_block | 蒙层遮挡导致不可交互 | close_overlay_first |
| zindex_occluded | z-index 层级遮挡 | close_overlay_first |
| multi_modal_conflict | 多弹框叠加冲突 | close_overlay_first |
| xpath_ambiguous | XPath 宽匹配多个元素 | narrow_xpath |
| async_timing_issue | 异步时序/数据未加载完 | adjust_wait_strategy |

## 置信度门槛设计

```python
CONFIDENCE_THRESHOLD = 0.7  # 低于此值升级人工

# 随案例积累可逐步调高
# 案例 < 50:  threshold = 0.7
# 案例 50-200: threshold = 0.75
# 案例 200+:  threshold = 0.8
```

## 安全设计

- **成功修复才入库**：避免错误修复方案污染知识库
- **置信度门槛**：低于 0.7 升级人工，防止 AI 误修
- **修复预览模式**：`--dry-run` 只诊断不执行，先看建议再决定
- **回滚机制**：每次修复前备份原始脚本，修复后测试失败可自动回滚

## 扩展指南

### 添加新的失败类型

1. 在 `templates/diagnostic_rules.yaml` 中添加失败类型和诊断规则
2. 在 `core/ai_reasoner.py` 的 `FAILURE_TYPES` 枚举中添加
3. 在 `core/auto_fixer.py` 的 `action_map` 中添加对应修复动作
4. 用 5-10 个手工修复案例做种子数据，入库训练

### 接入不同的 LLM

编辑 `config.yaml`：

```yaml
llm:
  provider: openai  # 支持: openai / azure / qwen / zhipu
  model: gpt-4o
  api_key: ${LLM_API_KEY}
```

### 接入不同的向量数据库

```yaml
vector_db:
  type: chroma  # 支持: chroma / milvus / qdrant / weaviate
  path: ./data/vector_store
```

## 落地建议

1. **先做诊断建议，不做自动修复**：让 Agent 输出诊断报告，人工执行修复，积累 100+ 案例
2. **先覆盖最高频的 3 类失败**：locator_change、xpath_ambiguous、async_timing_issue
3. **逐步开启自动修复**：从置信度 > 0.9 的案例开始，逐步降低门槛
4. **定期清理知识库**：移除过时的修复案例（如被测系统大改版后）

## 限制说明

- 本脚手架是**架构参考实现**，不是生产级系统
- 需要你自行适配你的测试框架（Selenium/Playwright/Appium）—— 参考 `GUIDE.md` 第 3 节
- **`--heal` 模式当前不可用**：`auto_fixer._rerun_test` 是 TODO 桩，会强制走回滚分支。
  补全方法见 `GUIDE.md` 第 6.3 节。补全前请只用 `--dry-run` 模式
- LLM 仅实现 `openai` provider，其他国产 LLM 通过 `base_url` 走 openai 兼容协议接入
- 向量数据库仅实现 `chroma`，milvus/qdrant/weaviate 未实装
- LLM 推理质量取决于 prompt 设计，建议基于 `templates/diagnostic_rules.yaml` 持续优化
- 知识库质量是核心壁垒——垃圾进垃圾出，种子案例必须高质量

## 故障排查

| 现象 | 排查方向 |
|---|---|
| `--dry-run` 在 Layer 2 崩溃 | 已修复；如果还崩，请检查 `core/evidence_fusion.py` 是否有 `__init__(self, config)` |
| `--report --last` 显示"暂无诊断报告" | 需要先跑过一次 `--dry-run` 或 `--heal`，诊断报告才会落盘到 `data/logs/last_report.json` |
| LLM 调用失败、所有诊断 confidence=0 | 检查 `LLM_API_KEY` 环境变量是否设置，或 `config.yaml` 中 `api_key` 是否填了真实值（不是 `${LLM_API_KEY}` 占位符） |
| ChromaDB 首次运行报错 | 已自动创建 `./data/vector_store` 目录；如仍报错检查目录权限 |
| `--init-kb` 重复执行报 ID 冲突 | 已改用 upsert，可重复执行覆盖旧数据 |

## License

MIT - 自由使用、修改、分发。如果对你有帮助，关注「智测开发手记」 :)