PromptX/docs/issues/resource-architecture-improvement.md

# PromptX 资源管理架构改进方案

## 背景

**Issue #31** 的修复虽然解决了 Windows 路径解析兼容性问题，但暴露了 PromptX 资源管理架构的深层次问题。本文档提出了一个基于**注册表缓存 + @reference protocol 体系**的全新架构改进方案。

## 当前架构问题分析

### 1. 架构复杂度过高

当前系统存在多个重叠的组件和注册表：

```
ResourceRegistry.js (248行) + resource.registry.json (167行) + 内存协议注册表
                    ↓
            ResourceManager.js (482行)
                    ↓
        SimplifiedRoleDiscovery.js (284行)
                    ↓
            PackageProtocol.js (581行)
```

**问题**：
- 职责重叠，维护成本高
- 数据流路径不清晰
- 调试困难

### 2. 协议系统不一致

**当前协议处理问题**：
```javascript
// 问题1：协议前缀不统一
"@package://resource/core/role.md"      // 正确
"@packages://promptx/resource/core/"    // 错误变换

// 问题2：循环依赖
ResourceManager → PackageProtocol → ResourceManager

// 问题3：硬编码协议处理
if (filePath.startsWith('@package://')) {
  // 每次都创建新实例，无复用
  const PackageProtocol = require('../../resource/protocols/PackageProtocol')
  const packageProtocol = new PackageProtocol()
}
```

### 3. 缓存机制缺失

**性能问题**：
- 每次资源解析都触发文件系统操作
- 资源发现结果未缓存，重复扫描
- 协议实例未复用

**具体数据**：
- 首次角色激活：~200ms（包含文件系统扫描）
- 后续角色激活：~150ms（仍需重复解析）
- 期望性能：<10ms（缓存命中）

### 4. 发现与注册强耦合

```javascript
// 当前实现问题
class SimplifiedRoleDiscovery {
  async discoverRoles() {
    // 直接操作文件系统
    const files = await this.scanFileSystem()
    // 直接写入注册表
    this.registry.register(roles)
  }
}
```

**问题**：
- 无法独立测试发现逻辑
- 扩展新资源类型需要修改多处代码
- 资源变更无法实时响应

## 新架构设计（奥卡姆剃刀原则）

### 核心问题聚焦

**Issue #31 暴露的根本问题**：
1. **注册表与协议不一致**：注册表存储直接路径，绕过了 @reference 体系
2. **发现与注册耦合**：SimplifiedRoleDiscovery 直接操作注册表
3. **协议解析分散**：每个地方都在解析协议，没有统一入口

### 简化架构设计

**核心原则**：
```
用户请求 → ResourceRegistry(查找@reference) → ProtocolResolver(统一解析) → 文件系统
```

**3个核心组件，解决核心问题**：
- `ResourceRegistry`：纯索引，存储 id → @reference 映射
- `ProtocolResolver`：统一协议解析入口
- `ResourceDiscovery`：独立发现服务，与注册表解耦

**完全兼容现有格式**：
- ✅ 100% 兼容现有 `resource.registry.json`
- ✅ 现有代码无需修改
- ✅ 保持 @reference 体系一致性

### 详细组件设计

#### 1. 简化的资源注册表 (ResourceRegistry)

**职责**：纯索引，存储 id → @reference 映射，兼容现有格式

```javascript
class ResourceRegistry {
  constructor() {
    this.index = new Map() // 纯粹的 id → @reference 映射
  }

  // 加载 resource.registry.json（兼容现有格式）
  loadFromFile(registryPath = 'src/resource.registry.json') {
    const data = JSON.parse(fs.readFileSync(registryPath, 'utf8'))
    
    for (const [protocol, info] of Object.entries(data.protocols)) {
      if (info.registry) {
        for (const [id, resourceInfo] of Object.entries(info.registry)) {
          const reference = typeof resourceInfo === 'string' 
            ? resourceInfo 
            : resourceInfo.file
          
          this.index.set(`${protocol}:${id}`, reference)
        }
      }
    }
  }

  // 注册新发现的资源
  register(id, reference) {
    this.index.set(id, reference)
  }

  // 解析资源ID到@reference
  resolve(resourceId) {
    // 1. 直接查找
    if (this.index.has(resourceId)) {
      return this.index.get(resourceId)
    }

    // 2. 兼容性：尝试添加协议前缀
    for (const protocol of ['role', 'thought', 'execution', 'memory']) {
      const fullId = `${protocol}:${resourceId}`
      if (this.index.has(fullId)) {
        return this.index.get(fullId)
      }
    }

    throw new Error(`Resource '${resourceId}' not found`)
  }
}
```

#### 2. 解耦的资源发现服务 (ResourceDiscovery)

**职责**：纯粹的发现功能，不操作注册表

```javascript
class ResourceDiscovery {
  // 纯粹的发现功能，不操作注册表
  async discoverResources(scanPaths) {
    const discovered = []
    
    for (const basePath of scanPaths) {
      // 发现角色文件
      const roleFiles = await glob(`${basePath}/**/*.role.md`)
      for (const file of roleFiles) {
        discovered.push({
          id: `role:${this.extractId(file, '.role.md')}`,
          reference: this.generateReference(file)
        })
      }

      // 发现执行模式文件
      const execFiles = await glob(`${basePath}/**/execution/*.execution.md`)
      for (const file of execFiles) {
        discovered.push({
          id: `execution:${this.extractId(file, '.execution.md')}`,
          reference: this.generateReference(file)
        })
      }

      // 发现思维模式文件
      const thoughtFiles = await glob(`${basePath}/**/thought/*.thought.md`)
      for (const file of thoughtFiles) {
        discovered.push({
          id: `thought:${this.extractId(file, '.thought.md')}`,
          reference: this.generateReference(file)
        })
      }
    }

    return discovered
  }

  extractId(filePath, suffix) {
    return path.basename(filePath, suffix)
  }

  generateReference(filePath) {
    // 简单的规则：根据路径判断协议
    if (filePath.includes('node_modules/promptx')) {
      const relativePath = path.relative(this.findPackageRoot(), filePath)
      return `@package://${relativePath}`
    } else if (filePath.includes('.promptx')) {
      const relativePath = path.relative(process.cwd(), filePath)
      return `@project://${relativePath}`
    } else {
      return `@file://${filePath}`
    }
  }
}
```

#### 3. 统一协议解析器 (ProtocolResolver)

**职责**：统一协议解析入口，移除分散的解析逻辑

```javascript
class ProtocolResolver {
  constructor() {
    this.packageRoot = null // 延迟加载
  }

  // 统一解析 @reference 到文件路径
  async resolve(reference) {
    const [protocol, path] = this.parseReference(reference)
    
    switch (protocol) {
      case 'package':
        return this.resolvePackage(path)
      case 'project':
        return this.resolveProject(path)
      case 'file':
        return this.resolveFile(path)
      default:
        throw new Error(`Unsupported protocol: ${protocol}`)
    }
  }

  parseReference(reference) {
    const match = reference.match(/^@(\w+):\/\/(.+)$/)
    if (!match) {
      throw new Error(`Invalid reference format: ${reference}`)
    }
    return [match[1], match[2]]
  }

  async resolvePackage(relativePath) {
    if (!this.packageRoot) {
      this.packageRoot = await this.findPackageRoot()
    }
    return path.resolve(this.packageRoot, relativePath)
  }

  resolveProject(relativePath) {
    return path.resolve(process.cwd(), relativePath)
  }

  resolveFile(filePath) {
    return path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath)
  }

  // 简化的包根目录查找
  async findPackageRoot() {
    let dir = __dirname
    while (dir !== path.parse(dir).root) {
      const packageJson = path.join(dir, 'package.json')
      if (fs.existsSync(packageJson)) {
        const pkg = JSON.parse(fs.readFileSync(packageJson, 'utf8'))
        if (pkg.name === 'promptx') {
          return dir
        }
      }
      dir = path.dirname(dir)
    }
    throw new Error('PromptX package root not found')
  }
}
```

#### 4. 简化的资源管理器 (ResourceManager)

**职责**：协调三个核心组件，提供统一接口

```javascript
class ResourceManager {
  constructor() {
    this.registry = new ResourceRegistry()
    this.resolver = new ProtocolResolver()
    this.discovery = new ResourceDiscovery()
  }

  // 初始化：加载静态注册表 + 发现动态资源
  async initialize() {
    // 1. 加载静态注册表
    this.registry.loadFromFile('src/resource.registry.json')

    // 2. 发现动态资源
    const discovered = await this.discovery.discoverResources([
      'resource/', // 包内资源
      '.promptx/', // 项目资源
      process.env.PROMPTX_USER_DIR // 用户资源
    ].filter(Boolean))

    // 3. 注册发现的资源（不覆盖静态注册表）
    for (const resource of discovered) {
      if (!this.registry.index.has(resource.id)) {
        this.registry.register(resource.id, resource.reference)
      }
    }
  }

  // 核心方法：加载资源
  async loadResource(resourceId) {
    // 1. 从注册表获取 @reference
    const reference = this.registry.resolve(resourceId)
    
    // 2. 通过协议解析器解析到文件路径
    const filePath = await this.resolver.resolve(reference)
    
    // 3. 加载文件内容
    return {
      content: fs.readFileSync(filePath, 'utf8'),
      path: filePath,
      reference
    }
  }
}
```

## 解决的核心问题

### 1. 统一 @reference 体系
```javascript
// 之前：绕过协议，直接路径映射
registry['role:java'] = '/path/to/file'

// 现在：保持协议一致性
registry['role:java'] = '@package://resource/domain/java/java.role.md'
resolver.resolve('@package://...') // 统一解析
```

### 2. 解耦发现与注册
```javascript
// 之前：发现服务直接操作注册表
discovery.scan() // 内部调用 registry.register()

// 现在：发现服务只返回结果
const resources = discovery.discoverResources()
resources.forEach(r => registry.register(r.id, r.reference))
```

### 3. 统一协议解析
```javascript
// 之前：每处都自己解析
if (path.startsWith('@package://')) {
  const pkg = new PackageProtocol()
  return pkg.resolve(path)
}

// 现在：统一入口
const filePath = await resolver.resolve(reference) // 所有协议
```

### 4. 完全兼容现有格式
```javascript
// resource.registry.json 继续工作
"java-backend-developer": "@package://resource/domain/java/java.role.md"

// 代码继续工作
await resourceManager.loadResource('java-backend-developer')
```

## 奥卡姆剃刀原则体现

**移除的复杂性**：
- ❌ 多级缓存机制
- ❌ 复杂的性能监控
- ❌ 过度的抽象层
- ❌ 文件监视器
- ❌ 复杂的元数据管理
- ❌ 多个重叠的注册表

**保留的核心功能**：
- ✅ 统一的 @reference 体系
- ✅ 发现与注册解耦
- ✅ 协议解析统一化
- ✅ 100% 向后兼容

**简化后的架构**：
```
3个核心类，4个核心方法，解决核心问题
ResourceRegistry.resolve() → ProtocolResolver.resolve() → fs.readFileSync()
```

## 迁移计划

### 阶段1：核心重构 (1周)

**严格遵循：发现 → 注册 → 解析 → 读取，无缓存**

**1.1 统一协议解析器**
```bash
# 创建统一协议解析器
src/lib/core/resource/ProtocolResolver.js

# 移除分散的协议解析逻辑
# 统一所有 @reference 解析到此处
```

**1.2 简化资源注册表**
```bash
# 重构 ResourceRegistry 为纯索引
src/lib/core/resource/ResourceRegistry.js

# 移除：缓存、元数据管理、复杂逻辑
# 保留：id → @reference 映射
# 兼容：现有 resource.registry.json 格式
```

**1.3 解耦资源发现**
```bash
# 创建独立的资源发现服务
src/lib/core/resource/ResourceDiscovery.js

# 移除：与注册表的直接耦合
# 保留：纯粹的发现功能，返回结果
# 实现：生成标准化 @reference
```

**1.4 重构资源管理器**
```bash
# 简化 ResourceManager 为协调器
src/lib/core/resource/ResourceManager.js

# 移除：复杂的初始化逻辑、性能监控
# 保留：协调三个核心组件
# 实现：发现 → 注册 → 解析 → 读取
```

### 阶段2：集成测试 (2-3天)

**2.1 兼容性验证**
```bash
# 验证现有代码继续工作
src/tests/compatibility/existing-api.test.js

# 验证 resource.registry.json 加载正确
src/tests/integration/registry-loading.test.js
```

**2.2 功能测试**
```bash
# 测试资源发现功能
src/tests/integration/resource-discovery.test.js

# 测试协议解析功能
src/tests/integration/protocol-resolution.test.js
```

### 阶段3：部署验证 (1-2天)

**3.1 向后兼容验证**
```bash
# 确保现有 ActionCommand 继续工作
# 确保角色激活流程正常
# 确保跨平台兼容性
```

**3.2 文档更新**
```bash
# 更新架构文档
docs/architecture/resource-management.md

# 更新开发者指南
docs/development/adding-resources.md
```

## 实施原则

**严格的简化原则**：
- ❌ 不引入任何缓存机制
- ❌ 不添加性能监控
- ❌ 不实现文件监视
- ❌ 不添加复杂的元数据管理

**专注核心问题**：
- ✅ 统一 @reference 体系
- ✅ 解耦发现与注册
- ✅ 统一协议解析
- ✅ 保持向后兼容

## 风险评估

### 技术风险

**1. 向后兼容性**
- **风险**：现有代码依赖旧API
- **缓解**：严格保持 API 兼容性，现有调用方式继续有效

**2. 功能回归**  
- **风险**：重构可能影响现有功能
- **缓解**：充分测试，确保功能对等

### 业务风险

**1. 开发时间**
- **风险**：重构时间超出预期  
- **缓解**：专注核心问题，避免过度设计

**2. 稳定性影响**
- **风险**：重构影响现有功能
- **缓解**：分阶段实施，充分验证

## 成功指标

### 功能指标
- ✅ 现有代码 100% 兼容
- ✅ resource.registry.json 继续有效
- ✅ 角色激活功能正常
- ✅ 跨平台兼容性保持

### 架构指标  
- ✅ 统一 @reference 体系
- ✅ 发现与注册解耦
- ✅ 协议解析统一化
- ✅ 代码复杂度降低

## 总结

本架构改进方案严格遵循**奥卡姆剃刀原则**，专注解决 Issue #31 暴露的核心架构问题：

**核心改进**：
1. **统一 @reference 体系**：注册表存储 @reference 而非直接路径
2. **解耦发现与注册**：独立的发现服务，纯粹返回结果
3. **统一协议解析**：单一解析入口，移除分散逻辑
4. **完全向后兼容**：现有代码和配置无需修改

**实施原则**：
- 发现 → 注册 → 解析 → 读取，每步都不缓存
- 3个核心类，4个核心方法
- 移除所有不必要的复杂性

这个方案解决了当前的架构问题，为未来扩展奠定了简洁、清晰的基础。