PromptX/docs/reference-protocol-layers.md

DPML三层协议体系设计文档

📋 概述

DPML (Deepractice Prompt Markup Language) 采用三层协议架构，从底层到上层逐步抽象，为不同使用场景提供合适的语义级别。

🏗️ 协议分层架构

┌─────────────────────────────────────┐
│     上层协议 (Application Layer)      │  
│     @prompt:// @memory://            │  ← 应用语义协议
├─────────────────────────────────────┤
│      中层协议 (Semantic Layer)       │
│   @user:// @project:// @package://   │  ← 语义路径定位协议  
├─────────────────────────────────────┤
│     底层协议 (Transport Layer)       │
│   @file:// @http:// @https://        │  ← 通用传输协议
└─────────────────────────────────────┘

📦 底层协议 (Transport Layer)

🎯 设计目标

• 提供最基础的资源传输能力
• 兼容标准协议规范
• 支持各种数据源接入

📋 协议列表

1. @file:// - 文件系统协议

# 绝对路径
@file:///Users/sean/Documents/notes.md

# 相对路径（相对当前工作目录）
@file://./src/main.js
@file://docs/readme.md

# 用户目录路径
@file://~/Documents/project/file.md

# 通配符支持
@file://src/**/*.js
@file://docs/*.md

路径解析规则：

• 绝对路径：直接使用
• 相对路径：相对于 process.cwd()
• ~ 路径：相对于用户家目录
• 通配符：使用 glob 模式展开

2. @http:// / @https:// - 网络协议

# 标准HTTP请求
@http://example.com/api/resource.json

# HTTPS安全请求  
@https://api.github.com/repos/owner/repo/contents/file.md

# 带查询参数
@https://api.example.com/data?format=json&limit=100

特性支持：

• 标准HTTP/HTTPS请求
• 自动处理重定向
• 支持常见认证方式
• 缓存机制集成

🎯 中层协议 (Semantic Layer)

🎯 设计目标

• 提供语义化的路径定位
• 屏蔽不同环境的路径差异
• 支持智能路径解析

📋 协议列表

1. @user:// - 用户目录协议 ✅

# 用户文档目录
@user://documents/my-project/notes.md

# 用户桌面  
@user://desktop/todo.txt

# 用户下载目录
@user://downloads/data.csv

# 用户配置目录
@user://home/.config/app/settings.json

路径映射：

• @user://documents/ → 用户文档目录（跨平台）
• @user://desktop/ → 用户桌面目录（跨平台）
• @user://downloads/ → 用户下载目录（跨平台）
• @user://home/ → 用户家目录

实现特性：

• ✅ 跨平台支持：Windows、macOS、Linux
• ✅ 智能检测：使用 platform-folders 库或回退方案
• ✅ 安全验证：路径安全检查，防止遍历攻击
• ✅ 缓存机制：提高重复访问性能

2. @project:// - 项目根目录协议 ✅

# 项目配置文件
@project://package.json
@project://.gitignore

# 项目源码
@project://src/main.js
@project://lib/utils.js

# 项目文档
@project://docs/readme.md
@project://CHANGELOG.md

# 项目资源
@project://assets/images/logo.png

项目根目录检测规则：

1. 向上查找 .promptx 目录（优先级最高）
2. 查找 package.json 文件
3. 查找 .git 目录
4. 默认使用当前工作目录

实现特性：

• ✅ 智能检测：自实现向上查找算法
• ✅ 多标识符支持：.promptx、package.json、.git
• ✅ 安全边界：防止越过文件系统根目录
• ✅ 直接路径访问：支持包内任意路径

3. @package:// - NPM包目录协议 ✅

# 包根目录
@package://package.json
@package://README.md

# 包源代码
@package://src/index.js
@package://lib/commands/hello.js

# 包提示词资源
@package://resource/core/execution/think.md
@package://resource/domain/scrum/role/product-owner.md

# 包配置和模板
@package://jest.config.js
@package://templates/basic/template.md

# 任意包内路径
@package://docs/api/README.md
@package://assets/images/logo.png
@package://examples/demo.js

包安装模式智能检测：

• development - 开发模式（源码开发）
• local - 本地安装（npm install）
• global - 全局安装（npm install -g）
• npx - NPX执行模式
• monorepo - Monorepo工作空间
• link - NPM链接模式（npm link）

实现特性：

• ✅ 多安装模式支持：覆盖所有NPM使用场景
• ✅ 环境变量检测：npm_execpath、npm_config_cache等
• ✅ 符号链接处理：正确解析npm link场景
• ✅ Monorepo支持：检测workspaces配置
• ✅ 路径安全：防止目录遍历攻击
• ✅ 直接路径访问：无需预定义目录，支持包内任意路径
• ✅ 多级缓存：安装模式缓存 + 路径解析缓存

核心价值：

• 智能包根检测：自动检测不同安装环境下的包根目录
• 统一路径接口：无论开发、测试、生产环境，使用相同路径语法
• 安全路径访问：确保所有访问都在包根目录范围内

🚀 上层协议 (Application Layer)

🎯 设计目标

• 提供应用级语义抽象
• 隐藏底层实现细节
• 支持业务逻辑映射

📋 协议列表

1. @prompt:// - 提示词资源协议

# 核心协议文档
@prompt://protocols
# → @package://resource/protocol/**/*.md

# 核心提示词模块
@prompt://core
# → @package://resource/core/**/*.md

# 领域提示词
@prompt://domain/scrum
# → @package://resource/domain/scrum/**/*.md

# 特定角色提示词
@prompt://domain/scrum/role/product-owner
# → @package://resource/domain/scrum/role/product-owner.role.md

注册表映射：

• protocols → @package://resource/protocol/**/*.md
• core → @package://resource/core/**/*.md
• domain → @package://resource/domain/**/*.md
• bootstrap → @package://bootstrap.md

2. @memory:// - 记忆系统协议

# 声明式记忆
@memory://declarative
# → @project://.memory/declarative.md

# 情景记忆
@memory://episodic
# → @project://.memory/episodic/**/*.md

# 语义记忆
@memory://semantic
# → @project://.memory/semantic.json

# 程序记忆
@memory://procedural
# → @project://.memory/procedural/**/*.md

记忆类型映射：

• declarative → .memory/declarative.md
• episodic → .memory/episodic/
• semantic → .memory/semantic.json
• procedural → .memory/procedural/

🔧 实现架构

📦 协议解析流程

// 1. 协议分层解析
@prompt://core
    ↓ 上层协议解析
@package://resource/core/**/*.md  
    ↓ 中层协议解析
@file://[NPM包路径]/resource/core/**/*.md
    ↓ 底层协议执行
读取文件系统资源

🎯 注册表设计

class LayeredProtocolRegistry {
  constructor() {
    this.transportLayer = new Map();  // 底层协议
    this.semanticLayer = new Map();   // 中层协议  
    this.applicationLayer = new Map(); // 上层协议
  }
  
  resolve(protocol, path) {
    // 递归解析直到底层协议
    if (this.applicationLayer.has(protocol)) {
      const mapping = this.applicationLayer.get(protocol);
      return this.resolve(mapping.protocol, mapping.path + path);
    }
    
    if (this.semanticLayer.has(protocol)) {
      const mapping = this.semanticLayer.get(protocol);
      return this.resolve(mapping.protocol, mapping.path + path);
    }
    
    // 底层协议直接执行
    return this.transportLayer.get(protocol).resolve(path);
  }
}

🔍 路径检测机制

class PathDetector {
  // 检测NPM包目录
  static detectPackageRoot() {
    // NPM包模式检测
    try {
      const packagePath = require.resolve('promptx/package.json');
      return path.dirname(packagePath);
    } catch {}
    
    // 开发模式检测
    let dir = __dirname;
    while (dir !== path.dirname(dir)) {
      const packageJson = path.join(dir, 'package.json');
      if (fs.existsSync(packageJson)) {
        const pkg = require(packageJson);
        if (pkg.name === 'promptx') return dir;
      }
      dir = path.dirname(dir);
    }
    
    throw new Error('Package not found');
  }
  
  // 检测项目根目录
  static detectProjectRoot() {
    const indicators = ['.promptx', 'package.json', '.git'];
    let dir = process.cwd();
    
    while (dir !== path.dirname(dir)) {
      if (indicators.some(indicator => 
        fs.existsSync(path.join(dir, indicator))
      )) {
        return dir;
      }
      dir = path.dirname(dir);
    }
    
    return process.cwd(); // 默认当前目录
  }
}

📊 协议使用示例

🎯 典型使用场景

# AI助手启动：加载角色提示词
promptx learn @prompt://domain/scrum/role/product-owner

# 等价于底层路径：
promptx learn @file://[NPM包]/resource/domain/scrum/role/product-owner.role.md

# 记忆保存：保存到项目记忆
promptx remember "重要决策" @memory://declarative

# 等价于底层路径：  
promptx remember "重要决策" @file://[项目根]/.memory/declarative.md

🔄 协议转换示例

# 上层 → 中层 → 底层
@prompt://core
  ↓
@package://resource/core/**/*.md
  ↓  
@file:///usr/local/lib/node_modules/promptx/resource/core/**/*.md

🎯 设计优势

✅ 分层优势

1. 底层协议：标准化、可复用、易测试
2. 中层协议：语义化、环境无关、智能解析
3. 上层协议：业务导向、用户友好、功能聚焦

🔧 扩展性

• 向下兼容：上层协议变更不影响底层
• 灵活映射：可动态调整协议映射关系
• 插件化：支持自定义协议扩展

🎯 用户体验

• 简洁语法：@prompt://core vs @file://./node_modules/promptx/resource/core/**/*.md
• 语义清晰：协议名称直接表达意图
• 智能解析：自动处理环境差异

🚀 实施计划

Phase 1: 底层协议完善 ✅

• file:// 协议优化
• http/https:// 协议实现
• 通配符支持增强
• 查询参数系统
• 缓存机制集成

Phase 2: 中层协议实现 ✅

• user:// 协议实现 (1.3.1.1)
  • 跨平台用户目录检测
  • platform-folders集成
  • 安全路径验证
  • 完整测试覆盖
• project:// 协议实现 (1.3.1.2)
  • .promptx目录检测
  • 向上查找算法
  • 多指示符支持
  • 边界安全检查
• package:// 协议实现 (1.3.1.3)
  • 多安装模式检测
  • NPM环境智能识别
  • Monorepo支持
  • 符号链接处理
  • 直接路径访问（无预定义目录限制）

Phase 3: 上层协议优化

• prompt:// 协议重构
• memory:// 协议增强

Phase 4: 集成测试

• 中层协议单元测试
• 分层协议集成测试
• 性能基准测试
• 用户体验测试

📈 当前实施状态

✅ 已完成功能

• 底层协议系统：完整实现，支持file、http、https
• 中层协议核心：三个协议全部实现并通过测试
  • UserProtocol: 22/22 测试通过
  • ProjectProtocol: 30/30 测试通过
  • PackageProtocol: 41/41 测试通过（无目录映射限制）
• ResourceProtocol基类：统一接口抽象
• 查询参数系统：支持缓存键生成
• 安全机制：路径遍历防护
• 直接路径访问：package协议支持任意包内路径

🔄 进行中

• 上层协议优化
• 协议注册表重构
• 性能优化调整

📋 待实施

• memory:// 协议增强
• 协议映射配置化
• 插件系统支持

---

本文档将随着协议体系的演进持续更新

最后更新： 简化了@package://协议，去掉预定义目录映射，支持直接访问包内任意路径，更符合file协议的使用习惯。