91 lines
4.4 KiB
Markdown
91 lines
4.4 KiB
Markdown
## Context
|
|
|
|
The AIOps endpoint is currently useful as a standalone alert-analysis demo, but it is not aligned with the MVP trace story:
|
|
|
|
- `ChatController.aiOps()` accepts no request body.
|
|
- `AiOpsService.executeAiOpsAnalysis(...)` creates a random 8-character session id internally.
|
|
- The caller cannot reliably discover that id and query `GET /api/diagnosis/{sessionId}/trace`.
|
|
- `extractFinalReport(...)` returns the report text but does not persist it to `diagnosis_session.answer`.
|
|
|
|
The existing trace API already aggregates `diagnosis_session`, `agent_step`, and `tool_invocation`, so this change should reuse that storage rather than introduce new persistence.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
|
|
- Make `/api/ai_ops` usable as an alert-triggered diagnosis entry point.
|
|
- Preserve backward compatibility for callers that post with no request body.
|
|
- Return the resolved `sessionId` through SSE.
|
|
- Persist the final report into the existing diagnosis session.
|
|
- Keep the AIOps path observable through the existing trace API.
|
|
|
|
**Non-Goals:**
|
|
|
|
- Do not merge AIOps into `ChatService`.
|
|
- Do not add a new Verifier Agent to AIOps in this slice.
|
|
- Do not change `GET /api/diagnosis/{sessionId}/trace`.
|
|
- Do not add database migrations.
|
|
- Do not clean up sensitive configuration.
|
|
|
|
## Decisions
|
|
|
|
| Decision | Choice | Alternative Considered | Rationale |
|
|
|---|---|---|---|
|
|
| API compatibility | Keep `POST /api/ai_ops` SSE and make body optional | Add a new `/api/ai_ops/v2` endpoint | Optional body keeps existing demo callers working while enabling traceable alert input. |
|
|
| Session identity | Accept request `sessionId`, otherwise generate UUID | Continue internal-only 8-char id | Reviewers need the id to query trace and submit feedback. |
|
|
| Query persistence | Build a concise alert diagnosis query from request fields | Store only "AI Ops 告警分析" | Trace should show what alert was diagnosed. |
|
|
| Final answer persistence | Save extracted final report to `diagnosis_session.answer` | Only stream the report | Trace replay must include the final answer without relying on SSE logs. |
|
|
| Verifier scope | Defer AIOps Verifier integration | Add Chat Verifier now | The minimum interview value is traceability; Verifier unification can be a follow-up after this entry point is stable. |
|
|
| GitNexus | Skip by user decision | Block until MCP available | GitNexus tools are not exposed in this session, and the user explicitly requested skipping GitNexus. Local impact analysis and tests cover this slice. |
|
|
|
|
## Interface Impact
|
|
|
|
- Level: L3 API behavior extension.
|
|
- Endpoint: `POST /api/ai_ops`
|
|
- Compatibility: callers may still omit a body. New callers may send:
|
|
|
|
```json
|
|
{
|
|
"sessionId": "mvp-demo-aiops-payment-latency-001",
|
|
"alertName": "payment-service-latency-high",
|
|
"service": "payment-service",
|
|
"severity": "P1",
|
|
"description": "支付服务 P95 延迟升高并伴随超时错误",
|
|
"timeRange": "last_15m"
|
|
}
|
|
```
|
|
|
|
The SSE stream emits a first content message containing the resolved session id:
|
|
|
|
```text
|
|
sessionId: mvp-demo-aiops-payment-latency-001
|
|
```
|
|
|
|
## Data Flow
|
|
|
|
```text
|
|
POST /api/ai_ops
|
|
-> ChatController resolves request body and tools
|
|
-> AiOpsService.executeAiOpsAnalysis(chatModel, tools, request)
|
|
-> create diagnosis_session(agentFlow=AI_OPS, query=<alert summary>)
|
|
-> set SessionContextHolder(sessionId)
|
|
-> ai_ops_supervisor -> planner_agent -> executor_agent
|
|
-> persist agent_step and tool_invocation through existing hooks/tools
|
|
-> extract final report
|
|
-> persist diagnosis_session.answer/status/counts
|
|
-> caller queries GET /api/diagnosis/{sessionId}/trace
|
|
```
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [Risk] AIOps still lacks the Chat Verifier quality gate. -> Mitigation: document as follow-up and keep this slice focused on traceability.
|
|
- [Risk] SSE clients may not parse the new first message. -> Mitigation: message is additive content; existing clients still receive the final report.
|
|
- [Risk] Optional request body in Spring MVC can be easy to mishandle. -> Mitigation: use `@RequestBody(required = false)` and default request values in service code.
|
|
- [Risk] AIOps generated reports may still depend on real infrastructure. -> Mitigation: demo profile already enables mock logs/metrics where available; full offline mode remains out of scope.
|
|
|
|
## Migration Plan
|
|
|
|
- No database migration.
|
|
- Deploy with application restart.
|
|
- Rollback by reverting controller/service/DTO changes; existing persisted sessions remain valid.
|