SuperBizAgent-java/openspec/specs/aci-evidence-tool-contracts/spec.md

aci-evidence-tool-contracts Specification

Purpose

定义 Diagnosis Harness 中 RAG、日志和只读 MySQL evidence Tool 的最小 Agent-facing ACI 契约，包括状态语义、框架 Tool Call 引用、逻辑输入、有界输出、Mock 来源标识和实现中立的 Tool 描述。

Requirements

Requirement: Evidence result semantics SHALL be distinct from invocation lifecycle

The system SHALL expose EVIDENCE_FOUND, NO_EVIDENCE, and ERROR as Agent-facing evidence result semantics while retaining PROJECTING, READY, and ERROR only for canonical invocation lifecycle. NO_EVIDENCE SHALL mean that the executed query found no evidence within its recorded scope and SHALL NOT mean tool failure or system health.

Scenario: Successful empty query result

• WHEN an evidence Tool completes successfully with no matching evidence in its recorded scope
• THEN its Agent-facing result uses evidence_status=NO_EVIDENCE and the invocation lifecycle may independently reach status=READY

Scenario: Tool execution fails

• WHEN schema, authorization, execution, or projection fails
• THEN the Agent-facing result uses evidence_status=ERROR and SHALL NOT report NO_EVIDENCE

Requirement: Referencable Tool results SHALL use the framework Tool Call ID

Each EVIDENCE_FOUND or NO_EVIDENCE result SHALL contain the non-blank tool_call_id supplied by the framework Tool Call request. Agent inputs SHALL NOT contain tool_call_id, and contract code SHALL NOT generate, replace, or derive a second call ID.

Scenario: Framework requests a Tool call

• WHEN Spring AI Alibaba exposes an AssistantMessage.ToolCall.id through ToolCallRequest.getToolCallId()
• THEN the bounded Agent result carries exactly that ID as tool_call_id

Scenario: Framework ID is invalid

• WHEN the Tool request has a missing or invalid framework Tool Call ID
• THEN the call returns an ERROR result without inventing a referencable ID

Requirement: RAG Tool contract SHALL expose only bounded document evidence

The RAG Request SHALL contain only query. The RAG Result SHALL contain evidence_status, tool_call_id, query, bounded evidence, returned_count, and truncated; each evidence item SHALL contain only document_id, source, title, breadcrumb, and an exact excerpt.

Scenario: RAG evidence is serialized

• WHEN a RAG result contains a matching document excerpt
• THEN its JSON matches the frozen snake_case fields and excludes ContextPack, RetrievalTrace, RerankTrace, raw scores, fallback attempts, metadata, and full document bodies

Scenario: RAG query has no evidence

• WHEN RAG executes successfully without a usable document excerpt
• THEN it returns NO_EVIDENCE, preserves the original query and framework Tool Call ID, and returns an empty evidence list

Requirement: Log Tool contract SHALL use logical scope and retain Mock provenance

The log Request SHALL contain logical topic, query, and optional lookback_minutes only. The log Result SHALL contain evidence_status, tool_call_id, source_kind, complete query scope, match_count, returned_count, bounded patterns, bounded timeline events, and truncated. The initial logical topics SHALL be APPLICATION, DATABASE_SLOW_QUERY, and SYSTEM_EVENTS, and the initial source kind SHALL be MOCK.

Scenario: Mock log evidence is serialized

• WHEN the existing Mock source returns matching application events
• THEN the Agent result records source_kind=MOCK, the logical query scope, aggregate patterns, bounded timeline events, and distinct match and returned counts

Scenario: Agent creates a log request

• WHEN the Agent requests log evidence
• THEN it selects a logical topic and lookback window without supplying region, physical TopicId, credentials, or result limit and without calling a Topic discovery Tool first

Requirement: MySQL Tool contract SHALL expose a logical read-only query interface

The MySQL Request SHALL contain only logical data_source, parameterized sql, and params. The MySQL Result SHALL contain evidence_status, tool_call_id, columns, bounded structured rows, returned_count, and truncated; it SHALL NOT expose connection details, credentials, internal stack traces, or resource-limit controls.

Scenario: MySQL evidence is serialized

• WHEN a future read-only adapter returns authorized rows
• THEN the Agent result preserves column order, structured row values, the framework Tool Call ID, returned count, and truncation state using the frozen JSON fields

Scenario: Agent creates a MySQL request

• WHEN the Agent requests business database evidence
• THEN it supplies a logical data source, SQL placeholders, and parameter values without supplying JDBC connection information or security policy

Requirement: Tool descriptions SHALL be concise and implementation-neutral

The system SHALL define stable snake_case names and concise descriptions for lookup_knowledge, query_logs, and query_mysql. Each description SHALL state when to call the Tool, its minimal input, and what it cannot query, and SHALL NOT describe retrieval internals, infrastructure coordinates, credentials, audit storage, retries, result limits, or ranking implementation.

Scenario: Agent receives Tool definitions

• WHEN a future Agent adapter registers the frozen Tool definitions
• THEN the definitions describe available actions and boundaries without exposing Milvus, L0/L1, rerank, CLS region/TopicId, Redis, JDBC credentials, topK, limit, or Trace internals

Requirement: Contract freeze SHALL NOT cut over the current runtime

This change SHALL add contract types, descriptions, and tests without changing the current LookupKnowledgeTool, QueryLogsTools, ChatService, AiOpsService, Controller, Tool registration, or Agent-visible runtime results.

Scenario: Stage 1 tests pass

• WHEN all ACI contract tests pass
• THEN the current public Chat and AIOps paths still execute the old Tool implementations until their later projector and cutover changes