Skip to content

AGENTS.md

Latest commit

 

History

History
74 lines (55 loc) · 2.4 KB

AGENTS.md

File metadata and controls

74 lines (55 loc) · 2.4 KB

AGENTS.md - AI 协作者上下文

项目概况

这是一个 AI 学习平台，用于理解和实践主流 AI 概念。Java Spring Boot 后端 + React TypeScript 前端，模块化单体架构。

技术栈

  • 后端: Java 17, Spring Boot 3.4.5, Spring AI 1.0.0-M6, PostgreSQL, Maven
  • 前端: React 18, TypeScript, Vite, Ant Design 5
  • AI: Spring AI (OpenAI chat + embedding, Ollama)

项目结构

backend/src/main/java/com/aiplatform/
  chat/       - 对话 Session/Message, SSE 流式
  prompt/     - Prompt 模板 CRUD, {{variable}} 渲染
  model/      - 多模型路由, ChatClient 管理
  toolcall/   - 工具注册中心, 内建工具
  rag/        - 文档摄入, 向量检索, Embedding
  mcp/        - MCP stdio 客户端, JSON-RPC
  skill/      - .md 技能文件加载, 热更新
  memory/     - Token 窗口, 长期记忆
  agent/      - ReAct 循环, 多步工具编排
  common/     - 共享 DTO, 异常, 分页

开发命令

# 后端
cd backend && mvnw spring-boot:run       # 启动 (端口 8080)

# 前端
cd frontend && npm run dev                # 启动 (端口 5173)

# 类型检查
cd frontend && npx tsc --noEmit

# MCP 示例
python mcp-examples/filesystem-server.py  # MCP 文件系统服务器

API 约定

  • 所有 API 前缀 /api/
  • 统一响应格式: { code: int, message: string, data: T }
  • SSE 端点返回 text/event-stream，事件名: token / done
  • 分页参数: page (0-indexed), size (default 20)
  • 异常统一由 GlobalExceptionHandler 处理

关键技术决策

  1. Spring AI ChatClient 而非原生 HTTP 调用 → 统一 LLM 抽象
  2. 模块化单体 而非微服务 → 学习项目，降低复杂度
  3. 模块间接口通信 → ToolRegistry 作为工具注册中心
  4. SSE (非 WebSocket) → 简单够用，单向推送
  5. 技能用 .md 文件 → 可读性好，热更新简单

Agent 循环实现

  • ReAct: LLM 输出 Thought → tool_call → 执行 → Observation → 继续/完成
  • 最大步数 10 防止无限循环
  • 工具结果以 AssistantMessage 注入回 messages 列表
  • 步数达到上限时返回部分结果 + 警告

文件生成注意

  • 所有 Java 文件不加注释（约定）
  • 前端使用 TypeScript 严格模式
  • API 客户端在 frontend/src/services/api.ts
  • 前端页面放在 frontend/src/pages/
  • 后端模块各包含: entity/ repository/ service/ controller/ dto/