Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
222 lines (176 loc) · 6.66 KB

ARCHITECTURE.md

File metadata and controls

222 lines (176 loc) · 6.66 KB
Raw

Pi Java 项目架构文档

🎯 项目目标

核心目标: 为Spring项目和Spring AI大模型应用提供完整的AI代理框架接入方案

次要目标:

  • 与SpringAI集成，提供统一的LLM抽象层
  • 支持多LLM提供商（Anthropic, OpenAI, Google, Azure等）
  • 提供企业级稳定性、安全性和监控功能
  • 持续同步TypeScript版本的功能

🏗️ 项目架构

模块结构

pi-java/
├── pi-core/                    # 核心接口和模型 - ✅ 完成
│   ├── AgentSession.java       # 会话管理接口
│   ├── SessionNode.java        # 会话节点（ULID + 树结构）
│   ├── LLMProvider.java        # LLM提供者抽象
│   ├── ToolDefinition.java     # 工具定义接口
│   └── ToolCall.java           # 工具调用模型
│
├── pi-session/                 # 会话管理实现 - ✅ 完成
│   ├── SessionTree.java        # 会话树实现
│   ├── SessionManager.java     # 会话管理器
│   └── SessionPersistence.java # JSONL持久化
│
├── pi-llm/                     # LLM集成层 - ✅ 完成
│   ├── LLMProviderManager.java # 提供者管理器
│   ├── mock/MockLLMProvider.java # Mock实现
│   └── [未来: AnthropicProvider.java, OpenAIProvider.java]
│
├── pi-tools/                   # 工具系统 - ✅ 完成
│   ├── ToolManager.java        # 工具管理器
│   ├── ToolPermissionManager.java # 权限管理
│   ├── 内置工具:
│   │   ├── ReadFileTool.java   # 文件读取
│   │   ├── WriteFileTool.java  # 文件写入
│   │   ├── EditFileTool.java   # 文件编辑
│   │   ├── BashTool.java       # Bash命令
│   │   ├── FindFileTool.java   # 文件搜索
│   │   ├── GrepTool.java       # 内容搜索
│   │   └── LsTool.java         # 列出文件
│
├── pi-cli/                     # 命令行界面 - ✅ 完成
│   └── PiCliApplication.java   # CLI入口
│
├── pi-ui/                      # UI组件（待开发）
├── pi-starter/                 # Spring Boot Starter（待开发）
├── pi-test/                    # 测试框架（待开发）
└── pi-extensions/              # 扩展系统（待开发）

技术栈

  • Java 17 - 发布字节码基线；可直接运行在 Java 17 及后续 LTS（含 Java 21）
  • Spring Boot 3.4.0 - 企业级应用框架
  • Spring AI - 统一的AI集成（独立抽象层）
  • Maven - 构建和依赖管理
  • ULID - 时间有序的唯一ID
  • JSONL - 会话持久化格式
  • Picocli - 命令行界面
  • Lanterna - 终端UI（未来）

架构设计原则

  1. 模块化设计 - 每个模块职责单一，可独立使用
  2. 接口抽象 - 核心功能通过接口抽象，便于扩展
  3. 依赖注入 - 使用Spring DI，便于测试和集成
  4. 安全优先 - 工具执行带沙箱和权限控制
  5. 性能优化 - 虚拟线程、内存优化、快速启动
  6. 企业级 - 健康检查、监控、日志、错误处理

🔄 开发机制

反思机制

触发条件:

  1. 每完成一个主要功能模块后自动触发
  2. 每次compact之前强制触发
  3. 开发迭代超过3天时提醒触发

反思内容:

  1. 目标对齐检查 - 当前开发是否服务于核心目标
  2. 架构一致性 - 新增功能是否符合架构设计原则
  3. 集成便利性 - 是否便于Spring项目接入
  4. 测试覆盖度 - 端到端测试是否充分
  5. 性能影响 - 是否影响整体性能目标

记录位置: CLAUDE.md 文件的"开发反思"部分

开发流程

需求分析 → 架构设计 → 编码实现 → 单元测试 → 集成测试 → 端到端测试 → 反思总结

端到端测试策略

测试层次:

  1. 单元测试 - 单个组件功能
  2. 集成测试 - 模块间协作
  3. 端到端测试 - 完整业务流程

测试场景:

  1. Spring Boot集成测试 - 验证starter可用性
  2. LLM切换测试 - 验证多提供商支持
  3. 工具链测试 - 验证工具组合使用
  4. 会话持久化测试 - 验证数据完整性
  5. 性能测试 - 验证响应时间和资源使用

📊 项目进度

当前状态 (Day 3完成)

✅ 已完成:

  • 核心架构设计和模块划分
  • Maven多模块项目结构
  • Session管理（ULID + JSONL）
  • LLM提供者抽象和Mock实现
  • 完整工具系统（7个内置工具）
  • 权限管理系统
  • CLI界面
  • 安全沙箱机制
  • GitHub仓库配置

下一步计划

Week 2 (Day 4-7):

  • Spring Boot Starter开发
  • 终端UI（Lanterna）
  • REST API端点
  • WebSocket支持
  • 配置管理

Week 3 (Day 8-14):

  • 实际LLM提供商集成（Anthropic, OpenAI）
  • 插件架构
  • 企业级监控和日志
  • 性能优化

Week 4 (Day 15-21):

  • 完整的测试框架
  • 文档和示例
  • 性能基准测试
  • 生产环境部署指南

🎯 下一步操作

立即行动项

  1. 创建Spring Boot Starter - 让Spring项目一键集成
  2. 开发REST API - 提供HTTP接口支持
  3. 实现真实LLM集成 - 替换Mock实现
  4. 完善测试框架 - 端到端测试自动化

开发优先级

P1 - 核心集成:

  • Spring Boot Starter
  • REST API
  • 真实LLM提供商

P2 - 企业特性:

  • 监控和日志
  • 安全增强
  • 性能优化

P3 - 开发体验:

  • 文档完善
  • 示例项目
  • 社区支持

📝 开发汇报机制

每次开发阶段结束时的汇报内容

  1. 项目架构状态 - 当前架构是否需要调整
  2. 技术实现边界 - 本次实现的技术范围和限制
  3. 项目实施目标 - 是否按计划推进核心目标
  4. 进度更新 - 完成度和下一步计划
  5. 端到端测试验证 - 测试覆盖情况和结果

汇报格式

## 🚀 开发阶段汇报 - [功能名称]

### 📋 本次完成
- [具体功能1]
- [具体功能2]

### 🎯 目标对齐
✅ 服务于核心目标: [说明如何服务]
✅ 便于Spring集成: [说明集成便利性]

### 🏗️ 架构影响
- 新增模块: [模块名]
- 架构调整: [如有]
- 接口变更: [如有]

### 🧪 测试验证
- 单元测试: ✅ [数量]个测试用例
- 集成测试: ✅ [场景描述]
- 端到端测试: ✅ [完整流程描述]

### 📊 进度更新
- 整体进度: [百分比]%
- 下一步: [具体计划]

### 🤔 反思总结
- 目标对齐: [评估]
- 架构一致性: [评估]
- 集成便利性: [评估]
- 测试覆盖: [评估]
- 性能影响: [评估]

这个机制将帮助我们确保开发方向始终对准核心目标，同时保证代码质量和可维护性。