feat: add traceable scoped AIOps diagnosis

2026-07-04 22:57:28 +08:00
parent 246c99b954
commit 23ee05c7c3
32 changed files with 1179 additions and 25 deletions
@@ -0,0 +1,28 @@
+# aiops-alert-scope-control Specification
+
+## Purpose
+TBD - created by archiving change aiops-alert-scope-control. Update Purpose after archive.
+## Requirements
+### Requirement: AIOps payload mode focuses on supplied alert
+When an AIOps request includes alert payload fields, the system SHALL instruct the agent to focus the final alert analysis report on the supplied alert.
+
+#### Scenario: Request includes alertName and service
+- **WHEN** a caller posts to `/api/ai_ops` with `alertName` and `service`
+- **THEN** the AIOps task prompt identifies payload mode
+- **AND** the prompt instructs the agent not to create full root-cause sections for unrelated active alerts
+
+### Requirement: AIOps auto-discovery mode queries active alerts first
+When an AIOps request omits alert payload fields, the system SHALL instruct the agent to first discover active Prometheus alerts.
+
+#### Scenario: Request body is omitted
+- **WHEN** a caller posts to `/api/ai_ops` without alert fields
+- **THEN** the AIOps task prompt identifies auto-discovery mode
+- **AND** the prompt instructs the agent to call `queryPrometheusAlerts` first
+
+### Requirement: Payload mode may use active alerts as supporting context
+Payload mode SHALL allow active-alert lookup as supporting evidence, but SHALL keep unrelated alerts out of the main report sections.
+
+#### Scenario: Prometheus returns multiple active alerts
+- **WHEN** payload mode is active and `queryPrometheusAlerts` returns unrelated active alerts
+- **THEN** the prompt permits mentioning those alerts only as related risk or context
+- **AND** the final report target remains the supplied alert
@@ -0,0 +1,44 @@
+# aiops-traceable-diagnosis-entry Specification
+
+## Purpose
+TBD - created by archiving change aiops-traceable-diagnosis-entry. Update Purpose after archive.
+## Requirements
+### Requirement: AIOps endpoint accepts optional alert input
+The system SHALL allow `POST /api/ai_ops` to accept an optional JSON request body describing the alert diagnosis request.
+
+#### Scenario: Caller supplies alert input
+- **WHEN** a caller posts to `/api/ai_ops` with alert fields such as session id, alert name, service, severity, description, and time range
+- **THEN** the AIOps analysis uses those fields to build the diagnosis task prompt and persisted session query
+
+#### Scenario: Caller omits alert input
+- **WHEN** a caller posts to `/api/ai_ops` without a body
+- **THEN** the system still starts the default AIOps alert-analysis flow
+
+### Requirement: AIOps session id is traceable
+The system SHALL resolve a stable AIOps session id from the request when provided, otherwise generate one, and SHALL expose that session id to the SSE caller.
+
+#### Scenario: Request includes session id
+- **WHEN** a caller posts to `/api/ai_ops` with `sessionId`
+- **THEN** the created `diagnosis_session.session_id` equals that value
+- **AND** the SSE stream includes the same session id
+
+#### Scenario: Request omits session id
+- **WHEN** a caller posts to `/api/ai_ops` without `sessionId`
+- **THEN** the system generates a session id
+- **AND** the SSE stream includes the generated session id
+
+### Requirement: AIOps report is persisted for trace replay
+The system SHALL persist the final AIOps report into the existing `diagnosis_session.answer` field when a report is available.
+
+#### Scenario: AIOps report is generated
+- **WHEN** the AIOps planner/executor flow returns a final report
+- **THEN** the corresponding diagnosis session is marked successful
+- **AND** `diagnosis_session.answer` stores the final report
+- **AND** `GET /api/diagnosis/{sessionId}/trace` can include that answer
+
+### Requirement: AIOps trace uses existing evidence tables
+The system SHALL continue using existing `agent_step` and `tool_invocation` persistence for AIOps trace evidence.
+
+#### Scenario: AIOps uses evidence tools
+- **WHEN** the AIOps flow calls available evidence tools
+- **THEN** existing hooks and recorders persist agent steps and tool invocations under the resolved AIOps session id