liyupi/yu-ai-agent

1. Repository shape

- This repo is a small AI platform, not a single app: it contains a Spring Boot backend, a Vue frontend, and a separate MCP image-search service.

- The backend is the orchestration layer; the frontend is just the chat/UI shell; the MCP server is an external tool endpoint the backend/agents can invoke.

2. Backend runtime boundary

- yu-ai-agent is the main Java 21 / Spring Boot 3 service.

- Its top-level responsibilities are exposed through AiController and HealthController, with cross-cutting config in CorsConfig and application settings in application.yml / application-prod.yml.

- YuAiAgentApplication is the backend entrypoint.

3. Two primary product flows in the backend

- The codebase centers on two user-facing capabilities:

- LoveApp: an AI “恋爱大师” conversation assistant.

- YuManus: a ReAct-style autonomous agent that plans and executes tasks.

- These map to separate backend domains under app/ and agent/, but they share the same AI and tool infrastructure.

4. LoveApp architecture: chat + memory + knowledge

- app/LoveApp is the domain orchestration class for the romance assistant.

- Conversation state is handled by chatmemory/FileBasedChatMemory, so memory is persisted outside process memory rather than being purely transient.

- The assistant also has a RAG path under rag/, which loads and prepares the knowledge base from src/main/resources/document/*.md.

5. RAG subsystem boundaries

- LoveAppDocumentLoader, MyTokenTextSplitter, MyKeywordEnricher, and QueryRewriter implement the document ETL / query-enrichment steps.

- LoveAppVectorStoreConfig and PgVectorVectorStoreConfig define the vector-store integration; the project explicitly supports PgVector and cloud-based variants.

- LoveAppContextualQueryAugmenterFactory, LoveAppRagCloudAdvisorConfig, and LoveAppRagCustomAdvisorFactory show that retrieval is wired into the Spring AI advisor pipeline rather than being a separate service.

6. Agent subsystem

- agent/BaseAgent, ReActAgent, ToolCallAgent, and YuManus define a layered agent model.

- agent/model/AgentState is the state container for iterative reasoning/execution.

- This subsystem is the automation engine: it decides when to think, when to call tools, and when to stop.

7. Tooling subsystem

- tools/ contains the callable capabilities exposed to the AI model:

- file operations

- web search

- web scraping

- resource download

- terminal execution

- PDF generation

- termination / control

- ToolRegistration is the central place where those tools are made available to agents/models.

- Architecturally, this is the main “actuation” boundary: the LLM does not directly touch the environment; it invokes these tools through the backend.

8. MCP integration

- The backend has an MCP-oriented setup, and src/main/resources/mcp-servers.json indicates external MCP server configuration.

- The separate yu-image-search-mcp-server module is a standalone Spring Boot service exposing ImageSearchTool.

- It supports both stdio and sse modes via application-stdio.yml and application-sse.yml, so the image-search capability can be embedded or networked depending on deployment.

9. Model/provider abstraction

- The repo is deliberately provider-agnostic at the architecture level.

- The README and demo package show integration patterns for multiple model access modes: Spring AI, LangChain4j, HTTP calls, Ollama, and hosted APIs.

- demo/invoke/* exists as a reference layer for comparing these access methods rather than as core runtime logic.

10. Frontend boundary

- yu-ai-agent-frontend is a separate Vue 3 + Vite application.

- Key views are Home.vue, LoveMaster.vue, and SuperAgent.vue, with a shared ChatRoom.vue component.

- This frontend talks to the backend over HTTP; the presence of SSE in the README suggests some responses are streamed back asynchronously for chat/agent output.

11. End-to-end data flow

- User enters the frontend chat UI.

- Frontend calls backend controllers.

- Backend routes the request into either LoveApp or YuManus.

- LoveApp may consult file-based memory, run RAG retrieval over the knowledge documents/vector store, then call the LLM.

- YuManus may iterate through reasoning steps, invoke tools, and optionally call MCP services.

- Final text or streamed chunks are returned to the frontend.

12. Persistence and data assets

- The main persistent assets visible in the repo are:

- markdown knowledge documents under src/main/resources/document

- file-based chat memory on disk

- vector-store data in PgVector or cloud storage, depending on config

- There is no traditional relational business domain in this repo; persistence is AI-state and knowledge oriented.

13. Deployment packaging

- Each deployable has its own Dockerfile: backend, frontend, and MCP server.

- This suggests a containerized, multi-service deployment where the frontend is served separately from the backend AI service, and the MCP service can be scaled or replaced independently.

14. Testing and validation

- Tests are organized per subsystem: app, agent, RAG, tools, and the MCP server.

- That mirrors the architecture: each major boundary has its own verification layer, which is useful when drawing the system diagram because the repo is modular rather than monolithic.