feat(harness): freeze aci tool contracts

2026-07-21 18:01:18 +08:00
parent 58c39107c5
commit 4274f3350b
32 changed files with 977 additions and 1 deletions
@@ -0,0 +1,26 @@
+package com.superbiz.agent.harness.tool.contract;
+
+public final class AgentToolContracts {
+
+    public static final String LOOKUP_KNOWLEDGE = "lookup_knowledge";
+    public static final String QUERY_LOGS = "query_logs";
+    public static final String QUERY_MYSQL = "query_mysql";
+
+    public static final String LOOKUP_KNOWLEDGE_DESCRIPTION =
+            "查询内部知识库中的文档、接口说明、错误码和排障手册。"
+                    + "适用于稳定背景知识，不用于查询实时日志、指标或数据库状态。"
+                    + "输入 query：需要查询的问题或关键词。";
+
+    public static final String QUERY_LOGS_DESCRIPTION =
+            "查询指定逻辑日志主题在时间窗口内与目标相关的日志证据。"
+                    + "适用于应用错误、慢查询和系统事件，不用于查询指标或数据库表。"
+                    + "输入 topic、query、lookback_minutes。";
+
+    public static final String QUERY_MYSQL_DESCRIPTION =
+            "在授权的逻辑数据源上执行参数化只读查询，获取业务数据库事实。"
+                    + "只用于已知库表字段的 SELECT，不用于发现表结构或执行写操作。"
+                    + "输入 data_source、sql、params。";
+
+    private AgentToolContracts() {
+    }
+}
@@ -0,0 +1,10 @@
+package com.superbiz.agent.harness.tool.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public record LogEvent(
+        @JsonProperty("timestamp") String timestamp,
+        @JsonProperty("level") String level,
+        @JsonProperty("service") String service,
+        @JsonProperty("message") String message) {
+}
@@ -0,0 +1,12 @@
+package com.superbiz.agent.harness.tool.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public record LogPattern(
+        @JsonProperty("count") long count,
+        @JsonProperty("first_seen") String firstSeen,
+        @JsonProperty("last_seen") String lastSeen,
+        @JsonProperty("level") String level,
+        @JsonProperty("service") String service,
+        @JsonProperty("example") String example) {
+}
@@ -0,0 +1,10 @@
+package com.superbiz.agent.harness.tool.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public record LogQueryScope(
+        @JsonProperty("topic") LogTopic topic,
+        @JsonProperty("query") String query,
+        @JsonProperty("start_time") String startTime,
+        @JsonProperty("end_time") String endTime) {
+}
@@ -0,0 +1,5 @@
+package com.superbiz.agent.harness.tool.contract;
+
+public enum LogSourceKind {
+    MOCK
+}
@@ -0,0 +1,7 @@
+package com.superbiz.agent.harness.tool.contract;
+
+public enum LogTopic {
+    APPLICATION,
+    DATABASE_SLOW_QUERY,
+    SYSTEM_EVENTS
+}
@@ -0,0 +1,15 @@
+package com.superbiz.agent.harness.tool.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+public record MysqlToolRequest(
+        @JsonProperty("data_source") String dataSource,
+        @JsonProperty("sql") String sql,
+        @JsonProperty("params") List<Object> params) {
+
+    public MysqlToolRequest {
+        params = ToolContractCollections.immutable(params);
+    }
+}
@@ -0,0 +1,21 @@
+package com.superbiz.agent.harness.tool.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.superbiz.agent.harness.contract.EvidenceStatus;
+
+import java.util.List;
+import java.util.Map;
+
+public record MysqlToolResult(
+        @JsonProperty("evidence_status") EvidenceStatus evidenceStatus,
+        @JsonProperty("tool_call_id") String toolCallId,
+        @JsonProperty("columns") List<String> columns,
+        @JsonProperty("rows") List<Map<String, Object>> rows,
+        @JsonProperty("returned_count") int returnedCount,
+        @JsonProperty("truncated") boolean truncated) {
+
+    public MysqlToolResult {
+        columns = ToolContractCollections.immutable(columns);
+        rows = ToolContractCollections.immutableRows(rows);
+    }
+}
@@ -0,0 +1,9 @@
+package com.superbiz.agent.harness.tool.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public record QueryLogsRequest(
+        @JsonProperty("topic") LogTopic topic,
+        @JsonProperty("query") String query,
+        @JsonProperty("lookback_minutes") Integer lookbackMinutes) {
+}
@@ -0,0 +1,23 @@
+package com.superbiz.agent.harness.tool.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.superbiz.agent.harness.contract.EvidenceStatus;
+
+import java.util.List;
+
+public record QueryLogsToolResult(
+        @JsonProperty("evidence_status") EvidenceStatus evidenceStatus,
+        @JsonProperty("tool_call_id") String toolCallId,
+        @JsonProperty("source_kind") LogSourceKind sourceKind,
+        @JsonProperty("scope") LogQueryScope scope,
+        @JsonProperty("match_count") long matchCount,
+        @JsonProperty("returned_count") int returnedCount,
+        @JsonProperty("patterns") List<LogPattern> patterns,
+        @JsonProperty("events") List<LogEvent> events,
+        @JsonProperty("truncated") boolean truncated) {
+
+    public QueryLogsToolResult {
+        patterns = ToolContractCollections.immutable(patterns);
+        events = ToolContractCollections.immutable(events);
+    }
+}
@@ -0,0 +1,11 @@
+package com.superbiz.agent.harness.tool.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public record RagEvidence(
+        @JsonProperty("document_id") String documentId,
+        @JsonProperty("source") String source,
+        @JsonProperty("title") String title,
+        @JsonProperty("breadcrumb") String breadcrumb,
+        @JsonProperty("excerpt") String excerpt) {
+}
@@ -0,0 +1,7 @@
+package com.superbiz.agent.harness.tool.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public record RagToolRequest(
+        @JsonProperty("query") String query) {
+}
@@ -0,0 +1,19 @@
+package com.superbiz.agent.harness.tool.contract;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.superbiz.agent.harness.contract.EvidenceStatus;
+
+import java.util.List;
+
+public record RagToolResult(
+        @JsonProperty("evidence_status") EvidenceStatus evidenceStatus,
+        @JsonProperty("tool_call_id") String toolCallId,
+        @JsonProperty("query") String query,
+        @JsonProperty("evidence") List<RagEvidence> evidence,
+        @JsonProperty("returned_count") int returnedCount,
+        @JsonProperty("truncated") boolean truncated) {
+
+    public RagToolResult {
+        evidence = ToolContractCollections.immutable(evidence);
+    }
+}
@@ -0,0 +1,32 @@
+package com.superbiz.agent.harness.tool.contract;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+final class ToolContractCollections {
+
+    private ToolContractCollections() {
+    }
+
+    static <T> List<T> immutable(List<T> values) {
+        return values == null ? List.of() : List.copyOf(values);
+    }
+
+    static List<Map<String, Object>> immutableRows(List<Map<String, Object>> rows) {
+        if (rows == null) {
+            return List.of();
+        }
+        return rows.stream()
+                .map(ToolContractCollections::immutableRow)
+                .toList();
+    }
+
+    private static Map<String, Object> immutableRow(Map<String, Object> row) {
+        if (row == null) {
+            return Map.of();
+        }
+        return Collections.unmodifiableMap(new LinkedHashMap<>(row));
+    }
+}