1 line
57 KiB
JSON
1 line
57 KiB
JSON
{"repo": "anniefandingying/software-testing-group-13", "files": {"task.md": {"a126731d9c6da648a3a9c80f939ea0b8a0b71acf": {"t": 1785746412.2047691, "n": 18730, "h": "ebf4bfc68752cefd", "c": "# 成员 F（智能体开发与系统集成）任务执行清单\n\n> **项目**：软件测试与维护（2026年春）大作业 — 加分项二：智能体自动运维 \n> **小组**：Group 13 \n> **GitHub 仓库**：https://github.com/AnnieFandingying/Software-Testing-Group-13 \n> **成员 F 职责**：基于 VeADK 框架开发 AIOps Agent + 项目 PM（GitHub 管理、PDF 排版、PPT 美化）\n\n---\n\n## 一、已完成内容概述（成员 A 和 B 的交付物）\n\n通过克隆并分析 GitHub 仓库 `main` 分支，成员 A 和 B 已完成以下工作：\n\n### 1.1 成员 A（平台与可观测性工程师）已完成：\n- ✅ 部署 Online-Boutique 微服务系统（基于 Minikube 集群）\n- ✅ 配置 Prometheus + Grafana 监控系统\n- ✅ **开发微服务3**：`recovery-gateway`（自愈网关）— 提供 REST API 供 Agent 远程调用执行 Pod 重启/服务降级\n - 路径：`src/recoverygateway/`\n - API 端点：`POST /api/v1/restart`、`POST /api/v1/degrade`、`GET /healthz`、`GET /metrics`\n - 认证：Bearer Token（环境变量 `RECOVERY_AUTH_TOKEN`）\n - K8s 清单：`kubernetes-manifests/recoverygateway.yaml`\n- ✅ 编写 K8s Deployment/Service/RBAC YAML 清单\n\n### 1.2 成员 B（微服务开发工程师）已完成：\n- ✅ **开发微服务1**：`discount-service`（618 满减折扣服务，gRPC）\n - 路径：`src/discountservice/`\n - 满 200 减 50、满 400 减 100、满 700 减 200\n - 仅对 CNY 币种生效\n- ✅ **开发微服务2**：`telemetry-service`（遥测聚合服务，HTTP）\n - 路径：`src/telemetryservice/`\n - 接收事件 `POST /events`，暴露 Prometheus 指标 `GET /metrics`\n - 弱依赖语义：遥测挂掉不影响主链路\n- ✅ 修改 `checkoutservice`：集成 discount-service gRPC 调用 + 遥测上报\n- ✅ 修改 `frontend`：结算页面金额修正 + 遥测上报\n- ✅ 编写 Dockerfile、K8s YAML、Helm Chart\n- ✅ 编写 `Ability.md`（功能说明）和 `Check.md`（编译自检清单）\n\n### 1.3 系统架构现状（了解 Agent 的工作环境）：\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Minikube 集群 (成员A电脑) │\n│ │\n│ ┌──────────────────────────────────────────────────────┐ │\n│ │ Online-Boutique 微服务 │ │\n│ │ frontend → checkoutservice → discountservice (NEW) │ │\n│ │ ↓ → telemetryservice (NEW) │ │\n│ │ cartservice, paymentservice, shippingservice, ... │ │\n│ └──────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │\n│ │ Prometheus │ │ Grafana │ │ recovery-gateway │ │\n│ │ (采集指标) │ │ (可视化) │ │ (自愈网关 :8080) │ │\n│ └──────┬──────┘ └──────────────┘ └────────▲─────────┘ │\n│ │ │ │\n│ ┌──────┴─────────────────────────────────────┴──────┐ │\n│ │ Alertmanager (告警 Webhook) │ │\n│ └──────────────────────────┬───────────────────────┘ │\n└─────────────────────────────┼─────────────────────────────┘\n │ HTTP POST (告警 JSON)\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 成员 F 电脑（Agent 运行环境） │\n│ │\n│ ┌──────────────────────────────────────────────────────┐ │\n│ │ VeADK Agent (veadk_agent.py) │ │\n│ │ │ │\n│ │ ① 接收 Alertmanager Webhook 告警 │ │\n│ │ ② ReAct 推理循环（LLM 分析 → 工具调用 → 综合分析） │ │\n│ │ ③ 工具1：execute_promql → 查询 Prometheus API │ │\n│ │ ④ 工具2：get_service_logs → 获取 K8s Pod 日志 │ │\n│ │ ⑤ 工具3：restart_pod → 调用 recovery-gateway 重启服务 │ │\n│ │ ⑥ 输出诊断报告 + 执行自愈动作 │ │\n│ └──────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## 二、详细任务分解（总计约 40 小时）\n\n### 📋 阶段一：环境准备与大模型 API 打通（约 8 小时）\n\n#### 任务 1.1：Python 开发环境准备\n- [ ] 确认 Python 3.8+ 已安装（`python --version`）\n- [ ] 创建项目虚拟环境：`python -m venv venv`\n- [ ] 激活虚拟环境并安装依赖：\n ```bash\n pip install openai requests fastapi uvicorn pyyaml kubernetes\n ```\n- [ ] 创建项目目录结构：\n ```\n cs-final-test/\n ├── task.md # 本任务清单\n ├── veadk_agent/\n │ ├── __init__.py\n │ ├── agent.py # Agent 核心逻辑（ReAct Loop）\n │ ├── tools.py # 工具注册与实现\n │ ├── config.py # 配置管理（环境变量读取）\n │ ├── webhook_server.py # Alertmanager Webhook 接收服务\n │ ├── prometheus_client.py # Prometheus API 查询客户端\n │ └── requirements.txt # Python 依赖清单\n ├── tests/\n │ ├── test_tools.py # 工具函数单测\n │ ├── test_agent.py # Agent 推理链单测\n │ └── test_integration.py # 端到端集成测试\n ├── config/\n │ └── agent_config.yaml # Agent 配置文件\n └── docs/\n └── agent_design.md # Agent 设计文档\n ```\n\n#### 任务 1.2：大模型 API 配置\n- [ ] 注册/获取大模型 API Key（推荐使用火山引擎豆包 API 或其他国产大模型）\n - 建议 API：DeepSeek API、通义千问 API、火山引擎豆包 API\n - 参考 VeADK 教程：`https://nankai.feishu.cn/wiki/AuPtwvDlKinPaskYVubcWoLancd`\n- [ ] 配置环境变量：\n ```bash\n export OPENAI_API_KEY=\"sk-xxxxxxxxxxxxx\"\n export OPENAI_BASE_URL=\"https://api.deepseek.com\" # 或其他兼容 OpenAI API 的地址\n ```\n- [ ] 编写简单的 API 连通性测试脚本，确认可以正常调用大模型\n\n#### 任务 1.3：克隆仓库并理解现有代码\n- [x] 已克隆 GitHub 仓库：`git clone https://github.com/AnnieFandingying/Software-Testing-Group-13.git`\n- [x] 已阅读 `Ability.md`（微服务功能说明）\n- [x] 已阅读 `Check.md`（编译自检清单）\n- [x] 已阅读 `recovery-gateway` 源码（理解 Agent 自愈 API）\n- [ ] 与成员 A 确认以下连接信息：\n - Prometheus 地址（Minikube 暴露的 URL）\n - recovery-gateway 的 Service 地址和 Bearer Token\n - Alertmanager Webhook 配置状态\n- [ ] 阅读 VeADK 教程原文（飞书文档链接）\n\n---\n\n### 📋 阶段二：Agent 核心逻辑开发（约 15 小时）\n\n#### 任务 2.1：编写 Agent 配置管理模块 (`config.py`)\n- [ ] 实现从环境变量读取配置：\n - `PROMETHEUS_URL`：Prometheus 查询地址\n - `RECOVERY_GATEWAY_URL`：recovery-gateway API 地址\n - `RECOVERY_AUTH_TOKEN`：自愈网关认证 Token\n - `LLM_API_KEY`：大模型 API Key\n - `LLM_BASE_URL`：大模型 API 地址\n - `LLM_MODEL`：模型名称（默认 `gpt-4o` 或 `deepseek-chat`）\n - `ALERTMANAGER_WEBHOOK_PORT`：Webhook 监听端口（默认 `5000`）\n - `SOCK_SHOP_NAMESPACE`：K8s 命名空间（默认 `sock-shop`）\n- [ ] 支持从 `.env` 文件加载配置\n\n#### 任务 2.2：实现工具函数模块 (`tools.py`)\n按照 VeADK 教程中定义的三个核心工具：\n\n**工具 1：`execute_promql(query_str: str) -> str`**\n- [ ] 实现 Prometheus HTTP API 查询：\n - 调用 `GET {PROMETHEUS_URL}/api/v1/query?query={query_str}`\n - 支持即时查询（instant query）\n - 解析 JSON 响应并格式化返回\n - 错误处理：超时、连接失败、无数据\n- [ ] 预定义常用 PromQL 查询模板（方便 LLM 选择）：\n - CPU 使用率：`sum(rate(container_cpu_usage_seconds_total{namespace=\"sock-shop\"}[5m])) by (pod)`\n - 内存使用率：`sum(container_memory_usage_bytes{namespace=\"sock-shop\"}) by (pod)`\n - 请求错误率：`sum(rate(http_requests_total{status_code=~\"5..\"}[5m])) / sum(rate(http_requests_total[5m]))`\n - 请求延迟 P99：`histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))`\n - Pod 重启次数：`kube_pod_container_status_restarts_total{namespace=\"sock-shop\"}`\n - 文件系统使用率：`sum(container_fs_usage_bytes{namespace=\"sock-shop\"}) by (pod)`\n\n**工具 2：`get_service_logs(service_name: str, tail_lines: int = 50) -> str`**\n- [ ] 实现通过 kubectl 获取 Pod 日志：\n - 使用 `kubectl logs` 命令（通过 subprocess 或 kubernetes Python 客户端）\n - 自动查找服务对应的 Pod 名称\n - 支持 `--tail` 参数限制行数\n - 支持 `--timestamps` 获取时间戳\n- [ ] 备选方案：如果 kubectl 不可用，通过 Kubernetes Python 客户端读取\n- [ ] 日志格式化输出，方便 LLM 理解\n\n**工具 3：`restart_pod(service_name: str, namespace: str = \"sock-shop\") -> str`**\n- [ ] 调用 recovery-gateway REST API：\n ```python\n POST {RECOVERY_GATEWAY_URL}/api/v1/restart\n Headers:\n Authorization: Bearer {RECOVERY_AUTH_TOKEN}\n Content-Type: application/json\n Body:\n {\n \"target\": \"{service_name}\",\n \"namespace\": \"{namespace}\",\n \"kind\": \"deployment\",\n \"reason\": \"agent_auto_recovery\"\n }\n ```\n- [ ] 验证 API 响应，确认重启操作是否成功\n- [ ] 如果 recovery-gateway 不可用，降级使用 kubectl 命令执行 `kubectl rollout restart deployment/{service_name}`\n- [ ] 增加安全检查：仅允许重启白名单中的服务\n\n**工具 4（扩展，加分项）：`set_degrade_mode(service_name: str, mode: str, ttl_seconds: int = 900) -> str`**\n- [ ] 调用 recovery-gateway 的 `/api/v1/degrade` 端点\n- [ ] 支持将服务设置为 `degraded` 或 `normal` 模式\n- [ ] 在诊断出部分服务压力过大时，可自动执行降级\n\n#### 任务 2.3：实现 Agent 核心推理循环 (`agent.py`)\n- [ ] 设计 Agent System Prompt（系统人设）：\n ```\n 你是一个资深的云原生 AIOps 专家。\n 当收到告警时，你不能盲目判断。你需要通过调用工具来收集证据，\n 区分这是正常的流量突增，还是底层组件发生了不可见的老化与\n Fail-Slow 劣化（例如死锁、连接池耗尽、慢查询）。\n \n 请遵循以下思考路径：\n ① 分析当前告警信息\n ② 决定是否需要更多数据（调用工具获取）\n ③ 交叉分析多项指标和日志\n ④ 得出根因诊断结论 + 给出置信度\n ⑤ 如果确认为可自愈故障，执行恢复操作\n ⑥ 输出结构化诊断报告\n ```\n- [ ] 实现 ReAct Loop（推理-行动循环）：\n - 最多允许 5 轮工具调用（防止无限循环）\n - 每轮将用户告警 + 工具返回结果加入 messages 上下文\n - 支持多工具并行调用（当多个查询不互相依赖时）\n- [ ] 实现诊断报告结构化输出：\n ```json\n {\n \"alert_time\": \"2026-06-12T14:30:00\",\n \"alert_summary\": \"catalogue 服务 CPU 突增至 85%\",\n \"root_cause\": \"数据库连接池耗尽，导致请求堆积\",\n \"confidence\": 0.85,\n \"supporting_evidence\": [\n \"PromQL 查询显示 catalogue CPU 持续 >80% 已达 5 分钟\",\n \"日志中频繁出现 'DB Pool exhausted' 错误\",\n \"数据库连接数指标显示连接池使用率 100%\"\n ],\n \"actions_taken\": [\n \"已通过 recovery-gateway 重启 catalogue 服务\",\n \"建议检查数据库最大连接数配置\"\n ],\n \"recovery_result\": \"catalogue 服务已成功重启，CPU 恢复正常\"\n }\n ```\n\n#### 任务 2.4：定义工具 Schema（供 LLM Function Calling 使用）\n- [ ] 按照 OpenAI Function Calling 格式定义每个工具：\n ```python\n TOOLS_SCHEMA = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"execute_promql\",\n \"description\": \"执行 PromQL 查询获取 Prometheus 监控指标。常用查询：\"\n \"1) CPU: sum(rate(container_cpu_usage_seconds_total{namespace='sock-shop'}[5m])) by (pod)\"\n \"2) 内存: sum(container_memory_usage_bytes{namespace='sock-shop'}) by (pod)\"\n \"3) 错误率: sum(rate(http_requests_total{status_code=~'5..'}[5m])) by (pod)\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"query_str\": {\n \"type\": \"string\",\n \"description\": \"要执行的 PromQL 查询语句\"\n }\n },\n \"required\": [\"query_str\"]\n }\n }\n },\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_service_logs\",\n \"description\": \"获取指定微服务的最新 Kubernetes Pod 日志\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"service_name\": {\"type\": \"string\", \"description\": \"服务名称，如 catalogue, frontend\"},\n \"tail_lines\": {\"type\": \"integer\", \"description\": \"返回最后 N 行日志，默认 50\"}\n },\n \"required\": [\"service_name\"]\n }\n }\n },\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"restart_pod\",\n \"description\": \"当确认服务处于死锁或内存泄漏等无法恢复的僵死状态时，通过 recovery-gateway 重启该服务。仅限白名单中的服务。\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"service_name\": {\"type\": \"string\", \"description\": \"要重启的服务名称\"},\n \"namespace\": {\"type\": \"string\", \"description\": \"K8s 命名空间，默认 sock-shop\"}\n },\n \"required\": [\"service_name\"]\n }\n }\n }\n ]\n ```\n- [ ] 确保工具描述中包含足够的提示信息（示例 PromQL），帮助 LLM 做出正确的工具选择\n\n---\n\n### 📋 阶段三：Webhook 接收与告警触发（约 8 小时）\n\n#### 任务 3.1：实现 Alertmanager Webhook 接收服务 (`webhook_server.py`)\n- [ ] 使用 FastAPI/Flask 创建 HTTP 服务器，接收 Alertmanager 发送的告警 JSON\n- [ ] 解析 Alertmanager Webhook 格式：\n ```json\n {\n \"receiver\": \"agent-webhook\",\n \"status\": \"firing\",\n \"alerts\": [\n {\n \"status\": \"firing\",\n \"labels\": {\n \"alertname\": \"HighCPUUsage\",\n \"severity\": \"critical\",\n \"service\": \"catalogue\",\n \"namespace\": \"sock-shop\"\n },\n \"annotations\": {\n \"summary\": \"catalogue service CPU usage is above 80%\",\n \"description\": \"CPU usage has been above 80% for 5 minutes\"\n },\n \"startsAt\": \"2026-06-12T14:25:00Z\",\n \"endsAt\": \"0001-01-01T00:00:00Z\"\n }\n ],\n \"groupLabels\": {},\n \"commonLabels\": {},\n \"externalURL\": \"http://prometheus:9093\"\n }\n ```\n- [ ] 告警去重：同一告警在 firing/resolved 周期内只触发一次 Agent 诊断\n- [ ] 告警优先级过滤：根据 severity 标签决定是否触发 Agent\n- [ ] 添加 `/healthz` 健康检查端点\n- [ ] 添加 `/metrics` 端点，暴露 Agent 自身运行指标（诊断次数、成功率等）\n\n#### 任务 3.2：告警格式化与上下文构建\n- [ ] 将 Alertmanager 告警转换为 Agent 可理解的文本描述：\n ```python\n def format_alert_for_agent(alert: dict) -> str:\n return f\"\"\"\n [告警名称] {alert['labels']['alertname']}\n [严重程度] {alert['labels']['severity']}\n [涉及服务] {alert['labels'].get('service', 'unknown')}\n [告警摘要] {alert['annotations']['summary']}\n [详细描述] {alert['annotations']['description']}\n [开始时间] {alert['startsAt']}\n [当前状态] {alert['status']}\n \"\"\"\n ```\n- [ ] 支持多告警聚合：将同一时间窗口内的多个相关告警打包发送给 Agent\n\n#### 任务 3.3：轮询模式（备选方案，当 Alertmanager 不可用时）\n- [ ] 实现定时巡检函数 `fetch_basic_cpu()`：\n - 每 10 秒查询一次关键服务的 CPU 使用率\n - 超过阈值（如 CPU > 0.5 或 80%）时主动触发 Agent 诊断\n- [ ] 参考教程中的 `main()` 函数实现守护进程模式\n\n---\n\n### 📋 阶段四：闭环联调与端到端验证（约 5 小时）\n\n#### 任务 4.1：与成员 A 的系统打通\n- [ ] 确认 Prometheus URL 连通性（从 F 电脑可访问 A 电脑的 Prometheus）\n- [ ] 确认 recovery-gateway API 连通性（从 F 电脑可调用 A 电脑的 K8s 集群内的 recovery-gateway）\n - 可能需要 Minikube tunnel 或 NodePort 暴露服务\n- [ ] 确认 kubectl 可远程操作 A 电脑的 K8s 集群（或通过 recovery-gateway 代理所有操作）\n- [ ] 测试工具函数是否正常工作：\n ```bash\n # 测试 PromQL 查询\n curl \"http://<A_IP>:<PROMETHEUS_PORT>/api/v1/query?query=up\"\n # 测试 recovery-gateway\n curl -X POST \"http://<A_IP>:<GATEWAY_PORT>/api/v1/restart\" \\\n -H \"Authorization: Bearer <TOKEN>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"target\":\"frontend\",\"kind\":\"deployment\",\"reason\":\"test\"}'\n ```\n\n#### 任务 4.2：模拟故障场景测试\n- [ ] **场景 1：CPU 飙升触发诊断**\n - 使用 `kubectl exec` 进入某 Pod 执行 `stress --cpu 2`\n - 观察 Agent 是否检测到 CPU 异常\n - 验证 Agent 能否正确分析并给出建议\n- [ ] **场景 2：服务 Crash 自动重启**\n - 手动删除一个 Pod（模拟 Crash）\n - 观察 Agent 是否检测到服务不可用\n - 验证 Agent 是否调用 recovery-gateway 执行恢复\n- [ ] **场景 3：日志异常检测**\n - 注入数据库连接错误（通过 ChaosMesh 网络分区）\n - 观察 Agent 是否查询日志并识别 `Connection refused` 错误\n- [ ] **场景 4：多告警并发**\n - 同时触发多个告警\n - 验证 Agent 能否正确聚合分析\n- [ ] 记录每个场景的 Agent 输出日志，作为演示素材\n\n#### 任务 4.3：端到端闭环验证\n- [ ] 完整链路测试：ChaosMesh 注入故障 → Prometheus 采集异常 → Alertmanager 触发 Webhook → Agent 唤醒 → 工具查询 → 根因诊断 → 调用 recovery-gateway 自愈 → 验证恢复\n- [ ] 记录端到端延迟（从故障注入到 Agent 完成诊断的总时间）\n- [ ] 记录自愈成功率（注入 10 次故障，统计成功自愈次数）\n\n---\n\n### 📋 阶段五：文档撰写与项目管理（约 4 小时）\n\n#### 任务 5.1：撰写大作业报告 — Agent 章节\n- [ ] 撰写报告章节：**\"基于 VeADK 的智能自愈运维 Agent 实现\"**（约 5-8 页）\n- [ ] 内容大纲：\n 1. 智能运维 Agent 背景与意义\n 2. Agent 架构设计（附架构图）\n 3. 工具注册与实现细节（PromQL 查询、日志抓取、远程重启）\n 4. ReAct 推理循环设计（附流程图）\n 5. 与 Alertmanager 和 recovery-gateway 的集成方案\n 6. 故障场景测试结果（附诊断报告截图）\n 7. 自愈效果评估（成功率、响应时间等指标）\n 8. 总结与改进方向\n\n#### 任务 5.2：项目管理（PM 职责）\n- [ ] GitHub 仓库管理：\n - 创建 `agent` 分支用于 Agent 代码开发\n - 定期 Review 成员提交的 PR（关注代码质量和合并冲突）\n - 合并前确保所有测试通过\n - 维护 `.gitignore` 和 `README.md`\n- [ ] 收集各成员撰写的报告章节：\n - 成员 A：集群架构部署与可观测性监控\n - 成员 B：微服务开发（discount-service、telemetry-service）\n - 成员 C：Selenium 功能测试与 JMeter 并发性能测试\n - 成员 D：KPI 异常检测与日志异常分类算法实现\n - 成员 E：Trace 异常定位与根因分类算法、多算法横向对比\n - 成员 F（自己）：智能运维 Agent 实现\n- [ ] PDF 报告排版：\n - 统一字体、行距、页眉页脚\n - 添加目录（含页码）\n - 统一图表编号（图 1-1、表 1-1 等）\n - 添加参考文献列表\n - 导出为 PDF\n- [ ] 答辩 PPT 制作：\n - 封面（项目名称、组号、成员名单）\n - 项目概述（1 页）\n - 系统架构（1 页）\n - 各成员贡献展示（每人 1-2 页）\n - 测试结果（2-3 页）\n - 算法对比（2-3 页）\n - Agent 演示（2-3 页，含自愈日志截图）\n - 总结与展望（1 页）\n - 总页数控制在 20-25 页\n\n#### 任务 5.3：录制演示视频\n- [ ] 与各成员协调录制多机联合演示视频：\n - 屏幕 1：压测屏（JMeter 并发压测界面）\n - 屏幕 2：监控自愈屏（Grafana 仪表盘 + Prometheus 界面）\n - 屏幕 3：Agent 运行屏（Agent 诊断日志 + 自愈动作输出）\n- [ ] 视频时长控制在 5-8 分钟\n- [ ] 添加字幕说明关键步骤\n\n---\n\n## 三、技术关键点与注意事项\n\n### 3.1 网络连通性\n- **核心挑战**：成员 F 的 Agent 运行在本地电脑，需要跨网络访问成员 A 电脑上的 Prometheus 和 recovery-gateway\n- **解决方案**：\n 1. 如果成员 A 使用 Minikube，通过 `minikube service recovery-gateway --url` 获取可访问的 URL\n 2. 如果成员 A 和 F 在同一局域网，直接使用 IP:端口访问\n 3. 如果不在同一网络，使用内网穿透工具（如 frp、ngrok）暴露服务\n\n### 3.2 大模型选择建议\n- **推荐方案**（按优先级）：\n 1. **DeepSeek API**（`deepseek-chat`）：性价比高，支持 Function Calling，中文理解能力强\n 2. **通义千问 API**（`qwen-plus`）：阿里云生态，兼容 OpenAI SDK\n 3. **火山引擎豆包 API**（`doubao-lite`）：VeADK 教程推荐\n- **关键要求**：必须支持 Function Calling / Tool Use 能力\n\n### 3.3 安全注意事项\n- [ ] recovery-gateway 的 Bearer Token 不要硬编码在代码中，使用环境变量\n- [ ] Agent 不会自动重启未在白名单中的服务\n- [ ] Agent 的 API Key 不提交到 Git 仓库（加入 `.gitignore`）\n- [ ] 所有外部调用（Prometheus、recovery-gateway）需要超时控制（默认 10 秒）\n\n### 3.4 容错设计\n- [ ] Prometheus 不可用时，Agent 应降级为纯日志分析模式\n- [ ] recovery-gateway 不可用时，Agent 应降级为仅诊断模式（不执行自愈）\n- [ ] LLM API 调用失败时，实现重试机制（最多 3 次，指数退避）\n- [ ] Webhook 服务崩溃时，Alertmanager 可自动重试（利用其内置重试机制）\n\n---\n\n## 四、交付物清单\n\n| 序号 | 交付物 | 格式 | 说明 |\n|------|--------|------|------|\n| 1 | `veadk_agent/` 完整源码 | Python | Agent 核心代码，含 agent.py, tools.py, config.py, webhook_server.py |\n| 2 | `requirements.txt` | 文本 | Python 依赖清单 |\n| 3 | `agent_config.yaml` | YAML | Agent 配置文件模板 |\n| 4 | `docs/agent_design.md` | Markdown | Agent 设计文档（含架构图、流程图） |\n| 5 | 诊断日志截图 | PNG | 至少 3 个故障场景的 Agent 诊断输出截图 |\n| 6 | 自愈验证日志 | 文本 | 端到端自愈闭环的日志输出 |\n| 7 | 报告章节 PDF | PDF | \"基于 VeADK 的智能自愈运维 Agent 实现\" 章节（5-8 页） |\n| 8 | 合并后的完整报告 | PDF | 各组员章节合并排版后的最终报告 |\n| 9 | 答辩 PPT | PPTX | 20-25 页展示用幻灯片 |\n| 10 | 演示视频 | MP4 | 5-8 分钟多机联合演示 |\n\n---\n\n## 五、时间规划（四周）\n\n```\n📅 第一周（6/12 - 6/18）：环境搭建 + Agent 基础框架\n├── Day 1-2：阅读文档，克隆仓库，理解现有代码 [已完成]\n├── Day 3-4：Python 环境准备，大模型 API 申请与测试\n├── Day 5-6：编写 config.py + tools.py（四个工具实现）\n└── Day 7：编写 agent.py（ReAct Loop 框架 + System Prompt）\n\n📅 第二周（6/19 - 6/25）：Agent 完善 + Webhook 集成\n├── Day 1-3：完善 Agent 推理链 + 工具 Schema 定义\n├── Day 4-5：编写 webhook_server.py（Alertmanager 对接）\n├── Day 6：编写轮询模式备用方案\n└── Day 7：单元测试（pytest）\n\n📅 第三周（6/26 - 7/2）：联调 + 故障测试\n├── Day 1-2：与成员 A 打通网络（Prometheus + recovery-gateway）\n├── Day 3-4：模拟故障场景测试（4 个场景）\n├── Day 5：端到端闭环验证 + 性能记录\n└── Day 6-7：修复问题 + 优化 Agent 诊断准确率\n\n📅 第四周（7/3 - 7/9）：文档 + PPT + 演示\n├── Day 1-2：撰写报告章节\n├── Day 3：收集各成员报告，合并排版 PDF\n├── Day 4-5：制作答辩 PPT\n├── Day 6：录制演示视频\n└── Day 7：最终检查，提交到 GitHub\n```\n\n---\n\n## 六、检查点与风险应对\n\n| 风险 | 影响 | 应对措施 |\n|------|------|----------|\n| 大模型 API 申请延迟 | 高 | 提前申请，准备多个备选 API（DeepSeek + 通义千问 + 豆包） |\n| 成员 A 电脑网络不可达 | 高 | 使用内网穿透（frp/ngrok），或让 Agent 也部署到 A 电脑的 Minikube 中 |\n| recovery-gateway 尚未就绪 | 中 | Agent 先使用 kubectl 直接操作，后续再切换到 recovery-gateway |\n| LLM 诊断准确率低 | 中 | 优化 System Prompt，添加 Few-shot 示例，增加工具描述详细度 |\n| 时间不足 | 中 | 优先保证核心 Agent 功能可用，PM 工作（PPT 排版）可简化为模板 |\n\n---\n\n## 七、参考资料\n\n1. **VeADK 智能运维教程**：[使用智能体进行智能运维](https://nankai.feishu.cn/wiki/AuPtwvDlKinPaskYVubcWoLancd)\n2. **Online-Boutique 官方仓库**：[GoogleCloudPlatform/microservices-demo](https://github.com/GoogleCloudPlatform/microservices-demo)\n3. **小组 GitHub 仓库**：[Software-Testing-Group-13](https://github.com/AnnieFandingying/Software-Testing-Group-13)\n4. **Prometheus HTTP API 文档**：[Prometheus Querying API](https://prometheus.io/docs/prometheus/latest/querying/api/)\n5. **Alertmanager Webhook 配置**：[Alertmanager Webhook](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config)\n6. **OpenAI Function Calling 文档**：[Function Calling Guide](https://platform.openai.com/docs/guides/function-calling)\n7. **Kubernetes Python Client**：[kubernetes-client/python](https://github.com/kubernetes-client/python)\n8. **ChaosMesh 官方文档**：[Chaos Mesh](https://chaos-mesh.org/docs/)\n\n---\n\n> **最后更新**：2026-06-12 \n> **状态**：阶段一进行中 — 已完成文档阅读和仓库分析，下一步进行 Agent 代码开发\n"}, "0aaca6ee52984567d2d96eab89b868bdea427c35": {"t": 1785763673.5560405, "n": 18730, "h": "ebf4bfc68752cefd", "c": "# 成员 F（智能体开发与系统集成）任务执行清单\n\n> **项目**：软件测试与维护（2026年春）大作业 — 加分项二：智能体自动运维 \n> **小组**：Group 13 \n> **GitHub 仓库**：https://github.com/AnnieFandingying/Software-Testing-Group-13 \n> **成员 F 职责**：基于 VeADK 框架开发 AIOps Agent + 项目 PM（GitHub 管理、PDF 排版、PPT 美化）\n\n---\n\n## 一、已完成内容概述（成员 A 和 B 的交付物）\n\n通过克隆并分析 GitHub 仓库 `main` 分支，成员 A 和 B 已完成以下工作：\n\n### 1.1 成员 A（平台与可观测性工程师）已完成：\n- ✅ 部署 Online-Boutique 微服务系统（基于 Minikube 集群）\n- ✅ 配置 Prometheus + Grafana 监控系统\n- ✅ **开发微服务3**：`recovery-gateway`（自愈网关）— 提供 REST API 供 Agent 远程调用执行 Pod 重启/服务降级\n - 路径：`src/recoverygateway/`\n - API 端点：`POST /api/v1/restart`、`POST /api/v1/degrade`、`GET /healthz`、`GET /metrics`\n - 认证：Bearer Token（环境变量 `RECOVERY_AUTH_TOKEN`）\n - K8s 清单：`kubernetes-manifests/recoverygateway.yaml`\n- ✅ 编写 K8s Deployment/Service/RBAC YAML 清单\n\n### 1.2 成员 B（微服务开发工程师）已完成：\n- ✅ **开发微服务1**：`discount-service`（618 满减折扣服务，gRPC）\n - 路径：`src/discountservice/`\n - 满 200 减 50、满 400 减 100、满 700 减 200\n - 仅对 CNY 币种生效\n- ✅ **开发微服务2**：`telemetry-service`（遥测聚合服务，HTTP）\n - 路径：`src/telemetryservice/`\n - 接收事件 `POST /events`，暴露 Prometheus 指标 `GET /metrics`\n - 弱依赖语义：遥测挂掉不影响主链路\n- ✅ 修改 `checkoutservice`：集成 discount-service gRPC 调用 + 遥测上报\n- ✅ 修改 `frontend`：结算页面金额修正 + 遥测上报\n- ✅ 编写 Dockerfile、K8s YAML、Helm Chart\n- ✅ 编写 `Ability.md`（功能说明）和 `Check.md`（编译自检清单）\n\n### 1.3 系统架构现状（了解 Agent 的工作环境）：\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Minikube 集群 (成员A电脑) │\n│ │\n│ ┌──────────────────────────────────────────────────────┐ │\n│ │ Online-Boutique 微服务 │ │\n│ │ frontend → checkoutservice → discountservice (NEW) │ │\n│ │ ↓ → telemetryservice (NEW) │ │\n│ │ cartservice, paymentservice, shippingservice, ... │ │\n│ └──────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │\n│ │ Prometheus │ │ Grafana │ │ recovery-gateway │ │\n│ │ (采集指标) │ │ (可视化) │ │ (自愈网关 :8080) │ │\n│ └──────┬──────┘ └──────────────┘ └────────▲─────────┘ │\n│ │ │ │\n│ ┌──────┴─────────────────────────────────────┴──────┐ │\n│ │ Alertmanager (告警 Webhook) │ │\n│ └──────────────────────────┬───────────────────────┘ │\n└─────────────────────────────┼─────────────────────────────┘\n │ HTTP POST (告警 JSON)\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 成员 F 电脑（Agent 运行环境） │\n│ │\n│ ┌──────────────────────────────────────────────────────┐ │\n│ │ VeADK Agent (veadk_agent.py) │ │\n│ │ │ │\n│ │ ① 接收 Alertmanager Webhook 告警 │ │\n│ │ ② ReAct 推理循环（LLM 分析 → 工具调用 → 综合分析） │ │\n│ │ ③ 工具1：execute_promql → 查询 Prometheus API │ │\n│ │ ④ 工具2：get_service_logs → 获取 K8s Pod 日志 │ │\n│ │ ⑤ 工具3：restart_pod → 调用 recovery-gateway 重启服务 │ │\n│ │ ⑥ 输出诊断报告 + 执行自愈动作 │ │\n│ └──────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## 二、详细任务分解（总计约 40 小时）\n\n### 📋 阶段一：环境准备与大模型 API 打通（约 8 小时）\n\n#### 任务 1.1：Python 开发环境准备\n- [ ] 确认 Python 3.8+ 已安装（`python --version`）\n- [ ] 创建项目虚拟环境：`python -m venv venv`\n- [ ] 激活虚拟环境并安装依赖：\n ```bash\n pip install openai requests fastapi uvicorn pyyaml kubernetes\n ```\n- [ ] 创建项目目录结构：\n ```\n cs-final-test/\n ├── task.md # 本任务清单\n ├── veadk_agent/\n │ ├── __init__.py\n │ ├── agent.py # Agent 核心逻辑（ReAct Loop）\n │ ├── tools.py # 工具注册与实现\n │ ├── config.py # 配置管理（环境变量读取）\n │ ├── webhook_server.py # Alertmanager Webhook 接收服务\n │ ├── prometheus_client.py # Prometheus API 查询客户端\n │ └── requirements.txt # Python 依赖清单\n ├── tests/\n │ ├── test_tools.py # 工具函数单测\n │ ├── test_agent.py # Agent 推理链单测\n │ └── test_integration.py # 端到端集成测试\n ├── config/\n │ └── agent_config.yaml # Agent 配置文件\n └── docs/\n └── agent_design.md # Agent 设计文档\n ```\n\n#### 任务 1.2：大模型 API 配置\n- [ ] 注册/获取大模型 API Key（推荐使用火山引擎豆包 API 或其他国产大模型）\n - 建议 API：DeepSeek API、通义千问 API、火山引擎豆包 API\n - 参考 VeADK 教程：`https://nankai.feishu.cn/wiki/AuPtwvDlKinPaskYVubcWoLancd`\n- [ ] 配置环境变量：\n ```bash\n export OPENAI_API_KEY=\"sk-xxxxxxxxxxxxx\"\n export OPENAI_BASE_URL=\"https://api.deepseek.com\" # 或其他兼容 OpenAI API 的地址\n ```\n- [ ] 编写简单的 API 连通性测试脚本，确认可以正常调用大模型\n\n#### 任务 1.3：克隆仓库并理解现有代码\n- [x] 已克隆 GitHub 仓库：`git clone https://github.com/AnnieFandingying/Software-Testing-Group-13.git`\n- [x] 已阅读 `Ability.md`（微服务功能说明）\n- [x] 已阅读 `Check.md`（编译自检清单）\n- [x] 已阅读 `recovery-gateway` 源码（理解 Agent 自愈 API）\n- [ ] 与成员 A 确认以下连接信息：\n - Prometheus 地址（Minikube 暴露的 URL）\n - recovery-gateway 的 Service 地址和 Bearer Token\n - Alertmanager Webhook 配置状态\n- [ ] 阅读 VeADK 教程原文（飞书文档链接）\n\n---\n\n### 📋 阶段二：Agent 核心逻辑开发（约 15 小时）\n\n#### 任务 2.1：编写 Agent 配置管理模块 (`config.py`)\n- [ ] 实现从环境变量读取配置：\n - `PROMETHEUS_URL`：Prometheus 查询地址\n - `RECOVERY_GATEWAY_URL`：recovery-gateway API 地址\n - `RECOVERY_AUTH_TOKEN`：自愈网关认证 Token\n - `LLM_API_KEY`：大模型 API Key\n - `LLM_BASE_URL`：大模型 API 地址\n - `LLM_MODEL`：模型名称（默认 `gpt-4o` 或 `deepseek-chat`）\n - `ALERTMANAGER_WEBHOOK_PORT`：Webhook 监听端口（默认 `5000`）\n - `SOCK_SHOP_NAMESPACE`：K8s 命名空间（默认 `sock-shop`）\n- [ ] 支持从 `.env` 文件加载配置\n\n#### 任务 2.2：实现工具函数模块 (`tools.py`)\n按照 VeADK 教程中定义的三个核心工具：\n\n**工具 1：`execute_promql(query_str: str) -> str`**\n- [ ] 实现 Prometheus HTTP API 查询：\n - 调用 `GET {PROMETHEUS_URL}/api/v1/query?query={query_str}`\n - 支持即时查询（instant query）\n - 解析 JSON 响应并格式化返回\n - 错误处理：超时、连接失败、无数据\n- [ ] 预定义常用 PromQL 查询模板（方便 LLM 选择）：\n - CPU 使用率：`sum(rate(container_cpu_usage_seconds_total{namespace=\"sock-shop\"}[5m])) by (pod)`\n - 内存使用率：`sum(container_memory_usage_bytes{namespace=\"sock-shop\"}) by (pod)`\n - 请求错误率：`sum(rate(http_requests_total{status_code=~\"5..\"}[5m])) / sum(rate(http_requests_total[5m]))`\n - 请求延迟 P99：`histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))`\n - Pod 重启次数：`kube_pod_container_status_restarts_total{namespace=\"sock-shop\"}`\n - 文件系统使用率：`sum(container_fs_usage_bytes{namespace=\"sock-shop\"}) by (pod)`\n\n**工具 2：`get_service_logs(service_name: str, tail_lines: int = 50) -> str`**\n- [ ] 实现通过 kubectl 获取 Pod 日志：\n - 使用 `kubectl logs` 命令（通过 subprocess 或 kubernetes Python 客户端）\n - 自动查找服务对应的 Pod 名称\n - 支持 `--tail` 参数限制行数\n - 支持 `--timestamps` 获取时间戳\n- [ ] 备选方案：如果 kubectl 不可用，通过 Kubernetes Python 客户端读取\n- [ ] 日志格式化输出，方便 LLM 理解\n\n**工具 3：`restart_pod(service_name: str, namespace: str = \"sock-shop\") -> str`**\n- [ ] 调用 recovery-gateway REST API：\n ```python\n POST {RECOVERY_GATEWAY_URL}/api/v1/restart\n Headers:\n Authorization: Bearer {RECOVERY_AUTH_TOKEN}\n Content-Type: application/json\n Body:\n {\n \"target\": \"{service_name}\",\n \"namespace\": \"{namespace}\",\n \"kind\": \"deployment\",\n \"reason\": \"agent_auto_recovery\"\n }\n ```\n- [ ] 验证 API 响应，确认重启操作是否成功\n- [ ] 如果 recovery-gateway 不可用，降级使用 kubectl 命令执行 `kubectl rollout restart deployment/{service_name}`\n- [ ] 增加安全检查：仅允许重启白名单中的服务\n\n**工具 4（扩展，加分项）：`set_degrade_mode(service_name: str, mode: str, ttl_seconds: int = 900) -> str`**\n- [ ] 调用 recovery-gateway 的 `/api/v1/degrade` 端点\n- [ ] 支持将服务设置为 `degraded` 或 `normal` 模式\n- [ ] 在诊断出部分服务压力过大时，可自动执行降级\n\n#### 任务 2.3：实现 Agent 核心推理循环 (`agent.py`)\n- [ ] 设计 Agent System Prompt（系统人设）：\n ```\n 你是一个资深的云原生 AIOps 专家。\n 当收到告警时，你不能盲目判断。你需要通过调用工具来收集证据，\n 区分这是正常的流量突增，还是底层组件发生了不可见的老化与\n Fail-Slow 劣化（例如死锁、连接池耗尽、慢查询）。\n \n 请遵循以下思考路径：\n ① 分析当前告警信息\n ② 决定是否需要更多数据（调用工具获取）\n ③ 交叉分析多项指标和日志\n ④ 得出根因诊断结论 + 给出置信度\n ⑤ 如果确认为可自愈故障，执行恢复操作\n ⑥ 输出结构化诊断报告\n ```\n- [ ] 实现 ReAct Loop（推理-行动循环）：\n - 最多允许 5 轮工具调用（防止无限循环）\n - 每轮将用户告警 + 工具返回结果加入 messages 上下文\n - 支持多工具并行调用（当多个查询不互相依赖时）\n- [ ] 实现诊断报告结构化输出：\n ```json\n {\n \"alert_time\": \"2026-06-12T14:30:00\",\n \"alert_summary\": \"catalogue 服务 CPU 突增至 85%\",\n \"root_cause\": \"数据库连接池耗尽，导致请求堆积\",\n \"confidence\": 0.85,\n \"supporting_evidence\": [\n \"PromQL 查询显示 catalogue CPU 持续 >80% 已达 5 分钟\",\n \"日志中频繁出现 'DB Pool exhausted' 错误\",\n \"数据库连接数指标显示连接池使用率 100%\"\n ],\n \"actions_taken\": [\n \"已通过 recovery-gateway 重启 catalogue 服务\",\n \"建议检查数据库最大连接数配置\"\n ],\n \"recovery_result\": \"catalogue 服务已成功重启，CPU 恢复正常\"\n }\n ```\n\n#### 任务 2.4：定义工具 Schema（供 LLM Function Calling 使用）\n- [ ] 按照 OpenAI Function Calling 格式定义每个工具：\n ```python\n TOOLS_SCHEMA = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"execute_promql\",\n \"description\": \"执行 PromQL 查询获取 Prometheus 监控指标。常用查询：\"\n \"1) CPU: sum(rate(container_cpu_usage_seconds_total{namespace='sock-shop'}[5m])) by (pod)\"\n \"2) 内存: sum(container_memory_usage_bytes{namespace='sock-shop'}) by (pod)\"\n \"3) 错误率: sum(rate(http_requests_total{status_code=~'5..'}[5m])) by (pod)\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"query_str\": {\n \"type\": \"string\",\n \"description\": \"要执行的 PromQL 查询语句\"\n }\n },\n \"required\": [\"query_str\"]\n }\n }\n },\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_service_logs\",\n \"description\": \"获取指定微服务的最新 Kubernetes Pod 日志\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"service_name\": {\"type\": \"string\", \"description\": \"服务名称，如 catalogue, frontend\"},\n \"tail_lines\": {\"type\": \"integer\", \"description\": \"返回最后 N 行日志，默认 50\"}\n },\n \"required\": [\"service_name\"]\n }\n }\n },\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"restart_pod\",\n \"description\": \"当确认服务处于死锁或内存泄漏等无法恢复的僵死状态时，通过 recovery-gateway 重启该服务。仅限白名单中的服务。\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"service_name\": {\"type\": \"string\", \"description\": \"要重启的服务名称\"},\n \"namespace\": {\"type\": \"string\", \"description\": \"K8s 命名空间，默认 sock-shop\"}\n },\n \"required\": [\"service_name\"]\n }\n }\n }\n ]\n ```\n- [ ] 确保工具描述中包含足够的提示信息（示例 PromQL），帮助 LLM 做出正确的工具选择\n\n---\n\n### 📋 阶段三：Webhook 接收与告警触发（约 8 小时）\n\n#### 任务 3.1：实现 Alertmanager Webhook 接收服务 (`webhook_server.py`)\n- [ ] 使用 FastAPI/Flask 创建 HTTP 服务器，接收 Alertmanager 发送的告警 JSON\n- [ ] 解析 Alertmanager Webhook 格式：\n ```json\n {\n \"receiver\": \"agent-webhook\",\n \"status\": \"firing\",\n \"alerts\": [\n {\n \"status\": \"firing\",\n \"labels\": {\n \"alertname\": \"HighCPUUsage\",\n \"severity\": \"critical\",\n \"service\": \"catalogue\",\n \"namespace\": \"sock-shop\"\n },\n \"annotations\": {\n \"summary\": \"catalogue service CPU usage is above 80%\",\n \"description\": \"CPU usage has been above 80% for 5 minutes\"\n },\n \"startsAt\": \"2026-06-12T14:25:00Z\",\n \"endsAt\": \"0001-01-01T00:00:00Z\"\n }\n ],\n \"groupLabels\": {},\n \"commonLabels\": {},\n \"externalURL\": \"http://prometheus:9093\"\n }\n ```\n- [ ] 告警去重：同一告警在 firing/resolved 周期内只触发一次 Agent 诊断\n- [ ] 告警优先级过滤：根据 severity 标签决定是否触发 Agent\n- [ ] 添加 `/healthz` 健康检查端点\n- [ ] 添加 `/metrics` 端点，暴露 Agent 自身运行指标（诊断次数、成功率等）\n\n#### 任务 3.2：告警格式化与上下文构建\n- [ ] 将 Alertmanager 告警转换为 Agent 可理解的文本描述：\n ```python\n def format_alert_for_agent(alert: dict) -> str:\n return f\"\"\"\n [告警名称] {alert['labels']['alertname']}\n [严重程度] {alert['labels']['severity']}\n [涉及服务] {alert['labels'].get('service', 'unknown')}\n [告警摘要] {alert['annotations']['summary']}\n [详细描述] {alert['annotations']['description']}\n [开始时间] {alert['startsAt']}\n [当前状态] {alert['status']}\n \"\"\"\n ```\n- [ ] 支持多告警聚合：将同一时间窗口内的多个相关告警打包发送给 Agent\n\n#### 任务 3.3：轮询模式（备选方案，当 Alertmanager 不可用时）\n- [ ] 实现定时巡检函数 `fetch_basic_cpu()`：\n - 每 10 秒查询一次关键服务的 CPU 使用率\n - 超过阈值（如 CPU > 0.5 或 80%）时主动触发 Agent 诊断\n- [ ] 参考教程中的 `main()` 函数实现守护进程模式\n\n---\n\n### 📋 阶段四：闭环联调与端到端验证（约 5 小时）\n\n#### 任务 4.1：与成员 A 的系统打通\n- [ ] 确认 Prometheus URL 连通性（从 F 电脑可访问 A 电脑的 Prometheus）\n- [ ] 确认 recovery-gateway API 连通性（从 F 电脑可调用 A 电脑的 K8s 集群内的 recovery-gateway）\n - 可能需要 Minikube tunnel 或 NodePort 暴露服务\n- [ ] 确认 kubectl 可远程操作 A 电脑的 K8s 集群（或通过 recovery-gateway 代理所有操作）\n- [ ] 测试工具函数是否正常工作：\n ```bash\n # 测试 PromQL 查询\n curl \"http://<A_IP>:<PROMETHEUS_PORT>/api/v1/query?query=up\"\n # 测试 recovery-gateway\n curl -X POST \"http://<A_IP>:<GATEWAY_PORT>/api/v1/restart\" \\\n -H \"Authorization: Bearer <TOKEN>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"target\":\"frontend\",\"kind\":\"deployment\",\"reason\":\"test\"}'\n ```\n\n#### 任务 4.2：模拟故障场景测试\n- [ ] **场景 1：CPU 飙升触发诊断**\n - 使用 `kubectl exec` 进入某 Pod 执行 `stress --cpu 2`\n - 观察 Agent 是否检测到 CPU 异常\n - 验证 Agent 能否正确分析并给出建议\n- [ ] **场景 2：服务 Crash 自动重启**\n - 手动删除一个 Pod（模拟 Crash）\n - 观察 Agent 是否检测到服务不可用\n - 验证 Agent 是否调用 recovery-gateway 执行恢复\n- [ ] **场景 3：日志异常检测**\n - 注入数据库连接错误（通过 ChaosMesh 网络分区）\n - 观察 Agent 是否查询日志并识别 `Connection refused` 错误\n- [ ] **场景 4：多告警并发**\n - 同时触发多个告警\n - 验证 Agent 能否正确聚合分析\n- [ ] 记录每个场景的 Agent 输出日志，作为演示素材\n\n#### 任务 4.3：端到端闭环验证\n- [ ] 完整链路测试：ChaosMesh 注入故障 → Prometheus 采集异常 → Alertmanager 触发 Webhook → Agent 唤醒 → 工具查询 → 根因诊断 → 调用 recovery-gateway 自愈 → 验证恢复\n- [ ] 记录端到端延迟（从故障注入到 Agent 完成诊断的总时间）\n- [ ] 记录自愈成功率（注入 10 次故障，统计成功自愈次数）\n\n---\n\n### 📋 阶段五：文档撰写与项目管理（约 4 小时）\n\n#### 任务 5.1：撰写大作业报告 — Agent 章节\n- [ ] 撰写报告章节：**\"基于 VeADK 的智能自愈运维 Agent 实现\"**（约 5-8 页）\n- [ ] 内容大纲：\n 1. 智能运维 Agent 背景与意义\n 2. Agent 架构设计（附架构图）\n 3. 工具注册与实现细节（PromQL 查询、日志抓取、远程重启）\n 4. ReAct 推理循环设计（附流程图）\n 5. 与 Alertmanager 和 recovery-gateway 的集成方案\n 6. 故障场景测试结果（附诊断报告截图）\n 7. 自愈效果评估（成功率、响应时间等指标）\n 8. 总结与改进方向\n\n#### 任务 5.2：项目管理（PM 职责）\n- [ ] GitHub 仓库管理：\n - 创建 `agent` 分支用于 Agent 代码开发\n - 定期 Review 成员提交的 PR（关注代码质量和合并冲突）\n - 合并前确保所有测试通过\n - 维护 `.gitignore` 和 `README.md`\n- [ ] 收集各成员撰写的报告章节：\n - 成员 A：集群架构部署与可观测性监控\n - 成员 B：微服务开发（discount-service、telemetry-service）\n - 成员 C：Selenium 功能测试与 JMeter 并发性能测试\n - 成员 D：KPI 异常检测与日志异常分类算法实现\n - 成员 E：Trace 异常定位与根因分类算法、多算法横向对比\n - 成员 F（自己）：智能运维 Agent 实现\n- [ ] PDF 报告排版：\n - 统一字体、行距、页眉页脚\n - 添加目录（含页码）\n - 统一图表编号（图 1-1、表 1-1 等）\n - 添加参考文献列表\n - 导出为 PDF\n- [ ] 答辩 PPT 制作：\n - 封面（项目名称、组号、成员名单）\n - 项目概述（1 页）\n - 系统架构（1 页）\n - 各成员贡献展示（每人 1-2 页）\n - 测试结果（2-3 页）\n - 算法对比（2-3 页）\n - Agent 演示（2-3 页，含自愈日志截图）\n - 总结与展望（1 页）\n - 总页数控制在 20-25 页\n\n#### 任务 5.3：录制演示视频\n- [ ] 与各成员协调录制多机联合演示视频：\n - 屏幕 1：压测屏（JMeter 并发压测界面）\n - 屏幕 2：监控自愈屏（Grafana 仪表盘 + Prometheus 界面）\n - 屏幕 3：Agent 运行屏（Agent 诊断日志 + 自愈动作输出）\n- [ ] 视频时长控制在 5-8 分钟\n- [ ] 添加字幕说明关键步骤\n\n---\n\n## 三、技术关键点与注意事项\n\n### 3.1 网络连通性\n- **核心挑战**：成员 F 的 Agent 运行在本地电脑，需要跨网络访问成员 A 电脑上的 Prometheus 和 recovery-gateway\n- **解决方案**：\n 1. 如果成员 A 使用 Minikube，通过 `minikube service recovery-gateway --url` 获取可访问的 URL\n 2. 如果成员 A 和 F 在同一局域网，直接使用 IP:端口访问\n 3. 如果不在同一网络，使用内网穿透工具（如 frp、ngrok）暴露服务\n\n### 3.2 大模型选择建议\n- **推荐方案**（按优先级）：\n 1. **DeepSeek API**（`deepseek-chat`）：性价比高，支持 Function Calling，中文理解能力强\n 2. **通义千问 API**（`qwen-plus`）：阿里云生态，兼容 OpenAI SDK\n 3. **火山引擎豆包 API**（`doubao-lite`）：VeADK 教程推荐\n- **关键要求**：必须支持 Function Calling / Tool Use 能力\n\n### 3.3 安全注意事项\n- [ ] recovery-gateway 的 Bearer Token 不要硬编码在代码中，使用环境变量\n- [ ] Agent 不会自动重启未在白名单中的服务\n- [ ] Agent 的 API Key 不提交到 Git 仓库（加入 `.gitignore`）\n- [ ] 所有外部调用（Prometheus、recovery-gateway）需要超时控制（默认 10 秒）\n\n### 3.4 容错设计\n- [ ] Prometheus 不可用时，Agent 应降级为纯日志分析模式\n- [ ] recovery-gateway 不可用时，Agent 应降级为仅诊断模式（不执行自愈）\n- [ ] LLM API 调用失败时，实现重试机制（最多 3 次，指数退避）\n- [ ] Webhook 服务崩溃时，Alertmanager 可自动重试（利用其内置重试机制）\n\n---\n\n## 四、交付物清单\n\n| 序号 | 交付物 | 格式 | 说明 |\n|------|--------|------|------|\n| 1 | `veadk_agent/` 完整源码 | Python | Agent 核心代码，含 agent.py, tools.py, config.py, webhook_server.py |\n| 2 | `requirements.txt` | 文本 | Python 依赖清单 |\n| 3 | `agent_config.yaml` | YAML | Agent 配置文件模板 |\n| 4 | `docs/agent_design.md` | Markdown | Agent 设计文档（含架构图、流程图） |\n| 5 | 诊断日志截图 | PNG | 至少 3 个故障场景的 Agent 诊断输出截图 |\n| 6 | 自愈验证日志 | 文本 | 端到端自愈闭环的日志输出 |\n| 7 | 报告章节 PDF | PDF | \"基于 VeADK 的智能自愈运维 Agent 实现\" 章节（5-8 页） |\n| 8 | 合并后的完整报告 | PDF | 各组员章节合并排版后的最终报告 |\n| 9 | 答辩 PPT | PPTX | 20-25 页展示用幻灯片 |\n| 10 | 演示视频 | MP4 | 5-8 分钟多机联合演示 |\n\n---\n\n## 五、时间规划（四周）\n\n```\n📅 第一周（6/12 - 6/18）：环境搭建 + Agent 基础框架\n├── Day 1-2：阅读文档，克隆仓库，理解现有代码 [已完成]\n├── Day 3-4：Python 环境准备，大模型 API 申请与测试\n├── Day 5-6：编写 config.py + tools.py（四个工具实现）\n└── Day 7：编写 agent.py（ReAct Loop 框架 + System Prompt）\n\n📅 第二周（6/19 - 6/25）：Agent 完善 + Webhook 集成\n├── Day 1-3：完善 Agent 推理链 + 工具 Schema 定义\n├── Day 4-5：编写 webhook_server.py（Alertmanager 对接）\n├── Day 6：编写轮询模式备用方案\n└── Day 7：单元测试（pytest）\n\n📅 第三周（6/26 - 7/2）：联调 + 故障测试\n├── Day 1-2：与成员 A 打通网络（Prometheus + recovery-gateway）\n├── Day 3-4：模拟故障场景测试（4 个场景）\n├── Day 5：端到端闭环验证 + 性能记录\n└── Day 6-7：修复问题 + 优化 Agent 诊断准确率\n\n📅 第四周（7/3 - 7/9）：文档 + PPT + 演示\n├── Day 1-2：撰写报告章节\n├── Day 3：收集各成员报告，合并排版 PDF\n├── Day 4-5：制作答辩 PPT\n├── Day 6：录制演示视频\n└── Day 7：最终检查，提交到 GitHub\n```\n\n---\n\n## 六、检查点与风险应对\n\n| 风险 | 影响 | 应对措施 |\n|------|------|----------|\n| 大模型 API 申请延迟 | 高 | 提前申请，准备多个备选 API（DeepSeek + 通义千问 + 豆包） |\n| 成员 A 电脑网络不可达 | 高 | 使用内网穿透（frp/ngrok），或让 Agent 也部署到 A 电脑的 Minikube 中 |\n| recovery-gateway 尚未就绪 | 中 | Agent 先使用 kubectl 直接操作，后续再切换到 recovery-gateway |\n| LLM 诊断准确率低 | 中 | 优化 System Prompt，添加 Few-shot 示例，增加工具描述详细度 |\n| 时间不足 | 中 | 优先保证核心 Agent 功能可用，PM 工作（PPT 排版）可简化为模板 |\n\n---\n\n## 七、参考资料\n\n1. **VeADK 智能运维教程**：[使用智能体进行智能运维](https://nankai.feishu.cn/wiki/AuPtwvDlKinPaskYVubcWoLancd)\n2. **Online-Boutique 官方仓库**：[GoogleCloudPlatform/microservices-demo](https://github.com/GoogleCloudPlatform/microservices-demo)\n3. **小组 GitHub 仓库**：[Software-Testing-Group-13](https://github.com/AnnieFandingying/Software-Testing-Group-13)\n4. **Prometheus HTTP API 文档**：[Prometheus Querying API](https://prometheus.io/docs/prometheus/latest/querying/api/)\n5. **Alertmanager Webhook 配置**：[Alertmanager Webhook](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config)\n6. **OpenAI Function Calling 文档**：[Function Calling Guide](https://platform.openai.com/docs/guides/function-calling)\n7. **Kubernetes Python Client**：[kubernetes-client/python](https://github.com/kubernetes-client/python)\n8. **ChaosMesh 官方文档**：[Chaos Mesh](https://chaos-mesh.org/docs/)\n\n---\n\n> **最后更新**：2026-06-12 \n> **状态**：阶段一进行中 — 已完成文档阅读和仓库分析，下一步进行 Agent 代码开发\n"}}}} |