AgentX: Command for Claude Code

RAG快照机制完善需求文档

业务背景

RAG系统架构概述

AgentX的RAG（知识库）系统采用分层发布机制：

1. 原始RAG数据集：用户创建和维护的工作数据，可随时修改
2. 版本快照：发布到市场的固化版本，内容不可变
3. 用户安装快照：用户从市场安装的个人副本，完全隔离

版本管理机制

• 用户创建RAG后自动生成0.0.1版本（REFERENCE类型），仅创建者可见
• 用户可发布RAG版本到市场（1.0.0、1.1.0等），生成SNAPSHOT类型的快照
• 其他用户只能看到和安装已发布的SNAPSHOT版本
• 0.0.1版本永远不会被其他用户安装

安装类型说明

REFERENCE类型（引用类型）：

• 仅用于用户自己创建的RAG的0.0.1版本
• 动态引用原始RAG数据，随原始数据变化而更新
• 用户修改原始RAG时，对应的0.0.1版本安装记录也会同步更新

SNAPSHOT类型（快照类型）：

• 用于所有发布版本和他人安装的版本
• 完全独立的数据副本，与原始RAG隔离
• 安装后内容固定，不会因原始RAG变化而改变

当前问题分析

1. 快照数据不完整

目前的快照机制只复制了基本信息（name、description、icon），但缺少：

• 文件数据的完整快照
• 文档单元的完整快照
• 相关配置和元数据的快照

2. 数据访问逻辑混乱

在查看已安装RAG信息时：

• REFERENCE类型应该显示原始RAG的实时信息
• SNAPSHOT类型应该显示快照数据
• 但当前实现中都从rag_versions表获取信息，违背了快照原则

3. 快照服务未完善

RagDataAccessService中的快照方法大多返回空列表，未实现真正的快照数据获取。

需要修改的代码模块

1. 数据模型扩展

UserRagDTO (/AgentX/src/main/java/org/xhy/application/rag/dto/UserRagDTO.java)

修改内容：

• 添加installType字段
• 添加isReferenceType()和isSnapshotType()判断方法

UserRagEntity 相关表结构

确认字段：

• install_type字段已存在
• 快照数据字段（name、description、icon等）已存在

2. 快照创建机制

RagPublishAppService (/AgentX/src/main/java/org/xhy/application/rag/RagPublishAppService.java)

需要完善的功能：

• 发布版本时创建完整快照
• 复制所有文件到rag_version_files表
• 复制所有文档单元到rag_version_documents表
• 复制相关配置和元数据

RagVersionDomainService (/AgentX/src/main/java/org/xhy/domain/rag/service/RagVersionDomainService.java)

需要添加的方法：

• createCompleteSnapshot() - 创建完整版本快照
• copyFilesToVersion() - 复制文件快照
• copyDocumentsToVersion() - 复制文档快照

3. 快照安装机制

UserRagDomainService (/AgentX/src/main/java/org/xhy/domain/rag/service/UserRagDomainService.java)

需要完善的方法：

• installRag() - 安装SNAPSHOT类型时创建用户专属快照
• 添加快照数据复制逻辑

新增服务类建议

UserRagSnapshotService：

• 专门处理用户级别的快照创建和管理
• createUserSnapshot() - 为用户创建专属快照
• copySnapshotToUser() - 从版本快照复制到用户快照

4. 数据访问优化

RagDataAccessService (/AgentX/src/main/java/org/xhy/domain/rag/service/RagDataAccessService.java)

需要完善的方法：

// 当前返回空列表，需要实现
private List<FileDetailEntity> getSnapshotFiles(String versionId)
private List<DocumentUnitEntity> getSnapshotDocuments(String versionId)
private List<DocumentUnitEntity> getSnapshotDocumentsByOriginalFile(String versionId, String originalFileId)