附录 F：核心数据结构汇总

本附录汇总全书 Java / Spring Boot Agent Framework 中反复出现的核心数据结构。它不是完整实现，而是后续示例工程的设计输入。

1. AgentTask

public record AgentTask(
    String taskId,
    String type,
    String userId,
    String repositoryId,
    String goal,
    Map<String, Object> input,
    RuntimePolicy policy,
    Instant createdAt
) {}

2. AgentSession

public record AgentSession(
    String sessionId,
    String taskId,
    AgentSessionState state,
    Instant startedAt,
    Instant updatedAt
) {}

Session 是持久化事件流，不等于 Context Window。

3. AgentEvent

public record AgentEvent(
    String eventId,
    String sessionId,
    String type,
    Map<String, Object> payload,
    Instant occurredAt
) {}

常见事件：

TASK_CREATED
SESSION_STARTED
CONTEXT_BUILT
SKILL_LOADED
TOOL_CALLED
TOOL_RESULT_RECEIVED
CHECKPOINT_CREATED
REPORT_GENERATED
VERIFICATION_PASSED
TASK_COMPLETED

4. ContextChunk

public record ContextChunk(
    String id,
    ContextType type,
    String source,
    String content,
    int tokenEstimate,
    double relevanceScore,
    Map<String, Object> metadata
) {}

5. ContextProvider

public interface ContextProvider {
    List<ContextChunk> provide(ContextRequest request);
}

6. ContextSelector

public interface ContextSelector {
    SelectedContext select(List<ContextChunk> candidates, ContextBudget budget);
}

7. ToolDefinition

public record ToolDefinition(
    String name,
    String description,
    JsonSchema inputSchema,
    JsonSchema outputSchema,
    RiskLevel riskLevel,
    boolean idempotent,
    boolean requiresApproval,
    Set<String> permissions
) {}

8. ToolResult

public record ToolResult(
    String toolCallId,
    String toolName,
    boolean success,
    Object data,
    ToolError error,
    String sourceRef,
    int tokenEstimate
) {}

9. SkillMetadata

public record SkillMetadata(
    String name,
    String description,
    String version,
    List<String> requiredTools,
    RiskLevel riskLevel
) {}

10. MemoryRecord

public record MemoryRecord(
    String memoryId,
    MemoryType type,
    MemoryScope scope,
    String scopeId,
    String content,
    String source,
    double confidence,
    Instant createdAt,
    Instant expiresAt
) {}

11. Checkpoint

public record Checkpoint(
    String checkpointId,
    String sessionId,
    String phase,
    List<String> completedSteps,
    List<String> pendingSteps,
    List<String> verifiedFacts,
    List<String> openQuestions,
    String nextAction,
    Instant createdAt
) {}

12. Finding

public record Finding(
    String findingId,
    String agentName,
    String statement,
    List<String> evidence,
    double confidence,
    String sourceRef
) {}

13. RuntimePolicy

public record RuntimePolicy(
    int maxIterations,
    Duration timeout,
    BigDecimal maxCost,
    boolean readOnly,
    Set<String> allowedTools,
    Set<String> deniedTools,
    boolean requireApprovalForWrite
) {}

14. CI 失败分析输入输出

输入

{
  "buildId": "4312",
  "repositoryId": "order-service",
  "pullRequestId": "882"
}

输出

{
  "status": "ANALYZED",
  "rootCause": "PR #882 added OrderStatus.PENDING_REVIEW but did not update OrderStateMachine.allowedTransitions.",
  "evidence": [
    "Failed test: OrderServiceTest.shouldApprovePendingReviewOrder",
    "Exception: transition PENDING_REVIEW -> APPROVED is not allowed",
    "Git diff shows OrderStatus added PENDING_REVIEW"
  ],
  "suspectedFiles": [
    "src/main/java/com/company/order/domain/OrderStatus.java",
    "src/main/java/com/company/order/state/OrderStateMachine.java",
    "src/test/java/com/company/order/service/OrderServiceTest.java"
  ],
  "suggestedFix": "Update OrderStateMachine.allowedTransitions to include PENDING_REVIEW -> APPROVED and run ./mvnw -Dtest=OrderServiceTest test.",
  "confidence": 0.88,
  "limitations": [
    "Agent did not modify files in read-only mode."
  ]
}