reem-mor/piter-aiops
GitHub: reem-mor/piter-aiops
基于 AWS Bedrock Agent 与 RAG 的代理式运维事件响应平台，为 SRE 和 DevOps 团队提供带引用依据的实时告警分流与升级指导。
Stars: 1 | Forks: 0
> **作品集旗舰项目** — 基于 AWS Bedrock 的代理式事件响应。课程归档：[amdocs-ai-course](https://github.com/reem-mor/amdocs-ai-course)。
# PITER AiOps
**面向 NOC、DevOps 和 SRE 团队的 AI 驱动事件响应**
**优先级** · **调查** · **分流** · **升级** · **解决**
[](#快速开始)
### 提交链接
| 资源 | 链接 |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **在线演示 (EC2)** | **[http://ec2-3-235-22-143.compute-1.amazonaws.com:8080/](http://ec2-3-235-22-143.compute-1.amazonaws.com:8080/)** *(已验证 `/health` 200)* |
| **Lovable UI (静态)** | **[https://ops-insight-nexus.lovable.app](https://ops-insight-nexus.lovable.app)** *(前端预览；Bedrock 流程使用 EC2)* |
| **演示文稿** | [`presentation/presentation_v1.pptx`](presentation/presentation_v1.pptx) |
| **演示脚本** | [`docs/demo_script.md`](docs/demo_script.md) |
| **部署指南** | [`docs/ec2_deployment.md`](docs/ec2_deployment.md) |
| **同步审计 (6月10日)** | [`docs/PHASE1_SYNC_AUDIT.md`](docs/PHASE1_SYNC_AUDIT.md) |
## 目录
- [项目目标](#project-goal)
- [需求覆盖](#requirements-coverage)
- [快速开始](#quick-start)
- [5分钟演示流程](#5-minute-demo-flow)
- [系统架构](#system-architecture)
- [核心组件](#key-components)
- [用例](#use-cases)
- [截图](#screenshots)
- [错误处理与安全](#error-handling-and-safety)
- [测试证据](#testing-evidence)
- [挑战与后续计划](#challenges-and-next-steps)
- [文档索引](#documentation-index)
- [课程背景](#course-context)
## 项目目标
PITER AiOps 是一款面向生产运营团队的 AI 事件响应助手。它结合了 Amazon Bedrock Agent 编排、Knowledge Base RAG、结构化富集工具和 React 运维控制台，让待命工程师能在数秒内获得**有依据、带引用的分流指导**，而无需在告警压力下苦苦翻阅操作手册。
| 阶段 | 含义 |
| ----------------- | ------------------------------------------------------------------------ |
| **Priority** | 使用严重性策略、告警上下文和业务影响对 P1–P4 进行分类 |
| **Investigation** | 仅使用 KB 引用和 Action Group 工具结果 — 绝不捏造事实 |
| **Triage** | 优先提供有序、可逆的步骤；为每一步引用操作手册 |
| **Escalation** | 当发生 P1–P3 或面临监管风险时；从策略中指明待命路径 |
| **Resolution** | 验证检查、安全恢复路径以及事后跟进 |
**问题：** 告警全天候触发。工程师在严重性不断攀升的同时，还要浪费关键时间去搜索操作手册、历史工单和事后复盘报告。
**解决方案：** 将操作手册、告警历史和事后复盘报告输入到 Bedrock Knowledge Base 中。当告警发生时，只需提出问题，即可在数秒内获得**有依据、带引用的回答** — 此外，还能通过四个 Action Group 工具进行部署关联、相似事件查找和升级预览。
**业务影响（演示）：** UI 追踪了说明性的 KPI（例如 MTTR 降低）。`data/source/business_impact.json` 中的美元数字仅为**经过清理的演示估算值**，仅作展示之用，非财务报告。
## 需求覆盖
来源于 **PITER AiOps — 期中项目说明** 和 **AI 辅助软件工程** 培训的期中需求。每一行都映射到实现证据和截图（如适用）。
| 需求 | 状态 | 实现 | 截图 |
| ----------- | ------ | -------------- | ---------- |
| Flask Web 应用 | 已满足 | [`app/routes.py`](app/routes.py), [`wsgi.py`](wsgi.py) — `/api/health`, `/api/chat`, `/api/triage`, `/api/history`, `/api/metrics/*` | — |
| RAG (文档问答) | 已满足 | Bedrock KB `RBTJM6NIG9` + [`knowledge_base/`](knowledge_base/); 后备 [`app/services/local_rag.py`](app/services/local_rag.py) | [`06_rag_citations.png`](screenshots/final/06_rag_citations.png) |
| Bedrock KB ↔ Agent | 已满足 | AWS: KB `RBTJM6NIG9` 在 Agent `HH4YGSLZUE` 上启用 (别名 `O2EM03R4R3`); [`infra/bedrock_agent_instructions.txt`](infra/bedrock_agent_instructions.txt) | [`11_knowledge_base.png`](screenshots/final/11_knowledge_base.png) |
| boto3 `invoke_agent` | 已满足 | [`app/bedrock_agent_client.py`](app/bedrock_agent_client.py) L137 — `bedrock-agent-runtime.invoke_agent`; 包装器 [`app/services/bedrock_agent_service.py`](app/services/bedrock_agent_service.py) | [`05_investigation_detail_triage.png`](screenshots/final/05_investigation_detail_triage.png) |
| 会话记忆 (后续跟进) | 已满足 | [`app/services/session_memory.py`](app/services/session_memory.py) — `append_followup()`; [`app/routes.py`](app/routes.py) 中的分流上下文 | [`08_memory_followup_context.png`](screenshots/final/08_memory_followup_context.png) |
| 聊天记录 | 已满足 | [`app/services/chat_history.py`](app/services/chat_history.py) — `append_turn()`; `GET/DELETE /api/history` | [`08_memory_followup_context.png`](screenshots/final/08_memory_followup_context.png) |
| Pandas / CSV / JSON | 已满足 | [`app/services/data_access.py`](app/services/data_access.py) — `pd.read_csv` + [`data/source/`](data/source/) 的加载器 | [`16_structured_analysis_panel.png`](screenshots/final/16_structured_analysis_panel.png) |
| 4 个指标 / MCP 函数 | 已满足 | [`app/enrichment_tools.py`](app/enrichment_tools.py); Lambdas `piter-recent-deployments`, `piter-service-context`, `piter-similar-incidents`, `piter-escalation`; MCP [`mcp/server.py`](mcp/server.py) | [`13b_settings_aws_status.png`](screenshots/final/13b_settings_aws_status.png) |
| 升级预览 (安全) | 已满足 | [`action_groups/piter-escalation/lambda_function.py`](action_groups/piter-escalation/lambda_function.py); [`app/services/escalation_service.py`](app/services/escalation_service.py) | [`09_escalation_preview.png`](screenshots/final/09_escalation_preview.png) |
| 演示关联链 | 已满足 | [`app/services/structured_analysis.py`](app/services/structured_analysis.py); wallet-service 部署 → 复制延迟 → 相似事件 | [`demo-wallet-v4-12-3-correlation-chain.png`](screenshots/final/demo-wallet-v4-12-3-correlation-chain.png) |
| Docker | 已满足 | [`Dockerfile`](Dockerfile), [`docker-compose.yml`](docker-compose.yml) | [`15_docker_running.png`](screenshots/final/15_docker_running.png) |
| EC2 部署 | 已满足 | 实例 `i-0c53b195878f0ea5f`; [`docs/ec2_deployment.md`](docs/ec2_deployment.md) | [`14b_live_demo_checks.png`](screenshots/final/14b_live_demo_checks.png) |
| GitHub + README | 已满足 | 本文件 — 安装、运行、架构、需求 | — |
| 演示文稿 | 已包含 | [`presentation/presentation_v1.pptx`](presentation/presentation_v1.pptx) | — |
完整就绪矩阵：[`docs/readiness_report.md`](docs/readiness_report.md) · 只读同步审计：[`docs/PHASE1_SYNC_AUDIT.md`](docs/PHASE1_SYNC_AUDIT.md)
## 快速开始
```
cd projects/piter-aiops
py -3.12 -m pip install -r requirements-dev.txt
py -3.12 -m pytest -q # 279 passing
cd frontend; npm ci; npm run build; cd ..
docker compose up --build -d
# http://localhost:8080/ → 启动 Alert Stream → 约 20s 时出现 P1 → 分析 P1 事件
```
**冒烟检查 (本地):**
```
Invoke-RestMethod http://localhost:8080/health
Invoke-RestMethod http://localhost:8080/api/tools/status
```
**启用 Bedrock (可选):**
```
copy .env.example .env
# 编辑 PITER_BEDROCK_* IDs — 参见 docs/environment.md
$env:PITER_DOCKER_USE_BEDROCK = "true"
docker compose up --build
```
**同步 Knowledge Base:**
```
aws s3 sync knowledge_base/ s3:///projects/piter-aiops/knowledge_base/
python scripts/sync_knowledge_base.py --ingest --wait
python scripts/kb_smoke_test.py
```
**预演示检查清单 (EC2):**
```
py -3.12 scripts/verify_credentials.py
py -3.12 scripts/agent_smoke_test.py
py -3.12 scripts/verify_live_demo.py --base-url http://ec2-3-235-22-143.compute-1.amazonaws.com:8080
```
日常开发流程：[`docs/LOCAL_DEV.md`](docs/LOCAL_DEV.md) · 演示者流程：[`docs/demo_script.md`](docs/demo_script.md)
## 5分钟演示流程
推荐的演示路径 — 每一步都对应 [截图](#screenshots) 中的一张图片：
| # | 步骤 | 展示内容 | 截图 |
|---|------|--------------|------------|
| 1 | 打开 **Dashboard** | KPI 卡片、告警队列、Agent Copilot 栏 | [`01`](screenshots/final/01_dashboard.png) |
| 2 | 点击 **Start Alert Stream** | 告警涌入；噪音抑制计数器上升 | [`03`](screenshots/final/03_alert_storm_running.png) |
| 3 | 等待约 20 秒 → **检测到 P1 候选** | 告警风暴在 P1 wallet-service 候选上暂停 | [`04`](screenshots/final/04_p1_detected.png) |
| 4 | 点击 **Analyze P1 Incident** | Bedrock Agent 分流：优先级、关联链、行动计划 | [`05`](screenshots/final/05_investigation_detail_triage.png) · [`16`](screenshots/final/16_structured_analysis_panel.png) |
| 5 | 查看 **Sources** | 为每一步提供依据的 KB 操作手册引用 | [`06`](screenshots/final/06_rag_citations.png) |
| 6 | 在聊天中提出 **后续跟进** | 会话记忆重用事件上下文 — 无需重新分流 | [`08`](screenshots/final/08_memory_followup_context.png) |
| 7 | 打开 **升级预览** | 待命接收人 + 检查；未经确认不会发送任何内容 | [`09`](screenshots/final/09_escalation_preview.png) |
包含时间和演讲要点完整演示脚本：[`docs/demo_script.md`](docs/demo_script.md)
## 系统架构
完整文档：[`docs/architecture.md`](docs/architecture.md) · *[在 Eraser 中编辑图表](https://app.eraser.io/workspace/k7BPJorv6ubjEktGOH3u)*
### 高层容器
```
flowchart LR
subgraph client [Operator]
SPA[React SPA]
end
subgraph app [PITER App — EC2 / Docker]
Flask[Flask API]
LocalRAG[Local TF-IDF fallback]
Tools[Enrichment tools]
end
subgraph aws [AWS Bedrock — us-east-1]
Agent[Bedrock Agent]
KB[Knowledge Base]
Lambdas[4 Action Group Lambdas]
S3[(S3 KB corpus)]
end
SPA -->|REST| Flask
Flask -->|invoke_agent| Agent
Flask -.->|offline| LocalRAG
Agent -->|retrieve + cite| KB
Agent -->|enrich| Lambdas
KB --- S3
Lambdas --> Tools
classDef clientStyle fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a8a
classDef appStyle fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#4c1d95
classDef awsStyle fill:#ffedd5,stroke:#ea580c,stroke-width:2px,color:#7c2d12
classDef dataStyle fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
class SPA clientStyle
class Flask,LocalRAG,Tools appStyle
class Agent,KB,Lambdas awsStyle
class S3 dataStyle
```
### 请求流程
```
sequenceDiagram
autonumber
participant Op as Operator
participant UI as React SPA
participant API as Flask API
participant BR as Bedrock Agent
participant KB as Knowledge Base
participant AG as Action Groups
participant Data as data/source
Op->>UI: Alert storm / chat / triage
UI->>API: POST /api/triage or /api/chat
API->>API: Validate input + guardrails
alt PITER_USE_BEDROCK=true
API->>BR: invoke_agent via boto3
BR->>KB: Retrieve runbooks and guides
BR->>AG: Call enrichment tools
AG->>Data: deploys, owners, incidents, policies
AG-->>BR: Structured JSON results
KB-->>BR: Citations
BR-->>API: Streamed answer + trace
else Fallback enabled
API->>API: Local TF-IDF over knowledge_base/
end
API->>API: Normalize PITER response
API-->>UI: priority, triage, sources, tool_results, memory
UI-->>Op: Enrichment panels + citations
```
### 数据拆分
```
flowchart TB
subgraph kb [Knowledge Base — procedural text]
RB[runbooks]
INC[incidents]
SVC[services]
PITER[piter guides]
end
subgraph structured [Structured data — Action Groups only]
DEP[deploys.csv]
OWN[service_owners.csv]
PAST[past_incidents.csv]
ESC[escalation_policies.json]
BI[business_impact.json]
end
Agent[Bedrock Agent] -->|RAG citations| kb
Agent -->|tool calls| structured
Flask[Flask enrichment_tools] --> structured
MCP[MCP server] --> structured
classDef kbStyle fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a8a
classDef structStyle fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
classDef hubStyle fill:#ffedd5,stroke:#ea580c,stroke-width:2px,color:#7c2d12
class RB,INC,SVC,PITER kbStyle
class DEP,OWN,PAST,ESC,BI structStyle
class Agent,Flask,MCP hubStyle
```
| 层级 | 位置 | 用途 |
| -------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- |
| 流程文本 | [`knowledge_base/`](knowledge_base/) | 修复步骤、服务上下文、历史记录 |
| 数值 / 表格运维数据 | [`data/source/`](data/source/) | 部署关联、负责人、MTTR、升级评分 |
| 索引 | [`docs/kb/structured_data_index.json`](docs/kb/structured_data_index.json) | 将工具映射到数据集 |
## 核心组件
### Bedrock Agent
系统提示词：[`infra/bedrock_agent_instructions.txt`](infra/bedrock_agent_instructions.txt) · 运行时镜像：[`app/bedrock_agent_client.py`](app/bedrock_agent_client.py)
**Agent 指令（节选）**
**工作流（始终按顺序执行）：** Priority → Investigation → Triage → Escalation → Resolution
**Grounding（基础依据）：** 每一个修复步骤都必须引用操作手册、策略或事件记录。绝不捏造负责人、部署版本、联系方式或过往事件。如果缺乏证据，请声明 *“知识库中未提供”*。
**安全性：** 拒绝 FLUSHALL、DROP/TRUNCATE、大规模 DELETE、未经批准的故障转移、禁用 WAF/MFA/auth 等操作。除非明确确认，否则升级预览不会发送消息。
**会话属性：** `service`, `environment`, `severity`, `symptom`, `alert_time`, `triage_complete` — 由 [`app/bedrock_agent_client.py`](app/bedrock_agent_client.py) `build_session_attributes()` 构建。
### Knowledge Base
| 主题 | 详情 |
| ----------------- | ---------------------------------------------------------------------------------- |
| 语料库 | [`knowledge_base/`](knowledge_base/) — 操作手册、事件、服务、piter 指南 |
| S3 前缀 | `s3://reem-amdocs-ai-artifacts-3331/projects/piter-aiops/knowledge_base/` |
| Knowledge base ID | `RBTJM6NIG9` |
| Agent ID | `HH4YGSLZUE` (别名 `O2EM03R4R3`) |
本地后备方案：当 `PITER_USE_BEDROCK=false` 或 Bedrock 失败且启用了后备方案时，Flask 会通过 [`app/services/local_rag.py`](app/services/local_rag.py) 使用 TF-IDF 进行回答。
### Action Groups 和 Lambda 函数
四个 Bedrock Action Groups 复用了与 Flask 富集逻辑和本地 MCP 服务器相同的 Python 逻辑 ([`app/enrichment_tools.py`](app/enrichment_tools.py))。
```
flowchart LR
Agent[Bedrock Agent] --> D & C & S & E
D[piter-recent-deployments] --> D1[(deploys.csv)]
C[piter-service-context] --> C1[(service_owners.csv)]
S[piter-similar-incidents] --> S1[(past_incidents.csv)]
E[piter-escalation] --> E1[(escalation_policies.json)]
E -.->|preview only| SNS[SNS / SES]
classDef agentStyle fill:#ffedd5,stroke:#ea580c,stroke-width:2px,color:#7c2d12
classDef lambdaStyle fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#4c1d95
classDef dataStyle fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
classDef notifyStyle fill:#ffe4e6,stroke:#e11d48,stroke-width:2px,color:#881337
class Agent agentStyle
class D,C,S,E lambdaStyle
class D1,C1,S1,E1 dataStyle
class SNS notifyStyle
```
| Action group | 数据源 | 用途 |
| -------------------------- | -------------------------------------------- | ---------------------------------------- |
| `piter-recent-deployments` | `deploys.csv` | 将告警时间与最近的部署关联 |
| `piter-service-context` | `service_owners.csv`, `business_impact.json` | 负责人、待班、业务影响 |
| `piter-similar-incidents` | `past_incidents.csv` | 历史匹配、根本原因、MTTR |
| `piter-escalation` | `escalation_policies.json` | 升级预览和优先级矩阵 |
部署：`.\scripts\aws_deploy_fix.ps1` — 在 Bedrock 控制台中附加 action groups **之前**创建 Lambda 函数。
### boto3 集成
| Client | 用于 | 调用 |
| ----------------------- | ------------------------------------------------------------ | --------------------------------------- |
| `bedrock-agent-runtime` | [`app/bedrock_agent_client.py`](app/bedrock_agent_client.py) | `invoke_agent`, `retrieve_and_generate` |
| `bedrock-agent` | [`app/upload_service.py`](app/upload_service.py) | S3 上传后的 KB 摄取任务 |
| `s3` | 上传服务、同步脚本 | `put_object`、语料库同步 |
**运行模式** ([`docs/environment.md`](docs/environment.md)):
| 模式 | 配置 | 行为 |
| -------------- | --------------------------------------------- | ----------------------------- |
| Bedrock Agent | `PITER_USE_BEDROCK=true`, `RAG_BACKEND=agent` | 完整的 agent + tools + KB |
| Direct KB RAG | `RAG_BACKEND=retrieve_and_generate` | 仅限 KB 的检索与生成 |
| 本地演示 | `PITER_USE_BEDROCK=false` | 对本地语料库执行 TF-IDF |
| Docker 默认 | `PITER_DOCKER_USE_BEDROCK=false` | 除非主动开启，否则为离线状态 |
### MCP server
[`mcp/server.py`](mcp/server.py) — 基于 stdio JSON-RPC 的 MCP，提供四个**只读**工具（与 Action Groups 的约定相同）：
| Tool | 用途 |
| ------------------------------- | ------------------------- |
| `get_recent_deployments` | 部署关联 |
| `get_service_context` | 服务负责人和影响 |
| `find_similar_incidents` | 历史匹配 + MTTR |
| `get_escalation_recommendation` | 升级预览 |
```
python mcp/server.py --selftest
```
### UI 技术栈
React 18 + Vite + TypeScript + Tailwind + shadcn/ui ([`frontend/`](frontend/))。主要界面：**Live Demo** (告警风暴 + 仪表盘)、**Analyzer**、**Agent Chat**、**Incident History**、**Post-Mortems**、**Agent Analytics**、**Knowledge Base**、**AWS / Bedrock status**、**System** 和 **Demo Guide** — 外加常驻的 **Agent Copilot** 聊天栏。
**API 端点（概览）**
| Method | Path | 用途 |
| ------ | ------------------------ | ---------------------------------- |
| GET | `/health`, `/api/health` | 存活检测；`?deep=1` 检查 Bedrock |
| POST | `/api/chat` | 带有 PITER 规范化的聊天 |
| POST | `/api/triage` | 主 SPA 分流 |
| POST | `/api/incidents/analyze` | 事件分析别名 |
| POST | `/api/follow-up` | 会话后续跟进 |
| GET | `/api/tools/status` | 四个富集工具的就绪状态 |
| GET | `/api/alert-stream` | 演示告警流 |
| POST | `/documents/upload` | S3 上传 + 可选的 KB 摄取 |
完整契约：[`docs/api_contract.md`](docs/api_contract.md)
## 用例
可接受的回答必须满足 [`evaluation/expected_answer_checklist.md`](evaluation/expected_answer_checklist.md)：包含结构化的 `piter` 对象、业务影响、下一步行动、来源、适用的工具结果、记忆，且不含原始堆栈跟踪。
**1. Knowledge Base 问答 — POST /api/chat**
**请求：**
```
{
"message": "What should I check when users cannot log in after the latest deployment?",
"session_id": "demo-session-1"
}
```
**响应包括：** `piter` (优先级、调查、分流、升级、解决)，`sources[]`，`confidence`，`mode: "bedrock"`。
**2. 告警分流 — POST /api/triage**
**请求：**
```
{
"alert_title": "High error rate on auth-service",
"service": "auth-service",
"environment": "production",
"severity": "high",
"description": "Many users cannot log in after the latest production deployment."
}
```
**响应增加：** 来自所有四个富集工具的 `tool_results`，来自 `business_impact.json` 的 `business_impact`，带有监管上下文的 P1–P4 优先级。
**3. 带会话记忆的后续跟进 — POST /api/follow-up**
**请求：**
```
{
"message": "Based on the previous incident, who should I escalate to?",
"session_id": "demo-session-1"
}
```
当 `triage_complete=true` 时重用会话属性。除非缺少上下文，否则不重复完整的分流。
**演示问题：** *在最近一次部署后用户无法登录，我应该检查什么？*
## 截图
精选自 [`screenshots/final/`](screenshots/final/) 的截图 — 符合期中演示需求 (RAG, 工具, 实时操作)。**2026 年 6 月 10 日更新：** 针对 EC2 实时环境通过 [`frontend/e2e/submission-screenshots.spec.ts`](frontend/e2e/submission-screenshots.spec.ts) 在 1920×1080 分辨率下使用 Playwright 截取 (`PITER_BASE_URL=http://ec2-3-235-22-143.compute-1.amazonaws.com:8080`)。
**分析告警** — Incident Analyzer 输入 + 结构化 PITER 输出
**结构化分析面板** — 关联链、业务影响、行动计划
**基于 KB 的回答** — 包含操作手册引用的来源部分
**聊天记忆** — 登录事件 + “接下来我该检查什么？”后续跟进
**升级流程** — 待命预览模态框，接收人已掩码，派遣前需确认
**演示关联链** — wallet-service 部署 → 复制延迟 → 相似事件
## 错误处理与安全
| 层级 | 机制 | 位置 |
| ------------------- | ---------------------------------------------- | ---------------------------------------------------- |
| 输入验证 | 空、超大、仅停用词的问题 | [`app/validators.py`](app/validators.py) |
| 操作员护栏 | 拦截 FLUSHALL, DROP, 绕过 WAF | [`app/guardrails.py`](app/guardrails.py) |
| boto3 转换 | Throttling, AccessDenied → 友好错误 | [`app/errors.py`](app/errors.py) |
| Bedrock 失败 UX | `ok=false`, `fallback_used`，拒绝静默成功 | [`docs/troubleshooting.md`](docs/troubleshooting.md) |
| 升级安全 | `PITER_NOTIFICATION_MODE=mock` 默认 | [`docs/environment.md`](docs/environment.md) |
当 Bedrock 失败且未启用后备方案时，UI 会明确显示失败 — 绝不伪造带有依据的回答。
**无 Token 升级 + 结构化分析（2026 年 6 月）：** 在线邮件派遣不再接受来自浏览器的确认 token — `POST /api/escalation/notify` 在服务端注入 `PITER_NOTIFICATION_CONFIRMATION_TOKEN`，而 UI 仅保留预览 + 显式确认 (`EscalationModal.tsx`)。分析告警的响应现在包含 `structured_analysis` 契约（关联链、证据、建议行动、升级建议），并在渲染前剔除 markdown；详见 `app/services/structured_analysis.py`、`PiterAnalysisPanel.tsx` 和 `screenshots/final/16_structured_analysis_panel.png`。EC2 上的实时 SES 证明：发送至 `reem.mor3@gmail.com` (沙盒环境) 的消息 ID `0100019eb06b31ee-7bfe623d-98fe-4d94-98e9-451931918d4a-000000`。
## 测试证据
| 测试套件 | 结果 | 范围 |
| ----------------------------- | -------------- | -------------------------------------------- |
| `py -3.12 -m pytest -q` | **279 passed** | 路由、agent、lambdas、MCP、护栏、RAG |
| `scripts/agent_smoke_test.py` | **6/6 PASS** | 实时 Bedrock Grounding |
| `scripts/_live_demo.py` | PASS on EC2 | 端到端公开演示 |
| `frontend npm run build` | Build OK | SPA 生产环境 bundle |
| `frontend npm run test:e2e` | **18+ passed** | EC2 演示路径 + 提交截图捕获 |
| `tests/test_structured_analysis.py` | PASS | wallet-service v4.12.3 关联链 |
| 实时 SES 升级 | **sent** | `0100019eb06b31ee-7bfe623d-98fe-4d94-98e9-451931918d4a-000000` |
证明捕获：[`14b_live_demo_checks.png`](screenshots/final/14b_live_demo_checks.png) (29/29 实时检查) · [`15_docker_running.png`](screenshots/final/15_docker_running.png) (容器在 :8080 上运行正常)
关键模块：[`tests/test_piter_lambdas.py`](tests/test_piter_lambdas.py), [`tests/test_mcp_server.py`](tests/test_mcp_server.py), [`tests/test_guardrails.py`](tests/test_guardrails.py), [`tests/test_incident_analysis.py`](tests/test_incident_analysis.py).
验证：[`screenshots/deployment_validation.md`](screenshots/deployment_validation.md) · 评分表：[`evaluation/manual_demo_scorecard.md`](evaluation/manual_demo_scorecard.md)
## 挑战与后续计划
### 已解决的挑战
| 挑战 | 解决方案 |
| ---------------------------------- | ----------------------------------------------------------------------------- |
| 遗留的 `iiq-`* 命名漂移 | 在 agent、Lambdas、部署脚本中重命名为 `piter-*` |
| Bedrock CLI 缺失 | Python 冒烟测试脚本 (`agent_smoke_test.py`) |
| 摄取期间 KB S3 IAM 403 错误 | 策略补丁 [`infra/kb_s3_policy_patch.json`](infra/kb_s3_policy_patch.json) |
| Bedrock 失败时静默“成功” | API 响应中明确的 `ok=false`, `fallback_used` |
| 字符串优先级比较 Bug | 事件分析中基于排名的 `_raise_priority()` |
详情：[`docs/troubleshooting.md`](docs/troubleshooting.md)
### 路线图
```
flowchart LR
subgraph now [Now]
A1[Bedrock Agent + KB]
A2[4 Action Groups]
A3[React ops console]
A4[EC2 demo deploy]
end
subgraph next [Next]
B1[Guardrails + CI alias]
B2[Playwright E2E]
B3[PagerDuty webhooks]
end
subgraph vision [Vision — PITER Ops 1.0]
C1[Closed-loop incident lifecycle]
C2[Multi-tenant KB]
C3[Observability correlation]
C4[Executive MTTR dashboard]
end
now ==> next ==> vision
classDef nowStyle fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
classDef nextStyle fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
classDef visionStyle fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#4c1d95
class A1,A2,A3,A4 nowStyle
class B1,B2,B3 nextStyle
class C1,C2,C3,C4 visionStyle
```
**近期计划：** Bedrock Guardrails, Playwright E2E, PagerDuty/ServiceNow webhooks (预览仍为默认)。
**愿景：** 是副驾驶而不是自动驾驶 — 每一步都有引用，破坏性操作需人工批准，闭环告警 → 分流 → 事后复盘 → KB 重新摄取。
## 文档索引
| 文档 | 描述 |
| ------------------------------------------------------------------------------------ | -------------------------------- |
| [`docs/architecture.md`](docs/architecture.md) | 组件和请求流程 |
| [`docs/api_contract.md`](docs/api_contract.md) | API 请求/响应结构 |
| [`docs/environment.md`](docs/environment.md) | 环境变量 |
| [`docs/aws_sync_guide.md`](docs/aws_sync_guide.md) | S3 同步和 KB 摄取 |
| [`docs/LOCAL_DEV.md`](docs/LOCAL_DEV.md) | 本地开发 + EC2 部署工作流 |
| [`docs/ec2_deployment.md`](docs/ec2_deployment.md) | EC2 部署清单 |
| [`docs/demo_script.md`](docs/demo_script.md) | 5–7 分钟演示者流程 |
| [`docs/readiness_report.md`](docs/readiness_report.md) | 课程就绪矩阵 |
| [`docs/troubleshooting.md`](docs/troubleshooting.md) | 常见故障与修复 |
| [`evaluation/expected_answer_checklist.md`](evaluation/expected_answer_checklist.md) | 可接受的 PITER 回答标准 |
## 课程背景
专为 **Amdocs AI 辅助软件工程** 课程打造 — 展示了 Flask, RAG, MCP 风格工具, Bedrock Agent, Docker 以及注重生产环境的事件响应 UX。
PITER AiOps · Priority → Investigation → Triage → Escalation → Resolution · Amazon Bedrock
完整截图索引（15 个文件）
| 文件 | 展示内容 | 更新日期 | | ---- | ----- | ------- | | [`01_dashboard.png`](screenshots/final/01_dashboard.png) | React NOC 仪表盘 (1920×1080) | 2026-06-10 | | [`02_investigations_table.png`](screenshots/final/02_investigations_table.png) | 事件历史 / 调查队列 | 2026-06-10 | | [`03_alert_storm_running.png`](screenshots/final/03_alert_storm_running.png) | 告警风暴运行中 | 2026-06-10 | | [`04_p1_detected.png`](screenshots/final/04_p1_detected.png) | 检测到 P1 候选 | 2026-06-10 | | [`05_investigation_detail_triage.png`](screenshots/final/05_investigation_detail_triage.png) | 分析告警 — 全页面分流 | 2026-06-10 | | [`06_rag_citations.png`](screenshots/final/06_rag_citations.png) | 分析面板中的 KB 引用 | 2026-06-10 | | [`08_memory_followup_context.png`](screenshots/final/08_memory_followup_context.png) | 会话记忆 + 后续跟进 | 2026-06-10 | | [`09_escalation_preview.png`](screenshots/final/09_escalation_preview.png) | 升级预览模态框（接收人已掩码） | 2026-06-10 | | [`10_post_mortem_summary.png`](screenshots/final/10_post_mortem_summary.png) | 事后复盘视图 | 2026-06-10 | | [`11_knowledge_base.png`](screenshots/final/11_knowledge_base.png) | Knowledge Base + 上传操作手册面板 | 2026-06-10 | | [`13b_settings_aws_status.png`](screenshots/final/13b_settings_aws_status.png) | AWS / Bedrock 状态 — agent 配置 + 4 个已注册的 action groups | 2026-06-10 | | [`14b_live_demo_checks.png`](screenshots/final/14b_live_demo_checks.png) | 在线演示验证 — 29/29 项检查通过 (实时 AWS + 本地后备) | 2026-06-08 | | [`15_docker_running.png`](screenshots/final/15_docker_running.png) | Docker 容器证明 | 2026-06-08 | | [`16_structured_analysis_panel.png`](screenshots/final/16_structured_analysis_panel.png) | 结构化分析 — 关联链 | 2026-06-10 | | [`demo-wallet-v4-12-3-correlation-chain.png`](screenshots/final/demo-wallet-v4-12-3-correlation-chain.png) | Wallet 部署 → 复制延迟链 | 2026-06-10 |标签：AIOps, AWS Bedrock, RAG, 安全规则引擎, 请求拦截, 运维自动化