seahorse-agent: Instructions file for Claude Code

Seahorse Agent 项目指南

项目概述

Seahorse Agent 是一个基于 Spring Boot 3.5.7 的 RAG（检索增强生成）智能体平台，采用六边形架构（端口-适配器模式）。

模块结构

seahorse-agent-kernel/              # 领域核心（L2）
seahorse-agent-adapter-web/         # Web 适配器（L3）
seahorse-agent-adapter-*/           # 各类适配器实现（L3）
seahorse-agent-spring-boot-starter/ # 自动配置（L3）
seahorse-agent-bootstrap/           # 启动入口
seahorse-agent-tests/               # 集成测试

自动配置架构

所有自动配置类注册在 AutoConfiguration.imports 中，分 13 层：

1. Layer 0 — Multi-tenancy（after DataSource）：租户隔离、RLS、TenantContext
2. Layer 1 — Adapters（20 个，after DataSource）：向量、缓存、存储、MQ、搜索等
3. Layer 2 — Outbox relay（after MQ + Ops）
4. Layer 3 — Native aggregator（after DataSource）
5. Layer 4 — Kernel auth（after Auth adapter）
6. Layer 5 — Kernel main（after Native aggregator）
7. Layer 6 — Kernel sub-configs（16 个，after Kernel main + 各自依赖的 adapter）
8. Layer 7 — Runtime guards（after kernel sub-configs）
9. Layer 8 — Alert notification（after runtime guards）：DingTalk 告警
10. Layer 9 — Registration + Security：用户注册、BCrypt、安全加固
11. Layer 10 — Billing：计费、订阅、配额强制
12. Layer 11 — RAG + Workflow：高级 RAG、工作流可视化
13. Layer 12 — KB + Marketplace + Admin：知识库增强、Agent 市场、管理后台
14. Layer 13 — AOP + Health：权限切面、试用拦截器、Redis 健康检查

关键规则： kernel 子配置必须在 @AutoConfigureAfter 中声明所有产生 @ConditionalOnBean 依赖的 adapter/repository 配置。

Controller 模式

所有 Controller 使用 ObjectProvider<T> 懒加载：

private final ObjectProvider<SomePort> somePortProvider;

public SomeController(ObjectProvider<SomePort> somePortProvider) {
    this.somePortProvider = somePortProvider;  // 不要在这里调用 getIfAvailable()
}

@GetMapping("/api")
public Map<String, Object> api() {
    return Map.of("code", "0", "data", somePortProvider.getIfAvailable().query());
}

部署

全量部署（所有中间件）

docker compose -f docker-compose.full.yml up -d --build

包含：PostgreSQL + Redis + Milvus + Pulsar + Elasticsearch + MinIO

本地构建 + Docker 打包（推荐，避免 Maven 代理问题）

./mvnw package -B -pl seahorse-agent-bootstrap -am -DskipTests -Dspotless.check.skip=true
docker build -t seahorse-agent-backend:latest -f - . <<'EOF'
FROM eclipse-temurin:21-jre
WORKDIR /app
COPY seahorse-agent-bootstrap/target/seahorse-agent-bootstrap-0.0.1-SNAPSHOT-exec.jar app.jar
EXPOSE 9090
ENTRYPOINT ["java", "-jar", "app.jar"]
EOF
docker compose -f docker-compose.full.yml up -d backend